kinemotion 0.72.1__py3-none-any.whl → 0.74.0__py3-none-any.whl

kinemotion/{cmj → countermovement_jump}/api.py

@@ -393,6 +393,24 @@ class CMJVideoConfig:
     overrides: AnalysisOverrides | None = None
     detection_confidence: float | None = None
     tracking_confidence: float | None = None
+    verbose: bool = False
+    timer: Timer | None = None
+    pose_tracker: "MediaPipePoseTracker | None" = None
+
+    def to_kwargs(self) -> dict:
+        """Convert config to kwargs dict for process_cmj_video."""
+        return {
+            "video_path": self.video_path,
+            "quality": self.quality,
+            "output_video": self.output_video,
+            "json_output": self.json_output,
+            "overrides": self.overrides,
+            "detection_confidence": self.detection_confidence,
+            "tracking_confidence": self.tracking_confidence,
+            "verbose": self.verbose,
+            "timer": self.timer,
+            "pose_tracker": self.pose_tracker,
+        }
 
 
 @dataclass
@@ -511,6 +529,23 @@ def process_cmj_video(
             return metrics
 
 
+def process_cmj_video_from_config(
+    config: CMJVideoConfig,
+) -> CMJMetrics:
+    """Process a CMJ video using a configuration object.
+
+    This is a convenience wrapper around process_cmj_video that
+    accepts a CMJVideoConfig instead of individual parameters.
+
+    Args:
+        config: Configuration object containing all analysis parameters
+
+    Returns:
+        CMJMetrics object containing analysis results
+    """
+    return process_cmj_video(**config.to_kwargs())
+
+
 def process_cmj_videos_bulk(
     configs: list[CMJVideoConfig],
     max_workers: int = 4,
@@ -537,17 +572,8 @@ def _process_cmj_video_wrapper(config: CMJVideoConfig) -> CMJVideoResult:
     start_time = time.perf_counter()
 
     try:
-        metrics = process_cmj_video(
-            video_path=config.video_path,
-            quality=config.quality,
-            output_video=config.output_video,
-            json_output=config.json_output,
-            overrides=config.overrides,
-            detection_confidence=config.detection_confidence,
-            tracking_confidence=config.tracking_confidence,
-            verbose=False,
-        )
-
+        # Use convenience wrapper to avoid parameter unpacking
+        metrics = process_cmj_video_from_config(config)
         processing_time = time.perf_counter() - start_time
 
         return CMJVideoResult(

kinemotion/{cmj → countermovement_jump}/cli.py

@@ -8,9 +8,12 @@ import click
 
 from ..core.auto_tuning import QualityPreset
 from ..core.cli_utils import (
+    batch_processing_options,
     collect_video_files,
     common_output_options,
     generate_batch_output_paths,
+    quality_option,
+    verbose_option,
 )
 from .api import AnalysisOverrides, process_cmj_video
 from .kinematics import CMJMetrics
@@ -59,52 +62,9 @@ def _process_batch_videos(
 @click.command(name="cmj-analyze")
 @click.argument("video_path", nargs=-1, type=click.Path(exists=False), required=True)
 @common_output_options
-@click.option(
-    "--quality",
-    type=click.Choice(["fast", "balanced", "accurate"], case_sensitive=False),
-    default="balanced",
-    help=(
-        "Analysis quality preset: "
-        "fast (quick, less precise), "
-        "balanced (default, good for most cases), "
-        "accurate (research-grade, slower)"
-    ),
-    show_default=True,
-)
-@click.option(
-    "--verbose",
-    "-v",
-    is_flag=True,
-    help="Show auto-selected parameters and analysis details",
-)
-# Batch processing options
-@click.option(
-    "--batch",
-    is_flag=True,
-    help="Enable batch processing mode for multiple videos",
-)
-@click.option(
-    "--workers",
-    type=int,
-    default=4,
-    help="Number of parallel workers for batch processing (default: 4)",
-    show_default=True,
-)
-@click.option(
-    "--output-dir",
-    type=click.Path(),
-    help="Directory for debug video outputs (batch mode only)",
-)
-@click.option(
-    "--json-output-dir",
-    type=click.Path(),
-    help="Directory for JSON metrics outputs (batch mode only)",
-)
-@click.option(
-    "--csv-summary",
-    type=click.Path(),
-    help="Path for CSV summary export (batch mode only)",
-)
+@quality_option
+@verbose_option
+@batch_processing_options
 # Expert parameters (hidden in help, but always available for advanced users)
 @click.option(
     "--smoothing-window",

kinemotion/{cmj → countermovement_jump}/metrics_validator.py

@@ -9,13 +9,6 @@ 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,
@@ -23,6 +16,13 @@ from kinemotion.core.validation import (
     MetricsValidator,
     ValidationResult,
 )
+from kinemotion.countermovement_jump.validation_bounds import (
+    CMJBounds,
+    MetricConsistency,
+    RSIBounds,
+    TripleExtensionBounds,
+    estimate_athlete_profile,
+)
 
 
 @dataclass
@@ -155,38 +155,21 @@ class CMJMetricsValidator(MetricsValidator):
 
         flight_time = self._convert_raw_duration_to_seconds(flight_time_raw)
         bounds = CMJBounds.FLIGHT_TIME
+        error_label = (
+            "below frame rate resolution limit"
+            if flight_time < bounds.absolute_min
+            else "exceeds elite human capability"
+        )
 
-        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),
-            )
+        self._validate_metric_with_bounds(
+            "flight_time",
+            flight_time,
+            bounds,
+            profile,
+            result,
+            error_suffix=error_label,
+            format_str="{value:.3f}s",
+        )
 
     def _check_jump_height(
         self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
@@ -197,37 +180,21 @@ class CMJMetricsValidator(MetricsValidator):
             return
 
         bounds = CMJBounds.JUMP_HEIGHT
+        error_label = (
+            "essentially no jump (noise)"
+            if jump_height < bounds.absolute_min
+            else "exceeds human capability"
+        )
 
-        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),
-            )
+        self._validate_metric_with_bounds(
+            "jump_height",
+            jump_height,
+            bounds,
+            profile,
+            result,
+            error_suffix=error_label,
+            format_str="{value:.3f}m",
+        )
 
     def _check_countermovement_depth(
         self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
@@ -238,37 +205,19 @@ class CMJMetricsValidator(MetricsValidator):
             return
 
         bounds = CMJBounds.COUNTERMOVEMENT_DEPTH
+        error_label = (
+            "essentially no squat" if depth < bounds.absolute_min else "exceeds physical limit"
+        )
 
-        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),
-            )
+        self._validate_metric_with_bounds(
+            "countermovement_depth",
+            depth,
+            bounds,
+            profile,
+            result,
+            error_suffix=error_label,
+            format_str="{value:.3f}m",
+        )
 
     def _check_concentric_duration(
         self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
@@ -340,71 +289,74 @@ class CMJMetricsValidator(MetricsValidator):
         self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate peak eccentric and concentric velocities."""
-        # 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),
-                )
+        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
+            )
 
-        # 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,
+    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}"
                 )
             else:
-                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),
+                error_msg = (
+                    f"Peak {name.replace('peak_', '')} velocity {velocity:.2f} m/s outside limits"
                 )
+            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
@@ -625,49 +577,28 @@ class CMJMetricsValidator(MetricsValidator):
         if angles is None:
             return
 
-        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,
-                )
+        joint_definitions = [
+            ("hip_angle", TripleExtensionBounds.hip_angle_valid, "Hip"),
+            ("knee_angle", TripleExtensionBounds.knee_angle_valid, "Knee"),
+            ("ankle_angle", TripleExtensionBounds.ankle_angle_valid, "Ankle"),
+        ]
 
-        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,
-                )
+        for metric_name, validator, joint_name in joint_definitions:
+            angle = angles.get(metric_name)
+            if angle is None:
+                continue
 
-        ankle = angles.get("ankle_angle")
-        if ankle is not None:
-            if not TripleExtensionBounds.ankle_angle_valid(ankle, profile):
+            if not validator(angle, profile):
                 result.add_warning(
-                    "ankle_angle",
-                    f"Ankle angle {ankle:.1f}° outside expected range for {profile.value}",
-                    value=ankle,
+                    metric_name,
+                    f"{joint_name} angle {angle:.1f}° outside expected range for {profile.value}",
+                    value=angle,
                 )
             else:
                 result.add_info(
-                    "ankle_angle",
-                    f"Ankle angle {ankle:.1f}° within expected range for {profile.value}",
-                    value=ankle,
+                    metric_name,
+                    f"{joint_name} angle {angle:.1f}° within expected range for {profile.value}",
+                    value=angle,
                 )
 
         # Detect joint compensation patterns
@@ -691,32 +622,32 @@ class CMJMetricsValidator(MetricsValidator):
         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:
+        # 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:
             return
 
-        # Count how many joints are near their boundaries
-        joints_at_boundary = 0
-        boundary_threshold = 3.0  # degrees from limit
+        hip_min, hip_max, knee_min, knee_max, ankle_min, ankle_max = bounds_tuple
 
-        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
+        # Count joints at boundaries
+        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 2+ joints at boundaries, likely compensation pattern
         if joints_at_boundary >= 2:
@@ -727,20 +658,3 @@ 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)