kinemotion 0.10.11__py3-none-any.whl → 0.11.0__py3-none-any.whl

{kinemotion-0.10.11.dist-info → kinemotion-0.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.10.11
+Version: 0.11.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
@@ -34,30 +34,45 @@ Description-Content-Type: text/markdown
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Type checked with pyright](https://img.shields.io/badge/type%20checked-pyright-blue.svg)](https://github.com/microsoft/pyright)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=feniix_kinemotion&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=feniix_kinemotion)
 
-A video-based kinematic analysis tool for athletic performance. Analyzes side-view drop-jump videos to estimate key performance metrics: ground contact time, flight time, and jump height. Uses MediaPipe pose tracking and advanced kinematics.
+A video-based kinematic analysis tool for athletic performance. Analyzes vertical jump videos to estimate key performance metrics using MediaPipe pose tracking and advanced kinematics.
+
+**Supported jump types:**
+
+- **Drop Jump**: Ground contact time, flight time, reactive strength index
+- **Counter Movement Jump (CMJ)**: Jump height, flight time, countermovement depth, triple extension biomechanics
 
 ## Features
 
+### Core Features
+
 - **Automatic pose tracking** using MediaPipe Pose landmarks
-- **Ground contact detection** based on foot velocity and position
 - **Derivative-based velocity** - smooth velocity calculation from position trajectory
 - **Trajectory curvature analysis** - acceleration patterns for refined event detection
-- **Sub-frame interpolation** - precise timing beyond frame boundaries for improved accuracy
-- **Automatic drop jump detection** - identifies box → drop → landing → jump phases
-- **Kinematic calculations** for jump metrics:
-  - Ground contact time (ms)
-  - Flight time (ms)
-  - Jump height (m) - with optional calibration using drop box height
-- **Calibrated measurements** - use known drop height for theoretically improved accuracy (⚠️ accuracy claims unvalidated)
+- **Sub-frame interpolation** - precise timing beyond frame boundaries
+- **Intelligent auto-tuning** - automatic parameter optimization based on video characteristics
 - **JSON output** for easy integration with other tools
-- **Optional debug video** with visual overlays showing contact states and landmarks
-- **Batch processing** - CLI and Python API for parallel processing of multiple videos
-- **Python library API** - use kinemotion programmatically in your own code
-- **CSV export** - aggregated results for research and analysis
-- **Configurable parameters** for smoothing, thresholds, and detection
+- **Debug video overlays** with visual analysis
+- **Batch processing** - CLI and Python API for parallel processing
+- **Python library API** - use kinemotion programmatically
+- **CSV export** - aggregated results for research
 
-**Note**: Drop jump analysis uses foot-based tracking with fixed velocity thresholds. Center of mass (CoM) tracking and adaptive thresholding (available in `core/` modules) require longer videos (~5+ seconds) with a 3-second standing baseline, making them unsuitable for typical drop jump videos (~3 seconds). These features may be available in future jump types like CMJ (countermovement jump).
+### Drop Jump Analysis
+
+- **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)
+- **Reactive strength index** calculations
+
+### Counter Movement Jump (CMJ) Analysis
+
+- **Backward search algorithm** - robust phase detection from peak height
+- **Flight time method** - force plate standard (h = g×t²/8)
+- **Triple extension tracking** - ankle, knee, hip joint angles
+- **Skeleton overlay** - biomechanical visualization
+- **Metrics**: Jump height, flight time, countermovement depth, eccentric/concentric durations
+- **Validated accuracy**: 50.6cm jump (±1 frame precision)
 
 ## Validation Status
 
@@ -103,133 +118,77 @@ This will install all dependencies and make the `kinemotion` command available.
 
 ## Usage
 
-**NEW:** Kinemotion now features **intelligent auto-tuning**! Just specify your drop box height and the tool automatically optimizes all parameters based on video frame rate and tracking quality.
+Kinemotion supports two jump types with intelligent auto-tuning that automatically optimizes parameters based on video characteristics.
 
-### Basic Analysis
+### Drop Jump Analysis
 
-Analyze a video with automatic parameter selection:
+Analyzes reactive strength and ground contact time:
 
 ```bash
 # Drop-height is REQUIRED for accurate calibration
 kinemotion dropjump-analyze video.mp4 --drop-height 0.40
 ```
 
-### Save Metrics to File
-
-```bash
-kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --json-output metrics.json
-```
+### Counter Movement Jump (CMJ) Analysis
 
