kinemotion-development

# Kinemotion Development Standards ## Pre-Commit Checklist Always run before committing: ```bash uv run ruff check --fix # Auto-fix linting uv run ruff format # Format code uv run pyright # Type check (strict) uv run pytest # Run all tests ``` Or combined: ```bash uv run ruff check --fix && uv run ruff format && uv run pyright && uv run pytest ``` ## Quality Targets | Metric | Target | Current | | ---------------- | ------ | ------- | | Test coverage | ≥ 50% | 80.86% | | Code duplication | < 3% | 2.96% | | Type errors | 0 | 0 | | Lint errors | 0 | 0 | Check duplication: `npx jscpd src/kinemotion` ## Type Hints - Use `NDArray[np.float64]` for numpy arrays - Use `TypedDict` for metric dictionaries - Use `Literal` for string unions - Pyright strict mode enforced ```python from numpy.typing import NDArray from typing import TypedDict, Literal QualityPreset = Literal["fast", "balanced", "accurate"] class CMJMetrics(TypedDict): jump_height_cm: float flight_time_ms: float ``` ## Module Structure ``` src/kinemotion/ ├── cli.py # Main CLI entry point ├── api.py # Public Python API ├── core/ # Shared utilities │ ├── validation.py # Base validation classes │ ├── pose.py # MediaPipe wrapper │ ├── filtering.py # Signal processing │ └── video_io.py # Video I/O handling ├── cmj/ # CMJ analysis module │ ├── cli.py # CMJ CLI subcommand │ ├── analysis.py # Core CMJ algorithm │ ├── kinematics.py # Velocity, position calc │ └── validation_bounds.py # CMJ-specific bounds └── dropjump/ # Drop jump module ├── cli.py # Drop jump CLI subcommand ├── analysis.py # Core drop jump algorithm └── validation_bounds.py # Drop jump bounds ``` ## Testing ### Structure Mirror source: `tests/core/`, `tests/cmj/`, `tests/dropjump/`, `tests/cli/` ### Fixtures Use centralized fixtures from `tests/conftest.py`: - `cli_runner`: Click test runner - `minimal_video`: Synthetic test video - `sample_video_path`: Path to test fixture ### Edge Cases to Test - Empty arrays - Single frame videos - NaN values in landmarks - Missing landmarks (occlusion) - Zero velocity scenarios ```python @pytest.mark.parametrize("input_data,expected", [ (np.array([]), None), # Empty (np.array([1.0]), 1.0), # Single value (np.array([np.nan, 1.0, 2.0]), None), # NaN handling ]) def test_edge_cases(input_data, expected): ... ``` ## Key Algorithm Differences | Aspect | CMJ | Drop Jump | | ----------------- | -------------------------- | -------------------- | | Search direction | Backward (from peak) | Forward | | Velocity type | Signed (direction matters) | Absolute (magnitude) | | Key phase | Countermovement detection | Ground contact | | Starting position | Floor level | Elevated (box) | ## Common Gotchas 1. **CMJ velocity must be signed** - backward search requires knowing direction 2. **Convert NumPy for JSON** - use `int()`, `float()` before serialization 3. **Handle video rotation** - mobile videos have rotation metadata 4. **Read first frame for dimensions** - don't trust OpenCV properties ## Commit Format Use Conventional Commits: ``` <type>(<scope>): <description> Types: feat, fix, docs, test, refactor, perf, chore ``` Examples: ``` feat(cmj): add triple extension tracking fix(dropjump): correct ground contact detection test(core): add filtering edge case tests ``` ## Code Style - 88 character line limit (ruff) - Use early returns to reduce nesting - Extract methods for complexity > 15 - Prefer composition over inheritance - Single Responsibility for all functions ## Adding New Analysis Type 1. Create module directory: `src/kinemotion/<type>/` 2. Implement: `cli.py`, `analysis.py`, `kinematics.py` 3. Add validation bounds in `validation_bounds.py` 4. Register CLI in main `cli.py` 5. Export in `api.py` and `__init__.py` 6. Add tests mirroring structure 7. Update CLAUDE.md quick reference