Post Processor

app.infrastructure.tracking.post_processor

Offline tracklet stitching and bounded Gaussian interpolation.

`TrackingPostProcessor`

Optionally stitch tracklets and generate confidence-bounded coast estimates.

PARAMETER	DESCRIPTION
`max_gap`	Maximum number of missed frames bridged by offline stitching. TYPE: `int` DEFAULT: `25`
`gsi_smoothness`	Gaussian kernel lengthscale used to blend gap predictions. TYPE: `float` DEFAULT: `10.0`
`confidence_decay`	Per-missed-frame confidence penalty. TYPE: `float` DEFAULT: `0.05`
`min_confidence`	Minimum confidence retained in tracking output. TYPE: `float` DEFAULT: `0.1`
`offline_stitching_enabled`	Whether to link tracklets and use GSI. TYPE: `bool` DEFAULT: `True`
`max_unbridged_coast`	Maximum coast frames for unbridged offline tails. TYPE: `int` DEFAULT: `6`
`privacy_features_enabled`	Whether conservative privacy post-processing is active. TYPE: `bool` DEFAULT: `False`
`resist_box_shrinking`	Whether output boxes resist sudden contractions. TYPE: `bool` DEFAULT: `True`
`shrink_resistance`	Damping factor for decreasing the box envelope. TYPE: `float` DEFAULT: `0.85`
`pre_detection_padding_sec`	Duration of backward box extrapolation. TYPE: `float` DEFAULT: `0.5`
`post_detection_padding_sec`	Duration of forward box holding. TYPE: `float` DEFAULT: `0.5`
`box_safety_padding_pct`	Proportional outward box inflation. TYPE: `float` DEFAULT: `0.1`
`fps`	Video frame rate used to convert padding durations to frames. TYPE: `float` DEFAULT: `30.0`
`frame_width`	Optional frame width used to clamp projected boxes. TYPE: `int` DEFAULT: `0`
`frame_height`	Optional frame height used to clamp projected boxes. TYPE: `int` DEFAULT: `0`

RAISES	DESCRIPTION
`ValueError`	If any numeric setting is outside its supported range.

Note

With offline stitching enabled, coasted input boxes are discarded in favor of detection-backed observations, stitched GSI gaps, and short 2x-decay tails. With stitching disabled, missing frames use causal 1x-decay estimates.

Example

processor = TrackingPostProcessor(max_gap=25, gsi_smoothness=10.0) results = processor.process(track_data, total_frames=300)

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

`init(max_gap: int = 25, gsi_smoothness: float = 10.0, confidence_decay: float = 0.05, min_confidence: float = 0.1, offline_stitching_enabled: bool = True, max_unbridged_coast: int = 6, privacy_features_enabled: bool = False, resist_box_shrinking: bool = True, shrink_resistance: float = 0.85, pre_detection_padding_sec: float = 0.5, post_detection_padding_sec: float = 0.5, box_safety_padding_pct: float = 0.1, fps: float = 30.0, frame_width: int = 0, frame_height: int = 0) -> None`

`process(tracked_data: ListOfBoxesByFrameIndexAsDict, total_frames: int | None = None, appearance_embeddings_by_frame: dict[int, dict[str, np.ndarray]] | None = None) -> ListOfBoxesByFrameIndexAsDict`

Post-process observations into stitched or causal tracking output.

PARAMETER	DESCRIPTION
`tracked_data`	Tracker output keyed by zero-based frame index. TYPE: `ListOfBoxesByFrameIndexAsDict`
`total_frames`	Optional video frame count used to bound final coast tails. TYPE: `int \| None` DEFAULT: `None`
`appearance_embeddings_by_frame`	Optional isolated appearance vectors keyed by frame index and tracker box ID. TYPE: `dict[int, dict[str, ndarray]] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`ListOfBoxesByFrameIndexAsDict`	A sorted frame-to-box mapping containing observations and accepted coasts.

RAISES	DESCRIPTION
`ValueError`	If `total_frames` is negative.

Note

Legacy boxes without coast metadata are treated as detection-backed.

Example

output = processor.process(raw_tracks, total_frames=120)