kinemotion 0.70.1__py3-none-any.whl → 0.71.1__py3-none-any.whl

kinemotion/core/debug_overlay_utils.py

@@ -6,12 +6,34 @@ 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 .overlay_constants import (
+    ANKLE_COLOR,
+    BLACK,
+    CODECS_TO_TRY,
+    CYAN,
+    FFMPEG_CRF,
+    FFMPEG_PIX_FMT,
+    FFMPEG_PRESET,
+    HIP_COLOR,
+    JOINT_CIRCLE_RADIUS,
+    JOINT_OUTLINE_RADIUS,
+    KNEE_COLOR,
+    MAX_VIDEO_DIMENSION,
+    NOSE_CIRCLE_RADIUS,
+    NOSE_OUTLINE_RADIUS,
+    TRUNK_COLOR,
+    VISIBILITY_THRESHOLD,
+    WHITE,
+    CodecAttemptLog,
+    Color,
+    Landmark,
+    LandmarkDict,
+)
 from .timing import NULL_TIMER, Timer
 
 # Setup logging with structlog support for backend, fallback to standard logging for CLI
@@ -71,12 +93,10 @@ def create_video_writer(
     # 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]] = []
+    # See overlay_constants.py for codec list and critical VP9 exclusion notes
+    codec_attempt_log: CodecAttemptLog = []
 
-    for codec in codecs_to_try:
+    for codec in CODECS_TO_TRY:
         writer = _try_open_video_writer(
             output_path, codec, fps, display_width, display_height, codec_attempt_log
         )
@@ -103,7 +123,7 @@ def _try_open_video_writer(
     fps: float,
     width: int,
     height: int,
-    attempt_log: list[dict[str, Any]],
+    attempt_log: CodecAttemptLog,
 ) -> cv2.VideoWriter | None:
     """Attempt to open a video writer with a specific codec."""
     try:
@@ -194,9 +214,8 @@ class BaseDebugOverlayRenderer:
         # 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)
+        if max(display_width, display_height) > MAX_VIDEO_DIMENSION:
+            scale = MAX_VIDEO_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
@@ -236,6 +255,114 @@ class BaseDebugOverlayRenderer:
             output_path, width, height, self.display_width, self.display_height, fps
         )
 
