Track Objects (BoT SORT)

@pipelogic1 VersionTrack

BoT-SORT multi-object tracker over per-frame [BoundingBox] or [Segmentation]. A ByteTrack-style two-stage IoU association keeps low-confidence detections instead of discarding them, a Kalman motion model predicts each track, and a per-frame camera-motion estimate warps prior boxes so global camera movement does not break the match. Emits one active-track list per frame, not per box.

How it fits

Typical backends

Tracked detections with trajectories into zone-transition logic.

Counted, tracked detections summarised over HTTP.

Instance-mask tracking - segmentations in, mask-bearing tracks out.

Re-id chain over long occlusions into a tracked-object summariser.

Caveats

I/O contractOutput is track-centric. Each frame emits the set of active CONFIRMED tracks, so the count is the number of live tracks, not the number of input detections.
I/O contractThe [TrackedSegmentation] output arm is only selectable when the input is [Segmentation]; the carried mask comes from the input. With [BoundingBox] input it cannot be resolved and the worker errors at startup.
I/O contractThe [Track] arm is the only one that fills each track's trajectory of past centre points.
Parameter interactionTwo-stage association keeps weaker detections for a second pass against still-unmatched tracks, recovering an occluded object on a low-confidence frame instead of losing its id. track_thresh is the high/low split and the floor for starting a new track.
Parameter interactionmatch_thresh is the IoU-distance gate; before it is applied, prior track boxes are warped by an estimated inter-frame camera transform, so panning or shaking cameras keep their IoU overlap. This camera-motion compensation is what distinguishes BoT-SORT from plain ByteTrack.
State lifetimeA new track is tentative until matched on min_hits consecutive frames, then confirmed and emitted. A confirmed track unmatched for up to track_buffer frames coasts on its Kalman prediction; after that it is dropped and its id is never reused. State is in-process; a restart resets all ids.
AccuracyAssociation uses IoU + Kalman motion + camera-motion compensation, with no appearance model in the default path. Add reidentify_objects_torchreid downstream when ids must survive long occlusions or identical-looking objects crossing.
Parameter interactionclass_agnostic false (default) forbids a class-A track from absorbing a class-B detection; set true only for single-class detectors or when the upstream class id is unreliable.

Versions

f3a5c5falatestdefault
Automated release
8/7/2026