kinemotion 0.71.0__py3-none-any.whl → 0.71.1__py3-none-any.whl

kinemotion/core/smoothing.py

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

kinemotion/core/types.py

@@ -29,6 +29,19 @@ 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",
@@ -39,4 +52,6 @@ __all__ = [
     "LandmarkFrame",
     "LandmarkSequence",
     "MetricsDict",
+    "FOOT_KEYS",
+    "HIP_KEYS",
 ]

kinemotion/core/validation.py

@@ -78,19 +78,18 @@ class MetricBounds:
 
     def contains(self, value: float, profile: AthleteProfile) -> bool:
         """Check if value is within bounds for athlete profile."""
-        if profile == AthleteProfile.ELDERLY:
+        # ELDERLY and UNTRAINED use same bounds (practical to recreational)
+        if profile in (AthleteProfile.ELDERLY, AthleteProfile.UNTRAINED):
             return self.practical_min <= value <= self.recreational_max
-        elif profile == AthleteProfile.UNTRAINED:
-            return self.practical_min <= value <= self.recreational_max
-        elif profile == AthleteProfile.RECREATIONAL:
+        if profile == AthleteProfile.RECREATIONAL:
             return self.recreational_min <= value <= self.recreational_max
-        elif profile == AthleteProfile.TRAINED:
+        if profile == AthleteProfile.ELITE:
+            return self.elite_min <= value <= self.elite_max
+        if 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:

kinemotion/core/video_io.py

@@ -18,6 +18,17 @@ 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.
@@ -216,15 +227,9 @@ class VideoProcessor:
 
         # Apply rotation if video has rotation metadata
         with self.timer.measure("frame_rotation"):
-            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)
+            rotation_op = self._ROTATION_OPS.get(self.rotation)
+            if rotation_op is not None:
+                frame = cv2.rotate(frame, rotation_op)
 
         self._frame_index += 1
         return frame

kinemotion/dropjump/__init__.py

@@ -9,7 +9,7 @@ from .analysis import (
     find_interpolated_phase_transitions_with_curvature,
     refine_transition_with_curvature,
 )
