kinemotion 0.73.0__py3-none-any.whl → 0.74.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/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}")

kinemotion/core/video_io.py

@@ -50,9 +50,27 @@ class VideoProcessor:
         self._current_timestamp_ms: int = 0  # Timestamp for the current frame
 
         # 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.
+        self._extract_dimensions_from_frame()
+
+        # Initialize metadata placeholders
+        self.rotation = 0  # Will be set by _extract_video_metadata()
+        self.codec: str | None = None  # Will be set by _extract_video_metadata()
+
+        # Initialize display dimensions (may be adjusted by SAR metadata)
+        self.display_width = self.width
+        self.display_height = self.height
+        self._extract_video_metadata()
+
+        # Apply rotation to dimensions if needed
+        self._apply_rotation_to_dimensions()
+
+    def _extract_dimensions_from_frame(self) -> None:
+        """Extract video dimensions by reading the first frame.
+
+        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
@@ -63,22 +81,13 @@ 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()
-
-        # Extract codec information from video metadata
-        self.codec: str | None = None  # 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._extract_video_metadata()
+    def _apply_rotation_to_dimensions(self) -> None:
+        """Swap width/height for 90/-90 degree rotations.
 
-        # Apply rotation to dimensions if needed
+        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.
+        """
         if self.rotation in [90, -90, 270]:
             # Swap dimensions for 90/-90 degree rotations
             self.width, self.height = self.height, self.width

kinemotion/countermovement_jump/analysis.py

@@ -55,103 +55,6 @@ class CMJPhase(Enum):
     UNKNOWN = "unknown"
 
 
-@unused(
-    reason="Alternative implementation not called by pipeline",
-    since="0.34.0",
-)
-def find_standing_phase(
-    positions: FloatArray,
-    velocities: FloatArray,
-    fps: float,
-    min_standing_duration: float = 0.5,
-    velocity_threshold: float = 0.01,
-) -> int | None:
-    """
-    Find the end of standing phase (start of countermovement).
-
-    Looks for a period of low velocity (standing) followed by consistent
-    downward motion.
-
-    Args:
-        positions: Array of vertical positions (normalized 0-1)
-        velocities: Array of vertical velocities
-        fps: Video frame rate
-        min_standing_duration: Minimum standing duration in seconds (default: 0.5s)
-        velocity_threshold: Velocity threshold for standing detection
-
-    Returns:
-        Frame index where countermovement begins, or None if not detected.
-    """
-    min_standing_frames = int(fps * min_standing_duration)
-
-    if len(positions) < min_standing_frames:
-        return None
-
-    # Find periods of low velocity (standing)
-    is_standing = np.abs(velocities) < velocity_threshold
-
-    # Look for first sustained standing period
-    standing_count = 0
-    standing_end = None
-
-    for i in range(len(is_standing)):
-        if is_standing[i]:
-            standing_count += 1
-            if standing_count >= min_standing_frames:
-                standing_end = i
-        else:
-            if standing_end is not None:
-                # Found end of standing phase
-                return standing_end
-            standing_count = 0
-
-    return None
-
-
-@unused(
-    reason="Alternative implementation not called by pipeline",
-    since="0.34.0",
-)
-def find_countermovement_start(
-    velocities: FloatArray,
-    countermovement_threshold: float = 0.015,
-    min_eccentric_frames: int = 3,
-    standing_start: int | None = None,
-) -> int | None:
-    """
-    Find the start of countermovement (eccentric phase).
-
-    Detects when velocity becomes consistently positive (downward motion in
-    normalized coords).
-
-    Args:
-        velocities: Array of SIGNED vertical velocities
-        countermovement_threshold: Velocity threshold for detecting downward
-            motion (POSITIVE)
-        min_eccentric_frames: Minimum consecutive frames of downward motion
-        standing_start: Optional frame where standing phase ended
-
-    Returns:
-        Frame index where countermovement begins, or None if not detected.
-    """
-    start_frame = standing_start if standing_start is not None else 0
-
-    # Look for sustained downward velocity (POSITIVE in normalized coords)
-    is_downward = velocities[start_frame:] > countermovement_threshold
-    consecutive_count = 0
-
-    for i in range(len(is_downward)):
-        if is_downward[i]:
-            consecutive_count += 1
-            if consecutive_count >= min_eccentric_frames:
-                # Found start of eccentric phase
-                return start_frame + i - consecutive_count + 1
-        else:
-            consecutive_count = 0
-
-    return None
-
-
 def find_lowest_point(
     positions: FloatArray,
     velocities: FloatArray,

kinemotion/countermovement_jump/api.py

@@ -393,6 +393,24 @@ class CMJVideoConfig:
     overrides: AnalysisOverrides | None = None
     detection_confidence: float | None = None
     tracking_confidence: float | None = None
+    verbose: bool = False
+    timer: Timer | None = None
+    pose_tracker: "MediaPipePoseTracker | None" = None
+
+    def to_kwargs(self) -> dict:
+        """Convert config to kwargs dict for process_cmj_video."""
+        return {
+            "video_path": self.video_path,
+            "quality": self.quality,
+            "output_video": self.output_video,
+            "json_output": self.json_output,
+            "overrides": self.overrides,
+            "detection_confidence": self.detection_confidence,
+            "tracking_confidence": self.tracking_confidence,
+            "verbose": self.verbose,
+            "timer": self.timer,
+            "pose_tracker": self.pose_tracker,
+        }
 
 
 @dataclass
@@ -511,6 +529,23 @@ def process_cmj_video(
             return metrics
 
 
+def process_cmj_video_from_config(
+    config: CMJVideoConfig,
+) -> CMJMetrics:
+    """Process a CMJ video using a configuration object.
+
+    This is a convenience wrapper around process_cmj_video that
+    accepts a CMJVideoConfig instead of individual parameters.
+
+    Args:
+        config: Configuration object containing all analysis parameters
+
+    Returns:
+        CMJMetrics object containing analysis results
+    """
+    return process_cmj_video(**config.to_kwargs())
+
+
 def process_cmj_videos_bulk(
     configs: list[CMJVideoConfig],
     max_workers: int = 4,
@@ -537,17 +572,8 @@ def _process_cmj_video_wrapper(config: CMJVideoConfig) -> CMJVideoResult:
     start_time = time.perf_counter()
 
     try:
-        metrics = process_cmj_video(
-            video_path=config.video_path,
-            quality=config.quality,
-            output_video=config.output_video,
-            json_output=config.json_output,
-            overrides=config.overrides,
-            detection_confidence=config.detection_confidence,
-            tracking_confidence=config.tracking_confidence,
-            verbose=False,
-        )
-
+        # Use convenience wrapper to avoid parameter unpacking
+        metrics = process_cmj_video_from_config(config)
         processing_time = time.perf_counter() - start_time
 
         return CMJVideoResult(