kinemotion-development

Kinemotion Development Standards

Pre-Commit Checklist

Always run before committing:

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:

uv run ruff check --fix && uv run ruff format && uv run pyright && uv run pytest

Quality Targets

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

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

@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

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