Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/roboflow/rf-detr/llms.txt

Use this file to discover all available pages before exploring further.

RF-DETR supports custom data augmentations via Albumentations, with automatic bounding box and mask handling for geometric transforms. Albumentations 1.4.24+ and 2.x are supported.

​
Quick start

Pass aug_config to your training call. The simplest approach is to use one of the built-in presets: 
from rfdetr import RFDETRSmall
from rfdetr.datasets.aug_config import AUG_CONSERVATIVE, AUG_AGGRESSIVE, AUG_AERIAL, AUG_INDUSTRIAL

model = RFDETRSmall()
model.train(dataset_dir="path/to/dataset", epochs=100, aug_config=AUG_CONSERVATIVE)
Or pass a custom dict directly — keys are Albumentations transform names: 
model.train(
    dataset_dir="path/to/dataset",
    epochs=100,
    aug_config={
        "HorizontalFlip": {"p": 0.5},
        "Rotate": {"limit": 15, "p": 0.3},
        "GaussianBlur": {"p": 0.2},
    },
)
To disable all augmentations, pass an empty dict: 
model.train(dataset_dir="path/to/dataset", aug_config={})
Omitting aug_config uses the default (horizontal flip at 50%).

​
Built-in presets

PresetBest for
AUG_CONSERVATIVESmall datasets (under 500 images)
AUG_AGGRESSIVELarge datasets (2000+ images)
AUG_AERIALSatellite / overhead imagery
AUG_INDUSTRIALManufacturing / inspection data
All presets are plain dicts — inspect or extend them before passing: 
from rfdetr.datasets.aug_config import AUG_AGGRESSIVE

my_config = {**AUG_AGGRESSIVE, "VerticalFlip": {"p": 0.1}}
model.train(dataset_dir="path/to/dataset", aug_config=my_config)

​
Recommendations by dataset size

Dataset sizeRecommended preset
Under 500 imagesAUG_CONSERVATIVE — flip + mild brightness/contrast
500–2000 imagesDefault or AUG_CONSERVATIVE with a few extra transforms added
2000+ imagesAUG_AGGRESSIVE — rotations, affine, color jitter

​
Nested transforms

RF-DETR supports OneOf, SomeOf, and Sequential container transforms from Albumentations. The most common pattern is OneOf, which randomly picks one transform from a group: 
aug_config = {
    "HorizontalFlip": {"p": 0.5},
    "OneOf": {
        "transforms": [
            {"Rotate": {"limit": 45, "p": 1.0}},
            {"Affine": {"scale": (0.8, 1.2), "p": 1.0}},
        ],
    },
    "GaussianBlur": {"p": 0.2},
}
Each child’s p controls its relative selection weight. The container itself always fires. If you need the same transform twice, or want explicit ordering, pass a list instead of a dict: 
aug_config = [
    {"HorizontalFlip": {"p": 0.5}},
    {"Rotate": {"limit": 45, "p": 0.3}},
    {"Rotate": {"limit": 5, "p": 0.5}},  # second Rotate — only possible with list format
]
Bounding boxes are updated automatically when a container holds any geometric transform — no extra configuration needed.

​
Geometric vs. pixel-level transforms

RF-DETR automatically handles bounding boxes for geometric transforms (flips, rotations, crops, affine, perspective). Pixel-level transforms (blur, noise, color) preserve coordinates unchanged. You don’t need to handle this distinction — it’s automatic based on the transform name.

​
Best practices

Begin with simple augmentations (horizontal flip, small brightness changes) and gradually add more as needed. With strong augmentations it’s normal for training mAP to be lower than validation mAP — validation uses original images while training uses augmented (harder) ones.
Be careful with aggressive rotations and crops on datasets where object orientation matters (e.g., text detection, oriented objects).
  • CPU-bound: Augmentations run on CPU during data loading — more transforms means slower loading.
  • Use num_workers: Parallelize augmentation across DataLoader workers.
  • Monitor training mAP vs. validation mAP: A gap is expected with strong augmentations and is not a bug.

​
Advanced: custom transforms

Any Albumentations transform works by name. If your custom transform is geometric, register it in rfdetr/datasets/transforms.py so bounding boxes are updated automatically: 
GEOMETRIC_TRANSFORMS = {
    ...
    "YourCustomTransform",
}
Then use it like any other transform: 
model.train(
    dataset_dir="path/to/dataset",
    aug_config={
        "HorizontalFlip": {"p": 0.5},
        "YourCustomTransform": {"param": 1, "p": 0.3},
    },
)

​
Troubleshooting

Training is slow — reduce the number of transforms or increase num_workers. Boxes disappear after augmentation — aggressive rotations or crops can push boxes outside the image boundary. Reduce rotation angles or avoid large crops. Model not improving — augmentations may be too aggressive. Start with AUG_CONSERVATIVE and add transforms gradually. Try removing geometric transforms first to isolate the cause. Validation mAP is much higher than training mAP — this is expected with strong augmentations and is not a bug. Upgrading Albumentations to 2.x with existing RandomSizedCrop configs? RF-DETR automatically adapts height/width kwargs to the size=(height, width) format required by Albumentations 2.x. No config changes needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us