D-FINE-seg

Real-Time Object Detection and Instance Segmentation

Quick Start • Usage • Export • Inference • Benchmarks • Video Tutorial • Colab

D-FINE-seg extends the D-FINE real-time transformer based object detector with instance segmentation. It adds a lightweight mask head, segmentation-aware training (box-cropped BCE and dice mask losses, auxiliary and denoising mask supervision), and mask-aware Hungarian matching. On the TACO and VisDrone datasets, D-FINE-seg improves F1-score over Ultralytics YOLO26 under a unified TensorRT FP16 end-to-end benchmarking protocol, while maintaining competitive latency.

The framework covers the full workflow — from data preparation and training (with DDP, EMA, AMP, mosaic) through export (ONNX, TensorRT, OpenVINO, CoreML, LiteRT) to optimized multi-backend inference for both object detection and instance segmentation tasks.

This is not a fork. The detection core is based on the original D-FINE paper; everything else — segmentation head, training pipeline, export, inference, augmentations — was reimplemented from scratch.

Paper: D-FINE-seg: Object Detection and Instance Segmentation Framework with Multi-Backend Deployment

• Instance segmentation via a lightweight mask head on top of D-FINE's HybridEncoder PAN outputs — fuses stride 8/16/32 features to 1/4 resolution, then dot-product between per-query mask embeddings (3-layer MLP) and shared mask features produces per-instance masks
• New losses: box-cropped BCE + Dice mask losses computed only inside GT boxes and normalized by ROI area
• Mask-aware denoising: contrastive denoising training extended with mask supervision for faster convergence (adds no inference cost)
• Mask-aware matching: Hungarian matcher augmented with Dice overlap cost and sigmoid focal mask cost alongside classification, L1, and GIoU costs
• 5 model sizes — Nano, Small, Medium, Large, Extra-Large — with HGNetv2 backbones
• Production-ready: export to ONNX / TensorRT / OpenVINO / CoreML / LiteRT and optimized inference backends

git clone https://github.com/ArgoHA/D-FINE-seg.git
cd D-FINE-seg
uv sync

This creates a .venv/ with all dependencies pinned by uv.lock. Activate it with source .venv/bin/activate, or run anything via uv run ... (the Makefile already does this).

Pretrained weights are auto-downloaded from Hugging Face into pretrained/ on first use, so no manual setup is needed. To download manually instead, grab dfine_<size>_<dataset>.pt (size ∈ {n, s, m, l, x}, dataset ∈ {coco, obj2coco}) and place it in pretrained/. Segmentation weights are also available in the Hugging Face model card.

Two annotation formats are supported: YOLO (default) and COCO JSON.

data/dataset/
├── images/    # all images: .jpg, .png, etc. (.npy for multi-channel — see below)
└── labels/    # all labels: one .txt per image (same filename stem)

Detection labels: class_id xc yc w h (normalized)

Segmentation labels: class_id x1 y1 x2 y2 ... xN yN (normalized polygon coordinates)

Input types & channel order: 3-channel .jpg/.png (BGR, read via cv2.imread), 3-channel .npy (RGB, read via np.load), or 4-channel .npy (RGB+extras, e.g. RGB+thermal).

Set train.in_channels: N (default 3) to train on stacks beyond plain RGB. Supported range is N=3 (RGB) or N=4 (RGB + one extra modality, e.g. thermal, depth, NIR). Higher channel counts are not supported — cv2 / Albumentations ops cap at 4.

Layout is the same; drop the stacks as .npy files (uint8 HWC arrays):

data/dataset/
├── images/    # one .npy per sample, shape (H, W, N), dtype uint8
└── labels/    # YOLO .txt (same as 3-channel case)

Loader rules (see src/dl/dataset.py):

• np.load is byte-faithful — channels come back exactly as you saved them.
• A file whose channel count doesn't match train.in_channels is skipped with a loguru.warning line (path + reason). Mosaic re-samples another index automatically.
• Pretrained 3-channel backbone weights are reused: the stem conv is inflated to N input channels by tiling/averaging the RGB filters (inflate_stem_weight in src/d_fine/utils.py), so fine-tuning from COCO still works.
• Stem freeze (freeze_at in src/d_fine/configs.py) is auto-bypassed when in_channels > 3 so the inflated extra-channel weights can train; the size-configured freeze_at still applies for plain 3-channel RGB.

Channel-order convention: write the RGB triplet in the first three planes (channels 0..2) so they line up with the pretrained RGB stem; extra modalities go in channels 3..N-1. Example for RGB + thermal: stack as [R, G, B, T].

