feat(reid): appearance ReID association via standalone reid package

.github/workflows/ci-integrations.yml

@@ -27,7 +27,7 @@ jobs:
           activate-environment: true
 
       - name: 🚀 Install Packages
-        run: uv sync --frozen --group dev
+        run: uv sync --frozen --group dev --extra reid
 
 
       - name: 🧪 Run Integration Tests

README.md

@@ -22,6 +22,7 @@ Keeping track of objects across video frames is one of those problems that sound
 - **Benchmarked across four datasets.** MOT17, SportsMOT, SoccerNet, and DanceTrack — at default parameters and after hyperparameter tuning, so you know what to expect before you deploy.
 - **Tunable out of the box.** Built-in Optuna-based hyperparameter search via `trackers tune` so you can optimize for your specific scene and detector.
 - **Camera motion compensation.** BoT-SORT handles moving cameras natively, keeping track IDs stable even when the whole frame shifts.
+- **Optional appearance ReID.** BoT-SORT can fuse visual embeddings with motion for harder association scenes: install `trackers[reid]` (pulls in the standalone [`reid`](https://github.com/roboflow/re-ID) package) and pass a `reid.ReIDModel` as `reid_model`.
 
 ## Install
 

docs/api/reid.md

@@ -0,0 +1,77 @@
+---
+description: ReID encoder protocol, feature bank, and appearance association utilities in Roboflow Trackers.
+---
+
+# ReID API
+
+Requires the optional extra:
+
+```bash
+pip install 'trackers[reid]'
+```
+
+This page covers the `ReIDEncoder` protocol, `FeatureBank`, and appearance
+association helpers in `trackers.core.reid`. ReID model loading, gallery
+evaluation, and MOT fine-tuning are documented in the standalone
+[`reid`](https://github.com/roboflow/re-ID) package. BoT-SORT usage is on the
+[BoT-SORT](../trackers/botsort.md) page.
+
+## BoT-SORT with and without ReID
+
+Reference scores on MOT17 val-half with YOLOX detections from the
+[BoT-SORT paper](https://arxiv.org/abs/2206.14651) Table 1. The
+[`eval_trackers_reid.ipynb`](../../notebooks/eval_trackers_reid.ipynb) notebook
+uses the same split and detector with `fastreid_mot17_sbs50` and
+`appearance_threshold=0.2` (MOT17 re-ID study Table 8); run it for
+trackers-local results.
+
+| Config          | HOTA  | MOTA  | IDF1  |
+| :-------------- | :---: | :---: | :---: |
+| BoT-SORT        | 69.11 | 78.39 | 81.53 |
+| BoT-SORT + ReID | 69.17 | 78.46 | 82.07 |
+
+The MOT17 re-ID study
+([*Does Re-ID Really Help in Multi-Object Tracking?*](https://www-sop.inria.fr/members/Francois.Bremond/Postscript/Tomasz__SCCAI_2025.pdf),
+Table 8 + Table 13 combined row, app th=0.2) reports HOTA 68.43 / IDF1 80.92
+without ReID and 68.95 / 81.98 with MOT17 FastReID; MOTA is not reported for
+that YOLOX setup.
+
+## Use with BoT-SORT
+
+Import the encoder from `reid` and pass any object that implements
+`ReIDEncoder` to `BoTSORTTracker`:
+
+```python
+from reid import ReIDModel
+
+from trackers import BoTSORTTracker
+
+reid_model = ReIDModel.from_pretrained("osnet_x1_0_msmt17_combineall", device="cpu")
+tracker = BoTSORTTracker(reid_model=reid_model)
+```
+
+See the [`reid` package documentation](https://github.com/roboflow/re-ID) for
+the model catalog, `from_pretrained` sources, gallery evaluation, and MOT
+fine-tuning.
+
+## Encoder protocol
+
+`ReIDEncoder` is the interface BoT-SORT expects: a single `extract_features`
+method. `reid.ReIDModel` satisfies it; custom encoders can implement the
+protocol without the model stack.
+
+::: trackers.core.reid.encoder.ReIDEncoder
+
+## Feature bank
+
+Per-track EMA of appearance embeddings. L2-normalize before and after the EMA
+blend, following BoT-SORT
+[`STrack.update_features`](https://github.com/NirAharon/BoT-SORT/blob/main/tracker/bot_sort.py).
+
+::: trackers.core.reid.feature_bank.FeatureBank
+
+## Appearance
+
+::: trackers.core.reid.appearance.appearance_similarity
+
+::: trackers.core.reid.appearance.extract_detection_embeddings

docs/learn/install.md

@@ -70,6 +70,29 @@ The `detection` extra installs `inference-models`, enabling the CLI to run detec
     uv pip install "trackers[detection]"
     ```
 
+### ReID (BoT-SORT appearance)
+
+The `reid` extra installs PyTorch, timm, Hugging Face Hub, safetensors, Pillow,
+and gdown for ReID model loading (OSNet, FastReID SBS, and `timm:` backbones)
+and BoT-SORT appearance association.
+
+=== "pip"
+
+    ```bash
+    pip install "trackers[reid]"
+    ```
+
+=== "uv"
+
+    ```bash
+    uv pip install "trackers[reid]"
+    ```
+
+Use programmatically via `from reid import ReIDModel` and
+`BoTSORTTracker(reid_model=...)`, or via CLI flags such as
+`--tracker.reid.enable` and `--tracker.reid.architecture` on `trackers track`
+(BoT-SORT only).
+
 !!! tip "GPU Acceleration"
 
     For GPU support, ensure PyTorch is installed with CUDA or MPS.

docs/trackers/botsort.md

@@ -50,6 +50,38 @@ BoT-SORT keeps the same tracking-by-detection backbone as [ByteTrack](bytetrack.
 | `high_conf_det_threshold`                 | Confidence split between stage-1 and stage-2 detections.                                                                    | 0.5-0.7 common. Higher shifts more detections to recovery stage; lower gives stage-1 broader coverage.                                                                                                                                 |
 | `enable_cmc`                              | Enables camera motion compensation before association.                                                                      | Keep enabled for moving-camera footage (sports, drone, handheld). Disable mainly for static cameras if you need maximal speed.                                                                                                         |
 
+## ReID appearance (optional)
+
+Install the extra first:
+
+```bash
+pip install 'trackers[reid]'
+```
+
+BoT-SORT can fuse appearance embeddings with IoU during association. Pass a
+`reid_model` that implements `ReIDEncoder` (for example, `ReIDModel` from the
+[`reid`](https://github.com/roboflow/re-ID) package) and pass the current frame
+to `tracker.update` so the encoder can crop detections:
+
+```python
+from reid import ReIDModel
+from trackers import BoTSORTTracker
+
+reid_model = ReIDModel.from_pretrained("osnet_x1_0_msmt17_combineall", device="cpu")
+tracker = BoTSORTTracker(reid_model=reid_model)
+detections = tracker.update(detections, frame=frame)
+```
+
+See the [ReID API](../api/reid.md) for the encoder protocol, feature bank,
+association helpers, and a [with/without ReID comparison](../api/reid.md#botsort-with-and-without-reid)
+on MOT17 val.
+
+| Parameter              | Default | Purpose                                                                                                                                                                           |
+| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reid_ema_alpha`       | 0.9     | EMA momentum for a track's appearance feature; higher retains more history.                                                                                                       |
+| `appearance_threshold` | 0.25    | Appearance-distance gate (BoT-SORT paper default). Rejects matches when `0.5 * (1 - cos_sim)` exceeds this value. The MOT17 eval notebook uses `0.2` per the re-ID study Table 8. |
+| `proximity_threshold`  | 0.5     | Standard-IoU gate applied before appearance is used (requires IoU ≥ `1 - proximity_threshold`), computed from true IoU even when `iou` is GIoU/DIoU/CIoU.                         |
+
 ## Run on video, webcam, or RTSP stream
 
 These examples use `opencv-python` for decoding and display. Replace `<SOURCE_VIDEO_PATH>`, `<WEBCAM_INDEX>`, and `<RTSP_STREAM_URL>` with your inputs. `<WEBCAM_INDEX>` is usually 0 for the default camera.

mkdocs.yml

@@ -147,6 +147,7 @@ nav:
   - API Reference:
     - Trackers: api/trackers.md
     - Motion: api/motion.md
+    - ReID: api/reid.md
     - Datasets: api/datasets.md
     - Evals: api/evals.md
     - I/O: api/io.md