-### Generate Debug Video
-
-Create an annotated video showing pose tracking and contact detection:
+Analyzes jump height and biomechanics:
 
 ```bash
-kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --output debug.mp4
-```
-
-### Complete Analysis
+# No drop height needed (floor level)
+kinemotion cmj-analyze video.mp4
 
-With all outputs:
-
-```bash
-kinemotion dropjump-analyze video.mp4 \
-  --drop-height 0.40 \
-  --output debug.mp4 \
-  --json-output results.json
+# With triple extension visualization
+kinemotion cmj-analyze video.mp4 --output debug.mp4
 ```
 
-### Quality Presets
-
-Choose analysis quality (automatically adjusts all parameters):
+### Common Options (Both Jump Types)
 
 ```bash
-# Fast analysis (quick, less precise - good for batch processing)
-kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --quality fast
+# Save metrics to JSON
+kinemotion cmj-analyze video.mp4 --json-output results.json
 
-# Balanced (default - best for most use cases)
-kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --quality balanced
+# Generate debug video
+kinemotion cmj-analyze video.mp4 --output debug.mp4
 
-# Accurate (research-grade, slower - maximum precision)
-kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --quality accurate
+# Complete analysis with all outputs
+kinemotion cmj-analyze video.mp4 \
+  --output debug.mp4 \
+  --json-output results.json \
+  --verbose
 ```
 
-### See Auto-Selected Parameters
-
-View what parameters were automatically selected:
+### Quality Presets
 
 ```bash
-kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --verbose
-```
+# Fast (50% faster, good for batch)
+kinemotion cmj-analyze video.mp4 --quality fast
 
-### Expert Mode (Advanced Users)
+# Balanced (default)
+kinemotion cmj-analyze video.mp4 --quality balanced
 
-Override auto-tuned parameters if needed:
-
-```bash
-# Manual parameter override (rarely needed)
-kinemotion dropjump-analyze video.mp4 \
-  --drop-height 0.40 \
-  --expert \
-  --smoothing-window 7 \
-  --velocity-threshold 0.015
+# Accurate (research-grade)
+kinemotion cmj-analyze video.mp4 --quality accurate --verbose
 ```
 
 ### Batch Processing
 
-Process multiple videos in parallel from the command line:
+Process multiple videos in parallel:
 
 ```bash
-# Process multiple videos with glob pattern
+# Drop jumps
 kinemotion dropjump-analyze videos/*.mp4 --batch --drop-height 0.40 --workers 4
 
-# Save all results to directories
-kinemotion dropjump-analyze videos/*.mp4 --batch --drop-height 0.40 \
+# CMJ (no drop height needed)
+kinemotion cmj-analyze videos/*.mp4 --batch --workers 4 \
   --json-output-dir results/ \
-  --output-dir debug_videos/ \
   --csv-summary summary.csv
-
-# Multiple explicit paths (batch mode auto-enabled)
-kinemotion dropjump-analyze video1.mp4 video2.mp4 video3.mp4 --drop-height 0.40
-```
-
-**Batch options:**
-
-- `--batch`: Explicitly enable batch mode
-- `--workers <int>`: Number of parallel workers (default: 4)
-- `--output-dir <path>`: Directory for debug videos (auto-named per video)
-- `--json-output-dir <path>`: Directory for JSON metrics (auto-named per video)
-- `--csv-summary <path>`: Export aggregated results to CSV
-
-**Output example:**
-
-```text
-Batch processing 10 videos with 4 workers
-======================================================================
-
-Processing videos...
-[1/10] ✓ athlete1.mp4 (2.3s)
-[2/10] ✓ athlete2.mp4 (2.1s)
-[3/10] ✗ athlete3.mp4 (0.5s)
-    Error: No frames could be processed
-
-======================================================================
-BATCH PROCESSING SUMMARY
-======================================================================
-Total videos: 10
-Successful: 9
-Failed: 1
-
-Average ground contact time: 245.3 ms
-Average flight time: 523.7 ms
-Average jump height: 0.352 m (35.2 cm)
 ```
 
 ## Python API
 
-Use kinemotion as a library in your Python code for automated pipelines and custom analysis:
+Use kinemotion as a library for automated pipelines and custom analysis.
 
