kinemotion 0.35.0__py3-none-any.whl → 0.35.2__py3-none-any.whl

kinemotion/api.py

@@ -548,9 +548,12 @@ def process_dropjump_video(
 
         # Check if drop start was auto-detected
         drop_frame = None
-        if drop_start_frame is None and metrics.contact_start_frame is not None:
-            # Auto-detected
-            drop_frame = metrics.contact_start_frame
+        if drop_start_frame is None and metrics.drop_start_frame is not None:
+            # Auto-detected drop start from box
+            drop_frame = metrics.drop_start_frame
+        elif drop_start_frame is not None:
+            # Manual drop start provided
+            drop_frame = drop_start_frame
 
         algorithm_config = AlgorithmConfig(
             detection_method="forward_search",
@@ -1057,7 +1060,7 @@ def process_cmj_video(
 
         # Validate metrics against physiological bounds
         validator = CMJMetricsValidator()
-        validation_result = validator.validate(metrics.to_dict()["data"])  # type: ignore[arg-type]
+        validation_result = validator.validate(metrics.to_dict())  # type: ignore[arg-type]
         metrics.validation_result = validation_result
 
         if verbose and validation_result.issues:

kinemotion/cmj/analysis.py

@@ -422,11 +422,59 @@ def find_landing_frame(
     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."""
+def find_standing_end(
+    velocities: np.ndarray,
+    lowest_point: float,
+    positions: np.ndarray | None = None,
+    accelerations: np.ndarray | None = None,
+) -> float | None:
+    """
+    Find end of standing phase before lowest point.
+
+    Uses acceleration-based detection to identify when downward movement begins.
+    Acceleration captures movement initiation even when velocity is negligible,
+    making it ideal for detecting slow countermovement starts.
+
+    Args:
+        velocities: Signed velocity array (for backward compatibility)
+        lowest_point: Frame index of lowest point
+        positions: Position array (unused, kept for backward compatibility)
+        accelerations: Acceleration array (if provided, uses
+            acceleration-based detection)
+
+    Returns:
+        Frame index where standing ends (countermovement begins), or None
+    """
     if lowest_point <= 20:
         return None
 
+    # Acceleration-based detection (best for detecting movement initiation)
+    if accelerations is not None:
+        # Use middle section of standing phase as baseline (avoids initial settling)
+        baseline_start = 10
+        baseline_end = min(40, int(lowest_point) - 10)
+
+        if baseline_end <= baseline_start:
+            return None
+
+        # Calculate baseline acceleration statistics
+        baseline_accel = accelerations[baseline_start:baseline_end]
+        baseline_mean = float(np.mean(baseline_accel))
+        baseline_std = float(np.std(baseline_accel))
+
+        # Threshold: 3 standard deviations above baseline
+        # This detects when acceleration significantly increases (movement starts)
+        accel_threshold = baseline_mean + 3.0 * baseline_std
+
+        # Search forward from baseline for acceleration spike
+        for i in range(baseline_end, int(lowest_point)):
+            if accelerations[i] > accel_threshold:
+                # Found start of downward acceleration
+                return float(i)
+
+        return None
+
+    # Fallback: velocity-based detection (legacy)
     standing_search = velocities[: int(lowest_point)]
     low_vel = np.abs(standing_search) < 0.005
     if np.any(low_vel):
@@ -479,6 +527,6 @@ def detect_cmj_phases(
     takeoff_frame = find_takeoff_frame(velocities, peak_height_frame, fps)
     lowest_point = find_lowest_frame(velocities, positions, takeoff_frame, fps)
     landing_frame = find_landing_frame(accelerations, peak_height_frame, fps)
-    standing_end = find_standing_end(velocities, lowest_point)
+    standing_end = find_standing_end(velocities, lowest_point, positions, accelerations)
 
     return (standing_end, lowest_point, takeoff_frame, landing_frame)

kinemotion/cmj/metrics_validator.py

@@ -68,6 +68,22 @@ class CMJValidationResult(ValidationResult):
 class CMJMetricsValidator(MetricsValidator):
     """Comprehensive CMJ metrics validator."""
 
+    @staticmethod
+    def _get_metric_value(
+        data: dict, key_with_suffix: str, key_without_suffix: str
+    ) -> float | None:
+        """Get metric value, supporting both suffixed and legacy key formats.
+
+        Args:
+            data: Dictionary containing metrics
+            key_with_suffix: Key with unit suffix (e.g., "flight_time_ms")
+            key_without_suffix: Legacy key without suffix (e.g., "flight_time")
+
+        Returns:
+            Metric value or None if not found
+        """
+        return data.get(key_with_suffix) or data.get(key_without_suffix)
+
     def validate(self, metrics: dict) -> CMJValidationResult:
         """Validate CMJ metrics comprehensively.
 
@@ -87,25 +103,28 @@ class CMJMetricsValidator(MetricsValidator):
 
         profile = result.athlete_profile
 
+        # Extract metric values (handle nested "data" structure)
+        data = metrics.get("data", metrics)  # Support both structures
+
         # PRIMARY BOUNDS CHECKS
-        self._check_flight_time(metrics, result, profile)
-        self._check_jump_height(metrics, result, profile)
-        self._check_countermovement_depth(metrics, result, profile)
-        self._check_concentric_duration(metrics, result, profile)
-        self._check_eccentric_duration(metrics, result, profile)
-        self._check_peak_velocities(metrics, result, profile)
+        self._check_flight_time(data, result, profile)
+        self._check_jump_height(data, result, profile)
+        self._check_countermovement_depth(data, result, profile)
+        self._check_concentric_duration(data, result, profile)
+        self._check_eccentric_duration(data, result, profile)
+        self._check_peak_velocities(data, result, profile)
 
         # CROSS-VALIDATION CHECKS
-        self._check_flight_time_height_consistency(metrics, result)
-        self._check_velocity_height_consistency(metrics, result)
-        self._check_rsi_validity(metrics, result, profile)
+        self._check_flight_time_height_consistency(data, result)
+        self._check_velocity_height_consistency(data, result)
+        self._check_rsi_validity(data, result, profile)
 
         # CONSISTENCY CHECKS
-        self._check_depth_height_ratio(metrics, result)
-        self._check_contact_depth_ratio(metrics, result)
+        self._check_depth_height_ratio(data, result)
+        self._check_contact_depth_ratio(data, result)
 
         # TRIPLE EXTENSION ANGLES
-        self._check_triple_extension(metrics, result, profile)
+        self._check_triple_extension(data, result, profile)
 
         # Finalize status
         result.finalize_status()
@@ -116,10 +135,18 @@ class CMJMetricsValidator(MetricsValidator):
         self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate flight time."""
-        flight_time = metrics.get("flight_time")
-        if flight_time is None:
+        flight_time_raw = self._get_metric_value(
+            metrics, "flight_time_ms", "flight_time"
+        )
+        if flight_time_raw is None:
             return
 
+        # If value is in seconds (legacy), use as-is; if in ms, convert
+        if flight_time_raw < 10:  # Likely in seconds
+            flight_time = flight_time_raw
+        else:  # In milliseconds
+            flight_time = flight_time_raw / 1000.0
+
         bounds = CMJBounds.FLIGHT_TIME
 
         if not bounds.is_physically_possible(flight_time):
@@ -159,7 +186,7 @@ class CMJMetricsValidator(MetricsValidator):
         self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate jump height."""
-        jump_height = metrics.get("jump_height")
+        jump_height = self._get_metric_value(metrics, "jump_height_m", "jump_height")
         if jump_height is None:
             return
 
@@ -201,7 +228,9 @@ class CMJMetricsValidator(MetricsValidator):
         self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate countermovement depth."""
-        depth = metrics.get("countermovement_depth")
+        depth = self._get_metric_value(
+            metrics, "countermovement_depth_m", "countermovement_depth"
+        )
         if depth is None:
             return
 
@@ -243,10 +272,19 @@ class CMJMetricsValidator(MetricsValidator):
         self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate concentric duration (contact time)."""
-        duration = metrics.get("concentric_duration")
-        if duration is None:
+        duration_raw = self._get_metric_value(
+            metrics, "concentric_duration_ms", "concentric_duration"
+        )
+        if duration_raw is None:
             return
 
+        # If value is in seconds (legacy), convert to ms first
+        # Values >10 are assumed to be in ms, <10 assumed to be in seconds
+        if duration_raw < 10:  # Likely in seconds
+            duration = duration_raw
+        else:  # In milliseconds
+            duration = duration_raw / 1000.0
+
         bounds = CMJBounds.CONCENTRIC_DURATION
 
         if not bounds.is_physically_possible(duration):
@@ -286,10 +324,18 @@ class CMJMetricsValidator(MetricsValidator):
         self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate eccentric duration."""
-        duration = metrics.get("eccentric_duration")
-        if duration is None:
+        duration_raw = self._get_metric_value(
+            metrics, "eccentric_duration_ms", "eccentric_duration"
+        )
+        if duration_raw is None:
             return
 
+        # If value is in seconds (legacy), use as-is; if in ms, convert
+        if duration_raw < 10:  # Likely in seconds
+            duration = duration_raw
+        else:  # In milliseconds
+            duration = duration_raw / 1000.0
+
         bounds = CMJBounds.ECCENTRIC_DURATION
 
         if not bounds.is_physically_possible(duration):
@@ -321,7 +367,9 @@ class CMJMetricsValidator(MetricsValidator):
     ) -> None:
         """Validate peak eccentric and concentric velocities."""
         # Eccentric
-        ecc_vel = metrics.get("peak_eccentric_velocity")
+        ecc_vel = self._get_metric_value(
+            metrics, "peak_eccentric_velocity_m_s", "peak_eccentric_velocity"
+        )
         if ecc_vel is not None:
             bounds = CMJBounds.PEAK_ECCENTRIC_VELOCITY
             if not bounds.is_physically_possible(ecc_vel):
@@ -349,7 +397,9 @@ class CMJMetricsValidator(MetricsValidator):
                 )
 
         # Concentric
-        con_vel = metrics.get("peak_concentric_velocity")
+        con_vel = self._get_metric_value(
+            metrics, "peak_concentric_velocity_m_s", "peak_concentric_velocity"
+        )
         if con_vel is not None:
             bounds = CMJBounds.PEAK_CONCENTRIC_VELOCITY
             if not bounds.is_physically_possible(con_vel):
@@ -390,12 +440,15 @@ class CMJMetricsValidator(MetricsValidator):
         self, metrics: dict, result: CMJValidationResult
     ) -> None:
         """Verify jump height is consistent with flight time."""
-        flight_time = metrics.get("flight_time")
-        jump_height = metrics.get("jump_height")
+        flight_time_ms = metrics.get("flight_time_ms")
+        jump_height = metrics.get("jump_height_m")
 
-        if flight_time is None or jump_height is None:
+        if flight_time_ms is None or jump_height is None:
             return
 
+        # Convert ms to seconds
+        flight_time = flight_time_ms / 1000.0
+
         # h = g * t^2 / 8
         g = 9.81
         expected_height = (g * flight_time**2) / 8
@@ -424,8 +477,8 @@ class CMJMetricsValidator(MetricsValidator):
         self, metrics: dict, result: CMJValidationResult
     ) -> None:
         """Verify peak velocity is consistent with jump height."""
-        velocity = metrics.get("peak_concentric_velocity")
-        jump_height = metrics.get("jump_height")
+        velocity = metrics.get("peak_concentric_velocity_m_s")
+        jump_height = metrics.get("jump_height_m")
 
         if velocity is None or jump_height is None:
             return
@@ -461,16 +514,31 @@ class CMJMetricsValidator(MetricsValidator):
         self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate Reactive Strength Index."""
-        flight_time = metrics.get("flight_time")
-        concentric_duration = metrics.get("concentric_duration")
+        flight_time_raw = self._get_metric_value(
+            metrics, "flight_time_ms", "flight_time"
+        )
+        concentric_duration_raw = self._get_metric_value(
+            metrics, "concentric_duration_ms", "concentric_duration"
+        )
 
         if (
-            flight_time is None
-            or concentric_duration is None
-            or concentric_duration == 0
+            flight_time_raw is None
+            or concentric_duration_raw is None
+            or concentric_duration_raw == 0
         ):
             return
 
+        # Convert to seconds if needed
+        if flight_time_raw < 10:  # Likely in seconds
+            flight_time = flight_time_raw
+        else:  # In milliseconds
+            flight_time = flight_time_raw / 1000.0
+
+        if concentric_duration_raw < 10:  # Likely in seconds
+            concentric_duration = concentric_duration_raw
+        else:  # In milliseconds
+            concentric_duration = concentric_duration_raw / 1000.0
+
         rsi = flight_time / concentric_duration
         result.rsi = rsi
 
@@ -513,8 +581,8 @@ class CMJMetricsValidator(MetricsValidator):
         self, metrics: dict, result: CMJValidationResult
     ) -> None:
         """Check countermovement depth to jump height ratio."""
-        depth = metrics.get("countermovement_depth")
-        jump_height = metrics.get("jump_height")
+        depth = metrics.get("countermovement_depth_m")
+        jump_height = metrics.get("jump_height_m")
 
         if (
             depth is None or jump_height is None or depth < 0.05
@@ -557,12 +625,14 @@ class CMJMetricsValidator(MetricsValidator):
         self, metrics: dict, result: CMJValidationResult
     ) -> None:
         """Check contact time to countermovement depth ratio."""
-        contact = metrics.get("concentric_duration")
-        depth = metrics.get("countermovement_depth")
+        contact_ms = metrics.get("concentric_duration_ms")
+        depth = metrics.get("countermovement_depth_m")
 
-        if contact is None or depth is None or depth < 0.05:
+        if contact_ms is None or depth is None or depth < 0.05:
             return
 
+        # Convert ms to seconds for ratio calculation
+        contact = contact_ms / 1000.0
         ratio = contact / depth
         result.contact_depth_ratio = ratio
 

kinemotion/cmj/validation_bounds.py

@@ -323,7 +323,10 @@ def estimate_athlete_profile(
     Returns:
         Estimated AthleteProfile
     """
-    jump_height = metrics_dict.get("jump_height", 0)
+    # Support both nested "data" structure and flat structure
+    # Extract with unit suffix as used in serialization, or without suffix (legacy)
+    data = metrics_dict.get("data", metrics_dict)
+    jump_height = data.get("jump_height_m") or data.get("jump_height", 0)
 
     if jump_height < 0.20:
         return AthleteProfile.ELDERLY

kinemotion/core/auto_tuning.py

@@ -108,10 +108,12 @@ def auto_tune_parameters(
     # =================================================================
 
     # Velocity threshold: Scale inversely with fps
-    # At 30fps, feet move ~2% of frame per frame when "stationary"
-    # At 60fps, feet move ~1% of frame per frame when "stationary"
-    # Formula: threshold = 0.02 * (30 / fps)
-    base_velocity_threshold = 0.02 * (30.0 / fps)
+    # Empirically validated with 45° oblique videos at 60fps:
+    # - Standing (stationary): ~0.001 mean, 0.0011 max
+    # - Flight/drop (moving): ~0.005-0.009
+    # Target threshold: 0.002 at 60fps for clear separation
+    # Formula: threshold = 0.004 * (30 / fps)
+    base_velocity_threshold = 0.004 * (30.0 / fps)
 
     # Min contact frames: Scale with fps to maintain same time duration
     # Goal: ~100ms minimum contact (3 frames @ 30fps, 6 frames @ 60fps)

kinemotion/dropjump/kinematics.py

@@ -57,6 +57,7 @@ class DropJumpMetrics:
         self.jump_height: float | None = None
         self.jump_height_kinematic: float | None = None  # From flight time
         self.jump_height_trajectory: float | None = None  # From position tracking
+        self.drop_start_frame: int | None = None  # Frame when athlete leaves box
         self.contact_start_frame: int | None = None
         self.contact_end_frame: int | None = None
         self.flight_start_frame: int | None = None
@@ -164,7 +165,7 @@ def _determine_drop_start_frame(
             foot_y_positions,
             fps,
             min_stationary_duration=0.5,
-            position_change_threshold=0.005,
+            position_change_threshold=0.01,  # Improved from 0.005 for better accuracy
             smoothing_window=smoothing_window,
         )
     return drop_start_frame
@@ -412,6 +413,11 @@ def calculate_drop_jump_metrics(
         drop_start_frame, foot_y_positions, fps, smoothing_window
     )
 
+    # Store drop start frame in metrics
+    metrics.drop_start_frame = (
+        drop_start_frame_value if drop_start_frame_value > 0 else None
+    )
+
     # Find contact phases
     phases = find_contact_phases(contact_states)
     interpolated_phases = find_interpolated_phase_transitions_with_curvature(

{kinemotion-0.35.0.dist-info → kinemotion-0.35.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.35.0
+Version: 0.35.2
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion

{kinemotion-0.35.0.dist-info → kinemotion-0.35.2.dist-info}/RECORD

@@ -1,16 +1,16 @@
 kinemotion/__init__.py,sha256=sxdDOekOrIgjxm842gy-6zfq7OWmGl9ShJtXCm4JI7c,723
-kinemotion/api.py,sha256=Rdz5XjFsIMK-9rByzOYiDTPz27vINB01fmdeDzPoxZY,39339
+kinemotion/api.py,sha256=nbDbyzhXIMA04tGqKPH8R0fR66zgtu14x6NgWroy_QU,39471
 kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
 kinemotion/cmj/__init__.py,sha256=Ynv0-Oco4I3Y1Ubj25m3h9h2XFqeNwpAewXmAYOmwfU,127
-kinemotion/cmj/analysis.py,sha256=DmZ7vptPd5PAkaWW-oSablA6DWrCj8u2qPxlKQm9cVU,17089
+kinemotion/cmj/analysis.py,sha256=OfNTMLPwZIRYbX-Yd8jgZ-7pqnHRz7L2bWAHVYFsQ60,18955
 kinemotion/cmj/cli.py,sha256=Mj2h9It1jVjAauvtCxfLWTRijj7zbYhxZuebhw2Zz6w,10828
 kinemotion/cmj/debug_overlay.py,sha256=fXmWoHhqMLGo4vTtB6Ezs3yLUDOLw63zLIgU2gFlJQU,15892
 kinemotion/cmj/joint_angles.py,sha256=HmheIEiKcQz39cRezk4h-htorOhGNPsqKIR9RsAEKts,9960
 kinemotion/cmj/kinematics.py,sha256=qRBe87NkX-7HQTQ8RoF-EpvfcffgP5vycJJRrxpHboc,10307
-kinemotion/cmj/metrics_validator.py,sha256=p_hgg0Q0UAiWGNXKSW4E9kPvyEgPNAujaxrk2XUmsBY,28619
-kinemotion/cmj/validation_bounds.py,sha256=yRhmpUzGJs0QYyL1o3mOkgUSTe4XTO2MONMITTjCv3c,11778
+kinemotion/cmj/metrics_validator.py,sha256=V_fmlczYH06SBtwqESv-IfGi3wDsIy3RQbd7VwOyNo0,31359
+kinemotion/cmj/validation_bounds.py,sha256=9ZTo68fl3ooyWjXXyTMRLpK9tFANa_rQf3oHhq7iQGE,11995
 kinemotion/core/__init__.py,sha256=HsqolRa60cW3vrG8F9Lvr9WvWcs5hCmsTzSgo7imi-4,1278
-kinemotion/core/auto_tuning.py,sha256=j6cul_qC6k0XyryCG93C1AWH2MKPj3UBMzuX02xaqfI,11235
+kinemotion/core/auto_tuning.py,sha256=wtCUMOhBChVJNXfEeku3GCMW4qED6MF-O_mv2sPTiVQ,11324
 kinemotion/core/cli_utils.py,sha256=zbnifPhD-OYofJioeYfJtshuWcl8OAEWtqCGVF4ctAI,7966
 kinemotion/core/debug_overlay_utils.py,sha256=TyUb5okv5qw8oeaX3jsUO_kpwf1NnaHEAOTm-8LwTno,4587
 kinemotion/core/experimental.py,sha256=IK05AF4aZS15ke85hF3TWCqRIXU1AlD_XKzFz735Ua8,3640
@@ -26,12 +26,12 @@ kinemotion/dropjump/__init__.py,sha256=tC3H3BrCg8Oj-db-Vrtx4PH_llR1Ppkd5jwaOjhQc
 kinemotion/dropjump/analysis.py,sha256=B_N_51WoChyQ8I7yaeKeqj3vw7NufgV_3QL-FBZEtW4,28752
 kinemotion/dropjump/cli.py,sha256=n_Wfv3AC6YIgRPYhO3F2nTSai0NR7fh95nAoWjryQeY,16250
 kinemotion/dropjump/debug_overlay.py,sha256=LkPw6ucb7beoYWS4L-Lvjs1KLCm5wAWDAfiznUeV2IQ,5668
-kinemotion/dropjump/kinematics.py,sha256=IH6nCOwTuocQNX1VPS_am9vPpMRUUla0a0MjDhEiXnA,17129
+kinemotion/dropjump/kinematics.py,sha256=yB4ws4VG59SUGcw1J-uXfDFfCMXBdzRh5C4jo0osXbs,17404
 kinemotion/dropjump/metrics_validator.py,sha256=sx4RodHpeiW8_PRB0GUJvkUWto1Ard1Dvrc9z8eKk7M,9351
 kinemotion/dropjump/validation_bounds.py,sha256=5b4I3CKPybuvrbn-nP5yCcGF_sH4Vtyw3a5AWWvWnBk,4645
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.35.0.dist-info/METADATA,sha256=vMAyXr_N5nJrQ4WvcnmQClVOw_EyvliO3PN09HMIsMw,26020
-kinemotion-0.35.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-kinemotion-0.35.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.35.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.35.0.dist-info/RECORD,,
+kinemotion-0.35.2.dist-info/METADATA,sha256=tb4l8YTLu_HqhK7tH5lwKLmQkBXvFDqhIyPPKP6qHgU,26020
+kinemotion-0.35.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+kinemotion-0.35.2.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.35.2.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.35.2.dist-info/RECORD,,