chore: import upstream snapshot with attribution

2026-07-13 12:26:24 +08:00
commit 16031aae96
343 changed files with 88674 additions and 0 deletions
@@ -0,0 +1,117 @@
+---
+description: Install RF-DETR via pip, uv, or from source. Set up a development environment for contributing to Roboflow's real-time detection transformer.
+---
+
+# Installation
+
+Welcome to RF-DETR! This guide will help you install and set up RF-DETR for your projects. Whether you're a developer looking to contribute or an end-user ready to start using RF-DETR, we've got you covered.
+
+## Installation Methods
+
+RF-DETR supports several installation methods. Choose the option which best fits your workflow.
+
+!!! example "Installation"
+
+    === "pip (recommended)"
+
+        The easiest way to install RF-DETR is using `pip`. This method is recommended for most users.
+
+        ```bash
+        pip install rfdetr
+        ```
+
+    === "uv"
+
+        If you are using `uv`, you can install RF-DETR using the following command:
+
+        ```bash
+        uv pip install rfdetr
+        ```
+
+        For `uv` projects, you can also use:
+
+        ```bash
+        uv add rfdetr
+        ```
+
+    === "Source Archive"
+
+        To install the latest development version of RF-DETR from source without cloning the full repository, run the command below.
+
+        ```bash
+        pip install https://github.com/roboflow/rf-detr/archive/refs/heads/develop.zip
+        ```
+
+## Dev Environment
+
+If you plan to contribute to RF-DETR or modify the codebase locally, set up a local development environment using the steps below.
+
+!!! example "Development Setup"
+
+    === "virtualenv"
+
+        ```bash
+        # Clone the repository and navigate to the root directory
+        git clone --depth 1 -b develop https://github.com/roboflow/rf-detr.git
+        cd rf-detr
+
+        # Set up a Python virtual environment with a specific Python version (e.g., 3.10)
+        python3.10 -m venv venv
+
+        # Activate the virtual environment
+        source venv/bin/activate
+
+        # Upgrade pip
+        pip install --upgrade pip
+
+        # Install the package in development mode
+        pip install -e "."
+        ```
+
+    === "uv"
+
+        ```bash
+        # Clone the repository and navigate to the root directory
+        git clone --depth 1 -b develop https://github.com/roboflow/rf-detr.git
+        cd rf-detr
+
+        # Pin Python version (optional but recommended)
+        uv python pin 3.11
+
+        # Sync environment (creates .venv, installs pinned Python, and installs dependencies)
+        uv sync
+
+        # Install the package in development mode with all extras
+        uv pip install -e . --all-extras
+        ```
+
+## Optional Extras
+
+RF-DETR provides several optional extras for additional functionality:
+
+| Extra     | Install command                     | Purpose                                                         |
+| --------- | ----------------------------------- | --------------------------------------------------------------- |
+| `train`   | `pip install "rfdetr[train]"`       | Training dependencies (PyTorch Lightning, albumentations, etc.) |
+| `loggers` | `pip install "rfdetr[loggers]"`     | Experiment tracking (TensorBoard, W&B, MLflow, ClearML)         |
+| `onnx`    | `pip install "rfdetr[onnx]"`        | ONNX export                                                     |
+| `tflite`  | `pip install "rfdetr[onnx,tflite]"` | TFLite export (Python 3.12 only)                                |
+| `trt`     | `pip install "rfdetr[trt]"`         | TensorRT inference (pycuda, onnxruntime-gpu, tensorrt)          |
+| `kornia`  | `pip install "rfdetr[kornia]"`      | GPU-accelerated augmentations via Kornia                        |
+| `lora`    | `pip install "rfdetr[lora]"`        | LoRA fine-tuning with PEFT                                      |
+| `visual`  | `pip install "rfdetr[visual]"`      | Visualization utilities (matplotlib, pandas, seaborn)           |
+| `cli`     | `pip install "rfdetr[cli]"`         | CLI with typed argument parsing (jsonargparse)                  |
+| `plus`    | `pip install "rfdetr[plus]"`        | XLarge and 2XLarge detection models (PML 1.0 license)           |
+
+## Additional Notes
+
+- Ensure you have Python 3.10 or higher installed.
+- For development, it is recommended to use a virtual environment to avoid conflicts with other packages.
+- If you encounter any issues during installation, refer to the [troubleshooting](#troubleshooting) section or open an issue on the [GitHub repository](https://github.com/roboflow/rf-detr).
+
+## Troubleshooting
+
+If you encounter any issues during installation, here are some common solutions:
+
+- **Permission Issues**: Use `pip install --user rfdetr` to install the package for your user only.
+- **Dependency Conflicts**: Use a virtual environment to isolate the installation.
+- **Python Version**: Ensure you are using Python 3.10 or higher.
@@ -0,0 +1,404 @@
+---
+description: Per-version migration guide for RF-DETR. Covers breaking changes and deprecated APIs for each release series.
+---
+
+# Migration Guide
+
+Read each section between your current version and your target — every section covers
+only the delta between two adjacent releases.
+
+```
+1.4.x  →  1.5 →  1.6  →  1.7  →  1.8
+```
+
+You can apply all changes in one go; working through sections one release at a time
+and verifying between each step is optional but makes failures easier to isolate.
+Deprecated APIs emit a `DeprecationWarning` until the version marked for removal.
+See the [Changelog](../changelog.md) for the full list of changes in each release.
+
+---
+
+## Upgrade 1.8 → 1.9
+
+### Planned for Removal in v1.9
+
+The following APIs were deprecated in earlier releases and will be removed in v1.9. They still work in the current release (v1.8.x) but emit `DeprecationWarning`. Update your code before upgrading.
+
+!!! warning "Planned for removal: `rfdetr.util.*` and `rfdetr.deploy.*` import paths"
+
+    Deprecated since v1.6. Use the canonical replacements listed in the [Upgrade 1.5 → 1.6](#upgrade-15--16) section.
+
+    ```python
+    # These imports still work in v1.8 but emit DeprecationWarning; update before v1.9
+    from rfdetr.util.coco_classes import COCO_CLASSES  # → rfdetr.assets.coco_classes
+    from rfdetr.util.misc import get_rank  # → rfdetr.utilities
+    from rfdetr.deploy import export_onnx  # → rfdetr.export.main
+    ```
+
+!!! warning "Planned for removal: `build_namespace(model_config, train_config)`"
+
+    Deprecated since v1.7. Use `build_model_from_config` and `build_criterion_from_config` instead.
+
+!!! warning "Planned for removal: `load_pretrain_weights(nn_model, model_config, train_config)` with `train_config`"
+
+    Deprecated since v1.7. Drop the `train_config` positional argument.
+
+!!! warning "Planned for removal: `start_epoch` kwarg in `train()`"
+
+    Deprecated since v1.7. PyTorch Lightning resumes automatically via `resume=`.
+
+!!! warning "Planned for removal: `do_benchmark` kwarg in `train()`"
+
+    Deprecated since v1.7. Use the `rfdetr.export.benchmark` module instead.
+
+!!! warning "Planned for removal: `callbacks` dict kwarg in `train()`"
+
+    Deprecated since v1.7. Pass PTL `Callback` objects directly via the Lightning API instead.
+
+!!! warning "Planned for removal: misplaced config fields"
+
+    The following `TrainConfig` and `ModelConfig` fields moved to their correct config class in v1.7 and the deprecated compatibility shims will be removed in v1.9. Update any direct references:
+
+    | Field               | Removed from  | Use in        |
+    | ------------------- | ------------- | ------------- |
+    | `group_detr`        | `TrainConfig` | `ModelConfig` |
+    | `ia_bce_loss`       | `TrainConfig` | `ModelConfig` |
+    | `segmentation_head` | `TrainConfig` | `ModelConfig` |
+    | `num_select`        | `TrainConfig` | `ModelConfig` |
+    | `cls_loss_coef`     | `ModelConfig` | `TrainConfig` |
+
+---
+
+## Upgrade 1.7 → 1.8
+
+### Breaking changes
+
+!!! note "Breaking in v1.8.2: default keypoint schema changed to active-first `[17]`"
+
+    New checkpoints created from v1.8.2 onwards use `class_id=0` for person. Legacy `[0, 17]` checkpoints
+    are still supported — RF-DETR auto-detects the schema from the checkpoint at load time.
+
+    If your post-processing code offsets class IDs by 1 (common for background-first models), update it:
+
+    ```python
+    # Before (background-first [0, 17]: person was at class_id=1)
+    class_name = "person" if detection.class_id == 1 else "other"
+
+    # After (active-first [17]: person is at class_id=0)
+    class_name = "person" if detection.class_id == 0 else "other"
+    ```
+
+    Use `detection.data["class_name"]` for schema-agnostic name resolution.
+
+!!! warning "Breaking: `rfdetr.datasets.aug_config` renamed to `rfdetr.datasets.aug_configs`"
+
+    The augmentation config module was renamed (singular → plural). If you import from it directly:
+
+    ```python
+    # Before
+    from rfdetr.datasets.aug_config import AUG_AGGRESSIVE
+
+    # After
+    from rfdetr.datasets.aug_configs import AUG_AGGRESSIVE
+    ```
+
+    All preset constants (`AUG_AGGRESSIVE`, `AUG_CONSERVATIVE`, etc.) are unchanged.
+
+!!! warning "Breaking: `supervision>=0.29.0` now required"
+
+    Required for `sv.KeyPoints` support. `pip install rfdetr==1.8.0` pulls this automatically.
+    If another dependency pins `supervision<0.29.0`, resolve the conflict manually.
+
+!!! warning "Breaking: `pyDeprecate` constraint narrowed to `>=0.9,<0.10`"
+
+    Was `>=0.6,<0.8`. If another package pins an older version, resolve with:
+
+    ```bash
+    pip install "rfdetr==1.8.0" "pyDeprecate>=0.9,<0.10"
+    ```
+
+---
+
+## Upgrade 1.6 → 1.7
+
+### Breaking changes
+
+!!! warning "Breaking: `peft` removed from the default install"
+
+    LoRA fine-tuning now requires the `lora` extra. If you use LoRA adapters during
+    training, update your install command.
+
+    ```bash
+    # Before
+    pip install rfdetr
+
+    # After
+    pip install 'rfdetr[lora]'
+    ```
+
+!!! warning "Breaking: `predict()` stores source image in `detections.metadata`"
+
+    **`predict()` stores the source image in `detections.metadata`, not `detections.data`.**
+
+    ```python
+    # Before (1.6.4 and earlier)
+    source = detections.data["source_image"]
+
+    # After
+    source = detections.metadata["source_image"]
+    ```
+
+!!! warning "Breaking: `pyDeprecate` constraint changed to `>=0.6,<0.8`"
+
+    Was `>=0.3,<0.6`. If another package pins an older version, resolve with:
+
+    ```bash
+    pip install "rfdetr==1.7.0" "pyDeprecate>=0.6,<0.8"
+    ```
+
+### Deprecated in v1.7 → Remove in v1.9
+
+!!! note "Deprecated: `build_namespace()` split into two functions"
+
+    **`build_namespace(model_config, train_config)`** — use `build_model_from_config` or
+    `build_criterion_from_config` instead.
+
+    ```python
+    # Before (deprecated)
+    from rfdetr.models import build_namespace
+
+    ns = build_namespace(model_config, train_config)
+
+    # After
+    from rfdetr.models import build_model_from_config, build_criterion_from_config
+
+    model = build_model_from_config(model_config)
+    criterion = build_criterion_from_config(model_config, train_config)
+    ```
+
+!!! note "Deprecated: `load_pretrain_weights()` no longer takes `train_config`"
+
+    **`load_pretrain_weights(nn_model, model_config, train_config)`** — drop the
+    `train_config` positional argument.
+
+    ```python
+    # Before (deprecated)
+    from rfdetr.models import load_pretrain_weights
+
+    load_pretrain_weights(nn_model, model_config, train_config)
+
+    # After
+    from rfdetr.models import load_pretrain_weights
+
+    load_pretrain_weights(nn_model, model_config)
+    ```
+
+!!! note "Deprecated: config fields moved between `ModelConfig` and `TrainConfig`"
+
+    **Config fields placed in the wrong config object.** Move them as shown:
+
+    | Field               | Was in        | Move to       |
+    | ------------------- | ------------- | ------------- |
+    | `group_detr`        | `TrainConfig` | `ModelConfig` |
+    | `ia_bce_loss`       | `TrainConfig` | `ModelConfig` |
+    | `segmentation_head` | `TrainConfig` | `ModelConfig` |
+    | `num_select`        | `TrainConfig` | `ModelConfig` |
+    | `cls_loss_coef`     | `ModelConfig` | `TrainConfig` |
+
+    ```python
+    # Before (deprecated)
+    train_config = TrainConfig(group_detr=13, cls_loss_coef=2.0)
+
+    # After
+    model_config = ModelConfig(group_detr=13)
+    train_config = TrainConfig(cls_loss_coef=2.0)
+    ```
+
+### Deprecated in v1.7 → Remove in v2.0
+
+!!! note "Deprecated: `RFDETRBase` replaced by size-specific classes"
+
+    **`RFDETRBase`** defaulted to the small variant and is replaced by size-specific
+    classes. Choose the variant that matches your previous model size. If you used
+    `RFDETRBase()` without arguments, switch to `RFDETRSmall()`.
+
+    ```python
+    # Before (deprecated)
+    from rfdetr import RFDETRBase
+
+    model = RFDETRBase()
+
+    # After — pick one
+    from rfdetr import RFDETRNano, RFDETRSmall, RFDETRMedium, RFDETRLarge
+
+    model = RFDETRSmall()
+    ```
+
+!!! note "Deprecated: `RFDETRSegPreview` replaced by size-specific segmentation classes"
+
+    **`RFDETRSegPreview`** defaulted to the small variant and is replaced by size-specific
+    segmentation classes. If you used `RFDETRSegPreview()` without arguments, switch to
+    `RFDETRSegSmall()`.
+
+    ```python
+    # Before (deprecated)
+    from rfdetr import RFDETRSegPreview
+
+    model = RFDETRSegPreview()
+
+    # After — pick one
+    from rfdetr import RFDETRSegNano, RFDETRSegSmall, RFDETRSegMedium, RFDETRSegLarge
+
+    model = RFDETRSegSmall()
+    ```
+
+---
+
+## Upgrade 1.5 → 1.6
+
+### Breaking changes
+
+!!! warning "Breaking: `transformers` minimum version raised to `>=5.1.0`"
+
+    **`transformers` minimum version raised to `>=5.1.0,<6.0.0`.**
+
+    Projects pinned to `transformers<5.0.0` must upgrade. If upgrading is not possible,
+    pin `rfdetr<1.6.0`.
+
+    ```bash
+    pip install 'transformers>=5.1.0,<6.0.0'
+    ```
+
+!!! warning "Breaking: PyPI extras renamed"
+
+    **PyPI extras renamed.**
+
+    Update your `pip install` commands and `requirements*.txt` files.
+
+    | Old extra            | New extra         |
+    | -------------------- | ----------------- |
+    | `rfdetr[metrics]`    | `rfdetr[loggers]` |
+    | `rfdetr[onnxexport]` | `rfdetr[onnx]`    |
+
+    ```bash
+    # Before
+    pip install 'rfdetr[metrics]'
+    pip install 'rfdetr[onnxexport]'
+
+    # After
+    pip install 'rfdetr[loggers]'
+    pip install 'rfdetr[onnx]'
+    ```
+
+!!! warning "Breaking: `draw_synthetic_shape()` now returns a tuple"
+
+    **`draw_synthetic_shape()` now returns `(image, polygon)` instead of `image`.**
+
+    Update every call site that unpacks only the image.
+
+    ```python
+    # Before
+    img = draw_synthetic_shape(...)
+
+    # After
+    img, polygon = draw_synthetic_shape(...)
+    ```
+
+### Deprecated in v1.6 → Removed in v1.8
+
+!!! note "Deprecated: `simplify` and `force` arguments in `RFDETR.export()`"
+
+    **`RFDETR.export(..., simplify=..., force=...)`** — both arguments are no-ops.
+    Remove them from your calls.
+
+    ```python
+    # Before (deprecated)
+    model.export("model.onnx", simplify=True, force=True)
+
+    # After
+    model.export("model.onnx")
+    ```
+
+### Deprecated in v1.6 → Remove in v1.9
+
+!!! note "Deprecated: `rfdetr.util.*` and `rfdetr.deploy.*` import paths"
+
+    Backward-compatibility shims are still active but emit `DeprecationWarning` on import.
+    Replace with the canonical paths listed in the table below.
+
+    | Deprecated module                 | Canonical replacement              |
+    | --------------------------------- | ---------------------------------- |
+    | `rfdetr.util.coco_classes`        | `rfdetr.assets.coco_classes`       |
+    | `rfdetr.util.misc`                | `rfdetr.utilities`                 |
+    | `rfdetr.util.logger`              | `rfdetr.utilities.logger`          |
+    | `rfdetr.util.box_ops`             | `rfdetr.utilities.box_ops`         |
+    | `rfdetr.util.files`               | `rfdetr.utilities.files`           |
+    | `rfdetr.util.package`             | `rfdetr.utilities.package`         |
+    | `rfdetr.util.get_param_dicts`     | `rfdetr.training.param_groups`     |
+    | `rfdetr.util.drop_scheduler`      | `rfdetr.training.drop_schedule`    |
+    | `rfdetr.util.visualize`           | `rfdetr.visualize.data`            |
+    | `rfdetr.deploy`                   | `rfdetr.export`                    |
+    | `rfdetr.models.segmentation_head` | `rfdetr.models.heads.segmentation` |
+
+    **Examples:**
+
+    ```python
+    # Before (deprecated)
+    from rfdetr.util.coco_classes import COCO_CLASSES
+    from rfdetr.util.misc import get_rank, get_world_size, is_main_process, save_on_master
+    from rfdetr.util.logger import get_logger
+    from rfdetr.util.box_ops import box_cxcywh_to_xyxy, generalized_box_iou
+    from rfdetr.util.get_param_dicts import get_param_dict
+    from rfdetr.util.drop_scheduler import drop_scheduler
+    from rfdetr.util.visualize import save_gt_predictions_visualization
+    from rfdetr.deploy import export_onnx
+    from rfdetr.models.segmentation_head import SegmentationHead
+
+    # After
+    from rfdetr.assets.coco_classes import COCO_CLASSES
+    from rfdetr.utilities.distributed import get_rank, get_world_size, is_main_process, save_on_master
+    from rfdetr.utilities.logger import get_logger
+    from rfdetr.utilities.box_ops import box_cxcywh_to_xyxy, generalized_box_iou
+    from rfdetr.training.param_groups import get_param_dict
+    from rfdetr.training.drop_schedule import drop_scheduler
+    from rfdetr.visualize.data import save_gt_predictions_visualization
+    from rfdetr.export.main import export_onnx
+    from rfdetr.models.heads.segmentation import SegmentationHead
+    ```
+
+---
+
+## Upgrade 1.4 → 1.5
+
+### Breaking changes
+
+!!! warning "Breaking: `ModelConfig` rejects unknown keyword arguments"
+
+    **`ModelConfig` now raises `ValidationError` on unknown keyword arguments.**
+
+    Previously, unrecognised fields were silently ignored. Remove or rename any
+    unrecognised keys you pass to `ModelConfig(...)`.
+
+    ```python
+    # Before — silently accepted
+    config = ModelConfig(unknown_field=True)
+
+    # Now raises ValidationError — remove the unknown key
+    config = ModelConfig()
+    ```
+
+### Deprecated in v1.5 → Removed in v1.7
+
+!!! note "Deprecated: `OPEN_SOURCE_MODELS` replaced by `ModelWeights` enum"
+
+    **`OPEN_SOURCE_MODELS` constant** — use the `ModelWeights` enum instead. A
+    `DeprecationWarning` is emitted on access. See the
+    [API reference](../reference/rfdetr.md) for available enum values.
+
+    ```python
+    # Before (deprecated)
+    from rfdetr import OPEN_SOURCE_MODELS
+
+    # After
+    from rfdetr.assets.model_weights import ModelWeights
+    ```