kinemotion 0.6.4__py3-none-any.whl → 0.7.1__py3-none-any.whl

kinemotion/dropjump/cli.py

@@ -3,10 +3,16 @@
 import json
 import sys
 from pathlib import Path
+from typing import Any
 
 import click
 import numpy as np
 
+from ..core.auto_tuning import (
+    QualityPreset,
+    analyze_video_sample,
+    auto_tune_parameters,
+)
 from ..core.pose import PoseTracker
 from ..core.smoothing import smooth_landmarks, smooth_landmarks_advanced
 from ..core.video_io import VideoProcessor
@@ -33,140 +39,102 @@ from .kinematics import calculate_drop_jump_metrics
     help="Path for JSON metrics output (default: stdout)",
 )
 @click.option(
-    "--smoothing-window",
-    type=int,
-    default=5,
-    help="Smoothing window size (must be odd, >= 3)",
-    show_default=True,
+    "--drop-height",
+    type=float,
+    required=True,
+    help=(
+        "Height of drop box/platform in meters (e.g., 0.40 for 40cm box) - "
+        "REQUIRED for accurate calibration"
+    ),
 )
 @click.option(
-    "--polyorder",
-    type=int,
-    default=2,
+    "--quality",
+    type=click.Choice(["fast", "balanced", "accurate"], case_sensitive=False),
+    default="balanced",
     help=(
-        "Polynomial order for Savitzky-Golay smoothing "
-        "(2=quadratic, 3=cubic, must be < smoothing-window)"
+        "Analysis quality preset: "
+        "fast (quick, less precise), "
+        "balanced (default, good for most cases), "
+        "accurate (research-grade, slower)"
     ),
     show_default=True,
 )
 @click.option(
-    "--outlier-rejection/--no-outlier-rejection",
-    default=True,
-    help=(
-        "Apply RANSAC and median-based outlier rejection to remove tracking glitches "
-        "(default: enabled, +1-2%% accuracy)"
-    ),
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Show auto-selected parameters and analysis details",
 )
+# Expert parameters (hidden in help, but always available for advanced users)
 @click.option(
-    "--bilateral-filter/--no-bilateral-filter",
-    default=False,
-    help=(
-        "Use bilateral temporal filter for edge-preserving smoothing "
-        "(default: disabled, experimental)"
-    ),
+    "--drop-start-frame",
+    type=int,
+    default=None,
+    help="[EXPERT] Manually specify frame where drop begins (overrides auto-detection)",
+)
+@click.option(
+    "--smoothing-window",
+    type=int,
+    default=None,
+    help="[EXPERT] Override auto-tuned smoothing window size",
 )
 @click.option(
     "--velocity-threshold",
     type=float,
-    default=0.02,
-    help="Velocity threshold for contact detection (normalized units)",
-    show_default=True,
+    default=None,
+    help="[EXPERT] Override auto-tuned velocity threshold",
 )
 @click.option(
     "--min-contact-frames",
     type=int,
-    default=3,
-    help="Minimum frames for valid ground contact",
-    show_default=True,
+    default=None,
+    help="[EXPERT] Override auto-tuned minimum contact frames",
 )
 @click.option(
     "--visibility-threshold",
     type=float,
-    default=0.5,
-    help="Minimum landmark visibility score (0-1)",
-    show_default=True,
+    default=None,
+    help="[EXPERT] Override visibility threshold",
 )
 @click.option(
     "--detection-confidence",
     type=float,
-    default=0.5,
-    help="Pose detection confidence threshold (0-1)",
-    show_default=True,
+    default=None,
+    help="[EXPERT] Override pose detection confidence",
 )
 @click.option(
     "--tracking-confidence",
     type=float,
-    default=0.5,
-    help="Pose tracking confidence threshold (0-1)",
-    show_default=True,
-)
-@click.option(
-    "--drop-height",
-    type=float,
     default=None,
-    help="Height of drop box/platform in meters (e.g., 0.40 for 40cm) - used for calibration",
-)
-@click.option(
-    "--use-curvature/--no-curvature",
-    default=True,
-    help="Use trajectory curvature analysis for refining transitions (default: enabled)",
-)
-@click.option(
-    "--kinematic-correction-factor",
-    type=float,
-    default=1.0,
-    help=(
-        "Correction factor for kinematic jump height (default: 1.0 = no correction). "
-        "Historical testing suggested 1.35, but this is UNVALIDATED. "
-        "Use --drop-height for validated measurements."
-    ),
-    show_default=True,
+    help="[EXPERT] Override pose tracking confidence",
 )
 def dropjump_analyze(
     video_path: str,
     output: str | None,
     json_output: str | None,
-    smoothing_window: int,
-    polyorder: int,
-    outlier_rejection: bool,
-    bilateral_filter: bool,
-    velocity_threshold: float,
-    min_contact_frames: int,
-    visibility_threshold: float,
-    detection_confidence: float,
-    tracking_confidence: float,
-    drop_height: float | None,
-    use_curvature: bool,
-    kinematic_correction_factor: float,
+    drop_height: float,
+    quality: str,
+    verbose: bool,
+    drop_start_frame: int | None,
+    smoothing_window: int | None,
+    velocity_threshold: float | None,
+    min_contact_frames: int | None,
+    visibility_threshold: float | None,
+    detection_confidence: float | None,
+    tracking_confidence: float | None,
 ) -> None:
     """
     Analyze drop-jump video to estimate ground contact time, flight time, and jump height.
 
+    Uses intelligent auto-tuning to select optimal parameters based on video characteristics.
+    Parameters are automatically adjusted for frame rate, tracking quality, and analysis preset.
+
     VIDEO_PATH: Path to the input video file
     """
     click.echo(f"Analyzing video: {video_path}", err=True)
 
