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

kinemotion/cli.py

@@ -1,22 +1,8 @@
 """Command-line interface for kinemotion analysis."""
 
-import json
-import sys
-from pathlib import Path
-
 import click
-import numpy as np
 
-from .core.pose import PoseTracker, compute_center_of_mass
-from .core.smoothing import smooth_landmarks, smooth_landmarks_advanced
-from .core.video_io import VideoProcessor
-from .dropjump.analysis import (
-    calculate_adaptive_threshold,
-    compute_average_foot_position,
-    detect_ground_contact,
-)
-from .dropjump.debug_overlay import DebugOverlayRenderer
-from .dropjump.kinematics import calculate_drop_jump_metrics
+from .dropjump.cli import dropjump_analyze
 
 
 @click.group()
@@ -26,374 +12,8 @@ def cli() -> None:
     pass
 
 
-@cli.command(name="dropjump-analyze")
-@click.argument("video_path", type=click.Path(exists=True))
-@click.option(
-    "--output",
-    "-o",
-    type=click.Path(),
-    help="Path for debug video output (optional)",
-)
-@click.option(
-    "--json-output",
-    "-j",
-    type=click.Path(),
-    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,
-)
-@click.option(
-    "--polyorder",
-    type=int,
-    default=2,
-    help=(
-        "Polynomial order for Savitzky-Golay smoothing "
-        "(2=quadratic, 3=cubic, must be < smoothing-window)"
-    ),
-    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)"
-    ),
-)
-@click.option(
-    "--bilateral-filter/--no-bilateral-filter",
-    default=False,
-    help=(
-        "Use bilateral temporal filter for edge-preserving smoothing "
-        "(default: disabled, experimental)"
-    ),
-)
-@click.option(
-    "--velocity-threshold",
-    type=float,
-    default=0.02,
-    help="Velocity threshold for contact detection (normalized units)",
-    show_default=True,
-)
-@click.option(
-    "--min-contact-frames",
-    type=int,
-    default=3,
-    help="Minimum frames for valid ground contact",
-    show_default=True,
-)
-@click.option(
-    "--visibility-threshold",
-    type=float,
-    default=0.5,
-    help="Minimum landmark visibility score (0-1)",
-    show_default=True,
-)
-@click.option(
-    "--detection-confidence",
-    type=float,
-    default=0.5,
-    help="Pose detection confidence threshold (0-1)",
-    show_default=True,
-)
-@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(
-    "--use-com/--use-feet",
-    default=False,
-    help="Track center of mass instead of feet for improved accuracy (default: feet)",
-)
-@click.option(
-    "--adaptive-threshold/--fixed-threshold",
-    default=False,
-    help="Auto-calibrate velocity threshold from video baseline (default: fixed)",
-)
-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,
-    use_com: bool,
-    adaptive_threshold: bool,
-) -> None:
-    """
-    Analyze drop-jump video to estimate ground contact time, flight time, and jump height.
-
-    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)
-
-    try:
-        # Initialize video processor
-        with VideoProcessor(video_path) as video:
-            click.echo(
-                f"Video: {video.width}x{video.height} @ {video.fps:.2f} fps, "
-                f"{video.frame_count} frames",
-                err=True,
-            )
-
-            # Initialize pose tracker
-            tracker = PoseTracker(
-                min_detection_confidence=detection_confidence,
-                min_tracking_confidence=tracking_confidence,
-            )
-
-            # Process all frames
-            click.echo("Tracking pose landmarks...", err=True)
-            landmarks_sequence = []
-            frames = []
-
-            frame_idx = 0
-            with click.progressbar(
-                length=video.frame_count, label="Processing frames"
-            ) as bar:
-                while True:
-                    frame = video.read_frame()
-                    if frame is None:
-                        break
-
-                    frames.append(frame)
-                    landmarks = tracker.process_frame(frame)
-                    landmarks_sequence.append(landmarks)
-
-                    frame_idx += 1
-                    bar.update(1)
-
-            tracker.close()
-
-            if not landmarks_sequence:
-                click.echo("Error: No frames processed", err=True)
-                sys.exit(1)
-
-            # Smooth landmarks
-            if outlier_rejection or bilateral_filter:
-                if outlier_rejection:
-                    click.echo(
-                        "Smoothing landmarks with outlier rejection...", err=True
-                    )
-                if 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,
-                )
-            else:
-                click.echo("Smoothing landmarks...", err=True)
-                smoothed_landmarks = smooth_landmarks(
-                    landmarks_sequence, window_length=smoothing_window, polyorder=polyorder
-                )
-
-            # Extract vertical positions (either CoM or feet)
-            if use_com:
-                click.echo("Computing center of mass positions...", err=True)
-            else:
-                click.echo("Extracting foot positions...", err=True)
-
-            position_list: list[float] = []
-            visibilities_list: list[float] = []
-
-            for frame_landmarks in smoothed_landmarks:
-                if frame_landmarks:
-                    if use_com:
-                        # Use center of mass estimation
-                        com_x, com_y, com_vis = compute_center_of_mass(
-                            frame_landmarks, visibility_threshold=visibility_threshold
-                        )
-                        position_list.append(com_y)
-                        visibilities_list.append(com_vis)
-                    else:
-                        # Use average foot position (original method)
-                        foot_x, foot_y = compute_average_foot_position(frame_landmarks)
-                        position_list.append(foot_y)
-
-                        # Average visibility of foot landmarks
-                        foot_vis = []
-                        for key in [
-                            "left_ankle",
-                            "right_ankle",
-                            "left_heel",
-                            "right_heel",
-                        ]:
-                            if key in frame_landmarks:
-                                foot_vis.append(frame_landmarks[key][2])
-                        visibilities_list.append(
-                            float(np.mean(foot_vis)) if foot_vis else 0.0
-                        )
-                else:
-                    # Use previous position if available, otherwise default
-                    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)
-
-            # Calculate adaptive threshold if enabled
-            if adaptive_threshold:
-                click.echo("Calculating adaptive velocity threshold...", err=True)
-                velocity_threshold = calculate_adaptive_threshold(
-                    vertical_positions,
-                    video.fps,
-                    baseline_duration=3.0,
-                    multiplier=1.5,
-                    smoothing_window=smoothing_window,
-                    polyorder=polyorder,
-                )
-                click.echo(
-                    f"Adaptive threshold: {velocity_threshold:.4f} "
-                    f"(auto-calibrated from baseline)",
-                    err=True,
-                )
-
-            # Detect ground contact
-            contact_states = detect_ground_contact(
-                vertical_positions,
-                velocity_threshold=velocity_threshold,
-                min_contact_frames=min_contact_frames,
-                visibility_threshold=visibility_threshold,
-                visibilities=visibilities,
-            )
-
-            # Calculate metrics
-            click.echo("Calculating metrics...", err=True)
-            if use_com:
-                click.echo("Using center of mass tracking for improved accuracy", err=True)
-            if drop_height:
-                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,
-            )
-
-            # Output metrics as JSON
-            metrics_dict = metrics.to_dict()
-            metrics_json = json.dumps(metrics_dict, indent=2)
-
-            if json_output:
-                output_path = Path(json_output)
-                output_path.write_text(metrics_json)
-                click.echo(f"Metrics written to: {json_output}", err=True)
-            else:
-                click.echo(metrics_json)
-
-            # 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:
-                    click.echo(
-                        f"Source video encoded: {video.width}x{video.height}",
-                        err=True,
-                    )
-                    click.echo(
-                        f"Output dimensions: {video.display_width}x{video.display_height} "
-                        f"(respecting display aspect ratio)",
-                        err=True,
-                    )
-                else:
-                    click.echo(
-                        f"Output dimensions: {video.width}x{video.height} "
-                        f"(matching source video aspect ratio)",
-                        err=True,
-                    )
-                with DebugOverlayRenderer(
-                    output,
-                    video.width,
-                    video.height,
-                    video.display_width,
-                    video.display_height,
-                    video.fps,
-                ) as renderer:
-                    with click.progressbar(
-                        length=len(frames), label="Rendering frames"
-                    ) as bar:
-                        for i, frame in enumerate(frames):
-                            annotated = renderer.render_frame(
-                                frame,
-                                smoothed_landmarks[i],
-                                contact_states[i],
-                                i,
-                                metrics,
-                                use_com=use_com,
-                            )
-                            renderer.write_frame(annotated)
-                            bar.update(1)
-
-                click.echo(f"Debug video saved: {output}", err=True)
-
-            click.echo("Analysis complete!", err=True)
-
-    except Exception as e:
-        click.echo(f"Error: {str(e)}", err=True)
-        sys.exit(1)
+# Register commands from submodules
+cli.add_command(dropjump_analyze)
 
 
 if __name__ == "__main__":

kinemotion/dropjump/analysis.py

@@ -95,16 +95,24 @@ def detect_ground_contact(
     min_contact_frames: int = 3,
     visibility_threshold: float = 0.5,
     visibilities: np.ndarray | None = None,
+    window_length: int = 5,
+    polyorder: int = 2,
 ) -> list[ContactState]:
     """
     Detect when feet are in contact with ground based on vertical motion.
 
