kinemotion 0.18.0__tar.gz → 0.22.0__tar.gz

{kinemotion-0.18.0 → kinemotion-0.22.0}/.github/workflows/docs.yml

@@ -1,25 +1,19 @@
 name: Documentation
 
 on:
-  # Trigger after release workflow completes (which bumps version)
-  workflow_run:
-    workflows: ["Release"]
-    types:
-      - completed
-    branches: [main]
-  # Also allow manual trigger and PR builds
+  # Build docs on PRs for validation (not deployed)
   pull_request:
     branches: [main]
-  workflow_dispatch:
+  # Called by release workflow for deployment
+  workflow_call:
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v4
         with:
-          # Check out main to get the version bump commit from semantic-release
-          ref: main
           fetch-depth: 0
 
       - name: Set up Python
@@ -27,9 +21,10 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@v3
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
         with:
+          version: "0.8.17"
           enable-cache: true
 
       - name: Install dependencies
@@ -47,29 +42,33 @@ jobs:
           path: site/
 
   deploy:
-    # Deploy only after successful release workflow, not on PRs
-    if: github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success'
+    name: Deploy to GitHub Pages
+    # Only deploy when called from release workflow, not on PRs
+    if: github.event_name == 'workflow_call'
     needs: build
     runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout repository
+        uses: actions/checkout@v4
         with:
           ref: main
-          fetch-depth: 0  # Fetch all history for gh-deploy
+          fetch-depth: 0
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.12"
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@v3
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.8.17"
+          enable-cache: true
 
       - name: Install dependencies
-        run: |
-          uv sync --frozen
+        run: uv sync --frozen
 
       - name: Configure git
         run: |
@@ -77,5 +76,4 @@ jobs:
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
       - name: Deploy to GitHub Pages
-        run: |
-          uv run mkdocs gh-deploy --force
+        run: uv run mkdocs gh-deploy --force

{kinemotion-0.18.0 → kinemotion-0.22.0}/.github/workflows/release.yml

@@ -66,6 +66,14 @@ jobs:
         if: steps.get_version.outputs.released == 'true'
         uses: pypa/gh-action-pypi-publish@release/v1
 
+  docs:
+    name: Deploy Documentation
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    uses: ./.github/workflows/docs.yml
+    permissions:
+      contents: write
+
   docker:
     name: Build and Push Docker Image
     needs: release

{kinemotion-0.18.0 → kinemotion-0.22.0}/.pre-commit-config.yaml

@@ -15,12 +15,12 @@ repos:
       - id: mixed-line-ending
 
   - repo: https://github.com/psf/black
-    rev: 25.9.0
+    rev: 25.11.0
     hooks:
       - id: black
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.3
+    rev: v0.14.4
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

{kinemotion-0.18.0 → kinemotion-0.22.0}/CHANGELOG.md