-    # Validate parameters
-    if smoothing_window < 3:
-        click.echo("Error: smoothing-window must be >= 3", err=True)
-        sys.exit(1)
-
-    if smoothing_window % 2 == 0:
-        smoothing_window += 1
-        click.echo(
-            f"Adjusting smoothing-window to {smoothing_window} (must be odd)", err=True
-        )
-
-    if polyorder < 1:
-        click.echo("Error: polyorder must be >= 1", err=True)
-        sys.exit(1)
-
-    if polyorder >= smoothing_window:
-        click.echo(
-            f"Error: polyorder ({polyorder}) must be < smoothing-window ({smoothing_window})",
-            err=True,
-        )
-        sys.exit(1)
+    # Convert quality string to enum
+    quality_preset = QualityPreset(quality.lower())
 
     try:
         # Initialize video processor
@@ -177,10 +145,32 @@ def dropjump_analyze(
                 err=True,
             )
 
+            # ================================================================
+            # STEP 1: Auto-tune parameters based on video characteristics
+            # ================================================================
+
+            # Analyze video characteristics from a sample to determine optimal parameters
+            # We'll use detection/tracking confidence from quality preset for initial tracking
+            initial_detection_conf = 0.5
+            initial_tracking_conf = 0.5
+
+            if quality_preset == QualityPreset.FAST:
+                initial_detection_conf = 0.3
+                initial_tracking_conf = 0.3
+            elif quality_preset == QualityPreset.ACCURATE:
+                initial_detection_conf = 0.6
+                initial_tracking_conf = 0.6
+
+            # Override with expert values if provided
+            if detection_confidence is not None:
+                initial_detection_conf = detection_confidence
+            if tracking_confidence is not None:
+                initial_tracking_conf = tracking_confidence
+
             # Initialize pose tracker
             tracker = PoseTracker(
-                min_detection_confidence=detection_confidence,
-                min_tracking_confidence=tracking_confidence,
+                min_detection_confidence=initial_detection_conf,
+                min_tracking_confidence=initial_tracking_conf,
             )
 
             # Process all frames
