kinemotion 0.29.3__py3-none-any.whl → 0.31.0__py3-none-any.whl

kinemotion/api.py

@@ -18,6 +18,8 @@ from .core.auto_tuning import (
     analyze_video_sample,
     auto_tune_parameters,
 )
+from .core.cmj_metrics_validator import CMJMetricsValidator
+from .core.dropjump_metrics_validator import DropJumpMetricsValidator
 from .core.filtering import reject_outliers
 from .core.metadata import (
     AlgorithmConfig,
@@ -60,7 +62,8 @@ def _parse_quality_preset(quality: str) -> QualityPreset:
         return QualityPreset(quality.lower())
     except ValueError as e:
         raise ValueError(
-            f"Invalid quality preset: {quality}. Must be 'fast', 'balanced', or 'accurate'"
+            f"Invalid quality preset: {quality}. "
+            "Must be 'fast', 'balanced', or 'accurate'"
         ) from e
 
 
@@ -499,7 +502,8 @@ def process_dropjump_video(
         if verbose:
             print("Assessing tracking quality...")
 
-        # Detect outliers for quality scoring (doesn't affect results, just for assessment)
+        # Detect outliers for quality scoring (doesn't affect results, just
+        # for assessment)
         _, outlier_mask = reject_outliers(
             vertical_positions,
             use_ransac=True,
@@ -602,6 +606,16 @@ def process_dropjump_video(
         if verbose:
             print("Analysis complete!")
 
+        # Validate metrics against physiological bounds
+        validator = DropJumpMetricsValidator()
+        validation_result = validator.validate(metrics.to_dict())  # type: ignore[arg-type]
+        metrics.validation_result = validation_result
+
+        if verbose and validation_result.issues:
+            print("\n⚠️  Validation Results:")
+            for issue in validation_result.issues:
+                print(f"  [{issue.severity.value}] {issue.metric}: {issue.message}")
+
         return metrics
 
 
@@ -614,9 +628,11 @@ def process_dropjump_videos_bulk(
     Process multiple drop jump videos in parallel using ProcessPoolExecutor.
 
     Args:
-        configs: List of DropJumpVideoConfig objects specifying video paths and parameters
+        configs: List of DropJumpVideoConfig objects specifying video paths
+            and parameters
         max_workers: Maximum number of parallel workers (default: 4)
-        progress_callback: Optional callback function called after each video completes.
+        progress_callback: Optional callback function called after each video
+            completes.
                          Receives DropJumpVideoResult object.
 
     Returns:
@@ -941,7 +957,8 @@ def process_cmj_video(
         if verbose:
             print("Assessing tracking quality...")
 
-        # Detect outliers for quality scoring (doesn't affect results, just for assessment)
+        # Detect outliers for quality scoring (doesn't affect results, just
+        # for assessment)
         _, outlier_mask = reject_outliers(
             vertical_positions,
             use_ransac=True,
@@ -1035,9 +1052,19 @@ def process_cmj_video(
 
         if verbose:
             print(f"\nJump height: {metrics.jump_height:.3f}m")
-            print(f"Flight time: {metrics.flight_time*1000:.1f}ms")
+            print(f"Flight time: {metrics.flight_time * 1000:.1f}ms")
             print(f"Countermovement depth: {metrics.countermovement_depth:.3f}m")
 
+        # Validate metrics against physiological bounds
+        validator = CMJMetricsValidator()
+        validation_result = validator.validate(metrics.to_dict()["data"])  # type: ignore[arg-type]
+        metrics.validation_result = validation_result
+
+        if verbose and validation_result.issues:
+            print("\n⚠️  Validation Results:")
+            for issue in validation_result.issues:
+                print(f"  [{issue.severity.value}] {issue.metric}: {issue.message}")
+
         return metrics
 
 
@@ -1104,7 +1131,8 @@ def process_cmj_videos_bulk(
 
 def _process_cmj_video_wrapper(config: CMJVideoConfig) -> CMJVideoResult:
     """
-    Wrapper function for parallel CMJ processing. Must be picklable (top-level function).
+    Wrapper function for parallel CMJ processing. Must be picklable
+    (top-level function).
 
     Args:
         config: CMJVideoConfig object with processing parameters

kinemotion/cmj/analysis.py

@@ -62,7 +62,8 @@ def find_standing_phase(
     """
     Find the end of standing phase (start of countermovement).
 
-    Looks for a period of low velocity (standing) followed by consistent downward motion.
+    Looks for a period of low velocity (standing) followed by consistent
+    downward motion.
 
     Args:
         positions: Array of vertical positions (normalized 0-1)
@@ -109,11 +110,13 @@ def find_countermovement_start(
     """
     Find the start of countermovement (eccentric phase).
 
-    Detects when velocity becomes consistently positive (downward motion in normalized coords).
+    Detects when velocity becomes consistently positive (downward motion in
+    normalized coords).
 
     Args:
         velocities: Array of SIGNED vertical velocities
-        countermovement_threshold: Velocity threshold for detecting downward motion (POSITIVE)
+        countermovement_threshold: Velocity threshold for detecting downward
+            motion (POSITIVE)
         min_eccentric_frames: Minimum consecutive frames of downward motion
         standing_start: Optional frame where standing phase ended
 

kinemotion/cmj/cli.py

@@ -177,7 +177,8 @@ def _process_batch_videos(
     default=None,
     help="[EXPERT] Override pose tracking confidence",
 )
-def cmj_analyze(  # NOSONAR(S107) - Click CLI requires individual parameters for each option
+def cmj_analyze(  # NOSONAR(S107) - Click CLI requires individual parameters
+    # for each option
     video_path: tuple[str, ...],
     output: str | None,
     json_output: str | None,
@@ -197,10 +198,12 @@ def cmj_analyze(  # NOSONAR(S107) - Click CLI requires individual parameters for
     tracking_confidence: float | None,
 ) -> None:
     """
-    Analyze counter movement jump (CMJ) video(s) to estimate jump performance metrics.
+    Analyze counter movement jump (CMJ) video(s) to estimate jump performance
+    metrics.
 
-    Uses intelligent auto-tuning to select optimal parameters based on video characteristics.
-    Parameters are automatically adjusted for frame rate, tracking quality, and analysis preset.
+    Uses intelligent auto-tuning to select optimal parameters based on video
+    characteristics. Parameters are automatically adjusted for frame rate,
+    tracking quality, and analysis preset.
 
     VIDEO_PATH: Path(s) to video file(s). Supports glob patterns in batch mode.
 
@@ -341,11 +344,13 @@ def _output_results(metrics: Any, json_output: str | None) -> None:
         f"Total movement time: {metrics.total_movement_time * 1000:.1f} ms", err=True
     )
     click.echo(
-        f"Peak eccentric velocity: {abs(metrics.peak_eccentric_velocity):.3f} m/s (downward)",
+        f"Peak eccentric velocity: {abs(metrics.peak_eccentric_velocity):.3f} "
+        "m/s (downward)",
         err=True,
     )
     click.echo(
-        f"Peak concentric velocity: {metrics.peak_concentric_velocity:.3f} m/s (upward)",
+        f"Peak concentric velocity: {metrics.peak_concentric_velocity:.3f} "
+        "m/s (upward)",
         err=True,
     )
     if metrics.transition_time is not None:

kinemotion/cmj/debug_overlay.py

@@ -370,10 +370,10 @@ class CMJDebugOverlayRenderer(BaseDebugOverlayRenderer):
 
         metrics_text = [
             f"Jump Height: {metrics.jump_height:.3f}m",
-            f"Flight Time: {metrics.flight_time*1000:.0f}ms",
+            f"Flight Time: {metrics.flight_time * 1000:.0f}ms",
             f"CM Depth: {metrics.countermovement_depth:.3f}m",
-            f"Ecc Duration: {metrics.eccentric_duration*1000:.0f}ms",
-            f"Con Duration: {metrics.concentric_duration*1000:.0f}ms",
+            f"Ecc Duration: {metrics.eccentric_duration * 1000:.0f}ms",
+            f"Con Duration: {metrics.concentric_duration * 1000:.0f}ms",
         ]
 
         # Draw background

kinemotion/cmj/kinematics.py

@@ -9,6 +9,7 @@ from numpy.typing import NDArray
 from ..core.formatting import format_float_metric
 
 if TYPE_CHECKING:
+    from ..core.cmj_metrics_validator import ValidationResult
     from ..core.metadata import ResultMetadata
     from ..core.quality import QualityAssessment
 
@@ -32,11 +33,12 @@ class CMJDataDict(TypedDict, total=False):
     tracking_method: str
 
 
-class CMJResultDict(TypedDict):
+class CMJResultDict(TypedDict, total=False):
     """Type-safe dictionary for complete CMJ result with data and metadata."""
 
     data: CMJDataDict
     metadata: dict  # ResultMetadata.to_dict()
+    validation: dict  # ValidationResult.to_dict()
 
 
 @dataclass
@@ -46,12 +48,17 @@ class CMJMetrics:
     Attributes:
         jump_height: Maximum jump height in meters
         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 milliseconds
+        countermovement_depth: Vertical distance traveled during eccentric
+            phase in meters
+        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
+        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 milliseconds
         standing_start_frame: Frame where standing phase ends (countermovement begins)
         lowest_point_frame: Frame at lowest point of countermovement
@@ -60,6 +67,7 @@ class CMJMetrics:
         video_fps: Frames per second of the analyzed video
         tracking_method: Method used for tracking ("foot" or "com")
         quality_assessment: Optional quality assessment with confidence and warnings
+        validation_result: Optional validation result with physiological bounds checks
     """
 
     jump_height: float
@@ -79,6 +87,7 @@ class CMJMetrics:
     tracking_method: str
     quality_assessment: "QualityAssessment | None" = None
     result_metadata: "ResultMetadata | None" = None
+    validation_result: "ValidationResult | None" = None
 
     def to_dict(self) -> CMJResultDict:
         """Convert metrics to JSON-serializable dictionary with data/metadata structure.
@@ -129,7 +138,13 @@ class CMJMetrics:
             # No metadata available
             metadata = {}
 
-        return {"data": data, "metadata": metadata}
+        result: CMJResultDict = {"data": data, "metadata": metadata}
+
+        # Include validation results if available
+        if self.validation_result is not None:
+            result["validation"] = self.validation_result.to_dict()
+
+        return result
 
 
 def calculate_cmj_metrics(

kinemotion/core/cli_utils.py

@@ -120,8 +120,10 @@ def print_auto_tuned_params(
         video: Video processor
         quality_preset: Quality preset
         params: Auto-tuned parameters
-        characteristics: Optional video characteristics (for tracking quality display)
-        extra_params: Optional extra parameters to display (e.g., countermovement_threshold)
+        characteristics: Optional video characteristics (for tracking quality
+            display)
+        extra_params: Optional extra parameters to display (e.g.,
+            countermovement_threshold)
     """
     click.echo("\n" + "=" * 60, err=True)
     click.echo("AUTO-TUNED PARAMETERS", err=True)

kinemotion/core/cmj_metrics_validator.py

@@ -121,6 +121,36 @@ class ValidationResult:
         else:
             self.status = "PASS"
 
+    def to_dict(self) -> dict:
+        """Convert validation result to JSON-serializable dictionary.
+
+        Returns:
+            Dictionary with status, issues, and consistency metrics.
+        """
+        return {
+            "status": self.status,
+            "issues": [
+                {
+                    "severity": issue.severity.value,
+                    "metric": issue.metric,
+                    "message": issue.message,
+                    "value": issue.value,
+                    "bounds": issue.bounds,
+                }
+                for issue in self.issues
+            ],
+            "athlete_profile": (
+                self.athlete_profile.value if self.athlete_profile else None
+            ),
+            "rsi": self.rsi,
+            "height_flight_time_consistency_percent": (
+                self.height_flight_time_consistency
+            ),
+            "velocity_height_consistency_percent": self.velocity_height_consistency,
+            "depth_height_ratio": self.depth_height_ratio,
+            "contact_depth_ratio": self.contact_depth_ratio,
+        }
+
 
 class CMJMetricsValidator:
     """Comprehensive CMJ metrics validator."""
@@ -206,7 +236,8 @@ class CMJMetricsValidator:
         elif bounds.contains(flight_time, profile):
             result.add_info(
                 "flight_time",
-                f"Flight time {flight_time:.3f}s within expected range for {profile.value}",
+                f"Flight time {flight_time:.3f}s within expected range for "
+                f"{profile.value}",
                 value=flight_time,
             )
         else:
@@ -248,7 +279,8 @@ class CMJMetricsValidator:
         elif bounds.contains(jump_height, profile):
             result.add_info(
                 "jump_height",
-                f"Jump height {jump_height:.3f}m within expected range for {profile.value}",
+                f"Jump height {jump_height:.3f}m within expected range for "
+                f"{profile.value}",
                 value=jump_height,
             )
         else:
@@ -289,7 +321,8 @@ class CMJMetricsValidator:
         elif bounds.contains(depth, profile):
             result.add_info(
                 "countermovement_depth",
-                f"Countermovement depth {depth:.3f}m within expected range for {profile.value}",
+                f"Countermovement depth {depth:.3f}m within expected range for "
+                f"{profile.value}",
                 value=depth,
             )
         else:
@@ -323,14 +356,16 @@ class CMJMetricsValidator:
             else:
                 result.add_error(
                     "concentric_duration",
-                    f"Concentric duration {duration:.3f}s likely includes standing phase",
+                    f"Concentric duration {duration:.3f}s likely includes "
+                    "standing phase",
                     value=duration,
                     bounds=(bounds.absolute_min, bounds.absolute_max),
                 )
         elif bounds.contains(duration, profile):
             result.add_info(
                 "concentric_duration",
-                f"Concentric duration {duration:.3f}s within expected range for {profile.value}",
+                f"Concentric duration {duration:.3f}s within expected range for "
+                f"{profile.value}",
                 value=duration,
             )
         else:
@@ -363,7 +398,8 @@ class CMJMetricsValidator:
         elif bounds.contains(duration, profile):
             result.add_info(
                 "eccentric_duration",
-                f"Eccentric duration {duration:.3f}s within expected range for {profile.value}",
+                f"Eccentric duration {duration:.3f}s within expected range for "
+                f"{profile.value}",
                 value=duration,
             )
         else:
@@ -394,7 +430,8 @@ class CMJMetricsValidator:
             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}",
+                    f"Peak eccentric velocity {ecc_vel:.2f} m/s within range "
+                    f"for {profile.value}",
                     value=ecc_vel,
                 )
             else:
@@ -415,21 +452,24 @@ class CMJMetricsValidator:
                 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",
+                        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",
+                        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}",
+                    f"Peak concentric velocity {con_vel:.2f} m/s within range "
+                    f"for {profile.value}",
                     value=con_vel,
                 )
             else:
@@ -462,15 +502,17 @@ class CMJMetricsValidator:
         if error_pct > MetricConsistency.HEIGHT_FLIGHT_TIME_TOLERANCE:
             result.add_error(
                 "height_flight_time_consistency",
-                f"Jump height {jump_height:.3f}m inconsistent with flight time {flight_time:.3f}s "
-                f"(expected {expected_height:.3f}m, error {error_pct*100:.1f}%)",
+                f"Jump height {jump_height:.3f}m inconsistent with flight "
+                f"time {flight_time:.3f}s (expected {expected_height:.3f}m, "
+                f"error {error_pct * 100:.1f}%)",
                 value=error_pct,
                 bounds=(0, MetricConsistency.HEIGHT_FLIGHT_TIME_TOLERANCE),
             )
         else:
             result.add_info(
                 "height_flight_time_consistency",
-                f"Jump height and flight time consistent (error {error_pct*100:.1f}%)",
+                f"Jump height and flight time consistent "
+                f"(error {error_pct * 100:.1f}%)",
                 value=error_pct,
             )
 
@@ -495,7 +537,7 @@ class CMJMetricsValidator:
             error_msg = (
                 f"Peak velocity {velocity:.2f} m/s inconsistent with "
                 f"jump height {jump_height:.3f}m (expected {expected_velocity:.2f} "
-                f"m/s, error {error_pct*100:.1f}%)"
+                f"m/s, error {error_pct * 100:.1f}%)"
             )
             result.add_warning(
                 "velocity_height_consistency",
@@ -506,7 +548,8 @@ class CMJMetricsValidator:
         else:
             result.add_info(
                 "velocity_height_consistency",
-                f"Peak velocity and jump height consistent (error {error_pct*100:.1f}%)",
+                f"Peak velocity and jump height consistent "
+                f"(error {error_pct * 100:.1f}%)",
                 value=error_pct,
             )
 
@@ -547,14 +590,16 @@ class CMJMetricsValidator:
             if expected_min <= rsi <= expected_max:
                 result.add_info(
                     "rsi",
-                    f"RSI {rsi:.2f} within expected range [{expected_min:.2f}-{expected_max:.2f}] "
+                    f"RSI {rsi:.2f} within expected range "
+                    f"[{expected_min:.2f}-{expected_max:.2f}] "
                     f"for {profile.value}",
                     value=rsi,
                 )
             else:
                 result.add_warning(
                     "rsi",
-                    f"RSI {rsi:.2f} outside typical range [{expected_min:.2f}-{expected_max:.2f}] "
+                    f"RSI {rsi:.2f} outside typical range "
+                    f"[{expected_min:.2f}-{expected_max:.2f}] "
                     f"for {profile.value}",
                     value=rsi,
                     bounds=(expected_min, expected_max),
@@ -620,7 +665,8 @@ class CMJMetricsValidator:
         if ratio < MetricConsistency.CONTACT_DEPTH_RATIO_MIN:
             result.add_warning(
                 "contact_depth_ratio",
-                f"Contact time {ratio:.2f}s/m to depth ratio: Very fast for depth traversed",
+                f"Contact time {ratio:.2f}s/m to depth ratio: Very fast for "
+                "depth traversed",
                 value=ratio,
                 bounds=(
                     MetricConsistency.CONTACT_DEPTH_RATIO_MIN,
@@ -672,7 +718,8 @@ class CMJMetricsValidator:
             if not TripleExtensionBounds.knee_angle_valid(knee, profile):
                 result.add_warning(
                     "knee_angle",
-                    f"Knee angle {knee:.1f}° outside expected range for {profile.value}",
+                    f"Knee angle {knee:.1f}° outside expected range for "
+                    f"{profile.value}",
                     value=knee,
                 )
             else:
@@ -687,16 +734,82 @@ class CMJMetricsValidator:
             if not TripleExtensionBounds.ankle_angle_valid(ankle, profile):
                 result.add_warning(
                     "ankle_angle",
-                    f"Ankle angle {ankle:.1f}° outside expected range for {profile.value}",
+                    f"Ankle angle {ankle:.1f}° outside expected range for "
+                    f"{profile.value}",
                     value=ankle,
                 )
             else:
                 result.add_info(
                     "ankle_angle",
-                    f"Ankle angle {ankle:.1f}° within expected range for {profile.value}",
+                    f"Ankle angle {ankle:.1f}° within expected range for "
+                    f"{profile.value}",
                     value=ankle,
                 )
 
+        # Detect joint compensation patterns
+        self._check_joint_compensation_pattern(angles, result, profile)
+
+    def _check_joint_compensation_pattern(
+        self, angles: dict, result: ValidationResult, profile: AthleteProfile
+    ) -> None:
+        """Detect compensatory joint patterns in triple extension.
+
+        When one joint cannot achieve full extension, others may compensate.
+        Example: Limited hip extension (160°) with excessive knee extension (185°+)
+        suggests compensation rather than balanced movement quality.
+
+        This is a biomechanical quality indicator, not an error.
+        """
+        hip = angles.get("hip_angle")
+        knee = angles.get("knee_angle")
+        ankle = angles.get("ankle_angle")
+
+        if hip is None or knee is None or ankle is None:
+            return  # Need all three to detect patterns
+
+        # 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
+
+        # Count how many joints are near their boundaries
+        joints_at_boundary = 0
+        boundary_threshold = 3.0  # degrees from limit
+
+        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:
+            result.add_info(
+                "joint_compensation",
+                f"Multiple joints near extension limits (hip={hip:.0f}°, "
+                f"knee={knee:.0f}°, ankle={ankle:.0f}°). "
+                f"May indicate compensatory movement pattern.",
+                value=float(joints_at_boundary),
+            )
+
     @staticmethod
     def _get_profile_range(
         profile: AthleteProfile, bounds: MetricBounds

kinemotion/core/cmj_validation_bounds.py

@@ -356,7 +356,9 @@ ATHLETE_PROFILES = {
 }
 
 
-def estimate_athlete_profile(metrics_dict: dict) -> AthleteProfile:
+def estimate_athlete_profile(
+    metrics_dict: dict, gender: str | None = None
+) -> AthleteProfile:
     """Estimate athlete profile from metrics.
 
     Uses jump height as primary classifier:
@@ -365,6 +367,18 @@ def estimate_athlete_profile(metrics_dict: dict) -> AthleteProfile:
     - 0.35-0.65m: Recreational
     - 0.65-0.85m: Trained
     - >0.85m: Elite
+
+    NOTE: Bounds are calibrated for adult males. Female athletes typically achieve
+    60-70% of male heights due to lower muscle mass and strength. If analyzing
+    female athletes, interpret results one level lower than classification suggests.
+    Example: Female athlete with 0.45m jump = Recreational male = Trained female.
+
+    Args:
+        metrics_dict: Dictionary with CMJ metric values
+        gender: Optional gender for context ("M"/"F"). Currently informational only.
+
+    Returns:
+        Estimated AthleteProfile
     """
     jump_height = metrics_dict.get("jump_height", 0)