feat(reid): appearance ReID association via standalone reid package - #511
Open
AlexBodner wants to merge 71 commits into
Open
feat(reid): appearance ReID association via standalone reid package#511AlexBodner wants to merge 71 commits into
AlexBodner wants to merge 71 commits into
Conversation
Add the optional trackers[reid] extra (git-pinned roboflow-reid during review) plus the lazy trackers._reid boundary that resolves reid.ReIDModel on demand. Ship association-only, torch-free modules under trackers.core.reid: the ReIDEncoder protocol, FeatureBank (per-track EMA), and appearance_similarity / extract_detection_embeddings. The model stack (encoder, weights, preprocessing, catalog, gallery eval) lives in the standalone reid package and is never vendored. Co-authored-by: Cursor <cursoragent@cursor.com>
Add appearance-IoU fusion (botsort/fusion.py) and wire it into BoT-SORT's
first and unconfirmed association stages, gated by proximity (standard IoU)
and appearance thresholds. Tracklets gain an optional per-track feature
bank; matched high-confidence detections update it. reid_model,
reid_ema_alpha, appearance_threshold, and proximity_threshold are new
BoTSORTTracker params; reid_model is excluded from CLI reflection.
Add --tracker.reid.{enable,model,device,architecture} CLI flags routed
through trackers._reid to reid.ReIDModel.from_pretrained. Importing BoT-SORT
stays torch-free (asserted by an isolation test). Add association/fusion/CLI
unit tests and a reid-backed integration smoke; docs and mkdocs nav cover
the association-only surface and link the model/eval stack out to reid.
CI installs the reid extra (unfrozen while the dep is a git pin).
Co-authored-by: Cursor <cursoragent@cursor.com>
- FeatureBank.update now L2-normalizes the incoming embedding and the resulting EMA, keeping the stored feature on the unit hypersphere (matches upstream BoT-SORT STrack.update_features). reid returns raw embeddings; normalization happens in the bank. Docstrings/tests updated. - Vectorize appearance._l2_normalize_rows. Co-authored-by: Cursor <cursoragent@cursor.com>
AlexBodner
force-pushed
the
feat/core/reid-consume-reid-package
branch
from
July 21, 2026 14:15
5afd3b9 to
fbbe664
Compare
AlexBodner
changed the title
…tion. Ports eval_trackers_reid from the reid-training branch with standalone reid imports and Colab-friendly private git installs for both trackers and re-ID. Co-authored-by: Cursor <cursoragent@cursor.com>
Exclude the default dev group from build/docs sync, authenticate git in integration/pytest workflows, and fix pre-commit failures in the ReID benchmark notebook and codespell config. Co-authored-by: Cursor <cursoragent@cursor.com>
Move the private git dependency to the reid extra only, avoid uv run re-syncing the dev group in build/docs jobs, and fix notebook JSON for pre-commit. Co-authored-by: Cursor <cursoragent@cursor.com>
State what trackers.core.reid covers positively, defer model/eval to the reid package, and drop subtractive architecture prose. Align install extra wording with develop (no roboflow-reid in prose). Co-authored-by: Cursor <cursoragent@cursor.com>
Add MOT17 val with/without ReID reference scores to the ReID API page and align the BoT-SORT optional ReID section with trackers docs style. Co-authored-by: Cursor <cursoragent@cursor.com>
Load frames by MOT index, use per-sequence FPS, re-encode to H.264 for notebook/Colab playback, and embed at the combined panel width. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Inline the optional reid import in the CLI like detection/tune, and keep all BoT-SORT ReID coverage in one test module. Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Avoid stale site-packages installs missing ReIDEncoder on this branch. Co-authored-by: Cursor <cursoragent@cursor.com>
Move install, usage, threshold selection, and benchmarks to learn/reid.md and leave api/reid.md as mkdocstrings reference. Co-authored-by: Cursor <cursoragent@cursor.com>
State that trackers[reid] installs the reid package, match the BoT-SORT Key Parameters table format, use HOTA/IDF1/MOTA ordering everywhere, cite pair counts behind the threshold percentages, and index the new pages in llms.txt. Co-authored-by: Cursor <cursoragent@cursor.com>
BoT-SORT takes min(d_iou, d_app), so failing the appearance or proximity gate drops the appearance term rather than vetoing a geometric match. Co-authored-by: Cursor <cursoragent@cursor.com>
The gate drops the appearance term rather than rejecting the match; fusion takes min(d_iou, d_app). Co-authored-by: Cursor <cursoragent@cursor.com>
Plot same-ID vs different-ID halved cosine distances on val GT crops with θ marked for threshold replication. Co-authored-by: Cursor <cursoragent@cursor.com>
Install reid and trackers from git with a PAT; PyPI trackers[reid] cannot fetch the private re-ID repo. Co-authored-by: Cursor <cursoragent@cursor.com>
Borda
reviewed
Jul 29, 2026
Co-authored-by: Jirka Borovec <6035284+Borda@users.noreply.github.com>
Replace the temporary git URL with reid>=0.1.0.dev0,<0.2 now that the package is published on PyPI. Co-authored-by: Cursor <cursoragent@cursor.com>
Drop the private-repo PAT path now that reid 0.1.0.dev0 is on PyPI. Co-authored-by: Cursor <cursoragent@cursor.com>
Use same-sequence temporal-horizon pair sampling for MOT17 and SoccerNet threshold figures, update learn/reid rates, and trim the eval notebook (Stanczyk §6c stashed separately). Co-authored-by: Cursor <cursoragent@cursor.com>
No behavior change; refresh CI on HEAD after the PyPI pin so integration and unit workflows re-run against reid 0.1.0.dev0. Co-authored-by: Cursor <cursoragent@cursor.com>
Collaborator
Author
|
@Borda on the `reid = ["reid"]` suggestion: keeping the floor/ceiling pin (`reid>=0.1.0.dev0,<0.2`) for now so installs stay on the published pre-release and do not silently float to an incompatible 0.2+. Happy to widen once we cut a stable `0.1.0`. |
Keep trackers[reid] PyPI pin alongside the new mask/Cutie extras from develop, and combine codespell skip/ignore lists so CI can run again. Co-authored-by: Cursor <cursoragent@cursor.com>
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
Rename ambiguous MOT bbox unpack locals and noqa the Colab pip install subprocess call so pre-commit.ci can pass on the merge commit. Co-authored-by: Cursor <cursoragent@cursor.com>
Rename ambiguous MOT bbox unpack locals and noqa the Colab pip install subprocess call; fold in the pre-commit.ci JSON autofix. Co-authored-by: Cursor <cursoragent@cursor.com>
Re-dump with the repo hook settings so pre-commit.ci stops oscillating on indent/encoding for notebooks/eval_trackers_reid.ipynb. Co-authored-by: Cursor <cursoragent@cursor.com>
Contributor
There was a problem hiding this comment.
🟡 Not ready to approve
Several user-facing docs/notebook cells are inconsistent or misleading about installation/usage (notably the Colab install pin and missing frame= requirement), and should be corrected before merge.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Pull request overview
Adds optional appearance-based ReID association to BoT-SORT while keeping the heavy model stack in the external reid package. This introduces NumPy-only tracker-side glue (trackers.core.reid), wires appearance–IoU fusion into BoT-SORT, and exposes ReID configuration via the trackers track CLI plus docs/tests/CI updates.
Changes:
- Add
trackers[reid]optional extra (PyPIreid>=0.1.0.dev0,<0.2) and update lockfile/mypy settings. - Implement tracker-side ReID utilities (
ReIDEncoder,FeatureBank, embedding extraction + cosine similarity) and BoT-SORT appearance–IoU fusion + per-track feature banks. - Extend CLI with
--tracker.reid.*flags (BoT-SORT only) and add unit/integration tests + documentation pages/notebooks.
File summaries
| File | Description |
|---|---|
| uv.lock | Adds/updates locked deps for the new reid optional extra and related transitive packages/markers. |
| pyproject.toml | Defines reid optional extra and mypy overrides; small tooling tweaks. |
| src/trackers/core/reid/init.py | Exposes the new tracker-side ReID helper API surface. |
| src/trackers/core/reid/encoder.py | Introduces the ReIDEncoder protocol for appearance embedding extraction. |
| src/trackers/core/reid/appearance.py | Adds embedding validation, extraction helper, and cosine similarity computation. |
| src/trackers/core/reid/feature_bank.py | Adds per-track EMA feature bank for appearance embeddings. |
| src/trackers/core/botsort/fusion.py | Implements BoT-SORT’s min-cost IoU/appearance fusion with gates. |
| src/trackers/core/botsort/tracklet.py | Adds optional feature_bank on tracklets for ReID state. |
| src/trackers/core/botsort/tracker.py | Wires ReID embeddings + feature bank updates into BoT-SORT association/spawn logic. |
| src/trackers/core/base.py | Hides reid_model from auto-generated CLI tracker params (injection-only arg). |
| src/trackers/scripts/track.py | Adds --tracker.reid.* flags and lazy-loads reid.ReIDModel at runtime. |
| tests/core/test_botsort_reid.py | Adds unit tests for feature bank, similarity, fusion, and BoT-SORT ReID behavior (+ integration smoke). |
| tests/scripts/test_track.py | Adds CLI wiring tests for ReID argument handling and help text. |
| .github/workflows/ci-integrations.yml | Installs integration deps with --extra reid to exercise the boundary. |
| README.md | Documents the new optional appearance ReID capability at a high level. |
| mkdocs.yml | Adjusts mkdocstrings config and adds ReID pages to navigation. |
| docs/api/reid.md | Adds API reference page for tracker-side ReID utilities. |
| docs/learn/reid.md | Adds user guide for enabling/tuning ReID appearance association. |
| docs/learn/install.md | Documents the new reid install extra. |
| docs/trackers/botsort.md | Links BoT-SORT docs to the ReID appearance guide. |
| docs/trackers/comparison.md | Cross-links benchmark tables to the ReID results page. |
| docs/llms.txt | Adds ReID page links for the docs index used by LLM tooling. |
| notebooks/plot_reid_appearance_distances.py | Adds a script to regenerate docs plots for appearance distance histograms. |
| notebooks/eval_trackers_reid.ipynb | Adds an evaluation notebook for BoT-SORT with/without ReID on MOT17 (and related diagnostics). |
Review details
- Files reviewed: 23/26 changed files
- Comments generated: 4
- Review effort level: Low
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Clarify README and the ReID quickstart that update() needs the current frame when reid_model is set. Co-authored-by: Cursor <cursoragent@cursor.com>
Drop the feature-branch git pin so the eval notebook matches the documented pip install path, and clear cell outputs. Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds optional appearance-ReID to BoT-SORT, sourcing the model stack from the standalone
reidpackage. Trackers ships only NumPy association glue (ReIDEncoder,FeatureBank,appearance_similarity,extract_detection_embeddings) plus BoT-SORT appearance–IoU fusion. Encoder weights, preprocessing, catalog, and gallery evaluation live inreidand are never vendored.This branch is merged with current
develop(including McByte) and is independent of the earlier stacked ReID PRs (#480/#501/#502).Added things
trackers[reid]optional extra →reid>=0.1.0.dev0,<0.2(PyPI).reid.*in mypy overrides;uv.lockupdated.src/trackers/core/reid/, torch-free):ReIDEncoder,FeatureBank(BoT-SORT EMA L2 before/after blend),appearance_similarity,extract_detection_embeddings.reid.ReIDModelat use time (same pattern as detection); importing BoT-SORT stays free ofreid/ torch (isolation test).reid_model,reid_ema_alpha,appearance_threshold,proximity_threshold.--tracker.reid.{enable,model,device,architecture}ontrackers track(BoT-SORT only).--extra reidrequired),@integrationsmoke with a realreid.ReIDModel, isolation test.docs/learn/reid.md(threshold guide + MOT17/SoccerNet association-local plots),docs/api/reid.md, install notes, BoT-SORT Appearance ReID section;notebooks/eval_trackers_reid.ipynbinstalls from PyPI.ci-tests.yml) syncs without--extra reid; integration (ci-integrations.yml) keeps--extra reid.Pre-merge checklist
reidto PyPI (0.1.0.dev0).pyproject.tomlto a PyPI range (reid>=0.1.0.dev0,<0.2) and refreshuv.lock.develop(McByte / mask extras) so PR CI can run.--extra reid(smoke should run, not skip).