Skip to content

pydfine

A batteries-included, config-first Python library for the D-FINE real-time object detector (Peterande/D-FINE, ICLR 2025 Spotlight), with an ultralytics-style developer experience.

Design goal: the entire model — backbone, encoder, decoder, losses, denoising, training, augmentation — is configured through typed Python parameters on one class (DFINEConfig). No YAML on the user path, no config-registry indirection, no torchrun incantations.

Install

pip install pydfine              # core (config + CLI, torch-free)
pip install pydfine[torch]       # + inference (model build + predict)
pip install pydfine[train]       # + training / COCO val
pip install pydfine[export]      # + ONNX export
pip install pydfine[track]       # + ByteTrack on predict_video

Quickstart

from dfine import DFINE

# Presets fill sensible defaults; every field is overridable inline.
model = DFINE(size="l", num_classes=80, device="cuda")

results = model.predict("street.jpg", conf=0.4)
results[0].save("out.jpg")

model.train(data="dataset/", epochs=72)  # fine-tune on a COCO dataset
metrics = model.val(data="dataset/")  # COCO metrics
model.export(format="onnx")  # deployable ONNX graph

Load released COCO weights in one line:

model = DFINE.from_pretrained("dfine-s")  # resolve + download + strict-load

Validate with analytics

Score the COCO metrics and render the diagnostic plots — confusion matrix, P/R/F1-vs- confidence curves, per-class AP, and a worst-predictions gallery:

metrics = model.val(data="coco/", plots=True, output_dir="runs/val")
print(metrics["AP"])  # primary mAP@[.50:.95]
# runs/val/{confusion_matrix,pr_curve,f1_curve,p_curve,r_curve}.png + worst/

See Validation & analytics for how to read each plot and pick a deployment confidence from the F1 curve.

CLI

dfine models                       # list presets + known checkpoints
dfine predict dfine-s img.jpg      # detect and save annotated output
dfine val dfine-l --data coco/     # COCO metrics
dfine train n --data coco/         # fine-tune
dfine export dfine-m               # ONNX
dfine convert yolo/ coco/          # YOLO dataset -> COCO layout

Learn more