Tracking Handler

app.ui.handlers.tracking_handler

View source code

Tracking configuration and execution handler for multi-object tracking.

`TrackingHandler`

Bases: QObject

Manages object tracking configuration and execution.

Responsibilities

Start background tracking worker with user-selected strategy.
Handle tracking source selection (which detection layer to track).
Update tracking parameters (IoU threshold, confidence, decay).
Monitor tracking worker progress and completion.
Display tracking results in UI.

Note

Signal flow: Receives signals from right panel (start tracking, strategy, source, parameters). Emits tracking worker finished/failed signals to update UI. Triggers frame re-render after tracking completion.

Validates that active session matches selected session before starting. Prevents tracking if detection worker is running. Shows configuration warning if tracking overlaps with detections.

Layer: Presentation. Context: Supports user interaction and delegates application work through presentation contracts.

`init(controller: UIController) -> None`

controller: UIController supplying tracking settings, worker controls, and the active window to this handler.

`on_box_safety_padding_pct_changed(value: float) -> None`

Update outward safety-margin inflation for privacy boxes.

PARAMETER	DESCRIPTION
`value`	Proportional inflation between 0.0 and 0.50. TYPE: `float`

Example

handler.on_box_safety_padding_pct_changed(0.10)

`on_confidence_decay_changed(value: float) -> None`

Update confidence decay rate for tracker.

Note

Triggered by right panel confidence_decay_spinbox.valueChanged signal.

`on_gsi_smoothness_changed(value: float) -> None`

Update the Gaussian interpolation lengthscale.

PARAMETER	DESCRIPTION
`value`	Kernel lengthscale from 1.0 to 30.0. TYPE: `float`

Raises: InvalidSessionIdException: If the application rejects the selected session.

Note

Higher values blend endpoint predictions across a wider temporal range.

Example

handler.on_gsi_smoothness_changed(10.0)

`on_max_stitch_gap_changed(value: int) -> None`

Update the maximum number of missed frames eligible for stitching.

PARAMETER	DESCRIPTION
`value`	Gap length from 1 to 60 frames. TYPE: `int`

Raises: InvalidSessionIdException: If the application rejects the selected session.

Note

The right-panel spin box enforces the supported numeric range.

Example

handler.on_max_stitch_gap_changed(25)

`on_min_iou_changed(value: float) -> None`

Update minimum IoU threshold for Hungarian strategy.

Note

Triggered by right panel min_iou_spinbox.valueChanged signal.

`on_min_tracker_confidence_changed(value: float) -> None`

Update minimum tracker confidence threshold.

Note

Triggered by right panel min_tracker_confidence_spinbox.valueChanged signal.

`on_offline_stitching_toggled(enabled: bool) -> None`

Update whether post-tracking tracklet stitching is enabled.

PARAMETER	DESCRIPTION
`enabled`	True to enable bidirectional stitching and GSI. TYPE: `bool`

Raises: InvalidSessionIdException: If the application rejects the selected session.

Note

The corresponding gap and smoothness controls are gated by the right panel.

Example

handler.on_offline_stitching_toggled(True)

`on_post_detection_padding_sec_changed(value: float) -> None`

Update the forward post-detection hold duration.

PARAMETER	DESCRIPTION
`value`	Hold duration in seconds, from 0.0 to 5.0. TYPE: `float`

Example

handler.on_post_detection_padding_sec_changed(0.5)

`on_pre_detection_padding_sec_changed(value: float) -> None`

Update the backward pre-detection padding duration.

PARAMETER	DESCRIPTION
`value`	Backfill duration in seconds, from 0.0 to 5.0. TYPE: `float`

Example

handler.on_pre_detection_padding_sec_changed(0.5)

`on_privacy_features_enabled_changed(enabled: bool) -> None`

Update the Privacy Shield master setting for the selected session.

PARAMETER	DESCRIPTION
`enabled`	Whether conservative privacy post-processing is active. TYPE: `bool`

Example

handler.on_privacy_features_enabled_changed(True)

`on_reid_embedding_dim_changed(dimension: int) -> None`

Update the Re-ID embedding dimension for the selected session.

PARAMETER	DESCRIPTION
`dimension`	Embedding vector size selected in the tracking panel. TYPE: `int`

Note: The panel offers only the dimensions accepted by ProcessingSettings.

Example

handler.on_reid_embedding_dim_changed(256)

`on_resist_box_shrinking_changed(enabled: bool) -> None`

Update whether track boxes resist sudden size contractions.

PARAMETER	DESCRIPTION
`enabled`	Whether the anti-shrink size envelope is active. TYPE: `bool`

Example

handler.on_resist_box_shrinking_changed(True)

`on_shrink_resistance_changed(value: float) -> None`

Update the damping factor used by anti-shrink box processing.

PARAMETER	DESCRIPTION
`value`	Contraction damping factor between 0.0 and 0.99. TYPE: `float`

Example

handler.on_shrink_resistance_changed(0.85)

`on_source_changed(source: str) -> None`

Update tracking source layer and reapply tracking configuration.

Note

Triggered by right panel tracking_source_changed signal.

Action: Update session settings and warn if tracking overlaps detection.

`on_start_tracking(strategy_name: str, source_layer_name: VideoDataLayer) -> None`

Start background tracking for detected objects.

Note

Triggered by right panel start_tracking_requested signal.

Flow: on_start_tracking(strategy, source) [this slot] ├── Validate selected and active sessions match ├── Check that detection is not currently running ├── Set UI to loading view_state ├── Start TrackingWorker in background └──> Connect worker signals for progress/completion

Safety Checks: Session ID must be selected. Active session must match selected session. Tracking worker must not already be running. Display error dialogs if any check fails.

`on_strategy_changed(strategy: str) -> None`

Update tracking strategy and adjust UI visibility accordingly.

Note

Triggered by right panel tracking_strategy_changed signal.

Action: Show/hide IoU threshold controls (only for Hungarian strategy). Update session settings and show warning if tracking data exists.

Tracking Handler