kinemotion 0.17.0__py3-none-any.whl

kinemotion/core/auto_tuning.py

@@ -0,0 +1,325 @@
+"""Automatic parameter tuning based on video characteristics."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+import numpy as np
+
+
+class QualityPreset(str, Enum):
+    """Quality presets for analysis."""
+
+    FAST = "fast"  # Quick analysis, lower precision
+    BALANCED = "balanced"  # Default: good balance of speed and accuracy
+    ACCURATE = "accurate"  # Research-grade analysis, slower
+
+
+@dataclass
+class VideoCharacteristics:
+    """Characteristics extracted from video analysis."""
+
+    fps: float
+    frame_count: int
+    avg_visibility: float  # Average landmark visibility (0-1)
+    position_variance: float  # Variance in foot positions
+    has_stable_period: bool  # Whether video has initial stationary period
+    tracking_quality: str  # "low", "medium", "high"
+
+
+@dataclass
+class AnalysisParameters:
+    """Auto-tuned parameters for drop jump analysis."""
+
+    smoothing_window: int
+    polyorder: int
+    velocity_threshold: float
+    min_contact_frames: int
+    visibility_threshold: float
+    detection_confidence: float
+    tracking_confidence: float
+    outlier_rejection: bool
+    bilateral_filter: bool
+    use_curvature: bool
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary."""
+        return {
+            "smoothing_window": self.smoothing_window,
+            "polyorder": self.polyorder,
+            "velocity_threshold": self.velocity_threshold,
+            "min_contact_frames": self.min_contact_frames,
+            "visibility_threshold": self.visibility_threshold,
+            "detection_confidence": self.detection_confidence,
+            "tracking_confidence": self.tracking_confidence,
+            "outlier_rejection": self.outlier_rejection,
+            "bilateral_filter": self.bilateral_filter,
+            "use_curvature": self.use_curvature,
+        }
+
+
+def analyze_tracking_quality(avg_visibility: float) -> str:
+    """
+    Classify tracking quality based on average landmark visibility.
+
+    Args:
+        avg_visibility: Average visibility score across all tracked landmarks
+
+    Returns:
+        Quality classification: "low", "medium", or "high"
+    """
+    if avg_visibility < 0.4:
+        return "low"
+    elif avg_visibility < 0.7:
+        return "medium"
+    else:
+        return "high"
+
+
+def auto_tune_parameters(
+    characteristics: VideoCharacteristics,
+    quality_preset: QualityPreset = QualityPreset.BALANCED,
+) -> AnalysisParameters:
+    """
+    Automatically tune analysis parameters based on video characteristics.
+
+    This function implements heuristics to select optimal parameters without
+    requiring user expertise in video analysis or kinematic tracking.
+
+    Key principles:
+    1. FPS-based scaling: Higher fps needs lower velocity thresholds
+    2. Quality-based smoothing: Noisy video needs more smoothing
+    3. Always enable proven features: outlier rejection, curvature analysis
+    4. Preset modifiers: fast/balanced/accurate adjust base parameters
+
+    Args:
+        characteristics: Analyzed video characteristics
+        quality_preset: Quality vs speed tradeoff
+
+    Returns:
+        AnalysisParameters with auto-tuned values
+    """
+    fps = characteristics.fps
+    quality = characteristics.tracking_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
+    # At 30fps, feet move ~2% of frame per frame when "stationary"
+    # At 60fps, feet move ~1% of frame per frame when "stationary"
+    # Formula: threshold = 0.02 * (30 / fps)
+    base_velocity_threshold = 0.02 * (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)))
+
+    # 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
+
+    # =================================================================
+    # STEP 4: Set fixed optimal values
+    # These are always the same regardless of video characteristics
+    # =================================================================
+
+    # Polyorder: Always 2 (quadratic) - optimal for jump physics (parabolic motion)
+    polyorder = 2
+
+    # Visibility threshold: Standard MediaPipe threshold
+    visibility_threshold = 0.5
+
+    # 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,
+        polyorder=polyorder,
+        velocity_threshold=velocity_threshold,
+        min_contact_frames=min_contact_frames,
+        visibility_threshold=visibility_threshold,
+        detection_confidence=detection_confidence,
+        tracking_confidence=tracking_confidence,
+        outlier_rejection=outlier_rejection,
+        bilateral_filter=bilateral_filter,
+        use_curvature=use_curvature,
+    )
+
+
+def _collect_foot_visibility_and_positions(
+    frame_landmarks: dict[str, tuple[float, float, float]],
+) -> tuple[list[float], list[float]]:
+    """
+    Collect visibility scores and Y positions from foot landmarks.
+
+    Args:
+        frame_landmarks: Landmarks for a single frame
+
+    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:
+        if key in frame_landmarks:
+            _, y, vis = frame_landmarks[key]  # x not needed for analysis
+            frame_vis.append(vis)
+            frame_y_positions.append(y)
+
+    return frame_vis, frame_y_positions
+
+
+def _check_stable_period(positions: list[float]) -> bool:
+    """
+    Check if video has a stable period at the start.
+
+    A stable period (low variance in first 30 frames) indicates
+    the subject is standing on an elevated platform before jumping.
+
+    Args:
+        positions: List of average Y positions per frame
+
+    Returns:
+        True if stable period detected, False otherwise
+    """
+    if len(positions) < 30:
+        return False
+
+    first_30_std = float(np.std(positions[:30]))
+    return first_30_std < 0.01  # Very stable = on platform
+
+
+def analyze_video_sample(
+    landmarks_sequence: list[dict[str, tuple[float, float, float]] | None],
+    fps: float,
+    frame_count: int,
+) -> VideoCharacteristics:
+    """
+    Analyze video characteristics from a sample of frames.
+
+    This function should be called after tracking the first 30-60 frames
+    to understand video quality and characteristics.
+
+    Args:
+        landmarks_sequence: Tracked landmarks from sample frames
+        fps: Video frame rate
+        frame_count: Total number of frames in video
+
+    Returns:
+        VideoCharacteristics with analyzed properties
+    """
+    visibilities = []
+    positions = []
+
+    # Collect visibility and position data from all frames
+    for frame_landmarks in landmarks_sequence:
+        if not frame_landmarks:
+            continue
+
+        frame_vis, frame_y_positions = _collect_foot_visibility_and_positions(
+            frame_landmarks
+        )
+
+        if frame_vis:
+            visibilities.append(float(np.mean(frame_vis)))
+        if frame_y_positions:
+            positions.append(float(np.mean(frame_y_positions)))
+
+    # Compute metrics
+    avg_visibility = float(np.mean(visibilities)) if visibilities else 0.5
+    position_variance = float(np.var(positions)) if len(positions) > 1 else 0.0
+
+    # Determine tracking quality
+    tracking_quality = analyze_tracking_quality(avg_visibility)
+
+    # Check for stable period (indicates drop jump from elevated platform)
+    has_stable_period = _check_stable_period(positions)
+
+    return VideoCharacteristics(
+        fps=fps,
+        frame_count=frame_count,
+        avg_visibility=avg_visibility,
+        position_variance=position_variance,
+        has_stable_period=has_stable_period,
+        tracking_quality=tracking_quality,
+    )

kinemotion/core/cli_utils.py

@@ -0,0 +1,212 @@
+"""Shared CLI utilities for drop jump and CMJ analysis."""
+
+from collections.abc import Callable
+from typing import Any, Protocol
+
+import click
+
+from .auto_tuning import AnalysisParameters, QualityPreset, VideoCharacteristics
+from .pose import PoseTracker
+from .smoothing import smooth_landmarks, smooth_landmarks_advanced
+from .video_io import VideoProcessor
+
+
+class ExpertParameters(Protocol):
+    """Protocol for expert parameter overrides."""
+
+    detection_confidence: float | None
+    tracking_confidence: float | None
+    smoothing_window: int | None
+    velocity_threshold: float | None
+    min_contact_frames: int | None
+    visibility_threshold: float | None
+
+
+def determine_initial_confidence(
+    quality_preset: QualityPreset,
+    expert_params: ExpertParameters,
+) -> tuple[float, float]:
+    """Determine initial detection and tracking confidence levels.
+
+    Args:
+        quality_preset: Quality preset enum
+        expert_params: Expert parameter overrides
+
+    Returns:
+        Tuple of (detection_confidence, tracking_confidence)
+    """
+    initial_detection_conf = 0.5
+    initial_tracking_conf = 0.5
+
+    if quality_preset == QualityPreset.FAST:
+        initial_detection_conf = 0.3
+        initial_tracking_conf = 0.3
+    elif quality_preset == QualityPreset.ACCURATE:
+        initial_detection_conf = 0.6
+        initial_tracking_conf = 0.6
+
+    # Override with expert values if provided
+    if expert_params.detection_confidence is not None:
+        initial_detection_conf = expert_params.detection_confidence
+    if expert_params.tracking_confidence is not None:
+        initial_tracking_conf = expert_params.tracking_confidence
+
+    return initial_detection_conf, initial_tracking_conf
+
+
+def track_all_frames(video: VideoProcessor, tracker: PoseTracker) -> tuple[list, list]:
+    """Track pose landmarks in all video frames.
+
+    Args:
+        video: Video processor
+        tracker: Pose tracker
+
+    Returns:
+        Tuple of (frames, landmarks_sequence)
+    """
+    click.echo("Tracking pose landmarks...", err=True)
+    landmarks_sequence = []
+    frames = []
+
+    bar: Any
+    with click.progressbar(length=video.frame_count, label="Processing frames") as bar:
+        while True:
+            frame = video.read_frame()
+            if frame is None:
+                break
+
+            frames.append(frame)
+            landmarks = tracker.process_frame(frame)
+            landmarks_sequence.append(landmarks)
+            bar.update(1)
+
+    tracker.close()
+    return frames, landmarks_sequence
+
+
+def apply_expert_param_overrides(
+    params: AnalysisParameters, expert_params: ExpertParameters
+) -> AnalysisParameters:
+    """Apply expert parameter overrides to auto-tuned parameters.
+
+    Args:
+        params: Auto-tuned parameters
+        expert_params: Expert overrides
+
+    Returns:
+        Modified params object (mutated in place)
+    """
+    if expert_params.smoothing_window is not None:
+        params.smoothing_window = expert_params.smoothing_window
+    if expert_params.velocity_threshold is not None:
+        params.velocity_threshold = expert_params.velocity_threshold
+    if expert_params.min_contact_frames is not None:
+        params.min_contact_frames = expert_params.min_contact_frames
+    if expert_params.visibility_threshold is not None:
+        params.visibility_threshold = expert_params.visibility_threshold
+    return params
+
+
+def print_auto_tuned_params(
+    video: VideoProcessor,
+    quality_preset: QualityPreset,
+    params: AnalysisParameters,
+    characteristics: VideoCharacteristics | None = None,
+    extra_params: dict[str, Any] | None = None,
+) -> None:
+    """Print auto-tuned parameters in verbose mode.
+
+    Args:
+        video: Video processor
+        quality_preset: Quality preset
+        params: Auto-tuned parameters
+        characteristics: Optional video characteristics (for tracking quality display)
+        extra_params: Optional extra parameters to display (e.g., countermovement_threshold)
+    """
+    click.echo("\n" + "=" * 60, err=True)
+    click.echo("AUTO-TUNED PARAMETERS", err=True)
+    click.echo("=" * 60, err=True)
+    click.echo(f"Video FPS: {video.fps:.2f}", err=True)
+
+    if characteristics:
+        click.echo(
+            f"Tracking quality: {characteristics.tracking_quality} "
+            f"(avg visibility: {characteristics.avg_visibility:.2f})",
+            err=True,
+        )
+
+    click.echo(f"Quality preset: {quality_preset.value}", err=True)
+    click.echo("\nSelected parameters:", err=True)
+    click.echo(f"  smoothing_window: {params.smoothing_window}", err=True)
+    click.echo(f"  polyorder: {params.polyorder}", err=True)
+    click.echo(f"  velocity_threshold: {params.velocity_threshold:.4f}", err=True)
+
+    # Print extra parameters if provided
+    if extra_params:
+        for key, value in extra_params.items():
+            if isinstance(value, float):
+                click.echo(f"  {key}: {value:.4f}", err=True)
+            else:
+                click.echo(f"  {key}: {value}", err=True)
+
+    click.echo(f"  min_contact_frames: {params.min_contact_frames}", err=True)
+    click.echo(f"  visibility_threshold: {params.visibility_threshold}", err=True)
+    click.echo(f"  detection_confidence: {params.detection_confidence}", err=True)
+    click.echo(f"  tracking_confidence: {params.tracking_confidence}", err=True)
+    click.echo(f"  outlier_rejection: {params.outlier_rejection}", err=True)
+    click.echo(f"  bilateral_filter: {params.bilateral_filter}", err=True)
+    click.echo(f"  use_curvature: {params.use_curvature}", err=True)
+    click.echo("=" * 60 + "\n", err=True)
+
+
+def smooth_landmark_sequence(
+    landmarks_sequence: list, params: AnalysisParameters
+) -> list:
+    """Apply smoothing to landmark sequence.
+
+    Args:
+        landmarks_sequence: Raw landmark sequence
+        params: Auto-tuned parameters
+
+    Returns:
+        Smoothed landmark sequence
+    """
+    if params.outlier_rejection or params.bilateral_filter:
+        if params.outlier_rejection:
+            click.echo("Smoothing landmarks with outlier rejection...", err=True)
+        if params.bilateral_filter:
+            click.echo(
+                "Using bilateral temporal filter for edge-preserving smoothing...",
+                err=True,
+            )
+        return smooth_landmarks_advanced(
+            landmarks_sequence,
+            window_length=params.smoothing_window,
+            polyorder=params.polyorder,
+            use_outlier_rejection=params.outlier_rejection,
+            use_bilateral=params.bilateral_filter,
+        )
+    else:
+        click.echo("Smoothing landmarks...", err=True)
+        return smooth_landmarks(
+            landmarks_sequence,
+            window_length=params.smoothing_window,
+            polyorder=params.polyorder,
+        )
+
+
+def common_output_options(func: Callable) -> Callable:  # type: ignore[type-arg]
+    """Add common output options to CLI command."""
+    func = click.option(
+        "--output",
+        "-o",
+        type=click.Path(),
+        help="Path for debug video output (optional)",
+    )(func)
+    func = click.option(
+        "--json-output",
+        "-j",
+        type=click.Path(),
+        help="Path for JSON metrics output (default: stdout)",
+    )(func)
+    return func

kinemotion/core/debug_overlay_utils.py

@@ -0,0 +1,143 @@
+"""Shared debug overlay utilities for video rendering."""
+
+import cv2
+import numpy as np
+
+
+def create_video_writer(
+    output_path: str,
+    width: int,
+    height: int,
+    display_width: int,
+    display_height: int,
+    fps: float,
+) -> tuple[cv2.VideoWriter, bool]:
+    """
+    Create a video writer with fallback codec support.
+
+    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)
+    """
+    needs_resize = (display_width != width) or (display_height != height)
+
+    # Try H.264 codec first (better quality/compatibility), fallback to mp4v
+    fourcc = cv2.VideoWriter_fourcc(*"avc1")
+    writer = cv2.VideoWriter(output_path, fourcc, fps, (display_width, display_height))
+
+    # Check if writer opened successfully, fallback to mp4v if not
+    if not writer.isOpened():
+        fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+        writer = cv2.VideoWriter(
+            output_path, fourcc, fps, (display_width, display_height)
+        )
+
+    if not writer.isOpened():
+        raise ValueError(
+            f"Failed to create video writer for {output_path} with dimensions "
+            f"{display_width}x{display_height}"
+        )
+
+    return writer, needs_resize
+
+
+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,
+    ):
+        """
+        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
+        """
+        self.width = width
+        self.height = height
+        self.display_width = display_width
+        self.display_height = display_height
+        self.writer, self.needs_resize = create_video_writer(
+            output_path, width, height, display_width, 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:
+            frame = cv2.resize(
+                frame,
+                (self.display_width, self.display_height),
+                interpolation=cv2.INTER_LANCZOS4,
+            )
+
+        write_overlay_frame(self.writer, frame, self.display_width, self.display_height)
+
+    def close(self) -> None:
+        """Release video writer."""
+        self.writer.release()
+
+    def __enter__(self) -> "BaseDebugOverlayRenderer":
+        return self
+
+    def __exit__(self, _exc_type, _exc_val, _exc_tb) -> None:  # type: ignore[no-untyped-def]
+        self.close()