Trackers API

SORT

`trackers.core.sort.tracker.SORTTracker`

Bases: BaseTracker

In SORT, object tracking begins with high-confidence detections fed into a Kalman filter framework assuming uniform motion for state prediction across frames. Association occurs via IoU-based costs in the Hungarian algorithm, enforcing a threshold to filter weak matches and initialize new identities. Tracks persist only with consistent associations, terminating quickly to avoid erroneous propagation. This detection-driven approach underscores the importance of upstream detector performance in achieving competitive multi-object tracking results. Over time, SORT has become a cornerstone for evaluating motion-based improvements in the field.

SORT's standout strength is its real-time capability, processing hundreds of frames per second while maintaining accuracy comparable to more complex offline methods. It performs well in controlled environments with reliable detections, minimizing computational demands. However, without mechanisms for re-identification, it incurs frequent identity switches during object reappearances post-occlusion. The linear motion assumption limits effectiveness in non-linear paths, such as those in sports or wildlife tracking. Ultimately, SORT's efficiency is offset by its sensitivity to environmental complexities, necessitating hybrid extensions for broader applicability.

Parameters:

Name	Type	Description	Default
`lost_track_buffer`	`int`	`int` specifying number of frames to buffer when a track is lost. Increasing this value enhances occlusion handling but may increase ID switching for similar objects.	`30`
`frame_rate`	`float`	`float` specifying video frame rate in frames per second. Used to scale the lost track buffer for consistent tracking across different frame rates.	`30.0`
`track_activation_threshold`	`float`	`float` specifying minimum detection confidence to create new tracks. Higher values reduce false positives but may miss low-confidence objects.	`0.25`
`minimum_consecutive_frames`	`int`	`int` specifying number of consecutive frames before a track is considered valid. Before reaching this threshold, tracks are assigned `tracker_id` of `-1`.	`3`
`minimum_iou_threshold`	`float`	`float` specifying IoU threshold for associating detections to existing tracks. Higher values require more overlap.	`0.3`
`state_estimator_class`	`type[BaseStateEstimator]`	State estimator class to use for Kalman filter. `XCYCSRStateEstimator` for center-based representation or `XYXYStateEstimator` for corner-based representation.	`XYXYStateEstimator`
`iou`	`BaseIoU \| None`	IoU similarity metric instance to use for data association. Defaults to standard `IoU`. Can be replaced with any `BaseIoU` subclass (e.g. GIoU, DIoU, CIoU) to change how bounding-box similarity is computed during the association step. Passing `None` (the default) is equivalent to `IoU()` and is provided for backward compatibility with existing code that did not supply an `iou` argument.	`None`

`trackers` `property`

Deprecated alias for :attr:tracks.

.. deprecated:: 2.5 Use :attr:tracks instead. Will be removed in v3.0.

`update(detections, frame=None)`

Update tracker state with new detections and return tracked objects. Performs Kalman filter prediction, IoU-based association, and initializes new tracks for unmatched high-confidence detections.

Parameters:

Name	Type	Description	Default
`detections`	`Detections`	`sv.Detections` containing bounding boxes with shape `(N, 4)` in `(x_min, y_min, x_max, y_max)` format and optional confidence scores.	required
`frame`	`ndarray \| None`	Ignored by SORT. If provided (not `None`), a warning is emitted.	`None`

Returns:

Type	Description
`Detections`	sv.Detections with tracker_id assigned for each detection.
`Detections`	Unmatched or immature tracks have tracker_id of -1.

`reset()`

Reset tracker state by clearing all tracks and resetting ID counter. Call this method when switching to a new video or scene.

ByteTrack

`trackers.core.bytetrack.tracker.ByteTrackTracker`

Bases: BaseTracker

ByteTrack operates online by processing all detector outputs, categorizing them by confidence thresholds to enable a two-stage association process. High-score boxes are initially linked to tracklets via Kalman filter predictions and IoU-based Hungarian matching, optionally enhanced with appearance features. Low-score boxes follow in a secondary matching phase using pure motion similarity to revive occluded tracks. Tracks without matches are kept briefly for potential re-association, preventing premature termination. This inclusive approach addresses common pitfalls in detection filtering, establishing ByteTrack as a flexible enhancer for existing tracking frameworks.

