kinemotion 0.1.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

{kinemotion-0.1.0.dist-info → kinemotion-0.4.0.dist-info}/METADATA

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.1.0
+Version: 0.4.0
 Summary: Video-based kinematic analysis for athletic performance
-Project-URL: Homepage, https://github.com/feniix/kinemetry
-Project-URL: Repository, https://github.com/feniix/kinemetry
-Project-URL: Issues, https://github.com/feniix/kinemetry/issues
+Project-URL: Homepage, https://github.com/feniix/kinemotion
+Project-URL: Repository, https://github.com/feniix/kinemotion
+Project-URL: Issues, https://github.com/feniix/kinemotion/issues
 Author-email: Sebastian Otaegui <feniix@gmail.com>
 License: MIT
 License-File: LICENSE
-Keywords: athletic-performance,drop-jump,kinemetry,mediapipe,pose-tracking,video-analysis
+Keywords: athletic-performance,drop-jump,kinemetry,kinemotion,mediapipe,pose-tracking,video-analysis
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -26,7 +26,7 @@ Requires-Dist: opencv-python>=4.9.0
 Requires-Dist: scipy>=1.11.0
 Description-Content-Type: text/markdown
 
-# Kinemetry
+# Kinemotion
 
 A video-based kinematic analysis tool for athletic performance. Analyzes side-view drop-jump videos to estimate key performance metrics: ground contact time, flight time, and jump height. Uses MediaPipe pose tracking and advanced kinematics.
 
@@ -42,11 +42,25 @@ A video-based kinematic analysis tool for athletic performance. Analyzes side-vi
   - Ground contact time (ms)
   - Flight time (ms)
   - Jump height (m) - with optional calibration using drop box height
-- **Calibrated measurements** - use known drop height for ~88% accuracy (vs 71% uncalibrated)
+- **Calibrated measurements** - use known drop height for theoretically improved accuracy (⚠️ accuracy claims unvalidated)
 - **JSON output** for easy integration with other tools
 - **Optional debug video** with visual overlays showing contact states and landmarks
 - **Configurable parameters** for smoothing, thresholds, and detection
 
+**Note**: Drop jump analysis uses foot-based tracking with fixed velocity thresholds. Center of mass (CoM) tracking and adaptive thresholding (available in `core/` modules) require longer videos (~5+ seconds) with a 3-second standing baseline, making them unsuitable for typical drop jump videos (~3 seconds). These features may be available in future jump types like CMJ (countermovement jump).
+
+## Validation Status
+
+⚠️ **IMPORTANT**: This tool's accuracy has **not been validated** against gold standard measurements (force plates, 3D motion capture). All accuracy claims and improvement estimates are theoretical and based on algorithmic considerations, not empirical testing.
+
+The tool provides consistent measurements and may be useful for:
+
+- Tracking relative changes in an individual athlete over time
+- Comparing similar jumps under controlled conditions
+- Exploratory analysis and research
+
+For clinical, research, or performance assessment requiring validated accuracy, this tool should be compared against validated measurement systems before use.
+
 ## Setup
 
 ### Prerequisites
@@ -63,19 +77,19 @@ asdf plugin add python
 asdf plugin add uv
 ```
 
-2. **Install versions specified in `.tool-versions`**:
+1. **Install versions specified in `.tool-versions`**:
 
 ```bash
 asdf install
 ```
 
-3. **Install project dependencies using uv**:
+1. **Install project dependencies using uv**:
 
 ```bash
 uv sync
 ```
 
-This will install all dependencies and make the `kinemetry` command available.
+This will install all dependencies and make the `kinemotion` command available.
 
 ## Usage
 
@@ -84,13 +98,13 @@ This will install all dependencies and make the `kinemetry` command available.
 Analyze a video and output metrics to stdout as JSON:
 
 ```bash
-kinemetry dropjump-analyze video.mp4
+kinemotion dropjump-analyze video.mp4
 ```
 
 ### Save Metrics to File
 
 ```bash
