kinemotion 0.10.6__py3-none-any.whl → 0.67.0__py3-none-any.whl

kinemotion/core/debug_overlay_utils.py

@@ -0,0 +1,385 @@
+"""Shared debug overlay utilities for video rendering."""
+
+# pyright: reportCallIssue=false
+import os
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+from typing_extensions import Self
+
+from .timing import NULL_TIMER, Timer
+
+# Setup logging with structlog support for backend, fallback to standard logging for CLI
+try:
+    import structlog
+
+    logger = structlog.get_logger(__name__)
+    _using_structlog = True
+except ImportError:
+    import logging
+
+    logger = logging.getLogger(__name__)
+    _using_structlog = False
+
+
+def _log(level: str, message: str, **kwargs: object) -> None:
+    """Log message with kwargs support for both structlog and standard logging."""
+    if _using_structlog:
+        getattr(logger, level)(message, **kwargs)
+    else:
+        # For standard logging, format kwargs as part of the message
+        if kwargs:
+            kwargs_str = " ".join(f"{k}={v}" for k, v in kwargs.items())
+            getattr(logger, level)(f"{message} {kwargs_str}")
+        else:
+            getattr(logger, level)(message)
+
+
+def create_video_writer(
+    output_path: str,
+    width: int,
+    height: int,
+    display_width: int,
+    display_height: int,
+    fps: float,
+) -> tuple[cv2.VideoWriter, bool, str]:
+    """
+    Create a video writer with fallback codec support.
+
+    ⚠️  CRITICAL: DO NOT add "vp09" (VP9) to the codec list!
+    VP9 is not supported on iOS browsers (iPhone/iPad) and causes playback failures.
+    Regression test: tests/core/test_debug_overlay_utils.py::test_vp09_codec_never_in_codec_list
+
+    Args:
+        output_path: Path for output video
+        width: Encoded frame width (from source video)
+        height: Encoded frame height (from source video)
+        display_width: Display width (considering SAR)
+        display_height: Display height (considering SAR)
+        fps: Frames per second
+
+    Returns:
+        Tuple of (video_writer, needs_resize, used_codec)
+    """
+    needs_resize = (display_width != width) or (display_height != height)
+
+    # Try browser-compatible codecs first
+    # avc1: H.264 (Most compatible, including iOS)
+    # mp4v: MPEG-4 (Poor browser support, will trigger ffmpeg re-encoding for H.264)
+    # ⚠️  CRITICAL: VP9 (vp09) is EXCLUDED - not supported on iOS/iPhone/iPad browsers!
+    #     Adding VP9 will break debug video playback on all iOS devices.
+    codecs_to_try = ["avc1", "mp4v"]
+    codec_attempt_log: list[dict[str, Any]] = []
+
+    for codec in codecs_to_try:
+        writer = _try_open_video_writer(
+            output_path, codec, fps, display_width, display_height, codec_attempt_log
+        )
+        if writer:
+            return writer, needs_resize, codec
+
+    _log(
+        "error",
+        "debug_video_writer_creation_failed",
+        output_path=output_path,
+        dimensions=f"{display_width}x{display_height}",
+        fps=fps,
+        codec_attempts=codec_attempt_log,
+    )
+    raise ValueError(
+        f"Failed to create video writer for {output_path} with dimensions "
+        f"{display_width}x{display_height}"
+    )
+
+
+def _try_open_video_writer(
+    output_path: str,
+    codec: str,
+    fps: float,
+    width: int,
+    height: int,
+    attempt_log: list[dict[str, Any]],
+) -> cv2.VideoWriter | None:
+    """Attempt to open a video writer with a specific codec."""
+    try:
+        fourcc = cv2.VideoWriter_fourcc(*codec)  # type: ignore[attr-defined]
+        writer = cv2.VideoWriter(output_path, fourcc, fps, (width, height))
+        if writer.isOpened():
+            attempt_log.append({"codec": codec, "status": "success"})
+            _log(
+                "info",
+                "debug_video_codec_selected",
+                codec=codec,
+                width=width,
+                height=height,
+                fps=fps,
+            )
+            if codec == "mp4v":
+                msg = (
+                    "Using fallback MPEG-4 codec; will re-encode with ffmpeg for "
+                    "browser compatibility"
+                )
+                _log("warning", "debug_video_fallback_codec", codec="mp4v", warning=msg)
+            return writer
+
+        attempt_log.append(
+            {"codec": codec, "status": "failed", "error": "isOpened() returned False"}
+        )
+    except Exception as e:
+        attempt_log.append({"codec": codec, "status": "failed", "error": str(e)})
+        _log("info", "debug_video_codec_attempt_failed", codec=codec, error=str(e))
+
+    return None
+
+
+def write_overlay_frame(
+    writer: cv2.VideoWriter, frame: np.ndarray, width: int, height: int
+) -> None:
+    """
+    Write a frame to the video writer with dimension validation.
+
+    Args:
+        writer: Video writer instance
+        frame: Frame to write
+        width: Expected frame width
+        height: Expected frame height
+
+    Raises:
+        ValueError: If frame dimensions don't match expected dimensions
+    """
+    # Validate dimensions before writing
+    if frame.shape[0] != height or frame.shape[1] != width:
+        raise ValueError(
+            f"Frame dimensions {frame.shape[1]}x{frame.shape[0]} do not match "
+            f"expected dimensions {width}x{height}"
+        )
+    writer.write(frame)
+
+
+class BaseDebugOverlayRenderer:
+    """Base class for debug overlay renderers with common functionality."""
+
+    def __init__(
+        self,
+        output_path: str,
+        width: int,
+        height: int,
+        display_width: int,
+        display_height: int,
+        fps: float,
+        timer: Timer | None = None,
+    ):
+        """
+        Initialize overlay renderer.
+
+        Args:
+            output_path: Path for output video
+            width: Encoded frame width (from source video)
+            height: Encoded frame height (from source video)
+            display_width: Display width (considering SAR)
+            display_height: Display height (considering SAR)
+            fps: Frames per second
+            timer: Optional Timer for measuring operations
+        """
+        self.output_path = output_path
+        self.width = width
+        self.height = height
+        self.timer = timer or NULL_TIMER
+
+        # Optimize debug video resolution: Cap max dimension to 720p
+        # Reduces software encoding time on single-core Cloud Run instances.
+        # while keeping sufficient quality for visual debugging.
+        max_dimension = 720
+        if max(display_width, display_height) > max_dimension:
+            scale = max_dimension / max(display_width, display_height)
+            # Ensure dimensions are even for codec compatibility
+            self.display_width = int(display_width * scale) // 2 * 2
+            self.display_height = int(display_height * scale) // 2 * 2
+            _log(
+                "info",
+                "debug_video_resolution_optimized",
+                original_width=display_width,
+                original_height=display_height,
+                optimized_width=self.display_width,
+                optimized_height=self.display_height,
+                scale_factor=round(scale, 2),
+            )
+        else:
+            self.display_width = display_width
+            self.display_height = display_height
+            _log(
+                "info",
+                "debug_video_resolution_native",
+                width=self.display_width,
+                height=self.display_height,
+            )
+
+        _log(
+            "info",
+            "debug_overlay_renderer_initialized",
+            output_path=output_path,
+            source_width=width,
+            source_height=height,
+            output_width=self.display_width,
+            output_height=self.display_height,
+            fps=fps,
+        )
+
+        # Duration of ffmpeg re-encoding (0.0 if not needed)
+        self.reencode_duration_s = 0.0
+        self.writer, self.needs_resize, self.used_codec = create_video_writer(
+            output_path, width, height, self.display_width, self.display_height, fps
+        )
+
+    def write_frame(self, frame: np.ndarray) -> None:
+        """
+        Write frame to output video.
+
+        Args:
+            frame: Video frame with shape (height, width, 3)
+
+        Raises:
+            ValueError: If frame dimensions don't match expected encoded dimensions
+        """
+        # Validate frame dimensions match expected encoded dimensions
+        frame_height, frame_width = frame.shape[:2]
+        if frame_height != self.height or frame_width != self.width:
+            raise ValueError(
+                f"Frame dimensions ({frame_width}x{frame_height}) don't match "
+                f"source dimensions ({self.width}x{self.height}). "
+                f"Aspect ratio must be preserved from source video."
+            )
+
+        # Resize to display dimensions if needed (to handle SAR)
+        if self.needs_resize:
+            with self.timer.measure("debug_video_resize"):
+                frame = cv2.resize(
+                    frame,
+                    (self.display_width, self.display_height),
+                    interpolation=cv2.INTER_LINEAR,
+                )
+
+        with self.timer.measure("debug_video_write"):
+            write_overlay_frame(self.writer, frame, self.display_width, self.display_height)
+
+    def close(self) -> None:
+        """Release video writer and re-encode if possible."""
+        self.writer.release()
+        _log(
+            "info",
+            "debug_video_writer_released",
+            output_path=self.output_path,
+            codec=self.used_codec,
+        )
+
+        if self.used_codec != "mp4v":
+            _log(
+                "info",
+                "debug_video_ready_for_playback",
+                codec=self.used_codec,
+                path=self.output_path,
+            )
+            return
+
+        ffmpeg_path = shutil.which("ffmpeg")
+        if not ffmpeg_path:
+            _log(
+                "warning",
+                "debug_video_ffmpeg_not_available",
+                codec=self.used_codec,
+                output_path=self.output_path,
+                warning="Video may not play in all browsers",
+            )
+            return
+
+        self._reencode_to_h264()
+
+    def _reencode_to_h264(self) -> None:
+        """Re-encode video to H.264 for browser compatibility using ffmpeg."""
+        temp_path = str(
+            Path(self.output_path).with_suffix(".temp" + Path(self.output_path).suffix)
+        )
+
+        # Convert to H.264 with yuv420p pixel format for browser compatibility
+        # -y: Overwrite output file
+        # -vcodec libx264: Use H.264 codec
+        # -pix_fmt yuv420p: Required for wide browser support (Chrome, Safari, Firefox, iOS)
+        # -preset fast: Reasonable speed/compression tradeoff
+        # -crf 23: Standard quality
+        # -an: Remove audio (debug video has no audio)
+        cmd = [
+            "ffmpeg",
+            "-y",
+            "-i",
+            self.output_path,
+            "-vcodec",
+            "libx264",
+            "-pix_fmt",
+            "yuv420p",
+            "-preset",
+            "fast",
+            "-crf",
+            "23",
+            "-an",
+            temp_path,
+        ]
+
+        _log(
+            "info",
+            "debug_video_ffmpeg_reencoding_start",
+            input_file=self.output_path,
+            output_file=temp_path,
+            output_codec="libx264",
+            pixel_format="yuv420p",
+            reason="iOS_compatibility",
+        )
+
+        try:
+            reencode_start = time.time()
+            subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+            self.reencode_duration_s = time.time() - reencode_start
+
+            _log(
+                "info",
+                "debug_video_ffmpeg_reencoding_complete",
+                duration_ms=round(self.reencode_duration_s * 1000, 1),
+            )
+
+            os.replace(temp_path, self.output_path)
+            _log(
+                "info",
+                "debug_video_reencoded_file_replaced",
+                output_path=self.output_path,
+                final_codec="libx264",
+                pixel_format="yuv420p",
+            )
+        except Exception as e:
+            self._handle_reencode_error(e, temp_path)
+
+    def _handle_reencode_error(self, e: Exception, temp_path: str) -> None:
+        """Handle errors during ffmpeg re-encoding."""
+        if isinstance(e, subprocess.CalledProcessError):
+            stderr_msg = e.stderr.decode("utf-8", errors="ignore") if e.stderr else "N/A"
+            _log(
+                "warning",
+                "debug_video_ffmpeg_reencoding_failed",
+                error=str(e),
+                stderr=stderr_msg,
+            )
+        else:
+            _log("warning", "debug_video_post_processing_error", error=str(e))
+
+        if os.path.exists(temp_path):
+            os.remove(temp_path)
+            _log("info", "debug_video_temp_file_cleaned_up", temp_file=temp_path)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, _exc_type, _exc_val, _exc_tb) -> None:  # type: ignore[no-untyped-def]
+        self.close()

