<!-- examples/README-d-fine.md -->

# D-FINE scalar reference

Run `python3 examples/d-fine.py --smoke` from the repository root. Python 3.9 or newer is sufficient; no packages, network, checkpoint, dataset or GPU are needed. The deterministic JSON contains calculated quantities, not model outputs.

The five extractable regions are `support`, `refinement`, `decode`, `localization`, and `distillation`. Helpers implement non-uniform support, residual logits, expectation decoding, two-bin localization supervision and temperature-scaled teacher-to-student KL. Additional checks cover union voting and square-root balancing of group means. The reference omits neural layers, matching optimization, denoising, classification, distributed reductions and training. It does not reproduce COCO AP or latency.

## Provenance and conventions

Paper: Peng et al., [D-FINE, arXiv:2410.13842v1](https://arxiv.org/html/2410.13842v1), first posted 2024; ICLR 2025 Spotlight according to the official repository.

Official implementation inspected at commit `956d1709314c2c6a4df6f34de232054578a7449f`:

- `src/zoo/dfine/dfine_utils.py`: weighting_function, translate_gt, distance2bbox.
- `src/zoo/dfine/dfine_decoder.py`: TransformerDecoder.forward.
- `src/zoo/dfine/dfine_criterion.py`: loss_local and \_get_go_indices.

These are independently authored scalar teaching functions, not copies of the training implementation. All edge arrays use left/top/right/bottom; paper Eq. 2 uses top/bottom/left/right. The paper's support is normalized by box extent. Released code integrates support multiplied by `reg_scale` and divides by the same scale in decoding. For fixed positive parameters the correspondence is `a = abs(up)`, `c = 1 / abs(reg_scale)`. Targets beyond support saturate to endpoints, so decoded expectations cannot represent arbitrary offsets. Union vote ties use smallest target ID here; upstream does not promise that tie order. Distillation uses square-root weighted group means as in the code, which should not be confused with a literal unnormalized reading of Eq. 6.

No original paper artwork or recorded inference assets are included.
