kinemotion 0.10.2__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

@@ -0,0 +1,345 @@
+"""Advanced filtering techniques for robust trajectory processing."""
+
+import numpy as np
+from scipy.signal import medfilt
+
+
+def detect_outliers_ransac(
+    positions: np.ndarray,
+    window_size: int = 15,
+    threshold: float = 0.02,
+    min_inliers: float = 0.7,
+) -> np.ndarray:
+    """
+    Detect outlier positions using RANSAC-based polynomial fitting.
+
+    Uses a sliding window approach to detect positions that deviate significantly
+    from a polynomial fit of nearby points. This catches MediaPipe tracking glitches
+    where landmarks jump to incorrect positions.
+
+    Args:
+        positions: 1D array of position values (e.g., y-coordinates)
+        window_size: Size of sliding window for local fitting
+        threshold: Distance threshold to consider a point an inlier
+        min_inliers: Minimum fraction of points that must be inliers
+
+    Returns:
+        Boolean array: True for outliers, False for valid points
+    """
+    n = len(positions)
+    is_outlier = np.zeros(n, dtype=bool)
+
+    if n < window_size:
+        return is_outlier
+
+    # Ensure window size is odd
+    if window_size % 2 == 0:
+        window_size += 1
+
+    half_window = window_size // 2
+
+    for i in range(n):
+        # Define window around current point
+        start = max(0, i - half_window)
+        end = min(n, i + half_window + 1)
+        window_positions = positions[start:end]
+        window_indices = np.arange(start, end)
+
+        if len(window_positions) < 3:
+            continue
+
+        # Fit polynomial (quadratic) to window
+        # Use polyfit with degree 2 (parabolic motion)
+        try:
+            coeffs = np.polyfit(window_indices, window_positions, deg=2)
+            predicted = np.polyval(coeffs, window_indices)
+
+            # Calculate residuals
+            residuals = np.abs(window_positions - predicted)
+
+            # Point is outlier if its residual is large
+            local_idx = i - start
+            if local_idx < len(residuals) and residuals[local_idx] > threshold:
+                # Also check if most other points are inliers (RANSAC criterion)
+                inliers = np.sum(residuals <= threshold)
+                if inliers / len(residuals) >= min_inliers:
+                    is_outlier[i] = True
+        except np.linalg.LinAlgError:
+            # Polyfit failed, skip this window
+            continue
+
+    return is_outlier
+
+
+def detect_outliers_median(
+    positions: np.ndarray, window_size: int = 5, threshold: float = 0.03
+) -> np.ndarray:
+    """
+    Detect outliers using median filtering.
+
+    Points that deviate significantly from the local median are marked as outliers.
+    More robust to noise than mean-based methods.
+
+    Args:
+        positions: 1D array of position values
+        window_size: Size of median filter window (must be odd)
+        threshold: Deviation threshold to mark as outlier
+
+    Returns:
+        Boolean array: True for outliers, False for valid points
+    """
+    if len(positions) < window_size:
+        return np.zeros(len(positions), dtype=bool)
+
+    # Ensure window size is odd
+    if window_size % 2 == 0:
+        window_size += 1
+
+    # Apply median filter
+    median_filtered = medfilt(positions, kernel_size=window_size)
+
+    # Calculate absolute deviation from median
+    deviations = np.abs(positions - median_filtered)
+
+    # Mark as outlier if deviation exceeds threshold
+    is_outlier = deviations > threshold
+
+    return is_outlier
+
+
+def remove_outliers(
+    positions: np.ndarray,
+    outlier_mask: np.ndarray,
+    method: str = "interpolate",
+) -> np.ndarray:
+    """
+    Replace outlier values with interpolated or median values.
+
+    Args:
+        positions: Original position array
+        outlier_mask: Boolean array indicating outliers
+        method: "interpolate" or "median"
+            - interpolate: Linear interpolation from neighboring valid points
+            - median: Replace with local median of valid points
+
+    Returns:
+        Position array with outliers replaced
+    """
+    positions_clean = positions.copy()
+
+    if not np.any(outlier_mask):
+        return positions_clean
+
+    outlier_indices = np.nonzero(outlier_mask)[0]
+
+    for idx in outlier_indices:
+        if method == "interpolate":
+            # Find nearest valid points before and after
+            valid_before = np.nonzero(~outlier_mask[:idx])[0]
+            valid_after = np.nonzero(~outlier_mask[idx + 1 :])[0]
+
+            if len(valid_before) > 0 and len(valid_after) > 0:
+                # Linear interpolation between nearest valid points
+                idx_before = valid_before[-1]
+                idx_after = valid_after[0] + idx + 1
+
+                # Interpolate
+                t = (idx - idx_before) / (idx_after - idx_before)
+                positions_clean[idx] = (
+                    positions[idx_before] * (1 - t) + positions[idx_after] * t
+                )
+            elif len(valid_before) > 0:
+                # Use last valid value
+                positions_clean[idx] = positions[valid_before[-1]]
+            elif len(valid_after) > 0:
+                # Use next valid value
+                positions_clean[idx] = positions[valid_after[0] + idx + 1]
+
+        elif method == "median":
+            # Replace with median of nearby valid points
+            window_size = 5
+            start = max(0, idx - window_size)
+            end = min(len(positions), idx + window_size + 1)
+
+            window_valid = ~outlier_mask[start:end]
+            if np.any(window_valid):
+                positions_clean[idx] = np.median(positions[start:end][window_valid])
+
+    return positions_clean
+
+
+def reject_outliers(
+    positions: np.ndarray,
+    use_ransac: bool = True,
+    use_median: bool = True,
+    ransac_window: int = 15,
+    ransac_threshold: float = 0.02,
+    median_window: int = 5,
+    median_threshold: float = 0.03,
+    interpolate: bool = True,
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Comprehensive outlier rejection using multiple methods.
+
+    Combines RANSAC-based and median-based outlier detection for robust
+    identification of tracking glitches.
+
+    Args:
+        positions: 1D array of position values
+        use_ransac: Enable RANSAC-based outlier detection
+        use_median: Enable median-based outlier detection
+        ransac_window: Window size for RANSAC
+        ransac_threshold: Deviation threshold for RANSAC
+        median_window: Window size for median filter
+        median_threshold: Deviation threshold for median
+        interpolate: Replace outliers with interpolated values
+
+    Returns:
+        Tuple of (cleaned_positions, outlier_mask)
+        - cleaned_positions: Positions with outliers replaced
+        - outlier_mask: Boolean array marking outliers
+    """
+    outlier_mask = np.zeros(len(positions), dtype=bool)
+
+    # Detect outliers using RANSAC
+    if use_ransac:
+        ransac_outliers = detect_outliers_ransac(
+            positions, window_size=ransac_window, threshold=ransac_threshold
+        )
+        outlier_mask |= ransac_outliers
+
+    # Detect outliers using median filtering
+    if use_median:
+        median_outliers = detect_outliers_median(
+            positions, window_size=median_window, threshold=median_threshold
+        )
+        outlier_mask |= median_outliers
+
+    # Remove/replace outliers
+    if interpolate:
+        cleaned_positions = remove_outliers(
+            positions, outlier_mask, method="interpolate"
+        )
+    else:
+        cleaned_positions = positions.copy()
+
+    return cleaned_positions, outlier_mask
+
+
+def adaptive_smooth_window(
+    positions: np.ndarray,
+    base_window: int = 5,
+    velocity_threshold: float = 0.02,
+    min_window: int = 3,
+    max_window: int = 11,
+) -> np.ndarray:
+    """
+    Determine adaptive smoothing window size based on local motion velocity.
+
+    Uses larger windows during slow motion (ground contact) and smaller windows
+    during fast motion (flight) to preserve details where needed while smoothing
+    where safe.
+
+    Args:
+        positions: 1D array of position values
+        base_window: Base window size (default: 5)
+        velocity_threshold: Velocity below which to use larger window
+        min_window: Minimum window size (for fast motion)
+        max_window: Maximum window size (for slow motion)
+
+    Returns:
+        Array of window sizes for each frame
+    """
+    n = len(positions)
+    windows = np.full(n, base_window, dtype=int)
+
+    if n < 2:
+        return windows
+
+    # Compute local velocity (simple diff)
+    velocities = np.abs(np.diff(positions, prepend=positions[0]))
+
+    # Smooth velocity to avoid spurious changes
+    if n >= 5:
+        from scipy.signal import medfilt
+
+        velocities = medfilt(velocities, kernel_size=5)
+
+    # Assign window sizes based on velocity
+    for i in range(n):
+        if velocities[i] < velocity_threshold / 2:
+            # Very slow motion - use maximum window
+            windows[i] = max_window
+        elif velocities[i] < velocity_threshold:
+            # Slow motion - use larger window
+            windows[i] = (base_window + max_window) // 2
+        else:
+            # Fast motion - use smaller window
+            windows[i] = min_window
+
+    # Ensure windows are odd
+    windows = np.where(windows % 2 == 0, windows + 1, windows)
+
+    return windows
+
+
+def bilateral_temporal_filter(
+    positions: np.ndarray,
+    window_size: int = 9,
+    sigma_spatial: float = 3.0,
+    sigma_intensity: float = 0.02,
+) -> np.ndarray:
+    """
+    Apply bilateral filter in temporal domain for edge-preserving smoothing.
+
+    Unlike Savitzky-Golay which smooths uniformly across all frames, the bilateral
+    filter preserves sharp transitions (like landing/takeoff) while smoothing within
+    smooth regions (flight phase, ground contact).
+
+    The filter weights each neighbor by both:
+    1. Temporal distance (like regular smoothing)
+    2. Intensity similarity (preserves edges)
+
+    Args:
+        positions: 1D array of position values
+        window_size: Temporal window size (must be odd)
+        sigma_spatial: Std dev for spatial (temporal) Gaussian kernel
+        sigma_intensity: Std dev for intensity (position difference) kernel
+
+    Returns:
+        Filtered position array
+    """
+    n = len(positions)
+    filtered = np.zeros(n)
+
+    # Ensure window size is odd
+    if window_size % 2 == 0:
+        window_size += 1
+
+    half_window = window_size // 2
+
+    for i in range(n):
+        # Define window
+        start = max(0, i - half_window)
+        end = min(n, i + half_window + 1)
+
+        # Get window positions
+        window_pos = positions[start:end]
+        center_pos = positions[i]
+
+        # Compute spatial (temporal) weights
+        temporal_indices = np.arange(start - i, end - i)
+        spatial_weights = np.exp(-(temporal_indices**2) / (2 * sigma_spatial**2))
+
+        # Compute intensity (position difference) weights
+        intensity_diff = window_pos - center_pos
+        intensity_weights = np.exp(-(intensity_diff**2) / (2 * sigma_intensity**2))
+
+        # Combined weights (bilateral)
+        weights = spatial_weights * intensity_weights
+        weights /= np.sum(weights)  # Normalize
+
+        # Weighted average
+        filtered[i] = np.sum(weights * window_pos)
+
+    return filtered