annie.dataset.corrections

Protagonist correction service.

This is the service surface the UI uses to read and fix which track is the active “protagonist” of a video. It composes the domain-level participant resolver (annie.parsers.participants) and the geometric hit-test (annie.color) so the UI never reaches past the service layer.

The correction flow: the annotator clicks the true protagonist on one of the five highlighted frames; hit_test_frame() maps the click to a track_id; set_active_track() persists it (manual _manual sibling, upsert by uuid); the frames are re-rendered so the new active track shows green.

Functions

manual_sibling(→ pathlib.Path)

The _manual CSV path for a protagonist source, next to the heuristic file.

export_active_tracks(→ pathlib.Path)

Write a video_id -> track_id correction mapping as a two-column CSV.

resolve_active_track(→ int)

Resolve a video's active track id (manual ▸ source ▸ -1).

set_active_track(→ pathlib.Path)

Persist a manual protagonist correction (upsert by video id).

export_corrected(→ pathlib.Path)

Export the resolved (manual ▸ source) protagonist mapping to a CSV.

hit_test_frame(→ int | None)

Map a click on a frame to the enclosing box's track_id.

Module Contents

annie.dataset.corrections.manual_sibling(heuristic_path: str | pathlib.Path) → pathlib.Path[source]

The _manual CSV path for a protagonist source, next to the heuristic file.

protagonist_track_heuristic.csv → protagonist_track_manual.csv; any other name gets a _manual suffix. This is where the Annotator exports its DB-stored corrections.

Parameters:

heuristic_path – The protagonist source CSV.

Returns:

The sibling manual-corrections CSV path.

annie.dataset.corrections.export_active_tracks(out_path: str | pathlib.Path, mapping: collections.abc.Mapping[str, int], key_column: str = DEFAULT_KEY_COLUMN, value_column: str = DEFAULT_VALUE_COLUMN) → pathlib.Path[source]

Write a video_id -> track_id correction mapping as a two-column CSV.

Parameters:

  • out_path – Destination CSV path (parent directories are created).

  • mapping – The corrections to write, keyed by video id.

  • key_column – Header for the video-id column.

  • value_column – Header for the track-id column.

Returns:

The path written.

annie.dataset.corrections.resolve_active_track(uuid: str, heuristic_file: str | pathlib.Path | None = None, key_column: str = DEFAULT_KEY_COLUMN, value_column: str = DEFAULT_VALUE_COLUMN) → int[source]

Resolve a video’s active track id (manual ▸ source ▸ -1).

Parameters:

  • uuid – The video id to look up.

  • heuristic_file – The protagonist source CSV. Defaults to the configured participants_file.

  • key_column – The column holding the video id.

  • value_column – The column holding the track index.

Returns:

The active track index, or -1 when none applies.

annie.dataset.corrections.set_active_track(uuid: str, track_id: int, heuristic_file: str | pathlib.Path | None = None, key_column: str = DEFAULT_KEY_COLUMN, value_column: str = DEFAULT_VALUE_COLUMN) → pathlib.Path[source]

Persist a manual protagonist correction (upsert by video id).

Parameters:

  • uuid – The video id being corrected.

  • track_id – The newly chosen active track index.

  • heuristic_file – The protagonist source CSV (defines where the _manual sibling lives). Defaults to the configured participants_file.

  • key_column – The column holding the video id.

  • value_column – The column holding the track index.

Returns:

The path to the manual-correction file that was written.

annie.dataset.corrections.export_corrected(out_path: str | pathlib.Path, heuristic_file: str | pathlib.Path | None = None, key_column: str = DEFAULT_KEY_COLUMN, value_column: str = DEFAULT_VALUE_COLUMN) → pathlib.Path[source]

Export the resolved (manual ▸ source) protagonist mapping to a CSV.

Parameters:

  • out_path – Destination CSV path.

  • heuristic_file – The protagonist source CSV. Defaults to the configured participants_file.

  • key_column – The column holding the video id.

  • value_column – The column holding the track index.

Returns:

The path written.

annie.dataset.corrections.hit_test_frame(click_xy: tuple[int, int], annotation: annie.core.models.FrameAnnotation, *, smallest_wins: bool = True) → int | None[source]

Map a click on a frame to the enclosing box’s track_id.

Parameters:

  • click_xy – The (x, y) click position in image-pixel space.

  • annotation – The boxes drawn on the clicked frame.

  • smallest_wins – Tie-break toward the smallest enclosing box when True.

Returns:

The selected track_id, or None if the click hit no track box.