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

{dropjump → kinemotion/dropjump}/cli.py

@@ -1,4 +1,4 @@
-"""Command-line interface for kinemetry analysis."""
+"""Command-line interface for drop jump analysis."""
 
 import json
 import sys
@@ -7,24 +7,18 @@ from pathlib import Path
 import click
 import numpy as np
 
-from .contact_detection import (
+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
-from .pose_tracker import PoseTracker
-from .smoothing import smooth_landmarks
-from .video_io import DebugOverlayRenderer, VideoProcessor
 
 
-@click.group()
-@click.version_option(package_name="dropjump-analyze")
-def cli() -> None:
-    """Kinemetry: Video-based kinematic analysis for athletic performance."""
-    pass
-
-
-@cli.command(name="dropjump-analyze")
+@click.command(name="dropjump-analyze")
 @click.argument("video_path", type=click.Path(exists=True))
 @click.option(
     "--output",
@@ -45,6 +39,32 @@ def cli() -> None:
     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,
@@ -91,11 +111,25 @@ def cli() -> None:
     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,
@@ -103,6 +137,7 @@ def dropjump_analyze(
     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.
@@ -122,6 +157,17 @@ def dropjump_analyze(
             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:
@@ -165,20 +211,40 @@ def dropjump_analyze(
                 sys.exit(1)
 
             # Smooth landmarks
-            click.echo("Smoothing landmarks...", err=True)
-            smoothed_landmarks = smooth_landmarks(
-                landmarks_sequence, window_length=smoothing_window
-            )
+            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)
 
-            # Extract foot positions
-            click.echo("Detecting ground contact...", err=True)
-            foot_positions_list: list[float] = []
+            position_list: list[float] = []
             visibilities_list: list[float] = []
 
             for frame_landmarks in smoothed_landmarks:
                 if frame_landmarks:
-                    foot_x, foot_y = compute_average_foot_position(frame_landmarks)
-                    foot_positions_list.append(foot_y)
+                    # Use average foot position
+                    _, foot_y = compute_average_foot_position(frame_landmarks)
+                    position_list.append(foot_y)
 
                     # Average visibility of foot landmarks
                     foot_vis = []
@@ -195,21 +261,23 @@ def dropjump_analyze(
                     )
                 else:
                     # Use previous position if available, otherwise default
-                    foot_positions_list.append(
-                        foot_positions_list[-1] if foot_positions_list else 0.5
+                    position_list.append(
+                        position_list[-1] if position_list else 0.5
                     )
                     visibilities_list.append(0.0)
 
-            foot_positions: np.ndarray = np.array(foot_positions_list)
+            vertical_positions: np.ndarray = np.array(position_list)
             visibilities: np.ndarray = np.array(visibilities_list)
 
             # Detect ground contact
             contact_states = detect_ground_contact(
-                foot_positions,
+                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
@@ -221,12 +289,14 @@ def dropjump_analyze(
                 )
             metrics = calculate_drop_jump_metrics(
                 contact_states,
-                foot_positions,
+                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
@@ -277,6 +347,7 @@ def dropjump_analyze(
                                 contact_states[i],
                                 i,
                                 metrics,
+                                use_com=False,
                             )
                             renderer.write_frame(annotated)
                             bar.update(1)
@@ -288,7 +359,3 @@ def dropjump_analyze(
     except Exception as e:
         click.echo(f"Error: {str(e)}", err=True)
         sys.exit(1)
-
-
-if __name__ == "__main__":
-    cli()

dropjump/video_io.py → kinemotion/dropjump/debug_overlay.py

@@ -1,131 +1,13 @@
-"""Video I/O and debug overlay rendering."""
-
-
-import json
-import subprocess
+"""Debug overlay rendering for drop jump analysis."""
 
 import cv2
 import numpy as np
 
-from .contact_detection import ContactState, compute_average_foot_position
+from ..core.pose import compute_center_of_mass
+from .analysis import ContactState, compute_average_foot_position
 from .kinematics import DropJumpMetrics
 
 
-class VideoProcessor:
-    """
-    Handles video reading and processing.
-
-    IMPORTANT: This class preserves the exact aspect ratio of the source video.
-    No dimensions are hardcoded - all dimensions are extracted from actual frame data.
-    """
-
-    def __init__(self, video_path: str):
-        """
-        Initialize video processor.
-
-        Args:
-            video_path: Path to input video file
-        """
-        self.video_path = video_path
-        self.cap = cv2.VideoCapture(video_path)
-
-        if not self.cap.isOpened():
-            raise ValueError(f"Could not open video: {video_path}")
-
-        self.fps = self.cap.get(cv2.CAP_PROP_FPS)
-        self.frame_count = int(self.cap.get(cv2.CAP_PROP_FRAME_COUNT))
-
-        # Read first frame to get actual dimensions
-        # This is critical for preserving aspect ratio, especially with mobile videos
-        # that have rotation metadata. OpenCV properties (CAP_PROP_FRAME_WIDTH/HEIGHT)
-        # may return incorrect dimensions, so we read the actual frame data.
-        ret, first_frame = self.cap.read()
-        if ret:
-            # frame.shape is (height, width, channels) - extract actual dimensions
-            self.height, self.width = first_frame.shape[:2]
-            self.cap.set(cv2.CAP_PROP_POS_FRAMES, 0)  # Reset to beginning
-        else:
-            # Fallback to video properties if can't read frame
-            self.width = int(self.cap.get(cv2.CAP_PROP_FRAME_WIDTH))
-            self.height = int(self.cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
-
-        # Calculate display dimensions considering SAR (Sample Aspect Ratio)
-        # Mobile videos often have non-square pixels encoded in SAR metadata
-        # OpenCV doesn't directly expose SAR, but we need to handle display correctly
-        self.display_width = self.width
-        self.display_height = self.height
-        self._calculate_display_dimensions()
-
-    def _calculate_display_dimensions(self) -> None:
-        """
-        Calculate display dimensions by reading SAR metadata from video file.
-
-        Many mobile videos use non-square pixels (SAR != 1:1), which means
-        the encoded dimensions differ from how the video should be displayed.
-        We use ffprobe to extract this metadata.
-        """
-        try:
-            # Use ffprobe to get SAR metadata
-            result = subprocess.run(
-                [
-                    "ffprobe",
-                    "-v",
-                    "quiet",
-                    "-print_format",
-                    "json",
-                    "-show_streams",
-                    "-select_streams",
-                    "v:0",
-                    self.video_path,
-                ],
-                capture_output=True,
-                text=True,
-                timeout=5,
-            )
-
-            if result.returncode == 0:
-                data = json.loads(result.stdout)
-                if "streams" in data and len(data["streams"]) > 0:
-                    stream = data["streams"][0]
-                    sar_str = stream.get("sample_aspect_ratio", "1:1")
-
-                    # Parse SAR (e.g., "270:473")
-                    if sar_str and ":" in sar_str:
-                        sar_parts = sar_str.split(":")
-                        sar_width = int(sar_parts[0])
-                        sar_height = int(sar_parts[1])
-
-                        # Calculate display dimensions
-                        # DAR = (width * SAR_width) / (height * SAR_height)
-                        if sar_width != sar_height:
-                            self.display_width = int(
-                                self.width * sar_width / sar_height
-                            )
-                            self.display_height = self.height
-        except (subprocess.TimeoutExpired, FileNotFoundError, json.JSONDecodeError):
-            # If ffprobe fails, keep original dimensions (square pixels)
-            pass
-
-    def read_frame(self) -> np.ndarray | None:
-        """Read next frame from video."""
-        ret, frame = self.cap.read()
-        return frame if ret else None
-
-    def reset(self) -> None:
-        """Reset video to beginning."""
-        self.cap.set(cv2.CAP_PROP_POS_FRAMES, 0)
-
-    def close(self) -> None:
-        """Release video capture."""
-        self.cap.release()
-
-    def __enter__(self) -> "VideoProcessor":
-        return self
-
-    def __exit__(self, exc_type, exc_val, exc_tb) -> None:  # type: ignore[no-untyped-def]
-        self.close()
-
-
 class DebugOverlayRenderer:
     """Renders debug information on video frames."""
 
@@ -183,6 +65,7 @@ class DebugOverlayRenderer:
         contact_state: ContactState,
         frame_idx: int,
         metrics: DropJumpMetrics | None = None,
+        use_com: bool = False,
     ) -> np.ndarray:
         """
         Render debug overlay on frame.
@@ -193,6 +76,7 @@ class DebugOverlayRenderer:
             contact_state: Ground contact state
             frame_idx: Current frame index
             metrics: Drop-jump metrics (optional)
+            use_com: Whether to visualize CoM instead of feet (optional)
 
         Returns:
             Frame with debug overlay
@@ -201,25 +85,50 @@ class DebugOverlayRenderer:
 
         # Draw landmarks if available
         if landmarks:
-            foot_x, foot_y = compute_average_foot_position(landmarks)
-            px = int(foot_x * self.width)
-            py = int(foot_y * self.height)
-
-            # Draw foot position circle
-            color = (
-                (0, 255, 0) if contact_state == ContactState.ON_GROUND else (0, 0, 255)
-            )
-            cv2.circle(annotated, (px, py), 10, color, -1)
-
-            # Draw individual foot landmarks
-            foot_keys = ["left_ankle", "right_ankle", "left_heel", "right_heel"]
-            for key in foot_keys:
-                if key in landmarks:
-                    x, y, vis = landmarks[key]
-                    if vis > 0.5:
-                        lx = int(x * self.width)
-                        ly = int(y * self.height)
-                        cv2.circle(annotated, (lx, ly), 5, (255, 255, 0), -1)
+            if use_com:
+                # Draw center of mass position
+                com_x, com_y, com_vis = compute_center_of_mass(landmarks)
+                px = int(com_x * self.width)
+                py = int(com_y * self.height)
+
+                # Draw CoM with larger circle
+                color = (
+                    (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
+
+                # Draw body segments for reference
+                # Draw hip midpoint
+                if "left_hip" in landmarks and "right_hip" in landmarks:
+                    lh_x, lh_y, _ = landmarks["left_hip"]
+                    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
+                    # Draw line from hip to CoM
+                    cv2.line(annotated, (hip_x, hip_y), (px, py), (255, 165, 0), 2)
+            else:
+                # Draw foot position (original method)
+                foot_x, foot_y = compute_average_foot_position(landmarks)
+                px = int(foot_x * self.width)
+                py = int(foot_y * self.height)
+
+                # Draw foot position circle
+                color = (
+                    (0, 255, 0) if contact_state == ContactState.ON_GROUND else (0, 0, 255)
+                )
+                cv2.circle(annotated, (px, py), 10, color, -1)
+
+                # Draw individual foot landmarks
+                foot_keys = ["left_ankle", "right_ankle", "left_heel", "right_heel"]
+                for key in foot_keys:
+                    if key in landmarks:
+                        x, y, vis = landmarks[key]
+                        if vis > 0.5:
+                            lx = int(x * self.width)
+                            ly = int(y * self.height)
+                            cv2.circle(annotated, (lx, ly), 5, (255, 255, 0), -1)
 
         # Draw contact state
         state_text = f"State: {contact_state.value}"

{dropjump → kinemotion/dropjump}/kinematics.py

@@ -3,7 +3,7 @@
 
 import numpy as np
 
-from .contact_detection import (
+from .analysis import (
     ContactState,
     find_contact_phases,
     find_interpolated_phase_transitions_with_curvature,
@@ -111,7 +111,9 @@ def calculate_drop_jump_metrics(
     drop_height_m: float | None = None,
     velocity_threshold: float = 0.02,
     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.
@@ -123,7 +125,11 @@ def calculate_drop_jump_metrics(
         drop_height_m: Known drop box/platform height in meters for calibration (optional)
         velocity_threshold: Velocity threshold used for contact detection (for interpolation)
         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
@@ -138,6 +144,7 @@ def calculate_drop_jump_metrics(
         contact_states,
         velocity_threshold,
         smoothing_window,
+        polyorder,
         use_curvature,
     )
 
@@ -312,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