trackers Files

📋 Summary

trackers v2.6.0 adds McByteTracker, a new mask-conditioned tracker that extends BoT-SORT-style association with SAM/Cutie temporal segmentation masks as an extra matching cue. It also adds dynamic frame rate support (timestamp= on update()) for all six trackers, tightens track-lifecycle validation with two breaking changes, fixes nine correctness bugs, and hardens ZIP extraction against path traversal (CWE-22).

https://github.com/user-attachments/assets/e2683415-f4b7-4862-8e60-8cd2431d19dd

✨ Spotlights / highlights

McByteTracker

:::python
from trackers import McByteTracker

tracker = McByteTracker()

Mask-conditioned association via SAM (box→mask) + Cutie (temporal mask propagation), opt-in via pip install trackers[mask]. Default enable_mask_manager=False runs ByteTrack-parity with no extra weights required.

Dynamic frame rate via timestamp=

:::python
tracker.update(detections, frame, timestamp=frame_wallclock_seconds)

Elapsed wall-clock seconds convert into Kalman frame units; omitting timestamp preserves the existing fixed-rate behavior.

Breaking: stricter lifecycle validation

:::python
# Before: silently accepted
tracker = SORTTracker(lost_track_buffer=-1)

# After: raises ValueError
tracker = SORTTracker(lost_track_buffer=-1)
# ValueError: lost_track_buffer must be greater than or equal to 0

Tracker performance improvements

CMC's sparse optical-flow status filter is now vectorized (~24x on that op); KalmanMotionModel caches transition/noise matrices and defers DWNA calibration (~38% lower BoT-SORT/CBIoU predict cost).

Security: hardened ZIP extraction

Dataset-download ZIP extraction rejects archive members with absolute paths, traversal segments, or Windows backslash paths (Zip Slip / CWE-22).

🔄 Migration guide

Breaking changes

lost_track_buffer / frame_rate now validated

SORTTracker, ByteTrackTracker, OCSORTTracker, BoTSORTTracker, and CBIoUTracker (which forwards its constructor args to BoTSORTTracker) now raise ValueError at construction if lost_track_buffer is negative or frame_rate is not finite and positive.

:::python
# Before (v2.5.0) — silently accepted
tracker = SORTTracker(lost_track_buffer=-1)

# After (v2.6.0) — raises immediately
tracker = SORTTracker(lost_track_buffer=-1)
# ValueError: lost_track_buffer must be greater than or equal to 0

lost_track_buffer=0 remains valid (no missed-frame grace period).

Missed-frame boundary is now inclusive

Confirmed tracks now survive one additional missed frame — comparison changed from time_since_update < maximum_frames_without_update to time_since_update <= maximum_frames_without_update (the frame-rate-scaled form of lost_track_buffer), matching OC-SORT's prior behavior. Expect small IDSW/HOTA shifts when comparing metrics across versions.

Behavior changes (non-breaking)

Unmatched sub-activation-threshold detections are now emitted

ByteTrackTracker, BoTSORTTracker, and CBIoUTracker.update() now return detections between the two confidence thresholds (below track_activation_threshold but above high_conf_det_threshold) with tracker_id=-1 instead of dropping them.

:::python
result = tracker.update(detections)
matched = result[result.tracker_id != -1]

Deprecations (removed in v3.0) — unchanged since the last release

• SORTTracker.trackers → .tracks
• trackers.core.botsort.cmc → trackers.utils.cmc
• CMCTMethod → CMCMethod
• CMC.apply_to_xyxy → CMC.warp_xyxy_corners

📝 Notable changes

🚀 Added

• McByteTracker — mask-conditioned tracker combining SAM box-mask generation and Cutie mask propagation with BoT-SORT-style association; exported from trackers along with McByteMaskConfig. New trackers[mask] extra (torch, torchvision, rf-segment-anything, rf-cutie[inference]; rf-cutie now ships on PyPI instead of git). Device selection defaults to "auto" (CUDA → MPS → CPU). Frames are expected in RGB (other trackers expect BGR). (#388, [#418], [#441], [#452], [#459], [#481], [#491], [#508], [#513], [#519]–#526, [#529], [#532])
• Optional timestamp= on BaseTracker.update() — all six trackers convert elapsed wall-clock seconds into Kalman frame units and prune lost tracks on a seconds budget. (#446)
• KalmanMotionModel in trackers.utils.motion_models — supplies Kalman F/Q for a given frame_step.

⚠️ Breaking Changes

• Invalid lost-track buffer settings now raise ValueError — lost_track_buffer must be non-negative and frame_rate finite and positive across all five classic trackers (SORT, ByteTrack, OC-SORT, BoT-SORT, CBIoU). (#420)
• Confirmed tracks now survive one additional missed frame — boundary changed from exclusive to inclusive to match OC-SORT. (#420)

🌱 Changed

• Improved tracker performance (bit-identical output) — CMC status-filter vectorized (~24x), KalmanMotionModel caches matrices (~38% lower BoT-SORT/CBIoU predict cost), predicted boxes cached across association stages, KF-copy trimming. (#522, [#527], [#528])
• Build backend migrated hatchling → setuptools (src-layout + py.typed); direct dependency constraint pydeprecate>=0.7.0 raised to >=0.8.0. (#492)

🔧 Fixed

• Positive low-FPS lost-track buffers no longer collapse to zero frames. (#420)
• BoT-SORT/CBIoU: instant-activated first-frame tracks no longer dropped on a single miss. (#478, [#504])
• ByteTrack/BoT-SORT/CBIoU now return unmatched detections between the two confidence thresholds instead of silently dropping them. (#475)
• Signed IoU variants (CIoU/DIoU/GIoU) clamped to [0, 1] before score fusion. (#476)
• OC-SORT: Kalman scale kept positive across frame-step gaps. (#509)
• CMC: handle mid-stream frame-resolution changes in optical-flow motion estimation. (#505)
• CMC: fixed cv2.resize crash on tiny downscaled images. (#488)
• xcycsr_to_xyxy: prevent zero-division on zero-aspect boxes. (#485)
• Video output resized on mid-stream resolution change. (#514)
• Package builds fixed for src layout. (#492)

🔒 Security

• Hardened ZIP extraction against Zip Slip / path traversal (CWE-22). (#495)

---

🏆 Contributors

• Agis Kounelis (@kounelisagis) — ByteTrack fix: return unmatched detections between the two confidence thresholds instead of dropping them.
• Alexander Bodner (@AlexBodner, LinkedIn) — dynamic frame-rate integration.
• Christoph Deil (@cdeil, LinkedIn) — unified lost-track buffer semantics across all trackers.
• Jesús Royeth (@JESUSROYETH) — McByte miss-clock timing, video output resize fix, OC-SORT Kalman scale fix.
• Jirka Borovec (@Borda, LinkedIn) — McByte MPS device support + Cutie streaming config, mask-pipeline public API export, package build/publish fix.
• Ruben Haisma (@RubenHaisma, LinkedIn) — BoT-SORT instant-activated track fix, IoU signed-variant fusion clamp.
• S B Pranay (@pranaysb) — CMC resize-crash fix, xcycsr_to_xyxy zero-division fix.
• Tomasz Stańczyk (@tstanczyk95, LinkedIn) — McByte tracker end-to-end: skeleton, dynamic Cutie mask lifecycle management, mask-conditioned association.

---

Full changelog: https://github.com/roboflow/trackers/compare/2.5.0...2.6.0