feat(reid): add Deep OC-SORT adaptive appearance fusion

BoT-SORT fuses appearance by taking the minimum of the geometry and
appearance costs, gated by two fixed thresholds. Deep OC-SORT instead adds
a weighted appearance term whose weight grows when the best match stands
clear of the runner-up, which helps most in crowded scenes where a fixed
weight is either too timid or too aggressive.

Adds fuse_adaptive_reid_association alongside the existing fusion and a
reid_fusion selector on BoTSORTTracker, with reid_appearance_weight and
reid_adaptive_weight_cap for its two knobs. Default stays "botsort", so
behaviour is unchanged unless opted into.

Implements equations (4)-(6) of the paper, matching compute_aw_new_metric
in the authors' integrated_ocsort_embedding tracker (the variant behind
their published results) rather than the ratio-based variant that other
ports use.

Named for what it does rather than where it came from: only the adaptive
weighting is ported, onto a BoT-SORT base, without Dynamic Appearance, the
velocity term or OCR/OOS.

Two documented departures from the reference: negative cosine similarities
are clamped to zero, and appearance is gated by reid_proximity_threshold.
Deep OC-SORT drops implausible pairs after matching, but this integration
thresholds the fused similarity directly, so the gate has to happen during
fusion. The discriminativeness gap is measured across all candidates
before that gate is applied, so a candidate excluded on geometry cannot
read as similarity 0 and earn the bonus for being spatially alone.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: AlexBodner

src/trackers/core/botsort/tracker.py

@@ -4,7 +4,7 @@
 # Licensed under the Apache License, Version 2.0 [see LICENSE for details]
 # ------------------------------------------------------------------------
 
-from typing import ClassVar, cast
+from typing import ClassVar, cast, get_args
 
 import numpy as np
 import supervision as sv
@@ -17,7 +17,11 @@
 from trackers.core.reid.appearance import appearance_similarity, extract_detection_embeddings
 from trackers.core.reid.encoder import ReIDEncoder
 from trackers.core.reid.feature_bank import FeatureBank
-from trackers.core.reid.fusion import fuse_botsort_reid_association
+from trackers.core.reid.fusion import (
+    ReidFusionMethod,
+    fuse_adaptive_reid_association,
+    fuse_botsort_reid_association,
+)
 from trackers.utils.cmc import CMC, CMCConfig, CMCMethod
 from trackers.utils.detections import default_confidences
 from trackers.utils.iou import BaseIoU, IoU
@@ -95,11 +99,25 @@ class BoTSORTTracker(BaseTracker):
         reid_appearance_threshold: Appearance distance gate. Drops the appearance term
             when the halved cosine distance ``0.5 * (1 - cos_sim)`` exceeds this
             value, leaving the pair scored on geometry alone. Default ``0.25``
-            (BoT-SORT ``appearance_thresh``).
+            (BoT-SORT ``appearance_thresh``). Used by ``reid_fusion="botsort"``
+            only.
         reid_proximity_threshold: Standard-IoU distance gate applied before appearance
             is used. Computed from true IoU even when ``iou`` is GIoU/DIoU/CIoU.
             Default ``0.5`` (BoT-SORT ``proximity_thresh``; requires
             ``IoU >= 1 - reid_proximity_threshold``).
+        reid_fusion: How appearance is combined with geometry. ``"botsort"``
+            (default) takes the minimum of the geometry and appearance costs.
+            ``"adaptive"`` adds an adaptively weighted appearance term, which
+            weighs appearance more heavily when the best match stands clear of
+            the runner-up. The two produce different similarity ranges, so
+            ``minimum_iou_threshold_first_assoc`` needs retuning when switching
+            (see :func:`~trackers.core.reid.fusion.fuse_adaptive_reid_association`).
+        reid_appearance_weight: Base appearance weight for ``reid_fusion="adaptive"``.
+            Ignored otherwise. Default ``0.75``, the value Deep OC-SORT reports
+            for MOT17 and MOT20; they use ``1.25`` for DanceTrack.
+        reid_adaptive_weight_cap: Upper bound on the adaptive appearance bonus for
+            ``reid_fusion="adaptive"``. Ignored otherwise. Default ``0.5``, the value
+            Deep OC-SORT reports for MOT17 and MOT20; they use ``1.0`` for DanceTrack.
 
     Notes:
         - Positive `maximum_frames_without_update` values are scaled by
