kinemotion 0.27.0__py3-none-any.whl → 0.29.0__py3-none-any.whl

{kinemotion-0.27.0.dist-info → kinemotion-0.29.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.27.0
+Version: 0.29.0
 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.27.0.dist-info → kinemotion-0.29.0.dist-info}/RECORD

@@ -1,17 +1,20 @@
-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/kinematics.py,sha256=4-YDbCq9e7JlyGl_R3W1tvo8iAkXhjNla9J5yevUSRk,9165
+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
 kinemotion/core/metadata.py,sha256=PyGHL6sx7Hj21lyorg2VsWP9BGTj_y_-wWU6eKCEfJo,6817
 kinemotion/core/pose.py,sha256=ztemdZ_ysVVK3gbXabm8qS_dr1VfJX9KZjmcO-Z-iNE,8532
 kinemotion/core/quality.py,sha256=OC9nuf5IrQ9xURf3eA50VoNWOqkGwbjJpS90q2FDQzA,13082
@@ -21,10 +24,10 @@ kinemotion/dropjump/__init__.py,sha256=yc1XiZ9vfo5h_n7PKVSiX2TTgaIfGL7Y7SkQtiDZj
 kinemotion/dropjump/analysis.py,sha256=BQ5NqSPNJjFQOb-W4bXSLvjCgWd-nvqx5NElyeqZJC4,29067
 kinemotion/dropjump/cli.py,sha256=ZyroaYPwz8TgfL39Wcaj6m68Awl6lYXC75ttaflU-c0,16236
 kinemotion/dropjump/debug_overlay.py,sha256=LkPw6ucb7beoYWS4L-Lvjs1KLCm5wAWDAfiznUeV2IQ,5668
-kinemotion/dropjump/kinematics.py,sha256=Ig9TqXr-OEUm19gqIvUjQkqrCuw1csYt1f4ZfwG8oGc,17464
+kinemotion/dropjump/kinematics.py,sha256=Yr3G7AQwtYy1dxyeOAYfqqgd4pzoZwWQAhZzxI5RbnE,16658
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.27.0.dist-info/METADATA,sha256=YhRgdOUcZ_mIgOgj0wJBdTW_msbUPlyZaCx7ND0dVTI,23244
-kinemotion-0.27.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.27.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.27.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.27.0.dist-info/RECORD,,
+kinemotion-0.29.0.dist-info/METADATA,sha256=ZAHFxbzTJXP_okBnSjd8zqqlZrKmTr89pny0ktv2H-0,25810
+kinemotion-0.29.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kinemotion-0.29.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.29.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.29.0.dist-info/RECORD,,