kinemotion 0.10.12__tar.gz → 0.11.0__tar.gz

{kinemotion-0.10.12 → kinemotion-0.11.0}/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.11.0 (2025-11-06)
+
+### Documentation
+
+- Add camera setup docs
+  ([`84678d6`](https://github.com/feniix/kinemotion/commit/84678d60261a361c1dce51aec604491ab096f537))
+
+### Features
+
+- Add counter movement jump (CMJ) analysis with triple extension tracking
+  ([`b6fc454`](https://github.com/feniix/kinemotion/commit/b6fc454482b20b11d82fadc51974a554562b60d3))
+
+
 ## v0.10.12 (2025-11-03)
 
 ### Bug Fixes

kinemotion-0.11.0/CLAUDE.md

@@ -0,0 +1,234 @@
+# CLAUDE.md
+
+## Repository Purpose
+
+Kinemotion: Video-based kinematic analysis for athletic performance using MediaPipe pose tracking.
+
+**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
+
+## Quick Setup
+
+```bash
+asdf install        # Install Python 3.12.7 + uv
+uv sync            # Install dependencies
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40
+uv run kinemotion cmj-analyze video.mp4
+```
+
+**Development:**
+```bash
+uv run pytest                           # Run all 70 tests
+uv run ruff check --fix && uv run pyright  # Lint + type check
+```
+
+## Architecture
+
+### Module Structure
+
+```
+src/kinemotion/
+├── cli.py                  # Main CLI (registers subcommands)
+├── api.py                  # Python API (process_video, process_cmj_video, bulk)
+├── core/                   # Shared: pose, smoothing, filtering, auto_tuning, video_io
+├── dropjump/               # Drop jump: cli, analysis, kinematics, debug_overlay
+└── cmj/                    # CMJ: cli, analysis, kinematics, joint_angles, debug_overlay
+
+tests/                      # 70 tests total (61 drop jump, 9 CMJ)
+docs/                       # CMJ_GUIDE, TRIPLE_EXTENSION, REAL_TIME_ANALYSIS, etc.
+```
+
+**Design**: Each jump type is a sibling module with its own CLI command, metrics, and visualization.
+
+### Key Differences: Drop Jump vs CMJ
+
+| Feature | Drop Jump | CMJ |
+|---------|-----------|-----|
+| Starting | Elevated box | Floor level |
+| Algorithm | Forward search | Backward search from peak |
+| Velocity | Absolute (magnitude) | Signed (direction matters) |
+| Parameter | `--drop-height` required | No calibration needed |
+| Key Metric | Ground contact time | Jump height from flight time |
+
+## Critical Implementation Details
+
+### 1. Aspect Ratio Preservation (core/video_io.py)
+
+**Always:**
+- Read first actual frame for dimensions: `frame.shape[:2]`
+- Handle SAR (Sample Aspect Ratio) metadata with ffprobe
+- Validate dimensions in `write_frame()` to prevent corruption
+
+**Never:**
+- Use `cv2.CAP_PROP_FRAME_WIDTH/HEIGHT` (wrong for rotated videos)
+
+### 2. Video Rotation (core/video_io.py)
+
+- Extract rotation metadata from ffprobe (`side_data_list`)
+- Apply rotation in `read_frame()` using `cv2.rotate()`
+- Update width/height after 90°/-90° rotations
+
+### 3. JSON Serialization
+
+**Always convert NumPy types:**
+```python
+"frame": int(self.frame) if self.frame is not None else None
+```
+
+**Never:**
+```python
+"frame": self.frame  # WRONG - int64 not JSON serializable
+```
+
+### 4. CMJ Signed Velocity (cmj/analysis.py)
+
+**Critical difference from drop jump:**
+
+```python
+# Drop jump: absolute velocity
+velocities = compute_velocity_from_derivative(positions)  # Returns abs()
+
+# CMJ: MUST use signed velocity
+velocities = compute_signed_velocity(positions)  # Keeps sign
+```
+
+**Why**: CMJ needs to distinguish upward (negative) vs downward (positive) motion for phase detection.
+
+### 5. CMJ Backward Search (cmj/analysis.py)
+
+**Algorithm:**
+1. Find peak height first (global argmin)
+2. Work backward: takeoff → lowest point
+3. Work forward: landing after peak
+
+**Why**: More robust than forward search, avoids false detections from video start.
+
+### 6. Frame Dimensions
+
+OpenCV vs NumPy ordering:
+- NumPy shape: `(height, width, channels)`
+- OpenCV VideoWriter: `(width, height)` tuple
+
+## Common Tasks
+
+### Add New Jump Type
+
+1. Create `src/kinemotion/newjump/` with cli.py, analysis.py, kinematics.py
+2. Register in `src/kinemotion/cli.py`: `cli.add_command(newjump_analyze)`
+3. Add API functions in `api.py`
+4. Export in `__init__.py`
+5. Add tests
+
+### Add Metrics
+
+1. Update dataclass (e.g., `CMJMetrics`)
+2. Calculate in `calculate_*_metrics()`
+3. Add to `to_dict()` (convert NumPy types!)
+4. Add tests
+
+### Modify Detection
+
+**Drop Jump**: Edit `detect_ground_contact()` in dropjump/analysis.py
+**CMJ**: Edit `detect_cmj_phases()` in cmj/analysis.py (backward search)
+
+## Testing & Quality
+
+### Before Commit
+
+```bash
+uv run ruff check --fix   # Auto-fix linting
+uv run pyright            # Type check (strict)
+uv run pytest             # All 70 tests
+```
+
+### Standards
+
+- Pyright strict mode (all functions typed)
+- Ruff (100 char lines)
+- Conventional Commits (see below)
+
+## Quick Reference
+
+### CLI
+
+```bash
+# Drop jump (requires --drop-height)
+kinemotion dropjump-analyze video.mp4 --drop-height 0.40
+
+# CMJ (no calibration needed)
+kinemotion cmj-analyze video.mp4 --output debug.mp4
+
+# Batch
+kinemotion cmj-analyze videos/*.mp4 --batch --workers 4
+```
+
+### Python API
+
+```python
+# Drop jump
+from kinemotion import process_video
+metrics = process_video("video.mp4", drop_height=0.40)
+
+# CMJ
+from kinemotion import process_cmj_video
+metrics = process_cmj_video("video.mp4")
+```
+
+## Important Gotchas
+
+### Video Processing
+
+1. Read first frame for dimensions (not OpenCV properties)
+2. Handle rotation metadata (mobile videos)
+3. Preserve aspect ratio (SAR)
+4. Validate dimensions in write_frame()
+
+### CMJ Specific
+
+1. **Lateral view required** - Front view won't work (parallax errors)
+2. **Signed velocity** - Critical for phase detection
+3. **Backward search** - Requires complete video (not real-time)
+4. **MediaPipe limitations** - Ankle/knee only 18-27% visible in side view
+
+### Type Safety
+
+1. Convert NumPy types in `to_dict()`: `int()`, `float()`
+2. Type all functions (pyright strict)
+3. Handle None in optional fields
+
+## Documentation
+
+**User guides:** docs/CMJ_GUIDE.md, docs/CAMERA_SETUP.md, docs/PARAMETERS.md
+**Technical:** docs/TRIPLE_EXTENSION.md, docs/REAL_TIME_ANALYSIS.md
+
+## Commit Format
+
+**Required**: [Conventional Commits](https://www.conventionalcommits.org/) - enforced by pre-commit hook
+
+**Format**: `<type>(<scope>): <description>`
+
+**Types** (triggers version bumps):
+- `feat`: New feature → minor version bump (0.x.0)
+- `fix`: Bug fix → patch version bump (0.0.x)
+- `perf`: Performance improvement → patch
+- `docs`, `test`, `refactor`, `chore`, `style`, `ci`, `build` → no version bump
+
+**Examples:**
+```bash
+feat: add CMJ analysis with triple extension tracking
+fix: correct takeoff detection in backward search algorithm
+docs: add triple extension biomechanics guide
+test: add CMJ phase detection tests
+refactor: extract signed velocity to separate function
+chore(release): 0.11.0 [skip ci]
+```
+
+**Breaking changes**: Add `!` or `BREAKING CHANGE:` footer
+```bash
+feat!: change API signature for process_video
+```
+
+## MCP Servers
+
+Configured in `.mcp.json`: web-search, sequential-thinking, context7, etc.

{kinemotion-0.10.12 → kinemotion-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.10.12
+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
@@ -36,29 +36,43 @@ Description-Content-Type: text/markdown
 [![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
 
@@ -104,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
@@ -252,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)"])