kinemotion 0.27.0__py3-none-any.whl → 0.29.0__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(

kinemotion/cmj/kinematics.py

@@ -6,6 +6,8 @@ from typing import TYPE_CHECKING, TypedDict
 import numpy as np
 from numpy.typing import NDArray
 
+from ..core.formatting import format_float_metric
+
 if TYPE_CHECKING:
     from ..core.metadata import ResultMetadata
     from ..core.quality import QualityAssessment
@@ -15,14 +17,14 @@ class CMJDataDict(TypedDict, total=False):
     """Type-safe dictionary for CMJ measurement data."""
 
     jump_height_m: float
-    flight_time_s: float
+    flight_time_ms: float
     countermovement_depth_m: float
-    eccentric_duration_s: float
-    concentric_duration_s: float
-    total_movement_time_s: float
+    eccentric_duration_ms: float
+    concentric_duration_ms: float
+    total_movement_time_ms: float
     peak_eccentric_velocity_m_s: float
     peak_concentric_velocity_m_s: float
-    transition_time_s: float | None
+    transition_time_ms: float | None
     standing_start_frame: float | None
     lowest_point_frame: float
     takeoff_frame: float
@@ -43,14 +45,14 @@ class CMJMetrics:
 
     Attributes:
         jump_height: Maximum jump height in meters
-        flight_time: Time spent in the air in seconds
+        flight_time: Time spent in the air in milliseconds
         countermovement_depth: Vertical distance traveled during eccentric phase in meters
-        eccentric_duration: Time from countermovement start to lowest point in seconds
-        concentric_duration: Time from lowest point to takeoff in seconds
-        total_movement_time: Total time from countermovement start to takeoff in seconds
+        eccentric_duration: Time from countermovement start to lowest point in milliseconds
+        concentric_duration: Time from lowest point to takeoff in milliseconds
+        total_movement_time: Total time from countermovement start to takeoff in milliseconds
         peak_eccentric_velocity: Maximum downward velocity during countermovement in m/s
         peak_concentric_velocity: Maximum upward velocity during propulsion in m/s
-        transition_time: Duration at lowest point (amortization phase) in seconds
+        transition_time: Duration at lowest point (amortization phase) in milliseconds
         standing_start_frame: Frame where standing phase ends (countermovement begins)
         lowest_point_frame: Frame at lowest point of countermovement
         takeoff_frame: Frame where athlete leaves ground
@@ -85,19 +87,27 @@ class CMJMetrics:
             Dictionary with nested data and metadata structure.
         """
         data: CMJDataDict = {
-            "jump_height_m": float(self.jump_height),
-            "flight_time_s": float(self.flight_time),
-            "countermovement_depth_m": float(self.countermovement_depth),
-            "eccentric_duration_s": float(self.eccentric_duration),
-            "concentric_duration_s": float(self.concentric_duration),
-            "total_movement_time_s": float(self.total_movement_time),
-            "peak_eccentric_velocity_m_s": float(self.peak_eccentric_velocity),
-            "peak_concentric_velocity_m_s": float(self.peak_concentric_velocity),
-            "transition_time_s": (
-                float(self.transition_time)
-                if self.transition_time is not None
-                else None
-            ),
+            "jump_height_m": format_float_metric(self.jump_height, 1, 3),  # type: ignore[typeddict-item]
+            "flight_time_ms": format_float_metric(self.flight_time, 1000, 2),  # type: ignore[typeddict-item]
+            "countermovement_depth_m": format_float_metric(
+                self.countermovement_depth, 1, 3
+            ),  # type: ignore[typeddict-item]
+            "eccentric_duration_ms": format_float_metric(
+                self.eccentric_duration, 1000, 2
+            ),  # type: ignore[typeddict-item]
+            "concentric_duration_ms": format_float_metric(
+                self.concentric_duration, 1000, 2
+            ),  # type: ignore[typeddict-item]
+            "total_movement_time_ms": format_float_metric(
+                self.total_movement_time, 1000, 2
+            ),  # type: ignore[typeddict-item]
+            "peak_eccentric_velocity_m_s": format_float_metric(
+                self.peak_eccentric_velocity, 1, 4
+            ),  # type: ignore[typeddict-item]
+            "peak_concentric_velocity_m_s": format_float_metric(
+                self.peak_concentric_velocity, 1, 4
+            ),  # type: ignore[typeddict-item]
+            "transition_time_ms": format_float_metric(self.transition_time, 1000, 2),
             "standing_start_frame": (
                 float(self.standing_start_frame)
                 if self.standing_start_frame is not None