-kinemetry dropjump-analyze video.mp4 --json-output metrics.json
+kinemotion dropjump-analyze video.mp4 --json-output metrics.json
 ```
 
 ### Generate Debug Video
@@ -98,7 +112,7 @@ kinemetry dropjump-analyze video.mp4 --json-output metrics.json
 Create an annotated video showing pose tracking and contact detection:
 
 ```bash
-kinemetry dropjump-analyze video.mp4 --output debug.mp4
+kinemotion dropjump-analyze video.mp4 --output debug.mp4
 ```
 
 ### Calibrated Drop Jump Analysis
@@ -107,24 +121,34 @@ For most accurate measurements, provide the drop box height in meters:
 
 ```bash
 # 40cm drop box
-kinemetry dropjump-analyze drop-jump.mp4 --drop-height 0.40
+kinemotion dropjump-analyze drop-jump.mp4 --drop-height 0.40
 
 # 60cm drop box with full outputs
-kinemetry dropjump-analyze drop-jump.mp4 \
+kinemotion dropjump-analyze drop-jump.mp4 \
   --drop-height 0.60 \
   --json-output metrics.json \
   --output debug.mp4
 ```
 
-### Full Example
+### Full Example (Maximum Accuracy)
 
 ```bash
-kinemetry dropjump-analyze jump.mp4 \
-  --json-output results.json \
-  --output debug.mp4 \
+# 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 \
-  --velocity-threshold 0.015
+  --polyorder 3
+
+# Alternative: With experimental bilateral filter
+kinemotion dropjump-analyze jump.mp4 \
+  --outlier-rejection \
+  --bilateral-filter \
+  --drop-height 0.40 \
+  --output debug.mp4 \
+  --json-output results.json
 ```
 
 ## Configuration Options
@@ -132,6 +156,7 @@ kinemetry dropjump-analyze jump.mp4 \
 > **📖 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
@@ -146,6 +171,43 @@ kinemetry dropjump-analyze jump.mp4 \
   - 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)
@@ -182,10 +244,25 @@ kinemetry dropjump-analyze jump.mp4 \
 - `--drop-height <float>` (optional)
   - Height of drop box/platform in meters (e.g., 0.40 for 40cm)
   - Enables calibrated jump height measurement using known drop height
-  - Improves accuracy from ~71% to ~88%
+  - 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
+
 ## Output Format
 
 ### JSON Metrics
@@ -206,6 +283,7 @@ kinemetry dropjump-analyze jump.mp4 \
 ```
 
 **Fields**:
+
 - `jump_height_m`: Primary jump height measurement (calibrated if --drop-height provided, otherwise corrected kinematic)
 - `jump_height_kinematic_m`: Kinematic estimate from flight time: h = (g × t²) / 8
 - `jump_height_trajectory_normalized`: Position-based measurement in normalized coordinates (0-1 range)
@@ -217,6 +295,7 @@ kinemetry dropjump-analyze jump.mp4 \
 ### Debug Video
 
 The debug video includes:
+
 - **Green circle**: Average foot position when on ground
 - **Red circle**: Average foot position when in air
 - **Yellow circles**: Individual foot landmarks (ankles, heels)
@@ -232,6 +311,7 @@ The debug video includes:
 **Symptoms**: Erratic landmark positions, missing detections, incorrect contact states
 
 **Solutions**:
+
 1. **Check video quality**: Ensure the athlete is clearly visible in profile view
 2. **Increase smoothing**: Use `--smoothing-window 7` or higher
 3. **Adjust detection confidence**: Try `--detection-confidence 0.6` or `--tracking-confidence 0.6`
@@ -242,6 +322,7 @@ The debug video includes:
 **Symptoms**: "No frames processed" error or all null landmarks
 
 **Solutions**:
+
 1. **Verify video format**: OpenCV must be able to read the video
 2. **Check framing**: Ensure full body is visible in side view
 3. **Lower confidence thresholds**: Try `--detection-confidence 0.3 --tracking-confidence 0.3`
