kinemotion 0.7.0__tar.gz → 0.8.0__tar.gz

kinemotion-0.8.0/.dockerignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Git
+.git/
+.gitignore
+.gitattributes
+
+# CI/CD
+.github/
+.pre-commit-config.yaml
+
+# Documentation
+docs/
+CHANGELOG.md
+CLAUDE.md
+*.md
+!README.md
+
+# Sample files
+samples/
+examples/
+
+# Development tools
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# MCP and Claude
+.mcp.json
+.claude/
+CLAUDE.md

kinemotion-0.8.0/.github/workflows/release.yml

@@ -0,0 +1,108 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    name: Create Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+      packages: write
+    outputs:
+      version: ${{ steps.get_version.outputs.version }}
+      released: ${{ steps.get_version.outputs.released }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.8.17"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Create Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config user.name "github-actions"
+          git config user.email "github-actions@github.com"
+          uv run semantic-release version
+
+      - name: Get version from pyproject.toml
+        id: get_version
+        run: |
+          VERSION=$(grep '^version = ' pyproject.toml | cut -d'"' -f2)
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          # Check if semantic-release created a new release by checking if there's a new tag
+          if git describe --exact-match --tags HEAD 2>/dev/null; then
+            echo "released=true" >> $GITHUB_OUTPUT
+          else
+            echo "released=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Publish to PyPI
+        if: steps.get_version.outputs.released == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  docker:
+    name: Build and Push Docker Image
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: v${{ needs.release.outputs.version }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}},value=v${{ needs.release.outputs.version }}
+            type=semver,pattern={{major}}.{{minor}},value=v${{ needs.release.outputs.version }}
+            type=semver,pattern={{major}},value=v${{ needs.release.outputs.version }}
+            type=raw,value=latest
+
+      - name: Build and push Docker image
+        id: push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          platforms: linux/amd64
+          # Multi-scope caching: Docker layers + uv cache
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

{kinemotion-0.7.0 → kinemotion-0.8.0}/.gitignore

@@ -28,7 +28,6 @@ env/
 
 # uv
 .uv/
-uv.lock
 
 # IDEs
 .vscode/