-from .debug_overlay import DebugOverlayRenderer
+from .debug_overlay import DropJumpDebugOverlayRenderer
 from .kinematics import DropJumpMetrics, calculate_drop_jump_metrics
 
 __all__ = [
@@ -25,5 +25,5 @@ __all__ = [
     "DropJumpMetrics",
     "calculate_drop_jump_metrics",
     # Debug overlay
-    "DebugOverlayRenderer",
+    "DropJumpDebugOverlayRenderer",
 ]

kinemotion/dropjump/analysis.py

@@ -11,7 +11,7 @@ from ..core.smoothing import (
     interpolate_threshold_crossing,
 )
 from ..core.timing import NULL_TIMER, Timer
-from ..core.types import BoolArray, FloatArray
+from ..core.types import FOOT_KEYS, BoolArray, FloatArray
 
 
 class ContactState(Enum):
@@ -424,6 +424,57 @@ def find_contact_phases(
     return phases
 
 
+def _interpolate_phase_boundary(
+    boundary_idx: int,
+    state: ContactState,
+    velocities: FloatArray,
+    velocity_threshold: float,
+    is_start: bool,
+) -> float:
+    """Interpolate phase boundary with sub-frame precision.
+
+    Args:
+        boundary_idx: Index of the boundary frame
+        state: Contact state of the phase
+        velocities: Velocity array
+        velocity_threshold: Threshold value for crossing detection
+        is_start: True for phase start, False for phase end
+
+    Returns:
+        Fractional frame index, or float(boundary_idx) if no interpolation.
+    """
+    n_velocities = len(velocities)
+
+    if is_start:
+        # For start boundary, look at velocity before and at the boundary
+        if boundary_idx <= 0 or boundary_idx >= n_velocities:
+            return float(boundary_idx)
+        vel_before = velocities[boundary_idx - 1]
+        vel_at = velocities[boundary_idx]
+        # Check threshold crossing based on state
+        is_crossing = (
+            state == ContactState.ON_GROUND and vel_before > velocity_threshold > vel_at
+        ) or (state == ContactState.IN_AIR and vel_before < velocity_threshold < vel_at)
+        if is_crossing:
+            offset = interpolate_threshold_crossing(vel_before, vel_at, velocity_threshold)
+            return (boundary_idx - 1) + offset
+        return float(boundary_idx)
+
+    # For end boundary, look at velocity at and after the boundary
+    if boundary_idx + 1 >= n_velocities:
+        return float(boundary_idx)
+    vel_at = velocities[boundary_idx]
+    vel_after = velocities[boundary_idx + 1]
+    # Check threshold crossing based on state
+    is_crossing = (
+        state == ContactState.ON_GROUND and vel_at < velocity_threshold < vel_after
+    ) or (state == ContactState.IN_AIR and vel_at > velocity_threshold > vel_after)
+    if is_crossing:
+        offset = interpolate_threshold_crossing(vel_at, vel_after, velocity_threshold)
+        return boundary_idx + offset
+    return float(boundary_idx)
+
+
 def _interpolate_phase_start(
     start_idx: int,
     state: ContactState,
@@ -435,21 +486,9 @@ def _interpolate_phase_start(
     Returns:
         Fractional start frame, or float(start_idx) if no interpolation.
     """
-    if start_idx <= 0 or start_idx >= len(velocities):
-        return float(start_idx)
-
-    vel_before = velocities[start_idx - 1]
-    vel_at = velocities[start_idx]
-
-    # Check threshold crossing based on state
-    is_landing = state == ContactState.ON_GROUND and vel_before > velocity_threshold > vel_at
-    is_takeoff = state == ContactState.IN_AIR and vel_before < velocity_threshold < vel_at
-
-    if is_landing or is_takeoff:
-        offset = interpolate_threshold_crossing(vel_before, vel_at, velocity_threshold)
-        return (start_idx - 1) + offset
-
-    return float(start_idx)
+    return _interpolate_phase_boundary(
+        start_idx, state, velocities, velocity_threshold, is_start=True
+    )
 
 
 def _interpolate_phase_end(
@@ -457,28 +496,16 @@ def _interpolate_phase_end(
     state: ContactState,
     velocities: FloatArray,
     velocity_threshold: float,
-    max_idx: int,
+    _max_idx: int,
 ) -> float:
     """Interpolate end boundary of a phase with sub-frame precision.
 
     Returns:
         Fractional end frame, or float(end_idx) if no interpolation.
     """
-    if end_idx >= max_idx - 1 or end_idx + 1 >= len(velocities):
-        return float(end_idx)
-
-    vel_at = velocities[end_idx]
-    vel_after = velocities[end_idx + 1]
-
-    # Check threshold crossing based on state
-    is_takeoff = state == ContactState.ON_GROUND and vel_at < velocity_threshold < vel_after
-    is_landing = state == ContactState.IN_AIR and vel_at > velocity_threshold > vel_after
-
-    if is_takeoff or is_landing:
-        offset = interpolate_threshold_crossing(vel_at, vel_after, velocity_threshold)
-        return end_idx + offset
-
-    return float(end_idx)
+    return _interpolate_phase_boundary(
+        end_idx, state, velocities, velocity_threshold, is_start=False
+    )
 
 
 def find_interpolated_phase_transitions(
@@ -747,19 +774,10 @@ def compute_average_foot_position(
     Returns:
         (x, y) average foot position in normalized coordinates
     """
-    foot_keys = [
-        "left_ankle",
-        "right_ankle",
-        "left_heel",
-        "right_heel",
-        "left_foot_index",
-        "right_foot_index",
-    ]
-
     x_positions = []
     y_positions = []
 
-    for key in foot_keys:
+    for key in FOOT_KEYS:
         if key in landmarks:
             x, y, visibility = landmarks[key]
             if visibility > 0.5:  # Only use visible landmarks
@@ -783,8 +801,13 @@ def _calculate_average_visibility(
     Returns:
         Average visibility of foot landmarks (0.0 if none visible)
     """
-    foot_keys = ["left_ankle", "right_ankle", "left_heel", "right_heel"]
-    foot_vis = [frame_landmarks[key][2] for key in foot_keys if key in frame_landmarks]
+    # Only use ankles and heels for visibility (foot_index can be noisy)
+    visibility_keys = ("left_ankle", "right_ankle", "left_heel", "right_heel")
+    foot_vis = [
+        frame_landmarks[key][2]
+        for key in FOOT_KEYS
+        if key in frame_landmarks and key in visibility_keys
+    ]
     return float(np.mean(foot_vis)) if foot_vis else 0.0
 
 

kinemotion/dropjump/api.py

@@ -48,7 +48,7 @@ from .analysis import (
     detect_ground_contact,
     find_contact_phases,
 )
-from .debug_overlay import DebugOverlayRenderer
+from .debug_overlay import DropJumpDebugOverlayRenderer
 from .kinematics import DropJumpMetrics, calculate_drop_jump_metrics
 from .metrics_validator import DropJumpMetricsValidator
 
@@ -305,7 +305,6 @@ def _tune_and_smooth(
         characteristics = analyze_video_sample(landmarks_sequence, video_fps, frame_count)
         params = auto_tune_parameters(characteristics, quality_preset)
 
-        # Apply overrides if provided
         if overrides:
             params = apply_expert_overrides(
                 params,
@@ -314,14 +313,6 @@ def _tune_and_smooth(
                 overrides.min_contact_frames,
                 overrides.visibility_threshold,
             )
-        else:
-            params = apply_expert_overrides(
-                params,
-                None,
-                None,
-                None,
-                None,
-            )
 
     smoothed_landmarks = apply_smoothing(landmarks_sequence, params, verbose, timer)
 
@@ -440,16 +431,13 @@ def _generate_debug_video(
     timer = timer or NULL_TIMER
     debug_h, debug_w = frames[0].shape[:2]
 
-    if video_fps > 30:
-        debug_fps = video_fps / (video_fps / 30.0)
-    else:
-        debug_fps = video_fps
-
+    # Calculate debug FPS: cap at 30 for high-fps videos, use step if frame-sparse
+    debug_fps = min(video_fps, 30.0)
     if len(frames) < len(smoothed_landmarks):
         step = max(1, int(video_fps / 30.0))
         debug_fps = video_fps / step
 
-    def _render_frames(renderer: DebugOverlayRenderer) -> None:
+    def _render_frames(renderer: DropJumpDebugOverlayRenderer) -> None:
         for frame, idx in zip(frames, frame_indices, strict=True):
             annotated = renderer.render_frame(
                 frame,
@@ -461,7 +449,7 @@ def _generate_debug_video(
             )
             renderer.write_frame(annotated)
 
-    renderer_context = DebugOverlayRenderer(
+    renderer_context = DropJumpDebugOverlayRenderer(
         output_video,
         debug_w,
         debug_h,