releasing 2.6.0

[Borda]

v2.6.0: McByte and dynamic frame rate

📋 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).

✨ Spotlights / highlights

McByteTracker

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=

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

# 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.

# 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.

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

📝 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).
  ([McByte part 1] Add McByte tracker skeleton #388, [McByte part 2] Feat/mcbyte mask manager #418, [McByte part 3] Add SAM box mask generator #441, [McByte part 4] Add Cutie mask propagator #452, [McByte part 5] Add dynamic mask lifecycle support for Cutie #459, [McByte part 6] Mask manager lifecycle wiring #481, [McByte part 7] Mask manager delayed mask creation #491, [McByte part 8] Complete McByte with mask-conditioned association #508, feat: McByteTracker [rebase & merge] #513, docs(mcbyte): schema figures, mask scoring, tuning #519–perf(mcbyte): default-off precision/compile knobs #526, feat(mcbyte): defer short-lived mask creation #529, fix(mcbyte): advance the miss clocks from the predict timing #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. (Feat/dynamic frame rate integration #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). (Unify lost track buffer semantics #420)
• Confirmed tracks now survive one additional missed frame — boundary changed from exclusive
  to inclusive to match OC-SORT. (Unify lost track buffer semantics #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. (feat(mcbyte): MPS support + Cutie streaming cfg #522, perf(kf): trim KF copies + OCSORT assoc hygiene #527, perf(assoc): cache predicted boxes across stages #528)
• Build backend migrated hatchling → setuptools (src-layout + py.typed); direct dependency
  constraint pydeprecate>=0.7.0 raised to >=0.8.0. (fix(pkg,ci): building package #492)

🔧 Fixed

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

🔒 Security

• Hardened ZIP extraction against Zip Slip / path traversal (CWE-22). (fix(utils): harden zip extraction #495)

---

🏆 Contributors

• Agis Kounelis (@kounelisagis) — ByteTrack fix: return unmatched detections between the two
  confidence thresholds instead of dropping them.
• Alexander Bodner (@AlexBodner) — dynamic frame-rate integration.
• Christoph Deil (@cdeil) — 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) — McByte MPS device support + Cutie streaming config, mask-pipeline
  public API export, package build/publish fix.
• Ruben (@RubenHaisma) — 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.

---

01_side_by_side.mp4

03_moment_of_decision.mp4

04_how_the_mask_decides.mp4

---

Full changelog: 2.5.0...2.6.0