kinemotion 0.76.2__py3-none-any.whl → 1.0.0__py3-none-any.whl

kinemotion/core/__init__.py

@@ -13,6 +13,7 @@ from .pose import (
     MediaPipePoseTracker,
     PoseTrackerFactory,
     compute_center_of_mass,
+    get_tracker_info,
 )
 from .pose_landmarks import KINEMOTION_LANDMARKS, LANDMARK_INDICES
 from .quality import (
@@ -34,24 +35,14 @@ from .timing import (
     PerformanceTimer,
     Timer,
 )
-from .video_analysis_base import (
-    AnalysisOverrides,
-    JumpAnalysisPipeline,
-    VideoAnalysisConfig,
-    VideoAnalysisResult,
-)
 from .video_io import VideoProcessor
 
 __all__ = [
-    # Video Analysis Base
-    "AnalysisOverrides",
-    "JumpAnalysisPipeline",
-    "VideoAnalysisConfig",
-    "VideoAnalysisResult",
     # Pose tracking
     "MediaPipePoseTracker",
     "PoseTrackerFactory",
     "compute_center_of_mass",
+    "get_tracker_info",
     "LANDMARK_INDICES",
     "KINEMOTION_LANDMARKS",
     "get_model_path",

kinemotion/core/auto_tuning.py

@@ -5,28 +5,6 @@ from enum import Enum
 
 import numpy as np
 
-from .types import FOOT_KEYS
-
-
-@dataclass
-class _PresetConfig:
-    """Configuration modifiers for quality presets."""
-
-    velocity_multiplier: float  # Multiplier for velocity threshold
-    contact_frames_multiplier: float  # Multiplier for min contact frames
-    smoothing_offset: int  # Offset to smoothing window (added to base)
-    force_bilateral: bool | None  # None means use quality-based, True=force on, False=force off
-    detection_confidence: float
-    tracking_confidence: float
-
-
-@dataclass
-class _QualityAdjustment:
-    """Smoothing adjustments based on tracking quality."""
-
-    smoothing_add: int  # Frames to add to smoothing window
-    enable_bilateral: bool  # Whether to enable bilateral filtering
-
 
 class QualityPreset(str, Enum):
     """Quality presets for analysis."""
@@ -36,46 +14,6 @@ class QualityPreset(str, Enum):
     ACCURATE = "accurate"  # Research-grade analysis, slower
 
 
-# Quality preset configurations
-# FAST: Speed over accuracy
-# BALANCED: Default (uses quality-based settings)
-# ACCURATE: Maximum accuracy
-_PRESET_CONFIGS: dict[QualityPreset, _PresetConfig] = {
-    QualityPreset.FAST: _PresetConfig(
-        velocity_multiplier=1.5,
-        contact_frames_multiplier=0.67,
-        smoothing_offset=-2,
-        force_bilateral=False,
-        detection_confidence=0.3,
-        tracking_confidence=0.3,
-    ),
-    QualityPreset.BALANCED: _PresetConfig(
-        velocity_multiplier=1.0,
-        contact_frames_multiplier=1.0,
-        smoothing_offset=0,
-        force_bilateral=None,
-        detection_confidence=0.5,
-        tracking_confidence=0.5,
-    ),
-    QualityPreset.ACCURATE: _PresetConfig(
-        velocity_multiplier=0.5,
-        contact_frames_multiplier=1.0,
-        smoothing_offset=2,
-        force_bilateral=True,
-        detection_confidence=0.6,
-        tracking_confidence=0.6,
-    ),
-}
-
-
-# Quality-based adjustments
-_QUALITY_ADJUSTMENTS: dict[str, _QualityAdjustment] = {
-    "low": _QualityAdjustment(smoothing_add=2, enable_bilateral=True),
-    "medium": _QualityAdjustment(smoothing_add=1, enable_bilateral=True),
-    "high": _QualityAdjustment(smoothing_add=0, enable_bilateral=False),
-}
-
-
 @dataclass
 class VideoCharacteristics:
     """Characteristics extracted from video analysis."""
@@ -137,73 +75,6 @@ def analyze_tracking_quality(avg_visibility: float) -> str:
         return "high"
 
 
-def _compute_fps_baseline_parameters(fps: float) -> tuple[float, int, int]:
-    """Compute FPS-based baseline parameters.
-
-    Args:
-        fps: Video frame rate
-
-    Returns:
-        Tuple of (base_velocity_threshold, base_min_contact_frames, base_smoothing_window)
-    """
-    # Base velocity threshold: 0.012 at 30fps, scaled inversely by fps
-    # Must exceed typical MediaPipe landmark jitter (0.5-2% per frame)
-    # Previous value of 0.004 was below noise floor, causing false IN_AIR detections
-    base_velocity_threshold = 0.012 * (30.0 / fps)
-    base_min_contact_frames = max(2, round(3.0 * (fps / 30.0)))
-
-    # Smoothing window: Decrease with higher fps for better temporal resolution
-    base_smoothing_window = 3 if fps > 30 else 5
-
-    return base_velocity_threshold, base_min_contact_frames, base_smoothing_window
-
-
-def _compute_smoothing_window(
-    fps: float,
-    preset: _PresetConfig,
-    quality_adj: _QualityAdjustment,
-) -> int:
-    """Compute smoothing window from FPS, preset, and quality adjustments.
-
-    Args:
-        fps: Video frame rate
-        preset: Quality preset configuration
-        quality_adj: Quality-based adjustments
-
-    Returns:
-        Odd smoothing window size (required for Savitzky-Golay filter)
-    """
-    _, _, base_smoothing_window = _compute_fps_baseline_parameters(fps)
-
-    # Smoothing window = base + preset offset + quality adjustment
-    smoothing_window = base_smoothing_window + preset.smoothing_offset + quality_adj.smoothing_add
-    smoothing_window = max(3, min(11, smoothing_window))
-
-    # Ensure smoothing window is odd (required for Savitzky-Golay)
-    if smoothing_window % 2 == 0:
-        smoothing_window += 1
-
-    return smoothing_window
-
-
-def _resolve_bilateral_filter(
-    preset: _PresetConfig,
-    quality_adj: _QualityAdjustment,
-) -> bool:
-    """Resolve whether to enable bilateral filtering.
-
-    Args:
-        preset: Quality preset configuration
-        quality_adj: Quality-based adjustments
-
-    Returns:
-        True if bilateral filtering should be enabled
-    """
-    if preset.force_bilateral is not None:
-        return preset.force_bilateral
-    return quality_adj.enable_bilateral
-
-
 def auto_tune_parameters(
     characteristics: VideoCharacteristics,
     quality_preset: QualityPreset = QualityPreset.BALANCED,
@@ -230,28 +101,106 @@ def auto_tune_parameters(
     fps = characteristics.fps
     quality = characteristics.tracking_quality
 
-    # Get preset configuration and quality-based adjustments
-    preset = _PRESET_CONFIGS[quality_preset]
-    quality_adj = _QUALITY_ADJUSTMENTS[quality]
+    # =================================================================
+    # STEP 1: FPS-based baseline parameters
+    # These scale automatically with frame rate to maintain consistent
+    # temporal resolution and sensitivity
+    # =================================================================
+
+    # Velocity threshold: Scale inversely with fps
+    # Empirically validated with 45° oblique videos at 60fps:
+    # - Standing (stationary): ~0.001 mean, 0.0011 max
+    # - Flight/drop (moving): ~0.005-0.009
+    # Target threshold: 0.002 at 60fps for clear separation
+    # Formula: threshold = 0.004 * (30 / fps)
+    base_velocity_threshold = 0.004 * (30.0 / fps)
+
+    # Min contact frames: Scale with fps to maintain same time duration
+    # Goal: ~100ms minimum contact (3 frames @ 30fps, 6 frames @ 60fps)
+    # Formula: frames = round(3 * (fps / 30))
+    base_min_contact_frames = max(2, round(3.0 * (fps / 30.0)))
 
-    # Compute FPS-based baseline parameters
-    base_velocity_threshold, base_min_contact_frames, _ = _compute_fps_baseline_parameters(fps)
+    # Smoothing window: Decrease with higher fps for better temporal resolution
+    # Lower fps (30fps): 5-frame window = 167ms
+    # Higher fps (60fps): 3-frame window = 50ms (same temporal resolution)
+    if fps <= 30:
+        base_smoothing_window = 5
+    elif fps <= 60:
+        base_smoothing_window = 3
+    else:
+        base_smoothing_window = 3  # Even at 120fps, 3 is minimum for Savitzky-Golay
+
+    # =================================================================
+    # STEP 2: Quality-based adjustments
+    # Adapt smoothing and filtering based on tracking quality
+    # =================================================================
+
+    smoothing_adjustment = 0
+    enable_bilateral = False
+
+    if quality == "low":
+        # Poor tracking quality: aggressive smoothing and filtering
+        smoothing_adjustment = +2
+        enable_bilateral = True
+    elif quality == "medium":
+        # Moderate quality: slight smoothing increase
+        smoothing_adjustment = +1
+        enable_bilateral = True
+    else:  # high quality
+        # Good tracking: preserve detail, minimal smoothing
+        smoothing_adjustment = 0
+        enable_bilateral = False
+
+    # =================================================================
+    # STEP 3: Apply quality preset modifiers
+    # User can choose speed vs accuracy tradeoff
+    # =================================================================
+
+    if quality_preset == QualityPreset.FAST:
+        # Fast: Trade accuracy for speed
+        velocity_threshold = base_velocity_threshold * 1.5  # Less sensitive
+        min_contact_frames = max(2, int(base_min_contact_frames * 0.67))
+        smoothing_window = max(3, base_smoothing_window - 2 + smoothing_adjustment)
+        bilateral_filter = False  # Skip expensive filtering
+        detection_confidence = 0.3
+        tracking_confidence = 0.3
+
+    elif quality_preset == QualityPreset.ACCURATE:
+        # Accurate: Maximize accuracy, accept slower processing
+        velocity_threshold = base_velocity_threshold * 0.5  # More sensitive
+        min_contact_frames = base_min_contact_frames  # Don't increase (would miss brief)
+        smoothing_window = min(11, base_smoothing_window + 2 + smoothing_adjustment)
+        bilateral_filter = True  # Always use for best accuracy
+        detection_confidence = 0.6
+        tracking_confidence = 0.6
+
+    else:  # QualityPreset.BALANCED (default)
+        # Balanced: Good accuracy, reasonable speed
+        velocity_threshold = base_velocity_threshold
+        min_contact_frames = base_min_contact_frames
+        smoothing_window = max(3, base_smoothing_window + smoothing_adjustment)
+        bilateral_filter = enable_bilateral
+        detection_confidence = 0.5
+        tracking_confidence = 0.5
+
+    # Ensure smoothing window is odd (required for Savitzky-Golay)
+    if smoothing_window % 2 == 0:
+        smoothing_window += 1
 
-    # Apply preset modifiers
-    velocity_threshold = base_velocity_threshold * preset.velocity_multiplier
-    min_contact_frames = max(2, int(base_min_contact_frames * preset.contact_frames_multiplier))
+    # =================================================================
+    # STEP 4: Set fixed optimal values
+    # These are always the same regardless of video characteristics
+    # =================================================================
 
-    # Compute smoothing window with preset and quality adjustments
-    smoothing_window = _compute_smoothing_window(fps, preset, quality_adj)
+    # Polyorder: Always 2 (quadratic) - optimal for jump physics (parabolic motion)
+    polyorder = 2
 
-    # Resolve bilateral filtering setting
-    bilateral_filter = _resolve_bilateral_filter(preset, quality_adj)
+    # Visibility threshold: Standard MediaPipe threshold
+    visibility_threshold = 0.5
 
-    # Fixed optimal values
-    polyorder = 2  # Quadratic - optimal for parabolic motion
-    visibility_threshold = 0.5  # Standard MediaPipe threshold
-    outlier_rejection = True  # Removes tracking glitches
-    use_curvature = True  # Trajectory curvature analysis
+    # Always enable proven accuracy features
+    outlier_rejection = True  # Removes tracking glitches (minimal cost)
+    use_curvature = True  # Trajectory curvature analysis (minimal cost)
 
     return AnalysisParameters(
         smoothing_window=smoothing_window,
@@ -259,8 +208,8 @@ def auto_tune_parameters(
         velocity_threshold=velocity_threshold,
         min_contact_frames=min_contact_frames,
         visibility_threshold=visibility_threshold,
-        detection_confidence=preset.detection_confidence,
-        tracking_confidence=preset.tracking_confidence,
+        detection_confidence=detection_confidence,
+        tracking_confidence=tracking_confidence,
         outlier_rejection=outlier_rejection,
         bilateral_filter=bilateral_filter,
         use_curvature=use_curvature,
@@ -279,10 +228,19 @@ def _collect_foot_visibility_and_positions(
     Returns:
         Tuple of (visibility_scores, y_positions)
     """
+    foot_keys = [
+        "left_ankle",
+        "right_ankle",
+        "left_heel",
+        "right_heel",
+        "left_foot_index",
+        "right_foot_index",
+    ]
+
     frame_vis = []
     frame_y_positions = []
 
-    for key in FOOT_KEYS:
+    for key in foot_keys:
         if key in frame_landmarks:
             _, y, vis = frame_landmarks[key]  # x not needed for analysis
             frame_vis.append(vis)

kinemotion/core/cli_utils.py

@@ -24,80 +24,6 @@ def common_output_options(func: Callable) -> Callable:  # type: ignore[type-arg]
     return func
 
 
-def quality_option(func: Callable) -> Callable:  # type: ignore[type-arg]
-    """Add quality preset option to CLI command."""
-    return click.option(
-        "--quality",
-        type=click.Choice(["fast", "balanced", "accurate"], case_sensitive=False),
-        default="balanced",
-        help=(
-            "Analysis quality preset: "
-            "fast (quick, less precise), "
-            "balanced (default, good for most cases), "
-            "accurate (research-grade, slower)"
-        ),
-        show_default=True,
-    )(func)
-
-
-def verbose_option(func: Callable) -> Callable:  # type: ignore[type-arg]
-    """Add verbose flag to CLI command."""
-    return click.option(
-        "--verbose",
-        "-v",
-        is_flag=True,
-        help="Show auto-selected parameters and analysis details",
-    )(func)
-
-
-def batch_processing_options(func: Callable) -> Callable:  # type: ignore[type-arg]
-    """Add batch processing options to CLI command."""
-    func = click.option(
-        "--batch",
-        is_flag=True,
-        help="Enable batch processing mode for multiple videos",
-    )(func)
-    func = click.option(
-        "--workers",
-        type=int,
-        default=4,
-        help="Number of parallel workers for batch processing (default: 4)",
-        show_default=True,
-    )(func)
-    func = click.option(
-        "--output-dir",
-        type=click.Path(),
-        help="Directory for debug video outputs (batch mode only)",
-    )(func)
-    func = click.option(
-        "--json-output-dir",
-        type=click.Path(),
-        help="Directory for JSON metrics outputs (batch mode only)",
-    )(func)
-    func = click.option(
-        "--csv-summary",
-        type=click.Path(),
-        help="Path for CSV summary export (batch mode only)",
-    )(func)
-    return func
-
-
-def common_analysis_options(func: Callable) -> Callable:  # type: ignore[type-arg]
-    """Add all common analysis options (output, quality, verbose, batch).
-
-    Combines:
-    - common_output_options (--output, --json-output)
-    - quality_option (--quality)
-    - verbose_option (--verbose)
-    - batch_processing_options (--batch, --workers, --output-dir, etc.)
-    """
-    func = common_output_options(func)
-    func = quality_option(func)
-    func = verbose_option(func)
-    func = batch_processing_options(func)
-    return func
-
-
 def collect_video_files(video_path: tuple[str, ...]) -> list[str]:
     """Expand glob patterns and collect all video files."""
     video_files: list[str] = []

kinemotion/core/debug_overlay_utils.py

@@ -6,34 +6,12 @@ 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
@@ -93,10 +71,12 @@ 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)
-    # See overlay_constants.py for codec list and critical VP9 exclusion notes
-    codec_attempt_log: CodecAttemptLog = []
+    # ⚠️  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:
+    for codec in codecs_to_try:
         writer = _try_open_video_writer(
             output_path, codec, fps, display_width, display_height, codec_attempt_log
         )
@@ -123,7 +103,7 @@ def _try_open_video_writer(
     fps: float,
     width: int,
     height: int,
-    attempt_log: CodecAttemptLog,
+    attempt_log: list[dict[str, Any]],
 ) -> cv2.VideoWriter | None:
     """Attempt to open a video writer with a specific codec."""
     try:
@@ -214,8 +194,9 @@ 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.
-        if max(display_width, display_height) > MAX_VIDEO_DIMENSION:
-            scale = MAX_VIDEO_DIMENSION / max(display_width, display_height)
+        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
@@ -255,114 +236,6 @@ 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.
@@ -447,11 +320,11 @@ class BaseDebugOverlayRenderer:
             "-vcodec",
             "libx264",
             "-pix_fmt",
-            FFMPEG_PIX_FMT,
+            "yuv420p",
             "-preset",
-            FFMPEG_PRESET,
+            "fast",
             "-crf",
-            FFMPEG_CRF,
+            "23",
             "-an",
             temp_path,
         ]
@@ -462,7 +335,7 @@ class BaseDebugOverlayRenderer:
             input_file=self.output_path,
             output_file=temp_path,
             output_codec="libx264",
-            pixel_format=FFMPEG_PIX_FMT,
+            pixel_format="yuv420p",
             reason="iOS_compatibility",
         )
 
@@ -483,7 +356,7 @@ class BaseDebugOverlayRenderer:
                 "debug_video_reencoded_file_replaced",
                 output_path=self.output_path,
                 final_codec="libx264",
-                pixel_format=FFMPEG_PIX_FMT,
+                pixel_format="yuv420p",
             )
         except Exception as e:
             self._handle_reencode_error(e, temp_path)