kinemotion 0.76.3__py3-none-any.whl → 2.0.0__py3-none-any.whl

kinemotion/{countermovement_jump → cmj}/metrics_validator.py

@@ -9,6 +9,13 @@ of metric issues.
 
 from dataclasses import dataclass
 
+from kinemotion.cmj.validation_bounds import (
+    CMJBounds,
+    MetricConsistency,
+    RSIBounds,
+    TripleExtensionBounds,
+    estimate_athlete_profile,
+)
 from kinemotion.core.types import MetricsDict
 from kinemotion.core.validation import (
     AthleteProfile,
@@ -16,13 +23,6 @@ from kinemotion.core.validation import (
     MetricsValidator,
     ValidationResult,
 )
-from kinemotion.countermovement_jump.validation_bounds import (
-    CMJBounds,
-    MetricConsistency,
-    RSIBounds,
-    TripleExtensionBounds,
-    estimate_athlete_profile,
-)
 
 
 @dataclass
@@ -81,23 +81,6 @@ class CMJMetricsValidator(MetricsValidator):
         """
         return data.get(key_with_suffix) or data.get(key_without_suffix)
 
-    @staticmethod
-    def _convert_raw_duration_to_seconds(value_raw: float) -> float:
-        """Convert raw duration value to seconds.
-
-        Handles legacy values that may be in seconds (<10) vs milliseconds (>10).
-        This heuristic works because no CMJ duration metric is between 10ms and 10s.
-
-        Args:
-            value_raw: Raw duration value (may be seconds or milliseconds)
-
-        Returns:
-            Duration in seconds
-        """
-        if value_raw < 10:  # Likely in seconds
-            return value_raw
-        return value_raw / 1000.0
-
     def validate(self, metrics: MetricsDict) -> CMJValidationResult:
         """Validate CMJ metrics comprehensively.
 
@@ -124,8 +107,8 @@ class CMJMetricsValidator(MetricsValidator):
         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)
-        self._check_eccentric_duration(data, result)
+        self._check_concentric_duration(data, result, profile)
+        self._check_eccentric_duration(data, result, profile)
         self._check_peak_velocities(data, result, profile)
 
         # CROSS-VALIDATION CHECKS
@@ -153,23 +136,45 @@ class CMJMetricsValidator(MetricsValidator):
         if flight_time_raw is None:
             return
 
-        flight_time = self._convert_raw_duration_to_seconds(flight_time_raw)
+        # 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
-        error_label = (
-            "below frame rate resolution limit"
-            if flight_time < bounds.absolute_min
-            else "exceeds elite human capability"
-        )
 
