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

kinemotion/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/countermovement_jump/metrics_validator.py

@@ -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)

kinemotion/drop_jump/analysis.py

@@ -677,6 +677,48 @@ def refine_transition_with_curvature(
     return refined_frame
 
 
+def _refine_phase_boundaries(
+    foot_positions: FloatArray,
+    start_frac: float,
+    end_frac: float,
+    start_type: str,
+    end_type: str,
+    smoothing_window: int,
+    polyorder: int,
+) -> tuple[float, float]:
+    """Refine phase boundary frames using curvature analysis.
+
+    Args:
+        foot_positions: Array of foot y-positions (normalized, 0-1)
+        start_frac: Start frame (fractional)
+        end_frac: End frame (fractional)
+        start_type: Transition type for start ("landing" or "takeoff")
+        end_type: Transition type for end ("landing" or "takeoff")
+        smoothing_window: Window size for acceleration computation
+        polyorder: Polynomial order for Savitzky-Golay filter
+
+    Returns:
+        Tuple of (refined_start, refined_end) fractional frame indices
+    """
+    refined_start = refine_transition_with_curvature(
+        foot_positions,
+        start_frac,
+        start_type,
+        search_window=3,
+        smoothing_window=smoothing_window,
+        polyorder=polyorder,
+    )
+    refined_end = refine_transition_with_curvature(
+        foot_positions,
+        end_frac,
+        end_type,
+        search_window=3,
+        smoothing_window=smoothing_window,
+        polyorder=polyorder,
+    )
+    return refined_start, refined_end
+
+
 def find_interpolated_phase_transitions_with_curvature(
     foot_positions: FloatArray,
     contact_states: list[ContactState],
@@ -716,47 +758,30 @@ def find_interpolated_phase_transitions_with_curvature(
     refined_phases: list[tuple[float, float, ContactState]] = []
 
     for start_frac, end_frac, state in interpolated_phases:
-        refined_start = start_frac
-        refined_end = end_frac
-
         if state == ContactState.ON_GROUND:
-            # Refine landing (start of ground contact)
-            refined_start = refine_transition_with_curvature(
+            # ON_GROUND: landing at start, takeoff at end
+            refined_start, refined_end = _refine_phase_boundaries(
                 foot_positions,
                 start_frac,
-                "landing",
-                search_window=3,
-                smoothing_window=smoothing_window,
-                polyorder=polyorder,
-            )
-            # Refine takeoff (end of ground contact)
-            refined_end = refine_transition_with_curvature(
-                foot_positions,
                 end_frac,
+                "landing",
                 "takeoff",
-                search_window=3,
-                smoothing_window=smoothing_window,
-                polyorder=polyorder,
+                smoothing_window,
+                polyorder,
             )
-
         elif state == ContactState.IN_AIR:
-            # For flight phases, takeoff is at start, landing is at end
-            refined_start = refine_transition_with_curvature(
+            # IN_AIR: takeoff at start, landing at end
+            refined_start, refined_end = _refine_phase_boundaries(
                 foot_positions,
                 start_frac,
-                "takeoff",
-                search_window=3,
-                smoothing_window=smoothing_window,
-                polyorder=polyorder,
-            )
-            refined_end = refine_transition_with_curvature(
-                foot_positions,
                 end_frac,
+                "takeoff",
                 "landing",
-                search_window=3,
-                smoothing_window=smoothing_window,
-                polyorder=polyorder,
+                smoothing_window,
+                polyorder,
             )
+        else:
+            refined_start, refined_end = start_frac, end_frac
 
         refined_phases.append((refined_start, refined_end, state))