kinemotion 0.73.0__py3-none-any.whl → 0.75.0__py3-none-any.whl

kinemotion/core/__init__.py

@@ -34,9 +34,20 @@ from .timing import (
     PerformanceTimer,
     Timer,
 )
+from .video_analysis_base import (
+    AnalysisOverrides,
+    JumpAnalysisPipeline,
+    VideoAnalysisConfig,
+    VideoAnalysisResult,
+)
 from .video_io import VideoProcessor
 
 __all__ = [
+    # Video Analysis Base
+    "AnalysisOverrides",
+    "JumpAnalysisPipeline",
+    "VideoAnalysisConfig",
+    "VideoAnalysisResult",
     # Pose tracking
     "MediaPipePoseTracker",
     "PoseTrackerFactory",

kinemotion/core/auto_tuning.py

@@ -137,6 +137,73 @@ def analyze_tracking_quality(avg_visibility: float) -> str:
         return "high"
 
 
+def _compute_fps_baseline_parameters(fps: float) -> tuple[float, int, int]:
+    """Compute FPS-based baseline parameters.
+
+    Args:
+        fps: Video frame rate
+
+    Returns:
+        Tuple of (base_velocity_threshold, base_min_contact_frames, base_smoothing_window)
+    """
+    # Base velocity threshold: 0.012 at 30fps, scaled inversely by fps
+    # Must exceed typical MediaPipe landmark jitter (0.5-2% per frame)
+    # Previous value of 0.004 was below noise floor, causing false IN_AIR detections
+    base_velocity_threshold = 0.012 * (30.0 / fps)
+    base_min_contact_frames = max(2, round(3.0 * (fps / 30.0)))
+
+    # Smoothing window: Decrease with higher fps for better temporal resolution
+    base_smoothing_window = 3 if fps > 30 else 5
+
+    return base_velocity_threshold, base_min_contact_frames, base_smoothing_window
+
+
+def _compute_smoothing_window(
+    fps: float,
+    preset: _PresetConfig,
+    quality_adj: _QualityAdjustment,
+) -> int:
+    """Compute smoothing window from FPS, preset, and quality adjustments.
+
+    Args:
+        fps: Video frame rate
+        preset: Quality preset configuration
+        quality_adj: Quality-based adjustments
+
+    Returns:
+        Odd smoothing window size (required for Savitzky-Golay filter)
+    """
+    _, _, base_smoothing_window = _compute_fps_baseline_parameters(fps)
+
+    # Smoothing window = base + preset offset + quality adjustment
+    smoothing_window = base_smoothing_window + preset.smoothing_offset + quality_adj.smoothing_add
+    smoothing_window = max(3, min(11, smoothing_window))
+
+    # Ensure smoothing window is odd (required for Savitzky-Golay)
+    if smoothing_window % 2 == 0:
+        smoothing_window += 1
+
+    return smoothing_window
+
+
+def _resolve_bilateral_filter(
+    preset: _PresetConfig,
+    quality_adj: _QualityAdjustment,
+) -> bool:
+    """Resolve whether to enable bilateral filtering.
+
+    Args:
+        preset: Quality preset configuration
+        quality_adj: Quality-based adjustments
+
+    Returns:
+        True if bilateral filtering should be enabled
+    """
+    if preset.force_bilateral is not None:
+        return preset.force_bilateral
+    return quality_adj.enable_bilateral
+
+
 def auto_tune_parameters(
     characteristics: VideoCharacteristics,
     quality_preset: QualityPreset = QualityPreset.BALANCED,
@@ -163,42 +230,22 @@ def auto_tune_parameters(
     fps = characteristics.fps
     quality = characteristics.tracking_quality
 
-    # Get preset configuration
+    # Get preset configuration and quality-based adjustments
     preset = _PRESET_CONFIGS[quality_preset]
-
-    # Get quality-based adjustments
     quality_adj = _QUALITY_ADJUSTMENTS[quality]
 
     # Compute FPS-based baseline parameters
-    # Base velocity threshold: 0.012 at 30fps, scaled inversely by fps
-    # Must exceed typical MediaPipe landmark jitter (0.5-2% per frame)
-    # Previous value of 0.004 was below noise floor, causing false IN_AIR detections
-    base_velocity_threshold = 0.012 * (30.0 / fps)
-    base_min_contact_frames = max(2, round(3.0 * (fps / 30.0)))
-
-    # Smoothing window: Decrease with higher fps for better temporal resolution
-    if fps <= 30:
-        base_smoothing_window = 5
-    else:
-        base_smoothing_window = 3  # 60fps+ use 3-frame window
+    base_velocity_threshold, base_min_contact_frames, _ = _compute_fps_baseline_parameters(fps)
 
-    # Apply preset modifiers and quality adjustments
+    # Apply preset modifiers
     velocity_threshold = base_velocity_threshold * preset.velocity_multiplier
     min_contact_frames = max(2, int(base_min_contact_frames * preset.contact_frames_multiplier))
 
-    # Smoothing window = base + preset offset + quality adjustment
-    smoothing_window = base_smoothing_window + preset.smoothing_offset + quality_adj.smoothing_add
-    smoothing_window = max(3, min(11, smoothing_window))
+    # Compute smoothing window with preset and quality adjustments
+    smoothing_window = _compute_smoothing_window(fps, preset, quality_adj)
 
-    # Ensure smoothing window is odd (required for Savitzky-Golay)
-    if smoothing_window % 2 == 0:
-        smoothing_window += 1
-
-    # Bilateral filtering: preset can override, otherwise use quality-based
-    if preset.force_bilateral is not None:
-        bilateral_filter = preset.force_bilateral
-    else:
-        bilateral_filter = quality_adj.enable_bilateral
+    # Resolve bilateral filtering setting
+    bilateral_filter = _resolve_bilateral_filter(preset, quality_adj)
 
     # Fixed optimal values
     polyorder = 2  # Quadratic - optimal for parabolic motion

kinemotion/core/cli_utils.py

@@ -24,6 +24,80 @@ def common_output_options(func: Callable) -> Callable:  # type: ignore[type-arg]
     return func
 
 
+def quality_option(func: Callable) -> Callable:  # type: ignore[type-arg]
+    """Add quality preset option to CLI command."""
+    return click.option(
+        "--quality",
+        type=click.Choice(["fast", "balanced", "accurate"], case_sensitive=False),
+        default="balanced",
+        help=(
+            "Analysis quality preset: "
+            "fast (quick, less precise), "
+            "balanced (default, good for most cases), "
+            "accurate (research-grade, slower)"
+        ),
+        show_default=True,
+    )(func)
+
+
+def verbose_option(func: Callable) -> Callable:  # type: ignore[type-arg]
+    """Add verbose flag to CLI command."""
+    return click.option(
+        "--verbose",
+        "-v",
+        is_flag=True,
+        help="Show auto-selected parameters and analysis details",
+    )(func)
+
+
+def batch_processing_options(func: Callable) -> Callable:  # type: ignore[type-arg]
+    """Add batch processing options to CLI command."""
+    func = click.option(
+        "--batch",
+        is_flag=True,
+        help="Enable batch processing mode for multiple videos",
+    )(func)
+    func = click.option(
+        "--workers",
+        type=int,
+        default=4,
+        help="Number of parallel workers for batch processing (default: 4)",
+        show_default=True,
+    )(func)
+    func = click.option(
+        "--output-dir",
+        type=click.Path(),
+        help="Directory for debug video outputs (batch mode only)",
+    )(func)
+    func = click.option(
+        "--json-output-dir",
+        type=click.Path(),
+        help="Directory for JSON metrics outputs (batch mode only)",
+    )(func)
+    func = click.option(
+        "--csv-summary",
+        type=click.Path(),
+        help="Path for CSV summary export (batch mode only)",
+    )(func)
+    return func
+
+
+def common_analysis_options(func: Callable) -> Callable:  # type: ignore[type-arg]
+    """Add all common analysis options (output, quality, verbose, batch).
+
+    Combines:
+    - common_output_options (--output, --json-output)
+    - quality_option (--quality)
+    - verbose_option (--verbose)
+    - batch_processing_options (--batch, --workers, --output-dir, etc.)
+    """
+    func = common_output_options(func)
+    func = quality_option(func)
+    func = verbose_option(func)
+    func = batch_processing_options(func)
+    return func
+
+
 def collect_video_files(video_path: tuple[str, ...]) -> list[str]:
     """Expand glob patterns and collect all video files."""
     video_files: list[str] = []

kinemotion/core/filtering.py

@@ -1,6 +1,8 @@
 """Advanced filtering techniques for robust trajectory processing."""
 
 import numpy as np
+from numpy.lib.stride_tricks import sliding_window_view
+from scipy.ndimage import convolve1d
 from scipy.signal import medfilt
 
 from .experimental import unused
@@ -31,6 +33,8 @@ def detect_outliers_ransac(
     from a polynomial fit of nearby points. This catches MediaPipe tracking glitches
     where landmarks jump to incorrect positions.
 
+    Vectorized implementation using convolution for 10-20x speedup.
+
     Args:
         positions: 1D array of position values (e.g., y-coordinates)
         window_size: Size of sliding window for local fitting
@@ -49,35 +53,79 @@ def detect_outliers_ransac(
     window_size = _ensure_odd_window_length(window_size)
     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)
+    # For centered quadratic fit, we can compute the predicted value at
+    # the window center using convolution. This is much faster than
+    # calling np.polyfit for each window.
+    #
+    # For a quadratic fit y = ax² + bx + c with centered window:
+    # - Predicted value at center (x=0) is just the intercept c
+    # - c can be computed from sum(y) and sum(x²*y) using precomputed constants
+    #
+    # The key insight: sum(y) and sum(x²*y) are convolution operations!
+
+    # Window indices (centered at 0)
+    x = np.arange(-half_window, half_window + 1)
+
+    # Precompute constants for the normal equations
+    sum_x2 = np.sum(x**2)
+    sum_x4 = np.sum(x**4)
+    det = window_size * sum_x4 - sum_x2**2
+
+    # Handle edge case where determinant is zero (shouldn't happen with valid window)
+    if det == 0:
+        return is_outlier
 
-        if len(window_positions) < 3:
-            continue
+    # Kernels for convolution
+    ones_kernel = np.ones(window_size)
+    x2_kernel = x**2
+
+    # Pad positions for boundary handling (use edge padding like original)
+    pad_width = half_window
+    padded = np.pad(positions, pad_width, mode="edge")
+
+    # Compute sums via convolution
+    # sum_y[i] = sum of positions in window centered at i
+    # sum_x2y[i] = sum of (x² * positions) in window centered at i
+    sum_y = convolve1d(padded, ones_kernel, mode="constant")
+    sum_x2y = convolve1d(padded, x2_kernel, mode="constant")
+
+    # Remove padding to match original positions length
+    sum_y = sum_y[pad_width:-pad_width]
+    sum_x2y = sum_x2y[pad_width:-pad_width]
+
+    # Compute predicted values at window centers
+    # For centered fit: predicted = c = (sum_x4 * sum_y - sum_x2 * sum_x2y) / det
+    predicted = (sum_x4 * sum_y - sum_x2 * sum_x2y) / det
 
-        # 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
+    # Calculate residuals
+    residuals = np.abs(positions - predicted)
+
+    # Mark outliers based on threshold
+    outlier_candidates = residuals > threshold
+
+    if not np.any(outlier_candidates):
+        return is_outlier
+
+    # RANSAC criterion: point is outlier if most OTHER points in window are inliers
+    # Compute fraction of inliers in each window using convolution
+    inlier_mask = (residuals <= threshold).astype(float)
+    inliers_in_window = convolve1d(
+        np.pad(inlier_mask, pad_width, mode="edge"),
+        ones_kernel,
+        mode="constant",
+    )
+    inliers_in_window = inliers_in_window[pad_width:-pad_width]
+
+    # Account for variable window sizes at boundaries
+    # At boundaries, windows are smaller, so we need to adjust the count
+    for i in range(n):
+        actual_window_size = min(i + half_window + 1, n) - max(0, i - half_window)
+        if actual_window_size < 3:
             continue
+        if outlier_candidates[i]:
+            inlier_fraction = inliers_in_window[i] / actual_window_size
+            if inlier_fraction >= min_inliers:
+                is_outlier[i] = True
 
     return is_outlier
 
@@ -310,6 +358,8 @@ def bilateral_temporal_filter(
     1. Temporal distance (like regular smoothing)
     2. Intensity similarity (preserves edges)
 
+    Vectorized implementation using sliding_window_view for 10-30x speedup.
+
     Args:
         positions: 1D array of position values
         window_size: Temporal window size (must be odd)
@@ -320,33 +370,39 @@ def bilateral_temporal_filter(
         Filtered position array
     """
     n = len(positions)
-    filtered = np.zeros(n)
+    if n == 0:
+        return np.array([])
 
     window_size = _ensure_odd_window_length(window_size)
     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)
+    # Pad edges with boundary values to maintain consistent window size
+    # This provides context for boundary positions while preserving edge information
+    padded = np.pad(positions, half_window, mode="edge")
+
+    # Create all sliding windows at once: shape (n, window_size)
+    # Each row represents the window centered at the corresponding input position
+    windows = sliding_window_view(padded, window_size)
 
-        # Get window positions
-        window_pos = positions[start:end]
-        center_pos = positions[i]
+    # Precompute spatial weights (only depends on distance from center)
+    temporal_indices = np.arange(-half_window, half_window + 1)
+    spatial_weights = np.exp(-(temporal_indices**2) / (2 * sigma_spatial**2))
 
-        # Compute spatial (temporal) weights
-        temporal_indices = np.arange(start - i, end - i)
-        spatial_weights = np.exp(-(temporal_indices**2) / (2 * sigma_spatial**2))
+    # Extract center positions for intensity weight computation
+    center_positions = windows[:, half_window]  # Shape: (n,)
+    center_positions = center_positions.reshape(-1, 1)  # Shape: (n, 1) for broadcast
 
-        # Compute intensity (position difference) weights
-        intensity_diff = window_pos - center_pos
-        intensity_weights = np.exp(-(intensity_diff**2) / (2 * sigma_intensity**2))
+    # Compute intensity weights (data-dependent, varies by window)
+    # intensity_diff[i, j] = windows[i, j] - windows[i, center]
+    intensity_diff = windows - center_positions  # Broadcasting: (n, window_size)
+    intensity_weights = np.exp(-(intensity_diff**2) / (2 * sigma_intensity**2))
 
-        # Combined weights (bilateral)
-        weights = spatial_weights * intensity_weights
-        weights /= np.sum(weights)  # Normalize
+    # Combine weights: spatial_weights broadcasts to (n, window_size)
+    weights = spatial_weights * intensity_weights
+    # Normalize each window's weights to sum to 1
+    weights /= weights.sum(axis=1, keepdims=True)
 
-        # Weighted average
-        filtered[i] = np.sum(weights * window_pos)
+    # Compute weighted average for each window
+    filtered = (weights * windows).sum(axis=1)
 
     return filtered

kinemotion/core/quality.py

@@ -86,13 +86,11 @@ def calculate_position_stability(
     if len(positions) < window_size:
         return float(np.var(positions))
 
-    # Calculate rolling variance
-    rolling_vars = []
-    for i in range(len(positions) - window_size + 1):
-        window = positions[i : i + window_size]
-        rolling_vars.append(np.var(window))
+    # Vectorized rolling variance using sliding window view
+    from numpy.lib.stride_tricks import sliding_window_view
 
-    return float(np.mean(rolling_vars))
+    windows = sliding_window_view(positions, window_size)
+    return float(np.mean(np.var(windows, axis=1)))
 
 
 def assess_tracking_quality(

kinemotion/core/validation.py

@@ -198,3 +198,73 @@ class MetricsValidator(ABC):
             ValidationResult with all issues and status
         """
         pass
+
+    def _validate_metric_with_bounds(
+        self,
+        name: str,
+        value: float,
+        bounds: MetricBounds,
+        profile: AthleteProfile | None,
+        result: ValidationResult,
+        error_suffix: str = "physically impossible",
+        format_str: str = "{value}",
+    ) -> None:
+        """Generic validation for metrics with physical and profile bounds.
+
+        Args:
+            name: Metric name for messages
+            value: Metric value
+            bounds: Bounds definition
+            profile: Athlete profile for expected ranges (can be None)
+            result: Validation result to add issues to
+            error_suffix: Description for out-of-bounds errors
+            format_str: Format string for value display
+        """
+        formatted_value = format_str.format(value=value)
+        display_name = name.replace("_", " ").title()
+
+        if not bounds.is_physically_possible(value):
+            result.add_error(
+                name,
+                f"{display_name} {formatted_value} {error_suffix}",
+                value=value,
+                bounds=(bounds.absolute_min, bounds.absolute_max),
+            )
+        elif profile is not None and bounds.contains(value, profile):
+            result.add_info(
+                name,
+                f"{display_name} {formatted_value} within expected range for {profile.value}",
+                value=value,
+            )
+        elif profile is not None:
+            expected_min, expected_max = self._get_profile_range(profile, bounds)
+            result.add_warning(
+                name,
+                f"{display_name} {formatted_value} outside typical range "
+                f"[{expected_min:.3f}-{expected_max:.3f}] for {profile.value}",
+                value=value,
+                bounds=(expected_min, expected_max),
+            )
+
+    @staticmethod
+    def _get_profile_range(profile: AthleteProfile, bounds: MetricBounds) -> tuple[float, float]:
+        """Get min/max bounds for specific profile.
+
+        Args:
+            profile: Athlete profile
+            bounds: Metric bounds definition
+
+        Returns:
+            Tuple of (min, max) bounds for the profile
+        """
+        profile_ranges = {
+            AthleteProfile.ELDERLY: (bounds.practical_min, bounds.recreational_max),
+            AthleteProfile.UNTRAINED: (bounds.practical_min, bounds.recreational_max),
+            AthleteProfile.RECREATIONAL: (bounds.recreational_min, bounds.recreational_max),
+            AthleteProfile.TRAINED: (
+                (bounds.recreational_min + bounds.elite_min) / 2,
+                (bounds.recreational_max + bounds.elite_max) / 2,
+            ),
+            AthleteProfile.ELITE: (bounds.elite_min, bounds.elite_max),
+        }
+        return profile_ranges.get(profile, (bounds.absolute_min, bounds.absolute_max))

kinemotion/core/video_analysis_base.py

@@ -0,0 +1,132 @@
+"""Base types and patterns for video analysis APIs.
+
+This module defines shared infrastructure for jump-type-specific analysis modules.
+Each jump type (CMJ, Drop Jump, etc.) has its own analysis algorithms, but they
+share common patterns for:
+
+1. Configuration (VideoConfig dataclass)
+2. Results (VideoResult dataclass)
+3. Parameter overrides (AnalysisOverrides dataclass)
+4. Bulk processing utilities
+
+To add a new jump type:
+1. Create a new module: src/kinemotion/{jump_type}/
+2. Implement analysis algorithms in {jump_type}/analysis.py
+3. Use the patterns in this module for API structure
+4. Import process_videos_bulk_generic from pipeline_utils for bulk processing
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..auto_tuning import QualityPreset
+    from ..timing import Timer
+
+__all__ = [
+    "AnalysisOverrides",
+    "VideoAnalysisConfig",
+    "VideoAnalysisResult",
+    "JumpAnalysisPipeline",
+]
+
+
+@dataclass
+class AnalysisOverrides:
+    """Optional overrides for analysis parameters.
+
+    Allows fine-tuning of specific analysis parameters beyond quality presets.
+    If None, values will be determined by the quality preset.
+
+    Common overrides across all jump types:
+    - smoothing_window: Number of frames for Savitzky-Golay smoothing
+    - velocity_threshold: Threshold for phase detection
+    - min_contact_frames: Minimum frames for ground contact
+    - visibility_threshold: Minimum landmark visibility (0-1)
+    """
+
+    smoothing_window: int | None = None
+    velocity_threshold: float | None = None
+    min_contact_frames: int | None = None
+    visibility_threshold: float | None = None
+
+
+@dataclass
+class VideoAnalysisConfig:
+    """Base configuration for video analysis.
+
+    Subclasses should add jump-type-specific fields (e.g., drop_start_frame
+    for Drop Jump, or additional overrides for CMJ).
+    """
+
+    video_path: str
+    quality: str = "balanced"
+    output_video: str | None = None
+    json_output: str | None = None
+    overrides: AnalysisOverrides | None = None
+    detection_confidence: float | None = None
+    tracking_confidence: float | None = None
+    verbose: bool = False
+    timer: "Timer | None" = None
+
+
+@dataclass
+class VideoAnalysisResult:
+    """Base result for video analysis.
+
+    Subclasses should add jump-type-specific fields.
+    """
+
+    video_path: str
+    success: bool
+    metrics: object | None = None  # Will be CMJMetrics, DropJumpMetrics, etc.
+    error: str | None = None
+    processing_time: float = 0.0
+
+
+class JumpAnalysisPipeline(ABC):
+    """Abstract base class for jump analysis pipelines.
+
+    Defines the common structure for processing jump videos. Each jump type
+    implements the specific analysis logic while following this pattern.
+
+    Example:
+        class CMJPipeline(JumpAnalysisPipeline):
+            def analyze(self) -> CMJMetrics:
+                # CMJ-specific analysis (backward search algorithm)
+                ...
+
+        class DropJumpPipeline(JumpAnalysisPipeline):
+            def analyze(self) -> DropJumpMetrics:
+                # Drop jump-specific analysis (forward search algorithm)
+                ...
+    """
+
+    def __init__(
+        self,
+        video_path: str,
+        quality_preset: "QualityPreset",
+        overrides: AnalysisOverrides | None,
+        timer: "Timer",
+    ) -> None:
+        """Initialize the analysis pipeline."""
+        self.video_path = video_path
+        self.quality_preset = quality_preset
+        self.overrides = overrides
+        self.timer = timer
+
+    @abstractmethod
+    def analyze(self) -> object:
+        """Run the jump-specific analysis algorithm.
+
+        Returns:
+            Metrics object with jump-type-specific results.
+        """
+        ...
+
+    def validate_video_exists(self) -> None:
+        """Validate that the input video file exists."""
+        if not Path(self.video_path).exists():
+            raise FileNotFoundError(f"Video file not found: {self.video_path}")