Skip to content

Service

app.application.services.tracking.service

View source code

Tracking worker orchestration and multi-object tracking management.

See Also

Layer: Application. Context: Coordinates domain state and infrastructure to complete application use cases.

TrackingService

Orchestrates multi-object tracking operations and worker lifecycle.

Responsibilities
  • Start background TrackingWorker for multi-frame tracking.
  • Validate tracking prerequisites (layer data, worker view_state).
  • Clear tracking output layers before starting new tracking.
  • Synchronize tracking results from worker to DataLayer.C.
  • Handle worker creation and view_state management.
Note

Creates TrackingWorker instances (runs in background thread). Manages Layer C/D lifecycle (clears C before tracking, syncs after). Validates the source layer and seeds missing Layer B frames from Layer A. Does NOT manage tracking layer editing (delegates to TrackingLayerService).

Tracking Layers: DataLayer.C — Post-processed tracking output (immutable, machine-written). DataLayer.D — User-editable tracking results (eagerly seeded from C).

PARAMETER DESCRIPTION
app

Application adapted for tracking-worker startup and result processing against session data.

TYPE: Application

__init__(app: Application)

get_detection_frame_coverage(s_id: SessionId) -> tuple[int, int]

Return detection-frame coverage and total video frames before tracking.

PARAMETER DESCRIPTION
s_id

Session to inspect without changing its annotation layers.

TYPE: SessionId

RETURNS DESCRIPTION
int

Pair of initialized Layer A frame count and video frame count.
int

Empty detection results count as processed; absent frames do not.
tuple[int, int]

Older/imported data can only provide evidence from stored entries,
tuple[int, int]

not proof that a particular background worker completed.

start_background_tracking(s_id: SessionId, strategy_name: str, source_layer_name: VideoDataLayer) -> None

Start background multi-object tracking on detection/tracking data.

PARAMETER DESCRIPTION
s_id

Session ID.

TYPE: SessionId

strategy_name

Tracking algorithm (e.g., "Hungarian", "DeepSort").

TYPE: str

source_layer_name

Source layer (DataLayer.A or DataLayer.B).

TYPE: str

Note

Flow: start_background_tracking(s_id, strategy, source_layer) ├── Validate session ID is valid ├── Check no tracking already running ├── Validate source layer (A or B only), seeding missing B frames ├── Clear Layer C/D (immutable/editable tracking layers) ├── Create TrackingWorker with source data └──> Start worker in background thread

Error Handling: Raises InvalidSessionIdException if session ID is invalid. Raises TrackingWorkerAlreadyRunningException if tracking already running. Raises UnsupportedLayerException if source layer is C or D (immutable). Raises EmptyLayerException if source layer has no detections.

Side Effects: Clears DataLayer.C and DataLayer.D to prepare for new tracking. Creates and starts TrackingWorker thread.

sync_tracking_cache(s_id: SessionId) -> None

Synchronize tracking results from worker to DataLayer.C (immutable tracking output).

PARAMETER DESCRIPTION
s_id

Session ID.

TYPE: SessionId

Note

Called after TrackingWorker finishes processing all frames. Fetches tracking results from worker (dict of frame_index → [boxes]). Overwrites DataLayer.C with post-processed tracking output. Uninitialized DataLayer.D frames are eagerly seeded with the current filter.

Layer Updates: Layer.C — Updated with post-processed tracking output (immutable). Layer.D — Seeded for uninitialized frames while preserving existing edits.

Error Handling: Raises InvalidSessionIdException if session ID invalid. Raises TrackingWorkerNotFoundException if no worker exists for session.

Side Effects: Overwrites all of DataLayer.C with new tracking data. Preserves initialized DataLayer.D frames (including user edits).