+    Uses derivative-based velocity calculation via Savitzky-Golay filter for smooth,
+    accurate velocity estimates. This is consistent with the velocity calculation used
+    throughout the pipeline for sub-frame interpolation and curvature analysis.
+
     Args:
         foot_positions: Array of foot y-positions (normalized, 0-1, where 1 is bottom)
         velocity_threshold: Threshold for vertical velocity to consider stationary
         min_contact_frames: Minimum consecutive frames to confirm contact
         visibility_threshold: Minimum visibility score to trust landmark
         visibilities: Array of visibility scores for each frame
+        window_length: Window size for velocity derivative calculation (must be odd)
+        polyorder: Polynomial order for Savitzky-Golay filter (default: 2)
 
     Returns:
         List of ContactState for each frame
@@ -115,8 +123,12 @@ def detect_ground_contact(
     if n_frames < 2:
         return states
 
-    # Compute vertical velocity (positive = moving down in image coordinates)
-    velocities = np.diff(foot_positions, prepend=foot_positions[0])
+    # Compute vertical velocity using derivative-based method
+    # This provides smoother, more accurate velocity estimates than frame-to-frame differences
+    # and is consistent with the velocity calculation used for sub-frame interpolation
+    velocities = compute_velocity_from_derivative(
+        foot_positions, window_length=window_length, polyorder=polyorder
+    )
 
     # Detect potential contact frames based on low velocity
     is_stationary = np.abs(velocities) < velocity_threshold

kinemotion/dropjump/cli.py

@@ -0,0 +1,361 @@
+"""Command-line interface for drop jump analysis."""
+
+import json
+import sys
+from pathlib import Path
+
+import click
+import numpy as np
+
+from ..core.pose import PoseTracker
+from ..core.smoothing import smooth_landmarks, smooth_landmarks_advanced
+from ..core.video_io import VideoProcessor
+from .analysis import (
+    compute_average_foot_position,
+    detect_ground_contact,
+)
+from .debug_overlay import DebugOverlayRenderer
+from .kinematics import calculate_drop_jump_metrics
+
+
+@click.command(name="dropjump-analyze")
+@click.argument("video_path", type=click.Path(exists=True))
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(),
+    help="Path for debug video output (optional)",
+)
+@click.option(
+    "--json-output",
+    "-j",
+    type=click.Path(),
+    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,
+)
+@click.option(
+    "--polyorder",
+    type=int,
+    default=2,
+    help=(
+        "Polynomial order for Savitzky-Golay smoothing "
+        "(2=quadratic, 3=cubic, must be < smoothing-window)"
+    ),
+    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)"
+    ),
+)
+@click.option(
+    "--bilateral-filter/--no-bilateral-filter",
+    default=False,
+    help=(
+        "Use bilateral temporal filter for edge-preserving smoothing "
+        "(default: disabled, experimental)"
+    ),
+)
+@click.option(
+    "--velocity-threshold",
+    type=float,
+    default=0.02,
+    help="Velocity threshold for contact detection (normalized units)",
+    show_default=True,
+)
+@click.option(
+    "--min-contact-frames",
+    type=int,
+    default=3,
+    help="Minimum frames for valid ground contact",
+    show_default=True,
+)
+@click.option(
+    "--visibility-threshold",
+    type=float,
+    default=0.5,
+    help="Minimum landmark visibility score (0-1)",
+    show_default=True,
+)
+@click.option(
+    "--detection-confidence",
+    type=float,
+    default=0.5,
+    help="Pose detection confidence threshold (0-1)",
+    show_default=True,
+)
+@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,
+)
+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,
+) -> None:
+    """
+    Analyze drop-jump video to estimate ground contact time, flight time, and jump height.
+
+    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)
+
+    try:
+        # Initialize video processor
+        with VideoProcessor(video_path) as video:
+            click.echo(
+                f"Video: {video.width}x{video.height} @ {video.fps:.2f} fps, "
+                f"{video.frame_count} frames",
+                err=True,
+            )
+
+            # Initialize pose tracker
+            tracker = PoseTracker(
+                min_detection_confidence=detection_confidence,
+                min_tracking_confidence=tracking_confidence,
+            )
+
+            # Process all frames
+            click.echo("Tracking pose landmarks...", err=True)
+            landmarks_sequence = []
+            frames = []
+
+            frame_idx = 0
+            with click.progressbar(
+                length=video.frame_count, label="Processing frames"
+            ) as bar:
+                while True:
+                    frame = video.read_frame()
+                    if frame is None:
+                        break
+
+                    frames.append(frame)
+                    landmarks = tracker.process_frame(frame)
+                    landmarks_sequence.append(landmarks)
+
+                    frame_idx += 1
+                    bar.update(1)
+
+            tracker.close()
+
+            if not landmarks_sequence:
+                click.echo("Error: No frames processed", err=True)
+                sys.exit(1)
+
+            # Smooth landmarks
+            if outlier_rejection or bilateral_filter:
+                if outlier_rejection:
+                    click.echo(
+                        "Smoothing landmarks with outlier rejection...", err=True
+                    )
+                if 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,
+                )
+            else:
+                click.echo("Smoothing landmarks...", err=True)
+                smoothed_landmarks = smooth_landmarks(
+                    landmarks_sequence, window_length=smoothing_window, polyorder=polyorder
+                )
+
+            # Extract vertical positions from feet
+            click.echo("Extracting foot positions...", err=True)
+
+            position_list: list[float] = []
+            visibilities_list: list[float] = []
+
+            for frame_landmarks in smoothed_landmarks:
+                if frame_landmarks:
+                    # Use average foot position
+                    _, foot_y = compute_average_foot_position(frame_landmarks)
+                    position_list.append(foot_y)
+
+                    # Average visibility of foot landmarks
+                    foot_vis = []
+                    for key in [
+                        "left_ankle",
+                        "right_ankle",
+                        "left_heel",
+                        "right_heel",
+                    ]:
+                        if key in frame_landmarks:
+                            foot_vis.append(frame_landmarks[key][2])
+                    visibilities_list.append(
+                        float(np.mean(foot_vis)) if foot_vis else 0.0
+                    )
+                else:
+                    # Use previous position if available, otherwise default
+                    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
+            contact_states = detect_ground_contact(
+                vertical_positions,
+                velocity_threshold=velocity_threshold,
+                min_contact_frames=min_contact_frames,
+                visibility_threshold=visibility_threshold,
+                visibilities=visibilities,
+                window_length=smoothing_window,
+                polyorder=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,
+                )
+            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,
+            )
+
+            # Output metrics as JSON
+            metrics_dict = metrics.to_dict()
+            metrics_json = json.dumps(metrics_dict, indent=2)
+
+            if json_output:
+                output_path = Path(json_output)
+                output_path.write_text(metrics_json)
+                click.echo(f"Metrics written to: {json_output}", err=True)
+            else:
+                click.echo(metrics_json)
+
+            # 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:
+                    click.echo(
+                        f"Source video encoded: {video.width}x{video.height}",
+                        err=True,
+                    )
+                    click.echo(
+                        f"Output dimensions: {video.display_width}x{video.display_height} "
+                        f"(respecting display aspect ratio)",
+                        err=True,
+                    )
+                else:
+                    click.echo(
+                        f"Output dimensions: {video.width}x{video.height} "
+                        f"(matching source video aspect ratio)",
+                        err=True,
+                    )
+                with DebugOverlayRenderer(
+                    output,
+                    video.width,
+                    video.height,
+                    video.display_width,
+                    video.display_height,
+                    video.fps,
+                ) as renderer:
+                    with click.progressbar(
+                        length=len(frames), label="Rendering frames"
+                    ) as bar:
+                        for i, frame in enumerate(frames):
+                            annotated = renderer.render_frame(
+                                frame,
+                                smoothed_landmarks[i],
+                                contact_states[i],
+                                i,
+                                metrics,
+                                use_com=False,
+                            )
+                            renderer.write_frame(annotated)
+                            bar.update(1)
+
+                click.echo(f"Debug video saved: {output}", err=True)
+
+            click.echo("Analysis complete!", err=True)
+
+    except Exception as e:
+        click.echo(f"Error: {str(e)}", err=True)
+        sys.exit(1)

kinemotion/dropjump/kinematics.py

@@ -113,6 +113,7 @@ def calculate_drop_jump_metrics(
     smoothing_window: int = 5,
     polyorder: int = 2,
     use_curvature: bool = True,
+    kinematic_correction_factor: float = 1.0,
 ) -> DropJumpMetrics:
     """
     Calculate drop-jump metrics from contact states and positions.
