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

kinemotion/cmj/cli.py

@@ -0,0 +1,626 @@
+"""Command-line interface for counter movement jump (CMJ) analysis."""
+
+import glob
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import click
+import numpy as np
+
+from ..core.auto_tuning import (
+    AnalysisParameters as AutoTunedParams,
+)
+from ..core.auto_tuning import (
+    QualityPreset,
+    analyze_video_sample,
+    auto_tune_parameters,
+)
+from ..core.pose import PoseTracker
+from ..core.smoothing import smooth_landmarks, smooth_landmarks_advanced
+from ..core.video_io import VideoProcessor
+from .analysis import detect_cmj_phases
+from .debug_overlay import CMJDebugOverlayRenderer
+from .kinematics import CMJMetrics, calculate_cmj_metrics
+
+
+@dataclass
+class AnalysisParameters:
+    """Expert parameters for CMJ analysis customization."""
+
+    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
+
+
+@click.command(name="cmj-analyze")
+@click.argument("video_path", nargs=-1, type=click.Path(exists=False), required=True)
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(),
+    help="Path for debug video output (optional)",
+)
+@click.option(
+    "--json-output",
+    "-j",
+    type=click.Path(),
+    help="Path for JSON metrics output (default: stdout)",
+)
+@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,
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    help="Show auto-selected parameters and analysis details",
+)
+# Batch processing options
+@click.option(
+    "--batch",
+    is_flag=True,
+    help="Enable batch processing mode for multiple videos",
+)
+@click.option(
+    "--workers",
+    type=int,
+    default=4,
+    help="Number of parallel workers for batch processing (default: 4)",
+    show_default=True,
+)
+@click.option(
+    "--output-dir",
+    type=click.Path(),
+    help="Directory for debug video outputs (batch mode only)",
+)
+@click.option(
+    "--json-output-dir",
+    type=click.Path(),
+    help="Directory for JSON metrics outputs (batch mode only)",
+)
+@click.option(
+    "--csv-summary",
+    type=click.Path(),
+    help="Path for CSV summary export (batch mode only)",
+)
+# Expert parameters (hidden in help, but always available for advanced users)
+@click.option(
+    "--smoothing-window",
+    type=int,
+    default=None,
+    help="[EXPERT] Override auto-tuned smoothing window size",
+)
+@click.option(
+    "--velocity-threshold",
+    type=float,
+    default=None,
+    help="[EXPERT] Override auto-tuned velocity threshold for flight detection",
+)
+@click.option(
+    "--countermovement-threshold",
+    type=float,
+    default=None,
+    help="[EXPERT] Override auto-tuned countermovement threshold (negative value)",
+)
+@click.option(
+    "--min-contact-frames",
+    type=int,
+    default=None,
+    help="[EXPERT] Override auto-tuned minimum contact frames",
+)
+@click.option(
+    "--visibility-threshold",
+    type=float,
+    default=None,
+    help="[EXPERT] Override visibility threshold",
+)
+@click.option(
+    "--detection-confidence",
+    type=float,
+    default=None,
+    help="[EXPERT] Override pose detection confidence",
+)
+@click.option(
+    "--tracking-confidence",
+    type=float,
+    default=None,
+    help="[EXPERT] Override pose tracking confidence",
+)
+def cmj_analyze(  # NOSONAR(S107) - Click CLI requires individual parameters for each option
+    video_path: tuple[str, ...],
+    output: str | None,
+    json_output: str | None,
+    quality: str,
+    verbose: bool,
+    batch: bool,
+    workers: int,
+    output_dir: str | None,
+    json_output_dir: str | None,
+    csv_summary: str | None,
+    smoothing_window: int | None,
+    velocity_threshold: float | None,
+    countermovement_threshold: float | None,
+    min_contact_frames: int | None,
+    visibility_threshold: float | None,
+    detection_confidence: float | None,
+    tracking_confidence: float | None,
+) -> None:
+    """
+    Analyze counter movement jump (CMJ) video(s) to estimate jump performance metrics.
+
+    Uses intelligent auto-tuning to select optimal parameters based on video characteristics.
+    Parameters are automatically adjusted for frame rate, tracking quality, and analysis preset.
+
+    VIDEO_PATH: Path(s) to video file(s). Supports glob patterns in batch mode.
+
+    Examples:
+
+    \\b
+    # Basic analysis
+    kinemotion cmj-analyze video.mp4
+
+    \\b
+    # With debug video output
+    kinemotion cmj-analyze video.mp4 --output debug.mp4
+
+    \\b
+    # Batch mode with glob pattern
+    kinemotion cmj-analyze videos/*.mp4 --batch --workers 4
+
+    \\b
+    # Batch with output directories
+    kinemotion cmj-analyze videos/*.mp4 --batch \\
+        --json-output-dir results/ --csv-summary summary.csv
+    """
+    # Expand glob patterns and collect all video files
+    video_files: list[str] = []
+    for pattern in video_path:
+        expanded = glob.glob(pattern)
+        if expanded:
+            video_files.extend(expanded)
+        elif Path(pattern).exists():
+            video_files.append(pattern)
+        else:
+            click.echo(f"Warning: No files found for pattern: {pattern}", err=True)
+
+    if not video_files:
+        click.echo("Error: No video files found", err=True)
+        sys.exit(1)
+
+    # Determine if batch mode should be used
+    use_batch = batch or len(video_files) > 1
+
+    quality_preset = QualityPreset(quality.lower())
+
+    # Group expert parameters
+    expert_params = AnalysisParameters(
+        smoothing_window=smoothing_window,
+        velocity_threshold=velocity_threshold,
+        countermovement_threshold=countermovement_threshold,
+        min_contact_frames=min_contact_frames,
+        visibility_threshold=visibility_threshold,
+        detection_confidence=detection_confidence,
+        tracking_confidence=tracking_confidence,
+    )
+
+    if use_batch:
+        click.echo(
+            f"Batch mode: Processing {len(video_files)} video(s) with {workers} workers",
+            err=True,
+        )
+        click.echo("Note: Batch processing not yet fully implemented", err=True)
+        click.echo("Processing videos sequentially...", err=True)
+        for video in video_files:
+            try:
+                click.echo(f"\nProcessing: {video}", err=True)
+                out_path = None
+                json_path = None
+                if output_dir:
+                    out_path = str(Path(output_dir) / f"{Path(video).stem}_debug.mp4")
+                if json_output_dir:
+                    json_path = str(Path(json_output_dir) / f"{Path(video).stem}.json")
+                _process_single(
+                    video, out_path, json_path, quality_preset, verbose, expert_params
+                )
+            except Exception as e:
+                click.echo(f"Error processing {video}: {e}", err=True)
+                continue
+    else:
+        # Single video mode
+        try:
+            _process_single(
+                video_files[0],
+                output,
+                json_output,
+                quality_preset,
+                verbose,
+                expert_params,
+            )
+        except Exception as e:
+            click.echo(f"Error: {e}", err=True)
+            sys.exit(1)
+
+
+def _determine_initial_confidence(
+    quality_preset: QualityPreset,
+    expert_params: AnalysisParameters,
+) -> tuple[float, float]:
+    """Determine initial detection and tracking confidence levels."""
+    initial_detection_conf = 0.5
+    initial_tracking_conf = 0.5
+
+    if quality_preset == QualityPreset.FAST:
+        initial_detection_conf = 0.3
+        initial_tracking_conf = 0.3
+    elif quality_preset == QualityPreset.ACCURATE:
+        initial_detection_conf = 0.6
+        initial_tracking_conf = 0.6
+
+    # Override with expert values if provided
+    if expert_params.detection_confidence is not None:
+        initial_detection_conf = expert_params.detection_confidence
+    if expert_params.tracking_confidence is not None:
+        initial_tracking_conf = expert_params.tracking_confidence
+
+    return initial_detection_conf, initial_tracking_conf
+
+
+def _track_all_frames(video: VideoProcessor, tracker: PoseTracker) -> tuple[list, list]:
+    """Track pose landmarks in all video frames."""
+    click.echo("Tracking pose landmarks...", err=True)
+    landmarks_sequence = []
+    frames = []
+
+    bar: Any
+    with click.progressbar(length=video.frame_count, label="Processing frames") as bar:
+        while True:
+            frame = video.read_frame()
+            if frame is None:
+                break
+
+            frames.append(frame)
+            landmarks = tracker.process_frame(frame)
+            landmarks_sequence.append(landmarks)
+
+            bar.update(1)
+
+    tracker.close()
+    return frames, landmarks_sequence
+
+
+def _apply_expert_param_overrides(
+    params: AutoTunedParams, expert_params: AnalysisParameters
+) -> AutoTunedParams:
+    """Apply expert parameter overrides to auto-tuned parameters."""
+    if expert_params.smoothing_window is not None:
+        params.smoothing_window = expert_params.smoothing_window
+    if expert_params.velocity_threshold is not None:
+        params.velocity_threshold = expert_params.velocity_threshold
+    if expert_params.min_contact_frames is not None:
+        params.min_contact_frames = expert_params.min_contact_frames
+    if expert_params.visibility_threshold is not None:
+        params.visibility_threshold = expert_params.visibility_threshold
+    return params
+
+
+def _print_auto_tuned_params(
+    video: VideoProcessor,
+    quality_preset: QualityPreset,
+    params: AutoTunedParams,
+    countermovement_threshold: float,
+) -> None:
+    """Print auto-tuned parameters in verbose mode."""
+    click.echo("\n" + "=" * 60, err=True)
+    click.echo("AUTO-TUNED PARAMETERS", err=True)
+    click.echo("=" * 60, err=True)
+    click.echo(f"Video FPS: {video.fps:.2f}", err=True)
+    click.echo(f"Quality preset: {quality_preset.value}", err=True)
+    click.echo("\nSelected parameters:", err=True)
+    click.echo(f"  smoothing_window: {params.smoothing_window}", err=True)
+    click.echo(f"  polyorder: {params.polyorder}", err=True)
+    click.echo(f"  velocity_threshold: {params.velocity_threshold:.4f}", err=True)
+    click.echo(
+        f"  countermovement_threshold: {countermovement_threshold:.4f}", err=True
+    )
+    click.echo(f"  min_contact_frames: {params.min_contact_frames}", err=True)
+    click.echo(f"  visibility_threshold: {params.visibility_threshold}", err=True)
+    click.echo(f"  detection_confidence: {params.detection_confidence}", err=True)
+    click.echo(f"  tracking_confidence: {params.tracking_confidence}", err=True)
+    click.echo(f"  outlier_rejection: {params.outlier_rejection}", err=True)
+    click.echo(f"  bilateral_filter: {params.bilateral_filter}", err=True)
+    click.echo(f"  use_curvature: {params.use_curvature}", err=True)
+    click.echo("=" * 60 + "\n", err=True)
+
+
+def _smooth_landmark_sequence(
+    landmarks_sequence: list, params: AutoTunedParams
+) -> list:
+    """Apply smoothing to landmark sequence."""
+    if params.outlier_rejection or params.bilateral_filter:
+        if params.outlier_rejection:
+            click.echo("Smoothing landmarks with outlier rejection...", err=True)
+        if params.bilateral_filter:
+            click.echo(
+                "Using bilateral temporal filter for edge-preserving smoothing...",
+                err=True,
+            )
+        return smooth_landmarks_advanced(
+            landmarks_sequence,
+            window_length=params.smoothing_window,
+            polyorder=params.polyorder,
+            use_outlier_rejection=params.outlier_rejection,
+            use_bilateral=params.bilateral_filter,
+        )
+    else:
+        click.echo("Smoothing landmarks...", err=True)
+        return smooth_landmarks(
+            landmarks_sequence,
+            window_length=params.smoothing_window,
+            polyorder=params.polyorder,
+        )
+
+
+def _extract_positions_from_landmarks(
+    smoothed_landmarks: list,
+) -> tuple[np.ndarray, str]:
+    """Extract vertical foot positions from landmarks.
+
+    Args:
+        smoothed_landmarks: Smoothed landmark sequence
+
+    Returns:
+        Tuple of (positions array, tracking method name)
+    """
+    click.echo("Extracting foot positions...", err=True)
+    position_list: list[float] = []
+
+    for frame_landmarks in smoothed_landmarks:
+        if frame_landmarks:
+            # Average foot position (ankles and heels)
+            foot_y_values = []
+            for key in ["left_ankle", "right_ankle", "left_heel", "right_heel"]:
+                if key in frame_landmarks:
+                    foot_y_values.append(frame_landmarks[key][1])
+
+            if foot_y_values:
+                avg_y = float(np.mean(foot_y_values))
+                position_list.append(avg_y)
+            else:
+                position_list.append(position_list[-1] if position_list else 0.5)
+        else:
+            position_list.append(position_list[-1] if position_list else 0.5)
+
+    return np.array(position_list), "foot"
+
+
+def _process_single(
+    video_path: str,
+    output: str | None,
+    json_output: str | None,
+    quality_preset: QualityPreset,
+    verbose: bool,
+    expert_params: AnalysisParameters,
+) -> None:
+    """Process a single CMJ video."""
+    try:
+        with VideoProcessor(video_path) as video:
+            click.echo(
+                f"Video: {video.width}x{video.height} @ {video.fps:.2f} fps, "
+                f"{video.frame_count} frames",
+                err=True,
+            )
+
+            # Determine confidence levels
+            detection_conf, tracking_conf = _determine_initial_confidence(
+                quality_preset, expert_params
+            )
+
+            # Track all frames
+            tracker = PoseTracker(
+                min_detection_confidence=detection_conf,
+                min_tracking_confidence=tracking_conf,
+            )
+            frames, landmarks_sequence = _track_all_frames(video, tracker)
+
+            if not landmarks_sequence:
+                click.echo("Error: No frames processed", err=True)
+                sys.exit(1)
+
+            # Auto-tune parameters
+            characteristics = analyze_video_sample(
+                landmarks_sequence, video.fps, video.frame_count
+            )
+            params = auto_tune_parameters(characteristics, quality_preset)
+            params = _apply_expert_param_overrides(params, expert_params)
+
+            # Calculate countermovement threshold (FPS-adjusted)
+            # Base: +0.015 at 30fps (POSITIVE for downward motion in normalized coords)
+            countermovement_threshold = 0.015 * (30.0 / video.fps)
+            if expert_params.countermovement_threshold is not None:
+                countermovement_threshold = expert_params.countermovement_threshold
+
+            # Show parameters if verbose
+            if verbose:
+                _print_auto_tuned_params(
+                    video, quality_preset, params, countermovement_threshold
+                )
+
+            # Apply smoothing
+            smoothed_landmarks = _smooth_landmark_sequence(landmarks_sequence, params)
+
+            # Extract foot positions
+            vertical_positions, tracking_method = _extract_positions_from_landmarks(
+                smoothed_landmarks
+            )
+
+            # Detect CMJ phases
+            click.echo("Detecting CMJ phases...", err=True)
+            phases = detect_cmj_phases(
+                vertical_positions,
+                video.fps,
+                velocity_threshold=params.velocity_threshold,
+                countermovement_threshold=countermovement_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:
+                click.echo("Error: Could not detect CMJ phases", err=True)
+                sys.exit(1)
+
+            standing_end, lowest_point, takeoff_frame, landing_frame = phases
+
+            # Calculate metrics
+            click.echo("Calculating metrics...", err=True)
+
+            # Compute SIGNED velocities for CMJ metrics (need direction info)
+            from .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,
+            )
+
+            # Output results
+            _output_results(metrics, json_output)
+
+            # Generate debug video if requested
+            if output:
+                _create_debug_video(output, video, frames, smoothed_landmarks, metrics)
+
+    except Exception as e:
+        click.echo(f"Error processing video: {e}", err=True)
+        import traceback
+
+        traceback.print_exc()
+        sys.exit(1)
+
+
+def _create_debug_video(
+    output: str,
+    video: VideoProcessor,
+    frames: list,
+    smoothed_landmarks: list,
+    metrics: CMJMetrics,
+) -> None:
+    """Generate debug video with overlays.
+
+    Args:
+        output: Output video path
+        video: Video processor
+        frames: Video frames
+        smoothed_landmarks: Smoothed landmarks
+        metrics: Calculated metrics
+    """
+    click.echo(f"Generating debug video: {output}", err=True)
+    if video.display_width != video.width or video.display_height != video.height:
+        click.echo(f"Source video encoded: {video.width}x{video.height}", err=True)
+        click.echo(
+            f"Output dimensions: {video.display_width}x{video.display_height} "
+            f"(respecting display aspect ratio)",
+            err=True,
+        )
+    else:
+        click.echo(
+            f"Output dimensions: {video.width}x{video.height} "
+            f"(matching source video aspect ratio)",
+            err=True,
+        )
+
+    with CMJDebugOverlayRenderer(
+        output,
+        video.width,
+        video.height,
+        video.display_width,
+        video.display_height,
+        video.fps,
+    ) as renderer:
+        render_bar: Any
+        with click.progressbar(
+            length=len(frames), label="Rendering frames"
+        ) as render_bar:
+            for i, frame in enumerate(frames):
+                annotated = renderer.render_frame(
+                    frame, smoothed_landmarks[i], i, metrics
+                )
+                renderer.write_frame(annotated)
+                render_bar.update(1)
+
+    click.echo(f"Debug video saved: {output}", err=True)
+
+
+def _output_results(metrics: Any, json_output: str | None) -> None:
+    """Output analysis results."""
+    results = metrics.to_dict()
+
+    # Output JSON
+    if json_output:
+        with open(json_output, "w") as f:
+            json.dump(results, f, indent=2)
+        click.echo(f"Metrics saved to: {json_output}", err=True)
+    else:
+        # Output to stdout
+        print(json.dumps(results, indent=2))
+
+    # Print summary
+    click.echo("\n" + "=" * 60, err=True)
+    click.echo("CMJ ANALYSIS RESULTS", err=True)
+    click.echo("=" * 60, err=True)
+    click.echo(f"Jump height: {metrics.jump_height:.3f} m", err=True)
+    click.echo(f"Flight time: {metrics.flight_time * 1000:.1f} ms", err=True)
+    click.echo(
+        f"Countermovement depth: {metrics.countermovement_depth:.3f} m", err=True
+    )
+    click.echo(
+        f"Eccentric duration: {metrics.eccentric_duration * 1000:.1f} ms", err=True
+    )
+    click.echo(
+        f"Concentric duration: {metrics.concentric_duration * 1000:.1f} ms", err=True
+    )
+    click.echo(
+        f"Total movement time: {metrics.total_movement_time * 1000:.1f} ms", err=True
+    )
+    click.echo(
+        f"Peak eccentric velocity: {abs(metrics.peak_eccentric_velocity):.3f} m/s (downward)",
+        err=True,
+    )
+    click.echo(
+        f"Peak concentric velocity: {metrics.peak_concentric_velocity:.3f} m/s (upward)",
+        err=True,
+    )
+    if metrics.transition_time is not None:
+        click.echo(
+            f"Transition time: {metrics.transition_time * 1000:.1f} ms", err=True
+        )
+    click.echo("=" * 60, err=True)