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

kinemotion/core/smoothing.py

@@ -181,18 +181,6 @@ def _smooth_landmarks_core(  # NOSONAR(S1172) - polyorder used via closure
     return smoothed_sequence
 
 
-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 smooth_landmarks(
     landmark_sequence: LandmarkSequence,
     window_length: int = 5,
@@ -212,7 +200,9 @@ def smooth_landmarks(
     if len(landmark_sequence) < window_length:
         return landmark_sequence
 
-    window_length = _ensure_odd_window_length(window_length)
+    # Ensure window_length is odd
+    if window_length % 2 == 0:
+        window_length += 1
 
     def savgol_smoother(
         x_coords: list[float], y_coords: list[float], _valid_frames: list[int]
@@ -241,87 +231,61 @@ def compute_velocity(positions: np.ndarray, fps: float, smooth_window: int = 3)
 
     # Smooth velocity if we have enough data
     if len(velocity) >= smooth_window and smooth_window > 1:
-        smooth_window = _ensure_odd_window_length(smooth_window)
+        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_derivative(
+def compute_velocity_from_derivative(
     positions: np.ndarray,
-    deriv_order: int,
     window_length: int = 5,
     polyorder: int = 2,
 ) -> np.ndarray:
     """
-    Compute nth derivative using Savitzky-Golay filter.
+    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 unified function handles both velocity (first derivative) and
-    acceleration (second derivative) computation with a single implementation.
+    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)
-        deriv_order: Order of derivative (1 for velocity, 2 for acceleration)
         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 derivative values
+        Array of absolute velocity values (magnitude of derivative)
     """
     if len(positions) < window_length:
         # Fallback to simple differences for short sequences
-        if deriv_order == 1:
-            return np.abs(np.diff(positions, prepend=positions[0]))
-        # Second derivative fallback
-        velocity = np.diff(positions, prepend=positions[0])
-        return np.diff(velocity, prepend=velocity[0])
+        return np.abs(np.diff(positions, prepend=positions[0]))
 
-    window_length = _ensure_odd_window_length(window_length)
+    # Ensure window_length is odd
+    if window_length % 2 == 0:
+        window_length += 1
 
     # Compute derivative using Savitzky-Golay filter
-    # delta=1.0: frame spacing
+    # deriv=1: compute first derivative
+    # delta=1.0: frame spacing (velocity per frame)
     # mode='interp': interpolate at boundaries
-    result = savgol_filter(
+    velocity = savgol_filter(
         positions,
         window_length,
         polyorder,
-        deriv=deriv_order,
-        delta=1.0,
+        deriv=1,  # First derivative
+        delta=1.0,  # Frame spacing
         mode="interp",
     )
 
-    # Return absolute values for velocity (first derivative)
-    return np.abs(result) if deriv_order == 1 else result
-
-
-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)
-    """
-    return _compute_derivative(
-        positions, deriv_order=1, window_length=window_length, polyorder=polyorder
-    )
+    # Return absolute velocity (magnitude only)
+    return np.abs(velocity)
 
 
 def compute_acceleration_from_derivative(
@@ -350,10 +314,30 @@ def compute_acceleration_from_derivative(
     Returns:
         Array of acceleration values (second derivative of position)
     """
-    return _compute_derivative(
-        positions, deriv_order=2, window_length=window_length, polyorder=polyorder
+    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: LandmarkSequence,
@@ -392,7 +376,9 @@ def smooth_landmarks_advanced(
     if len(landmark_sequence) < window_length:
         return landmark_sequence
 
-    window_length = _ensure_odd_window_length(window_length)
+    # Ensure window_length is odd
+    if window_length % 2 == 0:
+        window_length += 1
 
     def advanced_smoother(
         x_coords: list[float], y_coords: list[float], _valid_frames: list[int]

kinemotion/core/types.py

@@ -29,19 +29,6 @@ LandmarkSequence: TypeAlias = list[LandmarkFrame]
 # - Wrapper structures: e.g. {"data": {...actual metrics...}}
 MetricsDict: TypeAlias = dict[str, Any]
 
-# MediaPipe foot landmark names used for position and visibility tracking
-FOOT_KEYS: tuple[str, ...] = (
-    "left_ankle",
-    "right_ankle",
-    "left_heel",
-    "right_heel",
-    "left_foot_index",
-    "right_foot_index",
-)
-
-# MediaPipe hip landmark names used for position tracking
-HIP_KEYS: tuple[str, ...] = ("left_hip", "right_hip")
-
 __all__ = [
     "FloatArray",
     "Float64Array",
@@ -52,6 +39,4 @@ __all__ = [
     "LandmarkFrame",
     "LandmarkSequence",
     "MetricsDict",
-    "FOOT_KEYS",
-    "HIP_KEYS",
 ]

kinemotion/core/validation.py

@@ -78,18 +78,19 @@ class MetricBounds:
 
     def contains(self, value: float, profile: AthleteProfile) -> bool:
         """Check if value is within bounds for athlete profile."""
-        # ELDERLY and UNTRAINED use same bounds (practical to recreational)
-        if profile in (AthleteProfile.ELDERLY, AthleteProfile.UNTRAINED):
+        if profile == AthleteProfile.ELDERLY:
             return self.practical_min <= value <= self.recreational_max
-        if profile == AthleteProfile.RECREATIONAL:
+        elif profile == AthleteProfile.UNTRAINED:
+            return self.practical_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.RECREATIONAL:
             return self.recreational_min <= value <= self.recreational_max
-        if profile == AthleteProfile.ELITE:
-            return self.elite_min <= value <= self.elite_max
-        if profile == AthleteProfile.TRAINED:
+        elif profile == AthleteProfile.TRAINED:
             # Trained athletes: midpoint between recreational and elite
             trained_min = (self.recreational_min + self.elite_min) / 2
             trained_max = (self.recreational_max + self.elite_max) / 2
             return trained_min <= value <= trained_max
+        elif profile == AthleteProfile.ELITE:
+            return self.elite_min <= value <= self.elite_max
         return False
 
     def is_physically_possible(self, value: float) -> bool:
@@ -198,73 +199,3 @@ class MetricsValidator(ABC):
             ValidationResult with all issues and status
         """
         pass
-
-    def _validate_metric_with_bounds(
-        self,
-        name: str,
-        value: float,
-        bounds: MetricBounds,
-        profile: AthleteProfile | None,
-        result: ValidationResult,
-        error_suffix: str = "physically impossible",
-        format_str: str = "{value}",
-    ) -> None:
-        """Generic validation for metrics with physical and profile bounds.
-
-        Args:
-            name: Metric name for messages
-            value: Metric value
-            bounds: Bounds definition
-            profile: Athlete profile for expected ranges (can be None)
-            result: Validation result to add issues to
-            error_suffix: Description for out-of-bounds errors
-            format_str: Format string for value display
-        """
-        formatted_value = format_str.format(value=value)
-        display_name = name.replace("_", " ").title()
-
-        if not bounds.is_physically_possible(value):
-            result.add_error(
-                name,
-                f"{display_name} {formatted_value} {error_suffix}",
-                value=value,
-                bounds=(bounds.absolute_min, bounds.absolute_max),
-            )
-        elif profile is not None and bounds.contains(value, profile):
-            result.add_info(
-                name,
-                f"{display_name} {formatted_value} within expected range for {profile.value}",
-                value=value,
-            )
-        elif profile is not None:
-            expected_min, expected_max = self._get_profile_range(profile, bounds)
-            result.add_warning(
-                name,
-                f"{display_name} {formatted_value} outside typical range "
-                f"[{expected_min:.3f}-{expected_max:.3f}] for {profile.value}",
-                value=value,
-                bounds=(expected_min, expected_max),
-            )
-
-    @staticmethod
-    def _get_profile_range(profile: AthleteProfile, bounds: MetricBounds) -> tuple[float, float]:
-        """Get min/max bounds for specific profile.
-
-        Args:
-            profile: Athlete profile
-            bounds: Metric bounds definition
-
-        Returns:
-            Tuple of (min, max) bounds for the profile
-        """
-        profile_ranges = {
-            AthleteProfile.ELDERLY: (bounds.practical_min, bounds.recreational_max),
-            AthleteProfile.UNTRAINED: (bounds.practical_min, bounds.recreational_max),
-            AthleteProfile.RECREATIONAL: (bounds.recreational_min, bounds.recreational_max),
-            AthleteProfile.TRAINED: (
-                (bounds.recreational_min + bounds.elite_min) / 2,
-                (bounds.recreational_max + bounds.elite_max) / 2,
-            ),
-            AthleteProfile.ELITE: (bounds.elite_min, bounds.elite_max),
-        }
-        return profile_ranges.get(profile, (bounds.absolute_min, bounds.absolute_max))

kinemotion/core/video_io.py

@@ -18,17 +18,6 @@ class VideoProcessor:
     No dimensions are hardcoded - all dimensions are extracted from actual frame data.
     """
 
-    # Mapping of rotation angles to OpenCV rotation operations
-    # Keys are normalized angles (equivalent angles grouped)
-    _ROTATION_OPS: dict[int, int] = {
-        -90: cv2.ROTATE_90_CLOCKWISE,
-        270: cv2.ROTATE_90_CLOCKWISE,
-        90: cv2.ROTATE_90_COUNTERCLOCKWISE,
-        -270: cv2.ROTATE_90_COUNTERCLOCKWISE,
-        180: cv2.ROTATE_180,
-        -180: cv2.ROTATE_180,
-    }
-
     def __init__(self, video_path: str, timer: Timer | None = None) -> None:
         """
         Initialize video processor.
@@ -50,27 +39,9 @@ class VideoProcessor:
         self._current_timestamp_ms: int = 0  # Timestamp for the current frame
 
         # Read first frame to get actual dimensions
-        self._extract_dimensions_from_frame()
-
-        # Initialize metadata placeholders
-        self.rotation = 0  # Will be set by _extract_video_metadata()
-        self.codec: str | None = None  # Will be set by _extract_video_metadata()
-
-        # Initialize display dimensions (may be adjusted by SAR metadata)
-        self.display_width = self.width
-        self.display_height = self.height
-        self._extract_video_metadata()
-
-        # Apply rotation to dimensions if needed
-        self._apply_rotation_to_dimensions()
-
-    def _extract_dimensions_from_frame(self) -> None:
-        """Extract video dimensions by reading the first frame.
-
-        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.
-        """
+        # 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
@@ -81,13 +52,22 @@ class VideoProcessor:
             self.width = int(self.cap.get(cv2.CAP_PROP_FRAME_WIDTH))
             self.height = int(self.cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
 
-    def _apply_rotation_to_dimensions(self) -> None:
-        """Swap width/height for 90/-90 degree rotations.
+        # 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()
+
+        # Extract codec information from video metadata
+        self.codec: str | None = None  # Will be set by _extract_video_metadata()
 
-        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.
-        """
+        # 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
@@ -236,9 +216,15 @@ class VideoProcessor:
 
         # Apply rotation if video has rotation metadata
         with self.timer.measure("frame_rotation"):
-            rotation_op = self._ROTATION_OPS.get(self.rotation)
-            if rotation_op is not None:
-                frame = cv2.rotate(frame, rotation_op)
+            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)
 
         self._frame_index += 1
         return frame

kinemotion/{drop_jump → dropjump}/__init__.py

@@ -3,10 +3,13 @@
 from ..core.smoothing import interpolate_threshold_crossing
 from .analysis import (
     ContactState,
+    calculate_adaptive_threshold,
     compute_average_foot_position,
     detect_ground_contact,
+    find_interpolated_phase_transitions_with_curvature,
+    refine_transition_with_curvature,
 )
-from .debug_overlay import DropJumpDebugOverlayRenderer
+from .debug_overlay import DebugOverlayRenderer
 from .kinematics import DropJumpMetrics, calculate_drop_jump_metrics
 
 __all__ = [
@@ -14,10 +17,13 @@ __all__ = [
     "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
-    "DropJumpDebugOverlayRenderer",
+    "DebugOverlayRenderer",
 ]