ByteTrack excels in dense environments, where its low-score recovery mechanism minimizes missed detections and enhances overall trajectory completeness. It consistently improves performance across diverse datasets, demonstrating robustness and generalization. The tracker's speed remains competitive, facilitating integration into production pipelines. On the downside, it is highly dependent on detector quality, with performance drops in noisy or low-resolution inputs. Additionally, the motion-only secondary association may lead to erroneous matches in scenes with similar moving objects.

Note

When input detections carry no confidence (detections.confidence is None), ByteTrack falls back to a single-stage IoU match equivalent to SORT — every detection is treated as fully confident, so the low-confidence recovery stage is bypassed. Pass per-detection confidences to exercise the two-stage matching this class otherwise provides.

Parameters:

Name	Type	Description	Default
`lost_track_buffer`	`int`	`int` specifying number of frames to buffer when a track is lost. Increasing this value enhances occlusion handling but may increase ID switching for disappearing objects.	`30`
`frame_rate`	`float`	`float` specifying video frame rate in frames per second. Used to scale the lost track buffer for consistent tracking across different frame rates.	`30.0`
`track_activation_threshold`	`float`	`float` specifying minimum detection confidence to create new tracks. Higher values reduce false positives but may miss low-confidence objects.	`0.7`
`minimum_consecutive_frames`	`int`	`int` specifying number of consecutive frames before a track is considered valid. Before reaching this threshold, tracks are assigned `tracker_id` of `-1`.	`2`
`minimum_iou_threshold`	`float`	`float` specifying IoU threshold for associating detections to existing tracks. Higher values require more overlap.	`0.1`
`high_conf_det_threshold`	`float`	`float` specifying threshold for separating high and low confidence detections in the two-stage association.	`0.6`
`state_estimator_class`	`type[BaseStateEstimator]`	State estimator class to use for Kalman filter. Defaults to `XYXYStateEstimator`. Can also use `XCYCSRStateEstimator` for center-based representation.	`XYXYStateEstimator`
`iou`	`BaseIoU \| None`	IoU similarity metric instance to use for data association. Defaults to standard `IoU`. Can be replaced with any `BaseIoU` subclass (e.g. GIoU, DIoU, CIoU) to change how bounding-box similarity is computed during the association step. Passing `None` (the default) is equivalent to `IoU()` and is provided for backward compatibility with existing code that did not supply an `iou` argument.	`None`

`update(detections, frame=None)`

Update tracks state with new detections and return tracked objects. Performs Kalman filter prediction, two-stage association (high then low confidence), and initializes new tracks for unmatched detections.

Parameters:

Name	Type	Description	Default
`detections`	`Detections`	`sv.Detections` containing bounding boxes with shape `(N, 4)` in `(x_min, y_min, x_max, y_max)` format and optional confidence scores. When `detections.confidence is None`, all detections are treated as confidence `1.0` — they bypass the low-confidence stage and any unmatched boxes can spawn new tracks regardless of `track_activation_threshold`.	required
`frame`	`ndarray \| None`	Ignored by ByteTrack. If provided (not `None`), a warning is emitted.	`None`

Returns:

Type	Description
`Detections`	sv.Detections with tracker_id assigned for each detection.
`Detections`	Unmatched detections have tracker_id of -1. Detection order may
`Detections`	differ from input.

`reset()`

Reset tracker state by clearing all tracks and resetting ID counter. Call this method when switching to a new video or scene.

OC-SORT

`trackers.core.ocsort.tracker.OCSORTTracker`

Bases: BaseTracker

