Session Data Store Interface

app.application.interfaces.session.session_data_store_interface

Protocol for frame-indexed annotation storage owned by a video session.

Layer: Application interface. Context: The application depends on this data-only contract rather than the infrastructure store; operations address domain layers and per-frame boxes.

`SessionDataStoreInterface`

Bases: Protocol

Contract for reading and mutating a session's annotation layers.

Layer: Application interface. Context: Defines the storage seam used by application services; the backing adapter enforces persistence, locking, and layer mutation rules.

`add_box_to_layer_at_frame_index(layer: VideoDataLayer, frame_index: int, box: BBoxViewModel) -> None`

Add one box to a layer at the given frame.

PARAMETER	DESCRIPTION
`layer`	Destination domain layer. TYPE: `VideoDataLayer`
`frame_index`	Zero-based frame index. TYPE: `int`
`box`	Box view model to store. TYPE: `BBoxViewModel`

`add_boxes_to_layer_at_frame_index(layer: VideoDataLayer, frame_index: int, boxes: Iterable[BBoxViewModel]) -> None`

Add multiple boxes to a layer at the given frame.

PARAMETER	DESCRIPTION
`layer`	Destination domain layer. TYPE: `VideoDataLayer`
`frame_index`	Zero-based frame index. TYPE: `int`
`boxes`	Boxes to append to the frame's stored annotations. TYPE: `Iterable[BBoxViewModel]`

`apply_filters_to_layers(source_layer_name: VideoDataLayer, target_layer_name: VideoDataLayer, session_settings: ProcessingSettings) -> int`

Apply session filters from a source layer to its target layer.

PARAMETER	DESCRIPTION
`source_layer_name`	Layer providing boxes for filtering. TYPE: `VideoDataLayer`
`target_layer_name`	Layer receiving retained boxes. TYPE: `VideoDataLayer`
`session_settings`	Confidence and processing settings to apply. TYPE: `ProcessingSettings`

RETURNS	DESCRIPTION
`int`	Number of frames whose target-layer box count changed.

`clear_all_layers(keep_manual: bool = False) -> None`

Clear all layers, optionally retaining editable manual annotations.

PARAMETER	DESCRIPTION
`keep_manual`	When true, retain manual boxes in editable layers B/D. Raw layers A/C are cleared. TYPE: `bool` DEFAULT: `False`

`clear_layer_by_name(layer: VideoDataLayer, keep_manual: bool = False) -> None`

Clear one layer, optionally retaining manual annotations.

PARAMETER	DESCRIPTION
`layer`	Layer to clear. TYPE: `VideoDataLayer`
`keep_manual`	When true, retain manual boxes in the selected layer. TYPE: `bool` DEFAULT: `False`

`clear_layers_by_name(layers: list[VideoDataLayer]) -> None`

Clear each named layer.

PARAMETER	DESCRIPTION
`layers`	Domain layers to clear. TYPE: `list[VideoDataLayer]`

`delete_boxes_from_layer_by_id(layer: VideoDataLayer, box_ids: Iterable[str]) -> None`

Delete boxes with matching identifiers throughout a layer.

PARAMETER	DESCRIPTION
`layer`	Layer to update. TYPE: `VideoDataLayer`
`box_ids`	Identifiers of boxes to remove. TYPE: `Iterable[str]`

`delete_boxes_from_layer_by_id_at_frame_index(layer: VideoDataLayer, box_ids: Iterable[str], frame_index: int) -> bool`

Delete matching boxes from one frame.

PARAMETER	DESCRIPTION
`layer`	Layer to update. TYPE: `VideoDataLayer`
`box_ids`	Identifiers of boxes to remove. TYPE: `Iterable[str]`
`frame_index`	Zero-based frame index. TYPE: `int`

RETURNS	DESCRIPTION
`bool`	Whether at least one matching box was deleted.

`get_all_boxes_for_layer_as_dict_of_lists(layer: VideoDataLayer) -> dict[int, ListOfBoxes]`

Return a layer's frame-indexed box lists.

