kinemotion 0.10.12__py3-none-any.whl → 0.11.0__py3-none-any.whl

kinemotion/__init__.py

@@ -1,14 +1,31 @@
 """Kinemotion: Video-based kinematic analysis for athletic performance."""
 
-from .api import VideoConfig, VideoResult, process_video, process_videos_bulk
+from .api import (
+    CMJVideoConfig,
+    CMJVideoResult,
+    VideoConfig,
+    VideoResult,
+    process_cmj_video,
+    process_cmj_videos_bulk,
+    process_video,
+    process_videos_bulk,
+)
+from .cmj.kinematics import CMJMetrics
 from .dropjump.kinematics import DropJumpMetrics
 
 __version__ = "0.1.0"
 
 __all__ = [
+    # Drop jump API
     "process_video",
     "process_videos_bulk",
     "VideoConfig",
     "VideoResult",
     "DropJumpMetrics",
+    # CMJ API
+    "process_cmj_video",
+    "process_cmj_videos_bulk",
+    "CMJVideoConfig",
+    "CMJVideoResult",
+    "CMJMetrics",
 ]

kinemotion/api.py

@@ -8,6 +8,9 @@ from pathlib import Path
 
 import numpy as np
 
+from .cmj.analysis import detect_cmj_phases
+from .cmj.debug_overlay import CMJDebugOverlayRenderer
+from .cmj.kinematics import CMJMetrics, calculate_cmj_metrics
 from .core.auto_tuning import (
     AnalysisParameters,
     QualityPreset,
@@ -602,3 +605,335 @@ def _process_video_wrapper(config: VideoConfig) -> VideoResult:
             error=str(e),
             processing_time=processing_time,
         )