OC-SORT enhances traditional SORT by shifting to an observation-centric paradigm, using detections to correct Kalman filter errors accumulated during occlusions. It introduces Observation-Centric Re-Update to generate virtual trajectories for parameter refinement upon track reactivation. Association incorporates Observation-Centric Momentum, blending IoU with direction consistency from historical observations. Short-term recoveries are aided by heuristics linking unmatched tracks to prior detections. This rethinking prioritizes real measurements over estimations, making OC-SORT particularly adept at handling real-world tracking challenges.

OC-SORT's primary strength is its robustness to non-linear motions and occlusions, outperforming baselines on datasets with erratic movements like DanceTrack. It maintains extreme efficiency, processing over 700 frames per second on CPUs for scalable deployments. The tracker excels in crowded scenes, reducing identity switches through momentum-based associations. However, lacking appearance features, it can confuse similar objects in overlapping paths. Its linear motion core still imposes limits in extreme velocity variations, requiring careful parameter selection.

Parameters:

Name	Type	Description	Default
`lost_track_buffer`	`int`	`int` specifying number of frames to buffer when a track is lost. Increasing this value enhances occlusion handling but may increase ID switching for similar objects.	`30`
`frame_rate`	`float`	`float` specifying video frame rate in frames per second. Used to scale the lost track buffer for consistent tracking across different frame rates.	`30.0`
`minimum_consecutive_frames`	`int`	`int` specifying number of consecutive frames before a track is considered valid. Before reaching this threshold, tracks are assigned `tracker_id` of `-1`.	`3`
`minimum_iou_threshold`	`float`	`float` specifying IoU threshold for associating detections to existing tracks. Higher values require more overlap.	`0.3`
`direction_consistency_weight`	`float`	`float` specifying weight for direction consistency in the association cost. Higher values prioritize angle alignment between motion and association direction.	`0.2`
`high_conf_det_threshold`	`float`	`float` specifying threshold for high confidence detections. Lower confidence detections are excluded from association.	`0.6`
`delta_t`	`int`	`int` specifying number of past frames to use for velocity estimation. Higher values provide more stable direction estimates during occlusion.	`3`
`state_estimator_class`	`type[BaseStateEstimator]`	State estimator class to use for Kalman filter. Defaults to `XCYCSRStateEstimator`. Can also use `XYXYStateEstimator` for corner-based representation.	`XCYCSRStateEstimator`
`iou`	`BaseIoU \| None`	IoU similarity metric instance to use for data association. Defaults to standard `IoU`. Can be replaced with any `BaseIoU` subclass (e.g. GIoU, DIoU, CIoU) to change how bounding-box similarity is computed during the association step. Passing `None` (the default) is equivalent to `IoU()` and is provided for backward compatibility with existing code that did not supply an `iou` argument.	`None`

`update(detections, frame=None)`

Update tracker state with new detections and return tracked objects. Performs Kalman filter prediction, two-stage association using direction consistency and last-observation recovery, and initializes new tracks for unmatched high-confidence detections.

Parameters:

Name	Type	Description	Default
`detections`	`Detections`	`sv.Detections` containing bounding boxes with shape `(N, 4)` in `(x_min, y_min, x_max, y_max)` format and optional confidence scores.	required
`frame`	`ndarray \| None`	Ignored by OC-SORT. If provided (not `None`), a warning is emitted.	`None`

Returns:

Type	Description
`Detections`	sv.Detections with tracker_id assigned for each detection.
`Detections`	Unmatched or immature tracks have tracker_id of -1.

`reset()`

Reset tracker state by clearing all tracks and resetting ID counter. Call this method when switching to a new video or scene.

BoT-SORT

`trackers.core.botsort.tracker.BoTSORTTracker`

Bases: BaseTracker

BoT-SORT-style multi-object tracker (IoU association + optional CMC).

The tracker maintains a list of active tracks (Kalman-filter-based) and, for each frame, performs: 1) Predict existing track states (Kalman predict) 2) Split detections into high/low confidence groups 3) Split tracks into confirmed, unconfirmed, and lost 4) Apply camera motion compensation to predicted tracks 5) Associate high-confidence detections to confirmed + lost tracks (IoU fused with detection scores + assignment) 6) Associate low-confidence detections to remaining tracks (excluding lost tracks) 7) Match remaining unmatched high-confidence detections to unconfirmed tracks and remove unmatched unconfirmed tracks 8) Spawn new tracks from still unmatched high-confidence detections (instantly activated on the very first frame) 9) Remove tracks that have been lost for too long