@@ -144,6 +162,9 @@ def __init__(
         reid_ema_alpha: float = 0.9,
         reid_appearance_threshold: float = 0.25,
         reid_proximity_threshold: float = 0.5,
+        reid_fusion: ReidFusionMethod = "botsort",
+        reid_appearance_weight: float = 0.75,
+        reid_adaptive_weight_cap: float = 0.5,
     ) -> None:
         self.maximum_frames_without_update = self._compute_maximum_frames_without_update(
             lost_track_buffer=lost_track_buffer,
@@ -176,6 +197,15 @@ def __init__(
             raise ValueError(f"reid_proximity_threshold must be in [0, 1], got {reid_proximity_threshold}")
         self.reid_appearance_threshold = reid_appearance_threshold
         self.reid_proximity_threshold = reid_proximity_threshold
+        if reid_fusion not in get_args(ReidFusionMethod):
+            raise ValueError(f"Unknown reid_fusion {reid_fusion!r}. Valid options are: {get_args(ReidFusionMethod)}.")
+        if reid_appearance_weight < 0.0:
+            raise ValueError(f"reid_appearance_weight must be non-negative, got {reid_appearance_weight}")
+        if reid_adaptive_weight_cap < 0.0:
+            raise ValueError(f"reid_adaptive_weight_cap must be non-negative, got {reid_adaptive_weight_cap}")
+        self.reid_fusion = reid_fusion
+        self.reid_appearance_weight = reid_appearance_weight
+        self.reid_adaptive_weight_cap = reid_adaptive_weight_cap
 
         self._init_timestamp_state(frame_rate)
 
@@ -432,7 +462,7 @@ def _association_similarity(
         scores: np.ndarray,
         embeddings: np.ndarray | None,
     ) -> np.ndarray:
-        """Score-fused association similarity, with optional BoT-SORT ReID fusion."""
+        """Score-fused association similarity, with optional ReID fusion."""
         iou_sim_raw = self.iou.normalize_for_fusion(self._get_iou_matrix(tracklets, boxes, tracklet_boxes_by_id))
         iou_sim_fused = _fuse_score(iou_sim_raw, scores)
         if embeddings is None or len(tracklets) == 0:
@@ -444,9 +474,19 @@ def _association_similarity(
             if isinstance(self.iou, IoU)
             else self._get_iou_matrix(tracklets, boxes, tracklet_boxes_by_id, metric=IoU())
         )
+        appearance = appearance_similarity(track_feats, embeddings, det_embeddings_normalized=True)
+        if self.reid_fusion == "adaptive":
+            return fuse_adaptive_reid_association(
+                iou_sim_fused,
+                appearance,
+                proximity_iou_similarity=proximity_iou,
+                reid_proximity_threshold=self.reid_proximity_threshold,
+                reid_appearance_weight=self.reid_appearance_weight,
+                reid_adaptive_weight_cap=self.reid_adaptive_weight_cap,
+            )
         return fuse_botsort_reid_association(
             iou_sim_fused,
-            appearance_similarity(track_feats, embeddings, det_embeddings_normalized=True),
+            appearance,
             proximity_iou_similarity=proximity_iou,
             reid_proximity_threshold=self.reid_proximity_threshold,
             reid_appearance_threshold=self.reid_appearance_threshold,

src/trackers/core/reid/fusion.py

@@ -8,6 +8,12 @@
 # Copyright (c) 2022 Nir Aharon
 # Source: https://github.com/NirAharon/BoT-SORT
 # Reference: tracker/bot_sort.py (ReID appearance-IoU cost fusion)
+#
+# Adapted from GerardMaggiolino/Deep-OC-SORT (MIT)
+# Copyright (c) 2023 Gerard Maggiolino
+# Source: https://github.com/GerardMaggiolino/Deep-OC-SORT
+# Reference: trackers/integrated_ocsort_embedding/association.py
+#            (compute_aw_new_metric, adaptive appearance weighting)
 # ------------------------------------------------------------------------
 
 """Appearance-IoU fusion methods for ReID association.
@@ -18,8 +24,12 @@
 
 from __future__ import annotations
 
+from typing import Literal
+
 import numpy as np
 
+ReidFusionMethod = Literal["botsort", "adaptive"]
+
 
 def fuse_botsort_reid_association(
     association_similarity: np.ndarray,
@@ -65,3 +75,91 @@ def fuse_botsort_reid_association(
     d_app = np.where(d_iou_proximity > reid_proximity_threshold, 1.0, d_app)
     fused_cost = np.minimum(d_iou, d_app)
     return 1.0 - fused_cost
+
+
+def _top_two_margin(similarity: np.ndarray, axis: int, cap: float) -> np.ndarray:
+    """Margin between the best and second-best similarity along ``axis``, capped.
+
+    A large margin means the best candidate stands clear of the rest, so appearance is discriminative for that row or
+    column. Zero when there are fewer than two candidates to compare.
+    """
+    if similarity.shape[axis] < 2:
+        return np.zeros(similarity.shape[1 - axis], dtype=float)
+    partitioned = np.partition(similarity, -2, axis=axis)
+    best = np.take(partitioned, -1, axis=axis)
+    runner_up = np.take(partitioned, -2, axis=axis)
+    return np.minimum(best - runner_up, cap)
+
+
+def fuse_adaptive_reid_association(
+    association_similarity: np.ndarray,
+    appearance_similarity: np.ndarray,
+    *,
+    reid_appearance_weight: float,
+    reid_adaptive_weight_cap: float,
+    reid_proximity_threshold: float,
+    proximity_iou_similarity: np.ndarray | None = None,
+) -> np.ndarray:
+    """Fuse IoU and appearance with Deep OC-SORT's adaptive weighting.
+
+    Adds a weighted appearance term to the geometric similarity instead of
+    taking a minimum. The weight grows when the best appearance match stands
+    clear of the runner-up and falls back to ``reid_appearance_weight`` when
+    the top candidates are hard to tell apart.
+
+    Implements equations (4)-(6) of the Deep OC-SORT paper, matching
+    ``compute_aw_new_metric`` in the authors' ``integrated_ocsort_embedding``
+    tracker, the variant behind their published results.
+
+    ``proximity_iou_similarity`` is the standard-IoU gate (defaults to
+    ``association_similarity``). Pass it separately when association uses
+    GIoU/DIoU/CIoU so proximity still uses plain IoU.
+
+    Args:
+        association_similarity: Geometry-based track-detection similarities with
+            shape ``(T, N)``.
+        appearance_similarity: Cosine similarities for the same pairs with shape
+            ``(T, N)``.
+        reid_appearance_weight: Base appearance weight, ``a_w`` in the paper.
+            The authors report ``0.75`` for MOT17 and MOT20 and ``1.25`` for
+            DanceTrack.
+        reid_adaptive_weight_cap: Upper bound on the adaptive bonus, ``epsilon``
+            in the paper. The authors report ``0.5`` for MOT17 and MOT20 and
+            ``1.0`` for DanceTrack.
+        reid_proximity_threshold: Maximum standard-IoU distance at which
+            appearance may contribute.
+        proximity_iou_similarity: Standard-IoU similarities with shape ``(T, N)``.
+            Defaults to ``association_similarity``.
+
+    Returns:
+        Fused track-detection similarities with shape ``(T, N)``, spanning
+        ``[0, 1 + reid_appearance_weight + reid_adaptive_weight_cap]``.
+        Association thresholds tuned against the BoT-SORT fusion do not carry
+        over and need retuning.
+
+    Notes:
+        Negative cosine similarities are clamped to zero, so appearance can
+        only ever raise a similarity. Appearance is gated by
+        ``reid_proximity_threshold``; Deep OC-SORT instead drops implausible
+        pairs after matching, but this integration thresholds the fused
+        similarity directly, so the gate has to apply here. The gate applies
+        only to the appearance term: the margin is measured over all
+        candidates, as in the reference, so a candidate excluded on geometry
+        cannot read as similarity ``0`` and widen the margin.
+
+        The velocity-direction term of the full Deep OC-SORT cost is not
+        included; it belongs to OC-SORT's motion model.
+    """
+    if proximity_iou_similarity is None:
+        proximity_iou_similarity = association_similarity
+
+    appearance = np.clip(appearance_similarity, 0.0, None)
+
+    track_margin = _top_two_margin(appearance, axis=1, cap=reid_adaptive_weight_cap)
+    detection_margin = _top_two_margin(appearance, axis=0, cap=reid_adaptive_weight_cap)
+    adaptive_bonus = (track_margin[:, np.newaxis] + detection_margin[np.newaxis, :]) / 2.0
+
+    out_of_range = (1.0 - proximity_iou_similarity) > reid_proximity_threshold
+    gated_appearance = np.where(out_of_range, 0.0, appearance)
+
+    return association_similarity + (reid_appearance_weight + adaptive_bonus) * gated_appearance