releasing 1.7.0

[Borda]

RF-DETR 1.7.0

This release adds TFLite export, GPU-side augmentation for segmentation, multi-channel input support (grayscale and multispectral), PyTorch Lightning checkpoint loading, and several developer-facing builder APIs that make custom model construction far easier. It also moves peft to an opt-in extra and removes the long-deprecated rfdetr.util / rfdetr.deploy import paths — see Breaking Changes below before upgrading.

🚀 Added

• TFLite export. New model.export(format="tflite") converts through ONNX using onnx2tf. FP32 and FP16 outputs are always produced; INT8 quantization is available with a calibration image directory. Requires pip install 'rfdetr[onnx]'. (feat(export): add TFLite export support with FP32/FP16/INT8 #920)

  model.export(
      format="tflite",
      quantization="int8",
      calibration_data="path/to/images/",
  )

• Kornia GPU augmentation now supports instance segmentation. Images, boxes, and per-instance masks are augmented in sync on the GPU via RFDETRDataModule.on_after_batch_transfer. Previously augmentation_backend="gpu"/"auto" was silently ignored for segmentation models. The mask buffer is [B, N_max, H, W] float32 — roughly 500 MB at B=8, N_max=50, H=W=560; use augmentation_backend="cpu" on cards with limited VRAM. (feat: Phase 2 Kornia GPU augmentation for segmentation masks #1003)

• Grayscale and multispectral imagery support. RF-DETR models now accept inputs with any number of channels, not just 3. The pretrained DINOv2 patch-embedding weights are automatically adapted to the specified channel count at construction time — no extra dependencies. (Grayscale and Multispectral Imagery Support #180)

• PyTorch Lightning .ckpt files accepted as pretrain_weights. Keys are auto-normalized from PTL format (state_dict with model.-prefixed keys, hyper_parameters → args) so that load_pretrain_weights, class-name extraction, and compatibility checks work without manual conversion. (Support PTL .ckpt files as pretrain_weights #951)

• rfdetr.from_checkpoint(path). New top-level convenience function that loads a checkpoint and infers the correct model subclass automatically — no need to know or pass the class. Equivalent to RFDETR.from_checkpoint(path). (Add from_checkpoint method that directly infers the model class #664)

• skip_best_epochs parameter for RFDETR.train() and TrainConfig. The first N epochs are excluded from best-checkpoint selection and early-stopping comparison, so strong pretrained weights or resumed checkpoints can't lock in a suboptimal early score. (feat: skip_best_epochs parameter for training #1000)

• augmentation_backend field on TrainConfig ("cpu" / "auto" / "gpu"): opt-in GPU-side augmentation via Kornia. CPU path is unchanged and remains the default. Install with pip install 'rfdetr[kornia]'. (feat: Phase 2 Kornia GPU augmentation for segmentation masks #1003)

• RF_HOME environment variable controls where pretrained model weights are cached (default: ~/.roboflow/models). Bare filenames passed as pretrain_weights (e.g. "rf-detr-base.pth") resolve relative to this directory; paths with a directory component are used as-is with parent directories created automatically. (Save weights to custom folder of user 's choice #130)

• training_config.json is now saved to the output directory after training completes. Captures the full TrainConfig, ModelConfig, effective training parameters, class names, and number of classes — useful for reproducibility and debugging predictions from older checkpoints. (Feature: save complete training configuration to disk after training #194)

• Native RLE annotation support in the COCO segmentation pipeline. convert_coco_poly_to_mask now decodes both compressed (string counts) and uncompressed (int-list counts) RLE formats alongside polygons. Malformed annotations now raise instead of being silently swallowed. (feat: add native RLE annotation support in COCO segmentation pipeline #897)

• ONNX export filenames include the model variant name (e.g. rfdetr-medium.onnx) instead of the generic inference_model.onnx. Exporting multiple variants to the same directory no longer overwrites previous exports. (feat: include variant name in ONNX export filename #910)

• Background images (no matching label file) are included in YOLO detection datasets as empty-detection samples instead of being silently dropped. Both detection and segmentation paths now use _LazyYoloDetectionDataset for consistent behaviour. (Add background image support for YOLO detection #915)

• RFDETR.predict(include_source_image=...) — opt-out flag (default True) to skip storing the source image in detections.metadata["source_image"]; set to False to reduce memory use when the image is not needed for annotation. (Fix inference optimization cleanup and download temp-file races #912)

• model_name is now stored in checkpoint files during training so that RFDETR.from_checkpoint() can resolve the correct model class directly from the checkpoint, without requiring the caller to pass a class hint. Backward-compatible: checkpoints without model_name continue to resolve via filename matching. (feat: store model_name in checkpoint for model identification #895)

• rfdetr_version is now stored in checkpoint files during training for provenance tracking and compatibility hints. (Add rfdetr_version to checkpoint payloads #918)

• dinov2_with_registers_windowed_small backbone is now available as a config option in ModelConfig.encoder. (Update config.py add dinov2 with registers #236)

Builder API surface (advanced users)

• build_model_from_config(model_config, train_config=None, defaults=MODEL_DEFAULTS) — config-native alternative to build_model(build_namespace(mc, tc)); accepts Pydantic config objects directly. (refactor: config-native build_{model|criterion}_from_config #845)
• build_criterion_from_config(model_config, train_config, defaults=MODEL_DEFAULTS) — config-native alternative to build_criterion_and_postprocessors(build_namespace(mc, tc)). (refactor: config-native build_{model|criterion}_from_config #845)
• ModelDefaults dataclass and MODEL_DEFAULTS singleton — exposes the 35 hardcoded architectural constants previously buried inside build_namespace(). Customise with dataclasses.replace(MODEL_DEFAULTS, ...). (refactor: config-native build_{model|criterion}_from_config #845)
• BuilderArgs — a @runtime_checkable typing.Protocol documenting the minimum attribute set consumed by build_model(), build_backbone(), build_transformer(), and build_criterion_and_postprocessors(). (refactor: BuilderArgs Protocol + ModelConfig/TrainConfig field deduplication #841)

⚠️ Breaking Changes

• peft is no longer installed by default. It has moved to the [lora] and [train] optional extras. If you use LoRA fine-tuning, install with pip install 'rfdetr[lora]'. Existing rfdetr[train] installs continue to include peft. (chore: packaging pins + move peft to [lora] extra, fix eager backbone import #838)

🗑️ Deprecated

• rfdetr.util.* and rfdetr.deploy.* import paths — both shim packages remain active in 1.7.0 and emit DeprecationWarning. Use rfdetr.utilities.* and rfdetr.export.* instead. Removal in v1.9. (chore: add __getattr__ hook for rfdetr.util/rfdetr.deploy removal #839)
• RFDETRBase — use RFDETRNano, RFDETRSmall, RFDETRMedium, or RFDETRLarge instead. Emits DeprecationWarning on instantiation; scheduled for removal in v2.0. (deprecate RFDETRBase and RFDETRSegPreview #900)
• RFDETRSegPreview — use RFDETRSegNano, RFDETRSegSmall, RFDETRSegMedium, or RFDETRSegLarge instead. Emits DeprecationWarning on instantiation; scheduled for removal in v2.0. (deprecate RFDETRBase and RFDETRSegPreview #900)
• build_namespace(model_config, train_config) — use build_model_from_config, build_criterion_from_config, or _namespace_from_configs directly. Removal in v1.9. (refactor: config-native build_{model|criterion}_from_config #845)
• load_pretrain_weights(nn_model, model_config, train_config) — the train_config positional argument is no longer used and emits DeprecationWarning. Removal in v1.9. (refactor: config-native build_{model|criterion}_from_config #845)
• TrainConfig.group_detr, TrainConfig.ia_bce_loss, TrainConfig.segmentation_head, TrainConfig.num_select, ModelConfig.cls_loss_coef — each now emits DeprecationWarning when set on the wrong config object. Removal in v1.9. SegmentationTrainConfig users: remove the num_select override — the model config value is always used. (refactor: BuilderArgs Protocol + ModelConfig/TrainConfig field deduplication #841)

🔧 Fixed

• Fixed ONNX/TRT dynamic batch inference. gen_encoder_output_proposals and Transformer.forward extracted the batch size as a Python int and passed it to torch.full, .view(N_, ...), .expand(N_, ...), and .repeat(bs, ...), baking the training batch size into the exported graph. TRT engines built with --minShapes smaller than the trace batch failed at inference with Reshape: reshaping failed. All six call sites now use ONNX-symbolic equivalents (zeros_like, -1 reshapes, expand(memory.shape[0], ...)). (Refactor proposal generation in transformer.py for ONNX/TRT dynamic batching compatibility #950)

• Fixed RFDETRModelModule.on_load_checkpoint crashing with RuntimeError on resume from a different image resolution. DINOv2 positional embeddings in the checkpoint are now bicubic-interpolated to match model_config.positional_encoding_size before PyTorch Lightning applies the state dict. (fix: interpolate PE in on_load_checkpoint for resume #1002)

• Fixed training failure when square_resize_div_64=False. The non-square resize pipeline (SmallestMaxSize + LongestMaxSize) did not guarantee output dimensions divisible by patch_size * num_windows, causing WindowedDinov2WithRegistersEmbeddings.forward to raise ValueError. A PadIfNeeded step is now appended in both train and val/test pipelines. (fix: pad non-square resize outputs to multiples of patch_size * num_windows #991)

• Fixed YOLO segmentation training out-of-memory on large datasets. supervision.DetectionDataset.from_yolo(force_masks=True) was eager-rasterising H×W boolean masks at dataset construction time (≈1 GB per 1 000 images at 1024 px). A new _LazyYoloDetectionDataset stores polygon coordinates only and defers dense mask rasterisation to __getitem__, keeping RAM proportional to annotation count. (Lazily materialize YOLO segmentation masks at sample fetch time #851)

• Fixed _namespace.py regression where TrainConfig.num_select=300 silently overrode model-specific values of 100–200 for segmentation variants. num_select in the builder namespace now always reads from ModelConfig. (refactor: BuilderArgs Protocol + ModelConfig/TrainConfig field deduplication #841)

• Fixed models/weights.py: load_pretrain_weights now correctly auto-aligns the model head when the checkpoint has fewer classes than the configured default, preventing a silent mismatch when num_classes was not explicitly set. (refactor: config-native build_{model|criterion}_from_config #845)

• Fixed RFDETRLarge initialization showing two conflicting ValueErrors. When the deprecated-config fallback retry also fails, the fallback now re-raises the original error without chained context, so users see a single deterministic message. (Suppress chained fallback exceptions for RFDETR patch-size #975)

• Fixed WindowedDinov2WithRegistersEmbeddings.forward() failing silently under -O when input spatial dimensions are not divisible by patch_size * num_windows. It now raises ValueError with a clear message identifying the divisor and actual shape. (Enhance WindowedDinov2 input validation and fix tensor reshaping #167)

⚠️ Known Issues

• COCO class_name lookup for pretrained models (#988). The fix in fix: correct class_name lookup for pretrained COCO models #1005 was reverted (bd1634b9) due to a regression. A follow-up fix is planned; in the meantime, class_name for pretrained COCO models may be missing or incorrect. Workaround: read class names from the model's class_names attribute directly.

---

🏆 Contributors

A special welcome to our new contributors and a big thank you to everyone who helped with this release:

• Isaac Corley (@isaaccorley) — grayscale and multispectral imagery support
• Leonidas Valavanis (@valavanisleonidas) — RF_HOME weight cache directory
• @JKurjenmiekka — training_config.json reproducibility output
• @sergiovillanueva — dinov2_with_registers_windowed_small backbone option
• Omkar Kabde (@omkar-334) — from_checkpoint model-class auto-resolution
• Jonas Pirner (@pirnerjonas) — native RLE annotation support in COCO segmentation
• Md Faruk Alam (@farukalamai) — ONNX export filenames + checkpoint model_name storage + typing modernization
• M. Fazri Nizar (@mfazrinizar) — TFLite export + skip_best_epochs parameter
• Saiteja Malyala (@tr-teja) — ONNX/TRT dynamic batch inference fix
• Irfan Hamid (@Irfan-Hamid-creates) — non-square resize patch-divisibility fix
• Jirka Borovec (@Borda) — Kornia GPU augmentation pipeline, builder API refactor, deprecation work, release coordination

Automated contributions: @copilot, @pre-commit-ci[bot]

---

Full changelog: 1.6.5...1.7.0

[codecov]

Codecov Report

❌ Patch coverage is 33.33333% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 77%. Comparing base (1a17f6f) to head (163ac9d).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop   #1010    +/-   ##
========================================
- Coverage       80%     77%    -3%     
========================================
  Files          101     101            
  Lines         8519    8523     +4     
========================================
- Hits          6836    6549   -287     
- Misses        1683    1974   +291     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.