kinemotion 0.15.1__tar.gz → 0.15.2__tar.gz

{kinemotion-0.15.1 → kinemotion-0.15.2}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -53,7 +53,7 @@ body:
       label: Command Used
       description: The exact command you ran (please remove any sensitive paths if needed).
       placeholder: |
-        kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --output debug.mp4
+        kinemotion dropjump-analyze video.mp4 --output debug.mp4
       render: bash
     validations:
       required: false

{kinemotion-0.15.1 → kinemotion-0.15.2}/.github/pull_request_template.md

@@ -52,7 +52,8 @@ Related to #
 
 ```bash
 # Example test commands
-uv run kinemotion dropjump-analyze test_video.mp4 --drop-height 0.40
+uv run kinemotion dropjump-analyze test_video.mp4
+uv run kinemotion cmj-analyze test_video.mp4
 ```
 
 ## Code Quality Checklist

{kinemotion-0.15.1 → kinemotion-0.15.2}/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.15.2 (2025-11-07)
+
+### Bug Fixes
+
+- **docs**: Update documentation to match current auto-tuning API
+  ([`a07b40d`](https://github.com/feniix/kinemotion/commit/a07b40d9057438912a44fc4eb5b9b3e6e34a6d56))
+
+
 ## v0.15.1 (2025-11-06)
 
 ### Bug Fixes

{kinemotion-0.15.1 → kinemotion-0.15.2}/CLAUDE.md

@@ -13,7 +13,7 @@ Kinemotion: Video-based kinematic analysis for athletic performance using MediaP
 ```bash
 asdf install        # Install Python 3.12.7 + uv
 uv sync            # Install dependencies
-uv run kinemotion dropjump-analyze video.mp4 --drop-height 0.40
+uv run kinemotion dropjump-analyze video.mp4
 uv run kinemotion cmj-analyze video.mp4
 ```
 
@@ -48,7 +48,7 @@ docs/                       # CMJ_GUIDE, TRIPLE_EXTENSION, REAL_TIME_ANALYSIS, e
 | Starting | Elevated box | Floor level |
 | Algorithm | Forward search | Backward search from peak |
 | Velocity | Absolute (magnitude) | Signed (direction matters) |
-| Parameter | `--drop-height` required | No calibration needed |
+| Parameters | Auto-tuned quality presets | Auto-tuned quality presets |
 | Key Metric | Ground contact time | Jump height from flight time |
 
 ## Critical Implementation Details
@@ -178,13 +178,13 @@ When writing new code, follow these principles to maintain low duplication:
 ### CLI
 
 ```bash
-# Drop jump (requires --drop-height)
-kinemotion dropjump-analyze video.mp4 --drop-height 0.40
+# Drop jump (auto-tuned parameters)
+kinemotion dropjump-analyze video.mp4
 
-# CMJ (no calibration needed)
+# CMJ with debug video
 kinemotion cmj-analyze video.mp4 --output debug.mp4
 
-# Batch
+# Batch processing
 kinemotion cmj-analyze videos/*.mp4 --batch --workers 4
 ```
 
@@ -193,11 +193,11 @@ kinemotion cmj-analyze videos/*.mp4 --batch --workers 4
 ```python
 # Drop jump
 from kinemotion import process_dropjump_video
-metrics = process_video("video.mp4", drop_height=0.40)
+metrics = process_dropjump_video("video.mp4", quality="balanced")
 
 # CMJ
 from kinemotion import process_cmj_video
-metrics = process_cmj_video("video.mp4")
+metrics = process_cmj_video("video.mp4", quality="balanced")
 ```
 
 ## Important Gotchas

{kinemotion-0.15.1 → kinemotion-0.15.2}/CONTRIBUTING.md

@@ -83,10 +83,10 @@ We actively welcome pull requests! Here's how to submit one:
 
 ```bash
 # Run from source
-uv run kinemotion dropjump-analyze <video_path> --drop-height 0.40
+uv run kinemotion dropjump-analyze <video_path>
 
 # With debug output
-uv run kinemotion dropjump-analyze <video_path> --drop-height 0.40 --output debug.mp4 --verbose
+uv run kinemotion dropjump-analyze <video_path> --output debug.mp4 --verbose
 ```
 
 ## Code Quality Standards

{kinemotion-0.15.1 → kinemotion-0.15.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.15.1
+Version: 0.15.2
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion
@@ -125,8 +125,8 @@ Kinemotion supports two jump types with intelligent auto-tuning that automatical
 Analyzes reactive strength and ground contact time:
 
 ```bash
-# Drop-height is REQUIRED for accurate calibration
-kinemotion dropjump-analyze video.mp4 --drop-height 0.40
+# Automatic parameter tuning based on video characteristics
+kinemotion dropjump-analyze video.mp4
 ```
 
 ### Counter Movement Jump (CMJ) Analysis
@@ -176,9 +176,9 @@ Process multiple videos in parallel:
 
 ```bash
 # Drop jumps
-kinemotion dropjump-analyze videos/*.mp4 --batch --drop-height 0.40 --workers 4
+kinemotion dropjump-analyze videos/*.mp4 --batch --workers 4
 
-# CMJ (no drop height needed)
+# CMJ with output directories
 kinemotion cmj-analyze videos/*.mp4 --batch --workers 4 \
   --json-output-dir results/ \
   --csv-summary summary.csv
@@ -194,9 +194,8 @@ Use kinemotion as a library for automated pipelines and custom analysis.
 from kinemotion import process_dropjump_video
 
 # Process a single video
-metrics = process_video(
+metrics = process_dropjump_video(
     video_path="athlete_jump.mp4",
-    drop_height=0.40,  # 40cm drop box
     quality="balanced",
     verbose=True
 )
@@ -214,11 +213,11 @@ print(f"Flight time: {metrics.flight_time * 1000:.1f} ms")
 from kinemotion import DropJumpVideoConfig, process_dropjump_videos_bulk
 
 configs = [
-    VideoConfig("video1.mp4", drop_height=0.40),
-    VideoConfig("video2.mp4", drop_height=0.30, quality="accurate"),
+    DropJumpVideoConfig("video1.mp4", quality="balanced"),
+    DropJumpVideoConfig("video2.mp4", quality="accurate"),
 ]
 
-results = process_videos_bulk(configs, max_workers=4)
+results = process_dropjump_videos_bulk(configs, max_workers=4)
 
 # CMJ bulk processing
 from kinemotion import CMJVideoConfig, process_cmj_videos_bulk

{kinemotion-0.15.1 → kinemotion-0.15.2}/README.md

@@ -96,8 +96,8 @@ Kinemotion supports two jump types with intelligent auto-tuning that automatical
 Analyzes reactive strength and ground contact time:
 
 ```bash
-# Drop-height is REQUIRED for accurate calibration
-kinemotion dropjump-analyze video.mp4 --drop-height 0.40
+# Automatic parameter tuning based on video characteristics
+kinemotion dropjump-analyze video.mp4
 ```
 
 ### Counter Movement Jump (CMJ) Analysis
@@ -147,9 +147,9 @@ Process multiple videos in parallel:
 
 ```bash
 # Drop jumps
-kinemotion dropjump-analyze videos/*.mp4 --batch --drop-height 0.40 --workers 4
+kinemotion dropjump-analyze videos/*.mp4 --batch --workers 4
 
-# CMJ (no drop height needed)
+# CMJ with output directories
 kinemotion cmj-analyze videos/*.mp4 --batch --workers 4 \
   --json-output-dir results/ \
   --csv-summary summary.csv
@@ -165,9 +165,8 @@ Use kinemotion as a library for automated pipelines and custom analysis.
 from kinemotion import process_dropjump_video
 
 # Process a single video
-metrics = process_video(
+metrics = process_dropjump_video(
     video_path="athlete_jump.mp4",
-    drop_height=0.40,  # 40cm drop box
     quality="balanced",
     verbose=True
 )
@@ -185,11 +184,11 @@ print(f"Flight time: {metrics.flight_time * 1000:.1f} ms")
 from kinemotion import DropJumpVideoConfig, process_dropjump_videos_bulk
 
 configs = [
-    VideoConfig("video1.mp4", drop_height=0.40),
-    VideoConfig("video2.mp4", drop_height=0.30, quality="accurate"),
+    DropJumpVideoConfig("video1.mp4", quality="balanced"),
+    DropJumpVideoConfig("video2.mp4", quality="accurate"),
 ]
 
-results = process_videos_bulk(configs, max_workers=4)
+results = process_dropjump_videos_bulk(configs, max_workers=4)
 
 # CMJ bulk processing
 from kinemotion import CMJVideoConfig, process_cmj_videos_bulk

{kinemotion-0.15.1 → kinemotion-0.15.2}/docs/api/cmj.md

@@ -9,8 +9,9 @@ from kinemotion import process_cmj_video
 
 metrics = process_cmj_video(
     video_path="cmj.mp4",
-    output_path="debug.mp4",  # optional
-    smoothing=True
+    quality="balanced",  # fast, balanced, or accurate
+    output_video="debug.mp4",  # optional
+    verbose=True
 )
 
 print(f"Jump height: {metrics.jump_height:.2f}m")

kinemotion-0.15.2/docs/api/dropjump.md

@@ -0,0 +1,106 @@
+# Drop Jump API
+
+The drop jump API provides functions for analyzing drop jump videos and extracting kinematic metrics.
+
+## Quick Example
+
+```python
+from kinemotion import process_dropjump_video
+
+metrics = process_dropjump_video(
+    video_path="dropjump.mp4",
+    quality="balanced",  # fast, balanced, or accurate
+    output_video="debug.mp4",  # optional
+    verbose=True
+)
+
+print(f"Ground contact time: {metrics.ground_contact_time:.3f}s")
+print(f"Flight time: {metrics.flight_time:.3f}s")
+print(f"RSI: {metrics.reactive_strength_index:.2f}")
+```
+
+## Main Functions
+
+::: kinemotion.api.process_dropjump_video
+options:
+show_root_heading: true
+show_source: false
+
+::: kinemotion.api.process_dropjump_videos_bulk
+options:
+show_root_heading: true
+show_source: false
+
+## Configuration
+
+::: kinemotion.api.DropJumpVideoConfig
+options:
+show_root_heading: true
+show_source: false
+
+## Results
+
+::: kinemotion.api.DropJumpVideoResult
+options:
+show_root_heading: true
+show_source: false
+
+## Metrics
+
+::: kinemotion.dropjump.kinematics.DropJumpMetrics
+options:
+show_root_heading: true
+show_source: false
+
+## Key Parameters
+
+### quality
+
+Analysis quality preset that determines processing speed and accuracy. The system automatically tunes parameters based on video characteristics and the selected preset.
+
+Options:
+
+- `"fast"` - Quick processing, lower precision
+- `"balanced"` - Default, good for most cases
+- `"accurate"` - Research-grade, slower processing
+
+Default: `"balanced"`
+
+```python
+metrics = process_dropjump_video("video.mp4", quality="accurate")
+```
+
+### output_video
+
+Path to write debug video with overlay visualization. If not provided, no debug video is created.
+
+```python
+metrics = process_dropjump_video(
+    "video.mp4",
+    quality="balanced",
+    output_video="debug.mp4"
+)
+```
+
+### json_output
+
+Path to write JSON metrics output. If not provided, metrics are only returned as a Python object.
+
+```python
+metrics = process_dropjump_video(
+    "video.mp4",
+    json_output="metrics.json"
+)
+```
+
+### Expert Parameters
+
+For advanced users, you can override auto-tuned parameters:
+
+- `smoothing_window` - Override auto-tuned smoothing window size
+- `velocity_threshold` - Override velocity threshold for ground contact detection
+- `min_contact_frames` - Override minimum contact frames
+- `visibility_threshold` - Override visibility threshold
+- `detection_confidence` - Override pose detection confidence
+- `tracking_confidence` - Override pose tracking confidence
+- `drop_start_frame` - Manually specify frame where drop begins

{kinemotion-0.15.1 → kinemotion-0.15.2}/docs/api/overview.md

@@ -8,10 +8,10 @@ Kinemotion provides a Python API for video-based kinematic analysis. The API is
 
 Process drop jump videos and extract kinematic metrics:
 
-- `process_video()` - Analyze a single drop jump video
-- `process_videos_bulk()` - Batch process multiple drop jump videos
-- `VideoConfig` - Configuration for drop jump analysis
-- `VideoResult` - Results from drop jump analysis
+- `process_dropjump_video()` - Analyze a single drop jump video
+- `process_dropjump_videos_bulk()` - Batch process multiple drop jump videos
+- `DropJumpVideoConfig` - Configuration for drop jump analysis
+- `DropJumpVideoResult` - Results from drop jump analysis
 - `DropJumpMetrics` - Kinematic metrics for drop jumps
 
 See [Drop Jump API](dropjump.md) for detailed documentation.
@@ -34,31 +34,35 @@ See [CMJ API](cmj.md) for detailed documentation.
 from kinemotion import process_dropjump_video, process_cmj_video
 
 # Drop jump analysis
-drop_metrics = process_video("dropjump.mp4", drop_height=0.40)
+drop_metrics = process_dropjump_video("dropjump.mp4", quality="balanced")
 
 # CMJ analysis
-cmj_metrics = process_cmj_video("cmj.mp4")
+cmj_metrics = process_cmj_video("cmj.mp4", quality="balanced")
 ```
 
 ## Batch Processing
 
 ```python
-from kinemotion import process_dropjump_videos_bulk, process_cmj_videos_bulk
+from kinemotion import (
+    DropJumpVideoConfig,
+    CMJVideoConfig,
+    process_dropjump_videos_bulk,
+    process_cmj_videos_bulk
+)
 
 # Batch drop jump analysis
-results = process_videos_bulk(
-    video_paths=["video1.mp4", "video2.mp4"],
-    drop_height=0.40,
-    output_dir="results/",
-    workers=4
-)
+configs = [
+    DropJumpVideoConfig("video1.mp4", quality="balanced"),
+    DropJumpVideoConfig("video2.mp4", quality="accurate"),
+]
+results = process_dropjump_videos_bulk(configs, max_workers=4)
 
 # Batch CMJ analysis
-cmj_results = process_cmj_videos_bulk(
-    video_paths=["cmj1.mp4", "cmj2.mp4"],
-    output_dir="results/",
-    workers=4
-)
+cmj_configs = [
+    CMJVideoConfig("cmj1.mp4", quality="balanced"),
+    CMJVideoConfig("cmj2.mp4", quality="accurate"),
+]
+cmj_results = process_cmj_videos_bulk(cmj_configs, max_workers=4)
 ```
 
 ## Core Utilities

{kinemotion-0.15.1 → kinemotion-0.15.2}/docs/guides/bulk-processing.md

@@ -2,6 +2,8 @@
 
 This guide covers different approaches for processing large batches of videos using kinemotion as a library.
 
+> **Note:** Some code examples in this guide use low-level API calls and may reference the removed `drop_height` parameter. For production use, prefer the high-level `process_dropjump_video()` and `process_cmj_video()` functions with `quality` presets (`"fast"`, `"balanced"`, or `"accurate"`) instead. See the [API documentation](../api/overview.md) for current best practices.
+
 ## Table of Contents
 
 - [Quick Start: Local Parallel Processing](#quick-start-local-parallel-processing)
@@ -31,42 +33,16 @@ from kinemotion.dropjump import (
 )
 from kinemotion.core.auto_tuning import auto_tune_parameters
 
-def analyze_video(video_path: str, drop_height: float = 0.40) -> dict:
+def analyze_video(video_path: str, quality: str = "balanced") -> dict:
     """Analyze a single drop jump video."""
     try:
-        # Auto-tune parameters based on video
-        params = auto_tune_parameters(video_path, quality_preset="balanced")
-
-        # Process video
-        video = VideoProcessor(video_path)
-        tracker = PoseTracker(
-            detection_confidence=params["detection_confidence"],
-            tracking_confidence=params["tracking_confidence"]
-        )
-
-        # Extract landmarks
-        landmarks = []
-        for frame in video.read_frames():
-            pose_result = tracker.process_frame(frame)
-            if pose_result:
-                landmarks.append(pose_result)
-
-        # Detect contact states
-        foot_positions = [compute_average_foot_position(lm) for lm in landmarks]
-        contact_states = detect_ground_contact(
-            foot_positions,
-            video.fps,
-            velocity_threshold=params["velocity_threshold"],
-            min_contact_frames=params["min_contact_frames"],
-            visibility_threshold=params["visibility_threshold"]
-        )
+        # Use the high-level API which handles auto-tuning
+        from kinemotion import process_dropjump_video
 
-        # Calculate metrics
-        metrics = calculate_drop_jump_metrics(
-            landmarks=landmarks,
-            contact_states=contact_states,
-            fps=video.fps,
-            drop_height_m=drop_height
+        metrics = process_dropjump_video(
+            video_path,
+            quality=quality,
+            verbose=False
         )
 
         return {
@@ -74,7 +50,6 @@ def analyze_video(video_path: str, drop_height: float = 0.40) -> dict:
             "success": True,
             **metrics.to_dict()
         }
-
     except Exception as e:
         return {
             "video": video_path,
@@ -88,7 +63,7 @@ video_files = list(video_dir.glob("*.mp4"))
 
 with ProcessPoolExecutor(max_workers=8) as executor:
     results = list(executor.map(
-        lambda p: analyze_video(str(p), 0.40),
+        lambda p: analyze_video(str(p), "balanced"),
         video_files
     ))
 
@@ -134,10 +109,10 @@ Bulk video processing with Kinemotion on Modal.com
 
 Usage:
     # Process videos from URLs
-    modal run batch_processor.py --video-list videos.txt --drop-height 0.40
+    modal run batch_processor.py --video-list videos.txt --quality balanced
 
     # Process videos from S3 bucket
-    modal run batch_processor.py --s3-bucket my-videos --drop-height 0.60
+    modal run batch_processor.py --s3-bucket my-videos --quality accurate
 """
 
 import modal

{kinemotion-0.15.1 → kinemotion-0.15.2}/docs/guides/camera-setup.md

@@ -657,17 +657,17 @@ ______________________________________________________________________
 
 **Possible causes:**
 
-1. Camera angle not exactly 45° (measurement error)
-1. Missing `--drop-height` calibration parameter
+1. Camera angle not optimal (measurement error)
 1. Athlete moving horizontally (drift during jump)
 1. Camera not level (tilted)
+1. Poor video quality affecting tracking
 
 **Solutions:**
 
-1. Verify 45° angle with measuring app or protractor
-1. Provide drop box height: `--drop-height 0.40`
+1. Verify camera angle with measuring app or protractor
 1. Coach athlete to jump straight up (minimal drift)
 1. Use tripod level indicator or phone level app
+1. Use `--quality accurate` for best results with good videos
 
 ### "No Drop Jump Detected" Error
 

{kinemotion-0.15.1 → kinemotion-0.15.2}/docs/index.md

@@ -18,7 +18,7 @@ pip install kinemotion
 ### Drop Jump Analysis
 
 ```bash
-kinemotion dropjump-analyze video.mp4 --drop-height 0.40
+kinemotion dropjump-analyze video.mp4
 ```
 
 Or via Python API:
@@ -26,7 +26,7 @@ Or via Python API:
 ```python
 from kinemotion import process_dropjump_video
 
-metrics = process_video("video.mp4", drop_height=0.40)
+metrics = process_dropjump_video("video.mp4", quality="balanced")
 print(f"Ground contact time: {metrics.ground_contact_time:.3f}s")
 print(f"RSI: {metrics.reactive_strength_index:.2f}")
 ```

{kinemotion-0.15.1 → kinemotion-0.15.2}/docs/reference/parameters.md

@@ -56,7 +56,7 @@ These parameters control batch processing mode when analyzing multiple videos:
 
 ```bash
 # Batch process with all outputs
-kinemotion dropjump-analyze videos/*.mp4 --batch --drop-height 0.40 \
+kinemotion dropjump-analyze videos/*.mp4 --batch \
   --workers 4 \
   --json-output-dir results/ \
   --output-dir debug_videos/ \
@@ -79,8 +79,8 @@ For more control, use the Python API:
 from kinemotion import DropJumpVideoConfig, process_dropjump_videos_bulk
 
 configs = [
-    DropJumpVideoConfig("video1.mp4", drop_height=0.40, quality="fast"),
-    DropJumpVideoConfig("video2.mp4", drop_height=0.30, quality="accurate"),  # Different settings per video
+    DropJumpVideoConfig("video1.mp4", quality="fast"),
+    DropJumpVideoConfig("video2.mp4", quality="accurate"),  # Different settings per video
 ]
 
 results = process_dropjump_videos_bulk(configs, max_workers=4)
@@ -234,9 +234,8 @@ kinemotion dropjump-analyze studio.mp4 \
 # Maximum accuracy setup
 kinemotion dropjump-analyze video.mp4 \
   --polyorder 3 \
-  --smoothing-window 9 \
-  --drop-height 0.40
-```text
+  --smoothing-window 9
+```
 
 **Validation rules:**
 
@@ -810,93 +809,47 @@ kinemotion dropjump-analyze video.mp4 --tracking-confidence 0.3
 
 ---
 
-## Calibration Parameters
-
-### `--drop-height` (optional, no default)
-
-**What it does:**
-Specifies the height of the drop box/platform in meters to enable calibrated jump height measurement.
-
-**How it works:**
-
-- Measures the actual drop distance from the box to the ground in the video
-- Calculates a scale factor to convert normalized coordinates (0-1) to real-world meters
-- Applies this scale factor to the jump height measurement
-- Significantly improves jump height accuracy from ~71% to ~88%
-
-**Technical details:**
-
-- Only applicable for drop jumps (box → drop → landing → jump)
-- Automatically detects drop jump pattern by comparing ground phase elevations
-- Uses the initial drop phase to establish the calibration scale factor
-- Formula: `scale_factor = drop_height_m / drop_distance_normalized`
-- Applied to position-based jump height measurement (not kinematic)
+## Auto-Tuning System
 
-**When to use:**
+Kinemotion uses an intelligent auto-tuning system that automatically optimizes analysis parameters based on video characteristics. This eliminates the need for manual calibration and makes the tool accessible to users without technical expertise.
 
-- Any drop jump where you know the box height
-- When accuracy of jump height is important
-- When comparing athletes or tracking progress over time
-- For research or performance analysis
+### How Auto-Tuning Works
 
-**When NOT to use:**
+The system analyzes:
 
-- Regular jumps without a drop box (no calibration reference available)
-- Unknown drop box height (will calculate but results won't be accurate)
-- Video doesn't show the full drop from box to ground
+- **Video frame rate** - Adjusts smoothing windows and thresholds
+- **Tracking quality** - Adapts confidence levels and filtering
+- **Landmark visibility** - Determines outlier rejection needs
+- **Quality preset** - Balances speed vs accuracy based on user selection
 
-**How to measure your drop box:**
+### Quality Presets
 
-1. Use a tape measure or ruler
-2. Measure from top of box surface to ground
-3. Convert to meters (divide cm by 100)
-4. Examples:
-   - 30cm box = 0.30
-   - 40cm box = 0.40
-   - 60cm box = 0.60
+All analysis functions accept a `quality` parameter:
 
-**Measurement methods:**
-
-```text
-Without calibration:
-- Uses kinematic method with optional empirical correction factor
-- Accuracy: ⚠️ Unvalidated - requires empirical validation
-- Provides relative measurements for comparison
-
-With calibration (--drop-height 0.40):
-- Uses position-based measurement with scale factor from known drop height
-- Theoretically more accurate (⚠️ unvalidated)
-- Provides calibrated measurements based on known reference distance
-```text
+- **`"fast"`** - Quick processing, good for batch operations (50% faster)
+- **`"balanced"`** - Default, optimal for most use cases
+- **`"accurate"`** - Research-grade, maximum precision (slower)
 
 **Example:**
 
 ```bash
-# 40cm drop box
-kinemotion dropjump-analyze video.mp4 --drop-height 0.40
-
-# 60cm drop box with outputs
-kinemotion dropjump-analyze video.mp4 \
-  --drop-height 0.60 \
-  --json-output metrics.json \
-  --output debug.mp4
+# Fast processing for batch
+kinemotion dropjump-analyze videos/*.mp4 --batch --quality fast
 
-# Compare calibrated vs uncalibrated
-# Without calibration
-kinemotion dropjump-analyze video.mp4 --json-output uncalibrated.json
+# Accurate for research
+kinemotion dropjump-analyze video.mp4 --quality accurate --verbose
+```
 
-# With calibration
-kinemotion dropjump-analyze video.mp4 --drop-height 0.40 --json-output calibrated.json
-```text
+**Python API:**
 
-**JSON output with calibration:**
+```python
+from kinemotion import process_dropjump_video
 
-```json
-{
-  "jump_height_m": 0.339,                      // Primary (calibrated)
-  "jump_height_kinematic_m": 0.256,            // Kinematic-only (fallback)
-  "jump_height_trajectory_normalized": 0.0845  // Normalized measurement
-}
+metrics = process_dropjump_video(
+    "video.mp4",
+    quality="accurate",
+    verbose=True  # Shows selected parameters
+)
 ```text
 
 **Troubleshooting:**
@@ -1012,10 +965,9 @@ kinemotion dropjump-analyze video.mp4 \
   --use-curvature \
   --adaptive-threshold \
   --use-com \
-  --drop-height 0.40 \
   --output debug_max.mp4 \
   --json-output metrics.json
-```text
+```
 
 **Effect on timing:**
 
@@ -1122,13 +1074,13 @@ kinemotion dropjump-analyze video.mp4 \
   --tracking-confidence 0.7
 ```text
 
-### Scenario 6: Drop Jump with Calibration
+### Scenario 6: Drop Jump with Expert Parameter Tuning
 
-- Standard drop jump analysis with 40cm box for accurate jump height
+- Drop jump analysis with manually tuned parameters for specific conditions
 
 ```bash
 kinemotion dropjump-analyze video.mp4 \
-  --drop-height 0.40 \
+  --quality accurate \
   --smoothing-window 5 \
   --velocity-threshold 0.02 \
   --min-contact-frames 3 \
@@ -1137,9 +1089,9 @@ kinemotion dropjump-analyze video.mp4 \
   --tracking-confidence 0.5 \
   --output debug.mp4 \
   --json-output metrics.json
-```text
+```
 
-**Note:** Calibration provides theoretical benefits by using known reference distances, but actual accuracy requires empirical validation against gold standards (force plates, 3D motion capture).
+**Note:** Expert parameters should only be adjusted when the automatic tuning doesn't work for your specific video conditions. The `--verbose` flag shows auto-selected parameters for comparison.
 
 ### Scenario 7: High-Performance Drop Jump Analysis (Maximum Accuracy)
 
@@ -1147,7 +1099,7 @@ kinemotion dropjump-analyze video.mp4 \
 
 ```bash
 kinemotion dropjump-analyze video.mp4 \
-  --drop-height 0.40 \
+  --quality accurate \
   --use-curvature \
   --outlier-rejection \
   --output debug_max.mp4 \
@@ -1158,13 +1110,13 @@ kinemotion dropjump-analyze video.mp4 \
   --visibility-threshold 0.6 \
   --detection-confidence 0.5 \
   --tracking-confidence 0.5
-```text
+```
 
-**Note:** This combines theoretical improvements for drop jumps (⚠️ all unvalidated):
+**Note:** This uses maximum accuracy settings with advanced filtering:
 
-- Calibration: Uses known reference distance for scaling
-- Curvature analysis: Enhanced timing precision (enabled by default)
-- Outlier rejection: Removes tracking glitches (enabled by default)
+- Curvature analysis: Enhanced timing precision
+- Outlier rejection: Removes tracking glitches
+- Fine-tuned expert parameters: Optimized for clean, high-quality videos
 
 ---
 
@@ -1315,7 +1267,6 @@ When bilateral-filter disabled (default):
 | visibility-threshold | None (simple comparison) |
 | detection-confidence | Medium (affects MediaPipe workload) |
 | tracking-confidence | Medium (affects MediaPipe workload) |
-| drop-height | None (scaling calculation only) |
 | use-curvature | Negligible (reuses smoothed trajectory) |
 
 **Notes:**
@@ -1390,6 +1341,7 @@ kinemotion dropjump-analyze video.mp4 --output v3.mp4 --json-output v3.json --sm
 | `visibility-threshold` | 0.5 | 0.3-0.8 | Landmark trust level | Occlusions or need high confidence |
 | `detection-confidence` | 0.5 | 0.1-0.9 | Initial pose detection | Multiple people or poor visibility |
 | `tracking-confidence` | 0.5 | 0.1-0.9 | Tracking persistence | Tracking lost or wrong person tracked |
-| `drop-height` | None | 0.1-2.0 | Jump height calibration | Drop jump with known box height |
 | `use-curvature` | enabled | enabled/disabled | Timing refinement | Default: keep enabled for best accuracy |
+| `quality` | balanced | fast/balanced/accurate | Analysis speed vs accuracy | Use fast for batch, accurate for research |
+```
 ````

{kinemotion-0.15.1 → kinemotion-0.15.2}/docs/technical/framerate.md

@@ -232,11 +232,10 @@ More temporal samples = smoother velocity derivative:
 kinemotion dropjump-analyze video_30fps.mp4 \
   --smoothing-window 5 \
   --velocity-threshold 0.02 \
-  --min-contact-frames 3 \
-  --drop-height 0.40
-```text
+  --min-contact-frames 3
+```
 
-**Expected accuracy:** ~88% with calibration
+**Note:** Auto-tuning handles these parameters automatically. Manual overrides shown for illustration.
 
 ---
 
@@ -270,9 +269,8 @@ kinemotion dropjump-analyze video_30fps.mp4 \
 kinemotion dropjump-analyze video_60fps.mp4 \
   --smoothing-window 5 \
   --velocity-threshold 0.01 \      # halve (less motion per frame)
-  --min-contact-frames 6 \         # double (same time duration)
-  --drop-height 0.40
-```text
+  --min-contact-frames 6          # double (same time duration)
+```
 
 **Expected accuracy:** ~90-91% with calibration (+2-3% over 30fps)
 
@@ -310,9 +308,8 @@ kinemotion dropjump-analyze video_60fps.mp4 \
 kinemotion dropjump-analyze video_120fps.mp4 \
   --smoothing-window 5 \
   --velocity-threshold 0.005 \     # quarter (4× more frames)
-  --min-contact-frames 12 \        # quadruple
-  --drop-height 0.40
-```text
+  --min-contact-frames 12         # quadruple
+```
 
 **Expected accuracy:** ~91-92% with calibration (+3-4% over 30fps, +1% over 60fps)
 
@@ -353,9 +350,8 @@ kinemotion dropjump-analyze video_120fps.mp4 \
 kinemotion dropjump-analyze video_240fps.mp4 \
   --smoothing-window 5 \
   --velocity-threshold 0.0025 \    # 1/8× (8× more frames)
-  --min-contact-frames 24 \        # 8×
-  --drop-height 0.40
-```text
+  --min-contact-frames 24         # 8×
+```
 
 **Expected accuracy:** ~92-93% with calibration (+4-5% over 30fps, +1-2% over 60fps, +0.5% over 120fps)
 
@@ -427,9 +423,8 @@ kinemotion dropjump-analyze video_30fps.mp4 \
   --polyorder 2 \
   --velocity-threshold 0.02 \
   --min-contact-frames 3 \
-  --visibility-threshold 0.5 \
-  --drop-height 0.40
-```text
+  --visibility-threshold 0.5
+```
 
 #### 60 fps (2× frames)
 
@@ -439,9 +434,8 @@ kinemotion dropjump-analyze video_60fps.mp4 \
   --polyorder 2 \                 # same
   --velocity-threshold 0.01 \     # halve (2× more frames)
   --min-contact-frames 6 \        # double (2× more frames)
-  --visibility-threshold 0.5 \    # same
-  --drop-height 0.40
-```text
+  --visibility-threshold 0.5     # same
+```
 
 #### 120 fps (4× frames)
 
@@ -451,9 +445,8 @@ kinemotion dropjump-analyze video_120fps.mp4 \
   --polyorder 2 \                 # same
   --velocity-threshold 0.005 \    # quarter (4× more frames)
   --min-contact-frames 12 \       # quadruple (4× more frames)
-  --visibility-threshold 0.5 \    # same
-  --drop-height 0.40
-```text
+  --visibility-threshold 0.5     # same
+```
 
 #### 240 fps (8× frames)
 
@@ -463,9 +456,8 @@ kinemotion dropjump-analyze video_240fps.mp4 \
   --polyorder 2 \                 # same
   --velocity-threshold 0.0025 \   # 1/8× (8× more frames)
   --min-contact-frames 24 \       # 8× (8× more frames)
-  --visibility-threshold 0.5 \    # same
-  --drop-height 0.40
-```text
+  --visibility-threshold 0.5     # same
+```
 
 ### Auto-Detecting Frame Rate (Future Enhancement)
 

{kinemotion-0.15.1 → kinemotion-0.15.2}/pyproject.toml

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

{kinemotion-0.15.1 → kinemotion-0.15.2}/uv.lock

@@ -648,7 +648,7 @@ wheels = [
 
 [[package]]
 name = "kinemotion"
-version = "0.15.1"
+version = "0.15.2"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

kinemotion-0.15.1/docs/api/dropjump.md

@@ -1,81 +0,0 @@
-# Drop Jump API
-
-The drop jump API provides functions for analyzing drop jump videos and extracting kinematic metrics.
-
-## Quick Example
-
-```python
-from kinemotion import process_dropjump_video
-
-metrics = process_dropjump_video(
-    video_path="dropjump.mp4",
-    drop_height=0.40,  # meters
-    output_path="debug.mp4",  # optional
-    smoothing=True
-)
-
-print(f"Ground contact time: {metrics.ground_contact_time:.3f}s")
-print(f"Flight time: {metrics.flight_time:.3f}s")
-print(f"RSI: {metrics.reactive_strength_index:.2f}")
-```
-
-## Main Functions
-
-::: kinemotion.api.process_dropjump_video
-options:
-show_root_heading: true
-show_source: false
-
-::: kinemotion.api.process_dropjump_videos_bulk
-options:
-show_root_heading: true
-show_source: false
-
-## Configuration
-
-::: kinemotion.api.DropJumpVideoConfig
-options:
-show_root_heading: true
-show_source: false
-
-## Results
-
-::: kinemotion.api.DropJumpVideoResult
-options:
-show_root_heading: true
-show_source: false
-
-## Metrics
-
-::: kinemotion.dropjump.kinematics.DropJumpMetrics
-options:
-show_root_heading: true
-show_source: false
-
-## Key Parameters
-
-### drop_height
-
-**Required.** The height of the drop box in meters. This is critical for accurate velocity calculations.
-
-```python
-metrics = process_dropjump_video("video.mp4", drop_height=0.40)  # 40cm box
-```
-
-### smoothing
-
-Apply Savitzky-Golay smoothing to landmark positions before analysis. Reduces noise but may slightly delay event detection.
-
-Default: `True`
-
-### output_path
-
-Path to write debug video with overlay visualization. If not provided, no debug video is created.
-
-```python
-metrics = process_dropjump_video(
-    "video.mp4",
-    drop_height=0.40,
-    output_path="debug.mp4"
-)
-```