Add rfdetr model files

README.md

@@ -0,0 +1,192 @@
+---
+license: apache-2.0
+tags:
+- vision
+- image-detection
+- image-segmentation
+datasets:
+- COCO
+---
+
+<div align="center">
+
+# RF-DETR for TI EdgeAI
+
+### Real-Time Transformer Detection with a DINOv2 Backbone
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=for-the-badge)](https://opensource.org/licenses/Apache-2.0)
+[![Framework](https://img.shields.io/badge/Framework-ONNX-orange?style=for-the-badge)](https://onnx.ai/)
+[![Task](https://img.shields.io/badge/Task-Object%20Detection-green?style=for-the-badge)](https://github.com/TexasInstruments/edgeai)
+[![Dataset](https://img.shields.io/badge/Dataset-COCO-blueviolet?style=for-the-badge)](https://cocodataset.org/)
+
+</div>
+
+---
+
+## Overview
+
+**RF-DETR** is a real-time transformer-based object detection (and instance segmentation) architecture developed by Roboflow, achieving state-of-the-art accuracy/latency trade-offs on COCO (presented at ICLR 2026). It builds on a **DINOv2 ViT backbone** paired with a DETR-style decoder and a hierarchical feature pyramid, giving it strong small-object and dense-scene performance without the NMS and anchor-tuning overhead of traditional detectors.
+
+RF-DETR ships in six size variants, Nano through 2XLarge, for flexible accuracy-speed trade-offs. The Nano through Large variants are released under Apache 2.0; XLarge and 2XLarge require the `rfdetr[plus]` extra and are licensed under PML 1.0. This folder packages the ONNX exports and TIDL configs for the Apache-licensed detection variants (Nano/Small/Medium/Large); the `prepare_model.py` script can additionally export the PML-licensed XLarge/2XLarge detection variants and the segmentation family on request.
+
+---
+
+## Model Variants
+
+| Model | Input Size | mAP[.5:.95]% | mAP[.50]% | Validated Devices | Config |
+|-------|-----------|--------------|-----------|--------------------|--------|
+| `rfdetr_nano` | 384×384 | 48.4 | 67.6 | TDA4VH | [rfdetr_nano_config.yaml](rfdetr_nano_config.yaml) |
+| `rfdetr_small` | 512×512 | 53.0 | 72.1 | TDA4VH | [rfdetr_small_config.yaml](rfdetr_small_config.yaml) |
+| `rfdetr_medium` | 576×576 | 54.7 | 73.6 | TDA4VH | [rfdetr_medium_config.yaml](rfdetr_medium_config.yaml) |
+| `rfdetr_large` | 704×704 | 56.5 | 75.1 | TDA4VH | [rfdetr_large_config.yaml](rfdetr_large_config.yaml) |
+
+> mAP values are on COCO val2017. `rfdetr_xlarge` (700×700, mAP[.5:.95] 58.6) and `rfdetr_2xlarge` (880×880, mAP[.5:.95] 60.1) are available via `prepare_model.py --plus` but are licensed under PML 1.0 and are not shipped as ONNX/config files in this folder.
+
+**Recommended for edge deployment:** `rfdetr_nano` (best accuracy/compute trade-off, smallest)
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+```bash
+# ONNX export dependencies
+pip install "rfdetr[onnx]"
+
+# For XLarge / 2XLarge variants (PML 1.0 license)
+pip install "rfdetr[onnx,plus]"
+
+# Inference and deployment
+pip install onnx>=1.22.0
+pip install onnxruntime>=1.23.2
+```
+
+### Export the Model
+
+```bash
+# List all available variants with accuracy and latency info
+python prepare_model.py --list-models
+
+# Export the default model (rfdetr_nano)
+python prepare_model.py
+
+# Export a specific model variant
+python prepare_model.py --model rfdetr_medium
+
+# Export multiple variants at once
+python prepare_model.py --model rfdetr_nano rfdetr_small rfdetr_medium rfdetr_large
+
+# Export XLarge / 2XLarge (requires rfdetr[plus], PML 1.0 license)
+python prepare_model.py --model rfdetr_xlarge rfdetr_2xlarge --plus
+```
+
+The script automatically:
+- Installs `rfdetr[onnx]` (or `rfdetr[onnx,plus]` for XLarge/2XLarge) if not already present
+- Downloads pretrained COCO weights from HuggingFace on first use
+- Exports the selected variant(s) to ONNX (opset 17 by default, static batch dimension)
+- Saves the result as `rfdetr_<variant>.onnx` in the output directory
+
+### Compile and Infer uing edgeai-tidlrunner
+
+> **Note:** Run the commands below from inside the `tidlrunner` directory (the cloned [edgeai-tidlrunner](https://github.com/TexasInstruments/edgeai-tidlrunner) repository), with `--config_path` pointing to this model's config file.
+
+**Compile using edgeai-tidlrunner - on PC**
+
+```bash
+cd /path/to/edgeai-tidlrunner
+tidlrunner-cli compile --target_device J784S4 \
+  --config_path /path/to/rfdetr_nano_config.yaml
+```
+
+**Run Inference Benchmark - on device**
+
+```bash
+cd /path/to/edgeai-tidlrunner
+tidlrunner-cli infer --target_device J784S4 \
+  --config_path /path/to/rfdetr_nano_config.yaml
+```
+
+### Compile and Infer using edgeai-tidl-tools (Advanced):
+
+Follow the instructions at https://github.com/TexasInstruments/edgeai-tidl-tools
+
+### Deploy using edgeai-tidl-tools:
+
+Deplyment can be done using **[edgeai-tidl-tools](https://github.com/TexasInstruments/edgeai-tidl-tools)**. For ONNX models, onnxruntime-tidl with TIDL acceleration can be used. Consult the documentation of edgeai-tidl-tools for more details.
+
+---
+
+## Citation
+
+If you use RF-DETR in your research, please cite:
+
+```bibtex
+@software{rfdetr2025,
+  title        = {RF-DETR},
+  author       = {Robinson, Isaac and Robicheaux, Peter and Popov, Matvei},
+  year         = {2025},
+  publisher    = {Roboflow},
+  url          = {https://github.com/roboflow/rf-detr},
+  note         = {International Conference on Learning Representations (ICLR) 2026}
+}
+```
+
+---
+
+## 🔗 Resources
+
+| Resource | Link |
+|----------|------|
+| **RF-DETR Source Code** | [roboflow/rf-detr](https://github.com/roboflow/rf-detr) |
+| **RF-DETR Documentation** | [rfdetr.roboflow.com](https://rfdetr.roboflow.com) |
+| **RF-DETR on HuggingFace** | [huggingface.co/roboflow](https://huggingface.co/roboflow) |
+| **edgeai-tidl-tools** | [GitHub](https://github.com/TexasInstruments/edgeai-tidl-tools) |
+| **edgeai-tidlrunner** | [GitHub](https://github.com/TexasInstruments/edgeai-tidlrunner) |
+| **EdgeAI SDK** | [Documentation](https://github.com/TexasInstruments/edgeai/blob/main/edgeai-mpu/readme_sdk.md) |
+
+---
+
+## Related Models
+
+<table>
+<tr>
+<td align="center">
+
+**RT-DETRv2**
+Real-time DETR variant
+Anchor-free, NMS-free
+
+</td>
+<td align="center">
+
+**DEIMv2**
+DETR-family detector
+Improved matching/training
+
+</td>
+<td align="center">
+
+**Deformable-DETR**
+Sparse attention DETR
+Faster convergence
+
+</td>
+<td align="center">
+
+**DETR**
+Original transformer detector
+End-to-end set prediction
+
+</td>
+</tr>
+</table>
+
+---
+
+<div align="center">
+
+**Maintained by:** Texas Instruments EdgeAI Team  
+**Last Updated:** August 2026
+
+</div>

prepare_model.py

@@ -0,0 +1,653 @@
+"""Script to export RF-DETR pretrained ONNX model(s).
+
+The rfdetr package auto-downloads pretrained COCO weights from HuggingFace on
+first use, then this script calls model.export() to produce the ONNX file.
+
+Detection variants (Apache 2.0, COCO pretrained):
+  rfdetr_nano    – 384×384,  30.5 M params,  AP50:95 48.4
+  rfdetr_small   – 512×512,  32.1 M params,  AP50:95 53.0
+  rfdetr_medium  – 576×576,  33.7 M params,  AP50:95 54.7
+  rfdetr_large   – 704×704,  33.9 M params,  AP50:95 56.5
+  rfdetr_xlarge  – 700×700, 126.4 M params,  AP50:95 58.6  [requires --plus]
+  rfdetr_2xlarge – 880×880, 126.9 M params,  AP50:95 60.1  [requires --plus]
+
+Segmentation variants (COCO pretrained):
+  rfdetr_seg_nano    – 312×312,  33.6 M params,  AP50:95 40.3
+  rfdetr_seg_small   – 384×384,  33.7 M params,  AP50:95 43.1
+  rfdetr_seg_medium  – 432×432,  35.7 M params,  AP50:95 45.3
+  rfdetr_seg_large   – 504×504,  36.2 M params,  AP50:95 47.1
+  rfdetr_seg_xlarge  – 624×624,  38.1 M params,  AP50:95 48.8  [requires --plus]
+  rfdetr_seg_2xlarge – 768×768,  38.6 M params,  AP50:95 49.9  [requires --plus]
+
+Input shape constraints:
+  Each model's spatial dimensions must be divisible by its block_size
+  (= patch_size × num_windows). The rfdetr API enforces this; using a
+  custom --shape that violates the constraint will raise a clear error.
+
+Usage:
+  python prepare_model.py
+  python prepare_model.py --model rfdetr_nano
+  python prepare_model.py --model rfdetr_nano rfdetr_small rfdetr_medium
+  python prepare_model.py --model rfdetr_large --shape 640 640
+  python prepare_model.py --model rfdetr_nano --backbone-only
+  python prepare_model.py --model rfdetr_nano --opset 18 --output-dir ./exports
+  python prepare_model.py --model rfdetr_xlarge rfdetr_2xlarge --plus
+  python prepare_model.py --model rfdetr_seg_nano rfdetr_seg_small
+  python prepare_model.py --list-models
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+
+# ─────────────────────────────────────────────
+# Model catalogue
+# ─────────────────────────────────────────────
+
+# Each entry:  variant_key → (class_name, default_shape, params_m, coco_ap5095, license, requires_plus, task)
+MODEL_CATALOG: dict[str, dict] = {
+    # ── Detection ────────────────────────────────────────────────────────────
+    "rfdetr_nano": {
+        "class":        "RFDETRNano",
+        "shape":        (384, 384),
+        "params_m":     30.5,
+        "ap50_95":      48.4,
+        "ap50":         67.6,
+        "latency_ms":   2.3,
+        "license":      "Apache 2.0",
+        "requires_plus": False,
+        "task":         "detection",
+    },
+    "rfdetr_small": {
+        "class":        "RFDETRSmall",
+        "shape":        (512, 512),
+        "params_m":     32.1,
+        "ap50_95":      53.0,
+        "ap50":         72.1,
+        "latency_ms":   3.5,
+        "license":      "Apache 2.0",
+        "requires_plus": False,
+        "task":         "detection",
+    },
+    "rfdetr_medium": {
+        "class":        "RFDETRMedium",
+        "shape":        (576, 576),
+        "params_m":     33.7,
+        "ap50_95":      54.7,
+        "ap50":         73.6,
+        "latency_ms":   4.4,
+        "license":      "Apache 2.0",
+        "requires_plus": False,
+        "task":         "detection",
+    },
+    "rfdetr_large": {
+        "class":        "RFDETRLarge",
+        "shape":        (704, 704),
+        "params_m":     33.9,
+        "ap50_95":      56.5,
+        "ap50":         75.1,
+        "latency_ms":   6.8,
+        "license":      "Apache 2.0",
+        "requires_plus": False,
+        "task":         "detection",
+    },
+    "rfdetr_xlarge": {
+        "class":        "RFDETRXLarge",
+        "shape":        (700, 700),
+        "params_m":     126.4,
+        "ap50_95":      58.6,
+        "ap50":         77.4,
+        "latency_ms":   11.5,
+        "license":      "PML 1.0",
+        "requires_plus": True,
+        "task":         "detection",
+    },
+    "rfdetr_2xlarge": {
+        "class":        "RFDETR2XLarge",
+        "shape":        (880, 880),
+        "params_m":     126.9,
+        "ap50_95":      60.1,
+        "ap50":         78.5,
+        "latency_ms":   17.2,
+        "license":      "PML 1.0",
+        "requires_plus": True,
+        "task":         "detection",
+    },
+    # ── Segmentation ─────────────────────────────────────────────────────────
+    "rfdetr_seg_nano": {
+        "class":        "RFDETRSegNano",
+        "shape":        (312, 312),
+        "params_m":     33.6,
+        "ap50_95":      40.3,
+        "ap50":         63.0,
+        "latency_ms":   3.4,
+        "license":      "Apache 2.0",
+        "requires_plus": False,
+        "task":         "segmentation",
+    },
+    "rfdetr_seg_small": {
+        "class":        "RFDETRSegSmall",
+        "shape":        (384, 384),
+        "params_m":     33.7,
+        "ap50_95":      43.1,
+        "ap50":         66.2,
+        "latency_ms":   4.4,
+        "license":      "Apache 2.0",
+        "requires_plus": False,
+        "task":         "segmentation",
+    },
+    "rfdetr_seg_medium": {
+        "class":        "RFDETRSegMedium",
+        "shape":        (432, 432),
+        "params_m":     35.7,
+        "ap50_95":      45.3,
+        "ap50":         68.4,
+        "latency_ms":   5.9,
+        "license":      "Apache 2.0",
+        "requires_plus": False,
+        "task":         "segmentation",
+    },
+    "rfdetr_seg_large": {
+        "class":        "RFDETRSegLarge",
+        "shape":        (504, 504),
+        "params_m":     36.2,
+        "ap50_95":      47.1,
+        "ap50":         70.5,
+        "latency_ms":   8.8,
+        "license":      "Apache 2.0",
+        "requires_plus": False,
+        "task":         "segmentation",
+    },
+    "rfdetr_seg_xlarge": {
+        "class":        "RFDETRSegXLarge",
+        "shape":        (624, 624),
+        "params_m":     38.1,
+        "ap50_95":      48.8,
+        "ap50":         72.2,
+        "latency_ms":   13.5,
+        "license":      "PML 1.0",
+        "requires_plus": True,
+        "task":         "segmentation",
+    },
+    "rfdetr_seg_2xlarge": {
+        "class":        "RFDETRSeg2XLarge",
+        "shape":        (768, 768),
+        "params_m":     38.6,
+        "ap50_95":      49.9,
+        "ap50":         73.1,
+        "latency_ms":   21.8,
+        "license":      "PML 1.0",
+        "requires_plus": True,
+        "task":         "segmentation",
+    },
+}
+
+# Default model exported when --model is not supplied
+DEFAULT_MODEL = "rfdetr_nano"
+
+
+# ─────────────────────────────────────────────
+# Dependency installer
+# ─────────────────────────────────────────────
+
+def _pip_install(*packages: str) -> None:
+    """Install *packages* via pip, suppressing verbose output."""
+    print(f"[DEP] Installing: {', '.join(packages)} …")
+    result = subprocess.run(
+        [sys.executable, "-m", "pip", "install", *packages],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    if result.returncode != 0:
+        print(f"[DEP] ERROR: pip install failed (exit code {result.returncode}).")
+        if result.stderr:
+            print(result.stderr.strip())
+        print("[DEP] Please install manually and re-run:")
+        print(f"      pip install {' '.join(packages)}")
+        sys.exit(1)
+    print("[DEP] Installation complete.\n")
+
+
+def ensure_rfdetr(need_plus: bool = False) -> None:
+    """
+    Ensure the rfdetr package (with ONNX export support) is importable.
+    Installs automatically if missing.
+
+    Args:
+        need_plus: Also install the rfdetr[plus] extra required by XLarge /
+                   2XLarge models (PML 1.0 licence).
+    """
+    extras = "rfdetr[onnx,plus]" if need_plus else "rfdetr[onnx]"
+
+    try:
+        importlib.import_module("rfdetr")
+        print(f"[DEP]  ✔  rfdetr is already installed.")
+    except ImportError:
+        print(f"[DEP]  ✘  rfdetr not found – installing '{extras}' …")
+        _pip_install(extras)
+        return
+
+    # rfdetr is present; check the onnx export extra (rfdetr.export module)
+    try:
+        importlib.import_module("rfdetr.export")
+        print("[DEP]  ✔  rfdetr export module is available.")
+    except (ImportError, ModuleNotFoundError):
+        print(f"[DEP]  ✘  rfdetr export support missing – upgrading to '{extras}' …")
+        _pip_install(extras)
+        # Invalidate cached module so export_model picks up the upgraded version
+        sys.modules.pop("rfdetr", None)
+        sys.modules.pop("rfdetr.export", None)
+
+
+# ─────────────────────────────────────────────
+# Model catalogue helpers
+# ─────────────────────────────────────────────
+
+def print_model_table() -> None:
+    """Print a formatted table of all available models."""
+    col = 22
+    header = (
+        f"  {'Variant':<{col}}  {'Task':<12}  {'Shape':<10}  "
+        f"{'Params(M)':<10}  {'AP50:95':<8}  {'AP50':<6}  "
+        f"{'Lat(ms)':<8}  {'License'}"
+    )
+    sep = "  " + "-" * (len(header) - 2)
+    print("\n" + "=" * len(header))
+    print("  Available RF-DETR model variants")
+    print("=" * len(header))
+    print(header)
+    print(sep)
+
+    for key, info in MODEL_CATALOG.items():
+        h, w = info["shape"]
+        plus = "  [--plus]" if info["requires_plus"] else ""
+        print(
+            f"  {key:<{col}}  {info['task']:<12}  {h}×{w:<5}  "
+            f"{info['params_m']:<10.1f}  {info['ap50_95']:<8.1f}  "
+            f"{info['ap50']:<6.1f}  {info['latency_ms']:<8.1f}  "
+            f"{info['license']}{plus}"
+        )
+    print("=" * len(header) + "\n")
+    print("  Latency measured on NVIDIA T4 GPU (TensorRT FP16).")
+    print("  [--plus] models require: pip install rfdetr[onnx,plus]\n")
+
+
+# ─────────────────────────────────────────────
+# Core export
+# ─────────────────────────────────────────────
+
+def export_model(
+    model_key: str,
+    output_dir: str,
+    shape: tuple[int, int] | None,
+    opset: int,
+    backbone_only: bool,
+    batch_size: int,
+    verbose: bool,
+    custom_weights: str | None,
+    force: bool,
+) -> str:
+    """
+    Instantiate an RF-DETR model and export it to ONNX.
+
+    Pretrained COCO weights are downloaded automatically from HuggingFace
+    on first use unless *custom_weights* is provided.
+
+    The rfdetr API always writes the ONNX to:
+        <tmp_dir>/inference_model.onnx  (or backbone_model.onnx)
+
+    This function moves it to:
+        <output_dir>/<model_key>.onnx   (or <model_key>_backbone.onnx)
+
+    Any .pth weight files produced by rfdetr in the temp directory are also
+    kept and moved to output_dir alongside the ONNX.
+
+    Args:
+        model_key      : Key from MODEL_CATALOG (e.g. "rfdetr_nano").
+        output_dir     : Final destination directory for the .onnx file.
+        shape          : Custom (height, width) or None to use model default.
+        opset          : ONNX opset version.
+        backbone_only  : Export backbone feature extractor only.
+        batch_size     : Batch size embedded in the exported graph.
+        verbose        : Print rfdetr's internal export messages.
+        custom_weights : Path to a local .pth checkpoint; None = COCO pretrained.
+        force          : Re-export even if the destination .onnx already exists.
+
+    Returns:
+        Absolute path of the saved .onnx file.
+    """
+    import rfdetr  # noqa: PLC0415
+
+    info       = MODEL_CATALOG[model_key]
+    class_name = info["class"]
+    task       = info["task"]
+
+    # ── Resolve the model class ───────────────────────────────────────────────
+    model_cls = getattr(rfdetr, class_name, None)
+    if model_cls is None:
+        print(
+            f"[ERROR] Class '{class_name}' not found in the rfdetr package.\n"
+            f"        Make sure rfdetr is up-to-date: pip install -U rfdetr[onnx]"
+        )
+        sys.exit(1)
+
+    # ── Determine export shape ────────────────────────────────────────────────
+    export_shape = shape if shape is not None else info["shape"]
+    h, w = export_shape
+
+    # ── Build destination path early so we can check for an existing file ─────
+    os.makedirs(output_dir, exist_ok=True)
+    suffix   = "_backbone" if backbone_only else ""
+    shape_tag = f"_{h}x{w}" if shape is not None else ""
+    dst_name = f"{model_key}{shape_tag}{suffix}.onnx"
+    dst_path = os.path.join(output_dir, dst_name)
+
+    if not force and os.path.exists(dst_path):
+        print(f"[SKIP] {dst_name} already exists. Use --force to re-export.\n")
+        return dst_path
+
+    print(f"[INFO] Model class : {class_name}")
+    print(f"[INFO] Task        : {task}")
+    print(f"[INFO] Input shape : {h}×{w}")
+    print(f"[INFO] Opset       : {opset}")
+    print(f"[INFO] Batch size  : {batch_size}")
+    if backbone_only:
+        print("[INFO] Mode        : backbone only")
+    if custom_weights:
+        print(f"[INFO] Weights     : {custom_weights}")
+    else:
+        print("[INFO] Weights     : COCO pretrained (auto-downloaded)")
+    print()
+
+    # ── Instantiate model ─────────────────────────────────────────────────────
+    print("[INFO] Loading model …")
+    init_kwargs: dict = {}
+    if custom_weights:
+        init_kwargs["pretrain_weights"] = custom_weights
+    model = model_cls(**init_kwargs)
+    print("[INFO] Model ready.\n")
+
+    # ── Export to a temporary directory, then move to final destination ───────
+    with tempfile.TemporaryDirectory(prefix="rfdetr_export_") as tmp_dir:
+        print("[INFO] Exporting to ONNX …")
+        model.export(
+            output_dir     = tmp_dir,
+            format         = "onnx",
+            shape          = (h, w),
+            opset_version  = opset,
+            backbone_only  = backbone_only,
+            batch_size     = batch_size,
+            verbose        = verbose,
+        )
+
+        # Locate the exported .onnx file.
+        # rfdetr has used different output filenames across versions:
+        #   ≤1.x  → inference_model.onnx / backbone_model.onnx
+        #   ≥1.8  → rfdetr-<size>.onnx  (e.g. rfdetr-nano.onnx)
+        # Try known names first, then fall back to any .onnx in the directory.
+        size_tag = model_key.replace("rfdetr_seg_", "").replace("rfdetr_", "")
+        candidates_ordered = (
+            [f"rfdetr-{size_tag}.onnx", "backbone_model.onnx"]
+            if backbone_only else
+            [f"rfdetr-{size_tag}.onnx", "inference_model.onnx"]
+        )
+
+        src_path = None
+        for name in candidates_ordered:
+            p = os.path.join(tmp_dir, name)
+            if os.path.exists(p):
+                src_path = p
+                break
+
+        if src_path is None:
+            all_onnx = [f for f in os.listdir(tmp_dir) if f.endswith(".onnx")]
+            if not all_onnx:
+                print(f"[ERROR] No .onnx file found in temp dir: {tmp_dir}")
+                sys.exit(1)
+            src_path = os.path.join(tmp_dir, all_onnx[0])
+            print(f"[INFO] Located exported model: {all_onnx[0]}")
+
+        shutil.move(src_path, dst_path)
+
+        # Keep any .pth weight files produced alongside the ONNX
+        for fname in os.listdir(tmp_dir):
+            if fname.endswith(".pth"):
+                pth_dst = os.path.join(output_dir, fname)
+                shutil.move(os.path.join(tmp_dir, fname), pth_dst)
+                print(f"[INFO] PTH weights saved to : {pth_dst}")
+
+    print(f"\n[SUCCESS] ONNX model saved to: {dst_path}\n")
+    return dst_path
+
+
+# ─────────────────────────────────────────────
+# CLI
+# ─────────────────────────────────────────────
+
+def build_parser() -> argparse.ArgumentParser:
+    default_output = os.path.dirname(os.path.abspath(__file__))
+
+    parser = argparse.ArgumentParser(
+        description=(
+            "Export RF-DETR pretrained ONNX models.\n\n"
+            "Pretrained COCO weights are downloaded automatically from\n"
+            "HuggingFace on first use.  Run --list-models to see all variants."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  %(prog)s\n"
+            "  %(prog)s --model rfdetr_nano\n"
+            "  %(prog)s --model rfdetr_nano rfdetr_small rfdetr_large\n"
+            "  %(prog)s --model rfdetr_medium --shape 608 608\n"
+            "  %(prog)s --model rfdetr_nano --backbone-only\n"
+            "  %(prog)s --model rfdetr_xlarge rfdetr_2xlarge --plus\n"
+            "  %(prog)s --model rfdetr_seg_nano rfdetr_seg_medium\n"
+            "  %(prog)s --model rfdetr_large --weights /path/to/custom.pth\n"
+            "  %(prog)s --model rfdetr_nano --opset 18 --output-dir ./exports\n"
+            "  %(prog)s --list-models"
+        ),
+    )
+
+    # ── Model selection ───────────────────────────────────────────────────────
+    parser.add_argument(
+        "--model",
+        nargs="+",
+        default=[DEFAULT_MODEL],
+        choices=list(MODEL_CATALOG.keys()),
+        metavar="VARIANT",
+        help=(
+            f"Model variant(s) to export. Default: {DEFAULT_MODEL}. "
+            "Run --list-models to see all options."
+        ),
+    )
+
+    # ── Export parameters ─────────────────────────────────────────────────────
+    parser.add_argument(
+        "--shape",
+        nargs=2,
+        type=int,
+        default=None,
+        metavar=("H", "W"),
+        help=(
+            "Custom input resolution (height width). Must be divisible by the "
+            "model's block_size (patch_size × num_windows). "
+            "Default: each model's native resolution."
+        ),
+    )
+    parser.add_argument(
+        "--opset",
+        type=int,
+        default=17,
+        metavar="N",
+        help="ONNX opset version. Default: 17.",
+    )
+    parser.add_argument(
+        "--batch-size",
+        type=int,
+        default=1,
+        metavar="N",
+        help="Batch size embedded in the exported ONNX graph. Default: 1.",
+    )
+    parser.add_argument(
+        "--backbone-only",
+        action="store_true",
+        default=False,
+        help=(
+            "Export only the DINOv2 backbone (feature extractor). "
+            "Output is named <variant>_backbone.onnx."
+        ),
+    )
+
+    # ── Weight source ─────────────────────────────────────────────────────────
+    parser.add_argument(
+        "--weights",
+        default=None,
+        metavar="PATH",
+        help=(
+            "Path to a local .pth checkpoint. "
+            "When omitted the official COCO pretrained weights are downloaded "
+            "automatically from HuggingFace."
+        ),
+    )
+
+    # ── Output ────────────────────────────────────────────────────────────────
+    parser.add_argument(
+        "--output-dir",
+        default=default_output,
+        metavar="DIR",
+        help=f"Directory where .onnx files will be saved. Default: {default_output}",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        default=False,
+        help="Re-export even if the destination .onnx file already exists.",
+    )
+
+    # ── Plus models ───────────────────────────────────────────────────────────
+    parser.add_argument(
+        "--plus",
+        action="store_true",
+        default=False,
+        help=(
+            "Install rfdetr[onnx,plus] to enable XLarge / 2XLarge models "
+            "(PML 1.0 license). Required when exporting rfdetr_xlarge, "
+            "rfdetr_2xlarge, rfdetr_seg_xlarge, or rfdetr_seg_2xlarge."
+        ),
+    )
+
+    # ── Verbosity ─────────────────────────────────────────────────────────────
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        default=False,
+        help="Suppress rfdetr's internal verbose output.",
+    )
+
+    # ── Utility ───────────────────────────────────────────────────────────────
+    parser.add_argument(
+        "--list-models",
+        action="store_true",
+        default=False,
+        help="Print the model catalogue table and exit.",
+    )
+
+    return parser
+
+
+# ─────────────────────────────────────────────
+# Entry point
+# ─────────────────────────────────────────────
+
+def main() -> None:
+    parser = build_parser()
+    args   = parser.parse_args()
+
+    if args.list_models:
+        print_model_table()
+        return
+
+    # ── Validate requested models ─────────────────────────────────────────────
+    need_plus = args.plus or any(
+        MODEL_CATALOG[m]["requires_plus"] for m in args.model
+    )
+
+    plus_models = [m for m in args.model if MODEL_CATALOG[m]["requires_plus"]]
+    if plus_models and not args.plus:
+        print(
+            f"[WARN] {', '.join(plus_models)} require the rfdetr[plus] extra "
+            "(PML 1.0 license).\n"
+            "       Re-run with --plus to confirm and install it."
+        )
+        sys.exit(1)
+
+    # ── Warn when --weights is used with multiple models ─────────────────────
+    if args.weights and len(args.model) > 1:
+        print(
+            "[WARN] --weights applies the same checkpoint to every model in "
+            "--model.\n       This is unusual; pass a single --model variant "
+            "when using custom weights."
+        )
+
+    # ── Install rfdetr ────────────────────────────────────────────────────────
+    ensure_rfdetr(need_plus=need_plus)
+
+    # ── Export each model ─────────────────────────────────────────────────────
+    shape = (args.shape[0], args.shape[1]) if args.shape else None
+    output_dir = os.path.abspath(args.output_dir)
+
+    exported: list[str] = []
+    failed:   list[str] = []
+
+    for model_key in args.model:
+        print(f"\n{'='*60}")
+        print(f"  Exporting: {model_key}")
+        print(f"{'='*60}\n")
+
+        try:
+            out_path = export_model(
+                model_key      = model_key,
+                output_dir     = output_dir,
+                shape          = shape,
+                opset          = args.opset,
+                backbone_only  = args.backbone_only,
+                batch_size     = args.batch_size,
+                verbose        = not args.quiet,
+                custom_weights = args.weights,
+                force          = args.force,
+            )
+            exported.append(out_path)
+        except SystemExit:
+            raise
+        except Exception as exc:
+            print(f"[ERROR] Export failed for '{model_key}': {exc}")
+            failed.append(model_key)
+
+    # ── Summary ───────────────────────────────────────────────────────────────
+    print("\n" + "=" * 60)
+    print("  Export Summary")
+    print("=" * 60)
+    for path in exported:
+        size_mb = os.path.getsize(path) / (1024 * 1024)
+        print(f"  ✔  {os.path.basename(path)}  ({size_mb:.1f} MB)")
+        print(f"       {path}")
+    if failed:
+        for key in failed:
+            print(f"  ✘  {key}  (FAILED)")
+    print("=" * 60 + "\n")
+
+    if failed:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

rfdetr_large_config.yaml

@@ -0,0 +1,152 @@
+task_type: detection
+dataloader:
+  name: coco_detection_dataloader
+  path: ./data/datasets/coco
+preprocess:
+  resize: 704
+  crop: 704
+  data_layout: NCHW
+  reverse_channels: true
+  backend: cv2
+  interpolation: null
+  resize_with_pad: false
+  pad_color:
+  - 0
+  - 0
+  - 0
+  name: image_preprocess
+session:
+  input_optimization: false
+  input_data_layout: NCHW
+  input_mean:
+  - 123.675
+  - 116.28
+  - 103.53
+  input_scale:
+  - 0.017125
+  - 0.017507
+  - 0.017429
+  runtime_options: {}
+  model_path: rfdetr_large.onnx
+  model_id: od-mh8043
+  input_details: null
+  output_details: null
+  num_inputs: 1
+postprocess:
+  reshape_list: null
+  formatter:
+    name: DetectionXYWH2XYXYCenterXY
+  resize_with_pad: false
+  normalized_detections: true
+  shuffle_indices: null
+  squeeze_axis: null
+  ignore_index: null
+  model_output_type: split
+  logits_bbox_to_bbox_ls:
+    score_fn: sigmoid
+    bbox_index: 0
+    scores_index: 1
+  keypoint: false
+  object6dpose: false
+  name: detection_postprocess
+metric:
+  label_offset_pred:
+    1: 1
+    2: 2
+    3: 3
+    4: 4
+    5: 5
+    6: 6
+    7: 7
+    8: 8
+    9: 9
+    10: 10
+    11: 11
+    12: 12
+    13: 13
+    14: 14
+    15: 15
+    16: 16
+    17: 17
+    18: 18
+    19: 19
+    20: 20
+    21: 21
+    22: 22
+    23: 23
+    24: 24
+    25: 25
+    26: 26
+    27: 27
+    28: 28
+    29: 29
+    30: 30
+    31: 31
+    32: 32
+    33: 33
+    34: 34
+    35: 35
+    36: 36
+    37: 37
+    38: 38
+    39: 39
+    40: 40
+    41: 41
+    42: 42
+    43: 43
+    44: 44
+    45: 45
+    46: 46
+    47: 47
+    48: 48
+    49: 49
+    50: 50
+    51: 51
+    52: 52
+    53: 53
+    54: 54
+    55: 55
+    56: 56
+    57: 57
+    58: 58
+    59: 59
+    60: 60
+    61: 61
+    62: 62
+    63: 63
+    64: 64
+    65: 65
+    66: 66
+    67: 67
+    68: 68
+    69: 69
+    70: 70
+    71: 71
+    72: 72
+    73: 73
+    74: 74
+    75: 75
+    76: 76
+    77: 77
+    78: 78
+    79: 79
+    80: 80
+    81: 81
+    82: 82
+    83: 83
+    84: 84
+    85: 85
+    86: 86
+    87: 87
+    88: 88
+    89: 89
+    90: 90
+    91: 91
+    0: 0
+model_info:
+  metric_reference:
+    accuracy_ap[.5:.95]%: 56.5
+  model_shortlist: 10
+  compact_name: rfdetr-large-704x704
+  shortlisted: true
+  recommended: false

rfdetr_medium_config.yaml

@@ -0,0 +1,152 @@
+task_type: detection
+dataloader:
+  name: coco_detection_dataloader
+  path: ./data/datasets/coco
+preprocess:
+  resize: 576
+  crop: 576
+  data_layout: NCHW
+  reverse_channels: true
+  backend: cv2
+  interpolation: null
+  resize_with_pad: false
+  pad_color:
+  - 0
+  - 0
+  - 0
+  name: image_preprocess
+session:
+  input_optimization: false
+  input_data_layout: NCHW
+  input_mean:
+  - 123.675
+  - 116.28
+  - 103.53
+  input_scale:
+  - 0.017125
+  - 0.017507
+  - 0.017429
+  runtime_options: {}
+  model_path: rfdetr_medium.onnx
+  model_id: od-mh8042
+  input_details: null
+  output_details: null
+  num_inputs: 1
+postprocess:
+  reshape_list: null
+  formatter:
+    name: DetectionXYWH2XYXYCenterXY
+  resize_with_pad: false
+  normalized_detections: true
+  shuffle_indices: null
+  squeeze_axis: null
+  ignore_index: null
+  model_output_type: split
+  logits_bbox_to_bbox_ls:
+    score_fn: sigmoid
+    bbox_index: 0
+    scores_index: 1
+  keypoint: false
+  object6dpose: false
+  name: detection_postprocess
+metric:
+  label_offset_pred:
+    1: 1
+    2: 2
+    3: 3
+    4: 4
+    5: 5
+    6: 6
+    7: 7
+    8: 8
+    9: 9
+    10: 10
+    11: 11
+    12: 12
+    13: 13
+    14: 14
+    15: 15
+    16: 16
+    17: 17
+    18: 18
+    19: 19
+    20: 20
+    21: 21
+    22: 22
+    23: 23
+    24: 24
+    25: 25
+    26: 26
+    27: 27
+    28: 28
+    29: 29
+    30: 30
+    31: 31
+    32: 32
+    33: 33
+    34: 34
+    35: 35
+    36: 36
+    37: 37
+    38: 38
+    39: 39
+    40: 40
+    41: 41
+    42: 42
+    43: 43
+    44: 44
+    45: 45
+    46: 46
+    47: 47
+    48: 48
+    49: 49
+    50: 50
+    51: 51
+    52: 52
+    53: 53
+    54: 54
+    55: 55
+    56: 56
+    57: 57
+    58: 58
+    59: 59
+    60: 60
+    61: 61
+    62: 62
+    63: 63
+    64: 64
+    65: 65
+    66: 66
+    67: 67
+    68: 68
+    69: 69
+    70: 70
+    71: 71
+    72: 72
+    73: 73
+    74: 74
+    75: 75
+    76: 76
+    77: 77
+    78: 78
+    79: 79
+    80: 80
+    81: 81
+    82: 82
+    83: 83
+    84: 84
+    85: 85
+    86: 86
+    87: 87
+    88: 88
+    89: 89
+    90: 90
+    91: 91
+    0: 0
+model_info:
+  metric_reference:
+    accuracy_ap[.5:.95]%: 54.7
+  model_shortlist: 10
+  compact_name: rfdetr-medium-576x576
+  shortlisted: true
+  recommended: false

rfdetr_nano_config.yaml

@@ -0,0 +1,152 @@
+task_type: detection
+dataloader:
+  name: coco_detection_dataloader
+  path: ./data/datasets/coco
+preprocess:
+  resize: 384
+  crop: 384
+  data_layout: NCHW
+  reverse_channels: true
+  backend: cv2
+  interpolation: null
+  resize_with_pad: false
+  pad_color:
+  - 0
+  - 0
+  - 0
+  name: image_preprocess
+session:
+  input_optimization: false
+  input_data_layout: NCHW
+  input_mean:
+  - 123.675
+  - 116.28
+  - 103.53
+  input_scale:
+  - 0.017125
+  - 0.017507
+  - 0.017429
+  runtime_options: {}
+  model_path: rfdetr_nano.onnx
+  model_id: od-mh8040
+  input_details: null
+  output_details: null
+  num_inputs: 1
+postprocess:
+  reshape_list: null
+  formatter:
+    name: DetectionXYWH2XYXYCenterXY
+  resize_with_pad: false
+  normalized_detections: true
+  shuffle_indices: null
+  squeeze_axis: null
+  ignore_index: null
+  model_output_type: split
+  logits_bbox_to_bbox_ls:
+    score_fn: sigmoid
+    bbox_index: 0
+    scores_index: 1
+  keypoint: false
+  object6dpose: false
+  name: detection_postprocess
+metric:
+  label_offset_pred:
+    1: 1
+    2: 2
+    3: 3
+    4: 4
+    5: 5
+    6: 6
+    7: 7
+    8: 8
+    9: 9
+    10: 10
+    11: 11
+    12: 12
+    13: 13
+    14: 14
+    15: 15
+    16: 16
+    17: 17
+    18: 18
+    19: 19
+    20: 20
+    21: 21
+    22: 22
+    23: 23
+    24: 24
+    25: 25
+    26: 26
+    27: 27
+    28: 28
+    29: 29
+    30: 30
+    31: 31
+    32: 32
+    33: 33
+    34: 34
+    35: 35
+    36: 36
+    37: 37
+    38: 38
+    39: 39
+    40: 40
+    41: 41
+    42: 42
+    43: 43
+    44: 44
+    45: 45
+    46: 46
+    47: 47
+    48: 48
+    49: 49
+    50: 50
+    51: 51
+    52: 52
+    53: 53
+    54: 54
+    55: 55
+    56: 56
+    57: 57
+    58: 58
+    59: 59
+    60: 60
+    61: 61
+    62: 62
+    63: 63
+    64: 64
+    65: 65
+    66: 66
+    67: 67
+    68: 68
+    69: 69
+    70: 70
+    71: 71
+    72: 72
+    73: 73
+    74: 74
+    75: 75
+    76: 76
+    77: 77
+    78: 78
+    79: 79
+    80: 80
+    81: 81
+    82: 82
+    83: 83
+    84: 84
+    85: 85
+    86: 86
+    87: 87
+    88: 88
+    89: 89
+    90: 90
+    91: 91
+    0: 0
+model_info:
+  metric_reference:
+    accuracy_ap[.5:.95]%: 48.4
+  model_shortlist: 10
+  compact_name: rfdetr-nano-384x384
+  shortlisted: true
+  recommended: true

rfdetr_small_config.yaml

@@ -0,0 +1,152 @@
+task_type: detection
+dataloader:
+  name: coco_detection_dataloader
+  path: ./data/datasets/coco
+preprocess:
+  resize: 512
+  crop: 512
+  data_layout: NCHW
+  reverse_channels: true
+  backend: cv2
+  interpolation: null
+  resize_with_pad: false
+  pad_color:
+  - 0
+  - 0
+  - 0
+  name: image_preprocess
+session:
+  input_optimization: false
+  input_data_layout: NCHW
+  input_mean:
+  - 123.675
+  - 116.28
+  - 103.53
+  input_scale:
+  - 0.017125
+  - 0.017507
+  - 0.017429
+  runtime_options: {}
+  model_path: rfdetr_small.onnx
+  model_id: od-mh8041
+  input_details: null
+  output_details: null
+  num_inputs: 1
+postprocess:
+  reshape_list: null
+  formatter:
+    name: DetectionXYWH2XYXYCenterXY
+  resize_with_pad: false
+  normalized_detections: true
+  shuffle_indices: null
+  squeeze_axis: null
+  ignore_index: null
+  model_output_type: split
+  logits_bbox_to_bbox_ls:
+    score_fn: sigmoid
+    bbox_index: 0
+    scores_index: 1
+  keypoint: false
+  object6dpose: false
+  name: detection_postprocess
+metric:
+  label_offset_pred:
+    1: 1
+    2: 2
+    3: 3
+    4: 4
+    5: 5
+    6: 6
+    7: 7
+    8: 8
+    9: 9
+    10: 10
+    11: 11
+    12: 12
+    13: 13
+    14: 14
+    15: 15
+    16: 16
+    17: 17
+    18: 18
+    19: 19
+    20: 20
+    21: 21
+    22: 22
+    23: 23
+    24: 24
+    25: 25
+    26: 26
+    27: 27
+    28: 28
+    29: 29
+    30: 30
+    31: 31
+    32: 32
+    33: 33
+    34: 34
+    35: 35
+    36: 36
+    37: 37
+    38: 38
+    39: 39
+    40: 40
+    41: 41
+    42: 42
+    43: 43
+    44: 44
+    45: 45
+    46: 46
+    47: 47
+    48: 48
+    49: 49
+    50: 50
+    51: 51
+    52: 52
+    53: 53
+    54: 54
+    55: 55
+    56: 56
+    57: 57
+    58: 58
+    59: 59
+    60: 60
+    61: 61
+    62: 62
+    63: 63
+    64: 64
+    65: 65
+    66: 66
+    67: 67
+    68: 68
+    69: 69
+    70: 70
+    71: 71
+    72: 72
+    73: 73
+    74: 74
+    75: 75
+    76: 76
+    77: 77
+    78: 78
+    79: 79
+    80: 80
+    81: 81
+    82: 82
+    83: 83
+    84: 84
+    85: 85
+    86: 86
+    87: 87
+    88: 88
+    89: 89
+    90: 90
+    91: 91
+    0: 0
+model_info:
+  metric_reference:
+    accuracy_ap[.5:.95]%: 53.0
+  model_shortlist: 10
+  compact_name: rfdetr-small-512x512
+  shortlisted: true
+  recommended: false