Example: src/etl/m3fd_to_yolo.py converts the M3FD RGB+thermal detection benchmark (PASCAL VOC XML + paired Vis//Ir/ PNGs) into this exact layout.

Place standard COCO JSON annotation files alongside your images folder. Splits are detected automatically by filename:

data/dataset/
├── images/       # all images
├── train.json    # COCO-format annotations for train split
├── val.json      # COCO-format annotations for val split
└── test.json     # (optional) COCO-format annotations for test split

Enable COCO mode by setting coco_dataset: True in your config (see below). No CSV split generation step is needed — the splits are read directly from the JSON files.

Edit config.yaml — key settings:

task: detect  # "detect" or "segment"
exp_name: my_exp  # experiment name (used in output paths)
model_name: s  # n / s / m / l / x

train:
  root: /path/to/project  # project root, will be used for outputs
  data_path: /path/to/dataset  # folder with images/ and labels/ (YOLO) or *.json files (COCO)
  coco_dataset: False  # set True to use COCO JSON annotations (train.json / val.json / test.json)
  label_to_name:
    0: class_a
    1: class_b
  epochs: 75
  batch_size: 8
  img_size: [640, 640]  # (h, w)

make split           # create train/val CSV splits (test split if configured)
make train           # train the model
make export          # export to ONNX, TensorRT, OpenVINO, CoreML, LiteRT
make bench           # benchmark all exported models on the val set

make infer           # run on test folder, save visualizations + YOLO txt predictions
make check_errors    # compare predictions against GT, save only mismatches (FP/FN)
make test_batching   # find optimal batch size for your GPU

make ov_int8         # INT8 accuracy-aware quantization for OpenVINO (can take hours)

Notes:

• YOLO format: make train requires train.csv and val.csv in train.data_path (generated by make split).
• COCO format: set coco_dataset: True — train.json and val.json are loaded directly; make split is not needed.
• make infer runs Torch inference on train.path_to_test_data and writes to train.infer_path.

Or run in sequence:

make                 # train -> export -> bench (does not run split)

Or run overwriting configs from CLI

uv run python -m src.dl.train exp_name=my_exp

Enable DDP (multi-GPU) by setting train.ddp.enabled: True and train.ddp.n_gpus: N in config. Then just run make train — it auto-launches with torchrun.

Tip: FP16 is the best latency/accuracy trade-off for GPU (TensorRT) and CPU (OpenVINO). For Apple Silicon (CoreML), FP32 is faster.

After export, a parity self-check (export.parity, on by default) runs each backend on a shared input and writes one cosine per backend — over the sorted top-K detection scores vs torch — to parity.csv next to the weights.

Six inference backends in src/infer/:

Also provided:

• Bytetrack - simple implementation of object tracker
• SAM3 - text-promptable zero-shot segmentation for auto-labeling

A simplified ByteTrack (Zhang et al., ECCV 2022) is included for persistent object tracking across video frames — uses constant-velocity motion prediction with EMA-smoothed velocity instead of a Kalman filter, blends IoU with centroid distance in the match cost, and does per-class matching by default.

uv run python -m demo.demo

A web UI for uploading images and running inference interactively.

VisDrone dataset - a large-scale drone-captured benchmark with 10 categories across diverse urban and rural scenes (~6500 train / ~550 val / ~1600 test-dev images). YOLO26 trained for 100 epochs, D-FINE for 75. YOLO26 confidence threshold - 0.25, D-FINE - 0.5. F1-score measured with IoU threshold 0.5. Preserved original dataset split (VisDrone2019-DET-train, VisDrone2019-DET-val, VisDrone2019-DET-test-dev). Metrics are reported on test-dev set. Latency measured end-to-end (preprocessing + forward pass + postprocessing) on RTX 5070 Ti with TensorRT FP16 at 640x640, batch size 1.

D-FINE outperforms YOLO26 in fine-tuning setting on VisDrone dataset in F1-score across every model size. D-FINE achieves ~7% higher mean relative F1-score with ~28% latency reduction. Notably, IoU is ~15% higher (mean relative improvement across all models).

TACO dataset (1500 images, 59 effective classes of waste in diverse environments, 86/14 train/val split by batch ID). The benchmarking environment is the same as for VisDrone.

D-FINE-seg outperforms YOLO26 in fine-tuning setting on TACO dataset in F1-score across every model size (N/S/M/L/X). In segmentation task - ~75% higher mean relative F1-score and ~16% latency reduction. In detection task - ~80% higher F1-score and ~28% latency reduction.

Note: although D-FINE does not require NMS, it still provides a small accuracy boost, so NMS is enabled by default in the current version. This is included in the reported latency.

Measured on TACO with D-FINE-seg S / D-FINE S at 640x640. Latency = preprocessing + inference + postprocessing.

Training

Benchmarking

WandB dashboard

Inference

If you use D-FINE-seg in your research, please cite:

@article{saakyan2026dfineseg,
  title={D-FINE-seg: Object Detection and Instance Segmentation Framework with multi-backend deployment},
  author={Saakyan Argo and Solntsev Dmitry},
  eprint={2602.23043},
  journal={arXiv preprint arXiv:2602.23043},
  year={2026}
}

And the original D-FINE paper:

@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}
}

This project is licensed under the Apache 2.0 License.

The detection core is based on the D-FINE paper and architecture. The mask head design follows the Mask DINO paradigm. Thank you to both teams for their excellent work.

Benchmarks in this project use the VisDrone and TACO datasets. We thank the authors for making these datasets publicly available.