src/utils/frame_result.py

"""
Frame result factory for creating standardized detection result dictionaries.

This module provides a factory function for creating frame-level detection results
used in both sequential and parallel processing pipelines.

These utilities are shared across:
- pipeline/parallel.py
- pipeline/play_extractor.py
"""

from typing import Any, Dict, Optional, Tuple


def create_frame_result(
    timestamp: float,
    scorebug_detected: bool,
    scorebug_bbox: Optional[Tuple[int, int, int, int]] = None,
    home_timeouts: Optional[int] = None,
    away_timeouts: Optional[int] = None,
    clock_value: Optional[int] = None,
    clock_detected: bool = False,
) -> Dict[str, Any]:
    """
    Create a standardized frame detection result dictionary.

    This factory function ensures consistent structure for frame results
    across both sequential and parallel processing pipelines.

    Args:
        timestamp: Frame timestamp in seconds.
        scorebug_detected: Whether scorebug was detected in this frame.
        scorebug_bbox: Scorebug bounding box (x, y, w, h) if detected.
        home_timeouts: Number of home team timeouts remaining.
        away_timeouts: Number of away team timeouts remaining.
        clock_value: Detected play clock value (0-40).
        clock_detected: Whether clock value was successfully read.

    Returns:
        Dictionary with frame detection results.
    """
    return {
        "timestamp": timestamp,
        "scorebug_detected": scorebug_detected,
        "scorebug_bbox": scorebug_bbox,
        "home_timeouts": home_timeouts,
        "away_timeouts": away_timeouts,
        "clock_value": clock_value,
        "clock_detected": clock_detected,
    }