kinemotion 0.12.3__tar.gz → 0.13.0__tar.gz

{kinemotion-0.12.3 → kinemotion-0.13.0}/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.13.0 (2025-11-06)
+
+### Documentation
+
+- Add sports biomechanics pose estimation research documentation
+  ([`745d273`](https://github.com/feniix/kinemotion/commit/745d273da294d49dd83f8fe488f5ede38189361a))
+
+- Update camera setup guides for 45° angle and dual iPhone configuration
+  ([`373a858`](https://github.com/feniix/kinemotion/commit/373a858e81c74da6a85be8c00d7fc0c20ac42e85))
+
+### Features
+
+- **docs**: Reorganize documentation and add 45° camera setup guidance
+  ([`0e8f992`](https://github.com/feniix/kinemotion/commit/0e8f992a7854a662b65574f589306bc13529cd5e))
+
+
 ## v0.12.3 (2025-11-06)
 
 ### Bug Fixes

{kinemotion-0.12.3 → kinemotion-0.13.0}/CLAUDE.md

@@ -224,8 +224,47 @@ metrics = process_cmj_video("video.mp4")
 
 ## Documentation
 
-**User guides:** docs/CMJ_GUIDE.md, docs/CAMERA_SETUP.md, docs/PARAMETERS.md
-**Technical:** docs/TRIPLE_EXTENSION.md, docs/REAL_TIME_ANALYSIS.md
+**User guides:** docs/guides/cmj-guide.md, docs/guides/camera-setup.md, docs/guides/bulk-processing.md
+**Reference:** docs/reference/parameters.md, docs/reference/pose-systems.md
+**Technical:** docs/technical/triple-extension.md, docs/technical/real-time-analysis.md
+**Research:** docs/research/sports-biomechanics-pose-estimation.md
+
+**See [docs/README.md](docs/README.md) for complete documentation navigation.**
+
+### Documentation Organization
+
+Documentation follows the [Diátaxis framework](https://diataxis.fr/) - a systematic approach that organizes content by user needs:
+
+**Framework categories:**
+1. **Tutorials/Guides** (learning-oriented) → `docs/guides/`
+   - Goal: Help users accomplish specific tasks
+   - Examples: Camera setup, CMJ analysis, bulk processing
+   - Characteristic: Step-by-step instructions
+
+2. **Reference** (information-oriented) → `docs/reference/`
+   - Goal: Provide technical descriptions and specifications
+   - Examples: CLI parameters, pose system comparisons
+   - Characteristic: Structured for quick lookup
+
+3. **Explanation** (understanding-oriented) → `docs/technical/`, `docs/research/`
+   - Goal: Clarify and illuminate topics
+   - Examples: Triple extension biomechanics, pose estimation research
+   - Characteristic: Background knowledge, theory
+
+4. **Development** (contributor-oriented) → `docs/development/`
+   - Goal: Support project contributors
+   - Examples: Validation plans, error findings
+   - Characteristic: Internal processes, debugging
+
+**Additional categories:**
+- `docs/translations/` - Non-English documentation (e.g., Spanish)
+
+**When adding new documentation:**
+- **How-to content?** → `guides/`
+- **Parameter specs or quick lookups?** → `reference/`
+- **Implementation details or theory?** → `technical/` or `research/`
+- **Testing or debugging?** → `development/`
+- **Translation?** → `translations/{language-code}/`
 
 ## Commit Format
 

{kinemotion-0.12.3 → kinemotion-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.12.3
+Version: 0.13.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
@@ -323,7 +323,7 @@ For advanced users who need manual control:
 - `--detection-confidence <float>`: Override MediaPipe detection confidence
 - `--tracking-confidence <float>`: Override MediaPipe tracking confidence
 
-> **📖 For detailed parameter explanations, see [docs/PARAMETERS.md](docs/PARAMETERS.md)**
+> **📖 For detailed parameter explanations, see [docs/reference/parameters.md](docs/reference/parameters.md)**
 >
 > **Note:** Most users never need expert parameters - auto-tuning handles optimization automatically!
 

{kinemotion-0.12.3 → kinemotion-0.13.0}/README.md

@@ -294,7 +294,7 @@ For advanced users who need manual control:
 - `--detection-confidence <float>`: Override MediaPipe detection confidence
 - `--tracking-confidence <float>`: Override MediaPipe tracking confidence
 
-> **📖 For detailed parameter explanations, see [docs/PARAMETERS.md](docs/PARAMETERS.md)**
+> **📖 For detailed parameter explanations, see [docs/reference/parameters.md](docs/reference/parameters.md)**
 >
 > **Note:** Most users never need expert parameters - auto-tuning handles optimization automatically!
 

kinemotion-0.13.0/docs/README.md

@@ -0,0 +1,103 @@
+# Kinemotion Documentation
+
+Welcome to the kinemotion documentation. This directory contains guides, technical documentation, and research for video-based kinematic analysis of athletic jumps.
+
+## Quick Navigation
+
+### 🚀 Getting Started
+
+- **[Camera Setup Guide](guides/camera-setup.md)** - How to position your camera for optimal analysis
+  - Single iPhone at 45° (standard setup)
+  - Dual iPhone stereo (advanced setup)
+  - [Versión en Español](translations/es/camera-setup.md)
+
+### 📖 User Guides
+
+- **[CMJ Guide](guides/cmj-guide.md)** - Counter-movement jump analysis guide
+- **[Bulk Processing](guides/bulk-processing.md)** - Processing multiple videos efficiently
+- **[Parameters Reference](reference/parameters.md)** - CLI parameters and options
+
+### 📊 Reference
+
+- **[Pose Systems Quick Reference](reference/pose-systems.md)** - Comparison of pose estimation systems
+- **[Parameters](reference/parameters.md)** - Complete CLI parameter documentation
+
+### 🔬 Research & Validation
+
+- **[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)
+  - AthletePose3D dataset
+  - System comparisons and recommendations
+
+### ⚙️ Technical Documentation
+
+- **[Triple Extension](technical/triple-extension.md)** - Biomechanics of triple extension in jumps
+- **[Framerate](technical/framerate.md)** - Frame rate considerations for analysis
+- **[IMU Metadata](technical/imu-metadata.md)** - Video metadata preservation
+- **[Real-Time Analysis](technical/real-time-analysis.md)** - Future real-time processing capabilities
+
+### 👨‍💻 Development
+
+- **[Validation Plan](development/validation-plan.md)** - Testing and validation strategy
+- **[Errors & Findings](development/errors-findings.md)** - Known issues and debugging information
+
+### 🌍 Translations
+
+- **[Español (Spanish)](translations/es/)**
+  - [Guía de Configuración de Cámara](translations/es/camera-setup.md)
+
+______________________________________________________________________
+
+## Documentation Organization
+
+This documentation follows a structured organization:
+
+- **guides/** - User-facing how-to guides for setup and usage
+- **reference/** - Quick lookup reference materials
+- **technical/** - Implementation details and technical explanations
+- **research/** - Academic research and validation studies
+- **development/** - Developer and contributor resources
+- **translations/** - Non-English documentation
+
+## Quick Links by Audience
+
+### For Athletes & Coaches
+
+Start here:
+
+1. [Camera Setup Guide](guides/camera-setup.md) - Critical first step
+1. [CMJ Guide](guides/cmj-guide.md) - Understanding CMJ analysis
+1. [Parameters Reference](reference/parameters.md) - Adjusting analysis settings
+
+### For Researchers
+
+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
+
+### For Developers
+
+1. [Triple Extension](technical/triple-extension.md) - Biomechanics implementation
+1. [IMU Metadata](technical/imu-metadata.md) - Video processing details
+1. [Validation Plan](development/validation-plan.md) - Testing strategy
+1. Main [CLAUDE.md](../CLAUDE.md) - Complete project documentation
+
+______________________________________________________________________
+
+## Contributing to Documentation
+
+When adding new documentation:
+
+- **User guides** → `guides/` (how-to content)
+- **Reference materials** → `reference/` (quick lookups, parameters, specs)
+- **Technical details** → `technical/` (implementation, algorithms, biomechanics)
+- **Research** → `research/` (validation studies, academic content)
+- **Development** → `development/` (testing, debugging, contributor info)
+- **Translations** → `translations/{language-code}/`
+
+Ensure cross-references use relative paths and follow conventional commits format when committing changes.
+
+______________________________________________________________________
+
+**Last Updated:** November 6, 2025