kinemotion 0.10.6__py3-none-any.whl → 0.67.0__py3-none-any.whl

kinemotion/cmj/validation_bounds.py

@@ -0,0 +1,341 @@
+"""CMJ metrics physiological bounds for validation testing.
+
+This module defines realistic physiological bounds for Counter Movement Jump (CMJ)
+metrics based on biomechanical literature and real-world athlete performance.
+
+These bounds are used to:
+1. Prevent false positives from measurement noise
+2. Catch real errors in video processing and phase detection
+3. Provide athlete-profile-appropriate validation
+4. Enable cross-validation of metric consistency
+
+References:
+- Nordez et al. (2009): CMJ depth-height relationships
+- Cormie et al. (2011): Power generation characteristics
+- Bogdanis (2012): Plyometric training effects
+"""
+
+from kinemotion.core.types import MetricsDict
+from kinemotion.core.validation import AthleteProfile, MetricBounds
+
+
+class CMJBounds:
+    """Collection of physiological bounds for all CMJ metrics."""
+
+    # FLIGHT TIME (seconds)
+    FLIGHT_TIME = MetricBounds(
+        absolute_min=0.08,  # Frame rate resolution limit
+        practical_min=0.15,  # Minimum effort jump
+        recreational_min=0.25,  # Untrained ~10cm
+        recreational_max=0.70,  # Recreational ~30-50cm
+        elite_min=0.65,  # Trained ~60cm
+        elite_max=1.10,  # Elite >100cm
+        absolute_max=1.30,
+        unit="s",
+    )
+
+    # JUMP HEIGHT (meters)
+    JUMP_HEIGHT = MetricBounds(
+        absolute_min=0.02,
+        practical_min=0.05,
+        recreational_min=0.15,  # Untrained with effort
+        recreational_max=0.60,  # Good recreational
+        elite_min=0.65,
+        elite_max=1.00,
+        absolute_max=1.30,
+        unit="m",
+    )
+
+    # COUNTERMOVEMENT DEPTH (meters)
+    COUNTERMOVEMENT_DEPTH = MetricBounds(
+        absolute_min=0.05,
+        practical_min=0.08,  # Minimal squat
+        recreational_min=0.20,  # Shallow to parallel
+        recreational_max=0.55,  # Normal to deep squat
+        elite_min=0.40,
+        elite_max=0.75,
+        absolute_max=1.10,  # Only extreme tall athletes
+        unit="m",
+    )
+
+    # CONCENTRIC DURATION / CONTACT TIME (seconds)
+    CONCENTRIC_DURATION = MetricBounds(
+        absolute_min=0.08,
+        practical_min=0.10,  # Extreme plyometric
+        recreational_min=0.40,  # Moderate propulsion
+        recreational_max=0.90,  # Slow push-off
+        elite_min=0.25,
+        elite_max=0.50,
+        absolute_max=1.80,
+        unit="s",
+    )
+
+    # ECCENTRIC DURATION (seconds)
+    ECCENTRIC_DURATION = MetricBounds(
+        absolute_min=0.15,
+        practical_min=0.25,
+        recreational_min=0.35,
+        recreational_max=0.75,
+        elite_min=0.30,
+        elite_max=0.65,
+        absolute_max=1.30,
+        unit="s",
+    )
+
+    # TOTAL MOVEMENT TIME (seconds)
+    TOTAL_MOVEMENT_TIME = MetricBounds(
+        absolute_min=0.25,
+        practical_min=0.35,
+        recreational_min=0.75,
+        recreational_max=1.50,
+        elite_min=0.55,
+        elite_max=1.10,
+        absolute_max=2.20,
+        unit="s",
+    )
+
+    # PEAK ECCENTRIC VELOCITY (m/s, downward)
+    PEAK_ECCENTRIC_VELOCITY = MetricBounds(
+        absolute_min=0.10,
+        practical_min=0.20,
+        recreational_min=0.80,
+        recreational_max=2.00,
+        elite_min=2.00,
+        elite_max=3.50,
+        absolute_max=4.50,
+        unit="m/s",
+    )
+
+    # PEAK CONCENTRIC VELOCITY (m/s, upward)
+    PEAK_CONCENTRIC_VELOCITY = MetricBounds(
+        absolute_min=0.30,
+        practical_min=0.50,
+        recreational_min=1.80,
+        recreational_max=2.80,
+        elite_min=3.00,
+        elite_max=4.20,
+        absolute_max=5.00,
+        unit="m/s",
+    )
+
+
+class TripleExtensionBounds:
+    """Physiological bounds for triple extension angles (degrees)."""
+
+    # HIP ANGLE at takeoff (close to 180° = full extension)
+    @staticmethod
+    def hip_angle_valid(angle: float | None, profile: AthleteProfile) -> bool:
+        """Check if hip angle is valid for profile."""
+        if angle is None:
+            return True  # May not be detectable
+        if angle < 120 or angle > 195:
+            return False  # Outside physiological limits
+        if profile == AthleteProfile.ELDERLY:
+            return 150 <= angle <= 175
+        elif profile in (AthleteProfile.UNTRAINED, AthleteProfile.RECREATIONAL):
+            return 160 <= angle <= 180
+        elif profile in (AthleteProfile.TRAINED, AthleteProfile.ELITE):
+            return 170 <= angle <= 185
+        return True
+
+    # KNEE ANGLE at takeoff (close to 180° = full extension)
+    @staticmethod
+    def knee_angle_valid(angle: float | None, profile: AthleteProfile) -> bool:
+        """Check if knee angle is valid for profile."""
+        if angle is None:
+            return True
+        if angle < 130 or angle > 200:
+            return False  # Outside physiological limits
+        if profile == AthleteProfile.ELDERLY:
+            return 155 <= angle <= 175
+        elif profile in (AthleteProfile.UNTRAINED, AthleteProfile.RECREATIONAL):
+            return 165 <= angle <= 182
+        elif profile in (AthleteProfile.TRAINED, AthleteProfile.ELITE):
+            return 173 <= angle <= 190
+        return True
+
+    # ANKLE ANGLE at takeoff (120-155° = plantarflexion, 90° = neutral)
+    @staticmethod
+    def ankle_angle_valid(angle: float | None, profile: AthleteProfile) -> bool:
+        """Check if ankle angle is valid for profile."""
+        if angle is None:
+            return True  # Often not detectable in side view
+        if angle < 90 or angle > 165:
+            return False  # Outside physiological limits
+        if profile == AthleteProfile.ELDERLY:
+            return 100 <= angle <= 125
+        elif profile in (AthleteProfile.UNTRAINED, AthleteProfile.RECREATIONAL):
+            return 110 <= angle <= 140
+        elif profile in (AthleteProfile.TRAINED, AthleteProfile.ELITE):
+            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."""
+
+    # Calculated as: RSI = flight_time / contact_time
+    MIN_VALID = 0.30  # Below this: invalid metrics
+    MAX_VALID = 4.00  # Above this: invalid metrics
+
+    ELDERLY_RANGE = (0.15, 0.30)
+    UNTRAINED_RANGE = (0.30, 0.80)
+    RECREATIONAL_RANGE = (0.80, 1.50)
+    TRAINED_RANGE = (1.50, 2.40)
+    ELITE_RANGE = (2.20, 3.50)
+
+    @staticmethod
+    def get_rsi_range(profile: AthleteProfile) -> tuple[float, float]:
+        """Get expected RSI range for athlete profile."""
+        if profile == AthleteProfile.ELDERLY:
+            return RSIBounds.ELDERLY_RANGE
+        elif profile == AthleteProfile.UNTRAINED:
+            return RSIBounds.UNTRAINED_RANGE
+        elif profile == AthleteProfile.RECREATIONAL:
+            return RSIBounds.RECREATIONAL_RANGE
+        elif profile == AthleteProfile.TRAINED:
+            return RSIBounds.TRAINED_RANGE
+        elif profile == AthleteProfile.ELITE:
+            return RSIBounds.ELITE_RANGE
+        return (RSIBounds.MIN_VALID, RSIBounds.MAX_VALID)
+
+    @staticmethod
+    def is_valid(rsi: float) -> bool:
+        """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."""
+
+    # Jump height from flight time: h = g*t²/8
+    # Allow 10% deviation for measurement noise
+    HEIGHT_FLIGHT_TIME_TOLERANCE = 0.10
+
+    # Peak velocity from jump height: v = sqrt(2*g*h)
+    # Allow 15% deviation (velocity harder to detect precisely)
+    VELOCITY_HEIGHT_TOLERANCE = 0.15
+
+    # Countermovement depth to jump height ratio
+    # Typically 0.5-1.2, flag if outside 0.3-1.5
+    DEPTH_HEIGHT_RATIO_MIN = 0.30
+    DEPTH_HEIGHT_RATIO_MAX = 1.50
+
+    # Contact time to countermovement depth ratio
+    # Should be roughly 1.0-1.5 s/m
+    CONTACT_DEPTH_RATIO_MIN = 0.50
+    CONTACT_DEPTH_RATIO_MAX = 2.50
+
+
+# Athlete profile examples with expected metric ranges
+ATHLETE_PROFILES = {
+    "elderly_deconditioned": {
+        "label": "Elderly/Deconditioned (70+, sedentary)",
+        "profile": AthleteProfile.ELDERLY,
+        "expected": {
+            "jump_height_m": (0.10, 0.18),
+            "flight_time_s": (0.14, 0.19),
+            "countermovement_depth_m": (0.12, 0.20),
+            "concentric_duration_s": (0.80, 1.20),
+            "eccentric_duration_s": (0.60, 0.95),
+            "peak_eccentric_velocity_ms": (0.4, 0.7),
+            "peak_concentric_velocity_ms": (1.0, 1.5),
+            "rsi": (0.15, 0.25),
+            "hip_angle_deg": (150, 165),
+            "knee_angle_deg": (155, 170),
+            "ankle_angle_deg": (105, 125),
+        },
+    },
+    "recreational": {
+        "label": "Recreational Athlete (fitness participant, 30-45 yrs)",
+        "profile": AthleteProfile.RECREATIONAL,
+        "expected": {
+            "jump_height_m": (0.35, 0.55),
+            "flight_time_s": (0.53, 0.67),
+            "countermovement_depth_m": (0.28, 0.45),
+            "concentric_duration_s": (0.45, 0.65),
+            "eccentric_duration_s": (0.40, 0.65),
+            "peak_eccentric_velocity_ms": (1.3, 1.9),
+            "peak_concentric_velocity_ms": (2.6, 3.3),
+            "rsi": (0.85, 1.25),
+            "hip_angle_deg": (168, 178),
+            "knee_angle_deg": (170, 182),
+            "ankle_angle_deg": (120, 138),
+        },
+    },
+    "elite_male": {
+        "label": "Elite Male Athlete (college/pro volleyball/basketball)",
+        "profile": AthleteProfile.ELITE,
+        "expected": {
+            "jump_height_m": (0.68, 0.88),
+            "flight_time_s": (0.74, 0.84),
+            "countermovement_depth_m": (0.42, 0.62),
+            "concentric_duration_s": (0.28, 0.42),
+            "eccentric_duration_s": (0.35, 0.55),
+            "peak_eccentric_velocity_ms": (2.1, 3.2),
+            "peak_concentric_velocity_ms": (3.6, 4.2),
+            "rsi": (1.85, 2.80),
+            "hip_angle_deg": (173, 185),
+            "knee_angle_deg": (176, 188),
+            "ankle_angle_deg": (132, 148),
+        },
+    },
+}
+
+
+def estimate_athlete_profile(
+    metrics_dict: MetricsDict, gender: str | None = None
+) -> AthleteProfile:
+    """Estimate athlete profile from metrics.
+
+    Uses jump height as primary classifier:
+    - <0.20m: Elderly
+    - 0.20-0.35m: Untrained
+    - 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
+    """
+    # Support both nested "data" structure and flat structure
+    # Extract with unit suffix as used in serialization, or without suffix (legacy)
+    data = metrics_dict.get("data", metrics_dict)
+    jump_height = data.get("jump_height_m") or data.get("jump_height", 0)
+
+    if jump_height < 0.20:
+        return AthleteProfile.ELDERLY
+    elif jump_height < 0.35:
+        return AthleteProfile.UNTRAINED
+    elif jump_height < 0.65:
+        return AthleteProfile.RECREATIONAL
+    elif jump_height < 0.85:
+        return AthleteProfile.TRAINED
+    else:
+        return AthleteProfile.ELITE

kinemotion/core/__init__.py

@@ -8,7 +8,15 @@ from .filtering import (
     reject_outliers,
     remove_outliers,
 )
+from .model_downloader import get_model_cache_dir, get_model_path
 from .pose import PoseTracker, compute_center_of_mass
+from .pose_landmarks import KINEMOTION_LANDMARKS, LANDMARK_INDICES
+from .quality import (
+    QualityAssessment,
+    QualityIndicators,
+    assess_jump_quality,
+    calculate_position_stability,
+)
 from .smoothing import (
     compute_acceleration_from_derivative,
     compute_velocity,
@@ -16,12 +24,22 @@ from .smoothing import (
     smooth_landmarks,
     smooth_landmarks_advanced,
 )
+from .timing import (
+    NULL_TIMER,
+    NullTimer,
+    PerformanceTimer,
+    Timer,
+)
 from .video_io import VideoProcessor
 
 __all__ = [
     # Pose tracking
     "PoseTracker",
     "compute_center_of_mass",
+    "LANDMARK_INDICES",
+    "KINEMOTION_LANDMARKS",
+    "get_model_path",
+    "get_model_cache_dir",
     # Smoothing
     "smooth_landmarks",
     "smooth_landmarks_advanced",
@@ -35,6 +53,16 @@ __all__ = [
     "reject_outliers",
     "adaptive_smooth_window",
     "bilateral_temporal_filter",
+    # Quality Assessment
+    "QualityAssessment",
+    "QualityIndicators",
+    "assess_jump_quality",
+    "calculate_position_stability",
+    # Timing
+    "PerformanceTimer",
+    "Timer",
+    "NullTimer",
+    "NULL_TIMER",
     # Video I/O
     "VideoProcessor",
 ]

kinemotion/core/auto_tuning.py

@@ -108,10 +108,12 @@ def auto_tune_parameters(
     # =================================================================
 
     # Velocity threshold: Scale inversely with fps
-    # At 30fps, feet move ~2% of frame per frame when "stationary"
-    # At 60fps, feet move ~1% of frame per frame when "stationary"
-    # Formula: threshold = 0.02 * (30 / fps)
-    base_velocity_threshold = 0.02 * (30.0 / fps)
+    # Empirically validated with 45° oblique videos at 60fps:
+    # - Standing (stationary): ~0.001 mean, 0.0011 max
+    # - Flight/drop (moving): ~0.005-0.009
+    # Target threshold: 0.002 at 60fps for clear separation
+    # Formula: threshold = 0.004 * (30 / fps)
+    base_velocity_threshold = 0.004 * (30.0 / fps)
 
     # Min contact frames: Scale with fps to maintain same time duration
     # Goal: ~100ms minimum contact (3 frames @ 30fps, 6 frames @ 60fps)
@@ -166,9 +168,7 @@ def auto_tune_parameters(
     elif quality_preset == QualityPreset.ACCURATE:
         # Accurate: Maximize accuracy, accept slower processing
         velocity_threshold = base_velocity_threshold * 0.5  # More sensitive
-        min_contact_frames = (
-            base_min_contact_frames  # Don't increase (would miss brief)
-        )
+        min_contact_frames = base_min_contact_frames  # Don't increase (would miss brief)
         smoothing_window = min(11, base_smoothing_window + 2 + smoothing_adjustment)
         bilateral_filter = True  # Always use for best accuracy
         detection_confidence = 0.6
@@ -216,6 +216,59 @@ def auto_tune_parameters(
     )
 
 
+def _collect_foot_visibility_and_positions(
+    frame_landmarks: dict[str, tuple[float, float, float]],
+) -> tuple[list[float], list[float]]:
+    """
+    Collect visibility scores and Y positions from foot landmarks.
+
+    Args:
+        frame_landmarks: Landmarks for a single frame
+
+    Returns:
+        Tuple of (visibility_scores, y_positions)
+    """
+    foot_keys = [
+        "left_ankle",
+        "right_ankle",
+        "left_heel",
+        "right_heel",
+        "left_foot_index",
+        "right_foot_index",
+    ]
+
+    frame_vis = []
+    frame_y_positions = []
+
+    for key in foot_keys:
+        if key in frame_landmarks:
+            _, y, vis = frame_landmarks[key]  # x not needed for analysis
+            frame_vis.append(vis)
+            frame_y_positions.append(y)
+
+    return frame_vis, frame_y_positions
+
+
+def _check_stable_period(positions: list[float]) -> bool:
+    """
+    Check if video has a stable period at the start.
+
+    A stable period (low variance in first 30 frames) indicates
+    the subject is standing on an elevated platform before jumping.
+
+    Args:
+        positions: List of average Y positions per frame
+
+    Returns:
+        True if stable period detected, False otherwise
+    """
+    if len(positions) < 30:
+        return False
+
+    first_30_std = float(np.std(positions[:30]))
+    return first_30_std < 0.01  # Very stable = on platform
+
+
 def analyze_video_sample(
     landmarks_sequence: list[dict[str, tuple[float, float, float]] | None],
     fps: float,
@@ -235,35 +288,20 @@ def analyze_video_sample(
     Returns:
         VideoCharacteristics with analyzed properties
     """
