annie.parsers.base

Shared CSV schema and the parser protocol.

Both .vdet and .track files use one identical 17-column schema with a header row and CRLF line endings:

frame_id, source, score, x, y, w, h, left_eye_x, left_eye_y, right_eye_x, right_eye_y, nose_x, nose_y, left_mouth_x, left_mouth_y, right_mouth_x, right_mouth_y

The source column is informational only — matching is done by file stem, not by this path (it points at the original capture location, which need not exist).

Attributes

CSV_COLUMNS

The 17 columns of the shared detection/track CSV schema, in order.

Classes

AnnotationParser

Protocol implemented by every annotation loader.

Functions

read_csv_rows(→ list[dict[str, str]])	Read a shared-schema CSV into a list of column-keyed dict rows.
parse_bbox_row(→ annie.core.models.BBox)	Build a BBox from one CSV row.
group_rows_by_frame(...)	Group flat CSV rows into per-frame annotations, sorted by frame index.

Module Contents

annie.parsers.base.CSV_COLUMNS: tuple[str, ...] = ('frame_id', 'source', 'score', 'x', 'y', 'w', 'h', 'left_eye_x', 'left_eye_y', 'right_eye_x',...

The 17 columns of the shared detection/track CSV schema, in order.

class annie.parsers.base.AnnotationParser

Bases: Protocol

Protocol implemented by every annotation loader.

A parser turns a path into a list of FrameAnnotation, one entry per distinct frame_id it contains.

__call__(path: str | pathlib.Path) → list[annie.core.models.FrameAnnotation]

Parse path into per-frame annotations.

Parameters:

path – Path to the annotation file.

Returns:

One FrameAnnotation per distinct frame index.

annie.parsers.base.read_csv_rows(path: str | pathlib.Path) → list[dict[str, str]]

Read a shared-schema CSV into a list of column-keyed dict rows.

Tolerant of both CRLF and LF line endings (newline="" lets csv handle either) and of a UTF-8 BOM. The header row is required and is used as the dict keys.

Parameters:

path – Path to the CSV file.

Returns:

One dict per data row, keyed by column name.

Raises:

FileNotFoundError – If path does not exist.

annie.parsers.base.parse_bbox_row(row: dict[str, str], track_id: int | None = None) → annie.core.models.BBox

Build a BBox from one CSV row.

Parameters:

• row – A column-keyed dict as produced by read_csv_rows().

• track_id – The owning track id to stamp onto the box, or None for a raw detection.

Returns:

The parsed bounding box, with its five named landmarks populated.

annie.parsers.base.group_rows_by_frame(rows: list[dict[str, str]], track_id: int | None = None) → list[annie.core.models.FrameAnnotation]

Group flat CSV rows into per-frame annotations, sorted by frame index.

Multiple rows sharing a frame_id (possible in a .vdet) collapse into a single FrameAnnotation carrying all their boxes.

Parameters:

• rows – Column-keyed CSV rows from read_csv_rows().

• track_id – Track id to stamp on every box, or None for raw detections.

Returns:

Per-frame annotations ordered by ascending frame_idx.