kinemotion/core/determinism.py

@@ -0,0 +1,83 @@
+"""Determinism utilities for reproducible analysis.
+
+Provides functions to set random seeds for NumPy, Python's random module,
+and TensorFlow (used by MediaPipe) to ensure deterministic behavior.
+"""
+
+import hashlib
+import os
+import random
+from pathlib import Path
+
+import numpy as np
+
+
+def get_video_hash_seed(video_path: str) -> int:
+    """Generate deterministic seed from video file path.
+
+    Uses video filename (not contents) to generate a consistent seed
+    for the same video across multiple runs.
+
+    Args:
+        video_path: Path to video file
+
+    Returns:
+        Integer seed value derived from filename
+    """
+    # Use filename only (not full path) for consistency
+    filename = Path(video_path).name
+    # Hash filename to get deterministic seed
+    hash_value = hashlib.md5(filename.encode()).hexdigest()
+    # Convert first 8 hex chars to integer
+    return int(hash_value[:8], 16)
+
+
+def set_deterministic_mode(seed: int | None = None, video_path: str | None = None) -> None:
+    """Set random seeds for reproducible analysis.
+
+    Sets seeds for:
+    - Python's random module
+    - NumPy random number generator
+    - TensorFlow (via environment variable for TFLite)
+
+    Args:
+        seed: Random seed value. If None and video_path provided,
+              generates seed from video filename.
+        video_path: Optional video path to generate deterministic seed
+
+    Note:
+        This should be called before any MediaPipe or analysis operations
+        to ensure deterministic pose detection and metric calculation.
+    """
+    # Generate seed from video if not provided
+    if seed is None and video_path is not None:
+        seed = get_video_hash_seed(video_path)
+    elif seed is None:
+        seed = 42  # Default
+
+    # Python random
+    random.seed(seed)
+
+    # NumPy random
+    np.random.seed(seed)
+
+    # TensorFlow/TFLite (used by MediaPipe)
+    # Set via environment variable before TF is initialized
+    os.environ["PYTHONHASHSEED"] = str(seed)
+    os.environ["TF_DETERMINISTIC_OPS"] = "1"
+
+    # Try to set TensorFlow seed if available
+    try:
+        import tensorflow as tf
+
+        tf.random.set_seed(seed)
+
+        # Disable GPU non-determinism if CUDA is available
+        try:
+            tf.config.experimental.enable_op_determinism()
+        except AttributeError:
+            # Older TensorFlow versions don't have this
+            pass
+    except ImportError:
+        # TensorFlow not directly available (only via MediaPipe's bundled version)
+        pass

