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

[AlexBodner]

Summary

Adds optional appearance-ReID to BoT-SORT, sourcing the model stack from the standalone reid package. 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 in reid and 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

• Deps: trackers[reid] optional extra → reid>=0.1.0.dev0,<0.2 (PyPI). reid.* in mypy overrides; uv.lock updated.
• Association glue (src/trackers/core/reid/, torch-free): ReIDEncoder, FeatureBank (BoT-SORT EMA L2 before/after blend), appearance_similarity, extract_detection_embeddings.
• Lazy import: CLI loads reid.ReIDModel at use time (same pattern as detection); importing BoT-SORT stays free of reid / torch (isolation test).
• BoT-SORT wiring: appearance–IoU fusion, per-track feature bank, params reid_model, reid_ema_alpha, appearance_threshold, proximity_threshold.
• CLI: --tracker.reid.{enable,model,device,architecture} on trackers track (BoT-SORT only).
• Tests: association / fusion / CLI unit tests (no --extra reid required), @integration smoke with a real reid.ReIDModel, isolation test.
• Docs / notebook: 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.ipynb installs from PyPI.
• CI: unit (ci-tests.yml) syncs without --extra reid; integration (ci-integrations.yml) keeps --extra reid.

Pre-merge checklist

• Publish reid to PyPI (0.1.0.dev0).
• Swap the git pin in pyproject.toml to a PyPI range (reid>=0.1.0.dev0,<0.2) and refresh uv.lock.
• Resolve merge conflicts with develop (McByte / mask extras) so PR CI can run.
• Confirm integration CI is green with --extra reid (smoke should run, not skip).
• Refresh MOT17 / SoccerNet appearance-threshold docs figures (association-local sampling).
• pre-commit.ci green.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 27 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

notebooks/plot_reid_appearance_distances.py:18

• This example is not runnable: --dataset both enters the SoccerNet branch, which exits unless --soccernet-root is supplied. Include the required root here, as in the SoccerNet-only example.

  python notebooks/plot_reid_appearance_distances.py --dataset both

[Copilot]

Pull request overview

Copilot reviewed 27 out of 32 changed files in this pull request and generated no new comments.

Suppressed comments (6)

src/trackers/core/reid/thresholds.py:327

• An empty but shape-valid dataset leaves indexes empty, after which _draw_distances calls _split_quota(..., 0) and raises ZeroDivisionError instead of the documented ValueError. Reject zero rows before building the sequence indexes.

    unique_sequences = np.unique(sequence_ids)

src/trackers/core/reid/thresholds.py:412

• This catches every ValueError from sampling, not only the expected “no pairs in this band” case. Invalid gap bands, mismatched array lengths, and non-finite embeddings are consequently hidden as omitted bands or an empty sweep. Validate shared inputs outside the loop and/or use a dedicated no-pairs exception so genuine input errors still propagate.

        except ValueError:
            continue

src/trackers/core/reid/thresholds.py:330

• The API describes these values as identity and sequence labels, but coercing them to int rejects normal string labels and can merge distinct non-integer labels (for example, 1.2 and 1.8). Preserve the original hashable sequence values here and identity values in _SequenceIndex rather than coercing both to integers, or explicitly validate and document integer-only inputs.

        int(sequence): _SequenceIndex(np.flatnonzero(sequence_ids == sequence), ids, frame_ids)
        for sequence in unique_sequences

src/trackers/cli/track.py:746

• architecture is documented as requiring model, but this predicate ignores it. Passing only --reid.architecture therefore bypasses _load_reid_model, silently runs geometry-only tracking, and never raises the existing validation error. Treat a non-None architecture as a ReID request so that validation executes.

    return reid.enable or reid.model is not None

docs/cookbooks/how-to-add-reid-to-trackers.ipynb:226

• For a zero-based detection file, offset is -1, but max(offset, 0) turns it back into 0; frame 0 therefore remains frame 0 and never matches the tracking loop, which starts at 1. Subtract the signed offset directly so both zero- and one-based files align to frame 1.

                "        by_frame.setdefault(frame - max(offset, 0), []).append([x1, y1, x2, y2, score])\n",

src/trackers/core/reid/thresholds.py:208

• pairable_ids only means an identity has multiple crops overall, not that it has a valid partner in the requested gap band. When a selected identity/anchor has no partner, the whole draw is rejected and another identity is selected, so accepted samples are weighted by each identity’s success rate; dense tracks can dominate despite the documented uniform-per-identity sampling. Build the candidate identities and anchors for the active gap band first, then sample uniformly from valid candidates.

This issue also appears in the following locations of the same file:

• line 327
• line 329
• line 411

    if not index.pairable_ids:
        return None
    slots = index.slots_by_id[index.pairable_ids[int(rng.integers(len(index.pairable_ids)))]]
    anchor = int(slots[int(rng.integers(len(slots)))])
    window = index.window(index.frames[slots], int(index.frames[anchor]), minimum_frame_gap, maximum_frame_gap)
    partner_slot = _pick_in_window(rng, window)