@@ -252,6 +333,7 @@ The debug video includes:
 **Symptoms**: Wrong ground contact times, flight phases not detected
 
 **Solutions**:
+
 1. **Generate debug video**: Visualize contact states to diagnose the issue
 2. **Adjust velocity threshold**:
    - If missing contacts: decrease to `--velocity-threshold 0.01`
@@ -264,8 +346,9 @@ The debug video includes:
 **Symptoms**: Unrealistic jump height values
 
 **Solutions**:
+
 1. **Use calibration**: For drop jumps, add `--drop-height` parameter with box height in meters (e.g., `--drop-height 0.40`)
-   - This improves accuracy from ~71% to ~88%
+   - Theoretically improves accuracy (⚠️ unvalidated)
 2. **Verify flight time detection**: Check `flight_start_frame` and `flight_end_frame` in JSON
 3. **Compare measurements**: JSON output includes both `jump_height_m` (primary) and `jump_height_kinematic_m` (kinematic-only)
 4. **Check for drop jump detection**: If doing a drop jump, ensure first phase is elevated enough (>5% of frame height)
@@ -275,50 +358,53 @@ The debug video includes:
 **Symptoms**: Cannot write debug video or corrupted output
 
 **Solutions**:
+
 1. **Install additional codecs**: Ensure OpenCV has proper video codec support
 2. **Try different output format**: Use `.avi` extension instead of `.mp4`
 3. **Check output path**: Ensure write permissions for output directory
 
 ## How It Works
 
-1. **Pose Tracking**: MediaPipe extracts 2D pose landmarks (ankles, heels, foot indices) from each frame
-2. **Smoothing**: Savitzky-Golay filter reduces tracking jitter while preserving motion dynamics
-3. **Contact Detection**: Analyzes vertical foot velocity to identify ground contact vs. flight phases
-4. **Phase Identification**: Finds continuous ground contact and flight periods
+1. **Pose Tracking**: MediaPipe extracts 2D pose landmarks (foot points: ankles, heels, foot indices) from each frame
+2. **Position Calculation**: Averages ankle, heel, and foot index positions to determine foot location
+3. **Smoothing**: Savitzky-Golay filter reduces tracking jitter while preserving motion dynamics
+4. **Contact Detection**: Analyzes vertical position velocity to identify ground contact vs. flight phases
+5. **Phase Identification**: Finds continuous ground contact and flight periods
    - Automatically detects drop jumps vs regular jumps
    - For drop jumps: identifies box → drop → ground contact → jump sequence
-5. **Sub-Frame Interpolation**: Estimates exact transition times between frames
+6. **Sub-Frame Interpolation**: Estimates exact transition times between frames
    - Uses Savitzky-Golay derivative for smooth velocity calculation
    - Linear interpolation of velocity to find threshold crossings
    - Achieves sub-millisecond timing precision (at 30fps: ±10ms vs ±33ms)
    - Reduces timing error by 60-70% for contact and flight measurements
    - Smoother velocity curves eliminate false threshold crossings
-6. **Trajectory Curvature Analysis**: Refines transitions using acceleration patterns
+7. **Trajectory Curvature Analysis**: Refines transitions using acceleration patterns
    - Computes second derivative (acceleration) from position trajectory
    - Detects landing impact by acceleration spike
    - Identifies takeoff by acceleration change patterns
    - Provides independent validation and refinement of velocity-based detection
-7. **Metric Calculation**:
+8. **Metric Calculation**:
    - Ground contact time = contact phase duration (using fractional frames)
    - Flight time = flight phase duration (using fractional frames)
    - Jump height = calibrated position-based measurement (if --drop-height provided)
-   - Fallback: corrected kinematic estimate (g × t²) / 8 × 1.35
+   - Fallback: kinematic estimate (g × t²) / 8 with optional empirical correction factor (⚠️ unvalidated)
 
 ## Development
 
 ### Code Quality Standards
 
 This project enforces strict code quality standards:
