"""Dense action annotations (``annotations/vX/sY.json``, v1.1 human-reviewed). Each file is ``{"segments": [{"timestamp": "HH:MM:SS-HH:MM:SS", "action_annotation": {"action_name", "object_name", "hand_type", ...}}, ...]}``. Timestamps are seconds from the start of the aligned recording. Malformed timestamps raise instead of silently becoming 0. """ from __future__ import annotations import json from dataclasses import dataclass from pathlib import Path from typing import List, Optional, Tuple from ..paths import DataRoot class AnnotationError(ValueError): pass def parse_time(ts: str) -> float: """``'HH:MM:SS'``, ``'MM:SS'`` (fractional seconds allowed) -> seconds.""" parts = ts.strip().split(":") try: if len(parts) == 3: return float(parts[0]) * 3600 + float(parts[1]) * 60 + float(parts[2]) if len(parts) == 2: return float(parts[0]) * 60 + float(parts[1]) except ValueError: pass raise AnnotationError(f"malformed time {ts!r}") def parse_range(ts_range: str) -> Tuple[float, float]: if not isinstance(ts_range, str) or "-" not in ts_range: raise AnnotationError(f"malformed timestamp range {ts_range!r}") a, b = ts_range.split("-", 1) start, end = parse_time(a), parse_time(b) if end < start: raise AnnotationError(f"timestamp range ends before it starts: {ts_range!r}") return start, end @dataclass(frozen=True) class Segment: rid: str index: int start_sec: float end_sec: float verb: Optional[str] noun: Optional[str] hand: Optional[str] raw: dict @property def duration_sec(self) -> float: return self.end_sec - self.start_sec def load_segments_file(path: Path, rid: str) -> List[Segment]: with open(path, encoding="utf-8") as f: d = json.load(f) if not isinstance(d, dict) or not isinstance(d.get("segments"), list): raise AnnotationError(f"{path}: expected an object with a 'segments' list") out = [] for i, s in enumerate(d["segments"]): a = s.get("action_annotation") or {} start, end = parse_range(s.get("timestamp", "")) out.append(Segment(rid, i, start, end, a.get("action_name"), a.get("object_name"), a.get("hand_type"), a)) return out def load_segments(dr: DataRoot, rid: str) -> List[Segment]: return load_segments_file(dr.annotation_path(rid, must_exist=True), rid)