Parameters:

Name	Type	Description	Default
`lost_track_buffer`	`int`	Time buffer (in frames at 30 FPS) for keeping lost tracks alive before deletion. This is scaled by `frame_rate`.	`30`
`frame_rate`	`float`	Video frame rate used to scale the lost track buffer to time-like behavior.	`30.0`
`track_activation_threshold`	`float`	Minimum detection confidence to spawn a new track.	`0.7`
`minimum_consecutive_frames`	`int`	Number of successful updates required before assigning a stable track ID (different than initial -1).	`2`
`minimum_iou_threshold_first_assoc`	`float`	Minimum fused similarity (IoU x detection confidence) to accept a detection-track association during the first association step.	`0.2`
`minimum_iou_threshold_second_assoc`	`float`	Minimum fused similarity (IoU x detection confidence) to accept a detection-track association during the second association step.	`0.5`
`minimum_iou_threshold_unconfirmed_assoc`	`float`	Minimum fused similarity (IoU x score) to accept a match between an unconfirmed track and a remaining high-confidence detection. Corresponds to the original ByteTrack's hardcoded cost threshold of 0.7 (= similarity 0.3).	`0.3`
`high_conf_det_threshold`	`float`	Confidence threshold used to split detections into: - high confidence: confidence >= threshold - low confidence: confidence < threshold	`0.6`
`enable_cmc`	`bool`	Whether to enable camera motion compensation (CMC).	`True`
`cmc_method`	`CMCMethod`	CMC method string passed into `CMCConfig(method=...)`. Supported values: "orb", "sift", "sparseOptFlow", "ecc". See CMCConfig.	`'sparseOptFlow'`
`cmc_downscale`	`int`	Downscale factor used inside CMC for speed/robustness.	`2`
`instant_first_frame_activation`	`bool`	If `True` (default), tracks spawned on the very first frame receive a real tracker ID immediately. If `False`, they start as unconfirmed (-1) and must survive `minimum_consecutive_frames` before getting an ID, matching the behaviour on every other frame.	`True`
`state_estimator_class`	`type[BaseStateEstimator]`	State estimator class for tracklets. Defaults to `XCYCWHStateEstimator`.	`XCYCWHStateEstimator`
`iou`	`BaseIoU \| None`	IoU similarity metric instance to use for data association. Defaults to standard `IoU`. Can be replaced with any `BaseIoU` subclass (e.g. GIoU, DIoU, CIoU) to change how bounding-box similarity is computed during association. Passing `None` (the default) is equivalent to `IoU()` and is provided for backward compatibility with existing code that did not supply an `iou` argument.	`None`

Notes

maximum_frames_without_update is computed as: int(frame_rate / 30.0 * lost_track_buffer) to maintain consistent “seconds” worth of buffer across different FPS.
When CMC is enabled, pass the current video frame via the frame argument of :meth:update.

`update(detections, frame=None)`

Update the tracker with detections from the current frame.

This is the main per-frame entry point.

Parameters:

Name	Type	Description	Default
`detections`	`Detections`	Supervision detections for the current frame. Must include `.xyxy`. Confidence (`detections.confidence`) is optional but recommended. This method does not mutate the input detections; it returns a new `sv.Detections` with `tracker_id` assigned.	required

Returns:

Type	Description
`Detections`	New sv.Detections with tracker_id assigned for each detection.
`Detections`	Confirmed tracks have tracker_id >= 0; unconfirmed tracks have
`Detections`	tracker_id of -1.

Notes

If CMC is enabled, pass the current video frame via frame so the tracker can estimate a global affine transform and warp predicted track states before association.

`reset()`

Reset tracker state by clearing all tracks and resetting ID counter. Call this method when switching to a new video or scene.

