D-FINE

Install

D-FINE needs no optional extra. Everything it imports is in the base install.

pip install libreyolo

Adapter fine-tuning with lora=True is the exception, and needs the lora extra.

pip install "libreyolo[lora]"

Predict

Weights download from Hugging Face on first use and are cached locally.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreDFINEn.pt")result = model(SAMPLE_IMAGE, save=True) for box in result.boxes:    print(box.cls, box.conf, box.xyxy)

libreyolo predict model=LibreDFINEn.pt source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg save=True

from libreyolo import LibreYOLO, SAMPLE_IMAGE # The -seg suffix in the filename selects the mask head, so no task# argument is needed here.model = LibreYOLO("LibreDFINEn-seg.pt")result = model(SAMPLE_IMAGE, save=True) print(result.masks.data.shape)

The returned Results object is the one every family returns, so swapping in a different detector is a one line change. A -seg filename resolves to the segmentation task on its own, and result.masks then carries the instance masks alongside the boxes. conf and max_det filter the query selection; iou is accepted for API parity but has no effect, because the decoder is a set predictor with no NMS step. See prediction for sources, streaming and result handling.

Variants

Five sizes. They all run at the same input resolution, so the table separates them by parameter count and accuracy.

Segmentation reuses the detection backbone, encoder and decoder and adds a mask head, so a -seg checkpoint takes the same arguments as its detect sibling. LibreYOLO's RT-DETRv4 family is written as a subclass of the D-FINE wrapper: it inherits this decoder line and then pins its task list back to detection, because it carries no mask head.

Train

Training starts from a published checkpoint, for both tasks.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDFINEn.pt")model.train(data="my-dataset.yaml", epochs=50, imgsz=640, batch=8, lr0=2e-4)

libreyolo train model=LibreDFINEn.pt data=my-dataset.yaml \  epochs=50 imgsz=640 batch=8 lr0=2e-4

# Continues from published segmentation weights, mask head included.libreyolo train model=LibreDFINEn-seg.pt data=my-dataset.yaml \  task=segment epochs=50 imgsz=640

# Detect weights carry no mask head, so this is an explicit transfer:# the head starts untrained and is only useful once trained. Asking for# task=segment here is what authorizes the transfer.libreyolo train model=LibreDFINEn.pt data=my-dataset.yaml \  task=segment epochs=50 imgsz=640

from libreyolo import LibreYOLO model = LibreYOLO("LibreDFINEn.pt")model.train(data="my-dataset.yaml", epochs=50, lora=True)

libreyolo train model=LibreDFINEn.pt data=my-dataset.yaml \  epochs=50 device=0,1 batch=16

Left alone, the trainer runs 132 epochs at lr0=2e-4 with amp=True and amp_dtype="float16", a batch of 16 and early stopping after 50 epochs without improvement. libreyolo train starts from the same recipe for both tasks: AdamW with a flat cosine schedule, weight_decay=1e-4, 2 warmup epochs, a gradient-norm clip of 0.1, and no mosaic, MixUp, HSV or affine augmentation. Without name=, its runs go to runs/train/dfine_exp. Detect weights are a legal starting point for segmentation training, but only as an explicit transfer, since the mask head begins untrained and would otherwise return meaningless masks. Passing task=segment to the CLI is what authorizes it. The Python route is narrower: LibreDFINE has to be constructed directly with allow_detect_to_segment_transfer=True, because the LibreYOLO() factory takes no such argument, and direct construction does not download, so the weights file must already be on disk.

lora=True applies to detection. Segment training rejects it and points at freeze='backbone' instead, because the mask head has not been tested with adapters. On Apple silicon the trainer moves the whole run to CPU: the backward pass of the Integral's binned matmul hits a Metal compilation failure. Inference on MPS is unaffected.

See training for datasets, augmentation, multi-GPU and loggers.

Validate

val() returns a dictionary keyed by metric name, and prints per-class results when verbose is left on.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDFINEn.pt")metrics = model.val(data="my-dataset.yaml") print(metrics["metrics/mAP50-95"])print(metrics["metrics/mAP50"])

libreyolo val model=LibreDFINEn.pt data=my-dataset.yaml

from libreyolo import LibreYOLO model = LibreYOLO("LibreDFINEn-seg.pt")metrics = model.val(data="my-dataset.yaml") print(metrics["metrics/mAP50-95(M)"])   # masksprint(metrics["metrics/mAP50-95(B)"])   # boxes

Against a -seg checkpoint the plain metrics/mAP50-95 key holds the mask score, and the same run also reports boxes under (B) and masks under (M) so both are available from one pass.

Export

An exported artifact loads back through LibreYOLO() on its file suffix, so a .onnx or .engine file behaves like a checkpoint and returns the same Results. The OpenVINO, Paddle, MNN and Core AI paths export at a fixed canvas rather than dynamic shapes. Export lists the arguments every format accepts and the extras a few of them add.

from libreyolo import LibreYOLO model = LibreYOLO("LibreDFINEn.pt")model.export(format="onnx", imgsz=640)model.export(format="tensorrt", imgsz=640, half=True)

libreyolo export model=LibreDFINEn.pt format=onnx imgsz=640libreyolo export model=LibreDFINEn.pt format=tensorrt imgsz=640 half=True

from libreyolo import LibreYOLO, SAMPLE_IMAGE # The factory routes on the file suffix, so an exported artifact loads# like any checkpoint and returns the same Results object.model = LibreYOLO("LibreDFINEn.onnx")result = model(SAMPLE_IMAGE) print(result.boxes.xyxy)

ONNX inputs and outputs

Checkpoints

Every published weight file for this family.

Licensing

Citation

@misc{peng2024dfine,
      title={D-FINE: Redefine Regression Task in DETRs as Fine-grained Distribution Refinement},
      author={Yansong Peng and Hebei Li and Peixi Wu and Yueyi Zhang and Xiaoyan Sun and Feng Wu},
      year={2024},
      eprint={2410.13842},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
}