kinemotion 0.1.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

{dropjump → kinemotion/core}/smoothing.py

@@ -4,6 +4,11 @@
 import numpy as np
 from scipy.signal import savgol_filter
 
+from .filtering import (
+    bilateral_temporal_filter,
+    reject_outliers,
+)
+
 
 def smooth_landmarks(
     landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
@@ -221,3 +226,142 @@ def compute_acceleration_from_derivative(
     )
 
     return acceleration  # type: ignore[no-any-return]
+
+
+def smooth_landmarks_advanced(
+    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    window_length: int = 5,
+    polyorder: int = 2,
+    use_outlier_rejection: bool = True,
+    use_bilateral: bool = False,
+    ransac_threshold: float = 0.02,
+    bilateral_sigma_spatial: float = 3.0,
+    bilateral_sigma_intensity: float = 0.02,
+) -> list[dict[str, tuple[float, float, float]] | None]:
+    """
+    Advanced landmark smoothing with outlier rejection and bilateral filtering.
+
+    Combines multiple techniques for robust smoothing:
+    1. Outlier rejection (RANSAC + median filtering)
+    2. Optional bilateral filtering (edge-preserving)
+    3. Savitzky-Golay smoothing
+
+    Args:
+        landmark_sequence: List of landmark dictionaries from each frame
+        window_length: Length of filter window (must be odd, >= polyorder + 2)
+        polyorder: Order of polynomial used to fit samples
+        use_outlier_rejection: Apply outlier detection and removal
+        use_bilateral: Use bilateral filter instead of Savitzky-Golay
+        ransac_threshold: Threshold for RANSAC outlier detection
+        bilateral_sigma_spatial: Spatial sigma for bilateral filter
+        bilateral_sigma_intensity: Intensity sigma for bilateral filter
+
+    Returns:
+        Smoothed landmark sequence with same structure as input
+    """
+    if len(landmark_sequence) < window_length:
+        # Not enough frames to smooth effectively
+        return landmark_sequence
+
+    # Ensure window_length is odd
+    if window_length % 2 == 0:
+        window_length += 1
+
+    # Extract landmark names from first valid frame
+    landmark_names = None
+    for frame_landmarks in landmark_sequence:
+        if frame_landmarks is not None:
+            landmark_names = list(frame_landmarks.keys())
+            break
+
+    if landmark_names is None:
+        return landmark_sequence
+
+    # Build arrays for each landmark coordinate
+    smoothed_sequence: list[dict[str, tuple[float, float, float]] | None] = []
+
+    for landmark_name in landmark_names:
+        # Extract x, y coordinates for this landmark across all frames
+        x_coords = []
+        y_coords = []
+        valid_frames = []
+
+        for i, frame_landmarks in enumerate(landmark_sequence):
+            if frame_landmarks is not None and landmark_name in frame_landmarks:
+                x, y, vis = frame_landmarks[landmark_name]
+                x_coords.append(x)
+                y_coords.append(y)
+                valid_frames.append(i)
+
+        if len(x_coords) < window_length:
+            continue
+
+        x_array = np.array(x_coords)
+        y_array = np.array(y_coords)
+
+        # Step 1: Outlier rejection
+        if use_outlier_rejection:
+            x_array, _ = reject_outliers(
+                x_array,
+                use_ransac=True,
+                use_median=True,
+                ransac_threshold=ransac_threshold,
+            )
+            y_array, _ = reject_outliers(
+                y_array,
+                use_ransac=True,
+                use_median=True,
+                ransac_threshold=ransac_threshold,
+            )
+
+        # Step 2: Smoothing (bilateral or Savitzky-Golay)
+        if use_bilateral:
+            x_smooth = bilateral_temporal_filter(
+                x_array,
+                window_size=window_length,
+                sigma_spatial=bilateral_sigma_spatial,
+                sigma_intensity=bilateral_sigma_intensity,
+            )
+            y_smooth = bilateral_temporal_filter(
+                y_array,
+                window_size=window_length,
+                sigma_spatial=bilateral_sigma_spatial,
+                sigma_intensity=bilateral_sigma_intensity,
+            )
+        else:
+            # Standard Savitzky-Golay
+            x_smooth = savgol_filter(x_array, window_length, polyorder)
+            y_smooth = savgol_filter(y_array, window_length, polyorder)
+
+        # Store smoothed values back
+        for idx, frame_idx in enumerate(valid_frames):
+            if frame_idx >= len(smoothed_sequence):
+                smoothed_sequence.extend(
+                    [{}] * (frame_idx - len(smoothed_sequence) + 1)
+                )
+
+            # Ensure smoothed_sequence[frame_idx] is a dict, not None
+            if smoothed_sequence[frame_idx] is None:
+                smoothed_sequence[frame_idx] = {}
+
+            if (
+                landmark_name not in smoothed_sequence[frame_idx]  # type: ignore[operator]
+                and landmark_sequence[frame_idx] is not None
+            ):
+                # Keep original visibility
+                orig_vis = landmark_sequence[frame_idx][landmark_name][2]  # type: ignore[index]
+                smoothed_sequence[frame_idx][landmark_name] = (  # type: ignore[index]
+                    float(x_smooth[idx]),
+                    float(y_smooth[idx]),
+                    orig_vis,
+                )
+
+    # Fill in any missing frames with original data
+    for i in range(len(landmark_sequence)):
+        if i >= len(smoothed_sequence) or not smoothed_sequence[i]:
+            if i < len(smoothed_sequence):
+                smoothed_sequence[i] = landmark_sequence[i]
+            else:
+                smoothed_sequence.append(landmark_sequence[i])
+
+    return smoothed_sequence

kinemotion/core/video_io.py

@@ -0,0 +1,122 @@
+"""Generic video I/O functionality for all jump analysis types."""
+
+import json
+import subprocess
+
+import cv2
+import numpy as np
+
+
+class VideoProcessor:
+    """
+    Handles video reading and processing.
+
+    IMPORTANT: This class preserves the exact aspect ratio of the source video.
+    No dimensions are hardcoded - all dimensions are extracted from actual frame data.
+    """
+
+    def __init__(self, video_path: str):
+        """
+        Initialize video processor.
+
+        Args:
+            video_path: Path to input video file
+        """
+        self.video_path = video_path
+        self.cap = cv2.VideoCapture(video_path)
+
+        if not self.cap.isOpened():
+            raise ValueError(f"Could not open video: {video_path}")
+
+        self.fps = self.cap.get(cv2.CAP_PROP_FPS)
+        self.frame_count = int(self.cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+        # Read first frame to get actual dimensions
+        # This is critical for preserving aspect ratio, especially with mobile videos
+        # that have rotation metadata. OpenCV properties (CAP_PROP_FRAME_WIDTH/HEIGHT)
+        # may return incorrect dimensions, so we read the actual frame data.
+        ret, first_frame = self.cap.read()
+        if ret:
+            # frame.shape is (height, width, channels) - extract actual dimensions
+            self.height, self.width = first_frame.shape[:2]
+            self.cap.set(cv2.CAP_PROP_POS_FRAMES, 0)  # Reset to beginning
+        else:
+            # Fallback to video properties if can't read frame
+            self.width = int(self.cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+            self.height = int(self.cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+
+        # Calculate display dimensions considering SAR (Sample Aspect Ratio)
+        # Mobile videos often have non-square pixels encoded in SAR metadata
+        # OpenCV doesn't directly expose SAR, but we need to handle display correctly
+        self.display_width = self.width
+        self.display_height = self.height
+        self._calculate_display_dimensions()
+
+    def _calculate_display_dimensions(self) -> None:
+        """
+        Calculate display dimensions by reading SAR metadata from video file.
+
+        Many mobile videos use non-square pixels (SAR != 1:1), which means
+        the encoded dimensions differ from how the video should be displayed.
+        We use ffprobe to extract this metadata.
+        """
+        try:
+            # Use ffprobe to get SAR metadata
+            result = subprocess.run(
+                [
+                    "ffprobe",
+                    "-v",
+                    "quiet",
+                    "-print_format",
+                    "json",
+                    "-show_streams",
+                    "-select_streams",
+                    "v:0",
+                    self.video_path,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+
+            if result.returncode == 0:
+                data = json.loads(result.stdout)
+                if "streams" in data and len(data["streams"]) > 0:
+                    stream = data["streams"][0]
+                    sar_str = stream.get("sample_aspect_ratio", "1:1")
+
+                    # Parse SAR (e.g., "270:473")
+                    if sar_str and ":" in sar_str:
+                        sar_parts = sar_str.split(":")
+                        sar_width = int(sar_parts[0])
+                        sar_height = int(sar_parts[1])
+
+                        # Calculate display dimensions
+                        # DAR = (width * SAR_width) / (height * SAR_height)
+                        if sar_width != sar_height:
+                            self.display_width = int(
+                                self.width * sar_width / sar_height
+                            )
+                            self.display_height = self.height
+        except (subprocess.TimeoutExpired, FileNotFoundError, json.JSONDecodeError):
+            # If ffprobe fails, keep original dimensions (square pixels)
+            pass
+
+    def read_frame(self) -> np.ndarray | None:
+        """Read next frame from video."""
+        ret, frame = self.cap.read()
+        return frame if ret else None
+
+    def reset(self) -> None:
+        """Reset video to beginning."""
+        self.cap.set(cv2.CAP_PROP_POS_FRAMES, 0)
+
+    def close(self) -> None:
+        """Release video capture."""
+        self.cap.release()
+
+    def __enter__(self) -> "VideoProcessor":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:  # type: ignore[no-untyped-def]
+        self.close()

kinemotion/dropjump/__init__.py

@@ -0,0 +1,29 @@
+"""Drop jump analysis module."""
+
+from .analysis import (
+    ContactState,
+    calculate_adaptive_threshold,
+    compute_average_foot_position,
+    detect_ground_contact,
+    find_interpolated_phase_transitions_with_curvature,
+    interpolate_threshold_crossing,
+    refine_transition_with_curvature,
+)
+from .debug_overlay import DebugOverlayRenderer
+from .kinematics import DropJumpMetrics, calculate_drop_jump_metrics
+
+__all__ = [
+    # Contact detection
+    "ContactState",
+    "detect_ground_contact",
+    "compute_average_foot_position",
+    "calculate_adaptive_threshold",
+    "interpolate_threshold_crossing",
+    "refine_transition_with_curvature",
+    "find_interpolated_phase_transitions_with_curvature",
+    # Metrics
+    "DropJumpMetrics",
+    "calculate_drop_jump_metrics",
+    # Debug overlay
+    "DebugOverlayRenderer",
+]

dropjump/contact_detection.py → kinemotion/dropjump/analysis.py

@@ -4,7 +4,7 @@ from enum import Enum
 
 import numpy as np
 
-from .smoothing import (
+from ..core.smoothing import (
     compute_acceleration_from_derivative,
     compute_velocity_from_derivative,
 )
@@ -18,22 +18,101 @@ class ContactState(Enum):
     UNKNOWN = "unknown"
 
 
+def calculate_adaptive_threshold(
+    positions: np.ndarray,
+    fps: float,
+    baseline_duration: float = 3.0,
+    multiplier: float = 1.5,
+    smoothing_window: int = 5,
+    polyorder: int = 2,
+) -> float:
+    """
+    Calculate adaptive velocity threshold based on baseline motion characteristics.
+
+    Analyzes the first few seconds of video (assumed to be relatively stationary,
+    e.g., athlete standing on box) to determine the noise floor, then sets threshold
+    as a multiple of this baseline noise.
+
+    This adapts to:
+    - Different camera distances (closer = more pixel movement)
+    - Different lighting conditions (affects tracking quality)
+    - Different frame rates (higher fps = smoother motion)
+    - Video compression artifacts
+
+    Args:
+        positions: Array of vertical positions (0-1 normalized)
+        fps: Video frame rate
+        baseline_duration: Duration in seconds to analyze for baseline (default: 3.0s)
+        multiplier: Factor above baseline noise to set threshold (default: 1.5x)
+        smoothing_window: Window size for velocity computation
+        polyorder: Polynomial order for Savitzky-Golay filter (default: 2)
+
+    Returns:
+        Adaptive velocity threshold value
+
+    Example:
+        At 30fps with 3s baseline:
+        - Analyzes first 90 frames
+        - Computes velocity for this "stationary" period
+        - 95th percentile velocity = 0.012 (noise level)
+        - Threshold = 0.012 × 1.5 = 0.018
+    """
+    if len(positions) < 2:
+        return 0.02  # Fallback to default
+
+    # Calculate number of frames for baseline analysis
+    baseline_frames = int(fps * baseline_duration)
+    baseline_frames = min(baseline_frames, len(positions))
+
+    if baseline_frames < smoothing_window:
+        return 0.02  # Not enough data, use default
+
+    # Extract baseline period (assumed relatively stationary)
+    baseline_positions = positions[:baseline_frames]
+
+    # Compute velocity for baseline period using derivative
+    baseline_velocities = compute_velocity_from_derivative(
+        baseline_positions, window_length=smoothing_window, polyorder=polyorder
+    )
+
+    # Calculate noise floor as 95th percentile of baseline velocities
+    # Using 95th percentile instead of max to be robust against outliers
+    noise_floor = float(np.percentile(np.abs(baseline_velocities), 95))
+
+    # Set threshold as multiplier of noise floor
+    # Minimum threshold to avoid being too sensitive
+    adaptive_threshold = max(noise_floor * multiplier, 0.005)
+
+    # Maximum threshold to ensure we still detect contact
+    adaptive_threshold = min(adaptive_threshold, 0.05)
+
+    return adaptive_threshold
+
+
 def detect_ground_contact(
     foot_positions: np.ndarray,
     velocity_threshold: float = 0.02,
     min_contact_frames: int = 3,
     visibility_threshold: float = 0.5,
     visibilities: np.ndarray | None = None,
+    window_length: int = 5,
+    polyorder: int = 2,
 ) -> list[ContactState]:
     """
     Detect when feet are in contact with ground based on vertical motion.
 
+    Uses derivative-based velocity calculation via Savitzky-Golay filter for smooth,
+    accurate velocity estimates. This is consistent with the velocity calculation used
+    throughout the pipeline for sub-frame interpolation and curvature analysis.
+
     Args:
         foot_positions: Array of foot y-positions (normalized, 0-1, where 1 is bottom)
         velocity_threshold: Threshold for vertical velocity to consider stationary
         min_contact_frames: Minimum consecutive frames to confirm contact
         visibility_threshold: Minimum visibility score to trust landmark
         visibilities: Array of visibility scores for each frame
+        window_length: Window size for velocity derivative calculation (must be odd)
+        polyorder: Polynomial order for Savitzky-Golay filter (default: 2)
 
     Returns:
         List of ContactState for each frame
@@ -44,8 +123,12 @@ def detect_ground_contact(
     if n_frames < 2:
         return states
 
-    # Compute vertical velocity (positive = moving down in image coordinates)
-    velocities = np.diff(foot_positions, prepend=foot_positions[0])
+    # Compute vertical velocity using derivative-based method
+    # This provides smoother, more accurate velocity estimates than frame-to-frame differences
+    # and is consistent with the velocity calculation used for sub-frame interpolation
+    velocities = compute_velocity_from_derivative(
+        foot_positions, window_length=window_length, polyorder=polyorder
+    )
 
     # Detect potential contact frames based on low velocity
     is_stationary = np.abs(velocities) < velocity_threshold
@@ -245,6 +328,7 @@ def refine_transition_with_curvature(
     transition_type: str,
     search_window: int = 3,
     smoothing_window: int = 5,
+    polyorder: int = 2,
 ) -> float:
     """
     Refine phase transition timing using trajectory curvature analysis.
@@ -259,6 +343,7 @@ def refine_transition_with_curvature(
         transition_type: Type of transition ("landing" or "takeoff")
         search_window: Number of frames to search around estimate
         smoothing_window: Window size for acceleration computation
+        polyorder: Polynomial order for Savitzky-Golay filter (default: 2)
 
     Returns:
         Refined fractional frame index
@@ -268,7 +353,7 @@ def refine_transition_with_curvature(
 
     # Compute acceleration (second derivative)
     acceleration = compute_acceleration_from_derivative(
-        foot_positions, window_length=smoothing_window, polyorder=2
+        foot_positions, window_length=smoothing_window, polyorder=polyorder
     )
 
     # Define search range around estimated transition
@@ -319,6 +404,7 @@ def find_interpolated_phase_transitions_with_curvature(
     contact_states: list[ContactState],
     velocity_threshold: float,
     smoothing_window: int = 5,
+    polyorder: int = 2,
     use_curvature: bool = True,
 ) -> list[tuple[float, float, ContactState]]:
     """
@@ -334,6 +420,7 @@ def find_interpolated_phase_transitions_with_curvature(
         contact_states: List of ContactState for each frame
         velocity_threshold: Threshold used for contact detection
         smoothing_window: Window size for velocity/acceleration smoothing
+        polyorder: Polynomial order for Savitzky-Golay filter (default: 2)
         use_curvature: Whether to apply curvature-based refinement
 
     Returns:
@@ -362,6 +449,7 @@ def find_interpolated_phase_transitions_with_curvature(
                 "landing",
                 search_window=3,
                 smoothing_window=smoothing_window,
+                polyorder=polyorder,
             )
             # Refine takeoff (end of ground contact)
             refined_end = refine_transition_with_curvature(
@@ -370,6 +458,7 @@ def find_interpolated_phase_transitions_with_curvature(
                 "takeoff",
                 search_window=3,
                 smoothing_window=smoothing_window,
+                polyorder=polyorder,
             )
 
         elif state == ContactState.IN_AIR:
@@ -380,6 +469,7 @@ def find_interpolated_phase_transitions_with_curvature(
                 "takeoff",
                 search_window=3,
                 smoothing_window=smoothing_window,
+                polyorder=polyorder,
             )
             refined_end = refine_transition_with_curvature(
                 foot_positions,
@@ -387,6 +477,7 @@ def find_interpolated_phase_transitions_with_curvature(
                 "landing",
                 search_window=3,
                 smoothing_window=smoothing_window,
+                polyorder=polyorder,
             )
 
         refined_phases.append((refined_start, refined_end, state))