Tracking Strategy

app.infrastructure.tracking.tracking_strategy

View source code

Module for tracking strategy; implements concrete processing and I/O behind application-facing contracts.

See Also

• TrackingStrategy — lists the strategies selected by the application
• HungarianIoUTracker — core tracker used by the Hungarian strategy

Layer: Infrastructure. Context: Implements concrete processing and i/o behind application-facing contracts at this architectural boundary.

HungarianStrategy

Tracking strategy using Hungarian algorithm with IoU matching (see HungarianIoUTracker).

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

uses_appearance = False class-attribute instance-attribute

__init__(iou_threshold: float = 0.3, confidence_decay: float = 0.05, min_confidence: float = 0.1) -> None

PARAMETER	DESCRIPTION
iou_threshold	Minimum IoU accepted for a detection-track match. TYPE: float DEFAULT: 0.3
confidence_decay	Per-frame confidence penalty while coasting. TYPE: float DEFAULT: 0.05
min_confidence	Confidence floor used to prune internal tracks. TYPE: float DEFAULT: 0.1

Note

Coasting states are retained in output with detection_backed=False.

Example

strategy = HungarianStrategy(iou_threshold=0.3, confidence_decay=0.05)

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

Run the incremental strategy over a complete frame map.

PARAMETER	DESCRIPTION
source_data	Per-frame detection input. TYPE: ListOfBoxesByFrameIndexAsDict
total_frames	Number of frames to process. TYPE: int

RETURNS	DESCRIPTION
ListOfBoxesByFrameIndexAsDict	Boxes keyed by frame, with detection-backed and coast-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 state with one frame and return active detection/coast boxes.

PARAMETER	DESCRIPTION
frame_idx	Zero-based frame index. TYPE: int
frame_boxes	Detection boxes for the current frame. TYPE: list[BBoxViewModel]
frame	Optional RGB frame, unused by this motion-only strategy. TYPE: RGBFrame | None DEFAULT: None
embeddings	Optional box-aligned appearance features, unused here. TYPE: Sequence[ndarray | None] | None DEFAULT: None

RETURNS	DESCRIPTION
list[BBoxViewModel]	Active tracker boxes for the current frame.

DummyTracker

No-op tracker — passes through detections as-is, marks with magenta (#ff00ff).

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

uses_appearance = False class-attribute instance-attribute

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

Return detections unchanged, just update source/color/key labels.

PARAMETER	DESCRIPTION
source_data	Detection boxes grouped by frame index. TYPE: ListOfBoxesByFrameIndexAsDict
total_frames	Retained for tracker API compatibility; this implementation does not use it. TYPE: int DEFAULT: 0

RETURNS	DESCRIPTION
ListOfBoxesByFrameIndexAsDict	New frame mapping containing deep-copied boxes retagged as dummy tracks.

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

Copy and retag detections for one frame.

PARAMETER	DESCRIPTION
frame_idx	Zero-based frame index. TYPE: int
frame_boxes	Detection boxes to copy. TYPE: list[BBoxViewModel]
frame	Optional RGB frame, unused by this strategy. TYPE: RGBFrame | None DEFAULT: None
embeddings	Optional appearance features, unused by this strategy. TYPE: Sequence[ndarray | None] | None DEFAULT: None

RETURNS	DESCRIPTION
list[BBoxViewModel]	Copied boxes marked as dummy tracking output.

uid_to_color(uid: int) -> str

Map track UID to color (wraps around palette for >20 tracks).

PARAMETER	DESCRIPTION
uid	Positive track identifier used to select a palette entry. TYPE: int

RETURNS	DESCRIPTION
str	Hex color selected cyclically from the tracking palette.