`apply_cmc_batch(H)`

Apply CMC to all active tracks.

.. deprecated:: 2.5 Use CMC.apply_batch(H, self.tracks) directly.

Parameters:

Name	Type	Description	Default
`H`	`ndarray \| None`	2x3 affine transform matrix returned by CMC.estimate(). If None, this method is a no-op.	required

Examples:

>>> tracker = BoTSORTTracker()
>>> tracker.apply_cmc_batch(None)  # no-op

Utilities

`trackers.utils.converters.xyxy_to_xcycsr(xyxy)`

Convert bounding boxes from corner to center-scale-ratio format.

Parameters:

Name	Type	Description	Default
`xyxy`	`ndarray`	Bounding boxes `[x_min, y_min, x_max, y_max]` with shape `(4,)` for a single box or `(N, 4)` for multiple boxes.	required

Returns:

Type	Description
`ndarray`	Bounding boxes `[x_center, y_center, scale, aspect_ratio]` with same shape as input, where `scale` is area (`width * height`) and `aspect_ratio` is `width / height`.

Examples:

>>> import numpy as np
>>> from trackers import xyxy_to_xcycsr
>>>
>>> boxes = np.array([
...     [0,   0, 10, 10],
...     [0,   0, 20, 10],
...     [0,   0, 10, 20],
... ])
>>>
>>> xyxy_to_xcycsr(boxes)
array([[  5.        ,   5.        , 100.        ,   0.9999999 ],
       [ 10.        ,   5.        , 200.        ,   1.9999998 ],
       [  5.        ,  10.        , 200.        ,   0.49999998]])

`trackers.utils.converters.xcycsr_to_xyxy(xcycsr)`

Convert bounding boxes from center-scale-ratio to corner format.

Parameters:

Name	Type	Description	Default
`xcycsr`	`ndarray`	Bounding boxes `[x_center, y_center, scale, aspect_ratio]` with shape `(4,)` for a single box or `(N, 4)` for multiple boxes, where `scale` is area and `aspect_ratio` is `width / height`.	required

Returns:

Type	Description
`ndarray`	Bounding boxes `[x_min, y_min, x_max, y_max]` with same shape as input.

Examples:

>>> import numpy as np
>>> from trackers import xcycsr_to_xyxy
>>>
>>> boxes = np.array([
...     [  5.,   5., 100., 1.],
...     [ 10.,   5., 200., 2.],
...     [  5.,  10., 200., 0.5],
... ])
>>>
>>> xcycsr_to_xyxy(boxes)
array([[ 0.,  0., 10., 10.],
       [ 0.,  0., 20., 10.],
       [ 0.,  0., 10., 20.]])

Trackers API

SORT

trackers.core.sort.tracker.SORTTracker

trackers property

update(detections, frame=None)

reset()

ByteTrack

trackers.core.bytetrack.tracker.ByteTrackTracker

update(detections, frame=None)

reset()

OC-SORT

trackers.core.ocsort.tracker.OCSORTTracker

update(detections, frame=None)

reset()

BoT-SORT

trackers.core.botsort.tracker.BoTSORTTracker

update(detections, frame=None)

reset()

apply_cmc_batch(H)

Utilities

trackers.utils.converters.xyxy_to_xcycsr(xyxy)

trackers.utils.converters.xcycsr_to_xyxy(xcycsr)

`trackers.core.sort.tracker.SORTTracker`

`trackers` `property`

`update(detections, frame=None)`

`reset()`

`trackers.core.bytetrack.tracker.ByteTrackTracker`

`update(detections, frame=None)`

`reset()`

`trackers.core.ocsort.tracker.OCSORTTracker`

`update(detections, frame=None)`

`reset()`

`trackers.core.botsort.tracker.BoTSORTTracker`

`update(detections, frame=None)`

`reset()`

`apply_cmc_batch(H)`

`trackers.utils.converters.xyxy_to_xcycsr(xyxy)`

`trackers.utils.converters.xcycsr_to_xyxy(xcycsr)`