-    # Calculate average landmark visibility
     visibilities = []
     positions = []
 
+    # Collect visibility and position data from all frames
     for frame_landmarks in landmarks_sequence:
-        if frame_landmarks:
-            # Collect visibility scores from foot landmarks
-            foot_keys = [
-                "left_ankle",
-                "right_ankle",
-                "left_heel",
-                "right_heel",
-                "left_foot_index",
-                "right_foot_index",
-            ]
-
-            frame_vis = []
-            frame_y_positions = []
-
-            for key in foot_keys:
-                if key in frame_landmarks:
-                    _, y, vis = frame_landmarks[key]  # x not needed for analysis
-                    frame_vis.append(vis)
-                    frame_y_positions.append(y)
-
-            if frame_vis:
-                visibilities.append(float(np.mean(frame_vis)))
-            if frame_y_positions:
-                positions.append(float(np.mean(frame_y_positions)))
+        if not frame_landmarks:
+            continue
+
+        frame_vis, frame_y_positions = _collect_foot_visibility_and_positions(frame_landmarks)
+
+        if frame_vis:
+            visibilities.append(float(np.mean(frame_vis)))
+        if frame_y_positions:
+            positions.append(float(np.mean(frame_y_positions)))
 
     # Compute metrics
     avg_visibility = float(np.mean(visibilities)) if visibilities else 0.5
