kinemotion 0.12.3__tar.gz → 0.14.0__tar.gz

kinemotion-0.14.0/.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv sync --frozen
+
+      - name: Build documentation
+        run: |
+          uv run mkdocs build --strict
+
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: site/
+
+  deploy:
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: |
+          uv sync --frozen
+
+      - name: Deploy to GitHub Pages
+        run: |
+          uv run mkdocs gh-deploy --force

{kinemotion-0.12.3 → kinemotion-0.14.0}/.gitignore

@@ -50,6 +50,9 @@ htmlcov/
 *.csv
 !pyproject.toml
 
+# Documentation build output
+site/
+
 # Logs
 *.log
 combined.log

kinemotion-0.14.0/.readthedocs.yml

@@ -0,0 +1,29 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Build documentation with MkDocs
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: false
+
+# Build environment
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_install:
+      # Install uv for faster dependency resolution
+      - pip install uv
+      # Install project dependencies including mkdocs
+      - uv sync --frozen
+
+# Python configuration
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev

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

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.14.0 (2025-11-06)
+
+### Features
+
+- **docs**: Add MkDocs documentation with auto-generated API reference
+  ([`cb5cd31`](https://github.com/feniix/kinemotion/commit/cb5cd313e43c6ba0c95c8e77b5651e7c86c73902))
+
+
+## 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.14.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.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.12.3
+Version: 0.14.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.14.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.14.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

kinemotion-0.14.0/docs/api/cmj.md

@@ -0,0 +1,87 @@
+# CMJ API
+
+The CMJ API provides functions for analyzing counter movement jump videos and extracting kinematic metrics including triple extension analysis.
+
+## Quick Example
+
+```python
+from kinemotion import process_cmj_video
+
+metrics = process_cmj_video(
+    video_path="cmj.mp4",
+    output_path="debug.mp4",  # optional
+    smoothing=True
+)
+
+print(f"Jump height: {metrics.jump_height:.2f}m")
+print(f"Flight time: {metrics.flight_time:.3f}s")
+print(f"Countermovement depth: {metrics.countermovement_depth:.3f}m")
+print(f"Triple extension: {metrics.triple_extension_percentage:.1f}%")
+```
+
+## Main Functions
+
+::: kinemotion.api.process_cmj_video
+options:
+show_root_heading: true
+show_source: false
+
+::: kinemotion.api.process_cmj_videos_bulk
+options:
+show_root_heading: true
+show_source: false
+
+## Configuration
+
+::: kinemotion.api.CMJVideoConfig
+options:
+show_root_heading: true
+show_source: false
+
+## Results
+
+::: kinemotion.api.CMJVideoResult
+options:
+show_root_heading: true
+show_source: false
+
+## Metrics
+
+::: kinemotion.cmj.kinematics.CMJMetrics
+options:
+show_root_heading: true
+show_source: false
+
+## Key Differences from Drop Jump
+
+### No Calibration Required
+
+Unlike drop jumps, CMJ analysis doesn't require a `drop_height` parameter. All measurements are relative to the starting position.
+
+### Backward Search Algorithm
+
+CMJ detection uses a backward search algorithm starting from the peak height, making it more robust than forward search.
+
+### Signed Velocity
+
+CMJ analysis uses signed velocity (direction matters) to distinguish upward vs downward motion phases.
+
+### Lateral View Required
+
+CMJ analysis requires a lateral (side) view for accurate depth and triple extension measurements. Front view will not work due to parallax errors.
+
+## Triple Extension Analysis
+
+The CMJ API includes detailed triple extension analysis:
+
+```python
+metrics = process_cmj_video("cmj.mp4")
+
+# Triple extension metrics
+print(f"Hip extension: {metrics.hip_extension_angle:.1f}°")
+print(f"Knee extension: {metrics.knee_extension_angle:.1f}°")
+print(f"Ankle plantar flexion: {metrics.ankle_plantar_flexion_angle:.1f}°")
+print(f"Overall triple extension: {metrics.triple_extension_percentage:.1f}%")
+```
+
+See [Triple Extension Technical Documentation](../technical/triple-extension.md) for biomechanics details.

kinemotion-0.14.0/docs/api/core.md

@@ -0,0 +1,81 @@
+# Core Utilities
+
+Lower-level utilities for advanced usage and custom analysis pipelines.
+
+## Pose Detection
+
+::: kinemotion.core.pose.PoseTracker
+options:
+show_root_heading: true
+show_source: false
+
+::: kinemotion.core.pose.compute_center_of_mass
+options:
+show_root_heading: true
+show_source: false
+
+## Smoothing & Filtering
+
+::: kinemotion.core.smoothing.smooth_landmarks
+options:
+show_root_heading: true
+show_source: false
+
+::: kinemotion.core.smoothing.smooth_landmarks_advanced
+options:
+show_root_heading: true
+show_source: false
+
+## Video Processing
+
+::: kinemotion.core.video_io.VideoProcessor
+options:
+show_root_heading: true
+show_source: false
+
+## Auto-Tuning
+
+::: kinemotion.core.auto_tuning.auto_tune_parameters
+options:
+show_root_heading: true
+show_source: false
+
+::: kinemotion.core.auto_tuning.analyze_video_sample
+options:
+show_root_heading: true
+show_source: false
+
+::: kinemotion.core.auto_tuning.QualityPreset
+options:
+show_root_heading: true
+show_source: false
+
+## Usage Example
+
+```python
+from kinemotion.core.pose import PoseTracker
+from kinemotion.core.smoothing import smooth_landmarks
+from kinemotion.core.video_io import VideoProcessor
+
+# Initialize pose tracker
+tracker = PoseTracker(
+    min_detection_confidence=0.5,
+    min_tracking_confidence=0.5
+)
+
+# Process video
+video = VideoProcessor("video.mp4")
+landmarks = []
+
+for frame in video:
+    result = tracker.process_frame(frame)
+    if result:
+        landmarks.append(result)
+
+# Apply smoothing
+smoothed = smooth_landmarks(
+    landmarks,
+    window_length=13,
+    polyorder=3
+)
+```

kinemotion-0.14.0/docs/api/dropjump.md

@@ -0,0 +1,81 @@
+# Drop Jump API
+
+The drop jump API provides functions for analyzing drop jump videos and extracting kinematic metrics.
+
+## Quick Example
+
+```python
+from kinemotion import process_video
+
+metrics = process_video(
+    video_path="dropjump.mp4",
+    drop_height=0.40,  # meters
+    output_path="debug.mp4",  # optional
+    smoothing=True
+)
+
+print(f"Ground contact time: {metrics.ground_contact_time:.3f}s")
+print(f"Flight time: {metrics.flight_time:.3f}s")
+print(f"RSI: {metrics.reactive_strength_index:.2f}")
+```
+
+## Main Functions
+
+::: kinemotion.api.process_video
+options:
+show_root_heading: true
+show_source: false
+
+::: kinemotion.api.process_videos_bulk
+options:
+show_root_heading: true
+show_source: false
+
+## Configuration
+
+::: kinemotion.api.VideoConfig
+options:
+show_root_heading: true
+show_source: false
+
+## Results
+
+::: kinemotion.api.VideoResult
+options:
+show_root_heading: true
+show_source: false
+
+## Metrics
+
+::: kinemotion.dropjump.kinematics.DropJumpMetrics
+options:
+show_root_heading: true
+show_source: false
+
+## Key Parameters
+
+### drop_height
+
+**Required.** The height of the drop box in meters. This is critical for accurate velocity calculations.
+
+```python
+metrics = process_video("video.mp4", drop_height=0.40)  # 40cm box
+```
+
+### smoothing
+
+Apply Savitzky-Golay smoothing to landmark positions before analysis. Reduces noise but may slightly delay event detection.
+
+Default: `True`
+
+### output_path
+
+Path to write debug video with overlay visualization. If not provided, no debug video is created.
+
+```python
+metrics = process_video(
+    "video.mp4",
+    drop_height=0.40,
+    output_path="debug.mp4"
+)
+```

kinemotion-0.14.0/docs/api/overview.md

@@ -0,0 +1,73 @@
+# API Overview
+
+Kinemotion provides a Python API for video-based kinematic analysis. The API is organized around two main jump types:
+
+## Main Functions
+
+### Drop Jump Analysis
+
+Process drop jump videos and extract kinematic metrics:
+
+- `process_video()` - Analyze a single drop jump video
+- `process_videos_bulk()` - Batch process multiple drop jump videos
+- `VideoConfig` - Configuration for drop jump analysis
+- `VideoResult` - Results from drop jump analysis
+- `DropJumpMetrics` - Kinematic metrics for drop jumps
+
+See [Drop Jump API](dropjump.md) for detailed documentation.
+
+### CMJ Analysis
+
+Process counter movement jump videos and extract kinematic metrics:
+
+- `process_cmj_video()` - Analyze a single CMJ video
+- `process_cmj_videos_bulk()` - Batch process multiple CMJ videos
+- `CMJVideoConfig` - Configuration for CMJ analysis
+- `CMJVideoResult` - Results from CMJ analysis
+- `CMJMetrics` - Kinematic metrics for CMJs
+
+See [CMJ API](cmj.md) for detailed documentation.
+
+## Basic Usage
+
+```python
+from kinemotion import process_video, process_cmj_video
+
+# Drop jump analysis
+drop_metrics = process_video("dropjump.mp4", drop_height=0.40)
+
+# CMJ analysis
+cmj_metrics = process_cmj_video("cmj.mp4")
+```
+
+## Batch Processing
+
+```python
+from kinemotion import process_videos_bulk, process_cmj_videos_bulk
+
+# Batch drop jump analysis
+results = process_videos_bulk(
+    video_paths=["video1.mp4", "video2.mp4"],
+    drop_height=0.40,
+    output_dir="results/",
+    workers=4
+)
+
+# Batch CMJ analysis
+cmj_results = process_cmj_videos_bulk(
+    video_paths=["cmj1.mp4", "cmj2.mp4"],
+    output_dir="results/",
+    workers=4
+)
+```
+
+## Core Utilities
+
+For advanced usage, you can access lower-level utilities:
+
+- Pose detection and tracking
+- Velocity computation
+- Smoothing and filtering
+- Video I/O with rotation handling
+
+See [Core Utilities](core.md) for detailed documentation.