README.md

---
pipeline_tag: object-detection
license: apache-2.0
base_model: ustc-community/dfine-medium-coco
library_name: kerasformers
tags:
- keras
- kerasformers
- d-fine
- dfine
- detr
- object-detection
- arxiv:2410.13842
- pytorch
- jax
- tf
---

## ***See [our collection](https://huggingface.co/collections/kerasformers/d-fine-6a69d56d4bee59c3f582ebf0) for all versions of D-FINE.***

# Run D-FINE with Keras 3: JAX, PyTorch, or TensorFlow

[![GitHub](https://img.shields.io/badge/GitHub-KerasFormers-black?logo=github)](https://github.com/IMvision12/KerasFormers) [![Docs](https://img.shields.io/badge/Docs-D--FINE-blue)](https://imvision12.github.io/KerasFormers/dfine/) [![Collection](https://img.shields.io/badge/HF-D--FINE%20collection-yellow)](https://huggingface.co/collections/kerasformers/d-fine-6a69d56d4bee59c3f582ebf0)

# kerasformers/dfine-medium

Paper: [D-FINE: Redefine Regression Task of DETRs as Fine-grained Distribution Refinement (arXiv:2410.13842)](https://arxiv.org/abs/2410.13842) · [HF Papers](https://huggingface.co/papers/2410.13842)

D-FINE is a real-time detector built on the RT-DETR recipe: an HGNetV2 backbone, a hybrid encoder, and a deformable decoder with 300 queries. It is NMS-free. Boxes are regressed via Fine-grained Distribution Refinement: each decoder layer predicts a distribution over discrete offset bins and accumulates refinements across layers.

For more details on the model, please go to the upstream [model card](https://huggingface.co/ustc-community/dfine-medium-coco).

Pure-**Keras 3** conversion of [`ustc-community/dfine-medium-coco`](https://huggingface.co/ustc-community/dfine-medium-coco) for [kerasformers](https://github.com/IMvision12/KerasFormers). One implementation runs unmodified on **TensorFlow / Torch / JAX**.

This is an **object detection** checkpoint (`DFineDetect`) on COCO (HGNetV2-Medium).

## ✨ Quick start

```python
import os
os.environ["KERAS_BACKEND"] = "torch"  # or "jax" / "tensorflow"

from PIL import Image
from kerasformers.models.dfine import DFineDetect, DFineImageProcessor

model = DFineDetect.from_weights("kerasformers/dfine-medium")
processor = DFineImageProcessor()

image = Image.open("your_image.jpg").convert("RGB")
inputs = processor(image)
output = model(inputs["pixel_values"], training=False)
results = processor.post_process_object_detection(
    output, threshold=0.5, target_sizes=[(image.height, image.width)]
)[0]
for score, name, box in zip(
    results["scores"], results["label_names"], results["boxes"]
):
    print(f"{name}: {float(score):.3f} {box}")
```

Load any D-FINE variant the same way with `from_weights("kerasformers/<variant>")`:

| Variant | Hub | Backbone |
|---|---|---|
| `dfine-nano` | [`kerasformers/dfine-nano`](https://huggingface.co/kerasformers/dfine-nano) | HGNetV2-Nano |
| `dfine-small` | [`kerasformers/dfine-small`](https://huggingface.co/kerasformers/dfine-small) | HGNetV2-Small |
| `dfine-medium` | [`kerasformers/dfine-medium`](https://huggingface.co/kerasformers/dfine-medium) | HGNetV2-Medium |
| `dfine-large` | [`kerasformers/dfine-large`](https://huggingface.co/kerasformers/dfine-large) | HGNetV2-Large |
| `dfine-xlarge` | [`kerasformers/dfine-xlarge`](https://huggingface.co/kerasformers/dfine-xlarge) | HGNetV2-XLarge |

## Tips

- Set `KERAS_BACKEND` **before** importing Keras / kerasformers.
- `DFineImageProcessor` keeps `do_normalize=False` by default (rescaled `[0, 1]` input, matching upstream).
- See [D-FINE docs](https://imvision12.github.io/KerasFormers/dfine/) and [Loading Weights](https://imvision12.github.io/KerasFormers/loading_weights/).
- Community / upstream safetensors still work via the `hf:` prefix, e.g. `DFineDetect.from_weights("hf:ustc-community/dfine-medium-coco")`.

## Special Thanks

A huge thank you to the D-FINE authors (USTC community) for creating and releasing these models.

License: Apache 2.0.