kinemotion/core/experimental.py

@@ -0,0 +1,103 @@
+"""Decorators for marking experimental and unused features.
+
+These decorators help identify code that is implemented but not yet
+integrated into the main pipeline, making it easier to track features
+for future enhancement or cleanup.
+"""
+
+import functools
+import warnings
+from collections.abc import Callable
+from typing import TypeVar
+
+F = TypeVar("F", bound=Callable)
+
+
+def experimental(
+    reason: str, *, issue: int | None = None, since: str | None = None
+) -> Callable[[F], F]:
+    """Mark a feature as experimental/not fully integrated.
+
+    Experimental features are working implementations that haven't been
+    fully integrated into the main pipeline. They emit warnings when called
+    to alert developers they're using untested/unstable APIs.
+
+    Args:
+        reason: Why this is experimental (e.g., "API unstable", "needs validation")
+        issue: Optional GitHub issue number for tracking integration
+        since: Optional version when this became experimental
+
+    Example:
+        >>> @experimental("API may change", issue=123, since="0.34.0")
+        ... def new_feature():
+        ...     pass
+
+    Returns:
+        Decorated function that warns on use
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):  # type: ignore
+            msg = f"{func.__name__} is experimental: {reason}"
+            if issue:
+                msg += f" (GitHub issue #{issue})"
+            if since:
+                msg += f" [since v{since}]"
+            warnings.warn(msg, FutureWarning, stacklevel=2)
+            return func(*args, **kwargs)
+
+        # Add metadata for documentation/tooling
+        wrapper.__experimental__ = True  # type: ignore[attr-defined]
+        wrapper.__experimental_reason__ = reason  # type: ignore[attr-defined]
+        if issue:
+            wrapper.__experimental_issue__ = issue  # type: ignore[attr-defined]
+        if since:
+            wrapper.__experimental_since__ = since  # type: ignore[attr-defined]
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def unused(
+    reason: str, *, remove_in: str | None = None, since: str | None = None
+) -> Callable[[F], F]:
+    """Mark a feature as implemented but not integrated into pipeline.
+
+    Unused features are fully working implementations that aren't called
+    by the main analysis pipeline. Unlike @experimental, these don't emit
+    warnings when called (they work fine), but are marked for tracking.
+
+    Use this for:
+    - Features awaiting CLI integration
+    - Alternative implementations not yet exposed
+    - Code kept for backward compatibility
+
+    Args:
+        reason: Why this is unused (e.g., "awaiting CLI parameter")
+        remove_in: Optional version when this might be removed if not integrated
+        since: Optional version when this became unused
+
+    Example:
+        >>> @unused("Not called by pipeline", remove_in="1.0.0", since="0.34.0")
+        ... def calculate_adaptive_threshold():
+        ...     pass
+
+    Returns:
+        Original function with metadata attached (no runtime behavior change)
+    """
+
+    def decorator(func: F) -> F:
+        # Don't wrap - we don't want warnings when calling it
+        # Just attach metadata for documentation/cleanup tools
+        func.__unused__ = True  # type: ignore[attr-defined]
+        func.__unused_reason__ = reason  # type: ignore[attr-defined]
+        if remove_in:
+            func.__unused_remove_in__ = remove_in  # type: ignore[attr-defined]
+        if since:
+            func.__unused_since__ = since  # type: ignore[attr-defined]
+
+        return func
+
+    return decorator

kinemotion/core/filtering.py

@@ -3,6 +3,8 @@
 import numpy as np
 from scipy.signal import medfilt
 
+from .experimental import unused
+
 
 def detect_outliers_ransac(
     positions: np.ndarray,
@@ -145,9 +147,7 @@ def remove_outliers(
 
                 # Interpolate
                 t = (idx - idx_before) / (idx_after - idx_before)
-                positions_clean[idx] = (
-                    positions[idx_before] * (1 - t) + positions[idx_after] * t
-                )
+                positions_clean[idx] = positions[idx_before] * (1 - t) + positions[idx_after] * t
             elif len(valid_before) > 0:
                 # Use last valid value
                 positions_clean[idx] = positions[valid_before[-1]]
@@ -217,15 +217,18 @@ def reject_outliers(
 
     # Remove/replace outliers
     if interpolate:
-        cleaned_positions = remove_outliers(
-            positions, outlier_mask, method="interpolate"
-        )
+        cleaned_positions = remove_outliers(positions, outlier_mask, method="interpolate")
     else:
         cleaned_positions = positions.copy()
 
     return cleaned_positions, outlier_mask
 
 
+@unused(
+    reason="Not called by analysis pipeline - alternative adaptive smoothing approach",
+    remove_in="1.0.0",
+    since="0.34.0",
+)
 def adaptive_smooth_window(
     positions: np.ndarray,
     base_window: int = 5,

kinemotion/core/formatting.py

@@ -0,0 +1,75 @@
+"""Formatting utilities for consistent numeric output across jump analysis types.
+
+This module provides shared helpers for formatting numeric values with appropriate
+precision based on measurement type and capabilities of video-based analysis.
+"""
+
+# Standard precision values for different measurement types
+# These values are chosen based on:
+# - Video analysis capabilities (30-240 fps)
+# - Typical measurement uncertainty in video-based biomechanics
+# - Balance between accuracy and readability
+
+PRECISION_TIME_MS = 2  # Time in milliseconds: ±0.01ms (e.g., 534.12)
+PRECISION_DISTANCE_M = 3  # Distance in meters: ±1mm (e.g., 0.352)
+PRECISION_VELOCITY_M_S = 4  # Velocity in m/s: ±0.0001 m/s (e.g., 2.6340)
+PRECISION_FRAME = 3  # Sub-frame interpolation precision (e.g., 154.342)
+PRECISION_NORMALIZED = 4  # Normalized values 0-1 ratios (e.g., 0.0582)
+
+
+def format_float_metric(
+    value: float | None,
+    multiplier: float = 1.0,
+    decimals: int = 2,
+) -> float | None:
+    """Format a float metric value with optional scaling and rounding.
+
+    This helper ensures consistent precision across all jump analysis outputs,
+    preventing false precision in measurements while maintaining appropriate
+    accuracy for the measurement type.
+
+    Args:
+        value: The value to format, or None
+        multiplier: Factor to multiply value by (e.g., 1000 for seconds→milliseconds)
+        decimals: Number of decimal places to round to
+
+    Returns:
+        Formatted value rounded to specified decimals, or None if input is None
+
+    Examples:
+        >>> format_float_metric(0.534123, 1000, 2)  # seconds to ms
+        534.12
+        >>> format_float_metric(0.3521234, 1, 3)  # meters
+        0.352
+        >>> format_float_metric(None, 1, 2)
+        None
+        >>> format_float_metric(-1.23456, 1, 4)  # negative values preserved
+        -1.2346
+    """
+    if value is None:
+        return None
+    return round(value * multiplier, decimals)
+
+
+def format_int_metric(value: float | int | None) -> int | None:
+    """Format a value as an integer.
+
+    Used for frame numbers and other integer-valued metrics.
+
+    Args:
+        value: The value to format, or None
+
+    Returns:
+        Value converted to int, or None if input is None
+
+    Examples:
+        >>> format_int_metric(42.7)
+        42
+        >>> format_int_metric(None)
+        None
+        >>> format_int_metric(154)
+        154
+    """
+    if value is None:
+        return None
+    return int(value)