-### Single Video Processing
+### Drop Jump API
 
 ```python
 from kinemotion import process_video
@@ -251,43 +210,53 @@ print(f"Flight time: {metrics.flight_time * 1000:.1f} ms")
 ### Bulk Video Processing
 
 ```python
+# Drop jump bulk processing
 from kinemotion import VideoConfig, process_videos_bulk
 
-# Configure multiple videos
 configs = [
     VideoConfig("video1.mp4", drop_height=0.40),
     VideoConfig("video2.mp4", drop_height=0.30, quality="accurate"),
-    VideoConfig("video3.mp4", drop_height=0.50, output_video="debug3.mp4"),
 ]
 
-# Process in parallel with 4 workers
 results = process_videos_bulk(configs, max_workers=4)
 
-# Check results
-for result in results:
+# CMJ bulk processing
+from kinemotion import CMJVideoConfig, process_cmj_videos_bulk
+
+cmj_configs = [
+    CMJVideoConfig("cmj1.mp4"),
+    CMJVideoConfig("cmj2.mp4", quality="accurate"),
+]
+
+cmj_results = process_cmj_videos_bulk(cmj_configs, max_workers=4)
+
+for result in cmj_results:
     if result.success:
-        print(f"✓ {result.video_path}: {result.metrics.jump_height:.3f} m")
-    else:
-        print(f"✗ {result.video_path}: {result.error}")
+        print(f"{result.video_path}: {result.metrics.jump_height*100:.1f}cm")
 ```
 
-### Export Results to CSV
+See `examples/bulk/README.md` for comprehensive API documentation.
+
+### CMJ-Specific Features
 
 ```python
-import csv
-from pathlib import Path
-from kinemotion import VideoConfig, process_videos_bulk
+# Triple extension angles available in metrics
+metrics = process_cmj_video("video.mp4", output_video="debug.mp4")
 
-# Process directory of videos
-video_dir = Path("athlete_videos")
-configs = [
-    VideoConfig(str(v), drop_height=0.40, quality="balanced")
-    for v in video_dir.glob("*.mp4")
-]
+# Debug video shows:
+# - Skeleton overlay (foot→shin→femur→trunk)
+# - Joint angles (ankle, knee, hip, trunk)
+# - Phase-coded visualization
+```
 
-results = process_videos_bulk(configs, max_workers=4)
+### CSV Export Example
+
+```python
+# See examples/bulk/ for complete CSV export examples
+from kinemotion import process_cmj_video
+import csv
 
-# Export to CSV
+# ... process videos ...
 with open("results.csv", "w", newline="") as f:
     writer = csv.writer(f)
     writer.writerow(["Video", "GCT (ms)", "Flight (ms)", "Jump (m)"])

kinemotion-0.11.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+kinemotion/__init__.py,sha256=REBC9wrwYC_grvCS00qEOyign65Zc1sc-5buLpyqQxA,654
+kinemotion/api.py,sha256=HYd8OnCZ9eJq7wn38dFVta5llTjqB9P0wKEwXPAXu6M,31666
+kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
+kinemotion/cmj/__init__.py,sha256=Ynv0-Oco4I3Y1Ubj25m3h9h2XFqeNwpAewXmAYOmwfU,127
+kinemotion/cmj/analysis.py,sha256=uzUouxeCE3H5dad_AQ8PhtpgVC8DfPE32AMDqihD82o,19887
+kinemotion/cmj/cli.py,sha256=kyPJpxvLZGfzdqv4FGzQVNmR2uUSOg3a6_I0d1VszVw,20874
+kinemotion/cmj/debug_overlay.py,sha256=TVDrZ16TJClftM_zhkrCzBLMs87SfYDa8H-eqfzQJ4c,17976
+kinemotion/cmj/joint_angles.py,sha256=8ucpDGPvbt4iX3tx9eVxJEUv0laTm2Y58_--VzJCogE,9113
+kinemotion/cmj/kinematics.py,sha256=Xl_PlC2OqMoA-zOc3SRB_GqI0AgLlJol5FTPe5J_qLc,7573
+kinemotion/core/__init__.py,sha256=3yzDhb5PekDNjydqrs8aWGneUGJBt-lB0SoB_Y2FXqU,1010
+kinemotion/core/auto_tuning.py,sha256=cvmxUI-CbahpOJQtR2r5jOx4Q6yKPe3DO1o15hOQIdw,10508
+kinemotion/core/filtering.py,sha256=f-m-aA59e4WqE6u-9MA51wssu7rI-Y_7n1cG8IWdeRQ,11241
+kinemotion/core/pose.py,sha256=Wfd1RR-2ZznYpWeQUbySwcV3mvReqn8n3XO6S7pGq4M,8390
+kinemotion/core/smoothing.py,sha256=FON4qKtsSp1-03GnJrDkEUAePaACn4QPMJF0eTIYqR0,12925
+kinemotion/core/video_io.py,sha256=z8Z0qbNaKbcdB40KnbNOBMzab3BbgnhBxp-mUBYeXgM,6577
+kinemotion/dropjump/__init__.py,sha256=yc1XiZ9vfo5h_n7PKVSiX2TTgaIfGL7Y7SkQtiDZj_E,838
+kinemotion/dropjump/analysis.py,sha256=HfJt2t9IsMBiBUz7apIzdxbRH9QqzlFnDVVWcKhU3ow,23291
+kinemotion/dropjump/cli.py,sha256=zo23qoYSpC_2BcScy-JOilcGcWGM0j3Xv0lpO0_n0wk,27975
+kinemotion/dropjump/debug_overlay.py,sha256=GMo-jCl5OPIv82uPxDbBVI7CsAMwATTvxZMeWfs8k8M,8701
+kinemotion/dropjump/kinematics.py,sha256=RM_O8Kdc6aEiPIu_99N4cu-4EhYSQxtBGASJF_dmQaU,19081
+kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kinemotion-0.11.0.dist-info/METADATA,sha256=JaV-num_wEFgMB_tl3sxOJmUGl0FddtS5bkfQmGH3Gc,18990
+kinemotion-0.11.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kinemotion-0.11.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.11.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.11.0.dist-info/RECORD,,

