kinemotion 0.76.3__py3-none-any.whl → 1.0.0__py3-none-any.whl

kinemotion/squat_jump/api.py

@@ -1,610 +0,0 @@
-"""Public API for SJ (Squat Jump) video analysis."""
-
-import json
-import time
-from collections.abc import Callable
-from dataclasses import dataclass
-from pathlib import Path
-
-import numpy as np
-from numpy.typing import NDArray
-
-from ..core.auto_tuning import (
-    AnalysisParameters,
-    QualityPreset,
-    analyze_video_sample,
-    auto_tune_parameters,
-)
-from ..core.experimental import experimental
-from ..core.filtering import reject_outliers
-from ..core.metadata import (
-    AlgorithmConfig,
-    DetectionConfig,
-    ProcessingInfo,
-    ResultMetadata,
-    SmoothingConfig,
-    VideoInfo,
-    create_timestamp,
-    get_kinemotion_version,
-)
-from ..core.pipeline_utils import (
-    apply_expert_overrides,
-    apply_smoothing,
-    convert_timer_to_stage_names,
-    determine_confidence_levels,
-    extract_vertical_positions,
-    parse_quality_preset,
-    print_verbose_parameters,
-    process_all_frames,
-    process_videos_bulk_generic,
-)
-from ..core.pose import MediaPipePoseTracker
-from ..core.quality import QualityAssessment, assess_jump_quality
-from ..core.timing import PerformanceTimer, Timer
-from ..core.validation import ValidationResult
-from ..core.video_io import VideoProcessor
-from .analysis import detect_sj_phases
-from .debug_overlay import SquatJumpDebugOverlayRenderer
-from .kinematics import SJMetrics, calculate_sj_metrics
-from .metrics_validator import SJMetricsValidator
-
-
-@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.
-    """
-
-    smoothing_window: int | None = None
-    velocity_threshold: float | None = None
-    min_contact_frames: int | None = None
-    visibility_threshold: float | None = None
-
-
-def _generate_debug_video(
-    output_video: str,
-    frames: list[NDArray[np.uint8]],
-    frame_indices: list[int],
-    smoothed_landmarks: list,
-    metrics: SJMetrics,
-    video_fps: float,
-    timer: Timer,
-    verbose: bool,
-) -> None:
-    """Generate debug video with SJ analysis overlay."""
-    if verbose:
-        print(f"Generating debug video: {output_video}")
-
-    debug_h, debug_w = frames[0].shape[:2]
-    step = max(1, int(video_fps / 30.0))
-    debug_fps = video_fps / step
-
-    with timer.measure("debug_video_generation"):
-        with SquatJumpDebugOverlayRenderer(
-            output_video,
-            debug_w,
-            debug_h,
-            debug_w,
-            debug_h,
-            debug_fps,
-            timer=timer,
-        ) as renderer:
-            for frame, idx in zip(frames, frame_indices, strict=True):
-                annotated = renderer.render_frame(frame, smoothed_landmarks[idx], idx, metrics)
-                renderer.write_frame(annotated)
-
-    if verbose:
-        print(f"Debug video saved: {output_video}")
-
-
-def _save_metrics_to_json(
-    metrics: SJMetrics, json_output: str, timer: Timer, verbose: bool
-) -> None:
-    """Save metrics to JSON file."""
-    with timer.measure("json_serialization"):
-        output_path = Path(json_output)
-        metrics_dict = metrics.to_dict()
-        json_str = json.dumps(metrics_dict, indent=2)
-        output_path.write_text(json_str)
-
-    if verbose:
-        print(f"Metrics written to: {json_output}")
-
-
-def _print_timing_summary(start_time: float, timer: Timer, metrics: SJMetrics) -> None:
-    """Print verbose timing summary and metrics."""
-    total_time = time.perf_counter() - start_time
-    stage_times = convert_timer_to_stage_names(timer.get_metrics())
-
-    print("\n=== Timing Summary ===")
-    for stage, duration in stage_times.items():
-        percentage = (duration / total_time) * 100
-        dur_ms = duration * 1000
-        print(f"{stage:.<40} {dur_ms:>6.0f}ms ({percentage:>5.1f}%)")
-    total_ms = total_time * 1000
-    print(f"{'Total':.<40} {total_ms:>6.0f}ms (100.0%)")
-    print()
-
-    print(f"\nJump height: {metrics.jump_height:.3f}m")
-    print(f"Flight time: {metrics.flight_time * 1000:.1f}ms")
-    print(f"Squat hold duration: {metrics.squat_hold_duration * 1000:.1f}ms")
-    print(f"Concentric duration: {metrics.concentric_duration * 1000:.1f}ms")
-    if metrics.peak_power is not None:
-        print(f"Peak power: {metrics.peak_power:.0f}W")
-    if metrics.peak_force is not None:
-        print(f"Peak force: {metrics.peak_force:.0f}N")
-
-
-def _print_quality_warnings(quality_result: QualityAssessment, verbose: bool) -> None:
-    """Print quality warnings if present."""
-    if verbose and quality_result.warnings:
-        print("\n⚠️  Quality Warnings:")
-        for warning in quality_result.warnings:
-            print(f"  - {warning}")
-        print()
-
-
-def _print_validation_results(validation_result: ValidationResult, verbose: bool) -> None:
-    """Print validation issues if present."""
-    if verbose and validation_result.issues:
-        print("\n⚠️  Validation Results:")
-        for issue in validation_result.issues:
-            print(f"  [{issue.severity.value}] {issue.metric}: {issue.message}")
-
-
-def _create_algorithm_config(params: AnalysisParameters) -> AlgorithmConfig:
-    """Create algorithm configuration from parameters."""
-    return AlgorithmConfig(
-        detection_method="static_squat",
-        tracking_method="mediapipe_pose",
-        model_complexity=1,
-        smoothing=SmoothingConfig(
-            window_size=params.smoothing_window,
-            polynomial_order=params.polyorder,
-            use_bilateral_filter=params.bilateral_filter,
-            use_outlier_rejection=params.outlier_rejection,
-        ),
-        detection=DetectionConfig(
-            velocity_threshold=params.velocity_threshold,
-            min_contact_frames=params.min_contact_frames,
-            visibility_threshold=params.visibility_threshold,
-            use_curvature_refinement=params.use_curvature,
-        ),
-        drop_detection=None,
-    )
-
-
-def _create_video_info(video_path: str, video: VideoProcessor) -> VideoInfo:
-    """Create video information metadata."""
-    return VideoInfo(
-        source_path=video_path,
-        fps=video.fps,
-        width=video.width,
-        height=video.height,
-        duration_s=video.frame_count / video.fps,
-        frame_count=video.frame_count,
-        codec=video.codec,
-    )
-
-
-def _create_processing_info(
-    start_time: float, quality_preset: QualityPreset, timer: Timer
-) -> ProcessingInfo:
-    """Create processing information metadata."""
-    processing_time = time.perf_counter() - start_time
-    stage_times = convert_timer_to_stage_names(timer.get_metrics())
-
-    return ProcessingInfo(
-        version=get_kinemotion_version(),
-        timestamp=create_timestamp(),
-        quality_preset=quality_preset.value,
-        processing_time_s=processing_time,
-        timing_breakdown=stage_times,
-    )
-
-
-def _create_result_metadata(
-    quality_result: QualityAssessment,
-    video_info: VideoInfo,
-    processing_info: ProcessingInfo,
-    algorithm_config: AlgorithmConfig,
-) -> ResultMetadata:
-    """Create result metadata from components."""
-    return ResultMetadata(
-        quality=quality_result,
-        video=video_info,
-        processing=processing_info,
-        algorithm=algorithm_config,
-    )
-
-
-def _run_pose_tracking(
-    video: VideoProcessor,
-    quality_preset: QualityPreset,
-    detection_confidence: float | None,
-    tracking_confidence: float | None,
-    pose_tracker: "MediaPipePoseTracker | None",
-    verbose: bool,
-    timer: Timer,
-) -> tuple[list[NDArray[np.uint8]], list, list[int]]:
-    """Initialize tracker and process all frames."""
-    if verbose:
-        print(
-            f"Video: {video.width}x{video.height} @ {video.fps:.2f} fps, "
-            f"{video.frame_count} frames"
-        )
-
-    det_conf, track_conf = determine_confidence_levels(
-        quality_preset, detection_confidence, tracking_confidence
-    )
-
-    if pose_tracker is None:
-        if verbose:
-            print("Processing all frames with MediaPipe pose tracking...")
-        tracker = MediaPipePoseTracker(
-            min_detection_confidence=det_conf,
-            min_tracking_confidence=track_conf,
-            timer=timer,
-        )
-        should_close_tracker = True
-    else:
-        tracker = pose_tracker
-        should_close_tracker = False
-
-    return process_all_frames(video, tracker, verbose, timer, close_tracker=should_close_tracker)
-
-
-def _get_tuned_parameters(
-    video: VideoProcessor,
-    landmarks_sequence: list,
-    quality_preset: QualityPreset,
-    overrides: AnalysisOverrides | None,
-    verbose: bool,
-    timer: Timer,
-) -> AnalysisParameters:
-    """Analyze sample and tune parameters with expert overrides."""
-    with timer.measure("parameter_auto_tuning"):
-        characteristics = analyze_video_sample(landmarks_sequence, video.fps, video.frame_count)
-        params = auto_tune_parameters(characteristics, quality_preset)
-
-        if overrides:
-            params = apply_expert_overrides(
-                params,
-                overrides.smoothing_window,
-                overrides.velocity_threshold,
-                overrides.min_contact_frames,
-                overrides.visibility_threshold,
-            )
-
-        if verbose:
-            print_verbose_parameters(video, characteristics, quality_preset, params)
-
-    return params
-
-
-def _run_kinematic_analysis(
-    video: VideoProcessor,
-    smoothed_landmarks: list,
-    params: AnalysisParameters,
-    mass_kg: float | None,
-    verbose: bool,
-    timer: Timer,
-) -> tuple[SJMetrics, NDArray[np.float64], NDArray[np.float64]]:
-    """Extract positions, detect phases, and calculate metrics."""
-    if verbose:
-        print("Extracting vertical positions (Hip and Foot)...")
-    with timer.measure("vertical_position_extraction"):
-        vertical_positions, visibilities = extract_vertical_positions(
-            smoothed_landmarks, target="hip"
-        )
-        foot_positions, _ = extract_vertical_positions(smoothed_landmarks, target="foot")
-
-    if verbose:
-        print("Detecting SJ phases...")
-    with timer.measure("phase_detection"):
-        phases = detect_sj_phases(
-            vertical_positions,
-            video.fps,
-            window_length=params.smoothing_window,
-            polyorder=params.polyorder,
-        )
-
-    if phases is None:
-        raise ValueError("Could not detect SJ phases in video")
-
-    squat_hold_start, concentric_start, takeoff_frame, landing_frame = phases
-
-    if verbose:
-        print("Calculating metrics...")
-    with timer.measure("metrics_calculation"):
-        metrics = calculate_sj_metrics(
-            vertical_positions,
-            foot_positions,
-            squat_hold_start,
-            concentric_start,
-            takeoff_frame,
-            landing_frame,
-            video.fps,
-            mass_kg=mass_kg,
-            tracking_method="hip_hybrid",
-        )
-
-    return metrics, vertical_positions, visibilities
-
-
-def _finalize_analysis_results(
-    metrics: SJMetrics,
-    video: VideoProcessor,
-    video_path: str,
-    vertical_positions: NDArray[np.float64],
-    visibilities: NDArray[np.float64],
-    params: AnalysisParameters,
-    quality_preset: QualityPreset,
-    start_time: float,
-    timer: Timer,
-    verbose: bool,
-) -> None:
-    """Assess quality, validate metrics, and attach metadata."""
-    if verbose:
-        print("Assessing tracking quality...")
-    with timer.measure("quality_assessment"):
-        _, outlier_mask = reject_outliers(
-            vertical_positions,
-            use_ransac=True,
-            use_median=True,
-            interpolate=False,
-        )
-        quality_result = assess_jump_quality(
-            visibilities=visibilities,
-            positions=vertical_positions,
-            outlier_mask=outlier_mask,
-            fps=video.fps,
-            phases_detected=True,
-            phase_count=3,  # SQUAT_HOLD, CONCENTRIC, FLIGHT
-        )
-
-    _print_quality_warnings(quality_result, verbose)
-
-    with timer.measure("metrics_validation"):
-        validator = SJMetricsValidator()
-        validation_result = validator.validate(metrics.to_dict())  # type: ignore[arg-type]
-
-    algorithm_config = _create_algorithm_config(params)
-    video_info = _create_video_info(video_path, video)
-    processing_info = _create_processing_info(start_time, quality_preset, timer)
-    result_metadata = _create_result_metadata(
-        quality_result, video_info, processing_info, algorithm_config
-    )
-    metrics.result_metadata = result_metadata
-
-    _print_validation_results(validation_result, verbose)
-
-
-@dataclass
-class SJVideoConfig:
-    """Configuration for processing a single SJ video."""
-
-    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
-    mass_kg: 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_sj_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,
-            "mass_kg": self.mass_kg,
-            "verbose": self.verbose,
-            "timer": self.timer,
-            "pose_tracker": self.pose_tracker,
-        }
-
-
-@dataclass
-class SJVideoResult:
-    """Result of processing a single SJ video."""
-
-    video_path: str
-    success: bool
-    metrics: SJMetrics | None = None
-    error: str | None = None
-    processing_time: float = 0.0
-
-
-@experimental(
-    "Squat Jump analysis is new and awaiting validation studies. "
-    "Power/force calculations use validated Sayers regression but SJ-specific "
-    "phase detection may need refinement based on real-world data.",
-    since="0.74.0",
-)
-def process_sj_video(
-    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,
-    mass_kg: float | None = None,
-    verbose: bool = False,
-    timer: Timer | None = None,
-    pose_tracker: MediaPipePoseTracker | None = None,
-) -> SJMetrics:
-    """
-    Process a single SJ video and return metrics.
-
-    SJ (Squat Jump) is performed from a static squat position without
-    countermovement. Athletes start in a squat hold, then explode
-    upward to measure pure concentric power output.
-
-    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
-        overrides: Optional AnalysisOverrides with parameter fine-tuning
-        detection_confidence: Optional override for pose detection confidence
-        tracking_confidence: Optional override for pose tracking confidence
-        mass_kg: Athlete mass in kilograms (required for power calculations)
-        verbose: Print processing details
-        timer: Optional Timer for measuring operations
-        pose_tracker: Optional pre-initialized PoseTracker instance (reused if provided)
-
-    Returns:
-        SJMetrics object containing analysis results
-
-    Raises:
-        ValueError: If video cannot be processed or parameters are invalid
-        FileNotFoundError: If video file does not exist
-    """
-    if not Path(video_path).exists():
-        raise FileNotFoundError(f"Video file not found: {video_path}")
-
-    if mass_kg is None or mass_kg <= 0:
-        raise ValueError("Athlete mass (mass_kg) must be provided and greater than 0")
-
-    start_time = time.perf_counter()
-    timer = timer or PerformanceTimer()
-    quality_preset = parse_quality_preset(quality)
-
-    with timer.measure("video_initialization"):
-        with VideoProcessor(video_path, timer=timer) as video:
-            # 1. Pose Tracking
-            frames, landmarks_sequence, frame_indices = _run_pose_tracking(
-                video,
-                quality_preset,
-                detection_confidence,
-                tracking_confidence,
-                pose_tracker,
-                verbose,
-                timer,
-            )
-
-            # 2. Parameters & Smoothing
-            params = _get_tuned_parameters(
-                video, landmarks_sequence, quality_preset, overrides, verbose, timer
-            )
-            smoothed_landmarks = apply_smoothing(landmarks_sequence, params, verbose, timer)
-
-            # 3. Kinematic Analysis
-            metrics, vertical_positions, visibilities = _run_kinematic_analysis(
-                video, smoothed_landmarks, params, mass_kg, verbose, timer
-            )
-
-            # 4. Debug Video Generation (Optional)
-            if output_video:
-                _generate_debug_video(
-                    output_video,
-                    frames,
-                    frame_indices,
-                    smoothed_landmarks,
-                    metrics,
-                    video.fps,
-                    timer,
-                    verbose,
-                )
-
-            # 5. Finalization (Quality, Metadata, Validation)
-            _finalize_analysis_results(
-                metrics,
-                video,
-                video_path,
-                vertical_positions,
-                visibilities,
-                params,
-                quality_preset,
-                start_time,
-                timer,
-                verbose,
-            )
-
-            if json_output:
-                _save_metrics_to_json(metrics, json_output, timer, verbose)
-
-            if verbose:
-                _print_timing_summary(start_time, timer, metrics)
-
-            return metrics
-
-
-def process_sj_video_from_config(
-    config: SJVideoConfig,
-) -> SJMetrics:
-    """Process a SJ video using a configuration object.
-
-    This is a convenience wrapper around process_sj_video that
-    accepts a SJVideoConfig instead of individual parameters.
-
-    Args:
-        config: Configuration object containing all analysis parameters
-
-    Returns:
-        SJMetrics object containing analysis results
-    """
-    return process_sj_video(**config.to_kwargs())
-
-
-@experimental(
-    "Squat Jump analysis is new and awaiting validation studies. "
-    "Bulk processing uses parallel workers which may need tuning for large batches.",
-    since="0.74.0",
-)
-def process_sj_videos_bulk(
-    configs: list[SJVideoConfig],
-    max_workers: int = 4,
-    progress_callback: Callable[[SJVideoResult], None] | None = None,
-) -> list[SJVideoResult]:
-    """Process multiple SJ videos in parallel."""
-
-    def error_factory(video_path: str, error_msg: str) -> SJVideoResult:
-        return SJVideoResult(video_path=video_path, success=False, error=error_msg)
-
-    return process_videos_bulk_generic(
-        configs,
-        _process_sj_video_wrapper,
-        error_factory,
-        max_workers,
-        progress_callback,
-    )
-
-
-def _process_sj_video_wrapper(config: SJVideoConfig) -> SJVideoResult:
-    """Wrapper function for parallel SJ processing."""
-    start_time = time.perf_counter()
-
-    try:
-        # Use convenience wrapper to avoid parameter unpacking
-        metrics = process_sj_video_from_config(config)
-        processing_time = time.perf_counter() - start_time
-
-        return SJVideoResult(
-            video_path=config.video_path,
-            success=True,
-            metrics=metrics,
-            processing_time=processing_time,
-        )
-
-    except Exception as e:
-        processing_time = time.perf_counter() - start_time
-
-        return SJVideoResult(
-            video_path=config.video_path,
-            success=False,
-            error=str(e),
-            processing_time=processing_time,
-        )