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	Non-negative int specifying number of 30 FPS frames to buffer when a track is lost. 0 deletes a confirmed track on the first missed frame. 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. Must be positive. 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, timestamp=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
timestamp	float | None	Absolute time of the current frame in seconds, or None for fixed-rate mode (frame_step = 1.0 per call).	None

Returns:

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

Warns:

Type	Description
UserWarning	If frame is passed but SORT does not perform camera motion compensation (CMC), the frame is ignored.

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	Non-negative int specifying number of 30 FPS frames to buffer when a track is lost. 0 deletes a confirmed track on the first missed frame. 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. Must be positive. 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, timestamp=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
timestamp	float | None	Absolute time of the current frame in seconds, or None for fixed-rate mode (frame_step = 1.0 per call).	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.

Warns:

Type	Description
UserWarning	If frame is passed but ByteTrack does not perform camera motion compensation (CMC), the frame is ignored.

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	Non-negative int specifying number of 30 FPS frames to buffer when a track is lost. 0 deletes a confirmed track on the first missed frame. 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. Must be positive. 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 and from spawning new tracks, but are still returned with tracker_id of -1.	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, timestamp=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. When detections.confidence is None, all detections are treated as confidence 1.0 -- they bypass high_conf_det_threshold entirely and are eligible for association/spawning regardless of its value.	required
frame	ndarray | None	Ignored by OC-SORT. If provided (not None), a warning is emitted.	None
timestamp	float | None	Absolute time of the current frame in seconds, or None for fixed-rate mode (frame_step = 1.0 per call).	None

Returns:

Type	Description
Detections	sv.Detections with tracker_id assigned for each detection.
Detections	Unmatched or immature tracks, and detections below
Detections	high_conf_det_threshold (which are never associated or used to
Detections	spawn a track), have tracker_id of -1. Detection order may differ
Detections	from input.

Warns:

Type	Description
UserWarning	If frame is passed but OC-SORT does not perform camera motion compensation (CMC), the frame is ignored.

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	Non-negative time buffer (in frames at 30 FPS) for keeping lost tracks alive before deletion. 0 deletes a confirmed track on the first missed frame. This is scaled by frame_rate.	30
frame_rate	float	Video frame rate used to scale the lost track buffer to time-like behavior. Must be positive.	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 IoU to accept a detection-track association during the second association step. No score fusion is applied in this pass, so this is plain IoU.	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

• Positive maximum_frames_without_update values are scaled by frame_rate and rounded up to at least one missed frame. Explicit zero-buffer configurations remain zero.
• When CMC is enabled, pass the current video frame via the frame argument of :meth:update.

