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

kinemotion/core/auto_tuning.py

@@ -0,0 +1,289 @@
+"""Automatic parameter tuning based on video characteristics."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+import numpy as np
+
+
+class QualityPreset(str, Enum):
+    """Quality presets for analysis."""
+
+    FAST = "fast"  # Quick analysis, lower precision
+    BALANCED = "balanced"  # Default: good balance of speed and accuracy
+    ACCURATE = "accurate"  # Research-grade analysis, slower
+
+
+@dataclass
+class VideoCharacteristics:
+    """Characteristics extracted from video analysis."""
+
+    fps: float
+    frame_count: int
+    avg_visibility: float  # Average landmark visibility (0-1)
+    position_variance: float  # Variance in foot positions
+    has_stable_period: bool  # Whether video has initial stationary period
+    tracking_quality: str  # "low", "medium", "high"
+
+
+@dataclass
+class AnalysisParameters:
+    """Auto-tuned parameters for drop jump analysis."""
+
+    smoothing_window: int
+    polyorder: int
+    velocity_threshold: float
+    min_contact_frames: int
+    visibility_threshold: float
+    detection_confidence: float
+    tracking_confidence: float
+    outlier_rejection: bool
+    bilateral_filter: bool
+    use_curvature: bool
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary."""
+        return {
+            "smoothing_window": self.smoothing_window,
+            "polyorder": self.polyorder,
+            "velocity_threshold": self.velocity_threshold,
+            "min_contact_frames": self.min_contact_frames,
+            "visibility_threshold": self.visibility_threshold,
+            "detection_confidence": self.detection_confidence,
+            "tracking_confidence": self.tracking_confidence,
+            "outlier_rejection": self.outlier_rejection,
+            "bilateral_filter": self.bilateral_filter,
+            "use_curvature": self.use_curvature,
+        }
+
+
+def analyze_tracking_quality(avg_visibility: float) -> str:
+    """
+    Classify tracking quality based on average landmark visibility.
+
+    Args:
+        avg_visibility: Average visibility score across all tracked landmarks
+
+    Returns:
+        Quality classification: "low", "medium", or "high"
+    """
+    if avg_visibility < 0.4:
+        return "low"
+    elif avg_visibility < 0.7:
+        return "medium"
+    else:
+        return "high"
+
+
+def auto_tune_parameters(
+    characteristics: VideoCharacteristics,
+    quality_preset: QualityPreset = QualityPreset.BALANCED,
+) -> AnalysisParameters:
+    """
+    Automatically tune analysis parameters based on video characteristics.
+
+    This function implements heuristics to select optimal parameters without
+    requiring user expertise in video analysis or kinematic tracking.
+
+    Key principles:
+    1. FPS-based scaling: Higher fps needs lower velocity thresholds
+    2. Quality-based smoothing: Noisy video needs more smoothing
+    3. Always enable proven features: outlier rejection, curvature analysis
+    4. Preset modifiers: fast/balanced/accurate adjust base parameters
+
+    Args:
+        characteristics: Analyzed video characteristics
+        quality_preset: Quality vs speed tradeoff
+
+    Returns:
+        AnalysisParameters with auto-tuned values
+    """
+    fps = characteristics.fps
+    quality = characteristics.tracking_quality
+
+    # =================================================================
+    # STEP 1: FPS-based baseline parameters
+    # These scale automatically with frame rate to maintain consistent
+    # temporal resolution and sensitivity
+    # =================================================================
+
+    # Velocity threshold: Scale inversely with fps
+    # At 30fps, feet move ~2% of frame per frame when "stationary"
+    # At 60fps, feet move ~1% of frame per frame when "stationary"
+    # Formula: threshold = 0.02 * (30 / fps)
+    base_velocity_threshold = 0.02 * (30.0 / fps)
+
+    # Min contact frames: Scale with fps to maintain same time duration
+    # Goal: ~100ms minimum contact (3 frames @ 30fps, 6 frames @ 60fps)
+    # Formula: frames = round(3 * (fps / 30))
+    base_min_contact_frames = max(2, round(3.0 * (fps / 30.0)))
+
+    # Smoothing window: Decrease with higher fps for better temporal resolution
+    # Lower fps (30fps): 5-frame window = 167ms
+    # Higher fps (60fps): 3-frame window = 50ms (same temporal resolution)
+    if fps <= 30:
+        base_smoothing_window = 5
+    elif fps <= 60:
+        base_smoothing_window = 3
+    else:
+        base_smoothing_window = 3  # Even at 120fps, 3 is minimum for Savitzky-Golay
+
+    # =================================================================
+    # STEP 2: Quality-based adjustments
+    # Adapt smoothing and filtering based on tracking quality
+    # =================================================================
+
+    smoothing_adjustment = 0
+    enable_bilateral = False
+
+    if quality == "low":
+        # Poor tracking quality: aggressive smoothing and filtering
+        smoothing_adjustment = +2
+        enable_bilateral = True
+    elif quality == "medium":
+        # Moderate quality: slight smoothing increase
+        smoothing_adjustment = +1
+        enable_bilateral = True
+    else:  # high quality
+        # Good tracking: preserve detail, minimal smoothing
+        smoothing_adjustment = 0
+        enable_bilateral = False
+
+    # =================================================================
+    # STEP 3: Apply quality preset modifiers
+    # User can choose speed vs accuracy tradeoff
+    # =================================================================
+
+    if quality_preset == QualityPreset.FAST:
+        # Fast: Trade accuracy for speed
+        velocity_threshold = base_velocity_threshold * 1.5  # Less sensitive
+        min_contact_frames = max(2, int(base_min_contact_frames * 0.67))
+        smoothing_window = max(3, base_smoothing_window - 2 + smoothing_adjustment)
+        bilateral_filter = False  # Skip expensive filtering
+        detection_confidence = 0.3
+        tracking_confidence = 0.3
+
+    elif quality_preset == QualityPreset.ACCURATE:
+        # Accurate: Maximize accuracy, accept slower processing
+        velocity_threshold = base_velocity_threshold * 0.5  # More sensitive
+        min_contact_frames = (
+            base_min_contact_frames  # Don't increase (would miss brief)
+        )
+        smoothing_window = min(11, base_smoothing_window + 2 + smoothing_adjustment)
+        bilateral_filter = True  # Always use for best accuracy
+        detection_confidence = 0.6
+        tracking_confidence = 0.6
+
+    else:  # QualityPreset.BALANCED (default)
+        # Balanced: Good accuracy, reasonable speed
+        velocity_threshold = base_velocity_threshold
+        min_contact_frames = base_min_contact_frames
+        smoothing_window = max(3, base_smoothing_window + smoothing_adjustment)
+        bilateral_filter = enable_bilateral
+        detection_confidence = 0.5
+        tracking_confidence = 0.5
+
+    # Ensure smoothing window is odd (required for Savitzky-Golay)
+    if smoothing_window % 2 == 0:
+        smoothing_window += 1
+
+    # =================================================================
+    # STEP 4: Set fixed optimal values
+    # These are always the same regardless of video characteristics
+    # =================================================================
+
+    # Polyorder: Always 2 (quadratic) - optimal for jump physics (parabolic motion)
+    polyorder = 2
+
+    # Visibility threshold: Standard MediaPipe threshold
+    visibility_threshold = 0.5
+
+    # Always enable proven accuracy features
+    outlier_rejection = True  # Removes tracking glitches (minimal cost)
+    use_curvature = True  # Trajectory curvature analysis (minimal cost)
+
+    return AnalysisParameters(
+        smoothing_window=smoothing_window,
+        polyorder=polyorder,
+        velocity_threshold=velocity_threshold,
+        min_contact_frames=min_contact_frames,
+        visibility_threshold=visibility_threshold,
+        detection_confidence=detection_confidence,
+        tracking_confidence=tracking_confidence,
+        outlier_rejection=outlier_rejection,
+        bilateral_filter=bilateral_filter,
+        use_curvature=use_curvature,
+    )
+
+
+def analyze_video_sample(
+    landmarks_sequence: list[dict[str, tuple[float, float, float]] | None],
+    fps: float,
+    frame_count: int,
+) -> VideoCharacteristics:
+    """
+    Analyze video characteristics from a sample of frames.
+
+    This function should be called after tracking the first 30-60 frames
+    to understand video quality and characteristics.
+
+    Args:
+        landmarks_sequence: Tracked landmarks from sample frames
+        fps: Video frame rate
+        frame_count: Total number of frames in video
+
+    Returns:
+        VideoCharacteristics with analyzed properties
+    """
+    # Calculate average landmark visibility
+    visibilities = []
+    positions = []
+
+    for frame_landmarks in landmarks_sequence:
+        if frame_landmarks:
+            # Collect visibility scores from foot landmarks
+            foot_keys = [
+                "left_ankle",
+                "right_ankle",
+                "left_heel",
+                "right_heel",
+                "left_foot_index",
+                "right_foot_index",
+            ]
+
+            frame_vis = []
+            frame_y_positions = []
+
+            for key in foot_keys:
+                if key in frame_landmarks:
+                    _, y, vis = frame_landmarks[key]  # x not needed for analysis
+                    frame_vis.append(vis)
+                    frame_y_positions.append(y)
+
+            if frame_vis:
+                visibilities.append(float(np.mean(frame_vis)))
+            if frame_y_positions:
+                positions.append(float(np.mean(frame_y_positions)))
+
+    # Compute metrics
+    avg_visibility = float(np.mean(visibilities)) if visibilities else 0.5
+    position_variance = float(np.var(positions)) if len(positions) > 1 else 0.0
+
+    # Determine tracking quality
+    tracking_quality = analyze_tracking_quality(avg_visibility)
+
+    # Check for stable period (indicates drop jump from elevated platform)
+    # Simple check: do first 30 frames have low variance?
+    has_stable_period = False
+    if len(positions) >= 30:
+        first_30_std = float(np.std(positions[:30]))
+        has_stable_period = first_30_std < 0.01  # Very stable = on platform
+
+    return VideoCharacteristics(
+        fps=fps,
+        frame_count=frame_count,
+        avg_visibility=avg_visibility,
+        position_variance=position_variance,
+        has_stable_period=has_stable_period,
+        tracking_quality=tracking_quality,
+    )

