v2.4.0: BoT-SORT & hyperparameter tuning

📋 Summary

trackers 2.4.0 ships the fourth tracker — BoT-SORT, built around camera motion compensation (CMC) — alongside a first-class hyperparameter tuning workflow, a unified Kalman implementation shared by all trackers, and a tracked_objects property on every tracker that exposes alive tracks even through occlusions.

All existing tracker.update(detections) calls continue to work without changes. One true breaking change: SORTTracker.update() no longer assigns tracker_id on the input object — read it from the returned value. Spawn order is now deterministic. See the Migration guide and Behaviour shifts below.

botsort_demo_sportsmot_03_train_v_2j7kLB-vEEk_c005_h264.mp4

✨ Spotlights

🎯 BoT-SORT tracker

BoT-SORT is designed for footage where the camera itself moves — handheld, drone, sport. Camera motion compensation (CMC) is what makes BoT-SORT distinct: it estimates the inter-frame homography and corrects Kalman predictions before association, so stationary subjects stay stationary in track coordinates even when the camera pans. CMC is on by default (enable_cmc=True); set enable_cmc=False only when the camera is fixed, though at that point BoT-SORT reduces to a ByteTrack variant with a different Kalman state estimator. Four CMC backends: sparseOptFlow (default), orb, sift, ecc. (#386)

Algorithm	MOT17 HOTA	SportsMOT HOTA	SoccerNet HOTA	DanceTrack val HOTA
SORT	58.4	70.8	81.6	45.0
ByteTrack	60.1	73.0	84.0	50.2
OC-SORT	61.9	71.7	78.4	51.8
BoT-SORT	63.7	73.8	84.5	50.5

MOT17 and SportsMOT use YOLOX detections. SoccerNet and DanceTrack use oracle (ground-truth) detections.

Note: Pass the raw video frame as the second argument to BoTSORTTracker.update() when CMC is enabled (the default). Without it, CMC silently no-ops and Kalman predictions may diverge. Existing calls to SORT, ByteTrack, and OC-SORT without frame are unaffected.

from trackers import BoTSORTTracker

tracker = BoTSORTTracker(
    track_activation_threshold=0.7,
    high_conf_det_threshold=0.6,
    enable_cmc=True,
    cmc_method="sparseOptFlow",  # "orb" | "sift" | "sparseOptFlow" | "ecc"
)

for frame in frames:
    detections = model(frame)
    tracked = tracker.update(detections, frame)  # frame required when enable_cmc=True

CLI: trackers track --tracker botsort ... — discoverable automatically.

⚙️ Hyperparameter tuning

Each tracker now declares a search_space ClassVar. Tuner uses Optuna — a Bayesian hyperparameter optimisation framework — to sample from that space, runs the tracker over MOT sequences with pre-computed detections, evaluates with HOTA / MOTA / IDF1, and returns the best parameter set. (#301, #374)

from trackers.tune import Tuner

tuner = Tuner(
    tracker_id="bytetrack",
    gt_dir="data/gt/",
    detections_dir="data/det/",
    objective="HOTA",
    n_trials=100,
)
best_params = tuner.run()

trackers tune --tracker bytetrack \
    --gt-dir data/gt/ --detections-dir data/det/ \
    --objective HOTA --n-trials 200

👁️ tracked_objects — every confirmed track, including between detections

tracker.update(detections) returns only the tracks matched to a detection on the current frame. The new tracked_objects property returns every confirmed track still alive in the buffer, including those not matched on this frame — subjects temporarily occluded or skipped by the detector. Boxes come from the Kalman state (get_state_bbox()), not from a detection, so position may drift slightly for unmatched tracks.

Tracks stay in the result until time_since_update exceeds lost_track_buffer frames (scaled by frame_rate). After that they are pruned and will not appear in tracked_objects.

confidence and class_id are None on this result — sv.LabelAnnotator and other annotators that read those fields will raise TypeError unless guarded. (#373)

tracked = tracker.update(detections, frame)  # matched this frame only
alive = tracker.tracked_objects  # all confirmed alive tracks

# guard before using supervision annotators:
if alive.class_id is not None:
    frame = label_annotator.annotate(frame, alive, ...)

🔄 Migration guide

✏️ SORTTracker.update() no longer assigns tracker_id on the input object

SORTTracker previously wrote tracker_id directly onto the caller's sv.Detections object and returned that same instance. It now returns a fresh indexed copy — matching ByteTrack and OC-SORT. Code that read detections.tracker_id after calling tracker.update(detections) without using the return value will now get None. (#360)

# Before (v2.3.0) — tracker_id written back to input
tracker.update(detections)
print(detections.tracker_id)  # worked (aliased)

# After (v2.4.0) — read from returned value
tracked = tracker.update(detections)
print(tracked.tracker_id)

🔀 Behaviour shifts

These changes affect reproducibility or numerical outputs but do not break correct usage of the public API.

🔢 Spawn order is now deterministic

Track IDs assigned to detections that spawn in the same frame are now sorted rather than dependent on CPython set iteration order — reproducible across machines and Python versions for the first time. One-time impact: re-record any raw ID baselines compared against v2.3.0. (#361)

📝 Notable changes

🚀 Added

• BoT-SORT tracker (BoTSORTTracker) — camera-motion-aware tracker with CMC on by default (enable_cmc=True), configurable backends (sparseOptFlow, orb, sift, ecc), and three-stage score-fused association. (#386)
• tracked_objects property on BaseTracker — returns every confirmed alive track (within lost_track_buffer) with Kalman-predicted boxes, not just tracks matched on the current frame. confidence and class_id are None; guard before using supervision annotators. (#373)
• Tuner class (trackers.tune.Tuner) — Optuna-based hyperparameter optimisation with HOTA / MOTA / IDF1 objectives over MOT ground-truth and pre-computed detections. (#301)
• trackers tune CLI subcommand — wires Tuner into the CLI. (#374)
• load_mot_file is now public — exported from trackers.io.mot for custom evaluation and tuning scripts. (#301, #374)
• frame parameter on BaseTracker.update() — update(detections, frame=None). Required by BoT-SORT with CMC enabled; SORT/ByteTrack/OC-SORT emit UserWarning if frame is provided but not used. (#386)
• Swappable Kalman state estimators — BaseStateEstimator, XCYCWHStateEstimator, XCYCSRStateEstimator, XYXYStateEstimator in trackers.utils.state_representations. (#310)
• search_space ClassVar on every tracker — declarative hyperparameter spaces consumed by Tuner. (#301)
• TrackletProtocol structural type — formalises the tracklet contract used by BaseTracker.tracks.
• Modern Python 3.10+ type hints across the public surface. (#302)

⚠️ Impactful Changes

• SORTTracker.update() no longer assigns tracker_id on the input object — previously wrote tracker_id onto the caller's sv.Detections in-place; now returns a fresh indexed copy. Code reading detections.tracker_id without using the return value will get None. (#360)

🌱 Changed

• Kalman filter refactored out of tracklet classes — all trackers share one implementation via BaseStateEstimator. Tracklet classes handle association and lifecycle only. (#310)
• ByteTrack tracklets now count number_of_successful_consecutive_updates instead of total number_of_updates, matching the original paper; public API and numerical outputs unchanged. (#310, #376)
• Spawn order is now deterministic across CPython versions — IDs reproducible across machines for the first time; re-record baselines from v2.3.0. (#361)
• Eval submodule uses lazy __getattr__ for evaluate_mot_sequence to avoid circular imports.
• For unmatched tracks, time_since_update now increments inside predict() rather than via an explicit tracklet.update(None) call. Custom OCSORTTracklet subclasses that overrode update() to handle None detections must move that logic into predict(). (#383)

🔧 Fixed

• ByteTrack: unmatched tracks now expire correctly — time_since_update advances on unmatched tracks and _get_alive_tracklets respects lost_track_buffer. (#376)
• Evaluation distractor filtering corrected on benchmark comparison numbers.
• ByteTrack documentation correction. (#371)

---

🏆 Contributors

This release is brought to you by five community contributors and the maintainer team.

• Tomasz Stańczyk (@tstanczyk95) (LinkedIn) — original BoT-SORT implementation and supervision integration
• Alexander Bodner (@AlexBodner) (LinkedIn) — BoT-SORT refactoring, Kalman filter unification, OC-SORT tracklet adaptation
• Omkar Kabde (@omkar-334) (LinkedIn) — Tuner class, tune CLI, tracked_objects, ByteTrack fix, type hints
• Christoph Deil (@cdeil) (LinkedIn) — deterministic spawn order, SORT input-mutation fix
• Piotr Skalski (@SkalskiP) (LinkedIn) — BoT-SORT branch integration, docs rewrite, comparison page expansion
• Jirka Borovec (@Borda) (LinkedIn) — release engineering, tooling, docs infrastructure

Automated contributions: @dependabot, @pre-commit-ci, @copilot-swe-agent

---

Full changelog: 2.3.0...2.4.0