@@ -273,11 +311,7 @@ def analyze_video_sample(
     tracking_quality = analyze_tracking_quality(avg_visibility)
 
     # Check for stable period (indicates drop jump from elevated platform)
-    # Simple check: do first 30 frames have low variance?
-    has_stable_period = False
-    if len(positions) >= 30:
-        first_30_std = float(np.std(positions[:30]))
-        has_stable_period = first_30_std < 0.01  # Very stable = on platform
+    has_stable_period = _check_stable_period(positions)
 
     return VideoCharacteristics(
         fps=fps,

kinemotion/core/cli_utils.py

@@ -0,0 +1,60 @@
+"""Shared CLI utilities for drop jump and CMJ analysis."""
+
+import glob
+from collections.abc import Callable
+from pathlib import Path
+
+import click
+
+
+def common_output_options(func: Callable) -> Callable:  # type: ignore[type-arg]
+    """Add common output options to CLI command."""
+    func = click.option(
+        "--output",
+        "-o",
+        type=click.Path(),
+        help="Path for debug video output (optional)",
+    )(func)
+    func = click.option(
+        "--json-output",
+        "-j",
+        type=click.Path(),
+        help="Path for JSON metrics output (default: stdout)",
+    )(func)
+    return func
+
+
+def collect_video_files(video_path: tuple[str, ...]) -> list[str]:
+    """Expand glob patterns and collect all video files."""
+    video_files: list[str] = []
+    for pattern in video_path:
+        expanded = glob.glob(pattern)
+        if expanded:
+            video_files.extend(expanded)
+        elif Path(pattern).exists():
+            video_files.append(pattern)
+        else:
+            click.echo(f"Warning: No files found for pattern: {pattern}", err=True)
+    return video_files
+
+
+def generate_batch_output_paths(
+    video_path: str, output_dir: str | None, json_output_dir: str | None
+) -> tuple[str | None, str | None]:
+    """Generate output paths for debug video and JSON in batch mode.
+
+    Args:
+        video_path: Path to source video
+        output_dir: Directory for debug video output (optional)
+        json_output_dir: Directory for JSON metrics output (optional)
+
+    Returns:
+        Tuple of (debug_video_path, json_output_path)
+    """
+    out_path = None
+    json_path = None
+    if output_dir:
+        out_path = str(Path(output_dir) / f"{Path(video_path).stem}_debug.mp4")
+    if json_output_dir:
+        json_path = str(Path(json_output_dir) / f"{Path(video_path).stem}.json")
+    return out_path, json_path