kinemotion/core/filtering.py

@@ -104,7 +104,7 @@ def detect_outliers_median(
     # Mark as outlier if deviation exceeds threshold
     is_outlier = deviations > threshold
 
-    return is_outlier  # type: ignore[no-any-return]
+    return is_outlier
 
 
 def remove_outliers(

kinemotion/core/smoothing.py

@@ -1,6 +1,5 @@
 """Landmark smoothing utilities to reduce jitter in pose tracking."""
 
-
 import numpy as np
 from scipy.signal import savgol_filter
 
@@ -79,12 +78,12 @@ def smooth_landmarks(
                 smoothed_sequence[frame_idx] = {}
 
             if (
-                landmark_name not in smoothed_sequence[frame_idx]  # type: ignore[operator]
+                landmark_name not in smoothed_sequence[frame_idx]
                 and landmark_sequence[frame_idx] is not None
             ):
                 # Keep original visibility
-                orig_vis = landmark_sequence[frame_idx][landmark_name][2]  # type: ignore[index]
-                smoothed_sequence[frame_idx][landmark_name] = (  # type: ignore[index]
+                orig_vis = landmark_sequence[frame_idx][landmark_name][2]
+                smoothed_sequence[frame_idx][landmark_name] = (
                     float(x_smooth[idx]),
                     float(y_smooth[idx]),
                     orig_vis,
@@ -125,7 +124,7 @@ def compute_velocity(
         for dim in range(velocity.shape[1]):
             velocity[:, dim] = savgol_filter(velocity[:, dim], smooth_window, 1)
 
-    return velocity  # type: ignore[no-any-return]
+    return velocity
 
 
 def compute_velocity_from_derivative(
@@ -154,7 +153,7 @@ def compute_velocity_from_derivative(
     """
     if len(positions) < window_length:
         # Fallback to simple differences for short sequences
-        return np.abs(np.diff(positions, prepend=positions[0]))  # type: ignore[no-any-return]
+        return np.abs(np.diff(positions, prepend=positions[0]))
 
     # Ensure window_length is odd
     if window_length % 2 == 0:
@@ -174,7 +173,7 @@ def compute_velocity_from_derivative(
     )
 
     # Return absolute velocity (magnitude only)
-    return np.abs(velocity)  # type: ignore[no-any-return]
+    return np.abs(velocity)
 
 
 def compute_acceleration_from_derivative(
@@ -225,7 +224,7 @@ def compute_acceleration_from_derivative(
         mode="interp",
     )
 
-    return acceleration  # type: ignore[no-any-return]
+    return acceleration
 
 
 def smooth_landmarks_advanced(
@@ -345,12 +344,12 @@ def smooth_landmarks_advanced(
                 smoothed_sequence[frame_idx] = {}
 
             if (
-                landmark_name not in smoothed_sequence[frame_idx]  # type: ignore[operator]
+                landmark_name not in smoothed_sequence[frame_idx]
                 and landmark_sequence[frame_idx] is not None
             ):
                 # Keep original visibility
-                orig_vis = landmark_sequence[frame_idx][landmark_name][2]  # type: ignore[index]
-                smoothed_sequence[frame_idx][landmark_name] = (  # type: ignore[index]
+                orig_vis = landmark_sequence[frame_idx][landmark_name][2]
+                smoothed_sequence[frame_idx][landmark_name] = (
                     float(x_smooth[idx]),
                     float(y_smooth[idx]),
                     orig_vis,

kinemotion/core/video_io.py

@@ -45,20 +45,35 @@ class VideoProcessor:
             self.width = int(self.cap.get(cv2.CAP_PROP_FRAME_WIDTH))
             self.height = int(self.cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
 
+        # Extract rotation metadata from video (iPhones store rotation in side_data_list)
+        # OpenCV ignores rotation metadata, so we need to extract and apply it manually
+        self.rotation = 0  # Will be set by _extract_video_metadata()
+
         # 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()
+        self._extract_video_metadata()
+
+        # Apply rotation to dimensions if needed
+        if self.rotation in [90, -90, 270]:
+            # Swap dimensions for 90/-90 degree rotations
+            self.width, self.height = self.height, self.width
+            self.display_width, self.display_height = (
+                self.display_height,
+                self.display_width,
+            )
 
-    def _calculate_display_dimensions(self) -> None:
+    def _extract_video_metadata(self) -> None:
         """
-        Calculate display dimensions by reading SAR metadata from video file.
+        Extract video metadata including SAR and rotation using ffprobe.
 
-        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.
+        Many mobile videos (especially from iPhones) have:
+        - Non-square pixels (SAR != 1:1) affecting display dimensions
+        - Rotation metadata in side_data_list that OpenCV ignores
+
+        We extract both to ensure proper display and pose detection.
         """
         try:
             # Use ffprobe to get SAR metadata
@@ -83,6 +98,8 @@ class VideoProcessor:
                 data = json.loads(result.stdout)
                 if "streams" in data and len(data["streams"]) > 0:
                     stream = data["streams"][0]
+
+                    # Extract SAR (Sample Aspect Ratio)
                     sar_str = stream.get("sample_aspect_ratio", "1:1")
 
                     # Parse SAR (e.g., "270:473")
@@ -98,14 +115,41 @@ class VideoProcessor:
                                 self.width * sar_width / sar_height
                             )
                             self.display_height = self.height
+
+                    # Extract rotation from side_data_list (common for iPhone videos)
+                    side_data_list = stream.get("side_data_list", [])
+                    for side_data in side_data_list:
+                        if side_data.get("side_data_type") == "Display Matrix":
+                            rotation = side_data.get("rotation", 0)
+                            # Convert to int and normalize to 0, 90, -90, 180
+                            self.rotation = int(rotation)
         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."""
+        """
+        Read next frame from video and apply rotation if needed.
+
+        OpenCV ignores rotation metadata, so we manually apply rotation
+        based on the display matrix metadata extracted from the video.
+        """
         ret, frame = self.cap.read()
-        return frame if ret else None
+        if not ret:
+            return None
+
+        # Apply rotation if video has rotation metadata
+        if self.rotation == -90 or self.rotation == 270:
+            # -90 degrees = rotate 90 degrees clockwise
+            frame = cv2.rotate(frame, cv2.ROTATE_90_CLOCKWISE)
+        elif self.rotation == 90 or self.rotation == -270:
+            # 90 degrees = rotate 90 degrees counter-clockwise
+            frame = cv2.rotate(frame, cv2.ROTATE_90_COUNTERCLOCKWISE)
+        elif self.rotation == 180 or self.rotation == -180:
+            # 180 degrees rotation
+            frame = cv2.rotate(frame, cv2.ROTATE_180)
+
+        return frame
 
     def reset(self) -> None:
         """Reset video to beginning."""

kinemotion/dropjump/analysis.py

@@ -89,6 +89,123 @@ def calculate_adaptive_threshold(
     return adaptive_threshold
 
 
+def detect_drop_start(
+    positions: np.ndarray,
+    fps: float,
+    min_stationary_duration: float = 1.0,
+    position_change_threshold: float = 0.02,
+    smoothing_window: int = 5,
+    debug: bool = False,
+) -> int:
+    """
+    Detect when the drop jump actually starts by finding stable period then detecting drop.
+
+    Strategy:
+    1. Scan forward to find first STABLE period (low variance over N frames)
+    2. Use that stable period as baseline
+    3. Detect when position starts changing significantly from baseline
+
+    This handles videos where athlete steps onto box at start (unstable beginning).
+
+    Args:
+        positions: Array of vertical positions (0-1 normalized, y increases downward)
+        fps: Video frame rate
+        min_stationary_duration: Minimum duration (seconds) of stable period (default: 1.0s)
+        position_change_threshold: Position change indicating start of drop
+            (default: 0.02 = 2% of frame)
+        smoothing_window: Window for computing position variance
+        debug: Print debug information (default: False)
+
+    Returns:
+        Frame index where drop starts (or 0 if no clear stable period found)
+
+    Example:
+        - Frames 0-14: Stepping onto box (noisy, unstable)
+        - Frames 15-119: Standing on box (stable, low variance)
+        - Frame 119: Drop begins (position changes significantly)
+        - Returns: 119
+    """
+    min_stable_frames = int(fps * min_stationary_duration)
+    if len(positions) < min_stable_frames + 30:  # Need some frames after stable period
+        if debug:
+            min_frames_needed = min_stable_frames + 30
+            print(
+                f"[detect_drop_start] Video too short: {len(positions)} < {min_frames_needed}"
+            )
+        return 0
+
+    # STEP 1: Find first stable period by scanning forward
+    # Look for window with low variance (< 1% of frame height)
+    stability_threshold = 0.01  # 1% of frame height
+    stable_window = min_stable_frames
+
+    baseline_start = -1
+    baseline_position = 0.0
+
+    # Scan from start, looking for stable window
+    for start_idx in range(0, len(positions) - stable_window, 5):  # Step by 5 frames
+        window = positions[start_idx : start_idx + stable_window]
+        window_std = float(np.std(window))
+
+        if window_std < stability_threshold:
+            # Found stable period!
+            baseline_start = start_idx
+            baseline_position = float(np.median(window))
+
+            if debug:
+                end_frame = baseline_start + stable_window - 1
+                print("[detect_drop_start] Found stable period:")
+                print(f"  frames {baseline_start}-{end_frame}")
+                print(f"  baseline_position: {baseline_position:.4f}")
+                print(f"  baseline_std: {window_std:.4f} < {stability_threshold:.4f}")
+            break
+
+    if baseline_start < 0:
+        if debug:
+            msg = (
+                f"No stable period found (variance always > {stability_threshold:.4f})"
+            )
+            print(f"[detect_drop_start] {msg}")
+        return 0
+
+    # STEP 2: Find when position changes significantly from baseline
+    # Start searching after stable period ends
+    search_start = baseline_start + stable_window
+    window_size = max(3, smoothing_window)
+
+    for i in range(search_start, len(positions) - window_size):
+        # Average position over small window to reduce noise
+        window_positions = positions[i : i + window_size]
+        avg_position = float(np.mean(window_positions))
+
+        # Check if position has increased (dropped) significantly
+        position_change = avg_position - baseline_position
+
+        if position_change > position_change_threshold:
+            # Found start of drop - back up slightly to catch beginning
+            drop_frame_candidate = i - window_size
+            if drop_frame_candidate < baseline_start:
+                drop_frame = baseline_start
+            else:
+                drop_frame = drop_frame_candidate
+
+            if debug:
+                print(f"[detect_drop_start] Drop detected at frame {drop_frame}")
+                print(
+                    f"  position_change: {position_change:.4f} > {position_change_threshold:.4f}"
+                )
+                print(
+                    f"  avg_position: {avg_position:.4f} vs baseline: {baseline_position:.4f}"
+                )
+
+            return drop_frame
+
+    # No significant position change detected
+    if debug:
+        print("[detect_drop_start] No drop detected after stable period")
+    return 0
+
+
 def detect_ground_contact(
     foot_positions: np.ndarray,
     velocity_threshold: float = 0.02,
@@ -273,7 +390,9 @@ def find_interpolated_phase_transitions(
 
         # Interpolate start boundary (transition INTO this phase)
         if start_idx > 0 and start_idx < len(velocities):
-            vel_before = velocities[start_idx - 1] if start_idx > 0 else velocities[start_idx]
+            vel_before = (
+                velocities[start_idx - 1] if start_idx > 0 else velocities[start_idx]
+            )
             vel_at = velocities[start_idx]
 
             # Check if we're crossing the threshold at this boundary
@@ -392,9 +511,7 @@ def refine_transition_with_curvature(
     # Blend with original estimate (don't stray too far)
     # 70% curvature-based, 30% velocity-based
     blend_factor = 0.7
-    refined_frame = (
-        blend_factor * refined_frame + (1 - blend_factor) * estimated_frame
-    )
+    refined_frame = blend_factor * refined_frame + (1 - blend_factor) * estimated_frame
 
     return refined_frame