annie.media.compose
===================

.. py:module:: annie.media.compose

.. autoapi-nested-parse::

   Compose a video's vdet and track annotations into per-frame overlays (service).

   A :class:`~annie.models.VideoEntry` aggregates one video's raw detections and all
   of its tracks. To draw a frame we merge the relevant boxes into a single
   :class:`~annie.models.FrameAnnotation`, then hand it to
   :func:`annie.color.draw_overlay`, which colours each box by the standing rules:

   * vdet boxes (``track_id is None``) → flat **blue**;
   * track boxes → a **stable unique colour** per track id (never blue/green);
   * the **active / protagonist** track → **green**, overriding its palette colour.

   Two inclusion modes are used: the Browse five-frame **strip** shows vdet + only
   the active track; the full **render** shows vdet + every track.



Functions
---------

.. autoapisummary::

   annie.media.compose.load_entry_annotations
   annie.media.compose.merge_frame
   annie.media.compose.strip_track_ids


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

.. py:function:: load_entry_annotations(entry: annie.core.models.VideoEntry) -> tuple[dict[int, annie.core.models.FrameAnnotation], dict[int, dict[int, annie.core.models.FrameAnnotation]]]

   Load and index a video's vdet and track annotations by frame.

   :param entry: The video whose annotation files to read.

   :returns: A ``(vdet_by_frame, tracks_by_id)`` pair where ``vdet_by_frame`` maps a
             frame index to its raw detections, and ``tracks_by_id`` maps each track id
             to its own ``frame_index -> FrameAnnotation`` mapping.


.. py:function:: merge_frame(frame_idx: int, vdet_by_frame: dict[int, annie.core.models.FrameAnnotation], tracks_by_id: dict[int, dict[int, annie.core.models.FrameAnnotation]], include_track_ids: list[int]) -> annie.core.models.FrameAnnotation

   Combine vdet and selected track boxes for one frame.

   :param frame_idx: The frame to assemble.
   :param vdet_by_frame: Per-frame raw detections (from :func:`load_entry_annotations`).
   :param tracks_by_id: Per-track per-frame annotations (from :func:`load_entry_annotations`).
   :param include_track_ids: Which track ids to include on this frame.

   :returns: A single :class:`~annie.models.FrameAnnotation` holding the vdet boxes
             followed by the selected track boxes present on that frame.


.. py:function:: strip_track_ids(entry: annie.core.models.VideoEntry) -> list[int]

   Track ids to draw on the Browse strip: just the active one, if any.

   :param entry: The video being shown.

   :returns: ``[active_track_id]`` when a protagonist is assigned, else ``[]``.