PARAMETER	DESCRIPTION
`layer`	Domain layer to read. TYPE: `VideoDataLayer`

RETURNS	DESCRIPTION
`dict[int, ListOfBoxes]`	The store's frame-indexed mapping for that layer, including any
`dict[int, ListOfBoxes]`	initialized empty frames.

Note

Implementations may expose the backing mapping rather than a copy; callers should use the mutation methods in this protocol.

`get_boxes_for_layer_at_frame_index_as_list(layer: VideoDataLayer, frame_index: int) -> ListOfBoxes`

Return the boxes stored for one layer and frame.

PARAMETER	DESCRIPTION
`layer`	Domain layer to read. TYPE: `VideoDataLayer`
`frame_index`	Zero-based frame whose boxes are requested. TYPE: `int`

RETURNS	DESCRIPTION
`ListOfBoxes`	Boxes for the frame, or an empty list when no frame data exists.

`has_boxes_for_layer(layer: VideoDataLayer) -> bool`

Check whether a layer contains any boxes.

PARAMETER	DESCRIPTION
`layer`	Domain layer to inspect. TYPE: `VideoDataLayer`

RETURNS	DESCRIPTION
`bool`	`True` when at least one box is stored.

`has_boxes_for_layer_at_frame_index(layer: VideoDataLayer, frame_index: int) -> bool`

Check whether a layer contains boxes at a particular frame.

PARAMETER	DESCRIPTION
`layer`	Domain layer to inspect. TYPE: `VideoDataLayer`
`frame_index`	Zero-based frame index. TYPE: `int`

RETURNS	DESCRIPTION
`bool`	`True` when the frame contains at least one box.

`has_frame_for_layer_at_frame_index(layer: VideoDataLayer, frame_index: int) -> bool`

Check whether a frame entry exists for a layer, even if it is empty.

PARAMETER	DESCRIPTION
`layer`	Domain layer to inspect. TYPE: `VideoDataLayer`
`frame_index`	Zero-based frame index. TYPE: `int`

RETURNS	DESCRIPTION
`bool`	`True` when storage has an entry for that layer and frame.

`move_boxes_in_layer_at_frame_index_by_delta(layer: VideoDataLayer, frame_index: int, keys: set[str], delta_x: float, delta_y: float) -> int`

Translate selected boxes in a frame by a coordinate delta.

PARAMETER	DESCRIPTION
`layer`	Layer containing the selected boxes. TYPE: `VideoDataLayer`
`frame_index`	Zero-based frame index. TYPE: `int`
`keys`	Box keys identifying the boxes to move. TYPE: `set[str]`
`delta_x`	Horizontal translation in frame coordinates. TYPE: `float`
`delta_y`	Vertical translation in frame coordinates. TYPE: `float`

RETURNS	DESCRIPTION
`int`	Number of boxes moved.

`move_manual_boxes_in_layer_at_frame_index_by_delta(layer: VideoDataLayer, frame_index: int, keys: set[str], delta_x: float, delta_y: float) -> int`

Translate selected manual boxes while leaving machine boxes unchanged.

PARAMETER	DESCRIPTION
`layer`	Layer containing the selected boxes. TYPE: `VideoDataLayer`
`frame_index`	Zero-based frame index. TYPE: `int`
`keys`	Box keys identifying the boxes to move. TYPE: `set[str]`
`delta_x`	Horizontal translation in frame coordinates. TYPE: `float`
`delta_y`	Vertical translation in frame coordinates. TYPE: `float`

RETURNS	DESCRIPTION
`int`	Number of manual boxes moved.

`overwrite_layer_at_index_with_boxes(layer: VideoDataLayer, frame_index: int, boxes: ListOfBoxes) -> None`

Replace all boxes for one frame in a layer.

PARAMETER	DESCRIPTION
`layer`	Layer to update. TYPE: `VideoDataLayer`
`frame_index`	Zero-based frame index. TYPE: `int`
`boxes`	Replacement box list. TYPE: `ListOfBoxes`

