Deepsort Strategy

app.infrastructure.tracking.deepsort_strategy

Incremental DeepSORT-style tracking with conservative appearance memory.

`DeepSortStrategy`

Associate detections using motion, IoU, and bounded per-track Re-ID memory.

ATTRIBUTE	DESCRIPTION
`uses_appearance`	Whether the strategy consumes appearance vectors.

Embeddings align with frame_boxes and may be None. If omitted while an RGB frame is supplied, the configured appearance extractor is used. Track memory is learned only from matched detections isolated by pairwise IoU <.25.

Note

A track's appearance distance is the minimum cosine distance across its EMA prototype and its last 30 isolated detection embeddings.

Example

strategy = DeepSortStrategy(min_iou=0.3)

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

`uses_appearance = True` `class-attribute` `instance-attribute`

`init(min_iou: float = 0.3, min_confidence: float = 0.1, confidence_decay: float = 0.05, *, max_age: int | None = None, appearance_extractor: ReIDExtractorProtocol | None = None) -> None`

PARAMETER	DESCRIPTION
`min_iou`	Minimum overlap for the motion/IoU association stage. TYPE: `float` DEFAULT: `0.3`
`min_confidence`	Minimum score to start a track and retain a coast. TYPE: `float` DEFAULT: `0.1`
`confidence_decay`	Confidence loss per missed frame. TYPE: `float` DEFAULT: `0.05`
`max_age`	Maximum missed frames; defaults to the decay-derived limit. TYPE: `int \| None` DEFAULT: `None`
`appearance_extractor`	Optional extractor used when `frame` is passed. TYPE: `ReIDExtractorProtocol \| None` DEFAULT: `None`

RAISES	DESCRIPTION
`ValueError`	If thresholds are outside their valid ranges.

Note: If the historical external DeepSORT backend is available, it is initialized only for compatibility with the legacy batch wrapper.

Example

strategy = DeepSortStrategy(min_confidence=0.2)

`track(source_data: ListOfBoxesByFrameIndexAsDict, total_frames: int = 0, *, frames: Mapping[int, np.ndarray] | Sequence[np.ndarray] | None = None, embeddings_by_frame: Mapping[int, Sequence[np.ndarray | None]] | None = None) -> ListOfBoxesByFrameIndexAsDict`

Track a full batch; the incremental API remains the implementation path.

PARAMETER	DESCRIPTION
`source_data`	Sparse per-frame detections. TYPE: `ListOfBoxesByFrameIndexAsDict`
`total_frames`	Number of frames; zero infers it from `source_data`. TYPE: `int` DEFAULT: `0`
`frames`	Optional RGB frames keyed by index or supplied as a sequence. TYPE: `Mapping[int, ndarray] \| Sequence[ndarray] \| None` DEFAULT: `None`
`embeddings_by_frame`	Optional aligned appearance vectors by frame. TYPE: `Mapping[int, Sequence[ndarray \| None]] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`ListOfBoxesByFrameIndexAsDict`	Track boxes keyed by frame index.

RAISES	DESCRIPTION
`ValueError`	If the frame count is invalid.

Note

When the historical DeepSORT backend is installed and optional appearance inputs are omitted, the batch wrapper preserves its old adapter behavior. Frame-aware callers use the native incremental association path.

Example

tracked = strategy.track(detections, total_frames=120)

When the optional historical deep_sort_realtime backend is available, this wrapper preserves its prior public behavior. Otherwise, it runs the native tracker over frames in order.

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

Advance one frame and return detection-backed and coasted track boxes.

PARAMETER	DESCRIPTION
`frame_idx`	Nonnegative, strictly increasing frame number. TYPE: `int`
`frame_boxes`	Current detections in input order. TYPE: `Sequence[BBoxViewModel]`
`frame`	Optional RGB image for appearance extraction. TYPE: `RGBFrame \| None` DEFAULT: `None`
`embeddings`	Optional vectors aligned with `frame_boxes`. TYPE: `Sequence[ndarray \| None] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[BBoxViewModel]`	Active tracking boxes for this frame.

RAISES	DESCRIPTION
`ValueError`	If frame indices, boxes, or embeddings are malformed.

Note

Confirmed tracks are matched by age cascade, followed by unambiguous wide-radius appearance recovery and tentative-track IoU matching.

Example

tracked_boxes = strategy.update_frame(0, detections, embeddings=vectors)

Deepsort Strategy