kinemotion 0.23.0__tar.gz → 0.25.0__tar.gz

kinemotion-0.25.0/.gitattributes

@@ -0,0 +1,41 @@
+docs/research/thirdparty/pdfs/running-biomechanics/2024_Bramah_Sprint-Mechanics-Assessment-Score.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/velocity-based-training/2016_Conceicao_Movement-Velocity-Lower-Limb.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/velocity-based-training/2023_Balsalobre-Fernandez_AI-Barbell-Velocity.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/athlete-monitoring/2015_Buchheit_GPS-Accelerometers-Stride-Stiffness.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/jump-performance/2016_Jimenez-Reyes_Force-Velocity-Training.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/running-biomechanics/2020_Filter_Curve-Sprint-Test-Soccer.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/velocity-based-training/2016_Pareja-Blanco_Velocity-Loss-Training.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/athlete-monitoring/2018_Saw_Training-Camps-Monitoring.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2017_Mason-Mackay_Ankle-Dorsiflexion-Landing.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2018_Balsalobre-Fernandez_Ankle-Dorsiflexion-App.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/running-biomechanics/2005_Morin_Running-Stiffness-Measurement.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/running-biomechanics/2021_vanOeveren_Running-Biomechanics-Synthesis.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/smartphone-technology/2022_Bishop_MyJumpLab-Validation.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/velocity-based-training/2011_Jidovtseff_Load-Velocity-1RM-Prediction.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/jump-performance/2011_Harper_10-to-5-Jump-Test.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/running-biomechanics/2020_Harper_Horizontal-Deceleration-Radar.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/velocity-based-training/2017_Balsalobre-Fernandez_Barbell-Velocity-1RM.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/athlete-monitoring/2018_Flatt_HRV-Recovery-Swimmers.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2011_Petersen_Nordic-Hamstring-Prevention.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2012_Hewit_Multidirectional-Leg-Asymmetry.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2016_Mendez-Villanueva_Hamstring-MRI-Regional.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2016_Read_Youth-Soccer-Injury-Risk.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2017_Mendiguchia_Hamstring-Treatment-Algorithm.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2020_Fidai_Fatigue-Knee-Valgus-Youth.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/jump-performance/2012_Samozino_Optimal-Force-Velocity-Profile.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/athlete-monitoring/2001_Foster_Session-RPE-Training-Monitoring.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/jump-performance/2018_Garcia-Ramos_Two-Point-Method-Optimization.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/running-biomechanics/2015_Balsalobre-Fernandez_Strength-Training-Running-Economy.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/running-biomechanics/2016_Moore_Economical-Running-Technique.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/smartphone-technology/2015_Balsalobre-Fernandez_iPhone-Vertical-Jump.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/velocity-based-training/2020_Balsalobre-Fernandez_Barbell-Trajectory-Snatch.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/jump-performance/2014_Samozino_FV-Imbalance.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/jump-performance/2016_Morin-Samozino_Power-Force-Velocity-Profiles.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2015_Ford_Hip-Neuromuscular-Exercise-Valgus.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2015_Mosler_Hip-Groin-Pain-Factors.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2015_Sconce_Nordic-Hamstring-Validity.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/jump-performance/2022_Wells_Golf-Clubhead-CMJ.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/athlete-monitoring/2018_Ward_Putting-i-in-Team.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2011_Wilk_Shoulder-GIRD-Baseball-Pitchers.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/injury-prevention/2018_Bramah_Pathological-Gait-Running-Injuries.pdf filter=lfs diff=lfs merge=lfs -text
+docs/research/thirdparty/pdfs/running-biomechanics/2016_Balsalobre-Fernandez_iPhone-Running-Mechanics.pdf filter=lfs diff=lfs merge=lfs -text

{kinemotion-0.23.0 → kinemotion-0.25.0}/.gitignore

@@ -69,3 +69,4 @@ Thumbs.db
 *.jpg
 
 .claude/settings.local.json*
+.cursor/mcp.json

{kinemotion-0.23.0 → kinemotion-0.25.0}/.pre-commit-config.yaml