`overwrite_layer_with_dict_of_boxes(layer: VideoDataLayer, boxes_dict: dict[int, ListOfBoxes]) -> None`

Replace a layer's complete frame-to-box mapping.

PARAMETER	DESCRIPTION
`layer`	Layer whose stored data is replaced. TYPE: `VideoDataLayer`
`boxes_dict`	Replacement boxes keyed by zero-based frame index. TYPE: `dict[int, ListOfBoxes]`

`overwrite_source_layer_to_target_layer(source_layer: VideoDataLayer, target_layer: VideoDataLayer, filter_fn: Callable[[BBoxViewModel], bool] | None = None) -> None`

Replace target-layer content with source boxes, optionally filtered.

PARAMETER	DESCRIPTION
`source_layer`	Layer providing replacement boxes. TYPE: `VideoDataLayer`
`target_layer`	Layer whose content is overwritten. TYPE: `VideoDataLayer`
`filter_fn`	Optional predicate selecting boxes to copy. TYPE: `Callable[[BBoxViewModel], bool] \| None` DEFAULT: `None`

`overwrite_source_to_target_layer_at_index(source_layer: VideoDataLayer, target_layer: VideoDataLayer, index: int) -> None`

Replace target-layer boxes at one frame with source-layer boxes.

PARAMETER	DESCRIPTION
`source_layer`	Layer whose frame data is copied. TYPE: `VideoDataLayer`
`target_layer`	Layer whose frame data is replaced. TYPE: `VideoDataLayer`
`index`	Zero-based frame index. TYPE: `int`

`purge_boxes_in_layer_by_minimum_confidence(layer: VideoDataLayer, min_conf: float) -> None`

Remove low-confidence machine boxes from every frame.

PARAMETER	DESCRIPTION
`layer`	Layer whose data is filtered. TYPE: `VideoDataLayer`
`min_conf`	Minimum confidence retained; manual boxes and boxes with no confidence value are preserved. TYPE: `float`

`purge_boxes_in_layer_by_minimum_confidence_at_frame_index(layer: VideoDataLayer, min_conf: float, frame_index: int) -> None`

Remove low-confidence machine boxes from one frame.

PARAMETER	DESCRIPTION
`layer`	Layer whose frame data is filtered. TYPE: `VideoDataLayer`
`min_conf`	Minimum confidence retained; manual boxes and boxes with no confidence value are preserved. TYPE: `float`
`frame_index`	Zero-based frame index to filter. TYPE: `int`

`replace_machine_boxes_at_frame_index(layer: VideoDataLayer, frame_index: int, boxes: Iterable[BBoxViewModel], filter_fn: Callable[[BBoxViewModel], bool] | None = None) -> None`

Replace machine output for one frame while preserving manual boxes.

PARAMETER	DESCRIPTION
`layer`	Target layer whose machine boxes are refreshed. TYPE: `VideoDataLayer`
`frame_index`	Zero-based frame index. TYPE: `int`
`boxes`	Candidate machine-produced boxes for the frame. TYPE: `Iterable[BBoxViewModel]`
`filter_fn`	Optional predicate applied before boxes are cloned. TYPE: `Callable[[BBoxViewModel], bool] \| None` DEFAULT: `None`

`replace_machine_boxes_for_frames(layer: VideoDataLayer, boxes_by_frame: dict[int, ListOfBoxes], frame_count: int, filter_fn: Callable[[BBoxViewModel], bool] | None = None) -> None`

Refresh machine output over a frame range under one storage lock.

PARAMETER	DESCRIPTION
`layer`	Target layer whose machine boxes are refreshed. TYPE: `VideoDataLayer`
`boxes_by_frame`	Candidate machine boxes keyed by frame index. TYPE: `dict[int, ListOfBoxes]`
`frame_count`	Number of frames to refresh, from 0 up to but excluding this value. TYPE: `int`
`filter_fn`	Optional predicate applied before boxes are cloned. TYPE: `Callable[[BBoxViewModel], bool] \| None` DEFAULT: `None`