update(detections, frame=None, timestamp=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
frame	ndarray | None	Current video frame in BGR format (H, W, 3), or None. Used for camera motion compensation when enable_cmc=True.	None
timestamp	float | None	Absolute time of the current frame in seconds, or None for fixed-rate mode (frame_step = 1.0 per call).	None

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.

Warns:

Type	Description
UserWarning	If timestamp is earlier than the previous call (backwards order); the whole update is skipped and all output IDs are -1. If timestamp equals the previous call (duplicate); predict is skipped but association still runs on the last state.

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. When frame=None and enable_cmc=True, CMC is silently skipped for that step.

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

C-BIoU

trackers.core.cbiou.tracker.CBIoUTracker

Bases: BoTSORTTracker

Cascaded-Buffered IoU (C-BIoU) tracker.

Implements the matching strategy from Yang et al., Hard To Track Objects with Irregular Motions and Similar Appearances? Make It Easier by Buffering the Matching Space, WACV 2023 (paper).

The paper proposes Buffered IoU (BIoU) — expanding boxes by a proportional margin before computing overlap — and cascaded matching with a small buffer scale b1 followed by a larger scale b2 (typically b1 < b2).

Each association step uses its own buffer_ratio:

• buffer_ratio_first — first pass (high-confidence detections vs tracks; paper: small b1).
• buffer_ratio_second — second pass (remaining confirmed tracks vs low-confidence detections; paper: large b2).

The ByteTrack-style unconfirmed-track step (leftover high-confidence detections vs tentative tracks) reuses b1 (iou_first).

Camera motion compensation is not used (detection-only / MOT-file workflows).

Parameters:

Name	Type	Description	Default
lost_track_buffer	int	Time buffer (in frames at 30 FPS) for keeping lost tracks alive before deletion. Scaled by frame_rate.	30
frame_rate	float	Video frame rate used to scale the lost track buffer.	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.	2
minimum_iou_threshold_first_assoc	float	Minimum fused similarity for the first association step.	0.2
minimum_iou_threshold_second_assoc	float	Minimum fused similarity for the second association step.	0.5
minimum_iou_threshold_unconfirmed_assoc	float	Minimum fused similarity for the unconfirmed association step.	0.3
high_conf_det_threshold	float	Confidence threshold splitting high / low detections.	0.6
instant_first_frame_activation	bool	If True, first-frame tracks receive a real ID immediately.	True
state_estimator_class	type[BaseStateEstimator]	Kalman state representation for tracklets.	XCYCWHStateEstimator
buffer_ratio_first	float	Buffer scale b1 for the first BIoU pass. It is suggested to be less than buffer_ratio_second (b1 < b2) per the paper.	0.3
buffer_ratio_second	float	Buffer scale b2 for the second BIoU pass. It is suggested to be greater than buffer_ratio_first.	0.5

Raises:

Type	Description
ValueError	If lost_track_buffer is negative or frame_rate is not a finite positive value (inherited from BoTSORTTracker).
ValueError	If buffer_ratio_first or buffer_ratio_second is negative.

Note

Unmatched low-confidence detections (confidence in (0.1, high_conf_det_threshold)) that are not associated in Step 2 appear in the output with tracker_id == -1, consistent with BoTSORTTracker behaviour. Callers filtering by tracker_id >= 0 will silently drop these rows. Tracks that already hold a real tracker_id (for example, instant-activated tracks) remain confirmed on a miss even before minimum_consecutive_frames is reached.

Example

Run C-BIoU on a batch of detections::

import numpy as np
import supervision as sv
from trackers import CBIoUTracker

tracker = CBIoUTracker()
detections = sv.Detections(
    xyxy=np.array([[0.0, 0.0, 100.0, 100.0]]),
    confidence=np.array([0.9]),
)
result = tracker.update(detections)

update(detections, frame=None, timestamp=None)

Update the C-BIoU tracker with detections from the current frame.

Runs the association pipeline with a distinct BIoU instance per step (cascaded buffers per Yang et al., WACV 2023). Does not use frames or CMC.

Parameters:

Name	Type	Description	Default
detections	Detections	Supervision detections for the current frame.	required
frame	ndarray | None	Unused. Emits a UserWarning if provided.	None
timestamp	float | None	Absolute time of the current frame in seconds, or None for fixed-rate mode (frame_step = 1.0 per call).	None

Returns:

Type	Description
Detections	Detections with tracker_id assigned. Unmatched
Detections	low-confidence detections are included with tracker_id == -1;
Detections	callers filtering by tracker_id >= 0 will silently drop these rows.

Warns:

Type	Description
UserWarning	If frame is passed but C-BIoU does not perform camera motion compensation (CMC), the frame is ignored.

McByte

trackers.core.mcbyte.tracker.McByteTracker

Bases: BaseTracker

McByte multi-object tracker with optional mask-conditioned association.

McByte extends a ByteTrack-style multi-stage tracking pipeline with clear-match locking, reduced assignment, optional camera motion compensation, and optional propagated-mask evidence.

The tracker can operate in two configurations:

• without a MaskManager, association uses the McByte clear-match locking and reduced-assignment procedure with IoU-based similarities;
• with a MaskManager (full McByte), masks are additionally used to condition ambiguous associations and, when enabled, isolated positive-IoU associations below the normal stage threshold.

When enable_mask_manager=True, the default mask pipeline initializes masks from detection boxes using SAM and propagates them temporally using Cutie. A custom MaskManager may instead be supplied directly, for example to inject alternative mask components or lightweight test doubles.

Mask processing follows the original McByte timing. At frame t, masks are updated before association using the frame, visible tracklets, newly created tracklets, and removed-tracklet events stored after processing frame t - 1. Temporarily lost but still active tracklets retain their masks. Masks are removed only after the corresponding tracklets are terminated during tracker pruning.

Input frames are expected in RGB channel order. A frame is required when mask management is enabled and is also needed for camera motion compensation. When no frame is supplied, those frame-dependent operations are skipped.

Parameters:

Name	Type	Description	Default
lost_track_buffer	int	Time buffer, expressed as a number of frames at 30 FPS, for retaining unmatched tracks before deletion. The value is scaled according to frame_rate.	30
frame_rate	float	Sequence frame rate used to scale lost_track_buffer.	30.0
track_activation_threshold	float	Minimum detection confidence required to create a new tracklet.	0.7
minimum_consecutive_frames	int	Number of successful tracklet updates required before assigning a confirmed non-negative tracker ID.	2
minimum_iou_threshold_first_assoc	float	Minimum association similarity for matching high-confidence detections to confirmed and lost tracks. The default of 0.1 follows ByteTrack's deliberately low first-association threshold: a broad candidate set is admitted and resolved by fused IoU and detection score. In the default mode (enable_mask_manager=False) this ByteTrack parity is the sole safety net. When mask management is enabled, the same broad candidate set additionally lets mask-conditioned association resolve ambiguities and optional isolations.	0.1
minimum_iou_threshold_second_assoc	float	Minimum association similarity for matching low-confidence detections to remaining tracked tracks.	0.5
minimum_iou_threshold_unconfirmed_assoc	float	Minimum association similarity for matching unconfirmed tracks to remaining high-confidence detections.	0.3
high_conf_det_threshold	float	Confidence threshold separating high- and low-confidence detections. Detections with confidence at or below 0.1 are discarded.	0.6
enable_cmc	bool	Whether to apply camera motion compensation before association.	True
cmc_method	CMCMethod	Camera motion compensation method.	'sparseOptFlow'
cmc_downscale	int	Image downscale factor used during camera motion estimation. Defaults to 6 based on the 1280x720 SportsMOT validation aggregate-performance criterion; it is not a strict per-clip guarantee. Tune it for other workloads or pass 2 to preserve the previous conservative behavior.	6
instant_first_frame_activation	bool	Whether tracklets created on the first frame receive confirmed tracker IDs immediately.	True
state_estimator_class	type[BaseStateEstimator]	State estimator class used by newly created McByteTracklet instances.	XCYCWHStateEstimator
iou	BaseIoU | None	IoU implementation used to compute association similarities. When omitted, the default IoU implementation is used.	None
enable_mask_manager	bool	Whether to construct McByte's default SAM and Cutie mask pipeline. It is disabled by default to avoid loading optional heavyweight models when mask-conditioned tracking is not requested.	False
mask_manager	MaskManager | None	Optional custom MaskManager. When supplied, it is used directly regardless of enable_mask_manager, and automatic SAM/Cutie construction is skipped.	None
mask_config	McByteMaskConfig | None	Configuration for automatic construction of the default SAM/Cutie pipeline. It requires enable_mask_manager=True and cannot be combined with a custom mask_manager.	None
minimum_mask_average_confidence	float	Minimum average confidence of a propagated mask before it may influence association.	MINIMUM_MASK_AVERAGE_CONFIDENCE
minimum_mask_coverage	float	Minimum fraction of the visible tracklet mask that must lie inside a candidate detection box.	MINIMUM_MASK_COVERAGE
minimum_mask_fill_ratio	float	Minimum fraction of a candidate detection-box area that must be occupied by the tracklet mask.	MINIMUM_MASK_FILL_RATIO
enable_isolated_mask_matching	bool	Whether mask evidence may rescue an isolated candidate with positive IoU whose association similarity is below the normal stage threshold.	False
minimum_mask_creation_frames	int	Number of consecutive frames a confirmed tracklet must remain visible in tracker output before its mask is created (the SAM prompt plus Cutie add_masks). This defers the per-appearance mask encode for very-short-lived tracklets: those that terminate before reaching the threshold never pay the encode, at the cost of running IoU-only association for those tracklets until their mask exists. Because mask conditioning is deferred, this can alter tracking output and must be validated for CLEAR/HOTA/ Identity parity on the target workload. Use 1 to create masks on a tracklet's first visible frame (the original immediate-creation timing). A deferred tracklet is withheld from the mask pipeline entirely, including Cutie's initial mask set: when every confirmed tracklet is still inside its defer window the first masks are produced only once at least one tracklet reaches the threshold.	3

update(detections, frame=None, timestamp=None)

Update the tracker with detections from the current frame.

This is the main per-frame entry point. If a mask manager is configured and a frame is provided, masks are updated before association using tracker lifecycle events stored from the previous call. After association, the method stores the current frame's visible tracklets, newly created tracklets, and explicitly terminated tracklet IDs for the next frame's mask update.

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
frame	ndarray | None	Current frame in RGB channel order, shape (H, W, 3). Note this deviates from the BaseTracker.update default of BGR: McByte's SAM and Cutie mask backends consume the frame as RGB without any internal channel conversion, so a BGR frame silently degrades mask quality (and therefore mask-conditioned association). Required for camera motion compensation and for mask-manager propagation.	None
timestamp	float | None	Absolute time of the current frame in seconds, or None for fixed-rate mode (frame_step = 1.0 per call). When provided, capture times must be non-decreasing; elapsed seconds are converted to Kalman frame units for prediction and used directly for lost-track pruning.	None

Returns:

Type	Description
Detections	New sv.Detections with tracker_id assigned for each output detection.
Detections	Confirmed tracks have tracker_id >= 0; unmatched/unconfirmed detections have
Detections	tracker_id of -1. When the update is skipped (backwards or non-finite
Detections	timestamp), all tracker_id values are -1.

Warns:

Type	Description
UserWarning	If timestamp is earlier than the previous call (backwards order); the whole update is skipped and all output IDs are -1. If timestamp equals the previous call (duplicate); predict is skipped but association still runs on the last state.

reset()

Reset tracker, camera-motion, and mask-manager state.

This clears active tracklets, resets the global McByte track ID counter, clears stored mask lifecycle inputs, and resets optional camera motion compensation and mask-manager components. Call this when switching to a new video or scene.

apply_cmc_batch(H)

Apply camera motion compensation to all active tracks.

Convenience wrapper around :meth:CMC.apply_batch for callers that hold a tracker instance and an affine transform. update() applies CMC directly and does not rely on this method.

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 = McByteTracker()
>>> tracker.apply_cmc_batch(None)  # no-op

trackers.core.mcbyte.tracker.McByteMaskConfig dataclass

Configuration for McByte's SAM and Cutie mask pipeline.

The configuration is used only when McByteTracker automatically creates its default real MaskManager. It is ignored when a custom manager is supplied directly.

Parameters:

Name	Type	Description	Default
device	str	Device shared by SAM and Cutie, for example "cuda", "cuda:0", "mps", or "cpu". The default "auto" resolves to CUDA when available, otherwise CPU. Apple MPS is never auto-selected (measured roughly an order of magnitude slower than CPU for this pipeline); pass device="mps" explicitly to use it.	'auto'
sam_checkpoint_path	str | Path | None	Optional SAM checkpoint path. When omitted, the default checkpoint for sam_model_type is used and downloaded automatically when necessary.	None
sam_model_type	str	SAM model variant used for box-prompted mask generation.	'vit_b'
cutie_weights_path	str | Path | None	Optional Cutie checkpoint path. When omitted, the default checkpoint for cutie_model_type is used and downloaded automatically when necessary.	None
cutie_model_type	str	Cutie model variant used for temporal propagation.	'base-mega'
cutie_config_path	str | Path | None	Optional Cutie Hydra configuration directory. When omitted, it is inferred from the installed Cutie package.	None
cutie_config_name	str	Hydra configuration name loaded by Cutie.	'eval_config'
cutie_use_amp	bool	Whether Cutie may use automatic mixed precision. AMP is activated only when Cutie runs on a CUDA device. Disabled by default so that default runs use full fp32 precision on every backend; opt in explicitly after validating tracking-quality parity on your hardware.	False
cutie_max_internal_size	int	Maximum shortest side of frames processed internally by Cutie. Larger frames are downscaled before the encoder and the propagated masks are restored to the original resolution, matching Cutie's own streaming preset. Use -1 to propagate at full input resolution (Cutie's offline-benchmark behavior; substantially slower on high-resolution streams).	480
cutie_mem_every	int | None	How often, in frames, Cutie updates its working memory. Higher values speed up processing. None keeps the value from the loaded Cutie configuration.	10
cutie_use_long_term	bool | None	Whether Cutie uses bounded long-term memory, recommended for videos longer than roughly one minute. None keeps the value from the loaded Cutie configuration.	True
cutie_channels_last	bool	Opt-in channels_last memory format for the Cutie model. Off by default so default runs are unchanged; it may alter kernel selection, so validate fp32 tracking-quality parity on your backend before enabling. Primarily helps CUDA.	False
cutie_compile	bool	Opt-in torch.compile of Cutie's shape-stable per-frame encoder path. Off by default; incurs first-call warmup and may alter numerics, so validate fp32 parity before enabling. torch.compile support on MPS is experimental.	False
mask_creation_bbox_overlap_threshold	float	Bounding-box overlap fraction at or above which mask creation is delayed by MaskManager.	MASK_CREATION_BBOX_OVERLAP_THRESHOLD

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.
ndarray	Decoding is always performed in floating point: integer input is promoted
ndarray	(int32/int64 decode to float64), and float input keeps its own
ndarray	precision (float32 decodes to float32).

Note

When scale or aspect_ratio is zero, w collapses to 0.0 and the box degenerates to a point at (x_center, y_center) — all four coordinates equal the center. No NaN or Inf is produced.

When the product scale * aspect_ratio underflows to exactly 0.0 due to subnormal float arithmetic (e.g. both values near 1e-200), the zero-guard fires and returns h=0.0 even though the mathematically correct value may be non-zero.

Negative scale yields NaN entries because sqrt of a negative value is undefined.

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.]])
>>>
>>> # degenerate: zero scale collapses to a point box
>>> xcycsr_to_xyxy(np.array([10., 20., 0., 1.]))
array([10., 20., 10., 20.])