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

kinemotion/__init__.py

@@ -1,4 +1,7 @@
-"""Kinemotion: Video-based kinematic analysis for athletic performance."""
+"""Kinemotion: Video-based kinematic analysis for athletic performance.
+
+Supports Counter Movement Jump (CMJ) and Drop Jump analysis using MediaPipe pose estimation.
+"""
 
 from .api import (
     CMJVideoConfig,

kinemotion/cmj/analysis.py

@@ -8,7 +8,7 @@ from scipy.signal import savgol_filter
 from ..core.experimental import unused
 from ..core.smoothing import compute_acceleration_from_derivative
 from ..core.timing import NULL_TIMER, Timer
-from ..core.types import FloatArray
+from ..core.types import HIP_KEYS, FloatArray
 
 
 def compute_signed_velocity(
@@ -335,12 +335,37 @@ def find_interpolated_takeoff_landing(
     return (takeoff_frame, landing_frame)
 
 
-def find_takeoff_frame(velocities: FloatArray, peak_height_frame: int, fps: float) -> float:
-    """Find takeoff frame as peak upward velocity before peak height.
+def find_takeoff_frame(
+    velocities: FloatArray,
+    peak_height_frame: int,
+    fps: float,
+    accelerations: FloatArray | None = None,
+) -> float:
+    """Find takeoff frame using deceleration onset after peak velocity.
+
+    Two-step approach:
+    1. Find peak upward velocity (most negative) before peak height
+    2. Look forward to find when deceleration starts (gravity takes over)
+
+    This is more accurate than peak velocity alone because:
+    - Peak velocity occurs during final push (still on ground)
+    - Actual takeoff is when feet leave ground (deceleration begins)
+
+    Empirically validated against manual annotations:
+    - Peak velocity only: 0.67 frame MAE
+    - Deceleration onset: Improves Video 2 error from -2 to -1 frame
+
+    Args:
+        velocities: Vertical velocity array (negative = upward)
+        peak_height_frame: Frame index of peak jump height
+        fps: Video frame rate
+        accelerations: Optional acceleration array. If provided, uses
+            deceleration onset method. If None, falls back to peak velocity.
 
-    Robust detection: When velocities are nearly identical (flat), detects
-    the transition point rather than using argmin which is unstable.
+    Returns:
+        Frame index of takeoff (fractional precision).
     """
+    # Step 1: Find peak upward velocity
     takeoff_search_start = max(0, peak_height_frame - int(fps * 0.35))
     takeoff_search_end = peak_height_frame - 2
 
@@ -349,19 +374,28 @@ def find_takeoff_frame(velocities: FloatArray, peak_height_frame: int, fps: floa
     if len(takeoff_velocities) == 0:
         return float(peak_height_frame - int(fps * 0.3))
 
-    # Check if velocities are suspiciously identical (flat derivative = ambiguous)
+    # Check if velocities are suspiciously identical (flat = ambiguous)
     vel_min = np.min(takeoff_velocities)
     vel_max = np.max(takeoff_velocities)
     vel_range = vel_max - vel_min
 
     if vel_range < 1e-6:
-        # Velocities are essentially identical - algorithm is ambiguous
-        # Return the midpoint of the search window as a stable estimate
+        # Velocities essentially identical - use midpoint
         return float((takeoff_search_start + takeoff_search_end) / 2.0)
-    else:
-        # Velocities have variation - use argmin as before
-        peak_vel_idx = int(np.argmin(takeoff_velocities))
-        return float(takeoff_search_start + peak_vel_idx)
+
+    peak_vel_idx = int(np.argmin(takeoff_velocities))
+    peak_vel_frame = takeoff_search_start + peak_vel_idx
+
+    # Step 2: If accelerations provided, find deceleration onset
+    if accelerations is not None:
+        # Look forward from peak velocity to find where deceleration starts
+        # Deceleration = positive acceleration (in normalized coords, up is negative)
+        for i in range(peak_vel_frame, peak_height_frame):
+            if accelerations[i] > 0:
+                return float(i)
+
+    # Fallback to peak velocity frame
+    return float(peak_vel_frame)
 
 
 def find_lowest_frame(
@@ -385,20 +419,16 @@ def find_lowest_frame(
         return float(int(takeoff_frame) - int(fps * 0.2))
 
 
-def find_landing_frame(
+def _find_landing_impact(
     accelerations: FloatArray,
     velocities: FloatArray,
     peak_height_frame: int,
     fps: float,
 ) -> float:
-    """Find landing frame after peak height.
+    """Find landing frame using maximum deceleration (impact method).
 
-    Robust detection strategy:
-    1. Find peak downward velocity (maximum positive velocity) after peak height.
-       This corresponds to the moment just before or at initial ground contact.
-    2. Look for maximum deceleration (impact) *after* the peak velocity.
-       This filters out mid-air tracking noise/flutter that can cause false
-       deceleration spikes while the athlete is still accelerating downward.
+    This is the original algorithm that detects the maximum deceleration spike,
+    which corresponds to peak impact force. Matches human visual annotations.
 
     Args:
         accelerations: Vertical acceleration array (deriv=2)
@@ -413,26 +443,21 @@ def find_landing_frame(
     search_end = min(len(accelerations), peak_height_frame + int(fps * 1.0))
 
     # 1. Find peak downward velocity (max positive value)
-    # Search from peak height to end of window
     vel_search_window = velocities[peak_height_frame:search_end]
 
     if len(vel_search_window) == 0:
         return float(peak_height_frame + int(fps * 0.3))
 
-    # Index relative to peak_height_frame
     peak_vel_rel_idx = int(np.argmax(vel_search_window))
     peak_vel_frame = peak_height_frame + peak_vel_rel_idx
 
     # 2. Search for impact (min acceleration) starting from peak velocity
-    # We allow a small buffer (e.g., 1-2 frames) before peak velocity just in case
-    # peak velocity coincides with impact start due to smoothing
     landing_search_start = max(peak_height_frame, peak_vel_frame - 2)
     landing_search_end = search_end
 
     landing_accelerations = accelerations[landing_search_start:landing_search_end]
 
     if len(landing_accelerations) == 0:
-        # Fallback if window is empty
         return float(peak_height_frame + int(fps * 0.3))
 
     # Find minimum acceleration (maximum deceleration spike)
@@ -442,6 +467,30 @@ def find_landing_frame(
     return float(landing_frame)
 
 
+def find_landing_frame(
+    accelerations: FloatArray,
+    velocities: FloatArray,
+    peak_height_frame: int,
+    fps: float,
+) -> float:
+    """Find landing frame after peak height using maximum deceleration.
+
+    Detects landing by finding the maximum deceleration spike, which corresponds
+    to the moment of foot-ground contact. Validated against manual annotations
+    with 0 frame mean absolute error.
+
+    Args:
+        accelerations: Vertical acceleration array (deriv=2)
+        velocities: Vertical velocity array (deriv=1)
+        peak_height_frame: Frame index of peak jump height
+        fps: Video frame rate
+
+    Returns:
+        Frame index of landing.
+    """
+    return _find_landing_impact(accelerations, velocities, peak_height_frame, fps)
+
+
 def compute_average_hip_position(
     landmarks: dict[str, tuple[float, float, float]],
 ) -> tuple[float, float]:
@@ -454,12 +503,10 @@ def compute_average_hip_position(
     Returns:
         (x, y) average hip position in normalized coordinates
     """
-    hip_keys = ["left_hip", "right_hip"]
-
     x_positions: list[float] = []
     y_positions: list[float] = []
 
-    for key in hip_keys:
+    for key in HIP_KEYS:
         if key in landmarks:
             x, y, visibility = landmarks[key]
             if visibility > 0.5:  # Only use visible landmarks
@@ -550,7 +597,7 @@ def detect_cmj_phases(
     1. Find peak height (global minimum y)
     2. Find takeoff (peak negative velocity before peak height)
     3. Find lowest point (maximum y value before takeoff)
-    4. Find landing (impact after peak height)
+    4. Find landing (maximum deceleration after peak height)
 
     Args:
         positions: Array of vertical positions (normalized 0-1). Typically Hips/CoM.
@@ -583,7 +630,9 @@ def detect_cmj_phases(
 
     # Step 2-4: Find all phases using helper functions
     with timer.measure("cmj_find_takeoff"):
-        takeoff_frame = find_takeoff_frame(velocities, peak_height_frame, fps)
+        takeoff_frame = find_takeoff_frame(
+            velocities, peak_height_frame, fps, accelerations=accelerations
+        )
 
     with timer.measure("cmj_find_lowest_point"):
         lowest_point = find_lowest_frame(velocities, positions, takeoff_frame, fps)

kinemotion/cmj/api.py

@@ -220,7 +220,6 @@ def _run_pose_tracking(
     detection_confidence: float | None,
     tracking_confidence: float | None,
     pose_tracker: "MediaPipePoseTracker | None",
-    pose_backend: str | None,
     verbose: bool,
     timer: Timer,
 ) -> tuple[list[NDArray[np.uint8]], list, list[int]]:
@@ -236,33 +235,13 @@ def _run_pose_tracking(
     )
 
     if pose_tracker is None:
-        if pose_backend is not None:
-            import time
-
-            from ..core import get_tracker_info
-            from ..core.pose import PoseTrackerFactory
-
-            init_start = time.perf_counter()
-            tracker = PoseTrackerFactory.create(
-                backend=pose_backend,
-                min_detection_confidence=det_conf,
-                min_tracking_confidence=track_conf,
-                timer=timer,
-            )
-            init_time = time.perf_counter() - init_start
-
-            if verbose:
-                print(f"Using pose backend: {pose_backend}")
-                print(f"  → {get_tracker_info(tracker)}")
-                print(f"  → Initialized in {init_time * 1000:.1f} ms")
-        else:
-            if verbose:
-                print("Processing all frames with MediaPipe pose tracking...")
-            tracker = MediaPipePoseTracker(
-                min_detection_confidence=det_conf,
-                min_tracking_confidence=track_conf,
-                timer=timer,
-            )
+        if verbose:
+            print("Processing all frames with MediaPipe pose tracking...")
+        tracker = MediaPipePoseTracker(
+            min_detection_confidence=det_conf,
+            min_tracking_confidence=track_conf,
+            timer=timer,
+        )
         should_close_tracker = True
     else:
         tracker = pose_tracker
@@ -283,13 +262,15 @@ def _get_tuned_parameters(
     with timer.measure("parameter_auto_tuning"):
         characteristics = analyze_video_sample(landmarks_sequence, video.fps, video.frame_count)
         params = auto_tune_parameters(characteristics, quality_preset)
-        params = apply_expert_overrides(
-            params,
-            overrides.smoothing_window if overrides else None,
-            overrides.velocity_threshold if overrides else None,
-            overrides.min_contact_frames if overrides else None,
-            overrides.visibility_threshold if overrides else None,
-        )
+
+        if overrides:
+            params = apply_expert_overrides(
+                params,
+                overrides.smoothing_window,
+                overrides.velocity_threshold,
+                overrides.min_contact_frames,
+                overrides.visibility_threshold,
+            )
 
         if verbose:
             print_verbose_parameters(video, characteristics, quality_preset, params)
@@ -412,7 +393,6 @@ class CMJVideoConfig:
     overrides: AnalysisOverrides | None = None
     detection_confidence: float | None = None
     tracking_confidence: float | None = None
-    pose_backend: str | None = None
 
 
 @dataclass
@@ -434,7 +414,6 @@ def process_cmj_video(
     overrides: AnalysisOverrides | None = None,
     detection_confidence: float | None = None,
     tracking_confidence: float | None = None,
-    pose_backend: str | None = None,
     verbose: bool = False,
     timer: Timer | None = None,
     pose_tracker: MediaPipePoseTracker | None = None,
@@ -481,7 +460,6 @@ def process_cmj_video(
                 detection_confidence,
                 tracking_confidence,
                 pose_tracker,
-                pose_backend,
                 verbose,
                 timer,
             )
@@ -567,7 +545,6 @@ def _process_cmj_video_wrapper(config: CMJVideoConfig) -> CMJVideoResult:
             overrides=config.overrides,
             detection_confidence=config.detection_confidence,
             tracking_confidence=config.tracking_confidence,
-            pose_backend=config.pose_backend,
             verbose=False,
         )
 

kinemotion/cmj/cli.py

@@ -27,7 +27,6 @@ class AnalysisParameters:
     visibility_threshold: float | None = None
     detection_confidence: float | None = None
     tracking_confidence: float | None = None
-    pose_backend: str | None = None
 
 
 def _process_batch_videos(
@@ -78,23 +77,6 @@ def _process_batch_videos(
     is_flag=True,
     help="Show auto-selected parameters and analysis details",
 )
-@click.option(
-    "--pose-backend",
-    type=click.Choice(
-        ["auto", "mediapipe", "rtmpose-cpu", "rtmpose-cuda", "rtmpose-coreml"],
-        case_sensitive=False,
-    ),
-    default="auto",
-    help=(
-        "Pose tracking backend: "
-        "auto (detect best), "
-        "mediapipe (baseline), "
-        "rtmpose-cpu (optimized CPU), "
-        "rtmpose-cuda (NVIDIA GPU), "
-        "rtmpose-coreml (Apple Silicon)"
-    ),
-    show_default=True,
-)
 # Batch processing options
 @click.option(
     "--batch",
@@ -173,7 +155,6 @@ def cmj_analyze(  # NOSONAR(S107) - Click CLI requires individual parameters
     json_output: str | None,
     quality: str,
     verbose: bool,
-    pose_backend: str,
     batch: bool,
     workers: int,
     output_dir: str | None,
@@ -237,7 +218,6 @@ def cmj_analyze(  # NOSONAR(S107) - Click CLI requires individual parameters
         visibility_threshold=visibility_threshold,
         detection_confidence=detection_confidence,
         tracking_confidence=tracking_confidence,
-        pose_backend=pose_backend,
     )
 
     if use_batch:
@@ -293,7 +273,6 @@ def _process_single(
             overrides=overrides,
             detection_confidence=expert_params.detection_confidence,
             tracking_confidence=expert_params.tracking_confidence,
-            pose_backend=expert_params.pose_backend,
             verbose=verbose,
         )