+    def _normalize_to_pixels(self, x: float, y: float) -> tuple[int, int]:
+        """Convert normalized coordinates (0-1) to pixel coordinates.
+
+        Args:
+            x: Normalized x coordinate (0-1)
+            y: Normalized y coordinate (0-1)
+
+        Returns:
+            Tuple of (pixel_x, pixel_y)
+        """
+        return int(x * self.width), int(y * self.height)
+
+    def _landmark_to_pixel(self, landmark: Landmark) -> tuple[int, int]:
+        """Convert normalized landmark coordinates to pixel coordinates."""
+        return self._normalize_to_pixels(landmark[0], landmark[1])
+
+    def _is_visible(self, landmark: Landmark, threshold: float = VISIBILITY_THRESHOLD) -> bool:
+        """Check if a landmark has sufficient visibility."""
+        return landmark[2] > threshold
+
+    def _get_skeleton_segments(self, side_prefix: str) -> list[tuple[str, str, Color, int]]:
+        """Get skeleton segments for one side of the body.
+
+        Returns list of (start_key, end_key, color, thickness) tuples.
+        """
+        p = side_prefix  # Shorter alias for readability
+        return [
+            (f"{p}heel", f"{p}ankle", ANKLE_COLOR, 3),  # Foot
+            (f"{p}heel", f"{p}foot_index", ANKLE_COLOR, 2),  # Alt foot
+            (f"{p}ankle", f"{p}knee", KNEE_COLOR, 4),  # Shin
+            (f"{p}knee", f"{p}hip", HIP_COLOR, 4),  # Femur
+            (f"{p}hip", f"{p}shoulder", TRUNK_COLOR, 4),  # Trunk
+            (f"{p}shoulder", "nose", (150, 150, 255), 2),  # Neck
+        ]
+
+    def _draw_segment(
+        self,
+        frame: np.ndarray,
+        landmarks: LandmarkDict,
+        start_key: str,
+        end_key: str,
+        color: Color,
+        thickness: int,
+    ) -> None:
+        """Draw a single skeleton segment if both endpoints are visible."""
+        if start_key not in landmarks or end_key not in landmarks:
+            return
+
+        start_landmark = landmarks[start_key]
+        end_landmark = landmarks[end_key]
+
+        if not (self._is_visible(start_landmark) and self._is_visible(end_landmark)):
+            return
+
+        start_pt = self._landmark_to_pixel(start_landmark)
+        end_pt = self._landmark_to_pixel(end_landmark)
+        cv2.line(frame, start_pt, end_pt, color, thickness)
+
+    def _draw_joints(
+        self,
+        frame: np.ndarray,
+        landmarks: LandmarkDict,
+        side_prefix: str,
+    ) -> None:
+        """Draw joint circles for one side of the body."""
+        p = side_prefix
+        joint_keys = [
+            f"{p}heel",
+            f"{p}foot_index",
+            f"{p}ankle",
+            f"{p}knee",
+            f"{p}hip",
+            f"{p}shoulder",
+        ]
+
+        for key in joint_keys:
+            if key not in landmarks:
+                continue
+            landmark = landmarks[key]
+            if not self._is_visible(landmark):
+                continue
+
+            point = self._landmark_to_pixel(landmark)
+            cv2.circle(frame, point, JOINT_CIRCLE_RADIUS, WHITE, -1)
+            cv2.circle(frame, point, JOINT_OUTLINE_RADIUS, BLACK, 2)
+
+    def _draw_skeleton(self, frame: np.ndarray, landmarks: LandmarkDict) -> None:
+        """Draw skeleton segments showing body landmarks.
+
+        Draws whatever landmarks are visible. In side-view videos, ankle/knee
+        may have low visibility, so we draw available segments.
+
+        Args:
+            frame: Frame to draw on (modified in place)
+            landmarks: Pose landmarks
+        """
+        # Draw segments and joints for both sides
+        for side_prefix in ["right_", "left_"]:
+            for start_key, end_key, color, thickness in self._get_skeleton_segments(side_prefix):
+                self._draw_segment(frame, landmarks, start_key, end_key, color, thickness)
+            self._draw_joints(frame, landmarks, side_prefix)
+
+        # Draw nose (head position) if visible
+        if "nose" in landmarks and self._is_visible(landmarks["nose"]):
+            point = self._landmark_to_pixel(landmarks["nose"])
+            cv2.circle(frame, point, NOSE_CIRCLE_RADIUS, CYAN, -1)
+            cv2.circle(frame, point, NOSE_OUTLINE_RADIUS, BLACK, 2)
+
     def write_frame(self, frame: np.ndarray) -> None:
         """
         Write frame to output video.
@@ -320,11 +447,11 @@ class BaseDebugOverlayRenderer:
             "-vcodec",
             "libx264",
             "-pix_fmt",
-            "yuv420p",
+            FFMPEG_PIX_FMT,
             "-preset",
-            "fast",
+            FFMPEG_PRESET,
             "-crf",
-            "23",
+            FFMPEG_CRF,
             "-an",
             temp_path,
         ]
@@ -335,7 +462,7 @@ class BaseDebugOverlayRenderer:
             input_file=self.output_path,
             output_file=temp_path,
             output_codec="libx264",
-            pixel_format="yuv420p",
+            pixel_format=FFMPEG_PIX_FMT,
             reason="iOS_compatibility",
         )
 
@@ -356,7 +483,7 @@ class BaseDebugOverlayRenderer:
                 "debug_video_reencoded_file_replaced",
                 output_path=self.output_path,
                 final_codec="libx264",
-                pixel_format="yuv420p",
+                pixel_format=FFMPEG_PIX_FMT,
             )
         except Exception as e:
             self._handle_reencode_error(e, temp_path)

kinemotion/core/experimental.py

@@ -1,6 +1,6 @@
-"""Decorators for marking experimental and unused features.
+"""Decorator for marking unused features.
 
-These decorators help identify code that is implemented but not yet
+This decorator helps identify code that is implemented but not yet
 integrated into the main pipeline, making it easier to track features
 for future enhancement or cleanup.
 """
@@ -13,61 +13,14 @@ 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.
+    by the main analysis pipeline. These don't emit warnings when called
+    (they work fine), but are marked for tracking.
 
     Use this for:
     - Features awaiting CLI integration
@@ -101,3 +54,54 @@ def unused(
         return func
 
     return decorator
+
+
+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 may change
+    or be removed. They emit a warning when called to alert users.
+
+    Use this for:
+    - Features under active development
+    - APIs that may change
+    - Functionality that needs more testing
+
+    Args:
+        reason: Why this is experimental (e.g., "API may change")
+        issue: Optional GitHub issue number tracking this feature
+        since: Optional version when this became experimental
+
+    Example:
+        >>> @experimental("API may change", issue=42, since="0.35.0")
+        ... def new_analysis_method():
+        ...     pass
+
+    Returns:
+        Wrapped function that emits ExperimentalWarning when called
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):  # type: ignore[no-untyped-def]
+            issue_ref = f" (see issue #{issue})" if issue else ""
+            version_ref = f" since {since}" if since else ""
+            warnings.warn(
+                f"{func.__name__} is experimental{version_ref}: {reason}{issue_ref}",
+                category=FutureWarning,
+                stacklevel=2,
+            )
+            return func(*args, **kwargs)
+
+        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