@@ -7,6 +7,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## 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
+
+- Add TypedDict and type aliases for improved type safety
+  ([`053e010`](https://github.com/feniix/kinemotion/commit/053e010cf80e1c91d5900c39d49b1d7ac2ac6ab4))
+
+
+## v0.20.2 (2025-11-10)
+
+### Bug Fixes
+
+- Achieve 80%+ coverage on video_io for SonarCloud quality gate
+  ([`ed77fdb`](https://github.com/feniix/kinemotion/commit/ed77fdb080f143c492c724c9f4a138b2a364ad7e))
+
+
+## v0.20.1 (2025-11-10)
+
+### Bug Fixes
+
+- Add test coverage for ffprobe warning path
+  ([`8ae3e55`](https://github.com/feniix/kinemotion/commit/8ae3e552a3bfb749d4e9bad10c634093db5eddee))
+
+
+## v0.20.0 (2025-11-10)
+
+### Features
+
+- Add platform-specific installation guide and ffprobe warnings
+  ([`b61c8c6`](https://github.com/feniix/kinemotion/commit/b61c8c6dbc2191ca321a2b813aa995c3a68b0b0b))
+
+
+## v0.19.0 (2025-11-10)
+
+### Features
+
+- Add comprehensive badge layout to README
+  ([`e1e2ca3`](https://github.com/feniix/kinemotion/commit/e1e2ca38c67077092bfc1455acfbe8a424e5d4b4))
+
+
+## v0.18.2 (2025-11-10)
+
+### Bug Fixes
+
+- Ci build
+  ([`5bbfc0f`](https://github.com/feniix/kinemotion/commit/5bbfc0fa610ff811e765dea2021602f09d02f9f8))
+
+### Testing
+
+- Add comprehensive test coverage for joint angles and CMJ analysis
+  ([`815c9be`](https://github.com/feniix/kinemotion/commit/815c9be1019414acf61563312a5d58f6305a17a4))
+
+
+## v0.18.1 (2025-11-10)
+
+### Bug Fixes
+
+- Ci build
+  ([`f45e2c3`](https://github.com/feniix/kinemotion/commit/f45e2c3c11ae241d24de3e44836206e111defc2a))
+
+### Refactoring
+
+- **ci**: Use reusable workflow for docs deployment
+  ([`013dbd1`](https://github.com/feniix/kinemotion/commit/013dbd112cd5bcbe69bc405066b39bb142996d46))
+
+
 ## v0.18.0 (2025-11-10)
 
 ### Bug Fixes

kinemotion-0.22.0/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.18.0 → kinemotion-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.18.0
+Version: 0.22.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
@@ -30,13 +30,18 @@ Description-Content-Type: text/markdown
 # Kinemotion
 
 [![PyPI version](https://img.shields.io/pypi/v/kinemotion.svg)](https://pypi.org/project/kinemotion/)
+[![Python Version](https://img.shields.io/pypi/pyversions/kinemotion.svg)](https://pypi.org/project/kinemotion/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![Type checked with pyright](https://img.shields.io/badge/type%20checked-pyright-blue.svg)](https://github.com/microsoft/pyright)
+
+[![Tests](https://github.com/feniix/kinemotion/workflows/Test%20%26%20Quality/badge.svg)](https://github.com/feniix/kinemotion/actions)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=feniix_kinemotion&metric=alert_status)](https://sonarcloud.io/summary/overall?id=feniix_kinemotion)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=feniix_kinemotion&metric=coverage)](https://sonarcloud.io/summary/overall?id=feniix_kinemotion)
+
 [![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)
+[![Type checked with pyright](https://img.shields.io/badge/type%20checked-pyright-blue.svg)](https://github.com/microsoft/pyright)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
 
-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.
+> 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:**
 
@@ -88,27 +93,70 @@ For clinical, research, or performance assessment requiring validated accuracy,
 
 ## Setup
 
-### Prerequisites
+### System Requirements
+
+**All Platforms:**
+
+- Python 3.10, 3.11, or 3.12
+
+**Platform-Specific:**
+
+#### Windows
 
-- [asdf](https://asdf-vm.com/) version manager
-- asdf plugins for Python and uv
+No additional system dependencies required.
 
-### Installation
+**Recommended for mobile video support:**
 
-1. **Install asdf plugins** (if not already installed):
+- [FFmpeg](https://ffmpeg.org/download.html) - Download and add to PATH
+
+#### macOS
+
+No additional system dependencies required.
+
+**Recommended for mobile video support:**
+
+```bash
+brew install ffmpeg
+```
+
+#### Linux (Ubuntu/Debian)
+
+**Recommended system libraries:**
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+    libgl1-mesa-glx \
+    libglib2.0-0 \
+    ffmpeg
+```
+
+**Note:** `ffmpeg` provides the `ffprobe` tool for video metadata extraction (rotation, aspect ratio). Kinemotion works without it, but mobile/rotated videos may not process correctly. A warning will be shown if `ffprobe` is not available.
+
+### Installation Methods
+
+#### From PyPI (Recommended)
+
+```bash
+pip install kinemotion
+```
+
+#### From Source (Development)
+
+**Step 1:** Install asdf plugins (if not already installed):
 
 ```bash
 asdf plugin add python
 asdf plugin add uv
 ```
 
-1. **Install versions specified in `.tool-versions`**:
+**Step 2:** Install versions specified in `.tool-versions`:
 
 ```bash
 asdf install
 ```
 
-1. **Install project dependencies using uv**:
+**Step 3:** Install project dependencies using uv:
 
 ```bash
 uv sync
@@ -120,7 +168,7 @@ This will install all dependencies and make the `kinemotion` command available.
 
 Kinemotion supports two jump types with intelligent auto-tuning that automatically optimizes parameters based on video characteristics.
 
-### Drop Jump Analysis
+### Analyzing Drop Jumps
 
 Analyzes reactive strength and ground contact time:
 
@@ -129,7 +177,7 @@ Analyzes reactive strength and ground contact time:
 kinemotion dropjump-analyze video.mp4
 ```
 
-### Counter Movement Jump (CMJ) Analysis
+### Analyzing CMJ
 
 Analyzes jump height and biomechanics: