annie.dataset.corrections
=========================

.. py:module:: annie.dataset.corrections

.. autoapi-nested-parse::

   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
   (:mod:`annie.parsers.participants`) and the geometric hit-test
   (:mod:`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; :func:`hit_test_frame` maps the click to a ``track_id``;
   :func:`set_active_track` persists it (manual ``_manual`` sibling, upsert by uuid);
   the frames are re-rendered so the new active track shows green.



Functions
---------

.. autoapisummary::

   annie.dataset.corrections.manual_sibling
   annie.dataset.corrections.export_active_tracks
   annie.dataset.corrections.resolve_active_track
   annie.dataset.corrections.set_active_track
   annie.dataset.corrections.export_corrected
   annie.dataset.corrections.hit_test_frame


Module Contents
---------------

.. py:function:: manual_sibling(heuristic_path: str | pathlib.Path) -> pathlib.Path

   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.

   :param heuristic_path: The protagonist source CSV.

   :returns: The sibling manual-corrections CSV path.


.. py:function:: 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

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

   :param out_path: Destination CSV path (parent directories are created).
   :param mapping: The corrections to write, keyed by video id.
   :param key_column: Header for the video-id column.
   :param value_column: Header for the track-id column.

   :returns: The path written.


.. py:function:: 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

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

   :param uuid: The video id to look up.
   :param heuristic_file: The protagonist source CSV. Defaults to the configured
                          ``participants_file``.
   :param key_column: The column holding the video id.
   :param value_column: The column holding the track index.

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


.. py:function:: 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

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

   :param uuid: The video id being corrected.
   :param track_id: The newly chosen active track index.
   :param heuristic_file: The protagonist source CSV (defines where the ``_manual``
                          sibling lives). Defaults to the configured ``participants_file``.
   :param key_column: The column holding the video id.
   :param value_column: The column holding the track index.

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


.. py:function:: 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

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

   :param out_path: Destination CSV path.
   :param heuristic_file: The protagonist source CSV. Defaults to the configured
                          ``participants_file``.
   :param key_column: The column holding the video id.
   :param value_column: The column holding the track index.

   :returns: The path written.


.. py:function:: hit_test_frame(click_xy: tuple[int, int], annotation: annie.core.models.FrameAnnotation, *, smallest_wins: bool = True) -> int | None

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

   :param click_xy: The ``(x, y)`` click position in image-pixel space.
   :param annotation: The boxes drawn on the clicked frame.
   :param 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.