Unified Layer Service

app.application.services.unified_layer_service

View source code

Unified layer service facade for cross-layer operations.

See Also

• DetectionLayerService — manages detection-layer operations
• TrackingLayerService — manages tracking-layer operations

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

UnifiedLayerService

Facade service that coordinates operations across all four detection layers.

Responsibilities:

• Route operations to the appropriate layer service (Detection or Tracking).
• Provide a unified interface for layer-agnostic operations.
• Handle compatibility seeding of editable layers from immutable sources.
• Prevent operations on immutable layers (A, C).
• Seed editable layers eagerly for new results and lazily for older sessions.

Note

• Delegates to DetectionLayerService for DataLayer.B/DataLayer.A operations.
• Delegates to TrackingLayerService for DataLayer.D/DataLayer.C operations.
• Does operations by itself for redundant tasks (e.g., copying boxes between frames).
• Retains JIT seeding as a compatibility path for sessions with older data.
• Protects immutable layers from user modifications.

Layer Seeding:

• Older sessions seed missing DataLayer.B frames from DataLayer.A on-demand.
• Older sessions seed missing DataLayer.D frames from DataLayer.C on-demand.
• User edits to B/D are persistent (don't re-seed on next access).

Layer Mapping:

• Detection Tab ↔ DataLayer.B (editable, seeded from DataLayer.A).
• Tracking Tab ↔ DataLayer.D (editable, seeded from DataLayer.C).

PARAMETER	DESCRIPTION
app	Application providing detection/tracking layer services and session access for this facade. TYPE: Application

detection_layer_svc = app.detection_layer_svc instance-attribute

tracking_layer_svc = app.tracking_layer_svc instance-attribute

__init__(app: Application)

add_manual_boxes_to_current_frame(s_id: SessionId, tab: VideoDataLayerGroup, boxes: Iterable[tuple[str, BBoxXYXYTuple, str]]) -> list[str]

Create clipboard boxes as manual boxes in Detection or Tracking editable layers.

PARAMETER	DESCRIPTION
s_id	Identifier of the session receiving the boxes. TYPE: SessionId
tab	Detection or tracking tab, selecting editable layer B or D. TYPE: VideoDataLayerGroup
boxes	Tuples of (label, coordinates, color_hex) for new boxes. TYPE: Iterable[tuple[str, BBoxXYXYTuple, str]]

RETURNS	DESCRIPTION
list[str]	Keys assigned to the newly created manual boxes.

apply_filters_to_layer_by_layer(layer_name: VideoDataLayer, s_id: SessionId) -> int

Refilter layer DataLayer.B or DataLayer.D based on current session settings.

PARAMETER	DESCRIPTION
layer_name	Layer to apply filters to (DataLayer.B or DataLayer.D). TYPE: VideoDataLayer
s_id	Session ID. TYPE: SessionId

RETURNS	DESCRIPTION
int	Number of frames where filtering changed the detection count. TYPE: int

change_xyxy_for_boxes_at_current_idx_by_keys_and_dxdy(s_id: SessionId, layer_name: VideoDataLayer, item_keys: Iterable[str], dx: int, dy: int) -> int

Translate selected boxes on the current frame by a pixel offset.

PARAMETER	DESCRIPTION
s_id	Identifier of the session to update. TYPE: SessionId
layer_name	Editable layer containing the boxes. TYPE: VideoDataLayer
item_keys	Keys of the boxes to move. TYPE: Iterable[str]
dx	Horizontal translation in pixels. TYPE: int
dy	Vertical translation in pixels. TYPE: int

RETURNS	DESCRIPTION
int	Number of boxes moved.

copy_boxes_to_adjacent_frame_by_direction(s_id: SessionId, layer_name: VideoDataLayer, item_keys: Iterable[str], direction: Direction) -> None

Copy boxes to the adjacent frame (next or previous).

PARAMETER	DESCRIPTION
s_id	Session ID. TYPE: SessionId
layer_name	Layer to copy from (DataLayer.B or DataLayer.D). TYPE: VideoDataLayer
item_keys	Iterable of detection keys to copy. TYPE: Iterable[str]
direction	Direction.NEXT or Direction.PREV. TYPE: Direction

RAISES	DESCRIPTION
ValueError	If the layer is immutable (A or C) or direction is unsupported.

delete_boxes_by_keys_and_tab_id_for_current_frame_by_session_id(s_id: SessionId, keys: list[str], tab: VideoDataLayerGroup) -> None

Delete boxes from the current frame in the active tab (Detection or Tracking).

PARAMETER	DESCRIPTION
s_id	Session ID. TYPE: SessionId
keys	List of detection keys to delete. TYPE: list[str]
tab	DataBox.DETECTION or DataBox.TRACKING. TYPE: VideoDataLayerGroup

get_layer_box_by_key(s_id: SessionId, layer_name: VideoDataLayer, key: str) -> BBoxViewModel | None

Find a box by key in the specified layer at the current frame.

PARAMETER	DESCRIPTION
s_id	Identifier of the session to query. TYPE: SessionId
layer_name	Editable layer B or D to search. TYPE: VideoDataLayer
key	Unique key of the box to find. TYPE: str

RETURNS	DESCRIPTION
BBoxViewModel | None	Matching box view model, or None when no box has that key.

RAISES	DESCRIPTION
UnsupportedLayerOperationException	If layer_name is immutable or unsupported.

get_tab_frame_boxes_at_frame_index(s_id: SessionId, tab: VideoDataLayerGroup, frame_index: int) -> list[BBoxViewModel]

Return cloned editable-layer boxes without changing playback state.

PARAMETER	DESCRIPTION
s_id	Identifier of the session to query. TYPE: SessionId
tab	Detection or tracking tab selecting editable layer B or D. TYPE: VideoDataLayerGroup
frame_index	Zero-based frame index to query. TYPE: int

RETURNS	DESCRIPTION
list[BBoxViewModel]	Clones of the boxes stored in the selected editable layer and frame.

get_tab_frame_boxes_for_session_id(s_id: SessionId, tab: VideoDataLayerGroup) -> FrameBoxesViewModel

Return boxes for the session's current frame in the selected tab.

PARAMETER	DESCRIPTION
s_id	Identifier of the session to query. TYPE: SessionId
tab	Detection or tracking tab to read. TYPE: VideoDataLayerGroup

RETURNS	DESCRIPTION
FrameBoxesViewModel	View model containing boxes from editable layer B or D.

RAISES	DESCRIPTION
UnsupportedTabException	If tab is not a supported data tab.

Note

When an editable-layer frame has not yet been initialized, it may be seeded from its corresponding source layer (A or C).

replace_tab_frame_boxes(s_id: SessionId, tab: VideoDataLayerGroup, frame_index: int, boxes: list[BBoxViewModel]) -> None

Replace one editable frame with cloned history snapshot boxes.

PARAMETER	DESCRIPTION
s_id	Identifier of the session whose frame is being restored. TYPE: SessionId
tab	Detection or tracking tab selecting editable layer B or D. TYPE: VideoDataLayerGroup
frame_index	Zero-based frame index to replace. TYPE: int
boxes	Snapshot boxes to clone into that frame. TYPE: list[BBoxViewModel]

reset_all_for_layer(s_id: SessionId, layer_name: VideoDataLayer) -> None

Rebuild an editable layer from its source layer across all frames.

PARAMETER	DESCRIPTION
s_id	Identifier of the session to update. TYPE: SessionId
layer_name	Editable layer B or D to rebuild from A or C. TYPE: VideoDataLayer

RAISES	DESCRIPTION
ImmutableLayerOperationException	If the requested layer is immutable.
UnsupportedLayerOperationException	If the layer is unsupported.

reset_frame_for_layer(s_id: SessionId, layer_name: VideoDataLayer, frame_index: int) -> None

Rebuild one editable-layer frame from its corresponding source frame.

PARAMETER	DESCRIPTION
s_id	Identifier of the session to update. TYPE: SessionId
layer_name	Editable layer B or D to rebuild. TYPE: VideoDataLayer
frame_index	Zero-based frame index to reset. TYPE: int

RAISES	DESCRIPTION
ImmutableLayerOperationException	If the requested layer is immutable.
UnsupportedLayerOperationException	If the layer is unsupported.

update_current_frame_box_xyxy(s_id: SessionId, layer_name: VideoDataLayer, item_key: str, label: str, bbox_xyxy: BBoxXYXYTuple) -> None

Update a box's label and coordinates on the current frame.

PARAMETER	DESCRIPTION
s_id	Identifier of the session containing the box. TYPE: SessionId
layer_name	Layer containing the box. TYPE: VideoDataLayer
item_key	Unique key identifying the box. TYPE: str
label	Replacement classification label. TYPE: str
bbox_xyxy	Replacement (x1, y1, x2, y2) coordinates. TYPE: BBoxXYXYTuple

RAISES	DESCRIPTION
UnknownFrameItemException	If no box with item_key exists on the current frame.