+
+
+# ========== CMJ Analysis API ==========
+
+
+@dataclass
+class CMJVideoConfig:
+    """Configuration for processing a single CMJ video."""
+
+    video_path: str
+    quality: str = "balanced"
+    output_video: str | None = None
+    json_output: str | None = None
+    smoothing_window: int | None = None
+    velocity_threshold: float | None = None
+    countermovement_threshold: float | None = None
+    min_contact_frames: int | None = None
+    visibility_threshold: float | None = None
+    detection_confidence: float | None = None
+    tracking_confidence: float | None = None
+
+
+@dataclass
+class CMJVideoResult:
+    """Result of processing a single CMJ video."""
+
+    video_path: str
+    success: bool
+    metrics: CMJMetrics | None = None
+    error: str | None = None
+    processing_time: float = 0.0
+
+
+def process_cmj_video(
+    video_path: str,
+    quality: str = "balanced",
+    output_video: str | None = None,
+    json_output: str | None = None,
+    smoothing_window: int | None = None,
+    velocity_threshold: float | None = None,
+    countermovement_threshold: float | None = None,
+    min_contact_frames: int | None = None,
+    visibility_threshold: float | None = None,
+    detection_confidence: float | None = None,
+    tracking_confidence: float | None = None,
+    verbose: bool = False,
+) -> CMJMetrics:
+    """
+    Process a single CMJ video and return metrics.
+
+    CMJ (Counter Movement Jump) is performed at floor level without a drop box.
+    Athletes start standing, perform a countermovement (eccentric phase), then
+    jump upward (concentric phase).
+
+    Args:
+        video_path: Path to the input video file
+        quality: Analysis quality preset ("fast", "balanced", or "accurate")
+        output_video: Optional path for debug video output
+        json_output: Optional path for JSON metrics output
+        smoothing_window: Optional override for smoothing window
+        velocity_threshold: Optional override for velocity threshold
+        countermovement_threshold: Optional override for countermovement threshold
+        min_contact_frames: Optional override for minimum contact frames
+        visibility_threshold: Optional override for visibility threshold
+        detection_confidence: Optional override for pose detection confidence
+        tracking_confidence: Optional override for pose tracking confidence
+        verbose: Print processing details
+
+    Returns:
+        CMJMetrics object containing analysis results
+
+    Raises:
+        ValueError: If video cannot be processed or parameters are invalid
+        FileNotFoundError: If video file does not exist
+
+    Example:
+        >>> metrics = process_cmj_video(
+        ...     "athlete_cmj.mp4",
+        ...     quality="balanced",
+        ...     verbose=True
+        ... )
+        >>> print(f"Jump height: {metrics.jump_height:.3f}m")
+        >>> print(f"Countermovement depth: {metrics.countermovement_depth:.3f}m")
+    """
+    if not Path(video_path).exists():
+        raise FileNotFoundError(f"Video file not found: {video_path}")
+
+    # Convert quality string to enum
+    quality_preset = _parse_quality_preset(quality)
+
+    # Initialize video processor
+    with VideoProcessor(video_path) as video:
+        if verbose:
+            print(
+                f"Video: {video.width}x{video.height} @ {video.fps:.2f} fps, "
+                f"{video.frame_count} frames"
+            )
+
+        # Determine confidence levels
+        det_conf, track_conf = _determine_confidence_levels(
+            quality_preset, detection_confidence, tracking_confidence
+        )
+
+        # Track all frames
+        tracker = PoseTracker(
+            min_detection_confidence=det_conf, min_tracking_confidence=track_conf
+        )
+        frames, landmarks_sequence = _process_all_frames(video, tracker, verbose)
+
+        # Auto-tune parameters
+        characteristics = analyze_video_sample(
+            landmarks_sequence, video.fps, video.frame_count
+        )
+        params = auto_tune_parameters(characteristics, quality_preset)
+
+        # Apply expert overrides
+        params = _apply_expert_overrides(
+            params,
+            smoothing_window,
+            velocity_threshold,
+            min_contact_frames,
+            visibility_threshold,
+        )
+
+        if verbose:
+            _print_verbose_parameters(video, characteristics, quality_preset, params)
+
+        # Apply smoothing
+        smoothed_landmarks = _apply_smoothing(landmarks_sequence, params, verbose)
+
+        # Extract foot positions
+        if verbose:
+            print("Extracting foot positions...")
+        vertical_positions, _ = _extract_vertical_positions(smoothed_landmarks)
+        tracking_method = "foot"
+
+        # Calculate countermovement threshold (FPS-adjusted)
+        # POSITIVE threshold for downward motion (squatting) in normalized coordinates
+        cm_threshold = countermovement_threshold
+        if cm_threshold is None:
+            cm_threshold = 0.015 * (30.0 / video.fps)
+
+        # Detect CMJ phases
+        if verbose:
+            print("Detecting CMJ phases...")
+
+        phases = detect_cmj_phases(
+            vertical_positions,
+            video.fps,
+            velocity_threshold=params.velocity_threshold,
+            countermovement_threshold=cm_threshold,
+            min_contact_frames=params.min_contact_frames,
+            min_eccentric_frames=params.min_contact_frames,
+            use_curvature=params.use_curvature,
+            window_length=params.smoothing_window,
+            polyorder=params.polyorder,
+        )
+
+        if phases is None:
+            raise ValueError("Could not detect CMJ phases in video")
+
+        standing_end, lowest_point, takeoff_frame, landing_frame = phases
+
+        # Calculate metrics
+        if verbose:
+            print("Calculating metrics...")
+
+        # Use signed velocity for CMJ (need direction information)
+        from .cmj.analysis import compute_signed_velocity
+
+        velocities = compute_signed_velocity(
+            vertical_positions,
+            window_length=params.smoothing_window,
+            polyorder=params.polyorder,
+        )
+
+        metrics = calculate_cmj_metrics(
+            vertical_positions,
+            velocities,
+            standing_end,
+            lowest_point,
+            takeoff_frame,
+            landing_frame,
+            video.fps,
+            tracking_method=tracking_method,
+        )
+
+        # Generate outputs if requested
+        if json_output:
+            import json
+
+            output_path = Path(json_output)
+            output_path.write_text(json.dumps(metrics.to_dict(), indent=2))
+            if verbose:
+                print(f"Metrics written to: {json_output}")
+
+        if output_video:
+            if verbose:
+                print(f"Generating debug video: {output_video}")
+
+            with CMJDebugOverlayRenderer(
+                output_video,
+                video.width,
+                video.height,
+                video.display_width,
+                video.display_height,
+                video.fps,
+            ) as renderer:
+                for i, frame in enumerate(frames):
+                    annotated = renderer.render_frame(
+                        frame, smoothed_landmarks[i], i, metrics
+                    )
+                    renderer.write_frame(annotated)
+
+            if verbose:
+                print(f"Debug video saved: {output_video}")
+
+        if verbose:
+            print(f"\nJump height: {metrics.jump_height:.3f}m")
+            print(f"Flight time: {metrics.flight_time*1000:.1f}ms")
+            print(f"Countermovement depth: {metrics.countermovement_depth:.3f}m")
+
+        return metrics
+
+
+def process_cmj_videos_bulk(
+    configs: list[CMJVideoConfig],
+    max_workers: int = 4,
+    progress_callback: Callable[[CMJVideoResult], None] | None = None,
+) -> list[CMJVideoResult]:
+    """
+    Process multiple CMJ videos in parallel using ProcessPoolExecutor.
+
+    Args:
+        configs: List of CMJVideoConfig objects specifying video paths and parameters
+        max_workers: Maximum number of parallel workers (default: 4)
+        progress_callback: Optional callback function called after each video completes.
+                         Receives CMJVideoResult object.
+
+    Returns:
+        List of CMJVideoResult objects, one per input video, in completion order
+
+    Example:
+        >>> configs = [
+        ...     CMJVideoConfig("video1.mp4"),
+        ...     CMJVideoConfig("video2.mp4", quality="accurate"),
+        ...     CMJVideoConfig("video3.mp4", output_video="debug3.mp4"),
+        ... ]
+        >>> results = process_cmj_videos_bulk(configs, max_workers=4)
+        >>> for result in results:
+        ...     if result.success:
+        ...         print(f"{result.video_path}: {result.metrics.jump_height:.3f}m")
+        ...     else:
+        ...         print(f"{result.video_path}: FAILED - {result.error}")
+    """
+    results: list[CMJVideoResult] = []
+
+    # Use ProcessPoolExecutor for CPU-bound video processing
+    with ProcessPoolExecutor(max_workers=max_workers) as executor:
+        # Submit all jobs
+        future_to_config = {
+            executor.submit(_process_cmj_video_wrapper, config): config
+            for config in configs
+        }
+
+        # Process results as they complete
+        for future in as_completed(future_to_config):
+            config = future_to_config[future]
+            result: CMJVideoResult
+
+            try:
+                result = future.result()
+                results.append(result)
+            except Exception as e:
+                result = CMJVideoResult(
+                    video_path=config.video_path, success=False, error=str(e)
+                )
+                results.append(result)
+
+            # Call progress callback if provided
+            if progress_callback:
+                progress_callback(result)
+
+    return results
+
+
+def _process_cmj_video_wrapper(config: CMJVideoConfig) -> CMJVideoResult:
+    """
+    Wrapper function for parallel CMJ processing. Must be picklable (top-level function).
+
+    Args:
+        config: CMJVideoConfig object with processing parameters
+
+    Returns:
+        CMJVideoResult object with metrics or error information
+    """
+    start_time = time.time()
+
+    try:
+        metrics = process_cmj_video(
+            video_path=config.video_path,
+            quality=config.quality,
+            output_video=config.output_video,
+            json_output=config.json_output,
+            smoothing_window=config.smoothing_window,
+            velocity_threshold=config.velocity_threshold,
+            countermovement_threshold=config.countermovement_threshold,
+            min_contact_frames=config.min_contact_frames,
+            visibility_threshold=config.visibility_threshold,
+            detection_confidence=config.detection_confidence,
+            tracking_confidence=config.tracking_confidence,
+            verbose=False,  # Disable verbose in parallel mode
+        )
+
+        processing_time = time.time() - start_time
+
+        return CMJVideoResult(
+            video_path=config.video_path,
+            success=True,
+            metrics=metrics,
+            processing_time=processing_time,
+        )
+
+    except Exception as e:
+        processing_time = time.time() - start_time
+
+        return CMJVideoResult(
+            video_path=config.video_path,
+            success=False,
+            error=str(e),
+            processing_time=processing_time,
+        )

kinemotion/cli.py

@@ -2,6 +2,7 @@
 
 import click
 
+from .cmj.cli import cmj_analyze
 from .dropjump.cli import dropjump_analyze
 
 
@@ -14,6 +15,7 @@ def cli() -> None:
 
 # Register commands from submodules
 cli.add_command(dropjump_analyze)
+cli.add_command(cmj_analyze)
 
 
 if __name__ == "__main__":

kinemotion/cmj/__init__.py

@@ -0,0 +1,5 @@
+"""Counter Movement Jump (CMJ) analysis module."""
+
+from kinemotion.cmj.kinematics import CMJMetrics
+
+__all__ = ["CMJMetrics"]