@@ -39,7 +39,7 @@ repos:
         additional_dependencies:
           - mdformat-gfm>=0.3.5  # GitHub Flavored Markdown
           - mdformat-tables  # Table formatting
-        exclude: (^CLAUDE\.md$|^CHANGELOG\.md$)
+        exclude: (^CLAUDE\.md$|^CHANGELOG\.md$|^presentation/revealjs/slides\.md$)
 
   - repo: https://github.com/compilerla/conventional-pre-commit
     rev: v4.3.0

{kinemotion-0.23.0 → kinemotion-0.25.0}/CHANGELOG.md

@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.25.0 (2025-11-14)
+
+### Documentation
+
+- Add comprehensive validation status and roadmap
+  ([`207b3ab`](https://github.com/feniix/kinemotion/commit/207b3abf4790e423ab69340eee98781aa9bcadc6))
+
+- Add presentation
+  ([`0f2715a`](https://github.com/feniix/kinemotion/commit/0f2715adf93a01fd12c72cd310339daf5d072b3e))
+
+- Add research papers
+  ([`b623c2a`](https://github.com/feniix/kinemotion/commit/b623c2ab265f34bedb38b6174958368bbd5e53bf))
+
+- Google colab
+  ([`98f474c`](https://github.com/feniix/kinemotion/commit/98f474cde68d5bc5ec3b7dc7f438eb912ebc617d))
+
+- Google colab
+  ([`f6bc11b`](https://github.com/feniix/kinemotion/commit/f6bc11bb08a566e846a0eb3549cf8e752839c54d))
+
+### Features
+
+- Add automatic quality assessment and confidence scores to all outputs
+  ([`8eee0e0`](https://github.com/feniix/kinemotion/commit/8eee0e051c3ac4fee8610f05f5735676a4d50331))
+
+- Refactor CLI to call API functions, adding automatic quality assessment
+  ([`b6511cb`](https://github.com/feniix/kinemotion/commit/b6511cbbb7bb93458b827d967636d72391651d0e))
+
+- Restructure JSON output to data/metadata format
+  ([`bb00d3e`](https://github.com/feniix/kinemotion/commit/bb00d3e871c68369dcbb308429084b11eecad0e0))
+
+### Testing
+
+- Add determinism validation scripts and confirm algorithm reliability
+  ([`bd115b0`](https://github.com/feniix/kinemotion/commit/bd115b056b91a55027c5b85362cc3942cf6ea7c5))
+
+### Breaking Changes
+
+- JSON output format restructured from flat to nested {data, metadata}
+
+
+## v0.24.0 (2025-11-11)
+
+### Features
+
+- Document platform-specific system dependencies for Windows, macOS, and Linux
+  ([`928a6ad`](https://github.com/feniix/kinemotion/commit/928a6adbef18df77f5941ae0b2e82ba9d62a38b7))
+
+
 ## v0.23.0 (2025-11-10)
 
 ### Features

{kinemotion-0.23.0 → kinemotion-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.23.0
+Version: 0.25.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
@@ -79,17 +79,42 @@ Description-Content-Type: text/markdown
 - **Metrics**: Jump height, flight time, countermovement depth, eccentric/concentric durations
 - **Validated accuracy**: 50.6cm jump (±1 frame precision)
 
-## Validation Status
+## ⚠️ Validation Status
 
-⚠️ **IMPORTANT**: This tool's accuracy has **not been validated** against gold standard measurements (force plates, 3D motion capture). All accuracy claims and improvement estimates are theoretical and based on algorithmic considerations, not empirical testing.
+**Current Status:** Pre-validation (not validated against force plates or motion capture systems)
 
-The tool provides consistent measurements and may be useful for:
+### What This Tool IS Suitable For
 
-- Tracking relative changes in an individual athlete over time
-- Comparing similar jumps under controlled conditions
-- Exploratory analysis and research
+✅ **Training monitoring** - Track relative changes within the same athlete over time
+✅ **Educational purposes** - Learn about jump biomechanics and video analysis
+✅ **Exploratory analysis** - Initial investigation before formal testing
+✅ **Proof-of-concept research** - Demonstrate feasibility of video-based methods
 
-For clinical, research, or performance assessment requiring validated accuracy, this tool should be compared against validated measurement systems before use.
+### What This Tool IS NOT Suitable For
+
+❌ **Research publications** - As a validated measurement instrument
+❌ **Clinical decision-making** - Injury assessment, return-to-play decisions
+❌ **Talent identification** - Absolute performance comparisons between athletes
+❌ **Legal/insurance assessments** - Any context requiring validated measurements
+❌ **High-stakes testing** - Draft combines, professional athlete evaluation
+
+### Known Limitations
+
+- **No force plate validation** - Accuracy claims are theoretical, not empirical
+- **MediaPipe constraints** - Accuracy affected by lighting, clothing, occlusion, camera quality
+- **Lower sampling rate** - Typical video (30-60fps) vs validated apps (120-240Hz)
+- **Indirect measurement** - Landmarks → CoM estimation introduces potential error
+- **No correction factors** - Unlike validated tools (e.g., MyJump), no systematic bias corrections applied
+
+### Recommended Use
+
+If you need validated measurements for research or clinical use, consider:
+
+- **Commercial validated apps**: MyJump 2, MyJumpLab (smartphone-based, force plate validated)
+- **Laboratory equipment**: Force plates, optical motion capture systems
+- **Validation testing**: Compare kinemotion against validated equipment in your specific use case
+
+For detailed validation status and roadmap, see [`docs/validation-status.md`](docs/validation-status.md).
 
 ## Setup
 
@@ -103,15 +128,24 @@ For clinical, research, or performance assessment requiring validated accuracy,
 
 #### Windows
 
-No additional system dependencies required.
+**Required system dependencies:**
+
+- [Microsoft Visual C++ 2022 Redistributable](https://visualstudio.microsoft.com/visual-cpp-build-tools/) - Runtime libraries for OpenCV/MediaPipe
+- Python 3.10-3.12 (64-bit) - MediaPipe requires 64-bit Python
 
 **Recommended for mobile video support:**
 
-- [FFmpeg](https://ffmpeg.org/download.html) - Download and add to PATH
+- [FFmpeg](https://ffmpeg.org/download.html) - Download and add to PATH for full video codec support
 
 #### macOS
 
-No additional system dependencies required.
+**Required system dependencies:**
+
+- Xcode Command Line Tools - Provides compilers and system frameworks
+
+  ```bash
+  xcode-select --install
+  ```
 
 **Recommended for mobile video support:**
 
@@ -126,9 +160,10 @@ brew install ffmpeg
 ```bash
 sudo apt-get update
 sudo apt-get install -y \
-    libgl1-mesa-glx \
-    libglib2.0-0 \
-    ffmpeg
+    libgl1 \           # OpenGL library for OpenCV
+    libglib2.0-0 \     # GLib library for MediaPipe
+    libgomp1 \         # OpenMP library for multi-threading
+    ffmpeg             # Video codec support and metadata extraction
 ```
 
 **Note:** `ffmpeg` provides the `ffprobe` tool for video metadata extraction (rotation, aspect ratio). Kinemotion works without it, but mobile/rotated videos may not process correctly. A warning will be shown if `ffprobe` is not available.
@@ -232,6 +267,55 @@ kinemotion cmj-analyze videos/*.mp4 --batch --workers 4 \
   --csv-summary summary.csv
 ```
 
+### Quality Indicators & Confidence Scores
+
+All analysis outputs include automatic quality assessment 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
+  },
+  "warnings": []
+}
+```
+
+**Confidence Levels:**
+
+- **High** (score ≥75): Trust these results, good tracking quality
+- **Medium** (score 50-74): Use with caution, check quality indicators
+- **Low** (score \<50): Results may be unreliable, review warnings
+
+**Common Warnings:**
+
+- Poor lighting or occlusion detected
+- Unstable landmark tracking (jitter)
+- High outlier rate (tracking glitches)
+- Low frame rate (\<30fps)
+- Unclear phase transitions
+
+**Filtering by Quality:**
+
+```python
+# Only use high-confidence results
+metrics = process_cmj_video("video.mp4")
+if metrics.quality_assessment.confidence == "high":
+    print(f"Reliable jump height: {metrics.jump_height:.3f}m")
+else:
+    print(f"Low quality - warnings: {metrics.quality_assessment.warnings}")
+```
+
 ## Python API
 
 Use kinemotion as a library for automated pipelines and custom analysis.

{kinemotion-0.23.0 → kinemotion-0.25.0}/README.md

@@ -50,17 +50,42 @@
 - **Metrics**: Jump height, flight time, countermovement depth, eccentric/concentric durations
 - **Validated accuracy**: 50.6cm jump (±1 frame precision)
 
-## Validation Status
+## ⚠️ Validation Status
 
-⚠️ **IMPORTANT**: This tool's accuracy has **not been validated** against gold standard measurements (force plates, 3D motion capture). All accuracy claims and improvement estimates are theoretical and based on algorithmic considerations, not empirical testing.
+**Current Status:** Pre-validation (not validated against force plates or motion capture systems)
 
-The tool provides consistent measurements and may be useful for:
+### What This Tool IS Suitable For
 
-- Tracking relative changes in an individual athlete over time
-- Comparing similar jumps under controlled conditions
-- Exploratory analysis and research
+✅ **Training monitoring** - Track relative changes within the same athlete over time
+✅ **Educational purposes** - Learn about jump biomechanics and video analysis
+✅ **Exploratory analysis** - Initial investigation before formal testing
+✅ **Proof-of-concept research** - Demonstrate feasibility of video-based methods
 
-For clinical, research, or performance assessment requiring validated accuracy, this tool should be compared against validated measurement systems before use.
+### What This Tool IS NOT Suitable For
+
+❌ **Research publications** - As a validated measurement instrument
+❌ **Clinical decision-making** - Injury assessment, return-to-play decisions
+❌ **Talent identification** - Absolute performance comparisons between athletes
+❌ **Legal/insurance assessments** - Any context requiring validated measurements
+❌ **High-stakes testing** - Draft combines, professional athlete evaluation
+
+### Known Limitations
+
+- **No force plate validation** - Accuracy claims are theoretical, not empirical
+- **MediaPipe constraints** - Accuracy affected by lighting, clothing, occlusion, camera quality
+- **Lower sampling rate** - Typical video (30-60fps) vs validated apps (120-240Hz)
+- **Indirect measurement** - Landmarks → CoM estimation introduces potential error
+- **No correction factors** - Unlike validated tools (e.g., MyJump), no systematic bias corrections applied
+
+### Recommended Use
+
+If you need validated measurements for research or clinical use, consider:
+
+- **Commercial validated apps**: MyJump 2, MyJumpLab (smartphone-based, force plate validated)
+- **Laboratory equipment**: Force plates, optical motion capture systems
+- **Validation testing**: Compare kinemotion against validated equipment in your specific use case
+
+For detailed validation status and roadmap, see [`docs/validation-status.md`](docs/validation-status.md).
 
 ## Setup
 
@@ -74,15 +99,24 @@ For clinical, research, or performance assessment requiring validated accuracy,
 
 #### Windows
 
-No additional system dependencies required.
+**Required system dependencies:**
+
+- [Microsoft Visual C++ 2022 Redistributable](https://visualstudio.microsoft.com/visual-cpp-build-tools/) - Runtime libraries for OpenCV/MediaPipe
+- Python 3.10-3.12 (64-bit) - MediaPipe requires 64-bit Python
 
 **Recommended for mobile video support:**
 
-- [FFmpeg](https://ffmpeg.org/download.html) - Download and add to PATH
+- [FFmpeg](https://ffmpeg.org/download.html) - Download and add to PATH for full video codec support
 
 #### macOS
 
-No additional system dependencies required.
+**Required system dependencies:**
+
+- Xcode Command Line Tools - Provides compilers and system frameworks
+
+  ```bash
+  xcode-select --install
+  ```
 
 **Recommended for mobile video support:**
 
@@ -97,9 +131,10 @@ brew install ffmpeg
 ```bash
 sudo apt-get update
 sudo apt-get install -y \
-    libgl1-mesa-glx \
-    libglib2.0-0 \
-    ffmpeg
+    libgl1 \           # OpenGL library for OpenCV
+    libglib2.0-0 \     # GLib library for MediaPipe
+    libgomp1 \         # OpenMP library for multi-threading
+    ffmpeg             # Video codec support and metadata extraction
 ```
 
 **Note:** `ffmpeg` provides the `ffprobe` tool for video metadata extraction (rotation, aspect ratio). Kinemotion works without it, but mobile/rotated videos may not process correctly. A warning will be shown if `ffprobe` is not available.
@@ -203,6 +238,55 @@ kinemotion cmj-analyze videos/*.mp4 --batch --workers 4 \
   --csv-summary summary.csv
 ```
 
+### Quality Indicators & Confidence Scores
+
+All analysis outputs include automatic quality assessment 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
+  },
+  "warnings": []
+}
+```
+
+**Confidence Levels:**
+
+- **High** (score ≥75): Trust these results, good tracking quality
+- **Medium** (score 50-74): Use with caution, check quality indicators
+- **Low** (score \<50): Results may be unreliable, review warnings
+
+**Common Warnings:**
+
+- Poor lighting or occlusion detected
+- Unstable landmark tracking (jitter)
+- High outlier rate (tracking glitches)
+- Low frame rate (\<30fps)
+- Unclear phase transitions
+
+**Filtering by Quality:**
+
+```python
+# Only use high-confidence results
+metrics = process_cmj_video("video.mp4")
+if metrics.quality_assessment.confidence == "high":
+    print(f"Reliable jump height: {metrics.jump_height:.3f}m")
+else:
+    print(f"Low quality - warnings: {metrics.quality_assessment.warnings}")
+```
+
 ## Python API
 
 Use kinemotion as a library for automated pipelines and custom analysis.

{kinemotion-0.23.0 → kinemotion-0.25.0}/docs/README.md

@@ -24,6 +24,7 @@ Welcome to the kinemotion documentation. This directory contains guides, technic
 
 ### 🔬 Research & Validation
 
+- **[⚠️ Validation Status](validation-status.md)** - **READ FIRST** - Current validation status, limitations, and appropriate use cases
 - **[Sports Biomechanics Pose Estimation](research/sports-biomechanics-pose-estimation.md)** - Comprehensive research analysis on pose detection systems for sports biomechanics
   - Pose2Sim validation (3-4° accuracy)
   - Stereo MediaPipe validation (30.1mm RMSE)
@@ -39,6 +40,7 @@ Welcome to the kinemotion documentation. This directory contains guides, technic
 
 ### 👨‍💻 Development
 
+- **[Validation Roadmap](development/validation-roadmap.md)** - 3-month validation plan (no lab equipment required)
 - **[Validation Plan](development/validation-plan.md)** - Testing and validation strategy
 - **[Errors & Findings](development/errors-findings.md)** - Known issues and debugging information
 - **[Wall Ball No-Rep Detection](development/wallball-norep-detection.md)** - Future feature implementation plan for HYROX wall ball analysis
@@ -73,9 +75,15 @@ Start here:
 
 ### For Researchers
 
+#### ⚠️ IMPORTANT: Read validation status first before using in research
+
+1. [**Validation Status**](validation-status.md) - **READ FIRST** - Limitations and appropriate use
+
 1. [Sports Biomechanics Pose Estimation](research/sports-biomechanics-pose-estimation.md) - Research analysis
+
 1. [Pose Systems Quick Reference](reference/pose-systems.md) - System comparisons
-1. [Validation Plan](development/validation-plan.md) - Validation methodology
+
+1. [Validation Roadmap](development/validation-roadmap.md) - Planned validation activities
 
 ### For Developers