-        self._validate_metric_with_bounds(
-            "flight_time",
-            flight_time,
-            bounds,
-            profile,
-            result,
-            error_suffix=error_label,
-            format_str="{value:.3f}s",
-        )
+        if not bounds.is_physically_possible(flight_time):
+            if flight_time < bounds.absolute_min:
+                result.add_error(
+                    "flight_time",
+                    f"Flight time {flight_time:.3f}s below frame rate resolution limit",
+                    value=flight_time,
+                    bounds=(bounds.absolute_min, bounds.absolute_max),
+                )
+            else:
+                result.add_error(
+                    "flight_time",
+                    f"Flight time {flight_time:.3f}s exceeds elite human capability",
+                    value=flight_time,
+                    bounds=(bounds.absolute_min, bounds.absolute_max),
+                )
+        elif bounds.contains(flight_time, profile):
+            result.add_info(
+                "flight_time",
+                f"Flight time {flight_time:.3f}s within expected range for {profile.value}",
+                value=flight_time,
+            )
+        else:
+            # Outside expected range but physically possible
+            expected_min, expected_max = self._get_profile_range(profile, bounds)
+            result.add_warning(
+                "flight_time",
+                f"Flight time {flight_time:.3f}s outside typical range "
+                f"[{expected_min:.3f}-{expected_max:.3f}]s for {profile.value}",
+                value=flight_time,
+                bounds=(expected_min, expected_max),
+            )
 
     def _check_jump_height(
         self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
@@ -180,21 +185,37 @@ class CMJMetricsValidator(MetricsValidator):
             return
 
         bounds = CMJBounds.JUMP_HEIGHT
-        error_label = (
-            "essentially no jump (noise)"
-            if jump_height < bounds.absolute_min
-            else "exceeds human capability"
-        )
 
-        self._validate_metric_with_bounds(
-            "jump_height",
-            jump_height,
-            bounds,
-            profile,
-            result,
-            error_suffix=error_label,
-            format_str="{value:.3f}m",
-        )
+        if not bounds.is_physically_possible(jump_height):
+            if jump_height < bounds.absolute_min:
+                result.add_error(
+                    "jump_height",
+                    f"Jump height {jump_height:.3f}m essentially no jump (noise)",
+                    value=jump_height,
+                    bounds=(bounds.absolute_min, bounds.absolute_max),
+                )
+            else:
+                result.add_error(
+                    "jump_height",
+                    f"Jump height {jump_height:.3f}m exceeds human capability",
+                    value=jump_height,
+                    bounds=(bounds.absolute_min, bounds.absolute_max),
+                )
+        elif bounds.contains(jump_height, profile):
+            result.add_info(
+                "jump_height",
+                f"Jump height {jump_height:.3f}m within expected range for {profile.value}",
+                value=jump_height,
+            )
+        else:
+            expected_min, expected_max = self._get_profile_range(profile, bounds)
+            result.add_warning(
+                "jump_height",
+                f"Jump height {jump_height:.3f}m outside typical range "
+                f"[{expected_min:.3f}-{expected_max:.3f}]m for {profile.value}",
+                value=jump_height,
+                bounds=(expected_min, expected_max),
+            )
 
     def _check_countermovement_depth(
         self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
@@ -205,22 +226,40 @@ class CMJMetricsValidator(MetricsValidator):
             return
 
         bounds = CMJBounds.COUNTERMOVEMENT_DEPTH
-        error_label = (
-            "essentially no squat" if depth < bounds.absolute_min else "exceeds physical limit"
-        )
 
-        self._validate_metric_with_bounds(
-            "countermovement_depth",
-            depth,
-            bounds,
-            profile,
-            result,
-            error_suffix=error_label,
-            format_str="{value:.3f}m",
-        )
+        if not bounds.is_physically_possible(depth):
+            if depth < bounds.absolute_min:
+                result.add_error(
+                    "countermovement_depth",
+                    f"Countermovement depth {depth:.3f}m essentially no squat",
+                    value=depth,
+                    bounds=(bounds.absolute_min, bounds.absolute_max),
+                )
+            else:
+                result.add_error(
+                    "countermovement_depth",
+                    f"Countermovement depth {depth:.3f}m exceeds physical limit",
+                    value=depth,
+                    bounds=(bounds.absolute_min, bounds.absolute_max),
+                )
+        elif bounds.contains(depth, profile):
+            result.add_info(
+                "countermovement_depth",
+                f"Countermovement depth {depth:.3f}m within expected range for {profile.value}",
+                value=depth,
+            )
+        else:
+            expected_min, expected_max = self._get_profile_range(profile, bounds)
+            result.add_warning(
+                "countermovement_depth",
+                f"Countermovement depth {depth:.3f}m outside typical range "
+                f"[{expected_min:.3f}-{expected_max:.3f}]m for {profile.value}",
+                value=depth,
+                bounds=(expected_min, expected_max),
+            )
 
     def _check_concentric_duration(
-        self, metrics: MetricsDict, result: CMJValidationResult
+        self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate concentric duration (contact time)."""
         duration_raw = self._get_metric_value(
@@ -229,7 +268,13 @@ class CMJMetricsValidator(MetricsValidator):
         if duration_raw is None:
             return
 
-        duration = self._convert_raw_duration_to_seconds(duration_raw)
+        # 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):
@@ -256,7 +301,9 @@ class CMJMetricsValidator(MetricsValidator):
                 value=duration,
             )
 
-    def _check_eccentric_duration(self, metrics: MetricsDict, result: CMJValidationResult) -> None:
+    def _check_eccentric_duration(
+        self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
+    ) -> None:
         """Validate eccentric duration."""
         duration_raw = self._get_metric_value(
             metrics, "eccentric_duration_ms", "eccentric_duration"
@@ -264,7 +311,12 @@ class CMJMetricsValidator(MetricsValidator):
         if duration_raw is None:
             return
 
-        duration = self._convert_raw_duration_to_seconds(duration_raw)
+        # 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):
@@ -287,74 +339,71 @@ class CMJMetricsValidator(MetricsValidator):
         self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate peak eccentric and concentric velocities."""
-        velocity_checks = [
-            (
-                "peak_eccentric_velocity",
-                "peak_eccentric_velocity_m_s",
-                CMJBounds.PEAK_ECCENTRIC_VELOCITY,
-                "",
-            ),
-            (
-                "peak_concentric_velocity",
-                "peak_concentric_velocity_m_s",
-                CMJBounds.PEAK_CONCENTRIC_VELOCITY,
-                "insufficient to leave ground",
-            ),
-        ]
-
-        for metric_name, key_name, bounds, error_suffix in velocity_checks:
-            velocity = self._get_metric_value(metrics, key_name, metric_name)
-            if velocity is None:
-                continue
-
-            self._validate_velocity_metric(
-                metric_name, velocity, bounds, profile, result, error_suffix
-            )
+        # Eccentric
+        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):
+                result.add_error(
+                    "peak_eccentric_velocity",
+                    f"Peak eccentric velocity {ecc_vel:.2f} m/s outside limits",
+                    value=ecc_vel,
+                    bounds=(bounds.absolute_min, bounds.absolute_max),
+                )
+            elif bounds.contains(ecc_vel, profile):
+                result.add_info(
+                    "peak_eccentric_velocity",
+                    f"Peak eccentric velocity {ecc_vel:.2f} m/s within range for {profile.value}",
+                    value=ecc_vel,
+                )
+            else:
+                expected_min, expected_max = self._get_profile_range(profile, bounds)
+                result.add_warning(
+                    "peak_eccentric_velocity",
+                    f"Peak eccentric velocity {ecc_vel:.2f} m/s outside typical range "
+                    f"[{expected_min:.2f}-{expected_max:.2f}] for {profile.value}",
+                    value=ecc_vel,
+                    bounds=(expected_min, expected_max),
+                )
 
-    def _validate_velocity_metric(
-        self,
-        name: str,
-        velocity: float,
-        bounds: MetricBounds,
-        profile: AthleteProfile,
-        result: CMJValidationResult,
-        error_suffix: str,
-    ) -> None:
-        """Validate a velocity metric against bounds."""
-        if not bounds.is_physically_possible(velocity):
-            if velocity < bounds.absolute_min and error_suffix:
-                error_msg = (
-                    f"Peak {name.replace('peak_', '')} velocity {velocity:.2f} m/s {error_suffix}"
+        # Concentric
+        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):
+                if con_vel < bounds.absolute_min:
+                    result.add_error(
+                        "peak_concentric_velocity",
+                        f"Peak concentric velocity {con_vel:.2f} m/s insufficient to leave ground",
+                        value=con_vel,
+                        bounds=(bounds.absolute_min, bounds.absolute_max),
+                    )
+                else:
+                    result.add_error(
+                        "peak_concentric_velocity",
+                        f"Peak concentric velocity {con_vel:.2f} m/s exceeds elite capability",
+                        value=con_vel,
+                        bounds=(bounds.absolute_min, bounds.absolute_max),
+                    )
+            elif bounds.contains(con_vel, profile):
+                result.add_info(
+                    "peak_concentric_velocity",
+                    f"Peak concentric velocity {con_vel:.2f} m/s within range for {profile.value}",
+                    value=con_vel,
                 )
             else:
-                error_msg = (
-                    f"Peak {name.replace('peak_', '')} velocity {velocity:.2f} m/s outside limits"
+                expected_min, expected_max = self._get_profile_range(profile, bounds)
+                result.add_warning(
+                    "peak_concentric_velocity",
+                    f"Peak concentric velocity {con_vel:.2f} m/s outside typical range "
+                    f"[{expected_min:.2f}-{expected_max:.2f}] for {profile.value}",
+                    value=con_vel,
+                    bounds=(expected_min, expected_max),
                 )
-            result.add_error(
-                name,
-                error_msg,
-                value=velocity,
-                bounds=(bounds.absolute_min, bounds.absolute_max),
-            )
-        elif bounds.contains(velocity, profile):
-            velocity_type = name.replace("peak_", "").replace("_", " ")
-            result.add_info(
-                name,
-                f"Peak {velocity_type} velocity {velocity:.2f} m/s "
-                f"within range for {profile.value}",
-                value=velocity,
-            )
-        else:
-            expected_min, expected_max = self._get_profile_range(profile, bounds)
-            velocity_type = name.replace("peak_", "").replace("_", " ")
-            result.add_warning(
-                name,
-                f"Peak {velocity_type} velocity {velocity:.2f} m/s "
-                f"outside typical range [{expected_min:.2f}-{expected_max:.2f}] "
-                f"for {profile.value}",
-                value=velocity,
-                bounds=(expected_min, expected_max),
-            )
 
     def _check_flight_time_height_consistency(
         self, metrics: MetricsDict, result: CMJValidationResult
@@ -444,8 +493,16 @@ class CMJMetricsValidator(MetricsValidator):
         ):
             return
 
-        flight_time = self._convert_raw_duration_to_seconds(flight_time_raw)
-        concentric_duration = self._convert_raw_duration_to_seconds(concentric_duration_raw)
+        # 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
@@ -575,28 +632,49 @@ class CMJMetricsValidator(MetricsValidator):
         if angles is None:
             return
 
-        joint_definitions = [
-            ("hip_angle", TripleExtensionBounds.hip_angle_valid, "Hip"),
-            ("knee_angle", TripleExtensionBounds.knee_angle_valid, "Knee"),
-            ("ankle_angle", TripleExtensionBounds.ankle_angle_valid, "Ankle"),
-        ]
+        hip = angles.get("hip_angle")
+        if hip is not None:
+            if not TripleExtensionBounds.hip_angle_valid(hip, profile):
+                result.add_warning(
+                    "hip_angle",
+                    f"Hip angle {hip:.1f}° outside expected range for {profile.value}",
+                    value=hip,
+                )
+            else:
+                result.add_info(
+                    "hip_angle",
+                    f"Hip angle {hip:.1f}° within expected range for {profile.value}",
+                    value=hip,
+                )
 
-        for metric_name, validator, joint_name in joint_definitions:
-            angle = angles.get(metric_name)
-            if angle is None:
-                continue
+        knee = angles.get("knee_angle")
+        if knee is not None:
+            if not TripleExtensionBounds.knee_angle_valid(knee, profile):
+                result.add_warning(
+                    "knee_angle",
+                    f"Knee angle {knee:.1f}° outside expected range for {profile.value}",
+                    value=knee,
+                )
+            else:
+                result.add_info(
+                    "knee_angle",
+                    f"Knee angle {knee:.1f}° within expected range for {profile.value}",
+                    value=knee,
+                )
 
-            if not validator(angle, profile):
+        ankle = angles.get("ankle_angle")
+        if ankle is not None:
+            if not TripleExtensionBounds.ankle_angle_valid(ankle, profile):
                 result.add_warning(
-                    metric_name,
-                    f"{joint_name} angle {angle:.1f}° outside expected range for {profile.value}",
-                    value=angle,
+                    "ankle_angle",
+                    f"Ankle angle {ankle:.1f}° outside expected range for {profile.value}",
+                    value=ankle,
                 )
             else:
                 result.add_info(
-                    metric_name,
-                    f"{joint_name} angle {angle:.1f}° within expected range for {profile.value}",
-                    value=angle,
+                    "ankle_angle",
+                    f"Ankle angle {ankle:.1f}° within expected range for {profile.value}",
+                    value=ankle,
                 )
 
         # Detect joint compensation patterns
@@ -620,32 +698,32 @@ class CMJMetricsValidator(MetricsValidator):
         if hip is None or knee is None or ankle is None:
             return  # Need all three to detect patterns
 
-        # Profile-specific bounds lookup
-        profile_bounds = {
-            AthleteProfile.ELDERLY: (150, 175, 155, 175, 100, 125),
-            AthleteProfile.UNTRAINED: (160, 180, 165, 182, 110, 140),
-            AthleteProfile.RECREATIONAL: (160, 180, 165, 182, 110, 140),
-            AthleteProfile.TRAINED: (170, 185, 173, 190, 125, 155),
-            AthleteProfile.ELITE: (170, 185, 173, 190, 125, 155),
-        }
-
-        bounds_tuple = profile_bounds.get(profile)
-        if not bounds_tuple:
+        # Get profile-specific bounds
+        if profile == AthleteProfile.ELDERLY:
+            hip_min, hip_max = 150, 175
+            knee_min, knee_max = 155, 175
+            ankle_min, ankle_max = 100, 125
+        elif profile in (AthleteProfile.UNTRAINED, AthleteProfile.RECREATIONAL):
+            hip_min, hip_max = 160, 180
+            knee_min, knee_max = 165, 182
+            ankle_min, ankle_max = 110, 140
+        elif profile in (AthleteProfile.TRAINED, AthleteProfile.ELITE):
+            hip_min, hip_max = 170, 185
+            knee_min, knee_max = 173, 190
+            ankle_min, ankle_max = 125, 155
+        else:
             return
 
-        hip_min, hip_max, knee_min, knee_max, ankle_min, ankle_max = bounds_tuple
-
-        # Count joints at boundaries
+        # Count how many joints are near their boundaries
+        joints_at_boundary = 0
         boundary_threshold = 3.0  # degrees from limit
-        joints_at_boundary = sum(
-            1
-            for val, min_val, max_val in [
-                (hip, hip_min, hip_max),
-                (knee, knee_min, knee_max),
-                (ankle, ankle_min, ankle_max),
-            ]
-            if val <= min_val + boundary_threshold or val >= max_val - boundary_threshold
-        )
+
+        if hip <= hip_min + boundary_threshold or hip >= hip_max - boundary_threshold:
+            joints_at_boundary += 1
+        if knee <= knee_min + boundary_threshold or knee >= knee_max - boundary_threshold:
+            joints_at_boundary += 1
+        if ankle <= ankle_min + boundary_threshold or ankle >= ankle_max - boundary_threshold:
+            joints_at_boundary += 1
 
         # If 2+ joints at boundaries, likely compensation pattern
         if joints_at_boundary >= 2:
@@ -656,3 +734,20 @@ class CMJMetricsValidator(MetricsValidator):
                 f"May indicate compensatory movement pattern.",
                 value=float(joints_at_boundary),
             )
+
+    @staticmethod
+    def _get_profile_range(profile: AthleteProfile, bounds: MetricBounds) -> tuple[float, float]:
+        """Get min/max bounds for specific profile."""
+        if profile == AthleteProfile.ELDERLY:
+            return (bounds.practical_min, bounds.recreational_max)
+        elif profile == AthleteProfile.UNTRAINED:
+            return (bounds.practical_min, bounds.recreational_max)
+        elif profile == AthleteProfile.RECREATIONAL:
+            return (bounds.recreational_min, bounds.recreational_max)
+        elif profile == AthleteProfile.TRAINED:
+            trained_min = (bounds.recreational_min + bounds.elite_min) / 2
+            trained_max = (bounds.recreational_max + bounds.elite_max) / 2
+            return (trained_min, trained_max)
+        elif profile == AthleteProfile.ELITE:
+            return (bounds.elite_min, bounds.elite_max)
+        return (bounds.absolute_min, bounds.absolute_max)

kinemotion/{countermovement_jump → cmj}/validation_bounds.py

@@ -170,6 +170,17 @@ class TripleExtensionBounds:
             return 125 <= angle <= 155
         return True
 
+    # TRUNK TILT (forward lean from vertical, degrees)
+    @staticmethod
+    def trunk_tilt_valid(angle: float | None, profile: AthleteProfile) -> bool:
+        """Check if trunk tilt is valid for profile."""
+        if angle is None:
+            return True
+        if angle < -15 or angle > 60:
+            return False  # Outside reasonable range
+        # Most athletes show 10-30° forward lean during takeoff
+        return -10 <= angle <= 45
+
 
 class RSIBounds:
     """Reactive Strength Index bounds."""
@@ -204,6 +215,12 @@ class RSIBounds:
         """Check if RSI is within physiological bounds."""
         return RSIBounds.MIN_VALID <= rsi <= RSIBounds.MAX_VALID
 
+    @staticmethod
+    def in_range_for_profile(rsi: float, profile: AthleteProfile) -> bool:
+        """Check if RSI is in expected range for profile."""
+        min_rsi, max_rsi = RSIBounds.get_rsi_range(profile)
+        return min_rsi <= rsi <= max_rsi
+
 
 class MetricConsistency:
     """Cross-validation tolerance for metric consistency checks."""
@@ -284,7 +301,7 @@ ATHLETE_PROFILES = {
 
 
 def estimate_athlete_profile(
-    metrics_dict: MetricsDict, _gender: str | None = None
+    metrics_dict: MetricsDict, gender: str | None = None
 ) -> AthleteProfile:
     """Estimate athlete profile from metrics.
 

kinemotion/core/__init__.py

@@ -13,6 +13,7 @@ from .pose import (
     MediaPipePoseTracker,
     PoseTrackerFactory,
     compute_center_of_mass,
+    get_tracker_info,
 )
 from .pose_landmarks import KINEMOTION_LANDMARKS, LANDMARK_INDICES
 from .quality import (
@@ -34,24 +35,14 @@ from .timing import (
     PerformanceTimer,
     Timer,
 )
-from .video_analysis_base import (
-    AnalysisOverrides,
-    JumpAnalysisPipeline,
-    VideoAnalysisConfig,
-    VideoAnalysisResult,
-)
 from .video_io import VideoProcessor
 
 __all__ = [
-    # Video Analysis Base
-    "AnalysisOverrides",
-    "JumpAnalysisPipeline",
-    "VideoAnalysisConfig",
-    "VideoAnalysisResult",
     # Pose tracking
     "MediaPipePoseTracker",
     "PoseTrackerFactory",
     "compute_center_of_mass",
+    "get_tracker_info",
     "LANDMARK_INDICES",
     "KINEMOTION_LANDMARKS",
     "get_model_path",