kinemotion 0.28.0__py3-none-any.whl → 0.29.1__py3-none-any.whl

kinemotion/core/cmj_validation_bounds.py

@@ -0,0 +1,380 @@
+"""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 dataclasses import dataclass
+from enum import Enum
+
+
+class AthleteProfile(Enum):
+    """Athlete performance categories for metric bounds."""
+
+    ELDERLY = "elderly"  # 70+, deconditioned
+    UNTRAINED = "untrained"  # Sedentary, no training
+    RECREATIONAL = "recreational"  # Fitness class, moderate activity
+    TRAINED = "trained"  # Regular athlete, 3-5 years training
+    ELITE = "elite"  # Competitive athlete, college/professional level
+
+
+@dataclass
+class MetricBounds:
+    """Physiological bounds for a single metric.
+
+    Attributes:
+        absolute_min: Absolute minimum value (error threshold)
+        practical_min: Practical minimum for weakest athletes
+        recreational_min: Minimum for recreational athletes
+        recreational_max: Maximum for recreational athletes
+        elite_min: Minimum for elite athletes
+        elite_max: Maximum for elite athletes
+        absolute_max: Absolute maximum value (error threshold)
+        unit: Unit of measurement (e.g., "m", "s", "m/s", "degrees")
+    """
+
+    absolute_min: float
+    practical_min: float
+    recreational_min: float
+    recreational_max: float
+    elite_min: float
+    elite_max: float
+    absolute_max: float
+    unit: str
+
+    def contains(self, value: float, profile: AthleteProfile) -> bool:
+        """Check if value is within bounds for athlete profile."""
+        if profile == AthleteProfile.ELDERLY:
+            return self.practical_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.UNTRAINED:
+            return self.practical_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.RECREATIONAL:
+            return self.recreational_min <= value <= self.recreational_max
+        elif profile == AthleteProfile.TRAINED:
+            # Trained athletes: midpoint between recreational and elite
+            trained_min = (self.recreational_min + self.elite_min) / 2
+            trained_max = (self.recreational_max + self.elite_max) / 2
+            return trained_min <= value <= trained_max
+        elif profile == AthleteProfile.ELITE:
+            return self.elite_min <= value <= self.elite_max
+        return False
+
+    def is_physically_possible(self, value: float) -> bool:
+        """Check if value is within absolute physiological limits."""
+        return self.absolute_min <= value <= self.absolute_max
+
+
+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: dict) -> 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
+    """
+    jump_height = metrics_dict.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-0.28.0.dist-info → kinemotion-0.29.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.28.0
+Version: 0.29.1
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion
@@ -67,7 +67,7 @@ Description-Content-Type: text/markdown
 
 - **Ground contact detection** based on foot velocity and position
 - **Automatic drop jump detection** - identifies box → drop → landing → jump phases
-- **Metrics**: Ground contact time, flight time, jump height (with drop height calibration)
+- **Metrics**: Ground contact time, flight time, jump height (calculated from flight time)
 - **Reactive strength index** calculations
 
 ### Counter Movement Jump (CMJ) Analysis