@@ -189,6 +179,7 @@ def dropjump_analyze(
             frames = []
 
             frame_idx = 0
+            bar: Any
             with click.progressbar(
                 length=video.frame_count, label="Processing frames"
             ) as bar:
@@ -210,28 +201,90 @@ def dropjump_analyze(
                 click.echo("Error: No frames processed", err=True)
                 sys.exit(1)
 
-            # Smooth landmarks
-            if outlier_rejection or bilateral_filter:
-                if outlier_rejection:
+            # ================================================================
+            # STEP 2: Analyze video characteristics and auto-tune parameters
+            # ================================================================
+
+            characteristics = analyze_video_sample(
+                landmarks_sequence, video.fps, video.frame_count
+            )
+
+            # Auto-tune parameters based on video characteristics
+            params = auto_tune_parameters(characteristics, quality_preset)
+
+            # Apply expert overrides if provided
+            if smoothing_window is not None:
+                params.smoothing_window = smoothing_window
+            if velocity_threshold is not None:
+                params.velocity_threshold = velocity_threshold
+            if min_contact_frames is not None:
+                params.min_contact_frames = min_contact_frames
+            if visibility_threshold is not None:
+                params.visibility_threshold = visibility_threshold
+
+            # Show selected parameters if verbose
+            if verbose:
+                click.echo("\n" + "=" * 60, err=True)
+                click.echo("AUTO-TUNED PARAMETERS", err=True)
+                click.echo("=" * 60, err=True)
+                click.echo(f"Video FPS: {video.fps:.2f}", err=True)
+                click.echo(
+                    f"Tracking quality: {characteristics.tracking_quality} "
+                    f"(avg visibility: {characteristics.avg_visibility:.2f})",
+                    err=True,
+                )
+                click.echo(f"Quality preset: {quality_preset.value}", err=True)
+                click.echo("\nSelected parameters:", err=True)
+                click.echo(f"  smoothing_window: {params.smoothing_window}", err=True)
+                click.echo(f"  polyorder: {params.polyorder}", err=True)
+                click.echo(
+                    f"  velocity_threshold: {params.velocity_threshold:.4f}", err=True
+                )
+                click.echo(
+                    f"  min_contact_frames: {params.min_contact_frames}", err=True
+                )
+                click.echo(
+                    f"  visibility_threshold: {params.visibility_threshold}", err=True
+                )
+                click.echo(
+                    f"  detection_confidence: {params.detection_confidence}", err=True
+                )
+                click.echo(
+                    f"  tracking_confidence: {params.tracking_confidence}", err=True
+                )
+                click.echo(f"  outlier_rejection: {params.outlier_rejection}", err=True)
+                click.echo(f"  bilateral_filter: {params.bilateral_filter}", err=True)
+                click.echo(f"  use_curvature: {params.use_curvature}", err=True)
+                click.echo("=" * 60 + "\n", err=True)
+
+            # ================================================================
+            # STEP 3: Apply smoothing with auto-tuned parameters
+            # ================================================================
+
+            # Smooth landmarks using auto-tuned parameters
+            if params.outlier_rejection or params.bilateral_filter:
+                if params.outlier_rejection:
                     click.echo(
                         "Smoothing landmarks with outlier rejection...", err=True
                     )
-                if bilateral_filter:
+                if params.bilateral_filter:
                     click.echo(
                         "Using bilateral temporal filter for edge-preserving smoothing...",
                         err=True,
                     )
                 smoothed_landmarks = smooth_landmarks_advanced(
                     landmarks_sequence,
-                    window_length=smoothing_window,
-                    polyorder=polyorder,
-                    use_outlier_rejection=outlier_rejection,
-                    use_bilateral=bilateral_filter,
+                    window_length=params.smoothing_window,
+                    polyorder=params.polyorder,
+                    use_outlier_rejection=params.outlier_rejection,
+                    use_bilateral=params.bilateral_filter,
                 )
             else:
                 click.echo("Smoothing landmarks...", err=True)
                 smoothed_landmarks = smooth_landmarks(
-                    landmarks_sequence, window_length=smoothing_window, polyorder=polyorder
+                    landmarks_sequence,
+                    window_length=params.smoothing_window,
+                    polyorder=params.polyorder,
                 )
 
             # Extract vertical positions from feet
@@ -261,42 +314,40 @@ def dropjump_analyze(
                     )
                 else:
                     # Use previous position if available, otherwise default
-                    position_list.append(
-                        position_list[-1] if position_list else 0.5
-                    )
+                    position_list.append(position_list[-1] if position_list else 0.5)
                     visibilities_list.append(0.0)
 
             vertical_positions: np.ndarray = np.array(position_list)
             visibilities: np.ndarray = np.array(visibilities_list)
 
-            # Detect ground contact
+            # Detect ground contact using auto-tuned parameters
             contact_states = detect_ground_contact(
                 vertical_positions,
-                velocity_threshold=velocity_threshold,
-                min_contact_frames=min_contact_frames,
-                visibility_threshold=visibility_threshold,
+                velocity_threshold=params.velocity_threshold,
+                min_contact_frames=params.min_contact_frames,
+                visibility_threshold=params.visibility_threshold,
                 visibilities=visibilities,
-                window_length=smoothing_window,
-                polyorder=polyorder,
+                window_length=params.smoothing_window,
+                polyorder=params.polyorder,
             )
 
             # Calculate metrics
             click.echo("Calculating metrics...", err=True)
-            if drop_height:
-                click.echo(
-                    f"Using drop height calibration: {drop_height}m ({drop_height*100:.0f}cm)",
-                    err=True,
-                )
+            click.echo(
+                f"Using drop height calibration: {drop_height}m ({drop_height*100:.0f}cm)",
+                err=True,
+            )
             metrics = calculate_drop_jump_metrics(
                 contact_states,
                 vertical_positions,
                 video.fps,
                 drop_height_m=drop_height,
-                velocity_threshold=velocity_threshold,
-                smoothing_window=smoothing_window,
-                polyorder=polyorder,
-                use_curvature=use_curvature,
-                kinematic_correction_factor=kinematic_correction_factor,
+                drop_start_frame=drop_start_frame,
+                velocity_threshold=params.velocity_threshold,
+                smoothing_window=params.smoothing_window,
+                polyorder=params.polyorder,
+                use_curvature=params.use_curvature,
+                kinematic_correction_factor=1.0,  # Always 1.0 now (no experimental correction)
             )
 
             # Output metrics as JSON
@@ -313,7 +364,10 @@ def dropjump_analyze(
             # Generate debug video if requested
             if output:
                 click.echo(f"Generating debug video: {output}", err=True)
-                if video.display_width != video.width or video.display_height != video.height:
+                if (
+                    video.display_width != video.width
+                    or video.display_height != video.height
+                ):
                     click.echo(
                         f"Source video encoded: {video.width}x{video.height}",
                         err=True,
@@ -337,9 +391,10 @@ def dropjump_analyze(
                     video.display_height,
                     video.fps,
                 ) as renderer:
+                    render_bar: Any
                     with click.progressbar(
                         length=len(frames), label="Rendering frames"
-                    ) as bar:
+                    ) as render_bar:
                         for i, frame in enumerate(frames):
                             annotated = renderer.render_frame(
                                 frame,
@@ -350,7 +405,7 @@ def dropjump_analyze(
                                 use_com=False,
                             )
                             renderer.write_frame(annotated)
-                            bar.update(1)
+                            render_bar.update(1)
 
                 click.echo(f"Debug video saved: {output}", err=True)
 

kinemotion/dropjump/debug_overlay.py

@@ -38,7 +38,7 @@ class DebugOverlayRenderer:
         self.needs_resize = (display_width != width) or (display_height != height)
 
         # Try H.264 codec first (better quality/compatibility), fallback to mp4v
-        fourcc = cv2.VideoWriter_fourcc(*"avc1")  # type: ignore[attr-defined]
+        fourcc = cv2.VideoWriter_fourcc(*"avc1")
         # IMPORTANT: cv2.VideoWriter expects (width, height) tuple - NOT (height, width)
         # Write at display dimensions so video displays correctly without SAR metadata
         self.writer = cv2.VideoWriter(
@@ -47,7 +47,7 @@ class DebugOverlayRenderer:
 
         # Check if writer opened successfully, fallback to mp4v if not
         if not self.writer.isOpened():
-            fourcc = cv2.VideoWriter_fourcc(*"mp4v")  # type: ignore[attr-defined]
+            fourcc = cv2.VideoWriter_fourcc(*"mp4v")
             self.writer = cv2.VideoWriter(
                 output_path, fourcc, fps, (display_width, display_height)
             )
@@ -93,7 +93,9 @@ class DebugOverlayRenderer:
 
                 # Draw CoM with larger circle
                 color = (
-                    (0, 255, 0) if contact_state == ContactState.ON_GROUND else (0, 0, 255)
+                    (0, 255, 0)
+                    if contact_state == ContactState.ON_GROUND
+                    else (0, 0, 255)
                 )
                 cv2.circle(annotated, (px, py), 15, color, -1)
                 cv2.circle(annotated, (px, py), 17, (255, 255, 255), 2)  # White border
@@ -105,7 +107,9 @@ class DebugOverlayRenderer:
                     rh_x, rh_y, _ = landmarks["right_hip"]
                     hip_x = int((lh_x + rh_x) / 2 * self.width)
                     hip_y = int((lh_y + rh_y) / 2 * self.height)
-                    cv2.circle(annotated, (hip_x, hip_y), 8, (255, 165, 0), -1)  # Orange
+                    cv2.circle(
+                        annotated, (hip_x, hip_y), 8, (255, 165, 0), -1
+                    )  # Orange
                     # Draw line from hip to CoM
                     cv2.line(annotated, (hip_x, hip_y), (px, py), (255, 165, 0), 2)
             else:
@@ -116,7 +120,9 @@ class DebugOverlayRenderer:
 
                 # Draw foot position circle
                 color = (
-                    (0, 255, 0) if contact_state == ContactState.ON_GROUND else (0, 0, 255)
+                    (0, 255, 0)
+                    if contact_state == ContactState.ON_GROUND
+                    else (0, 0, 255)
                 )
                 cv2.circle(annotated, (px, py), 10, color, -1)
 

kinemotion/dropjump/kinematics.py

@@ -1,10 +1,10 @@
 """Kinematic calculations for drop-jump metrics."""
 
-
 import numpy as np
 
 from .analysis import (
     ContactState,
+    detect_drop_start,
     find_contact_phases,
     find_interpolated_phase_transitions_with_curvature,
 )
@@ -109,6 +109,7 @@ def calculate_drop_jump_metrics(
     foot_y_positions: np.ndarray,
     fps: float,
     drop_height_m: float | None = None,
+    drop_start_frame: int | None = None,
     velocity_threshold: float = 0.02,
     smoothing_window: int = 5,
     polyorder: int = 2,
@@ -135,6 +136,20 @@ def calculate_drop_jump_metrics(
         DropJumpMetrics object with calculated values
     """
     metrics = DropJumpMetrics()
+
+    # Detect or use manually specified drop jump start frame
+    if drop_start_frame is None:
+        # Auto-detect where drop jump actually starts (skip initial stationary period)
+        drop_start_frame = detect_drop_start(
+            foot_y_positions,
+            fps,
+            min_stationary_duration=0.5,  # 0.5s stable period (~30 frames @ 60fps)
+            position_change_threshold=0.005,  # 0.5% of frame height - sensitive to drop start
+            smoothing_window=smoothing_window,
+        )
+    # If manually specified or auto-detected, use it
+    drop_start_frame_value = drop_start_frame if drop_start_frame is not None else 0
+
     phases = find_contact_phases(contact_states)
 
     # Get interpolated phases with curvature-based refinement
@@ -148,6 +163,23 @@ def calculate_drop_jump_metrics(
         use_curvature,
     )
 
+    if not phases:
+        return metrics
+
+    # Filter phases to only include those after drop start
+    # This removes the initial stationary period where athlete is standing on box
+    if drop_start_frame_value > 0:
+        phases = [
+            (start, end, state)
+            for start, end, state in phases
+            if end >= drop_start_frame_value
+        ]
+        interpolated_phases = [
+            (start, end, state)
+            for start, end, state in interpolated_phases
+            if end >= drop_start_frame_value
+        ]
+
     if not phases:
         return metrics
 
@@ -177,7 +209,9 @@ def calculate_drop_jump_metrics(
 
         # Find ground phase after first air phase
         ground_after_air = [
-            (start, end, idx) for start, end, idx in ground_phases if idx > first_air_idx
+            (start, end, idx)
+            for start, end, idx in ground_phases
+            if idx > first_air_idx
         ]
 
         if ground_after_air and first_ground_idx < first_air_idx:
@@ -241,7 +275,9 @@ def calculate_drop_jump_metrics(
             # Look back a few frames to get stable position on box
             lookback_start = max(0, first_air_start - 5)
             if lookback_start < first_air_start:
-                initial_position = float(np.mean(foot_y_positions[lookback_start:first_air_start]))
+                initial_position = float(
+                    np.mean(foot_y_positions[lookback_start:first_air_start])
+                )
             else:
                 initial_position = float(foot_y_positions[first_air_start])
 
@@ -337,13 +373,17 @@ def calculate_drop_jump_metrics(
                 # For validated measurements, use:
                 # - Calibrated measurement with --drop-height parameter
                 # - Or compare against validated measurement systems
-                metrics.jump_height = jump_height_kinematic * kinematic_correction_factor
+                metrics.jump_height = (
+                    jump_height_kinematic * kinematic_correction_factor
+                )
                 metrics.jump_height_kinematic = jump_height_kinematic
         else:
             # Fallback to kinematic if no position data
             if drop_height_m is None:
                 # Apply kinematic correction factor (see detailed comment above)
-                metrics.jump_height = jump_height_kinematic * kinematic_correction_factor
+                metrics.jump_height = (
+                    jump_height_kinematic * kinematic_correction_factor
+                )
             else:
                 metrics.jump_height = jump_height_kinematic
             metrics.jump_height_kinematic = jump_height_kinematic