kinemotion 0.21.0__tar.gz → 0.22.1__tar.gz

{kinemotion-0.21.0 → kinemotion-0.22.1}/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.22.1 (2025-11-10)
+
+### Bug Fixes
+
+- Skip batch mode tests in CI to prevent MediaPipe multiprocessing crashes
+  ([`05dd796`](https://github.com/feniix/kinemotion/commit/05dd796b36252323c36f8d503c372d96e4108381))
+
+
+## v0.22.0 (2025-11-10)
+
+### Bug Fixes
+
+- Make CLI batch tests resilient to processing failures in CI
+  ([`1f3dfed`](https://github.com/feniix/kinemotion/commit/1f3dfedbe88a2c9be21c907053e549ee2431c500))
+
+### Features
+
+- Comprehensive test coverage expansion and documentation refactoring
+  ([`dc3cda4`](https://github.com/feniix/kinemotion/commit/dc3cda4e022b61f635e537784aafc08e0f6e78fe))
+
+
 ## v0.21.0 (2025-11-10)
 
 ### Features

kinemotion-0.22.1/CLAUDE.md

@@ -0,0 +1,247 @@
+# 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
+uv run kinemotion cmj-analyze video.mp4
+```
+
+**Development:**
+
+```bash
+uv run pytest                           # Run all 206 tests with coverage (73.03%)
+uv run pytest --cov-report=html         # Generate HTML coverage report
+uv run ruff check --fix && uv run pyright  # Lint + type check
+```
+
+**Coverage Reports:**
+
+- Terminal: Automatic with `uv run pytest`
+- HTML: `htmlcov/index.html` (open in browser)
+- XML: `coverage.xml` (for CI integration)
+
+**SonarQube Cloud Integration:**
+
+The project integrates with SonarQube Cloud for continuous code quality and coverage tracking.
+
+Setup (one-time):
+
+1. Visit [SonarCloud](https://sonarcloud.io/) and sign in with GitHub
+2. Import the `feniix/kinemotion` repository
+3. Generate a token: My Account > Security > Generate Tokens
+4. Add token to GitHub: Repository > Settings > Secrets and variables > Actions
+   - Name: `SONAR_TOKEN`
+   - Value: Your generated token
+
+Configuration files:
+
+- `sonar-project.properties` - SonarQube project configuration
+- `.github/workflows/test.yml` - CI workflow with SonarQube scan
+
+The workflow automatically:
+
+- Runs tests with coverage on every PR and push to main
+- Uploads coverage.xml to SonarQube Cloud
+- Runs quality gate checks
+
+View results: <https://sonarcloud.io/project/overview?id=feniix_kinemotion>
+
+## Architecture
+
+### Module Structure
+
+```text
+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/                      # 206 tests total (comprehensive coverage across all modules)
+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) |
+| Parameters | Auto-tuned quality presets | Auto-tuned quality presets |
+| Key Metric | Ground contact time | Jump height from flight time |
+
+## Critical Gotchas
+
+**Video Processing:**
+
+- Read first frame for dimensions (not OpenCV properties)
+- Handle rotation metadata (mobile videos)
+- Convert NumPy types for JSON: `int()`, `float()`
+
+**CMJ Specific:**
+
+- Use signed velocity (not absolute)
+- Backward search algorithm (find peak first)
+- Lateral view required
+
+See [Implementation Details](docs/technical/implementation-details.md) for complete technical reference.
+
+## Testing & Quality
+
+### Before Commit
+
+```bash
+uv run ruff check --fix   # Auto-fix linting
+uv run pyright            # Type check (strict)
+uv run pytest             # All 206 tests with coverage
+```
+
+### Standards
+
+- Pyright strict mode (all functions typed)
+- Ruff (100 char lines)
+- Conventional Commits (see below)
+- **Code duplication target: < 3%**
+- **Test coverage: ≥ 50% (current: 73.03% with branch coverage)**
+
+### Coverage Summary
+
+**Current:** 73.03% (206 tests, 2225 statements, 752 branches)
+
+**Coverage by tier:**
+
+- Core algorithms: 85-100% ✅ (analysis, kinematics, filtering, pose)
+- API/Integration: 63% ✅ (api.py)
+- CLI modules: 62-89% ✅ (dropjump: 88.75%, cmj: 62.27%)
+- Visualization: 10-36% ✅ (debug overlays - appropriate)
+
+**Key metrics:**
+
+- All 206 tests pass
+- 0 type errors (pyright strict)
+- 0 linting errors (ruff)
+
+See [Testing Guide](docs/development/testing.md) for:
+
+- Detailed coverage breakdown by module
+- Test file organization
+- CLI testing strategy (maintainable patterns)
+- Test breakdown by category
+
+View HTML report: `uv run pytest --cov-report=html && open htmlcov/index.html`
+
+### Code Quality
+
+- **Duplication target:** < 3% (current: 2.96%)
+- **Check:** `npx jscpd src/kinemotion`
+
+**Principles:**
+
+1. Extract common logic to shared utilities
+2. Use inheritance for shared behavior
+3. Create helper functions (testable, reusable)
+4. Use function composition (pass functions as parameters)
+
+See [Testing Guide](docs/development/testing.md) for detailed duplication avoidance strategies.
+
+## Quick Reference
+
+### CLI
+
+```bash
+# Drop jump (auto-tuned parameters)
+kinemotion dropjump-analyze video.mp4
+
+# CMJ with debug video
+kinemotion cmj-analyze video.mp4 --output debug.mp4
+
+# Batch processing
+kinemotion cmj-analyze videos/*.mp4 --batch --workers 4
+```
+
+### Python API
+
+```python
+# Drop jump
+from kinemotion import process_dropjump_video
+metrics = process_dropjump_video("video.mp4", quality="balanced")
+
+# CMJ
+from kinemotion import process_cmj_video
+metrics = process_cmj_video("video.mp4", quality="balanced")
+```
+
+## Type Safety & Dependencies
+
+**Type hints:** Use TypedDict, type aliases, NDArray[dtype]. See [Type Hints Guide](docs/development/type-hints.md).
+
+**Key versions:**
+
+- Python: 3.12.7
+- NumPy: 2.3.4
+- pytest: 9.0.0
+- MediaPipe: 0.10.14
+
+## Documentation
+
+Documentation follows the [Diátaxis framework](https://diataxis.fr/):
+
+- **guides/** - How-to tutorials
+- **reference/** - Technical specs
+- **technical/** - Implementation details
+- **development/** - Testing, typing, contribution guides
+- **research/** - Background theory
+
+See [docs/README.md](docs/README.md) for complete navigation.
+
+## 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
+```
+
+**Important**: Commit messages must never reference Claude or AI assistance. Keep messages professional and focused on the technical changes.
+
+## MCP Servers
+
+Configured in `.mcp.json`: web-search, sequential-thinking, context7, etc.

{kinemotion-0.21.0 → kinemotion-0.22.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.21.0
+Version: 0.22.1
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion

kinemotion-0.22.1/docs/development/testing.md

@@ -0,0 +1,311 @@
+# Testing Guide
+
+Comprehensive guide to testing in the Kinemotion project.
+
+## Current Coverage
+
+**Overall:** 73.03% (2225 statements, 752 branches, 206 tests)
+
+### Coverage by Module Category
+
+#### Perfect Coverage (100%)
+
+- Init files (`__init__.py` modules)
+- CMJ joint angles: 100.00%
+
+#### Excellent Coverage (85-99%)
+
+- Drop jump CLI: 88.75%
+- CMJ analysis: 88.24%
+- Drop jump analysis: 86.26%
+- CMJ kinematics: 95.65%
+- Drop jump kinematics: 85.71%
+- Core video I/O: 91.09%
+- Main CLI: 88.89%
+- Core pose tracking: 88.46%
+- Core filtering: 87.80%
+
+#### Good Coverage (60-84%)
+
+- Core smoothing: 73.29%
+- Core auto-tuning: 69.66%
+- CMJ CLI: 62.27%
+- Core CLI utils: 64.23%
+- API module: 62.89%
+- Core debug overlay utils: 80.43%
+
+#### Expected Lower Coverage (Visualization/UI)
+
+- Debug overlays: 10-36% (visualization code - appropriate for UI layer)
+
+### Coverage Targets by Module Type
+
+| Module Type     | Target Coverage | Current | Status         |
+| --------------- | --------------- | ------- | -------------- |
+| Core algorithms | 80%+            | 85-100% | ✅ Exceeded    |
+| API/Integration | 60-70%          | 63%     | ✅ Met         |
+| CLI modules     | 40-60%          | 62-89%  | ✅ Exceeded    |
+| Visualization   | 20-40%          | 10-36%  | ✅ Appropriate |
+
+## Test File Organization
+
+```
+tests/
+├── test_cli_dropjump.py      # Drop jump CLI integration (17 tests)
+├── test_cli_cmj.py            # CMJ CLI integration (17 tests)
+├── test_cli_imports.py        # CLI import verification (5 tests)
+├── test_api.py                # Public API tests (19 tests)
+├── test_cmj_analysis.py       # CMJ phase detection (31 tests)
+├── test_contact_detection.py  # Drop jump detection (12 tests)
+├── test_cmj_kinematics.py     # CMJ metrics (4 tests)
+├── test_kinematics.py         # Drop jump metrics (2 tests)
+├── test_joint_angles.py       # Triple extension (48 tests)
+├── test_adaptive_threshold.py # Auto-tuning (10 tests)
+├── test_filtering.py          # Signal filtering (15 tests)
+├── test_aspect_ratio.py       # Video I/O (13 tests)
+├── test_com_estimation.py     # Center of mass (6 tests)
+└── test_polyorder.py          # Savitzky-Golay (5 tests)
+```
+
+### Test Breakdown by Category
+
+- **Analysis module tests:** 43 tests (edge cases, helper functions, debug modes)
+- **API tests:** 19 tests (helper functions, verbose mode, outputs)
+- **CLI integration tests:** 34 tests (CliRunner-based, Tier 1 + Tier 2)
+- **Kinematics tests:** 8 tests
+- **Joint angles tests:** 48 tests
+- **Other core tests:** 54 tests
+
+## CLI Testing Strategy
+
+The project uses **maintainable CLI testing** with Click's CliRunner to achieve 62-89% coverage on CLI modules without brittle hardcoded strings.
+
+### Maintainable Test Patterns
+
+#### Pattern 1: Test Exit Codes (Most Stable)
+
+```python
+from click.testing import CliRunner
+
+def test_command_succeeds(cli_runner, minimal_video):
+    result = cli_runner.invoke(command, [str(minimal_video), '--quality', 'fast'])
+
+    # ✅ STABLE: Exit codes rarely change
+    assert result.exit_code == 0
+```
+
+#### Pattern 2: Test Behavior, Not Output
+
+```python
+def test_json_output_created(cli_runner, minimal_video, tmp_path):
+    json_output = tmp_path / "metrics.json"
+
+    result = cli_runner.invoke(
+        command,
+        [str(minimal_video), '--json-output', str(json_output)]
+    )
+
+    # ✅ STABLE: Test file creation
+    if result.exit_code == 0:
+        assert json_output.exists()
+
+        # ✅ STABLE: Test structure, not values
+        with open(json_output) as f:
+            data = json.load(f)
+        assert 'ground_contact_time_ms' in data  # Key exists
+        # ❌ DON'T: assert data['ground_contact_time_ms'] == 250.0
+```
+
+#### Pattern 3: Test CSV Structure
+
+```python
+def test_csv_summary_created(cli_runner, minimal_video, tmp_path):
+    csv_path = tmp_path / "summary.csv"
+
+    result = cli_runner.invoke(
+        command,
+        [str(minimal_video), '--batch', '--csv-summary', str(csv_path)]
+    )
+
+    if result.exit_code == 0 and csv_path.exists():
+        import csv
+
+        with open(csv_path, newline="") as f:
+            reader = csv.DictReader(f)
+            rows = list(reader)
+
+            # ✅ STABLE: Test structure
+            assert reader.fieldnames is not None  # Has headers
+            assert len(rows) >= 1  # Has data
+            # ❌ DON'T: Check specific column names or cell values
+```
+
+#### Pattern 4: Parametrized Options
+
+```python
+@pytest.mark.parametrize("quality", ["fast", "balanced", "accurate"])
+def test_quality_presets(cli_runner, minimal_video, quality):
+    result = cli_runner.invoke(
+        command,
+        [str(minimal_video), '--quality', quality]
+    )
+
+    # ✅ STABLE: Just verify option accepted
+    assert "Invalid quality" not in result.output
+```
+
+### What TO Test (CLI)
+
+#### Tier 1: Must Have (High Priority)
+
+- ✅ Help text displays (`--help`)
+- ✅ Missing video file error
+- ✅ Invalid quality preset error
+- ✅ JSON output file created
+- ✅ Debug video output created
+- ✅ All quality presets accepted
+- ✅ Expert parameters accepted
+- ✅ Command runs without crash
+
+#### Tier 2: Nice to Have (Medium Priority)
+
+- ✅ Batch mode with multiple videos
+- ✅ Output directory creation
+- ✅ CSV summary creation
+- ✅ Workers option accepted
+
+### What NOT to Test (CLI)
+
+- ❌ Exact output text (too fragile)
+- ❌ Progress bar appearance
+- ❌ Specific metric values (tested in core modules)
+- ❌ Output formatting details
+- ❌ Color codes in terminal
+
+### CLI Test Results
+
+#### Tier 1 Tests (12 per CLI = 24 total)
+
+**Coverage improvement:**
+
+- dropjump/cli.py: 23.33% → 52.08% (+28.75%)
+- cmj/cli.py: 22.73% → 51.82% (+29.09%)
+
+#### Tier 2 Tests (5 per CLI = 10 total)
+
+**Final coverage:**
+
+- dropjump/cli.py: 52.08% → 88.75% (+36.67%)
+- cmj/cli.py: 51.82% → 62.27% (+10.45%)
+
+**Total CLI tests:** 34 tests (all passing)
+
+## Avoiding Code Duplication
+
+When writing new code, follow these principles to maintain duplication below 3%:
+
+### 1. Extract Common Logic
+
+If you find yourself copying code between modules, extract it to a shared utility.
+
+**Examples:**
+
+- `core/smoothing.py` uses `_smooth_landmarks_core()` shared by both standard and advanced smoothing
+- `core/debug_overlay_utils.py` provides `BaseDebugOverlayRenderer` base class
+
+### 2. Use Inheritance for Shared Behavior
+
+When classes share common initialization or methods.
+
+**Example:**
+
+- `DebugOverlayRenderer` and `CMJDebugOverlayRenderer` inherit from `BaseDebugOverlayRenderer`
+- Avoids duplicating `__init__()`, `write_frame()`, `close()`, and context manager methods
+
+### 3. Create Helper Functions
+
+Break down complex functions into smaller, reusable pieces.
+
+**Examples:**
+
+- `_extract_landmark_coordinates()`, `_get_landmark_names()`, `_fill_missing_frames()`
+- Makes code more testable and reusable
+
+### 4. Use Function Composition
+
+Pass functions as parameters to share control flow logic.
+
+**Example:**
+
+- `_smooth_landmarks_core()` accepts a `smoother_fn` parameter
+- Allows different smoothing strategies without duplicating iteration logic
+
+### 5. Check Duplication
+
+Run `npx jscpd src/kinemotion` to verify duplication stays below 3%.
+
+**Current:** 2.96% (206 duplicated lines out of 6952)
+
+**Acceptable duplicates:**
+
+- CLI option definitions
+- Small wrapper functions for type safety
+
+## Running Tests
+
+### Quick Commands
+
+```bash
+# Run all tests with coverage
+uv run pytest
+
+# Run specific test file
+uv run pytest tests/test_cmj_analysis.py
+
+# Run tests matching pattern
+uv run pytest -k "test_edge"
+
+# Run with verbose output
+uv run pytest -v
+
+# Generate HTML coverage report
+uv run pytest --cov-report=html
+open htmlcov/index.html
+```
+
+### Coverage Reports
+
+**Terminal:** Automatic with `uv run pytest`
+
+**HTML:** `htmlcov/index.html` (open in browser)
+
+**XML:** `coverage.xml` (for CI integration)
+
+### Test Configuration
+
+Pytest 9 native TOML configuration in `pyproject.toml`:
+
+```toml
+[tool.pytest]
+minversion = "9.0"
+testpaths = ["tests"]
+console_output_style = "times"  # Per-test execution time
+strict = true                    # All strictness options enabled
+addopts = [
+    "--cov=src/kinemotion",
+    "--cov-report=term-missing",
+    "--cov-report=html",
+    "--cov-report=xml",
+    "--cov-branch",
+]
+```
+
+### Before Commit Checklist
+
+```bash
+uv run ruff check --fix   # Auto-fix linting
+uv run pyright            # Type check (strict)
+uv run pytest             # All 206 tests with coverage (73.03%)
+```
+
+All checks must pass before committing.