+
 - **Type safety**: Full mypy strict mode compliance with complete type annotations
 - **Linting**: Comprehensive ruff checks (pycodestyle, pyflakes, isort, pep8-naming, etc.)
 - **Formatting**: Black code style
-- **Testing**: pytest with 9 unit tests
+- **Testing**: pytest with 25 unit tests
 
 ### Development Commands
 
 ```bash
 # Run the tool
-uv run kinemetry dropjump-analyze <video_path>
+uv run kinemotion dropjump-analyze <video_path>
 
 # Run all tests
 uv run pytest
@@ -356,7 +442,7 @@ See [CLAUDE.md](CLAUDE.md) for detailed development guidelines.
 ## Limitations
 
 - **2D Analysis**: Only analyzes motion in the camera's view plane
-- **Calibration accuracy**: With drop height calibration, achieves ~88% accuracy; without calibration ~71% accuracy
+- **Validation Status**: ⚠️ Accuracy has not been validated against gold standard measurements (force plates, 3D motion capture)
 - **Side View Required**: Must film from the side to accurately track vertical motion
 - **Single Athlete**: Designed for analyzing one athlete at a time
 - **Timing precision**:

kinemotion-0.4.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+kinemotion/__init__.py,sha256=JhS0ZTgcTdcMH5WcIyWxEqZJPOoBUSKX8tT8hsG-xWk,98
+kinemotion/cli.py,sha256=2IFA2_TE9a5zBtmGVzv5SnX39w7yPuBlw42dL7ca25U,402
+kinemotion/core/__init__.py,sha256=3yzDhb5PekDNjydqrs8aWGneUGJBt-lB0SoB_Y2FXqU,1010
+kinemotion/core/filtering.py,sha256=QtZRz8KlcLtR4dLRFH9sGqRQsUo_Dqcr1ZJIyWwPlcM,11266
+kinemotion/core/pose.py,sha256=5Dhw3LqX3STR-eLb5JAQkxhS-dd0PqGytBWnaQ66nWc,8391
+kinemotion/core/smoothing.py,sha256=z2qnpEGohDm6ZUrzqRXGLp189-NJL0ngKqYwXkU-iW0,13166
+kinemotion/core/video_io.py,sha256=LD7qmHIqUYomGxS1kxz6khugIbFo2y4tDSY7XqJQCOM,4581
+kinemotion/dropjump/__init__.py,sha256=yc1XiZ9vfo5h_n7PKVSiX2TTgaIfGL7Y7SkQtiDZj_E,838
+kinemotion/dropjump/analysis.py,sha256=5lyTJFiItqmSHw96m8HmFrl7N6nCVQZnERWU2prjn9Y,18719
+kinemotion/dropjump/cli.py,sha256=URQguQ6tmDofWagGydXzvc4NPXOCfOGX-yyFgvLV6lM,11954
+kinemotion/dropjump/debug_overlay.py,sha256=s7hwYLA2JenRYOPD2GNmx3kATFseeZT3pW8jxiVgys8,8621
+kinemotion/dropjump/kinematics.py,sha256=wcXaGUrb1kjSTus0KEwgdDzdkJRMy-umAzfStGq0_t4,16258
+kinemotion-0.4.0.dist-info/METADATA,sha256=gbmHKdrYweUTafp6utQxnVAqHEgx4_EWNPEua86_kBU,18693
+kinemotion-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kinemotion-0.4.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.4.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.4.0.dist-info/RECORD,,

kinemotion-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kinemotion = kinemotion.cli:cli

dropjump/__init__.py

@@ -1,3 +0,0 @@
-"""Drop-jump video analysis tool."""
-
-__version__ = "0.1.0"

dropjump/pose_tracker.py

@@ -1,74 +0,0 @@
-"""Pose tracking using MediaPipe Pose."""
-
-
-import cv2
-import mediapipe as mp
-import numpy as np
-
-
-class PoseTracker:
-    """Tracks human pose landmarks in video frames using MediaPipe."""
-
-    def __init__(
-        self,
-        min_detection_confidence: float = 0.5,
-        min_tracking_confidence: float = 0.5,
-    ):
-        """
-        Initialize the pose tracker.
-
-        Args:
-            min_detection_confidence: Minimum confidence for pose detection
-            min_tracking_confidence: Minimum confidence for pose tracking
-        """
-        self.mp_pose = mp.solutions.pose
-        self.pose = self.mp_pose.Pose(
-            min_detection_confidence=min_detection_confidence,
-            min_tracking_confidence=min_tracking_confidence,
-            model_complexity=1,
-        )
-
-    def process_frame(
-        self, frame: np.ndarray
-    ) -> dict[str, tuple[float, float, float]] | None:
-        """
-        Process a single frame and extract pose landmarks.
-
-        Args:
-            frame: BGR image frame
-
-        Returns:
-            Dictionary mapping landmark names to (x, y, visibility) tuples,
-            or None if no pose detected. Coordinates are normalized (0-1).
-        """
-        # Convert BGR to RGB
-        rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
-
-        # Process the frame
-        results = self.pose.process(rgb_frame)
-
-        if not results.pose_landmarks:
-            return None
-
-        # Extract key landmarks for feet tracking
-        landmarks = {}
-        landmark_names = {
-            self.mp_pose.PoseLandmark.LEFT_ANKLE: "left_ankle",
-            self.mp_pose.PoseLandmark.RIGHT_ANKLE: "right_ankle",
-            self.mp_pose.PoseLandmark.LEFT_HEEL: "left_heel",
-            self.mp_pose.PoseLandmark.RIGHT_HEEL: "right_heel",
-            self.mp_pose.PoseLandmark.LEFT_FOOT_INDEX: "left_foot_index",
-            self.mp_pose.PoseLandmark.RIGHT_FOOT_INDEX: "right_foot_index",
-            self.mp_pose.PoseLandmark.LEFT_HIP: "left_hip",
-            self.mp_pose.PoseLandmark.RIGHT_HIP: "right_hip",
-        }
-
-        for landmark_id, name in landmark_names.items():
-            lm = results.pose_landmarks.landmark[landmark_id]
-            landmarks[name] = (lm.x, lm.y, lm.visibility)
-
-        return landmarks
-
-    def close(self) -> None:
-        """Release resources."""
-        self.pose.close()

kinemotion-0.1.0.dist-info/RECORD

@@ -1,12 +0,0 @@
-dropjump/__init__.py,sha256=3os3CgjXm09srnAvsNIjA_KpHHfsu4ioRY0_oVDaX0w,60
-dropjump/cli.py,sha256=mW_wUaAb1mzQks8oFcZHre50U0pbTacJZg3x-VUdLtY,9563
-dropjump/contact_detection.py,sha256=cHqQ_nR9mbKyHeb90iuGjE8Hq34S01VURBMF8x5oHeM,15015
-dropjump/kinematics.py,sha256=x2SB_4Pj-kJUFCI-KSMjr5PypCmh9FkRR9dorvMq8zI,14983
-dropjump/pose_tracker.py,sha256=JDHK7di6-ObxwVR3TzERUmwCXeCFZWua1kUp1W9W55c,2367
-dropjump/smoothing.py,sha256=FCAk6PnMs7v8dzh98cteLaCvHOuYtfWDVI3X51MxEqs,7836
-dropjump/video_io.py,sha256=Cw_dYRgwybN1gIj4P88tedWAjwmQ4UxkRDztdpRD1hQ,11614
-kinemotion-0.1.0.dist-info/METADATA,sha256=VpBdG6PQcEdjskv-oQssggqltnuDgxvmfd0-1nTj5oA,13737
-kinemotion-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.1.0.dist-info/entry_points.txt,sha256=yRp0CWopxkd5fjbnhQ9OjI9gELPmpcCSMCDvWidatD4,47
-kinemotion-0.1.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.1.0.dist-info/RECORD,,

kinemotion-0.1.0.dist-info/entry_points.txt

@@ -1,2 +0,0 @@
-[console_scripts]
-kinemetry = dropjump.cli:cli