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,30 @@
+---
+description: Python API reference for the ReID encoder protocol, feature bank, and appearance association utilities in Roboflow Trackers.
+---
+
+# ReID API
+
+Requires the `reid` extra (`pip install "trackers[reid]"`, see the
+[install guide](../learn/install.md)).
+
+This page covers the `ReIDEncoder` protocol, `FeatureBank`, and appearance
+association helpers in `trackers.core.reid`. For enabling appearance on
+BoT-SORT, threshold selection, and benchmark results, see the
+[ReID appearance guide](../learn/reid.md). Model loading and gallery evaluation
+are in the standalone [`reid`](https://github.com/roboflow/re-ID) package.
+
+## ReIDEncoder
+
+::: trackers.core.reid.encoder.ReIDEncoder
+
+## FeatureBank
+
+::: trackers.core.reid.feature_bank.FeatureBank
+
+## appearance_similarity
+
+::: trackers.core.reid.appearance.appearance_similarity
+
+## extract_detection_embeddings
+
+::: trackers.core.reid.appearance.extract_detection_embeddings

docs/learn/install.md

@@ -70,6 +70,30 @@ 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 the standalone
+[`reid`](https://github.com/roboflow/re-ID) package, which brings 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 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` command
+(BoT-SORT only).
+
 !!! tip "GPU Acceleration"
 
     For GPU support, ensure PyTorch is installed with CUDA or MPS.

docs/learn/reid.md

@@ -0,0 +1,132 @@
+---
+title: ReID Appearance — BoT-SORT Appearance Association | Trackers
+description: Use ReID appearance association with BoT-SORT in Roboflow Trackers, from model loading to appearance threshold selection, with MOT17 and SoccerNet results.
+---
+
+# ReID Appearance
+
+BoT-SORT can fuse appearance embeddings with IoU during association. Embeddings
+come from a model in the standalone [`reid`](https://github.com/roboflow/re-ID)
+package. See the [ReID API](../api/reid.md) for the association helpers.
+
+**What you'll learn:**
+
+- How to enable appearance association on BoT-SORT
+- Which parameters control the appearance gate
+- How to pick `appearance_threshold` for your encoder and domain
+- What ReID changes on MOT17 and SoccerNet
+
+---
+
+## Install
+
+```bash
+pip install "trackers[reid]"
+```
+
+For extra contents and other options, see the [install guide](install.md).
+
+---
+
+## Quickstart
+
+```python
+from reid import ReIDModel
+
+from trackers import BoTSORTTracker
+
+reid_model = ReIDModel.from_pretrained("fastreid_mot17_sbs50")
+tracker = BoTSORTTracker(reid_model=reid_model, appearance_threshold=0.2)
+```
+
+For the model catalog and fine-tuning, see the
+[`reid` training guide](https://github.com/roboflow/re-ID/blob/main/docs/learn/train.md).
+
+---
+
+## Key Parameters
+
+| Parameter              | Purpose                                                                                                          | Tuning guidance                                                                                                        |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `reid_model`           | Appearance encoder queried during association.                                                                   | Leave unset for IoU and CMC only. Pick a checkpoint trained on your object domain where possible.                      |
+| `reid_ema_alpha`       | EMA momentum for a track's appearance feature.                                                                    | Default 0.9. Higher keeps a stable long-term identity; lower adapts faster to appearance change but drifts more.       |
+| `appearance_threshold` | Maximum appearance distance `d_app` for appearance to lower a pair's matching cost.                              | BoT-SORT paper default 0.25. Calibrate per encoder and domain, see below.                                               |
+| `proximity_threshold`  | IoU gate applied before appearance (`IoU ≥ 1 - proximity_threshold`), from true IoU even with GIoU/DIoU/CIoU.      | Default 0.5. Lower restricts how far apart a pair may be before appearance stops contributing.                          |
+
+---
+
+## Choosing an appearance threshold
+
+BoT-SORT fuses costs as `min(d_iou, d_app)` with
+`d_app = 0.5 * (1 - cos_sim)`, and discards the appearance term when `d_app`
+exceeds `appearance_threshold` (paper default 0.25) or when the pair fails the
+`proximity_threshold` IoU gate. Appearance can therefore only lower a pair's
+cost, never veto a geometric match. Pick θ on a labeled split with the encoder
+you will track with:
+
+1. Embed GT crops.
+2. Histogram `d_app` for same-ID vs different-ID pairs.
+3. Choose θ so most same-ID pairs fall below it and most different-ID pairs fall
+   above it.
+
+**MOT17 val, `fastreid_mot17_sbs50`.** Same-ID distances peak near 0 and
+different-ID near 0.4. On 1360 same-ID and 2800 different-ID GT crop pairs, θ=0.2
+keeps 88% of same-ID pairs while passing 1% of different-ID pairs, which is why
+it beats the paper default 0.25 here
+([MOT17 re-ID study](https://www-sop.inria.fr/members/Francois.Bremond/Postscript/Tomasz__SCCAI_2025.pdf)
+Table 8 uses the same threshold).
+
+![FastReID MOT17 SBS on MOT17 val GT](../assets/reid/mot17-fastreid-appearance-distances.png)
+
+**SoccerNet test, `osnet_x1_0_msmt17_combineall`.** Same-ID and different-ID
+distances overlap heavily (similar kits). On 1200 same-ID and 2400 different-ID
+GT crop pairs, θ=0.2 admits 97% of same-ID pairs but also 50% of different-ID
+pairs, and tracking stays flat against CMC-only. θ=0.1 holds different-ID pairs
+to 9%, yet appearance still assists a mix of correct and same-kit pairs and
+costs HOTA and IDF1 (see the SoccerNet table below).
+
+![OSNet MSMT17 on SoccerNet test GT](../assets/reid/soccernet-osnet-appearance-distances.png)
+
+---
+
+## BoT-SORT with and without ReID
+
+### MOT17 test
+
+YOLOX detections, CMC on, Codabench MOT17 test (same protocol as the
+[tracker comparison](../trackers/comparison.md) default table). ReID:
+`fastreid_mot17_sbs50`, `appearance_threshold=0.2`
+([MOT17 re-ID study](https://www-sop.inria.fr/members/Francois.Bremond/Postscript/Tomasz__SCCAI_2025.pdf)
+Table 8).
+
+| Config          |  HOTA  |  IDF1  |  MOTA  |
+| :-------------- | :----: | :----: | :----: |
+| BoT-SORT        |  63.7  |  78.7  | **79.2** |
+| BoT-SORT + ReID | **63.9** | **79.2** | **79.2** |
+
+### MOT17 val-half
+
+YOLOX detections, CMC on, MOT17 val-half split, same encoder and threshold,
+scored with `trackers eval`.
+
+| Config          |  HOTA  |  IDF1  |  MOTA  |
+| :-------------- | :----: | :----: | :----: |
+| BoT-SORT        |  68.9  |  81.2  |  78.3  |
+| BoT-SORT + ReID | **69.1** | **81.9** | **78.4** |
+
+The MOT17 re-ID study reports 68.43 HOTA / 80.92 IDF1 without ReID and
+68.95 / 81.98 with, on the same split at `appearance_threshold=0.2`
+(Table 8 and Table 13; MOTA is not reported for that YOLOX setup).
+
+### SoccerNet test (OSNet MSMT17)
+
+Oracle detections, CMC on, SoccerNet-tracking test (same protocol as the
+[tracker comparison](../trackers/comparison.md) default table). ReID:
+`osnet_x1_0_msmt17_combineall` (MSMT17 pretrained), so this is a cross-domain
+encoder on soccer footage.
+
+| Config                              |  HOTA  |  IDF1  |  MOTA  |
+| :---------------------------------- | :----: | :----: | :----: |
+| BoT-SORT                            |  84.5  |  79.3  | **96.6** |
+| BoT-SORT + OSNet MSMT17 (θ=0.2)     | **84.6** | **79.4** | **96.6** |
+| BoT-SORT + OSNet MSMT17 (θ=0.1)     |  82.9  |  77.7  |  96.5  |

docs/llms.txt

@@ -11,6 +11,7 @@
 - [Track Objects](https://trackers.roboflow.com/latest/learn/track/): CLI and Python API
 - [Evaluate Trackers](https://trackers.roboflow.com/latest/learn/evaluate/): HOTA, IDF1, MOTA metrics guide
 - [Detection Quality Matters](https://trackers.roboflow.com/latest/learn/detection-quality/): How detector quality affects tracking
+- [ReID Appearance](https://trackers.roboflow.com/latest/learn/reid/): BoT-SORT appearance association, threshold selection, MOT17 and SoccerNet results
 - [SORT](https://trackers.roboflow.com/latest/trackers/sort/): Kalman + Hungarian algorithm tracker
 - [ByteTrack](https://trackers.roboflow.com/latest/trackers/bytetrack/): Low-confidence detection association tracker
 - [OC-SORT](https://trackers.roboflow.com/latest/trackers/ocsort/): Observation-centric re-update tracker
@@ -19,6 +20,7 @@
 
 - [Trackers API](https://trackers.roboflow.com/latest/api/trackers/)
 - [Motion API](https://trackers.roboflow.com/latest/api/motion/)
+- [ReID API](https://trackers.roboflow.com/latest/api/reid/)
 - [Evals API](https://trackers.roboflow.com/latest/api/evals/)
 
 ## Optional

docs/trackers/botsort.md

@@ -50,6 +50,12 @@ 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)
+
+BoT-SORT can fuse appearance embeddings with IoU during association via an
+optional `reid_model`. Install, usage, parameters, and MOT17 with/without ReID
+scores are on the [ReID appearance](../learn/reid.md) page.
+
 ## 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.

docs/trackers/comparison.md

@@ -28,6 +28,9 @@ Pedestrian tracking with crowded scenes and frequent occlusions. Strongly tests
 
     Parameters were tuned on the validation set. Results are reported on the
     test set via Codabench submission. Detections come from a YOLOX model.
+    BoT-SORT rows are CMC without appearance; for CMC + FastReID on MOT17 and
+    OSNet MSMT17 on SoccerNet see
+    [BoT-SORT with and without ReID](../learn/reid.md#bot-sort-with-and-without-reid).
 
 === "Default"
 
@@ -198,7 +201,9 @@ Long sequences with dense interactions and partial occlusions. Tests long-term I
 
     Parameters were tuned on the train set. Results are reported on the test
     set. SoccerNet-tracking has no validation split. This dataset provides
-    oracle (ground-truth) detections.
+    oracle (ground-truth) detections. The BoT-SORT row is CMC without
+    appearance; for OSNet MSMT17 appearance on this split see
+    [BoT-SORT with and without ReID](../learn/reid.md#bot-sort-with-and-without-reid).
 
 === "Default"
 

mkdocs.yml

@@ -104,6 +104,7 @@ plugins:
   - mkdocstrings:
       handlers:
         python:
+          paths: [src]
           options:
             # Controls whether to show symbol types in the table of contents
             show_symbol_type_toc: true
@@ -135,6 +136,7 @@ nav:
     - Detection Quality Matters: learn/detection-quality.md
     - State Estimators: learn/state-estimators.md
     - IoU Variants: learn/iou.md
+    - ReID Appearance: learn/reid.md
     - About: learn/about.md
   - Trackers:
     - Comparison: trackers/comparison.md
@@ -147,6 +149,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