> This is the documentation for LibreYOLO 1.6.0. Current version: https://www.libreyolo.com/docs/models/deformable-detr

# Deformable DETR
Deformable DETR replaces DETR's dense cross-attention with sparse, multi-scale sampling around each reference point, which is what made transformer detectors practical to train. LibreYOLO ships five sizes for detection, inference only.
Tasks: Detection. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

Deformable DETR needs no optional extra. Everything it imports is in the base
install, using a pure-PyTorch multi-scale deformable attention core.

```bash
pip install libreyolo
```

Installing `libreyolo[hub-kernels]` is optional. Once the `kernels` package is
present, LibreYOLO fetches a compiled multi-scale deformable attention kernel
from the Hugging Face Hub at runtime and uses it in place of the pure-PyTorch
core; `LIBREYOLO_HUB_KERNELS=0` turns it back off.

## Predict

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

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreDeformableDETRr50.pt")
result = model(SAMPLE_IMAGE, save=True)

for box in result.boxes:
    print(box.cls, box.conf, box.xyxy)
```

**CLI**

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

The returned `Results` object is the one every family returns, so swapping in a
different detector is a one line change. `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](/docs/v1.6.0/predict) for sources, streaming and result handling.

Deformable DETR is inference-only in LibreYOLO. Upstream trains with Hungarian
matching and a focal classification loss; that recipe is not implemented here,
so `train()` raises `NotImplementedError`.

## Variants

Five checkpoints cover the released configurations, all at the same input
resolution. `r50ss` restricts attention to a single feature scale; `r50ssdc5`
adds a dilated C5 backbone stage on top of that. `r50` is the default
multi-scale configuration, sampling across four feature-map levels.
`r50refine` adds iterative bounding box refinement across decoder layers, and
`r50twostage` generates its initial region proposals from the encoder output
instead of learned queries.

## Validate

`val()` returns a dictionary of `metrics/` keys covering precision, recall,
mAP 50 and mAP 50-95, measured against any dataset in the format you trained on.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreDeformableDETRr50.pt")

# val() returns a plain dict, not an object
metrics = model.val(data="my-dataset.yaml")

print(metrics["metrics/mAP50-95"])
print(metrics["metrics/mAP50"])
print(metrics["metrics/precision"], metrics["metrics/recall"])
```

**CLI**

```bash
libreyolo val model=LibreDeformableDETRr50.pt data=my-dataset.yaml
```

## Export

| Task | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | ncnn | TFLite | CoreML | Core AI |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Detection | yes | yes | yes | yes | yes |  |  |  |  |  |  |  |

A "yes" means the export is supported. An empty cell means the exporter refuses that combination.

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`. [Export](/docs/v1.6.0/export) lists the arguments every format accepts.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreDeformableDETRr50.pt")
model.export(format="onnx", imgsz=800)
model.export(format="tensorrt", imgsz=800, half=True)
```

**CLI**

```bash
libreyolo export model=LibreDeformableDETRr50.pt format=onnx imgsz=800
libreyolo export model=LibreDeformableDETRr50.pt format=tensorrt imgsz=800 half=True
```

**Use the exported file**

```python
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("LibreDeformableDETRr50.onnx")
result = model(SAMPLE_IMAGE)

print(result.boxes.xyxy)
```

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreDeformableDETRr50ss.pt` | 800 | Detection | apache-2.0 |
| `LibreDeformableDETRr50ssdc5.pt` | 800 | Detection | apache-2.0 |
| `LibreDeformableDETRr50.pt` | 800 | Detection | apache-2.0 |
| `LibreDeformableDETRr50twostage.pt` | 800 | Detection | apache-2.0 |
| `LibreDeformableDETRr50refine.pt` | 800 | Detection | apache-2.0 |

## Licensing

Check the license on the Hugging Face repository of the specific weights you download. That repository is authoritative and licenses are not always uniform across a family. This is a description of the licenses involved, not legal advice.

- Original work: Deformable DETR, SenseTime
- Upstream license: Apache-2.0
- Upstream source: https://github.com/fundamentalvision/Deformable-DETR
- LibreYOLO code: Apache-2.0
- Weights: Apache-2.0, republished at https://huggingface.co/LibreYOLO
- Interpretation: Apache-2.0 is a permissive license, so these weights can be used in commercial and closed-source products. It asks you to keep its license text and attribution notices with any copy of the weights you redistribute, and it grants a patent license. It places no obligation on your own application code, and weights you train yourself on your own data are yours. The five checkpoints are converted from SenseTime's own Hugging Face mirrors, each of which declares apache-2.0 in its model card; that declaration, not the original repository's Google Drive release links, is the redistribution basis.

## Citation

```bibtex
@article{zhu2020deformable,
  title={Deformable DETR: Deformable Transformers for End-to-End Object Detection},
  author={Zhu, Xizhou and Su, Weijie and Lu, Lewei and Li, Bin and Wang, Xiaogang and Dai, Jifeng},
  journal={arXiv preprint arXiv:2010.04159},
  year={2020}
}
```

Copied from https://github.com/fundamentalvision/Deformable-DETR#citing-deformable-detr