kinemotion 0.28.0__py3-none-any.whl → 0.29.1__py3-none-any.whl

kinemotion/__init__.py

@@ -13,7 +13,7 @@ from .api import (
 from .cmj.kinematics import CMJMetrics
 from .dropjump.kinematics import DropJumpMetrics
 
-__version__ = "0.1.0"
+__version__ = "0.27.0"
 
 __all__ = [
     # Drop jump API

kinemotion/cmj/analysis.py

@@ -417,17 +417,32 @@ def find_interpolated_takeoff_landing(
 def _find_takeoff_frame(
     velocities: np.ndarray, peak_height_frame: int, fps: float
 ) -> float:
-    """Find takeoff frame as peak upward velocity before peak height."""
+    """Find takeoff frame as peak upward velocity before peak height.
+
+    Robust detection: When velocities are nearly identical (flat), detects
+    the transition point rather than using argmin which is unstable.
+    """
     takeoff_search_start = max(0, peak_height_frame - int(fps * 0.35))
     takeoff_search_end = peak_height_frame - 2
 
     takeoff_velocities = velocities[takeoff_search_start:takeoff_search_end]
 
-    if len(takeoff_velocities) > 0:
+    if len(takeoff_velocities) == 0:
+        return float(peak_height_frame - int(fps * 0.3))
+
+    # Check if velocities are suspiciously identical (flat derivative = 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
+        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)
-    else:
-        return float(peak_height_frame - int(fps * 0.3))
 
 
 def _find_lowest_frame(
@@ -454,17 +469,35 @@ def _find_lowest_frame(
 def _find_landing_frame(
     accelerations: np.ndarray, peak_height_frame: int, fps: float
 ) -> float:
-    """Find landing frame after peak height."""
+    """Find landing frame after peak height after takeoff.
+
+    Detects landing by finding the minimum acceleration (impact) in a search
+    window after peak height. The window is extended to 1.0s to ensure all
+    realistic flight times are captured.
+
+    Robust detection: When accelerations are nearly flat, skips the impact
+    frames near peak height and looks for the actual landing signal.
+    """
     landing_search_start = peak_height_frame
-    landing_search_end = min(len(accelerations), peak_height_frame + int(fps * 0.5))
+    # Search window extended to 1.0s to accommodate all realistic flight times
+    # (recreational: 0.25-0.65s, elite: 0.65-0.95s, max: 1.1s)
+    landing_search_end = min(len(accelerations), peak_height_frame + int(fps * 1.0))
     landing_accelerations = accelerations[landing_search_start:landing_search_end]
 
-    if len(landing_accelerations) > 0:
-        landing_idx = int(np.argmin(landing_accelerations))
-        return float(landing_search_start + landing_idx)
-    else:
+    if len(landing_accelerations) == 0:
         return float(peak_height_frame + int(fps * 0.3))
 
+    # Skip the first 2 frames after peak (often have unreliable acceleration)
+    # This avoids locking onto peak height acceleration instead of impact
+    skip_frames = 2
+    if len(landing_accelerations) > skip_frames:
+        landing_accelerations_filtered = landing_accelerations[skip_frames:]
+        landing_idx = int(np.argmin(landing_accelerations_filtered)) + skip_frames
+    else:
+        landing_idx = int(np.argmin(landing_accelerations))
+
+    return float(landing_search_start + landing_idx)
+
 
 def _find_standing_end(velocities: np.ndarray, lowest_point: float) -> float | None:
     """Find end of standing phase before lowest point."""

kinemotion/cmj/joint_angles.py

@@ -68,11 +68,19 @@ def calculate_ankle_angle(
     """
     Calculate ankle angle (dorsiflexion/plantarflexion).
 
-    Angle formed by: heel -> ankle -> knee
+    Angle formed by: foot_index -> ankle -> knee (primary)
+    Falls back to heel -> ankle -> knee if foot_index visibility < 0.5
+
+    Measurements:
     - 90° = neutral (foot perpendicular to shin)
     - < 90° = dorsiflexion (toes up)
     - > 90° = plantarflexion (toes down)
 
+    Technical note:
+    - foot_index (toe tip) is used for accurate plantarflexion measurement
+    - Heel is relatively static during push-off; toes (foot_index) actively plantarflex
+    - Expected range during CMJ: 80° (standing) -> 130°+ (plantarflex at takeoff)
+
     Args:
         landmarks: Pose landmarks dictionary
         side: Which side to measure ("left" or "right")
@@ -82,23 +90,32 @@ def calculate_ankle_angle(
     """
     prefix = "left_" if side == "left" else "right_"
 
+    foot_index_key = f"{prefix}foot_index"
     heel_key = f"{prefix}heel"
     ankle_key = f"{prefix}ankle"
     knee_key = f"{prefix}knee"
 
-    # Check visibility threshold
-    if heel_key not in landmarks or landmarks[heel_key][2] < 0.3:
-        return None
+    # Check ankle and knee visibility (required)
     if ankle_key not in landmarks or landmarks[ankle_key][2] < 0.3:
         return None
     if knee_key not in landmarks or landmarks[knee_key][2] < 0.3:
         return None
 
-    heel = (landmarks[heel_key][0], landmarks[heel_key][1])
     ankle = (landmarks[ankle_key][0], landmarks[ankle_key][1])
     knee = (landmarks[knee_key][0], landmarks[knee_key][1])
 
-    return calculate_angle_3_points(heel, ankle, knee)
+    # Try foot_index first (primary: toe tip for plantarflexion accuracy)
+    if foot_index_key in landmarks and landmarks[foot_index_key][2] > 0.5:
+        foot_point = (landmarks[foot_index_key][0], landmarks[foot_index_key][1])
+        return calculate_angle_3_points(foot_point, ankle, knee)
+
+    # Fallback to heel if foot_index visibility is insufficient
+    if heel_key in landmarks and landmarks[heel_key][2] > 0.3:
+        foot_point = (landmarks[heel_key][0], landmarks[heel_key][1])
+        return calculate_angle_3_points(foot_point, ankle, knee)
+
+    # No valid foot landmark available
+    return None
 
 
 def calculate_knee_angle(