kinemotion 0.6.4__tar.gz → 0.7.1__tar.gz

{kinemotion-0.6.4 → kinemotion-0.7.1}/.pre-commit-config.yaml

@@ -15,19 +15,20 @@ repos:
       - id: mixed-line-ending
 
   - repo: https://github.com/psf/black
-    rev: 23.12.1
+    rev: 25.9.0
     hooks:
       - id: black
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.9
+    rev: v0.14.3
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.7.1
+    rev: v1.18.2
     hooks:
       - id: mypy
         args: [--ignore-missing-imports, --no-strict-optional]
-        exclude: ^tests/
+        files: ^src/
+        exclude: ^(tests/|examples/)

{kinemotion-0.6.4 → kinemotion-0.7.1}/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## 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
+
+- Add intelligent auto-tuning and video rotation handling
+  ([`7b35f67`](https://github.com/feniix/kinemotion/commit/7b35f6790dd8b6714f3e42389555107a043d486c))
+
+
 ## v0.6.4 (2025-10-26)
 
 ### Bug Fixes

{kinemotion-0.6.4 → kinemotion-0.7.1}/CLAUDE.md

@@ -240,6 +240,48 @@ self.height = int(self.cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
 - Runtime validation in `write_frame()` ensures every frame matches expected encoded dimensions
 - Raises `ValueError` if aspect ratio would be corrupted
 
+### Video Rotation Handling (core/video_io.py)
+
+**IMPORTANT**: The tool automatically handles video rotation metadata from mobile devices. OpenCV ignores rotation metadata, so we extract and apply it manually.
+
+#### Rotation Metadata Extraction (`core/video_io.py:65-126`)
+
+- **Display Matrix Metadata**: iPhones and other mobile devices store rotation in `side_data_list`
+  - Common rotation values: -90° (portrait right), 90° (portrait left), 180° (upside down)
+  - OpenCV's `VideoCapture.read()` ignores this metadata (known OpenCV issue #26876)
+  - Extracted using ffprobe from the same call that extracts SAR metadata
+- **Automatic Frame Rotation**: Applied in `read_frame()` method using `cv2.rotate()`
+  - -90° / 270° → `cv2.ROTATE_90_CLOCKWISE`
+  - 90° / -270° → `cv2.ROTATE_90_COUNTERCLOCKWISE`
+  - ±180° → `cv2.ROTATE_180`
+- **Dimension Updates**: Width and height are swapped after 90°/-90° rotations
+
+```python
+# Rotation extraction from side_data_list
+side_data_list = stream.get("side_data_list", [])
+for side_data in side_data_list:
+    if side_data.get("side_data_type") == "Display Matrix":
+        self.rotation = int(side_data.get("rotation", 0))
+
+# Automatic rotation in read_frame()
+if self.rotation == -90 or self.rotation == 270:
+    frame = cv2.rotate(frame, cv2.ROTATE_90_CLOCKWISE)
+```
+
+**Why this matters:**
+
+- Without rotation handling, portrait videos are processed sideways
+- MediaPipe would detect poses on rotated frames (person lying horizontally)
+- Output videos would have incorrect orientation
+- Jump analysis would fail due to incorrect gravity axis
+
+**Example:**
+
+- iPhone video encoded as 1920x1080 (landscape) with -90° rotation metadata
+- Should be displayed as 1080x1920 (portrait)
+- Tool automatically rotates frames and updates dimensions
+- Output video correctly shows 1080x1920 portrait orientation
+
 ### Sub-Frame Interpolation (contact_detection.py:113-227)
 
 **IMPORTANT**: The tool uses sub-frame interpolation with derivative-based velocity to achieve timing precision beyond frame boundaries.
@@ -462,30 +504,129 @@ Modify `smooth_landmarks()` in `core/smoothing.py:9`:
 - `window_length`: Controls smoothing strength (must be odd, default: 5)
 - `polyorder`: Polynomial order for Savitzky-Golay filter (default: 2)
 
-### Parameter Tuning
+### Intelligent Auto-Tuning System
 
-**IMPORTANT**: See `docs/PARAMETERS.md` for comprehensive guide on all CLI parameters.
+**NEW**: The tool now features intelligent auto-tuning that eliminates the need for manual parameter adjustment!
 
-Quick reference for `dropjump-analyze`:
+#### How It Works (core/auto_tuning.py)
 
-- **smoothing-window**: Trajectory smoothness (↑ for noisy video)
-- **velocity-threshold**: Contact sensitivity (↓ to detect brief contacts)
-- **min-contact-frames**: Temporal filter (↑ to remove false contacts)
-- **visibility-threshold**: Landmark confidence (↓ for occluded landmarks)
-- **detection-confidence**: Pose detection strictness (MediaPipe)
-- **tracking-confidence**: Tracking persistence (MediaPipe)
-- **drop-height**: Drop box height in meters for calibration (e.g., 0.40 for 40cm)
-- **use-curvature**: Enable trajectory curvature analysis (default: enabled)
+The auto-tuning system analyzes your video and automatically selects optimal parameters:
 
-**Note**: Drop jump analysis always uses foot-based tracking with fixed velocity thresholds because typical drop jump videos are ~3 seconds long without a stationary baseline period. The `--use-com` and `--adaptive-threshold` options (available in `core/` modules) require longer videos (~5+ seconds) with 3 seconds of standing baseline, making them suitable for future jump types like CMJ (countermovement jump) but not drop jumps.
+**Phase 1: Video Analysis**
+- Extracts frame rate from video metadata
+- Analyzes landmark visibility quality (average MediaPipe confidence scores)
+- Measures position variance (tracking stability)
+- Detects drop jump pattern (stationary period on platform)
 
-The detailed guide includes:
+**Phase 2: Automatic Parameter Selection**
 
-- How each parameter works internally
-- Frame rate considerations
-- Scenario-based recommended settings
-- Debugging workflow with visual indicators
-- Parameter interaction effects
+**FPS-based scaling** (maintains consistent temporal resolution):
+```python
+velocity_threshold = 0.02 × (30 / fps)
+# 30fps → 0.020, 60fps → 0.010, 120fps → 0.005
+
+min_contact_frames = round(3 × (fps / 30))
+# 30fps → 3 frames (100ms), 60fps → 6 frames (100ms)
+
+smoothing_window = 5 if fps ≤ 30 else 3
+# Higher fps → less smoothing (better temporal resolution)
+```
+
+**Quality-based adjustments** (adapts to tracking quality):
+- High visibility (>0.7): Minimal smoothing, no bilateral filter
+- Medium visibility (0.4-0.7): Moderate smoothing, enable bilateral filter
+- Low visibility (<0.4): Aggressive smoothing, bilateral filter, lower confidence thresholds
+
+**Always enabled** (proven beneficial, no downsides):
+- Outlier rejection (removes tracking glitches)
+- Trajectory curvature analysis (sub-frame precision)
+- Drop start auto-detection (skips stationary period)
+- Polyorder 2 (optimal for parabolic jump motion)
+
+#### Quality Presets
+
+**`--quality fast`** (50% faster, good for batch processing)
+- Velocity threshold ×1.5 (less sensitive)
+- Reduced smoothing (-2 frames)
+- Skips bilateral filter
+- Lower detection confidence (0.3)
+
+**`--quality balanced`** (default, best for most cases)
+- FPS-adjusted parameters
+- Adaptive smoothing based on quality
+- All accuracy features enabled
+
+**`--quality accurate`** (research-grade, slower)
+- Velocity threshold ×0.5 (more sensitive)
+- Increased smoothing (+2 frames)
+- Always enables bilateral filter
+- Higher detection confidence (0.6)
+
+#### User-Facing Parameters
+
+**Reduced from 13 → 2 required + 2 optional:**
+
+**Required:**
+- `--drop-height`: Box height in meters (e.g., 0.40 for 40cm) - REQUIRED for accurate calibration
+
+**Optional:**
+- `--output`: Debug video path
+- `--json-output`: Metrics JSON path
+- `--quality`: fast/balanced/accurate (default: balanced)
+- `--verbose`: Show auto-selected parameters
+
+**Expert overrides** (rarely needed):
+- `--drop-start-frame`: Manual drop start frame
+- `--smoothing-window`: Override auto-tuned smoothing
+- `--velocity-threshold`: Override auto-tuned threshold
+- `--min-contact-frames`: Override auto-tuned minimum
+- `--visibility-threshold`: Override visibility threshold
+- `--detection-confidence`: Override MediaPipe detection
+- `--tracking-confidence`: Override MediaPipe tracking
+
+#### Migration from Manual Parameters
+
+**Old way** (complex, error-prone):
+```bash
+# User had to know these magic numbers for 60fps video
+uv run kinemotion dropjump-analyze video.mp4 \
+  --smoothing-window 3 \
+  --velocity-threshold 0.01 \
+  --min-contact-frames 6 \
+  --outlier-rejection \
+  --use-curvature
+```
+
+**New way** (simple, automatic):
+```bash
+# Just works - auto-detects 60fps and adjusts all parameters
+uv run kinemotion dropjump-analyze video.mp4
+```
+
+#### Viewing Auto-Selected Parameters
+
+Use `--verbose` to see what parameters were automatically selected:
+
+```bash
+uv run kinemotion dropjump-analyze video.mp4 --verbose
+
+# Output shows:
+# ============================================================
+# AUTO-TUNED PARAMETERS
+# ============================================================
+# Video FPS: 59.98
+# Tracking quality: high (avg visibility: 0.79)
+# Quality preset: balanced
+#
+# Selected parameters:
+#   smoothing_window: 3
+#   velocity_threshold: 0.0100
+#   min_contact_frames: 6
+#   ...
+# ============================================================
+```
+
+**Note**: See `docs/PARAMETERS.md` for detailed explanation of what each parameter does internally (useful for expert mode overrides).
 
 ### Working with Different Video Formats
 
@@ -576,6 +717,10 @@ If mypy reports errors:
 
 ## CLI Usage Examples
 
+**NEW: The tool now features intelligent auto-tuning!** Parameters are automatically adjusted based on video frame rate, tracking quality, and analysis preset. No manual parameter tuning required.
+
+### Simple Usage (Recommended)
+
 ```bash
 # Show main command help
 uv run kinemotion --help
@@ -583,35 +728,91 @@ uv run kinemotion --help
 # Show subcommand help
 uv run kinemotion dropjump-analyze --help
 
-# Basic analysis (JSON to stdout)
-uv run kinemotion dropjump-analyze video.mp4
+# Basic analysis (JSON to stdout) - JUST WORKS!
+# Drop-height is REQUIRED - specify your box height in meters
+# Auto-detects fps, tracking quality, and selects optimal parameters
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40
 
 # Save metrics to file
-uv run kinemotion dropjump-analyze video.mp4 --json-output results.json
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --json-output results.json
 
 # Generate debug video
-uv run kinemotion dropjump-analyze video.mp4 --output debug.mp4
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --output debug.mp4
 
-# Drop jump with calibration (40cm box)
-uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40
+# Complete analysis with all outputs
+uv run kinemotion dropjump-analyze video.mp4 \
+  --drop-height 0.40 \
+  --output debug.mp4 \
+  --json-output metrics.json
+
+# See what parameters were auto-selected
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --verbose
+
+# Different box heights (examples)
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.30  # 30cm box
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.60  # 60cm box
+```
 
-# Custom parameters for noisy video
+### Quality Presets
+
+```bash
+# Fast analysis (quick, less precise)
+# - 50% faster processing
+# - Good for batch processing or initial assessment
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --quality fast
+
+# Balanced analysis (default)
+# - Good accuracy/speed tradeoff
+# - Best for most use cases
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --quality balanced
+
+# Accurate analysis (research-grade, slower)
+# - Maximum accuracy
+# - More aggressive smoothing and filtering
+# - Best for publication-quality data
+uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --quality accurate
+```
+
+### Expert Mode (Advanced Users Only)
+
+```bash
+# Override specific auto-tuned parameters
 uv run kinemotion dropjump-analyze video.mp4 \
+  --drop-height 0.40 \
+  --expert \
   --smoothing-window 7 \
-  --velocity-threshold 0.01 \
-  --min-contact-frames 5
+  --velocity-threshold 0.015
 
-# Full analysis with calibration and all outputs
+# Manual drop start frame (if auto-detection fails)
 uv run kinemotion dropjump-analyze video.mp4 \
-  --output debug.mp4 \
-  --json-output metrics.json \
   --drop-height 0.40 \
-  --smoothing-window 7
+  --drop-start-frame 120
+```
 
-# Regular jump (no calibration, uses corrected kinematic method)
-uv run kinemotion dropjump-analyze jump.mp4 \
-  --output debug.mp4 \
-  --json-output metrics.json
+### Auto-Tuning Examples
+
+```bash
+# 30fps video - auto-selects:
+#   velocity_threshold: 0.020
+#   min_contact_frames: 3
+#   smoothing_window: 5
+uv run kinemotion dropjump-analyze video_30fps.mp4 --drop-height 0.40
+
+# 60fps video - auto-selects:
+#   velocity_threshold: 0.010
+#   min_contact_frames: 6
+#   smoothing_window: 3
+uv run kinemotion dropjump-analyze video_60fps.mp4 --drop-height 0.40
+
+# Low quality video (avg visibility < 0.4) - auto-enables:
+#   bilateral_filter: True
+#   smoothing_window: +2 adjustment
+uv run kinemotion dropjump-analyze low_quality.mp4 --drop-height 0.40
+
+# High quality video (avg visibility > 0.7) - optimizes:
+#   bilateral_filter: False (not needed)
+#   smoothing_window: minimal (preserve detail)
+uv run kinemotion dropjump-analyze high_quality.mp4 --drop-height 0.40
 ```
 
 ## MCP Server Configuration

{kinemotion-0.6.4 → kinemotion-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.6.4
+Version: 0.7.1
 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