Bytetrack Strategy

app.infrastructure.tracking.bytetrack_strategy

View source code

ByteTrack strategy adapter.

Simple explanation: ByteTrack links boxes from one frame to the next by looking at overlap and motion, then keeps each object under the same track ID. If a detection is not very confident, ByteTrack can still use it as a secondary hint so tracks do not break too quickly.

See Also

• TrackingWorker — dispatches frames to this strategy
• TrackingStrategy — lists the user-selectable strategy

Layer: Infrastructure. Context: Implements concrete processing and I/O behind application-facing contracts.

ByteTrackStrategy

Track objects using ByteTrack while preserving the app's output contract.

Simple runtime note: Ultralytics ByteTrack expects a Boxes/results-like object (with fields like conf and xywh), not a raw matrix. We therefore build a Boxes object per frame and parse ByteTrack's ndarray output rows back into BBoxViewModel objects.

Layer: Infrastructure. Context: Implements concrete processing or I/O behind application-facing contracts.

uses_appearance = False class-attribute instance-attribute

__init__(min_iou: float = 0.3, min_confidence: float = 0.1, min_detection_confidence: float = 0.25, confidence_decay: float = 0.05) -> None

PARAMETER	DESCRIPTION
min_iou	IoU similarity used to configure tracker association. TYPE: float DEFAULT: 0.3
min_confidence	Minimum confidence for accepting tracker output. TYPE: float DEFAULT: 0.1
min_detection_confidence	Confidence floor applied before tracking. TYPE: float DEFAULT: 0.25
confidence_decay	Confidence reduction per coasted frame. TYPE: float DEFAULT: 0.05

Raises: ModuleNotFoundError: If the optional Ultralytics dependency is unavailable.

Note

The wrapped ByteTrack constructor is version-adapted because supported releases differ in their required constructor arguments.

Example

strategy = ByteTrackStrategy(min_iou=0.3, confidence_decay=0.05)

track(source_data: ListOfBoxesByFrameIndexAsDict, total_frames: int = 0) -> ListOfBoxesByFrameIndexAsDict

Run the incremental strategy over a complete detection frame map.

PARAMETER	DESCRIPTION
source_data	Per-frame detections to associate. TYPE: ListOfBoxesByFrameIndexAsDict
total_frames	Number of frames to process. TYPE: int DEFAULT: 0

RETURNS	DESCRIPTION
ListOfBoxesByFrameIndexAsDict	Tracking boxes keyed by frame index with observation-age metadata.

update_frame(frame_idx: int, frame_boxes: list[BBoxViewModel], frame: RGBFrame | None = None, embeddings: Sequence[np.ndarray | None] | None = None) -> list[BBoxViewModel]

Update ByteTrack with one frame of detections.

PARAMETER	DESCRIPTION
frame_idx	Zero-based frame index. TYPE: int
frame_boxes	Detections to associate for this frame. TYPE: list[BBoxViewModel]
frame	Optional RGB frame; unused by this motion-only strategy. TYPE: RGBFrame | None DEFAULT: None
embeddings	Optional box-aligned features; unused here. TYPE: Sequence[ndarray | None] | None DEFAULT: None

RETURNS	DESCRIPTION
list[BBoxViewModel]	Detection-backed or coasted track boxes for this frame.