@@ -126,6 +127,9 @@ def calculate_drop_jump_metrics(
         smoothing_window: Window size for velocity/acceleration smoothing (must be odd)
         polyorder: Polynomial order for Savitzky-Golay filter (default: 2)
         use_curvature: Whether to use curvature analysis for refining transitions
+        kinematic_correction_factor: Correction factor for kinematic jump height calculation
+            (default: 1.0 = no correction). Historical testing suggested 1.35, but this is
+            unvalidated. Use calibrated measurement (--drop-height) for validated results.
 
     Returns:
         DropJumpMetrics object with calculated values
@@ -315,18 +319,30 @@ def calculate_drop_jump_metrics(
                 metrics.jump_height = height_normalized * scale_factor
                 metrics.jump_height_kinematic = jump_height_kinematic
             else:
-                # Use empirical correction factor for kinematic method
-                # Testing shows kinematic method underestimates by ~29% due to:
-                # 1. Contact detection timing (detects landing slightly early)
-                # 2. Frame rate limitations (30 fps = 33ms intervals)
-                # 3. Foot position vs center of mass difference
-                kinematic_correction_factor = 1.35
+                # Apply kinematic correction factor to kinematic method
+                # ⚠️ WARNING: Kinematic correction factor is EXPERIMENTAL and UNVALIDATED
+                #
+                # The kinematic method h = (g × t²) / 8 may underestimate jump height due to:
+                # 1. Contact detection timing (may detect landing slightly early/late)
+                # 2. Frame rate limitations (30 fps = 33ms intervals between samples)
+                # 3. Foot position vs center of mass difference (feet land before CoM peak)
+                #
+                # Default correction factor is 1.0 (no correction). Historical testing
+                # suggested 1.35 could improve accuracy, but:
+                # - This value has NOT been validated against gold standards
+                #   (force plates, motion capture)
+                # - The actual correction needed may vary by athlete, jump type, and video quality
+                # - Using a correction factor without validation is experimental
+                #
+                # 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_kinematic = jump_height_kinematic
         else:
             # Fallback to kinematic if no position data
             if drop_height_m is None:
-                kinematic_correction_factor = 1.35
+                # Apply kinematic correction factor (see detailed comment above)
                 metrics.jump_height = jump_height_kinematic * kinematic_correction_factor
             else:
                 metrics.jump_height = jump_height_kinematic

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.2.0
+Version: 0.4.0
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion
@@ -33,9 +33,7 @@ A video-based kinematic analysis tool for athletic performance. Analyzes side-vi
 ## Features
 
 - **Automatic pose tracking** using MediaPipe Pose landmarks
-- **Center of mass (CoM) tracking** - biomechanical CoM estimation for 3-5% accuracy improvement
-- **Adaptive velocity thresholding** - auto-calibrates from video baseline for 2-3% additional accuracy
-- **Ground contact detection** based on velocity and position (feet or CoM)
+- **Ground contact detection** based on foot velocity and position
 - **Derivative-based velocity** - smooth velocity calculation from position trajectory
 - **Trajectory curvature analysis** - acceleration patterns for refined event detection
 - **Sub-frame interpolation** - precise timing beyond frame boundaries for improved accuracy
@@ -44,13 +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)
-  - With CoM tracking: potential for 91-93% accuracy
-  - With adaptive thresholding + CoM: potential for 93-96% accuracy
+- **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
@@ -67,13 +77,13 @@ 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
@@ -120,46 +130,11 @@ kinemotion dropjump-analyze drop-jump.mp4 \
   --output debug.mp4
 ```
 
-### Center of Mass Tracking (Improved Accuracy)
-
-Use CoM tracking for 3-5% accuracy improvement:
-
-```bash
-# Basic CoM tracking
-kinemotion dropjump-analyze video.mp4 --use-com
-
-# CoM tracking with calibration for maximum accuracy
-kinemotion dropjump-analyze drop-jump.mp4 \
-  --use-com \
-  --drop-height 0.40 \
-  --output debug_com.mp4 \
-  --json-output metrics.json
-```
-
-### Adaptive Thresholding (Auto-Calibration)
-
-Auto-calibrate velocity threshold from video baseline for 2-3% accuracy improvement:
-
-```bash
-# Basic adaptive thresholding
-kinemotion dropjump-analyze video.mp4 --adaptive-threshold
-
-# Combined with CoM for maximum accuracy
-kinemotion dropjump-analyze video.mp4 \
-  --adaptive-threshold \
-  --use-com \
-  --drop-height 0.40 \
-  --output debug.mp4 \
-  --json-output metrics.json
-```
-
 ### Full Example (Maximum Accuracy)
 
 ```bash
-# With all accuracy improvements enabled (~93-96% accuracy)
+# With all accuracy improvements enabled
 kinemotion dropjump-analyze jump.mp4 \
-  --adaptive-threshold \
-  --use-com \
   --outlier-rejection \
   --drop-height 0.40 \
   --output debug.mp4 \
@@ -169,8 +144,6 @@ kinemotion dropjump-analyze jump.mp4 \
 
 # Alternative: With experimental bilateral filter
 kinemotion dropjump-analyze jump.mp4 \
-  --adaptive-threshold \
-  --use-com \
   --outlier-rejection \
   --bilateral-filter \
   --drop-height 0.40 \
@@ -183,6 +156,7 @@ kinemotion 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
@@ -270,38 +244,10 @@ kinemotion 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
 
-### Tracking Method
-
-- `--use-com / --use-feet` (default: --use-feet)
-  - Choose between center of mass (CoM) or foot-based tracking
-  - **CoM tracking** (`--use-com`): Uses biomechanical CoM estimation with Dempster's body segment parameters
-    - Head: 8%, Trunk: 50%, Thighs: 20%, Legs: 10%, Feet: 3% of body mass
-    - Tracks true body movement instead of foot position
-    - Reduces error from foot dorsiflexion/plantarflexion during flight
-    - **Accuracy improvement**: +3-5% over foot-based tracking
-  - **Foot tracking** (`--use-feet`): Traditional method using average ankle/heel positions
-    - Faster, simpler, well-tested baseline method
-  - **Tip**: Use `--use-com` for maximum accuracy, especially for drop jumps
-
-### Velocity Threshold Mode
-
-- `--adaptive-threshold / --fixed-threshold` (default: --fixed-threshold)
-  - Choose between adaptive or fixed velocity threshold for contact detection
-  - **Adaptive threshold** (`--adaptive-threshold`): Auto-calibrates from video baseline
-    - Analyzes first 3 seconds of video (assumed relatively stationary)
-    - Computes noise floor as 95th percentile of baseline velocity
-    - Sets threshold as 1.5× noise floor (bounded: 0.005-0.05)
-    - Adapts to camera distance, lighting, frame rate, and compression artifacts
-    - **Accuracy improvement**: +2-3% by eliminating manual tuning
-  - **Fixed threshold** (`--fixed-threshold`): Uses `--velocity-threshold` value (default: 0.02)
-    - Consistent, predictable behavior
-    - Requires manual tuning for optimal results
-  - **Tip**: Use `--adaptive-threshold` for varying video conditions or when unsure of optimal threshold
-
 ### Trajectory Analysis
 
 - `--use-curvature / --no-curvature` (default: --use-curvature)
@@ -337,6 +283,7 @@ kinemotion 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)
@@ -348,6 +295,7 @@ kinemotion 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)
@@ -363,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`
@@ -373,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`
@@ -383,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`
@@ -395,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)
@@ -406,18 +358,15 @@ 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 (13 points: feet, ankles, knees, hips, shoulders, nose) from each frame
-2. **Position Calculation**: Two methods available:
-   - **Foot-based** (default): Averages ankle, heel, and foot index positions
-   - **CoM-based** (--use-com): Biomechanical center of mass using Dempster's body segment parameters
-     - Head: 8%, Trunk: 50%, Thighs: 20%, Legs: 10%, Feet: 3% of body mass
-     - Weighted average reduces error from foot movement artifacts
+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
@@ -438,13 +387,14 @@ The debug video includes:
    - 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
@@ -492,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.2.0.dist-info → kinemotion-0.4.0.dist-info}/RECORD

@@ -1,16 +1,17 @@
 kinemotion/__init__.py,sha256=JhS0ZTgcTdcMH5WcIyWxEqZJPOoBUSKX8tT8hsG-xWk,98
-kinemotion/cli.py,sha256=afQiAWBQBbLM2SZnwFPZ0gr_jjVIQtkhYh5cHYWPeco,13532
+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=MsEnho8WeGFxStHpKVGbj7gzdb3MUfozksmlAReAkI0,18026
+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=bM1A6LGSDWbNOrRa_x2v9hXJOwxef69h3R_0naLZ4Zw,15092
-kinemotion-0.2.0.dist-info/METADATA,sha256=pJ1KUIaG6F7xljGjjmwLALM2j9IHEAE5eJ4F6lWB4Lc,20616
-kinemotion-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.2.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.2.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.2.0.dist-info/RECORD,,
+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,,