{kinemotion-0.7.0 → kinemotion-0.8.0}/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.8.0 (2025-11-02)
+
+### Features
+
+- Add Docker support and GitHub Container Registry publishing
+  ([`249ca4c`](https://github.com/feniix/kinemotion/commit/249ca4c0c0ab40cda5acfebac012db8075b9694f))
+
+
+## v0.7.1 (2025-11-01)
+
+### Bug Fixes
+
+- Update documentation for auto-tuning system
+  ([`6c1a135`](https://github.com/feniix/kinemotion/commit/6c1a135acf5cce7a627644dbc6393460277906ad))
+
+
 ## v0.7.0 (2025-11-01)
 
 ### Features

kinemotion-0.8.0/Dockerfile

@@ -0,0 +1,96 @@
+# Multi-stage Dockerfile for kinemotion
+# Optimized for Python 3.12, uv, OpenCV, and MediaPipe
+# Note: Only linux/amd64 platform supported (MediaPipe lacks ARM64 Linux wheels)
+
+# ============================================================================
+# Stage 1: Builder - Install dependencies with uv
+# ============================================================================
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
+
+# Optimization: Compile Python bytecode at build time for faster startup
+# Optimization: Copy mode for dependencies to work across build stages
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy
+
+WORKDIR /app
+
+# Install dependencies FIRST (cached layer - only invalidated when dependencies change)
+# Use bind mounts to avoid copying files into the image
+# Use cache mount to reuse uv downloads across builds
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-project --no-dev
+
+# Copy source code AFTER dependencies (source changes don't invalidate dependency cache)
+COPY . /app
+
+# Install the project itself as a non-editable package (fast since dependencies are already installed)
+# --no-editable ensures the package is properly installed, not as editable
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev --no-editable
+
+# ============================================================================
+# Stage 2: Runtime - Minimal production image
+# ============================================================================
+FROM python:3.12-slim-bookworm AS runtime
+
+# Install system dependencies required by OpenCV and MediaPipe
+# - libgl1: OpenGL library for OpenCV
+# - libglib2.0-0: GLib library for MediaPipe
+# - libgomp1: GNU OpenMP library for multi-threading
+# - ffmpeg: Video codec support for OpenCV
+# hadolint ignore=DL3008
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgl1 \
+    libglib2.0-0 \
+    libgomp1 \
+    ffmpeg \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy virtual environment from builder (contains installed package)
+COPY --from=builder /app/.venv /app/.venv
+
+# Set environment variables
+# PATH: Use virtual environment binaries
+# PYTHONUNBUFFERED: Force stdout/stderr to be unbuffered for real-time logging
+# PYTHONDONTWRITEBYTECODE: Don't create .pyc files (saves space)
+ENV PATH="/app/.venv/bin:$PATH" \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+# Create non-root user for security
+RUN useradd -m -u 1000 kinemotion && \
+    chown -R kinemotion:kinemotion /app
+
+USER kinemotion
+
+# Verify installation
+RUN python -c "import kinemotion; print('kinemotion installed successfully')"
+
+# Set entrypoint to kinemotion CLI
+ENTRYPOINT ["kinemotion"]
+
+# Default command: show help
+CMD ["--help"]
+
+# ============================================================================
+# Usage examples:
+#
+# Build:
+#   docker build -t kinemotion:latest .
+#
+# Run with help:
+#   docker run --rm kinemotion:latest --help
+#
+# Analyze video:
+#   docker run --rm -v $(pwd):/data kinemotion:latest \
+#     dropjump-analyze /data/video.mp4 --drop-height 0.40 \
+#     --output /data/debug.mp4 --json-output /data/metrics.json
+#
+# Interactive shell:
+#   docker run --rm -it --entrypoint /bin/bash kinemotion:latest
+# ============================================================================

{kinemotion-0.7.0 → kinemotion-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.7.0
+Version: 0.8.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
@@ -100,18 +100,21 @@ 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.
+
 ### Basic Analysis
 
-Analyze a video and output metrics to stdout as JSON:
+Analyze a video with automatic parameter selection:
 
 ```bash
-kinemotion dropjump-analyze video.mp4
+# 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 --json-output metrics.json
+kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --json-output metrics.json
 ```
 
 ### Generate Debug Video
@@ -119,156 +122,104 @@ kinemotion dropjump-analyze video.mp4 --json-output metrics.json
 Create an annotated video showing pose tracking and contact detection:
 
 ```bash
-kinemotion dropjump-analyze video.mp4 --output debug.mp4
+kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --output debug.mp4
 ```
 
-### Calibrated Drop Jump Analysis
+### Complete Analysis
 
-For most accurate measurements, provide the drop box height in meters:
+With all outputs:
 
 ```bash
-# 40cm drop box
-kinemotion dropjump-analyze drop-jump.mp4 --drop-height 0.40
-
-# 60cm drop box with full outputs
-kinemotion dropjump-analyze drop-jump.mp4 \
-  --drop-height 0.60 \
-  --json-output metrics.json \
-  --output debug.mp4
+kinemotion dropjump-analyze video.mp4 \
+  --drop-height 0.40 \
+  --output debug.mp4 \
+  --json-output results.json
 ```
 
-### Full Example (Maximum Accuracy)
+### Quality Presets
+
+Choose analysis quality (automatically adjusts all parameters):
 
 ```bash
-# With all accuracy improvements enabled
-kinemotion dropjump-analyze jump.mp4 \
-  --outlier-rejection \
-  --drop-height 0.40 \
-  --output debug.mp4 \
-  --json-output results.json \
-  --smoothing-window 7 \
-  --polyorder 3
+# Fast analysis (quick, less precise - good for batch processing)
+kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --quality fast
 
-# Alternative: With experimental bilateral filter
-kinemotion dropjump-analyze jump.mp4 \
-  --outlier-rejection \
-  --bilateral-filter \
+# Balanced (default - best for most use cases)
+kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --quality balanced
+
+# Accurate (research-grade, slower - maximum precision)
+kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --quality accurate
+```
+
+### See Auto-Selected Parameters
+
+View what parameters were automatically selected:
+
+```bash
+kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --verbose
+```
+
+### Expert Mode (Advanced Users)
+
+Override auto-tuned parameters if needed:
+
+```bash
+# Manual parameter override (rarely needed)
+kinemotion dropjump-analyze video.mp4 \
   --drop-height 0.40 \
-  --output debug.mp4 \
-  --json-output results.json
+  --expert \
+  --smoothing-window 7 \
+  --velocity-threshold 0.015
 ```
 
 ## Configuration Options
 
-> **📖 For detailed explanations of all parameters, see [docs/PARAMETERS.md](docs/PARAMETERS.md)**
->
-> This section provides a quick reference. The full guide includes:
->
-> - How each parameter works internally
-> - When and why to adjust them
-> - Scenario-based recommendations
-> - Debugging workflows
-> - Parameter interaction effects
-
-### Smoothing
-
-- `--smoothing-window <int>` (default: 5)
-  - Window size for Savitzky-Golay smoothing filter
-  - Must be odd and >= 3
-  - Larger values = smoother trajectories but less responsive
-  - **Tip**: Increase for noisy videos, decrease for high-quality stable footage
-
-- `--polyorder <int>` (default: 2)
-  - Polynomial order for Savitzky-Golay smoothing filter
-  - Must be < smoothing-window (typically 2 or 3)
-  - 2 = quadratic fit (good for parabolic motion like jumps)
-  - 3 = cubic fit (better for complex motion patterns)
-  - Higher order captures more motion complexity but more sensitive to noise
-  - **Tip**: Use 2 for most cases, try 3 for high-quality videos with complex motion
-  - **Accuracy improvement**: +1-2% for complex motion patterns
-
-### Advanced Filtering
-
-- `--outlier-rejection / --no-outlier-rejection` (default: --outlier-rejection)
-  - Apply RANSAC and median-based outlier rejection to remove tracking glitches
-  - **With outlier rejection** (`--outlier-rejection`): Detects and removes MediaPipe tracking errors
-    - RANSAC-based polynomial fitting identifies positions that deviate from smooth trajectory
-    - Median filtering catches spikes in otherwise smooth motion
-    - Outliers replaced with interpolated values from neighboring valid points
-    - Removes jumps, jitter, and temporary tracking losses
-    - **Accuracy improvement**: +1-2% by eliminating tracking glitches
-  - **Without outlier rejection** (`--no-outlier-rejection`): Uses raw tracked positions
-    - Faster processing, relies entirely on MediaPipe quality
-  - **Tip**: Keep enabled (default) unless debugging or working with perfect tracking
-
-- `--bilateral-filter / --no-bilateral-filter` (default: --no-bilateral-filter)
-  - Use bilateral temporal filter for edge-preserving smoothing
-  - **With bilateral filter** (`--bilateral-filter`): Preserves sharp transitions while smoothing noise
-    - Weights each frame by temporal distance AND position similarity
-    - Landing/takeoff transitions remain sharp (not smoothed away)
-    - Noise in smooth regions (flight, ground contact) is reduced
-    - Edge-preserving alternative to Savitzky-Golay smoothing
-    - **Accuracy improvement**: +1-2% by preserving event timing precision
-  - **Without bilateral filter** (`--no-bilateral-filter`): Uses standard Savitzky-Golay smoothing
-    - Uniform smoothing across all frames
-    - Well-tested baseline method
-  - **Tip**: Experimental feature; enable for videos with rapid transitions or variable motion
-  - **Note**: Cannot be used simultaneously with Savitzky-Golay; bilateral replaces it when enabled
-
-### Contact Detection
-
-- `--velocity-threshold <float>` (default: 0.02)
-  - Vertical velocity threshold for detecting stationary feet
-  - In normalized coordinates (0-1 range)
-  - Lower values = more sensitive (may detect false contacts)
-  - Higher values = less sensitive (may miss brief contacts)
-  - **Tip**: Start with default, decrease if missing contacts, increase if detecting false contacts
-
-- `--min-contact-frames <int>` (default: 3)
-  - Minimum consecutive frames to confirm ground contact
-  - Filters out momentary tracking glitches
-  - **Tip**: Increase for noisy videos with jittery tracking
-
-### Visibility
-
-- `--visibility-threshold <float>` (default: 0.5)
-  - Minimum MediaPipe visibility score (0-1) to trust a landmark
-  - Higher values require more confident tracking
-  - **Tip**: Lower if landmarks are frequently obscured but tracking seems reasonable
-
-### Pose Tracking
-
-- `--detection-confidence <float>` (default: 0.5)
-  - MediaPipe pose detection confidence threshold
-  - **Tip**: Increase if getting false pose detections
-
-- `--tracking-confidence <float>` (default: 0.5)
-  - MediaPipe pose tracking confidence threshold
-  - **Tip**: Increase if tracking is jumping between different people/objects
-
-### Calibration
-
-- `--drop-height <float>` (optional)
+### Intelligent Auto-Tuning
+
+Kinemotion automatically optimizes parameters based on your video:
+- **FPS-based scaling**: 30fps, 60fps, 120fps videos use different thresholds automatically
+- **Quality-based adjustments**: Adapts smoothing based on MediaPipe tracking confidence
+- **Always enabled**: Outlier rejection, curvature analysis, drop start detection
+
+### Required Parameters
+
+- `--drop-height <float>` **[REQUIRED]**
   - Height of drop box/platform in meters (e.g., 0.40 for 40cm)
-  - Enables calibrated jump height measurement using known drop height
-  - Theoretically improves accuracy (⚠️ unvalidated - requires empirical validation)
-  - Only applicable for drop jumps (box → drop → landing → jump)
-  - **Tip**: Measure your box height accurately for best results
-
-### Trajectory Analysis
-
-- `--use-curvature / --no-curvature` (default: --use-curvature)
-  - Enable/disable trajectory curvature analysis for refining transitions
-  - **With curvature** (`--use-curvature`): Uses acceleration patterns to refine event timing
-    - Landing detection: Finds acceleration spike from impact deceleration
-    - Takeoff detection: Finds acceleration change as body transitions from static to upward motion
-    - Blends curvature-based refinement (70%) with velocity-based estimate (30%)
-    - Provides physics-based validation of velocity threshold crossings
-    - **Accuracy improvement**: More precise timing, especially for rapid transitions
-  - **Without curvature** (`--no-curvature`): Pure velocity-based detection with sub-frame interpolation
-    - Simpler, faster algorithm
-    - Still highly accurate with smooth velocity curves
-  - **Tip**: Keep enabled (default) for best results; disable only for debugging or comparison
+  - Used for accurate calibration of jump height measurements
+  - Measure your box height accurately for best results
+
+### Optional Parameters
+
+- `--quality [fast|balanced|accurate]` (default: balanced)
+  - **fast**: Quick analysis, less precise (~50% faster)
+  - **balanced**: Good accuracy/speed tradeoff (recommended)
+  - **accurate**: Research-grade analysis, slower (maximum precision)
+
+- `--verbose` / `-v`
+  - Show auto-selected parameters and analysis details
+  - Useful for understanding what the tool is doing
+
+- `--output <path>` / `-o`
+  - Generate annotated debug video with pose tracking visualization
+
+- `--json-output <path>` / `-j`
+  - Save metrics to JSON file instead of stdout
+
+### Expert Overrides (Rarely Needed)
+
+For advanced users who need manual control:
+
+- `--drop-start-frame <int>`: Manually specify where drop begins (if auto-detection fails)
+- `--smoothing-window <int>`: Override auto-tuned smoothing window
+- `--velocity-threshold <float>`: Override auto-tuned velocity threshold
+- `--min-contact-frames <int>`: Override auto-tuned minimum contact frames
+- `--visibility-threshold <float>`: Override visibility threshold
+- `--detection-confidence <float>`: Override MediaPipe detection confidence
+- `--tracking-confidence <float>`: Override MediaPipe tracking confidence
+
+> **📖 For detailed parameter explanations, see [docs/PARAMETERS.md](docs/PARAMETERS.md)**
+>
+> **Note:** Most users never need expert parameters - auto-tuning handles optimization automatically!
 
 ## Output Format