kinemotion 0.18.2__tar.gz → 0.20.0__tar.gz

{kinemotion-0.18.2 → kinemotion-0.20.0}/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## 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

{kinemotion-0.18.2 → kinemotion-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.18.2
+Version: 0.20.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:
 

{kinemotion-0.18.2 → kinemotion-0.20.0}/README.md

@@ -1,13 +1,18 @@
 # 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:**
 
@@ -59,27 +64,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
@@ -91,7 +139,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:
 
@@ -100,7 +148,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:
 

{kinemotion-0.18.2 → kinemotion-0.20.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kinemotion"
-version = "0.18.2"
+version = "0.20.0"
 description = "Video-based kinematic analysis for athletic performance"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"

{kinemotion-0.18.2 → kinemotion-0.20.0}/src/kinemotion/core/video_io.py

@@ -2,6 +2,7 @@
 
 import json
 import subprocess
+import warnings
 
 import cv2
 import numpy as np
@@ -147,8 +148,17 @@ class VideoProcessor:
             # Extract rotation from side_data_list (common for iPhone videos)
             self.rotation = self._extract_rotation_from_stream(stream)
 
-        except (subprocess.TimeoutExpired, FileNotFoundError, json.JSONDecodeError):
-            # If ffprobe fails, keep original dimensions (square pixels)
+        except FileNotFoundError:
+            # ffprobe not found - warn user about reduced functionality
+            warnings.warn(
+                "ffprobe not found. Video rotation and aspect ratio metadata will be "
+                "ignored. This may cause issues with mobile/rotated videos. "
+                "Install FFmpeg for full video support: https://ffmpeg.org/download.html",
+                UserWarning,
+                stacklevel=2,
+            )
+        except (subprocess.TimeoutExpired, json.JSONDecodeError):
+            # If ffprobe fails for other reasons, silently continue with defaults
             pass
 
     def read_frame(self) -> np.ndarray | None:

{kinemotion-0.18.2 → kinemotion-0.20.0}/uv.lock

@@ -700,7 +700,7 @@ wheels = [
 
 [[package]]
 name = "kinemotion"
-version = "0.18.2"
+version = "0.20.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },