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

kinemotion/{drop_jump → dropjump}/api.py

@@ -8,11 +8,8 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    import numpy as np
     from numpy.typing import NDArray
 
-    from .analysis import ContactState
-
 from ..core.auto_tuning import (
     AnalysisParameters,
     QualityPreset,
@@ -51,19 +48,10 @@ from .analysis import (
     detect_ground_contact,
     find_contact_phases,
 )
-from .debug_overlay import DropJumpDebugOverlayRenderer
+from .debug_overlay import DebugOverlayRenderer
 from .kinematics import DropJumpMetrics, calculate_drop_jump_metrics
 from .metrics_validator import DropJumpMetricsValidator
 
-__all__ = [
-    "AnalysisOverrides",
-    "DropJumpVideoConfig",
-    "DropJumpVideoResult",
-    "process_dropjump_video",
-    "process_dropjump_video_from_config",
-    "process_dropjump_videos_bulk",
-]
-
 
 @dataclass
 class AnalysisOverrides:
@@ -102,33 +90,14 @@ class DropJumpVideoConfig:
     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_dropjump_video."""
-        return {
-            "video_path": self.video_path,
-            "quality": self.quality,
-            "output_video": self.output_video,
-            "json_output": self.json_output,
-            "drop_start_frame": self.drop_start_frame,
-            "overrides": self.overrides,
-            "detection_confidence": self.detection_confidence,
-            "tracking_confidence": self.tracking_confidence,
-            "verbose": self.verbose,
-            "timer": self.timer,
-            "pose_tracker": self.pose_tracker,
-        }
 
 
 def _assess_dropjump_quality(
-    vertical_positions: "NDArray[np.float64]",
-    visibilities: "NDArray[np.float64]",
-    contact_states: list["ContactState"],
+    vertical_positions: "NDArray",
+    visibilities: "NDArray",
+    contact_states: list,
     fps: float,
-) -> tuple[QualityAssessment, "NDArray[np.bool_]", bool, int]:
+) -> tuple:
     """Assess tracking quality and detect phases.
 
     Returns:
@@ -336,6 +305,7 @@ def _tune_and_smooth(
         characteristics = analyze_video_sample(landmarks_sequence, video_fps, frame_count)
         params = auto_tune_parameters(characteristics, quality_preset)
 
+        # Apply overrides if provided
         if overrides:
             params = apply_expert_overrides(
                 params,
@@ -344,6 +314,14 @@ def _tune_and_smooth(
                 overrides.min_contact_frames,
                 overrides.visibility_threshold,
             )
+        else:
+            params = apply_expert_overrides(
+                params,
+                None,
+                None,
+                None,
+                None,
+            )
 
     smoothed_landmarks = apply_smoothing(landmarks_sequence, params, verbose, timer)
 
@@ -462,13 +440,16 @@ def _generate_debug_video(
     timer = timer or NULL_TIMER
     debug_h, debug_w = frames[0].shape[:2]
 
-    # Calculate debug FPS: cap at 30 for high-fps videos, use step if frame-sparse
-    debug_fps = min(video_fps, 30.0)
+    if video_fps > 30:
+        debug_fps = video_fps / (video_fps / 30.0)
+    else:
+        debug_fps = video_fps
+
     if len(frames) < len(smoothed_landmarks):
         step = max(1, int(video_fps / 30.0))
         debug_fps = video_fps / step
 
-    def _render_frames(renderer: DropJumpDebugOverlayRenderer) -> None:
+    def _render_frames(renderer: DebugOverlayRenderer) -> None:
         for frame, idx in zip(frames, frame_indices, strict=True):
             annotated = renderer.render_frame(
                 frame,
@@ -480,7 +461,7 @@ def _generate_debug_video(
             )
             renderer.write_frame(annotated)
 
-    renderer_context = DropJumpDebugOverlayRenderer(
+    renderer_context = DebugOverlayRenderer(
         output_video,
         debug_w,
         debug_h,
@@ -630,23 +611,6 @@ def process_dropjump_video(
             return metrics
 
 
-def process_dropjump_video_from_config(
-    config: DropJumpVideoConfig,
-) -> DropJumpMetrics:
-    """Process a drop jump video using a configuration object.
-
-    This is a convenience wrapper around process_dropjump_video that
-    accepts a DropJumpVideoConfig instead of individual parameters.
-
-    Args:
-        config: Configuration object containing all analysis parameters
-
-    Returns:
-        DropJumpMetrics object containing analysis results
-    """
-    return process_dropjump_video(**config.to_kwargs())
-
-
 def process_dropjump_videos_bulk(
     configs: list[DropJumpVideoConfig],
     max_workers: int = 4,
@@ -673,8 +637,18 @@ def _process_dropjump_video_wrapper(config: DropJumpVideoConfig) -> DropJumpVide
     start_time = time.perf_counter()
 
     try:
-        # Use convenience wrapper to avoid parameter unpacking
-        metrics = process_dropjump_video_from_config(config)
+        metrics = process_dropjump_video(
+            video_path=config.video_path,
+            quality=config.quality,
+            output_video=config.output_video,
+            json_output=config.json_output,
+            drop_start_frame=config.drop_start_frame,
+            overrides=config.overrides,
+            detection_confidence=config.detection_confidence,
+            tracking_confidence=config.tracking_confidence,
+            verbose=False,
+        )
+
         processing_time = time.perf_counter() - start_time
 
         return DropJumpVideoResult(

kinemotion/{drop_jump → dropjump}/cli.py

@@ -5,17 +5,12 @@ import json
 import sys
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING
 
 import click
 
 from ..core.cli_utils import (
-    batch_processing_options,
     collect_video_files,
-    common_output_options,
     generate_batch_output_paths,
-    quality_option,
-    verbose_option,
 )
 from .api import (
     DropJumpVideoConfig,
@@ -24,9 +19,6 @@ from .api import (
     process_dropjump_videos_bulk,
 )
 
-if TYPE_CHECKING:
-    from .api import AnalysisOverrides
-
 
 @dataclass
 class AnalysisParameters:
@@ -43,10 +35,64 @@ class AnalysisParameters:
 
 @click.command(name="dropjump-analyze")
 @click.argument("video_path", nargs=-1, type=click.Path(exists=False), required=True)
-@common_output_options
-@quality_option
-@verbose_option
-@batch_processing_options
+@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(
     "--drop-start-frame",
@@ -179,34 +225,6 @@ def dropjump_analyze(  # NOSONAR(S107) - Click CLI requires individual
         )
 
 
-def _create_overrides_if_needed(params: AnalysisParameters) -> "AnalysisOverrides | None":
-    """Create AnalysisOverrides if any override parameters are set.
-
-    Args:
-        params: Expert parameters from CLI
-
-    Returns:
-        AnalysisOverrides if any relevant parameters are non-None, else None
-    """
-    from .api import AnalysisOverrides
-
-    if any(
-        [
-            params.smoothing_window is not None,
-            params.velocity_threshold is not None,
-            params.min_contact_frames is not None,
-            params.visibility_threshold is not None,
-        ]
-    ):
-        return AnalysisOverrides(
-            smoothing_window=params.smoothing_window,
-            velocity_threshold=params.velocity_threshold,
-            min_contact_frames=params.min_contact_frames,
-            visibility_threshold=params.visibility_threshold,
-        )
-    return None
-
-
 def _process_single(
     video_path: str,
     output: str | None,
@@ -219,7 +237,24 @@ def _process_single(
     click.echo(f"Analyzing video: {video_path}", err=True)
 
     try:
-        overrides = _create_overrides_if_needed(expert_params)
+        # Create AnalysisOverrides if any expert parameters are set
+        from .api import AnalysisOverrides
+
+        overrides = None
+        if any(
+            [
+                expert_params.smoothing_window is not None,
+                expert_params.velocity_threshold is not None,
+                expert_params.min_contact_frames is not None,
+                expert_params.visibility_threshold is not None,
+            ]
+        ):
+            overrides = AnalysisOverrides(
+                smoothing_window=expert_params.smoothing_window,
+                velocity_threshold=expert_params.velocity_threshold,
+                min_contact_frames=expert_params.min_contact_frames,
+                visibility_threshold=expert_params.visibility_threshold,
+            )
 
         # Call the API function (handles all processing logic)
         metrics = process_dropjump_video(
@@ -293,7 +328,24 @@ def _create_video_configs(
             video_file, output_dir, json_output_dir
         )
 
-        overrides = _create_overrides_if_needed(expert_params)
+        # Create AnalysisOverrides if any expert parameters are set
+        from .api import AnalysisOverrides
+
+        overrides = None
+        if any(
+            [
+                expert_params.smoothing_window is not None,
+                expert_params.velocity_threshold is not None,
+                expert_params.min_contact_frames is not None,
+                expert_params.visibility_threshold is not None,
+            ]
+        ):
+            overrides = AnalysisOverrides(
+                smoothing_window=expert_params.smoothing_window,
+                velocity_threshold=expert_params.velocity_threshold,
+                min_contact_frames=expert_params.min_contact_frames,
+                visibility_threshold=expert_params.visibility_threshold,
+            )
 
         config = DropJumpVideoConfig(
             video_path=video_file,
@@ -328,33 +380,35 @@ def _compute_batch_statistics(results: list[DropJumpVideoResult]) -> None:
     click.echo(f"Failed: {len(failed)}", err=True)
 
     if successful:
-        # Calculate average metrics from results with non-None values
-        gct_values = [
-            r.metrics.ground_contact_time * 1000
-            for r in successful
-            if r.metrics and r.metrics.ground_contact_time is not None
-        ]
-        flight_values = [
-            r.metrics.flight_time * 1000
-            for r in successful
-            if r.metrics and r.metrics.flight_time is not None
-        ]
-        jump_values = [
-            r.metrics.jump_height
-            for r in successful
-            if r.metrics and r.metrics.jump_height is not None
+        # Calculate average metrics
+        with_gct = [
+            r for r in successful if r.metrics and r.metrics.ground_contact_time is not None
         ]
-
-        if gct_values:
-            avg_gct = sum(gct_values) / len(gct_values)
+        with_flight = [r for r in successful if r.metrics and r.metrics.flight_time is not None]
+        with_jump = [r for r in successful if r.metrics and r.metrics.jump_height is not None]
+
+        if with_gct:
+            avg_gct = sum(
+                r.metrics.ground_contact_time * 1000
+                for r in with_gct
+                if r.metrics and r.metrics.ground_contact_time is not None
+            ) / len(with_gct)
             click.echo(f"\nAverage ground contact time: {avg_gct:.1f} ms", err=True)
 
-        if flight_values:
-            avg_flight = sum(flight_values) / len(flight_values)
+        if with_flight:
+            avg_flight = sum(
+                r.metrics.flight_time * 1000
+                for r in with_flight
+                if r.metrics and r.metrics.flight_time is not None
+            ) / len(with_flight)
             click.echo(f"Average flight time: {avg_flight:.1f} ms", err=True)
 
-        if jump_values:
-            avg_jump = sum(jump_values) / len(jump_values)
+        if with_jump:
+            avg_jump = sum(
+                r.metrics.jump_height
+                for r in with_jump
+                if r.metrics and r.metrics.jump_height is not None
+            ) / len(with_jump)
             click.echo(
                 f"Average jump height: {avg_jump:.3f} m ({avg_jump * 100:.1f} cm)",
                 err=True,
@@ -399,27 +453,38 @@ def _create_csv_row_from_result(result: DropJumpVideoResult) -> list[str]:
     processing_time = f"{result.processing_time:.2f}"
 
     if result.success and result.metrics:
-        metrics_data = [
+        return [
+            video_name,
             _format_time_metric(result.metrics.ground_contact_time),
             _format_time_metric(result.metrics.flight_time),
             _format_distance_metric(result.metrics.jump_height),
+            processing_time,
+            "Success",
+        ]
+    else:
+        return [
+            video_name,
+            "N/A",
+            "N/A",
+            "N/A",
+            processing_time,
+            f"Failed: {result.error}",
         ]
-        return [video_name, *metrics_data, processing_time, "Success"]
-
-    return [video_name, "N/A", "N/A", "N/A", processing_time, f"Failed: {result.error}"]
 
 
 def _write_csv_summary(
     csv_summary: str | None,
     results: list[DropJumpVideoResult],
+    successful: list[DropJumpVideoResult],
 ) -> None:
     """Write CSV summary of batch processing results.
 
     Args:
         csv_summary: Path to CSV output file
         results: All processing results
+        successful: Successful processing results
     """
-    if not csv_summary:
+    if not csv_summary or not successful:
         return
 
     click.echo(f"\nExporting CSV summary to: {csv_summary}", err=True)
@@ -493,6 +558,7 @@ def _process_batch(
     _compute_batch_statistics(results)
 
     # Export CSV summary if requested
-    _write_csv_summary(csv_summary, results)
+    successful = [r for r in results if r.success]
+    _write_csv_summary(csv_summary, results, successful)
 
     click.echo("\nBatch processing complete!", err=True)

kinemotion/dropjump/debug_overlay.py

@@ -0,0 +1,182 @@
+"""Debug overlay rendering for drop jump analysis."""
+
+import cv2
+import numpy as np
+
+from ..core.debug_overlay_utils import BaseDebugOverlayRenderer
+from ..core.pose import compute_center_of_mass
+from .analysis import ContactState, compute_average_foot_position
+from .kinematics import DropJumpMetrics
+
+
+class DebugOverlayRenderer(BaseDebugOverlayRenderer):
+    """Renders debug information on video frames."""
+
+    def _draw_com_visualization(
+        self,
+        frame: np.ndarray,
+        landmarks: dict[str, tuple[float, float, float]],
+        contact_state: ContactState,
+    ) -> None:
+        """Draw center of mass visualization on frame."""
+        com_x, com_y, _ = compute_center_of_mass(landmarks)
+        px = int(com_x * self.width)
+        py = int(com_y * self.height)
+
+        color = (0, 255, 0) if contact_state == ContactState.ON_GROUND else (0, 0, 255)
+        cv2.circle(frame, (px, py), 15, color, -1)
+        cv2.circle(frame, (px, py), 17, (255, 255, 255), 2)
+
+        # Draw hip midpoint reference
+        if "left_hip" in landmarks and "right_hip" in landmarks:
+            lh_x, lh_y, _ = landmarks["left_hip"]
+            rh_x, rh_y, _ = landmarks["right_hip"]
+            hip_x = int((lh_x + rh_x) / 2 * self.width)
+            hip_y = int((lh_y + rh_y) / 2 * self.height)
+            cv2.circle(frame, (hip_x, hip_y), 8, (255, 165, 0), -1)
+            cv2.line(frame, (hip_x, hip_y), (px, py), (255, 165, 0), 2)
+
+    def _draw_foot_visualization(
+        self,
+        frame: np.ndarray,
+        landmarks: dict[str, tuple[float, float, float]],
+        contact_state: ContactState,
+    ) -> None:
+        """Draw foot position visualization on frame."""
+        foot_x, foot_y = compute_average_foot_position(landmarks)
+        px = int(foot_x * self.width)
+        py = int(foot_y * self.height)
+
+        color = (0, 255, 0) if contact_state == ContactState.ON_GROUND else (0, 0, 255)
+        cv2.circle(frame, (px, py), 10, color, -1)
+
+        # Draw individual foot landmarks
+        foot_keys = ["left_ankle", "right_ankle", "left_heel", "right_heel"]
+        for key in foot_keys:
+            if key in landmarks:
+                x, y, vis = landmarks[key]
+                if vis > 0.5:
+                    lx = int(x * self.width)
+                    ly = int(y * self.height)
+                    cv2.circle(frame, (lx, ly), 5, (255, 255, 0), -1)
+
+    def _draw_phase_labels(
+        self,
+        frame: np.ndarray,
+        frame_idx: int,
+        metrics: DropJumpMetrics,
+    ) -> None:
+        """Draw phase labels (ground contact, flight, peak) on frame."""
+        y_offset = 110
+
+        # Ground contact phase
+        if (
+            metrics.contact_start_frame
+            and metrics.contact_end_frame
+            and metrics.contact_start_frame <= frame_idx <= metrics.contact_end_frame
+        ):
+            cv2.putText(
+                frame,
+                "GROUND CONTACT",
+                (10, y_offset),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                0.7,
+                (0, 255, 0),
+                2,
+            )
+            y_offset += 40
+
+        # Flight phase
+        if (
+            metrics.flight_start_frame
+            and metrics.flight_end_frame
+            and metrics.flight_start_frame <= frame_idx <= metrics.flight_end_frame
+        ):
+            cv2.putText(
+                frame,
+                "FLIGHT PHASE",
+                (10, y_offset),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                0.7,
+                (0, 0, 255),
+                2,
+            )
+            y_offset += 40
+
+        # Peak height
+        if metrics.peak_height_frame == frame_idx:
+            cv2.putText(
+                frame,
+                "PEAK HEIGHT",
+                (10, y_offset),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                0.7,
+                (255, 0, 255),
+                2,
+            )
+
+    def render_frame(
+        self,
+        frame: np.ndarray,
+        landmarks: dict[str, tuple[float, float, float]] | None,
+        contact_state: ContactState,
+        frame_idx: int,
+        metrics: DropJumpMetrics | None = None,
+        use_com: bool = False,
+    ) -> np.ndarray:
+        """
+        Render debug overlay on frame.
+
+        Args:
+            frame: Original video frame
+            landmarks: Pose landmarks for this frame
+            contact_state: Ground contact state
+            frame_idx: Current frame index
+            metrics: Drop-jump metrics (optional)
+            use_com: Whether to visualize CoM instead of feet (optional)
+
+        Returns:
+            Frame with debug overlay
+        """
+        with self.timer.measure("debug_video_copy"):
+            annotated = frame.copy()
+
+        def _draw_overlays() -> None:
+            # Draw landmarks
+            if landmarks:
+                if use_com:
+                    self._draw_com_visualization(annotated, landmarks, contact_state)
+                else:
+                    self._draw_foot_visualization(annotated, landmarks, contact_state)
+
+            # Draw contact state
+            state_color = (0, 255, 0) if contact_state == ContactState.ON_GROUND else (0, 0, 255)
+            cv2.putText(
+                annotated,
+                f"State: {contact_state.value}",
+                (10, 30),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                1,
+                state_color,
+                2,
+            )
+
+            # Draw frame number
+            cv2.putText(
+                annotated,
+                f"Frame: {frame_idx}",
+                (10, 70),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                0.7,
+                (255, 255, 255),
+                2,
+            )
+
+            # Draw phase labels
+            if metrics:
+                self._draw_phase_labels(annotated, frame_idx, metrics)
+
+        with self.timer.measure("debug_video_draw"):
+            _draw_overlays()
+
+        return annotated