kinemotion/core/filtering.py

@@ -6,6 +6,18 @@ from scipy.signal import medfilt
 from .experimental import unused
 
 
+def _ensure_odd_window_length(window_length: int) -> int:
+    """Ensure window_length is odd (required for Savitzky-Golay filter).
+
+    Args:
+        window_length: Desired window length
+
+    Returns:
+        Odd window length (increments by 1 if even)
+    """
+    return window_length + 1 if window_length % 2 == 0 else window_length
+
+
 def detect_outliers_ransac(
     positions: np.ndarray,
     window_size: int = 15,
@@ -34,10 +46,7 @@ def detect_outliers_ransac(
     if n < window_size:
         return is_outlier
 
-    # Ensure window size is odd
-    if window_size % 2 == 0:
-        window_size += 1
-
+    window_size = _ensure_odd_window_length(window_size)
     half_window = window_size // 2
 
     for i in range(n):
@@ -93,9 +102,7 @@ def detect_outliers_median(
     if len(positions) < window_size:
         return np.zeros(len(positions), dtype=bool)
 
-    # Ensure window size is odd
-    if window_size % 2 == 0:
-        window_size += 1
+    window_size = _ensure_odd_window_length(window_size)
 
     # Apply median filter
     median_filtered = medfilt(positions, kernel_size=window_size)
@@ -315,10 +322,7 @@ def bilateral_temporal_filter(
     n = len(positions)
     filtered = np.zeros(n)
 
-    # Ensure window size is odd
-    if window_size % 2 == 0:
-        window_size += 1
-
+    window_size = _ensure_odd_window_length(window_size)
     half_window = window_size // 2
 
     for i in range(n):

kinemotion/core/overlay_constants.py

@@ -0,0 +1,61 @@
+"""Shared constants and type aliases for overlay renderers."""
+
+from typing import Any
+
+# Type aliases for overlay rendering
+Color = tuple[int, int, int]
+Landmark = tuple[float, float, float]
+LandmarkDict = dict[str, Landmark]
+CodecAttemptLog = list[dict[str, Any]]
+
+# Visibility thresholds
+VISIBILITY_THRESHOLD = 0.2
+VISIBILITY_THRESHOLD_HIGH = 0.3
+FOOT_VISIBILITY_THRESHOLD = 0.5
+
+# Video encoding constants
+MAX_VIDEO_DIMENSION = 720
+CODECS_TO_TRY = ["avc1", "mp4v"]
+FFMPEG_PRESET = "fast"
+FFMPEG_CRF = "23"
+FFMPEG_PIX_FMT = "yuv420p"
+
+# Common colors (BGR format for OpenCV)
+GREEN = (0, 255, 0)
+RED = (0, 0, 255)
+WHITE = (255, 255, 255)
+BLACK = (0, 0, 0)
+GRAY = (128, 128, 128)
+CYAN = (255, 255, 0)
+ORANGE = (0, 165, 255)
+
+# Joint colors for triple extension
+ANKLE_COLOR = (0, 255, 255)  # Cyan
+KNEE_COLOR = (255, 100, 100)  # Light blue
+HIP_COLOR = (100, 255, 100)  # Light green
+TRUNK_COLOR = (100, 100, 255)  # Light red
+
+# Angle thresholds
+FULL_EXTENSION_ANGLE = 160
+DEEP_FLEXION_ANGLE = 90
+
+# Circle sizes
+JOINT_CIRCLE_RADIUS = 6
+JOINT_OUTLINE_RADIUS = 8
+COM_CIRCLE_RADIUS = 15
+COM_OUTLINE_RADIUS = 17
+HIP_MARKER_RADIUS = 8
+FOOT_CIRCLE_RADIUS = 10
+FOOT_LANDMARK_RADIUS = 5
+ANGLE_ARC_RADIUS = 25
+NOSE_CIRCLE_RADIUS = 8
+NOSE_OUTLINE_RADIUS = 10
+
+# Box positioning
+JOINT_ANGLES_BOX_X_OFFSET = 180
+JOINT_ANGLES_BOX_HEIGHT = 150
+METRICS_BOX_WIDTH = 320
+
+# Phase label positioning
+PHASE_LABEL_START_Y = 110
+PHASE_LABEL_LINE_HEIGHT = 40