@@ -267,27 +267,33 @@ kinemotion cmj-analyze videos/*.mp4 --batch --workers 4 \
   --csv-summary summary.csv
 ```
 
-### Quality Indicators & Confidence Scores
+### Quality Assessment
 
-All analysis outputs include automatic quality assessment to help you know when to trust results:
+All analysis outputs include automatic quality assessment in the metadata section to help you know when to trust results:
 
 ```json
 {
-  "jump_height_m": 0.352,
-  "flight_time_s": 0.534,
-  "confidence": "high",
-  "quality_score": 87.3,
-  "quality_indicators": {
-    "avg_visibility": 0.89,
-    "min_visibility": 0.82,
-    "tracking_stable": true,
-    "phase_detection_clear": true,
-    "outliers_detected": 2,
-    "outlier_percentage": 1.5,
-    "position_variance": 0.0008,
-    "fps": 60.0
+  "data": {
+    "jump_height_m": 0.352,
+    "flight_time_ms": 534.2
   },
-  "warnings": []
+  "metadata": {
+    "quality": {
+      "confidence": "high",
+      "quality_score": 87.3,
+      "quality_indicators": {
+        "avg_visibility": 0.89,
+        "min_visibility": 0.82,
+        "tracking_stable": true,
+        "phase_detection_clear": true,
+        "outliers_detected": 2,
+        "outlier_percentage": 1.5,
+        "position_variance": 0.0008,
+        "fps": 60.0
+      },
+      "warnings": []
+    }
+  }
 }
 ```
 
@@ -310,9 +316,9 @@ All analysis outputs include automatic quality assessment to help you know when
 ```python
 # Only use high-confidence results
 metrics = process_cmj_video("video.mp4")
-if metrics.quality_assessment.confidence == "high":
+if metrics.quality_assessment is not None and metrics.quality_assessment.confidence == "high":
     print(f"Reliable jump height: {metrics.jump_height:.3f}m")
-else:
+elif metrics.quality_assessment is not None:
     print(f"Low quality - warnings: {metrics.quality_assessment.warnings}")
 ```
 
@@ -414,14 +420,9 @@ Kinemotion automatically optimizes parameters based on your video:
 - **Quality-based adjustments**: Adapts smoothing based on MediaPipe tracking confidence
 - **Always enabled**: Outlier rejection, curvature analysis, drop start detection
 
-### Required Parameters
+### Parameters
 
-- `--drop-height <float>` **\[REQUIRED\]**
-  - Height of drop box/platform in meters (e.g., 0.40 for 40cm)
-  - Used for accurate calibration of jump height measurements
-  - Measure your box height accurately for best results
-
-### Optional Parameters
+All parameters are optional. Kinemotion uses intelligent auto-tuning to select optimal settings based on video characteristics.
 
 - `--quality [fast|balanced|accurate]` (default: balanced)
 
@@ -460,32 +461,95 @@ For advanced users who need manual control:
 
 ## Output Format
 
-### JSON Metrics
+### Drop Jump JSON Output
 
 ```json
 {
-  "ground_contact_time_ms": 245.67,
-  "flight_time_ms": 456.78,
-  "jump_height_m": 0.339,
-  "jump_height_kinematic_m": 0.256,
-  "jump_height_trajectory_normalized": 0.0845,
-  "contact_start_frame": 45,
-  "contact_end_frame": 67,
-  "flight_start_frame": 68,
-  "flight_end_frame": 95,
-  "peak_height_frame": 82
+  "data": {
+    "ground_contact_time_ms": 245.67,
+    "flight_time_ms": 456.78,
+    "jump_height_m": 0.339,
+    "jump_height_kinematic_m": 0.339,
+    "jump_height_trajectory_normalized": 0.0845,
+    "contact_start_frame": 45,
+    "contact_end_frame": 67,
+    "flight_start_frame": 68,
+    "flight_end_frame": 95,
+    "peak_height_frame": 82,
+    "contact_start_frame_precise": 45.234,
+    "contact_end_frame_precise": 67.891,
+    "flight_start_frame_precise": 68.123,
+    "flight_end_frame_precise": 94.567
+  },
+  "metadata": {
+    "quality": { },
+    "processing_info": { }
+  }
 }
 ```
 
-**Fields**:
+**Data Fields**:
 
-- `jump_height_m`: Primary jump height measurement (calibrated if --drop-height provided, otherwise corrected kinematic)
-- `jump_height_kinematic_m`: Kinematic estimate from flight time: h = (g × t²) / 8
+- `ground_contact_time_ms`: Duration of ground contact phase in milliseconds
+- `flight_time_ms`: Duration of flight phase in milliseconds
+- `jump_height_m`: Jump height calculated from flight time: h = g × t² / 8
+- `jump_height_kinematic_m`: Kinematic estimate (same as `jump_height_m`)
 - `jump_height_trajectory_normalized`: Position-based measurement in normalized coordinates (0-1 range)
-- `contact_start_frame_precise`, `contact_end_frame_precise`: Sub-frame timing (fractional frames)
-- `flight_start_frame_precise`, `flight_end_frame_precise`: Sub-frame timing (fractional frames)
+- `contact_start_frame`: Frame index where contact begins (integer, for visualization)
+- `contact_end_frame`: Frame index where contact ends (integer, for visualization)
+- `flight_start_frame`: Frame index where flight begins (integer, for visualization)
+- `flight_end_frame`: Frame index where flight ends (integer, for visualization)
+- `peak_height_frame`: Frame index at maximum jump height (integer, for visualization)
+- `contact_start_frame_precise`: Sub-frame precise timing for contact start (fractional, for calculations)
+- `contact_end_frame_precise`: Sub-frame precise timing for contact end (fractional, for calculations)
+- `flight_start_frame_precise`: Sub-frame precise timing for flight start (fractional, for calculations)
+- `flight_end_frame_precise`: Sub-frame precise timing for flight end (fractional, for calculations)
+
+**Note**: Integer frame indices are provided for visualization in debug videos. Precise fractional frames are used for all timing calculations and provide sub-frame accuracy (±10ms at 30fps).
+
+### CMJ JSON Output
+
+```json
+{
+  "data": {
+    "jump_height_m": 0.352,
+    "flight_time_ms": 534.2,
+    "countermovement_depth_m": 0.285,
+    "eccentric_duration_ms": 612.5,
+    "concentric_duration_ms": 321.8,
+    "total_movement_time_ms": 934.3,
+    "peak_eccentric_velocity_m_s": -2.145,
+    "peak_concentric_velocity_m_s": 3.789,
+    "transition_time_ms": 125.4,
+    "standing_start_frame": 12.5,
+    "lowest_point_frame": 45.2,
+    "takeoff_frame": 67.8,
+    "landing_frame": 102.3,
+    "tracking_method": "foot"
+  },
+  "metadata": {
+    "quality": { },
+    "processing_info": { }
+  }
+}
+```
 
-**Note**: Integer frame indices (e.g., `contact_start_frame`) are provided for visualization in debug videos. Precise fractional frames (e.g., `contact_start_frame_precise`) are used for all timing calculations and provide higher accuracy.
+**Data Fields**:
+
+- `jump_height_m`: Jump height calculated from flight time: h = g × t² / 8
+- `flight_time_ms`: Duration of flight phase in milliseconds
+- `countermovement_depth_m`: Maximum downward displacement during eccentric (descent) phase
+- `eccentric_duration_ms`: Time from start of countermovement to lowest point
+- `concentric_duration_ms`: Time from lowest point to takeoff
+- `total_movement_time_ms`: Total time from countermovement start to takeoff
+- `peak_eccentric_velocity_m_s`: Maximum downward velocity during descent (negative value)
+- `peak_concentric_velocity_m_s`: Maximum upward velocity during propulsion (positive value)
+- `transition_time_ms`: Duration at lowest point (amortization phase between descent and propulsion)
+- `standing_start_frame`: Frame where standing phase ends and countermovement begins
+- `lowest_point_frame`: Frame at the lowest point of the countermovement
+- `takeoff_frame`: Frame where athlete leaves ground
+- `landing_frame`: Frame where athlete lands after jump
+- `tracking_method`: Tracking method used - "foot" (foot landmarks) or "com" (center of mass estimation)
 
 ### Debug Video
 
@@ -542,8 +606,7 @@ The debug video includes:
 
 **Solutions**:
 
-1. **Use calibration**: For drop jumps, add `--drop-height` parameter with box height in meters (e.g., `--drop-height 0.40`)
-   - Theoretically improves accuracy (⚠️ unvalidated)
+1. **Check video quality**: Ensure video frame rate is adequate (30fps or higher recommended)
 1. **Verify flight time detection**: Check `flight_start_frame` and `flight_end_frame` in JSON
 1. **Compare measurements**: JSON output includes both `jump_height_m` (primary) and `jump_height_kinematic_m` (kinematic-only)
 1. **Check for drop jump detection**: If doing a drop jump, ensure first phase is elevated enough (>5% of frame height)
@@ -581,8 +644,7 @@ The debug video includes:
 1. **Metric Calculation**:
    - Ground contact time = contact phase duration (using fractional frames)
    - Flight time = flight phase duration (using fractional frames)
-   - Jump height = calibrated position-based measurement (if --drop-height provided)
-   - Fallback: kinematic estimate (g × t²) / 8 with optional empirical correction factor (⚠️ unvalidated)
+   - Jump height = kinematic estimate from flight time: (g × t²) / 8
 
 ## Development
 
@@ -593,7 +655,7 @@ This project enforces strict code quality standards:
 - **Type safety**: Full pyright strict mode compliance with complete type annotations
 - **Linting**: Comprehensive ruff checks (pycodestyle, pyflakes, isort, pep8-naming, etc.)
 - **Formatting**: Black code style
-- **Testing**: pytest with 61 unit tests
+- **Testing**: pytest with 261 comprehensive tests (74.27% coverage)
 - **PEP 561 compliant**: Includes py.typed marker for type checking support
 
 ### Development Commands

{kinemotion-0.28.0.dist-info → kinemotion-0.29.1.dist-info}/RECORD

@@ -1,15 +1,17 @@
-kinemotion/__init__.py,sha256=vAEIg-oDX1ZkQMnWgXd__tekaA5KUcEvdJSAGWS8VUY,722
+kinemotion/__init__.py,sha256=sxdDOekOrIgjxm842gy-6zfq7OWmGl9ShJtXCm4JI7c,723
 kinemotion/api.py,sha256=tbkjXsfe0N0Bmik6XRIOYM7Nom4QqeQJSpDx7IoiuSA,38177
 kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
 kinemotion/cmj/__init__.py,sha256=Ynv0-Oco4I3Y1Ubj25m3h9h2XFqeNwpAewXmAYOmwfU,127
-kinemotion/cmj/analysis.py,sha256=4HYGn4VDIB6oExAees-VcPfpNgWOltpgwjyNTU7YAb4,18263
+kinemotion/cmj/analysis.py,sha256=il7-sfM89ZetxLhmw9boViaP4E8Y3mlS_XI-B5txmMs,19795
 kinemotion/cmj/cli.py,sha256=12FEfWrseG4kCUbgHHdBPkWp6zzVQ0VAzfgNJotArmM,10792
 kinemotion/cmj/debug_overlay.py,sha256=D-y2FQKI01KY0WXFKTKg6p9Qj3AkXCE7xjau3Ais080,15886
-kinemotion/cmj/joint_angles.py,sha256=8ucpDGPvbt4iX3tx9eVxJEUv0laTm2Y58_--VzJCogE,9113
+kinemotion/cmj/joint_angles.py,sha256=HmheIEiKcQz39cRezk4h-htorOhGNPsqKIR9RsAEKts,9960
 kinemotion/cmj/kinematics.py,sha256=-iBFg2AkQR4LaThCQzO09fx6qJed27ZfMDQJgE7Si4k,9772
 kinemotion/core/__init__.py,sha256=HsqolRa60cW3vrG8F9Lvr9WvWcs5hCmsTzSgo7imi-4,1278
 kinemotion/core/auto_tuning.py,sha256=j6cul_qC6k0XyryCG93C1AWH2MKPj3UBMzuX02xaqfI,11235
 kinemotion/core/cli_utils.py,sha256=Pq1JF7yvK1YbH0tOUWKjplthCbWsJQt4Lv7esPYH4FM,7254
+kinemotion/core/cmj_metrics_validator.py,sha256=Jfh8oxhxz5BCBIPdeMRHa60tZsliDkN10RiLQYkmck4,27262
+kinemotion/core/cmj_validation_bounds.py,sha256=WBMuJx6ewb-rYan3xmQu32m7bs9h8J5isa4LduZuZkI,13507
 kinemotion/core/debug_overlay_utils.py,sha256=TyUb5okv5qw8oeaX3jsUO_kpwf1NnaHEAOTm-8LwTno,4587
 kinemotion/core/filtering.py,sha256=f-m-aA59e4WqE6u-9MA51wssu7rI-Y_7n1cG8IWdeRQ,11241
 kinemotion/core/formatting.py,sha256=G_3eqgOtym9RFOZVEwCxye4A2cyrmgvtQ214vIshowU,2480
@@ -24,8 +26,8 @@ kinemotion/dropjump/cli.py,sha256=ZyroaYPwz8TgfL39Wcaj6m68Awl6lYXC75ttaflU-c0,16
 kinemotion/dropjump/debug_overlay.py,sha256=LkPw6ucb7beoYWS4L-Lvjs1KLCm5wAWDAfiznUeV2IQ,5668
 kinemotion/dropjump/kinematics.py,sha256=Yr3G7AQwtYy1dxyeOAYfqqgd4pzoZwWQAhZzxI5RbnE,16658
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.28.0.dist-info/METADATA,sha256=RIUN7r__qFVHSNzj2CglERzONmcmLiIYrDZLkpztZu8,23244
-kinemotion-0.28.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.28.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.28.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.28.0.dist-info/RECORD,,
+kinemotion-0.29.1.dist-info/METADATA,sha256=fOQmDQ0rv47YYfH_wXRU6wUDk2gDnSfS__nHTOlTKXU,25810
+kinemotion-0.29.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kinemotion-0.29.1.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.29.1.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.29.1.dist-info/RECORD,,