botsort_persistent.yaml

# BoT-SORT + ReID: upgrade from bytetrack_persistent.yaml to fix track-ID
# swapping when two people/vehicles cross paths or pass close together.
# Plain ByteTrack (see ultralytics/trackers/byte_tracker.py's
# BYTETracker.get_dists) associates using ONLY IoU distance between
# Kalman-predicted boxes and new detections -- no appearance information at
# all, so overlapping predicted boxes during a crossing can swap which
# detection feeds which track. BoT-SORT adds a cosine-similarity appearance
# (ReID) distance fused with IoU, which should tell two crossing objects
# apart even when their boxes overlap.
tracker_type: botsort
track_high_thresh: 0.25
track_low_thresh: 0.1
new_track_thresh: 0.6      # same as bytetrack_persistent.yaml: don't casually mint new IDs
track_buffer: 150          # same as bytetrack_persistent.yaml: ~5s @ 30fps occlusion tolerance
match_thresh: 0.9          # same as bytetrack_persistent.yaml: looser IoU/motion gate re-links lost tracks
fuse_score: True

# camera is fixed/elevated with no pan-tilt-zoom -- skip motion compensation
# entirely rather than paying for optical-flow/feature-matching compute that
# a static rig doesn't need.
gmc_method: none

# ReID: the actual fix for crossing-path ID swaps.
with_reid: True
# Tried yolov8n-cls.pt here instead of "auto" for a real appearance
# embedding (a detector's own features are optimized for localization, not
# identity). Reverted: in the installed ultralytics version (8.4.62),
# ultralytics/trackers/bot_sort.py's ReID class always runs its model on
# CPU with one unbatched forward pass per detected object per frame,
# regardless of device= elsewhere -- with multiple objects in frame this
# tanked throughput to a small fraction of real-time. "auto" reuses the
# main detector's already-computed (GPU/MPS) features for free instead, so
# no separate model/CPU bottleneck. Revisit if a future ultralytics version
# makes ReID device-aware.
model: auto
# lowered from 0.5 (Ultralytics default): consult ReID appearance as soon as
# boxes start to converge, not only once they're already heavily
# overlapping -- catches a swap forming right at the crossing moment instead
# of after. If this starts pulling in spurious appearance matches for
# far-apart boxes, raise back toward 0.5.
proximity_thresh: 0.35
appearance_thresh: 0.8 # cosine-similarity floor to accept a ReID match -- matches default; raise if swaps persist

# Other packaged (config-only, no code changes) knobs worth trying if swaps
# persist, roughly in order of expected relevance to swaps specifically
# (as opposed to track drops, which this file already tunes for):
#   - appearance_thresh: already at Ultralytics' default (0.8), which is
#     already stricter than common community starting points (~0.25-0.3) --
#     limited headroom to raise further before legit re-links start failing.
#     Since ReID here runs on reused detector features (see `model: auto`
#     above) rather than a dedicated embedding, the bottleneck is more
#     likely embedding quality than this threshold.
#   - match_thresh (currently 0.9, loosened from 0.8 default): loosening
#     this helps re-link tracks after occlusion (drops) but by the same
#     mechanism makes it easier for the WRONG nearby detection to satisfy a
#     match during a crossing (swaps) -- tightening back toward 0.8 would
#     trade some drop-resistance for swap-resistance if swaps still show up
#     with clean ReID separation already failing.
#   - track_buffer (currently 150, up from 30 default): same drop/swap
#     tension as match_thresh -- a long buffer keeps lost tracks alive
#     longer, which is more opportunity for a wrong re-link. Only worth
#     lowering if swaps trace to stale long-lost tracks getting re-matched,
#     not fresh crossings.
#   - track_high_thresh / track_low_thresh (0.25 / 0.1, both untouched
#     Ultralytics defaults): gate which detections even reach matching;
#     mostly affect drops/fragmentation rather than swap direction, so low
#     priority for this specific problem.
#   - new_track_thresh (currently 0.6, up from 0.25 default): already raised
#     so a low-confidence detection during a crossing is tested against
#     existing tracks before minting a new ID -- this is part of what
#     prevents "swap picked up as new ID" double-counts. Already well-tuned.