Annotation Handler

app.ui.handlers.annotation_handler

View source code

Annotation creation and editing handler for bounding detection management.

See Also

• AnnotationContextActions — describes supported annotation operations
• AnnotationOverlayWidget — captures box-editing interactions

Layer: Presentation. Context: Converts user actions and worker signals into application calls and UI feedback.

AnnotationHandler

Bases: QObject

Manages detection creation, editing, and deletion operations.

Responsibilities

• Handle manual bounding detection drawing and labeling.
• Edit existing annotations (move, resize, relabel).
• Delete annotations (single or in direction).
• Copy annotations to adjacent frames.
• Handle keyboard nudge commands for detection positioning.
• Route context menu actions (copy, delete in direction).

Note

Signal flow: Receives signals from the preview container (bbox drawn, edited, deleted). Receives signals from the bottom panel (edit, delete, copy buttons). Handles keyboard events for detection nudging with acceleration. Emits frame render requests after detection changes.

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

__init__(controller: UIController) -> None

PARAMETER	DESCRIPTION
controller	UIController supplying annotation mutations, selection widgets, and preview rendering. TYPE: UIController

copy_to_direction(direction: Direction, keys: list[str] | None = None) -> None

Copy the specified boxes to the adjacent frame in the selected direction.

PARAMETER	DESCRIPTION
direction	Direction.NEXT or Direction.PREV. TYPE: Direction
keys	Box keys to copy; defaults to the current selection. TYPE: list[str] | None DEFAULT: None

handle_delete_key(event: QKeyEvent) -> bool

Delete the current selection for an unmodified Delete key press.

PARAMETER	DESCRIPTION
event	Key event to inspect. TYPE: QKeyEvent

RETURNS	DESCRIPTION
bool	True if the key was Delete and was consumed, including when nothing is selected.

handle_existing_box_edit(s_id: SessionId, box_key: str, new_coords: BBoxXYXYTuple | None = None) -> None

Handles both visual drags (new_coords) and table 'Edit' clicks (dialog).

PARAMETER	DESCRIPTION
s_id	Identifier of the target session. TYPE: SessionId
box_key	Key of the existing box to update. TYPE: str
new_coords	Replacement (x1, y1, x2, y2) coordinates from a drag, or None to open the edit dialog. TYPE: BBoxXYXYTuple | None DEFAULT: None

handle_new_drawn_box(s_id: SessionId, x1: int, y1: int, x2: int, y2: int) -> None

Handles the addition of a new drawn box.

This function is triggered when a new box is drawn on the interface. It prompts the user to provide a label for the box via a dialog. If a valid label is provided and accepted, the function attempts to add the box, updates the user interface, and triggers the provided rendering function to refresh the box visually.

PARAMETER	DESCRIPTION
s_id	A unique identifier for the current session. TYPE: SessionId
x1	The x-coordinate of the top-left corner of the box. TYPE: int
y1	The y-coordinate of the top-left corner of the box. TYPE: int
x2	The x-coordinate of the bottom-right corner of the box. TYPE: int
y2	The y-coordinate of the bottom-right corner of the box. TYPE: int

handle_nudge_key(event: QKeyEvent) -> bool

Move selected boxes by one nudge increment for an unmodified arrow key.

PARAMETER	DESCRIPTION
event	Key event to inspect. TYPE: QKeyEvent

RETURNS	DESCRIPTION
bool	True if an arrow key was consumed; otherwise False.

handle_selection_shortcut(event: QKeyEvent) -> bool

Apply a supported Ctrl selection, history, clipboard, or cut shortcut.

PARAMETER	DESCRIPTION
event	Key event to inspect. TYPE: QKeyEvent

RETURNS	DESCRIPTION
bool	True if a supported Ctrl shortcut was handled; otherwise False.

on_copy_to_next() -> None

Copy selected annotations to the next frame.

on_copy_to_prev() -> None

Copy selected annotations to the previous frame.

on_delete_next_occurrences() -> None

Delete the selected boxes' later-frame occurrences.

on_delete_prev_occurrences() -> None

Delete the selected boxes' earlier-frame occurrences.

on_delete_selected() -> None

Delete the currently selected boxes.

Flow:

on_delete_selected() [this slot]: | | ├── Get selected session and detection keys | ├── Delete boxes from the active tab (Detection or Tracking) | └──> Render frame with updated boxes

on_edit_selected() -> None

Open edit dialog for the selected detection if exactly one detection is selected, allow user to modify label and coordinates.

on_preview_bbox_deleted(box_key: str) -> None

Delete the box from the active layer, update selection history, and rerender.

PARAMETER	DESCRIPTION
box_key	Key of the box to delete. TYPE: str

on_preview_bbox_drawn(x1: int, y1: int, x2: int, y2: int) -> None

Forward newly drawn preview coordinates to the selected session's annotation flow.

PARAMETER	DESCRIPTION
x1	Left coordinate of the drawn box. TYPE: int
y1	Top coordinate of the drawn box. TYPE: int
x2	Right coordinate of the drawn box. TYPE: int
y2	Bottom coordinate of the drawn box. TYPE: int

on_preview_bbox_edited(box_key: str, x1: int, y1: int, x2: int, y2: int) -> None

Forward edited preview coordinates to the selected session's annotation flow.

PARAMETER	DESCRIPTION
box_key	Key of the box being edited. TYPE: str
x1	Updated left coordinate. TYPE: int
y1	Updated top coordinate. TYPE: int
x2	Updated right coordinate. TYPE: int
y2	Updated bottom coordinate. TYPE: int

on_preview_bbox_marquee_selected(box_keys: list[str]) -> None

Add marquee-contained boxes to the current shared selection.

PARAMETER	DESCRIPTION
box_keys	Keys of boxes contained by the marquee rectangle. TYPE: list[str]

on_preview_bbox_selected(box_key: str) -> None

Handle canvas-originated selection and sync to table and shared state.

PARAMETER	DESCRIPTION
box_key	Key of the box selected on the preview canvas. TYPE: str

on_preview_bbox_selection_cleared() -> None

Clear shared selection after a click on empty canvas space.

on_preview_bbox_selection_requested(box_key: str, additive: bool) -> None

Apply a canvas click to the shared selection, toggling when Ctrl is held.

PARAMETER	DESCRIPTION
box_key	Key of the box clicked on the canvas. TYPE: str
additive	Whether the click toggles this box in the existing selection. TYPE: bool

on_preview_bboxes_moved(box_keys: list[str], dx: int, dy: int) -> None

Apply an overlay group-drag delta to every selected editable box.

PARAMETER	DESCRIPTION
box_keys	Keys of boxes moved by the drag. TYPE: list[str]
dx	Horizontal drag delta in image coordinates. TYPE: int
dy	Vertical drag delta in image coordinates. TYPE: int

on_preview_context_action(action: str, box_key: str) -> None

Apply the requested context-menu action to the target or selected boxes.

PARAMETER	DESCRIPTION
action	Context-action identifier emitted by the preview menu. TYPE: str
box_key	Box under the context menu, if any. TYPE: str

on_relabel_selected() -> None

Relabel the currently selected boxes using a dialog.

on_reset_all() -> None

Reset editable detection layer B across all frames and rerender the current frame.

on_reset_all_trackers() -> None

Reset editable tracking layer D across all frames and rerender the current frame.

on_reset_frame() -> None

Reset editable detection layer B on the current frame and rerender it.

on_reset_tracker_frame() -> None

Reset editable tracking layer D on the current frame and rerender it.