kinemotion 0.17.0__py3-none-any.whl

kinemotion/core/smoothing.py

@@ -0,0 +1,412 @@
+"""Landmark smoothing utilities to reduce jitter in pose tracking."""
+
+import numpy as np
+from scipy.signal import savgol_filter
+
+from .filtering import (
+    bilateral_temporal_filter,
+    reject_outliers,
+)
+
+
+def _extract_landmark_coordinates(
+    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    landmark_name: str,
+) -> tuple[list[float], list[float], list[int]]:
+    """
+    Extract x, y coordinates and valid frame indices for a specific landmark.
+
+    Args:
+        landmark_sequence: List of landmark dictionaries from each frame
+        landmark_name: Name of the landmark to extract
+
+    Returns:
+        Tuple of (x_coords, y_coords, valid_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, _ = frame_landmarks[landmark_name]  # vis not used
+            x_coords.append(x)
+            y_coords.append(y)
+            valid_frames.append(i)
+
+    return x_coords, y_coords, valid_frames
+
+
+def _get_landmark_names(
+    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+) -> list[str] | None:
+    """
+    Extract landmark names from first valid frame.
+
+    Args:
+        landmark_sequence: List of landmark dictionaries from each frame
+
+    Returns:
+        List of landmark names or None if no valid frame found
+    """
+    for frame_landmarks in landmark_sequence:
+        if frame_landmarks is not None:
+            return list(frame_landmarks.keys())
+    return None
+
+
+def _fill_missing_frames(
+    smoothed_sequence: list[dict[str, tuple[float, float, float]] | None],
+    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+) -> None:
+    """
+    Fill in any missing frames in smoothed sequence with original data.
+
+    Args:
+        smoothed_sequence: Smoothed sequence (modified in place)
+        landmark_sequence: Original sequence
+    """
+    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])
+
+
+def _store_smoothed_landmarks(
+    smoothed_sequence: list[dict[str, tuple[float, float, float]] | None],
+    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    landmark_name: str,
+    x_smooth: np.ndarray,
+    y_smooth: np.ndarray,
+    valid_frames: list[int],
+) -> None:
+    """
+    Store smoothed landmark values back into the sequence.
+
+    Args:
+        smoothed_sequence: Sequence to store smoothed values into (modified in place)
+        landmark_sequence: Original sequence (for visibility values)
+        landmark_name: Name of the landmark being smoothed
+        x_smooth: Smoothed x coordinates
+        y_smooth: Smoothed y coordinates
+        valid_frames: Frame indices corresponding to smoothed values
+    """
+    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] = {}
+
+        # Type narrowing: after the check above, we know it's a dict
+        frame_dict = smoothed_sequence[frame_idx]
+        assert frame_dict is not None  # for type checker
+
+        if landmark_name not in frame_dict and landmark_sequence[frame_idx] is not None:
+            # Keep original visibility
+            orig_landmarks = landmark_sequence[frame_idx]
+            assert orig_landmarks is not None  # for type checker
+            orig_vis = orig_landmarks[landmark_name][2]
+            frame_dict[landmark_name] = (
+                float(x_smooth[idx]),
+                float(y_smooth[idx]),
+                orig_vis,
+            )
+
+
+def _smooth_landmarks_core(  # NOSONAR(S1172) - polyorder used via closure capture in smoother_fn
+    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    window_length: int,
+    polyorder: int,
+    smoother_fn,  # type: ignore[no-untyped-def]
+) -> list[dict[str, tuple[float, float, float]] | None]:
+    """
+    Core smoothing logic shared by both standard and advanced smoothing.
+
+    Args:
+        landmark_sequence: List of landmark dictionaries from each frame
+        window_length: Length of filter window (must be odd)
+        polyorder: Order of polynomial used to fit samples (captured by smoother_fn closure)
+        smoother_fn: Function that takes (x_coords, y_coords, valid_frames)
+            and returns (x_smooth, y_smooth)
+
+    Returns:
+        Smoothed landmark sequence
+    """
+    landmark_names = _get_landmark_names(landmark_sequence)
+    if landmark_names is None:
+        return landmark_sequence
+
+    smoothed_sequence: list[dict[str, tuple[float, float, float]] | None] = []
+
+    for landmark_name in landmark_names:
+        x_coords, y_coords, valid_frames = _extract_landmark_coordinates(
+            landmark_sequence, landmark_name
+        )
+
+        if len(x_coords) < window_length:
+            continue
+
+        # Apply smoothing function
+        x_smooth, y_smooth = smoother_fn(x_coords, y_coords, valid_frames)
+
+        # Store smoothed values back
+        _store_smoothed_landmarks(
+            smoothed_sequence,
+            landmark_sequence,
+            landmark_name,
+            x_smooth,
+            y_smooth,
+            valid_frames,
+        )
+
+    # Fill in any missing frames with original data
+    _fill_missing_frames(smoothed_sequence, landmark_sequence)
+
+    return smoothed_sequence
+
+
+def smooth_landmarks(
+    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    window_length: int = 5,
+    polyorder: int = 2,
+) -> list[dict[str, tuple[float, float, float]] | None]:
+    """
+    Smooth landmark trajectories using Savitzky-Golay filter.
+
+    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
+
+    Returns:
+        Smoothed landmark sequence with same structure as input
+    """
+    if len(landmark_sequence) < window_length:
+        return landmark_sequence
+
+    # Ensure window_length is odd
+    if window_length % 2 == 0:
+        window_length += 1
+
+    def savgol_smoother(x_coords, y_coords, _valid_frames):  # type: ignore[no-untyped-def]
+        x_smooth = savgol_filter(x_coords, window_length, polyorder)
+        y_smooth = savgol_filter(y_coords, window_length, polyorder)
+        return x_smooth, y_smooth
+
+    return _smooth_landmarks_core(
+        landmark_sequence, window_length, polyorder, savgol_smoother
+    )
+
+
+def compute_velocity(
+    positions: np.ndarray, fps: float, smooth_window: int = 3
+) -> np.ndarray:
+    """
+    Compute velocity from position data.
+
+    Args:
+        positions: Array of positions over time (n_frames, n_dims)
+        fps: Frames per second of the video
+        smooth_window: Window size for velocity smoothing
+
+    Returns:
+        Velocity array (n_frames, n_dims)
+    """
+    dt = 1.0 / fps
+    velocity = np.gradient(positions, dt, axis=0)
+
+    # Smooth velocity if we have enough data
+    if len(velocity) >= smooth_window and smooth_window > 1:
+        if smooth_window % 2 == 0:
+            smooth_window += 1
+        for dim in range(velocity.shape[1]):
+            velocity[:, dim] = savgol_filter(velocity[:, dim], smooth_window, 1)
+
+    return velocity
+
+
+def compute_velocity_from_derivative(
+    positions: np.ndarray,
+    window_length: int = 5,
+    polyorder: int = 2,
+) -> np.ndarray:
+    """
+    Compute velocity as derivative of smoothed position trajectory.
+
+    Uses Savitzky-Golay filter to compute the derivative directly, which provides
+    a much smoother and more accurate velocity estimate than frame-to-frame differences.
+
+    This method:
+    1. Fits a polynomial to the position data in a sliding window
+    2. Analytically computes the derivative of that polynomial
+    3. Returns smooth velocity values
+
+    Args:
+        positions: 1D array of position values (e.g., foot y-positions)
+        window_length: Window size for smoothing (must be odd, >= polyorder + 2)
+        polyorder: Polynomial order for Savitzky-Golay filter (typically 2 or 3)
+
+    Returns:
+        Array of absolute velocity values (magnitude of derivative)
+    """
+    if len(positions) < window_length:
+        # Fallback to simple differences for short sequences
+        return np.abs(np.diff(positions, prepend=positions[0]))
+
+    # Ensure window_length is odd
+    if window_length % 2 == 0:
+        window_length += 1
+
+    # Compute derivative using Savitzky-Golay filter
+    # deriv=1: compute first derivative
+    # delta=1.0: frame spacing (velocity per frame)
+    # mode='interp': interpolate at boundaries
+    velocity = savgol_filter(
+        positions,
+        window_length,
+        polyorder,
+        deriv=1,  # First derivative
+        delta=1.0,  # Frame spacing
+        mode="interp",
+    )
+
+    # Return absolute velocity (magnitude only)
+    return np.abs(velocity)
+
+
+def compute_acceleration_from_derivative(
+    positions: np.ndarray,
+    window_length: int = 5,
+    polyorder: int = 2,
+) -> np.ndarray:
+    """
+    Compute acceleration as second derivative of smoothed position trajectory.
+
+    Uses Savitzky-Golay filter to compute the second derivative directly,
+    providing smooth acceleration (curvature) estimates for detecting
+    characteristic patterns at landing and takeoff.
+
+    Landing and takeoff events show distinctive acceleration patterns:
+    - Landing: Large acceleration spike as feet decelerate on impact
+    - Takeoff: Acceleration change as body accelerates upward
+    - In flight: Constant acceleration due to gravity
+    - On ground: Near-zero acceleration (stationary position)
+
+    Args:
+        positions: 1D array of position values (e.g., foot y-positions)
+        window_length: Window size for smoothing (must be odd, >= polyorder + 2)
+        polyorder: Polynomial order for Savitzky-Golay filter (typically 2 or 3)
+
+    Returns:
+        Array of acceleration values (second derivative of position)
+    """
+    if len(positions) < window_length:
+        # Fallback to simple second differences for short sequences
+        velocity = np.diff(positions, prepend=positions[0])
+        return np.diff(velocity, prepend=velocity[0])
+
+    # Ensure window_length is odd
+    if window_length % 2 == 0:
+        window_length += 1
+
+    # Compute second derivative using Savitzky-Golay filter
+    # deriv=2: compute second derivative (acceleration/curvature)
+    # delta=1.0: frame spacing
+    # mode='interp': interpolate at boundaries
+    acceleration = savgol_filter(
+        positions,
+        window_length,
+        polyorder,
+        deriv=2,  # Second derivative
+        delta=1.0,  # Frame spacing
+        mode="interp",
+    )
+
+    return acceleration
+
+
+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:
+        return landmark_sequence
+
+    # Ensure window_length is odd
+    if window_length % 2 == 0:
+        window_length += 1
+
+    def advanced_smoother(x_coords, y_coords, _valid_frames):  # type: ignore[no-untyped-def]
+        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)
+
+        return x_smooth, y_smooth
+
+    return _smooth_landmarks_core(
+        landmark_sequence, window_length, polyorder, advanced_smoother
+    )

kinemotion/core/video_io.py

@@ -0,0 +1,186 @@
+"""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))
+
+        # Extract rotation metadata from video (iPhones store rotation in side_data_list)
+        # OpenCV ignores rotation metadata, so we need to extract and apply it manually
+        self.rotation = 0  # Will be set by _extract_video_metadata()
+
+        # 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._extract_video_metadata()
+
+        # Apply rotation to dimensions if needed
+        if self.rotation in [90, -90, 270]:
+            # Swap dimensions for 90/-90 degree rotations
+            self.width, self.height = self.height, self.width
+            self.display_width, self.display_height = (
+                self.display_height,
+                self.display_width,
+            )
+
+    def _parse_sample_aspect_ratio(self, sar_str: str) -> None:
+        """
+        Parse SAR string and update display dimensions.
+
+        Args:
+            sar_str: SAR string in format "width:height" (e.g., "270:473")
+        """
+        if not sar_str or ":" not in sar_str:
+            return
+
+        sar_parts = sar_str.split(":")
+        sar_width = int(sar_parts[0])
+        sar_height = int(sar_parts[1])
+
+        # Calculate display dimensions if pixels are non-square
+        # 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
+
+    def _extract_rotation_from_stream(self, stream: dict) -> int:  # type: ignore[type-arg]
+        """
+        Extract rotation metadata from video stream.
+
+        Args:
+            stream: ffprobe stream dictionary
+
+        Returns:
+            Rotation angle in degrees (0, 90, -90, 180)
+        """
+        side_data_list = stream.get("side_data_list", [])
+        for side_data in side_data_list:
+            if side_data.get("side_data_type") == "Display Matrix":
+                rotation = side_data.get("rotation", 0)
+                return int(rotation)
+        return 0
+
+    def _extract_video_metadata(self) -> None:
+        """
+        Extract video metadata including SAR and rotation using ffprobe.
+
+        Many mobile videos (especially from iPhones) have:
+        - Non-square pixels (SAR != 1:1) affecting display dimensions
+        - Rotation metadata in side_data_list that OpenCV ignores
+
+        We extract both to ensure proper display and pose detection.
+        """
+        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:
+                return
+
+            data = json.loads(result.stdout)
+            if "streams" not in data or len(data["streams"]) == 0:
+                return
+
+            stream = data["streams"][0]
+
+            # Extract and parse SAR (Sample Aspect Ratio)
+            sar_str = stream.get("sample_aspect_ratio", "1:1")
+            self._parse_sample_aspect_ratio(sar_str)
+
+            # Extract rotation from side_data_list (common for iPhone videos)
+            self.rotation = self._extract_rotation_from_stream(stream)
+
+        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 and apply rotation if needed.
+
+        OpenCV ignores rotation metadata, so we manually apply rotation
+        based on the display matrix metadata extracted from the video.
+        """
+        ret, frame = self.cap.read()
+        if not ret:
+            return None
+
+        # Apply rotation if video has rotation metadata
+        if self.rotation == -90 or self.rotation == 270:
+            # -90 degrees = rotate 90 degrees clockwise
+            frame = cv2.rotate(frame, cv2.ROTATE_90_CLOCKWISE)
+        elif self.rotation == 90 or self.rotation == -270:
+            # 90 degrees = rotate 90 degrees counter-clockwise
+            frame = cv2.rotate(frame, cv2.ROTATE_90_COUNTERCLOCKWISE)
+        elif self.rotation == 180 or self.rotation == -180:
+            # 180 degrees rotation
+            frame = cv2.rotate(frame, cv2.ROTATE_180)
+
+        return frame
+
+    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",
+]