kinemotion-0.10.11.dist-info/RECORD

@@ -1,20 +0,0 @@
-kinemotion/__init__.py,sha256=Z85xg29NA-r4IjrSbAkJpMFigyxACFGUb-37AiMp6YY,350
-kinemotion/api.py,sha256=2MsiHsmmxfpvhHIbDXcZpvsCLROKi4MV8LQpKu2r_a8,20078
-kinemotion/cli.py,sha256=2IFA2_TE9a5zBtmGVzv5SnX39w7yPuBlw42dL7ca25U,402
-kinemotion/core/__init__.py,sha256=3yzDhb5PekDNjydqrs8aWGneUGJBt-lB0SoB_Y2FXqU,1010
-kinemotion/core/auto_tuning.py,sha256=cvmxUI-CbahpOJQtR2r5jOx4Q6yKPe3DO1o15hOQIdw,10508
-kinemotion/core/filtering.py,sha256=f-m-aA59e4WqE6u-9MA51wssu7rI-Y_7n1cG8IWdeRQ,11241
-kinemotion/core/pose.py,sha256=Wfd1RR-2ZznYpWeQUbySwcV3mvReqn8n3XO6S7pGq4M,8390
-kinemotion/core/smoothing.py,sha256=FON4qKtsSp1-03GnJrDkEUAePaACn4QPMJF0eTIYqR0,12925
-kinemotion/core/video_io.py,sha256=z8Z0qbNaKbcdB40KnbNOBMzab3BbgnhBxp-mUBYeXgM,6577
-kinemotion/dropjump/__init__.py,sha256=yc1XiZ9vfo5h_n7PKVSiX2TTgaIfGL7Y7SkQtiDZj_E,838
-kinemotion/dropjump/analysis.py,sha256=HfJt2t9IsMBiBUz7apIzdxbRH9QqzlFnDVVWcKhU3ow,23291
-kinemotion/dropjump/cli.py,sha256=zo23qoYSpC_2BcScy-JOilcGcWGM0j3Xv0lpO0_n0wk,27975
-kinemotion/dropjump/debug_overlay.py,sha256=GMo-jCl5OPIv82uPxDbBVI7CsAMwATTvxZMeWfs8k8M,8701
-kinemotion/dropjump/kinematics.py,sha256=RM_O8Kdc6aEiPIu_99N4cu-4EhYSQxtBGASJF_dmQaU,19081
-kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.10.11.dist-info/METADATA,sha256=9HZYBmm4SP6ty8z4CXqWj4J9uEPRcVS9kdnVmZwXRc4,20363
-kinemotion-0.10.11.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.10.11.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.10.11.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.10.11.dist-info/RECORD,,