RF-DETR

1.6.4 · active · verified Fri Apr 17

RF-DETR is a PyTorch-based library for object detection and instance segmentation, implementing the DETR architecture with enhancements. It provides tools for training, inference, and deployment, integrating with PyTorch Lightning for composable training workflows. The library is actively maintained, with version 1.6.4 released recently, and receives frequent updates.

Common errors

```
ImportError: rfdetr[train] is not installed. Please install with 'pip install "rfdetr[train]"'
```
cause Attempting to use training-specific modules or functions without installing the optional training dependencies.

fix Install `rfdetr` with its training dependencies: `pip install "rfdetr[train]"`
```
KeyError: 'class_name'
```
cause Attempting to access `detections.data['class_name']` using an `rfdetr` version older than 1.6.4, where this key was not present.

fix Upgrade `rfdetr` to `v1.6.4` or later, or use `detections.data.get('class_name')` and handle `None` for backward compatibility.
```
ValueError: Input shape dimensions must be divisible by 14. Got (500, 500)
```
cause The `shape` argument passed to `RFDETR.predict()` had dimensions (height, width) that were not perfectly divisible by 14.

fix Provide a `shape` where both height and width are positive integers divisible by 14, e.g., `model.predict(..., shape=(480, 640))`.
```
TypeError: RFDETR.export() got an unexpected keyword argument 'simplify'
```
cause Using the deprecated `simplify` or `force` arguments in `RFDETR.export()`, which are no longer supported since v1.6.1.

fix Remove the `simplify` and `force` arguments from your `RFDETR.export()` method calls.

Warnings

deprecated Arguments `simplify` and `force` in `RFDETR.export()` are deprecated and no-ops, and will be removed in v1.8.
Fix: Remove `simplify` and `force` arguments from your `RFDETR.export()` calls.
gotcha Training features require the `rfdetr[train]` optional dependencies to be installed.
Fix: Install with `pip install "rfdetr[train]"` to enable training functionality and avoid `ImportError`s.
gotcha `RFDETR.predict(shape=...)` requires both `height` and `width` dimensions to be positive integers divisible by 14.
Fix: Ensure the `shape` tuple (e.g., `(480, 640)`) contains dimensions that are multiples of 14 to prevent incorrect processing.
gotcha The `detections.data` dictionary returned by `predict()` now includes additional keys like `class_name` (v1.6.4) and `source_image`/`source_shape` (v1.6.3).
Fix: If your code assumes a fixed set of keys or iterates through `detections.data` without checking for key existence, adapt it to account for these new additions, e.g., `detections.data.get('class_name')`.

Install

pip install rfdetr Core library
pip install "rfdetr[train]" With training dependencies

Imports

RFDETRSmall
```
from rfdetr import RFDETRSmall
```
RFDETRBase
```
from rfdetr import RFDETRBase
```
RFDETRLarge
```
from rfdetr import RFDETRLarge
```
DetectionDataset
wrong:
```
from rfdetr.datasets import DetectionDataset
```
correct:
```
from rfdetr.data import DetectionDataset
```
Dataset classes were refactored into the `rfdetr.data` module.

Quickstart

This quickstart demonstrates how to load a pre-trained RF-DETR model, perform inference on an image URL, and inspect the returned detections object. It highlights recently added data fields like class names and source image/shape, which are useful for post-processing and visualization with libraries like `supervision`.

import supervision as sv
from rfdetr import RFDETRSmall

# Initialize model with pre-trained weights. Use "rfdetr-small" for the default.
# For a custom fine-tuned model: pretrain_weights="path/to/your/model.pth"
model = RFDETRSmall(pretrain_weights="rfdetr-small")

# Example image URL for prediction
image_url = "https://media.roboflow.com/dog.jpg"

# Perform inference with a confidence threshold
detections = model.predict(image_url, threshold=0.5)

print(f"Detected {len(detections)} objects.")

# Access new data points introduced in recent versions:
if "class_name" in detections.data:
    print(f"Class names: {detections.data['class_name']}")
if "source_image" in detections.data:
    print(f"Source image shape: {detections.data['source_shape']}")

# Visualize results (requires 'supervision' to be installed)
# image_bgr = detections.data.get("source_image")
# if image_bgr is not None:
#     box_annotator = sv.BoxAnnotator()
#     annotated_image = box_annotator.annotate(scene=image_bgr.copy(), detections=detections)
#     sv.plot_image(annotated_image, size=(8, 8))

view raw JSON →