kinemotion 0.71.0__py3-none-any.whl → 0.72.0__py3-none-any.whl

kinemotion/{dropjump → dj}/api.py

@@ -48,10 +48,18 @@ from .analysis import (
     detect_ground_contact,
     find_contact_phases,
 )
-from .debug_overlay import DebugOverlayRenderer
+from .debug_overlay import DropJumpDebugOverlayRenderer
 from .kinematics import DropJumpMetrics, calculate_drop_jump_metrics
 from .metrics_validator import DropJumpMetricsValidator
 
+__all__ = [
+    "AnalysisOverrides",
+    "DropJumpVideoConfig",
+    "DropJumpVideoResult",
+    "process_dropjump_video",
+    "process_dropjump_videos_bulk",
+]
+
 
 @dataclass
 class AnalysisOverrides:
@@ -305,7 +313,6 @@ 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,
@@ -314,14 +321,6 @@ 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)
 
@@ -440,16 +439,13 @@ def _generate_debug_video(
     timer = timer or NULL_TIMER
     debug_h, debug_w = frames[0].shape[:2]
 
-    if video_fps > 30:
-        debug_fps = video_fps / (video_fps / 30.0)
-    else:
-        debug_fps = video_fps
-
+    # Calculate debug FPS: cap at 30 for high-fps videos, use step if frame-sparse
+    debug_fps = min(video_fps, 30.0)
     if len(frames) < len(smoothed_landmarks):
         step = max(1, int(video_fps / 30.0))
         debug_fps = video_fps / step
 
-    def _render_frames(renderer: DebugOverlayRenderer) -> None:
+    def _render_frames(renderer: DropJumpDebugOverlayRenderer) -> None:
         for frame, idx in zip(frames, frame_indices, strict=True):
             annotated = renderer.render_frame(
                 frame,
@@ -461,7 +457,7 @@ def _generate_debug_video(
             )
             renderer.write_frame(annotated)
 
-    renderer_context = DebugOverlayRenderer(
+    renderer_context = DropJumpDebugOverlayRenderer(
         output_video,
         debug_w,
         debug_h,

kinemotion/{dropjump → dj}/cli.py

@@ -5,6 +5,7 @@ import json
 import sys
 from dataclasses import dataclass
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import click
 
@@ -19,6 +20,9 @@ from .api import (
     process_dropjump_videos_bulk,
 )
 
+if TYPE_CHECKING:
+    from .api import AnalysisOverrides
+
 
 @dataclass
 class AnalysisParameters:
@@ -225,6 +229,34 @@ 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,
@@ -237,24 +269,7 @@ def _process_single(
     click.echo(f"Analyzing video: {video_path}", err=True)
 
     try:
-        # 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,
-            )
+        overrides = _create_overrides_if_needed(expert_params)
 
         # Call the API function (handles all processing logic)
         metrics = process_dropjump_video(
@@ -328,24 +343,7 @@ def _create_video_configs(
             video_file, output_dir, json_output_dir
         )
 
-        # 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,
-            )
+        overrides = _create_overrides_if_needed(expert_params)
 
         config = DropJumpVideoConfig(
             video_path=video_file,
@@ -380,35 +378,33 @@ def _compute_batch_statistics(results: list[DropJumpVideoResult]) -> None:
     click.echo(f"Failed: {len(failed)}", err=True)
 
     if successful:
-        # Calculate average metrics
-        with_gct = [
-            r for r in successful if r.metrics and r.metrics.ground_contact_time is not None
+        # 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
         ]
-        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)
+        jump_values = [
+            r.metrics.jump_height
+            for r in successful
+            if r.metrics and r.metrics.jump_height is not None
+        ]
+
+        if gct_values:
+            avg_gct = sum(gct_values) / len(gct_values)
             click.echo(f"\nAverage ground contact time: {avg_gct:.1f} ms", err=True)
 
-        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)
+        if flight_values:
+            avg_flight = sum(flight_values) / len(flight_values)
             click.echo(f"Average flight time: {avg_flight:.1f} ms", err=True)
 
-        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)
+        if jump_values:
+            avg_jump = sum(jump_values) / len(jump_values)
             click.echo(
                 f"Average jump height: {avg_jump:.3f} m ({avg_jump * 100:.1f} cm)",
                 err=True,
@@ -453,38 +449,27 @@ def _create_csv_row_from_result(result: DropJumpVideoResult) -> list[str]:
     processing_time = f"{result.processing_time:.2f}"
 
     if result.success and result.metrics:
-        return [
-            video_name,
+        metrics_data = [
             _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 or not successful:
+    if not csv_summary:
         return
 
     click.echo(f"\nExporting CSV summary to: {csv_summary}", err=True)
@@ -558,7 +543,6 @@ def _process_batch(
     _compute_batch_statistics(results)
 
     # Export CSV summary if requested
-    successful = [r for r in results if r.success]
-    _write_csv_summary(csv_summary, results, successful)
+    _write_csv_summary(csv_summary, results)
 
     click.echo("\nBatch processing complete!", err=True)

kinemotion/dj/debug_overlay.py

@@ -0,0 +1,241 @@
+"""Debug overlay rendering for drop jump analysis."""
+
+import cv2
+import numpy as np
+
+from ..core.debug_overlay_utils import BaseDebugOverlayRenderer
+from ..core.overlay_constants import (
+    BLACK,
+    COM_CIRCLE_RADIUS,
+    COM_OUTLINE_RADIUS,
+    CYAN,
+    FOOT_CIRCLE_RADIUS,
+    FOOT_LANDMARK_RADIUS,
+    FOOT_VISIBILITY_THRESHOLD,
+    GREEN,
+    HIP_MARKER_RADIUS,
+    METRICS_BOX_WIDTH,
+    ORANGE,
+    PHASE_LABEL_LINE_HEIGHT,
+    PHASE_LABEL_START_Y,
+    RED,
+    WHITE,
+    Color,
+    LandmarkDict,
+)
+from ..core.pose import compute_center_of_mass
+from .analysis import ContactState, compute_average_foot_position
+from .kinematics import DropJumpMetrics
+
+
+class DropJumpDebugOverlayRenderer(BaseDebugOverlayRenderer):
+    """Renders debug information on video frames."""
+
+    def _get_contact_state_color(self, contact_state: ContactState) -> Color:
+        """Get color based on ground contact state."""
+        return GREEN if contact_state == ContactState.ON_GROUND else RED
+
+    def _draw_com_visualization(
+        self,
+        frame: np.ndarray,
+        landmarks: LandmarkDict,
+        contact_state: ContactState,
+    ) -> None:
+        """Draw center of mass visualization on frame."""
+        com_x, com_y, _ = compute_center_of_mass(landmarks)
+        px, py = self._normalize_to_pixels(com_x, com_y)
+
+        color = self._get_contact_state_color(contact_state)
+        cv2.circle(frame, (px, py), COM_CIRCLE_RADIUS, color, -1)
+        cv2.circle(frame, (px, py), COM_OUTLINE_RADIUS, WHITE, 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, hip_y = self._normalize_to_pixels((lh_x + rh_x) / 2, (lh_y + rh_y) / 2)
+            cv2.circle(frame, (hip_x, hip_y), HIP_MARKER_RADIUS, ORANGE, -1)
+            cv2.line(frame, (hip_x, hip_y), (px, py), ORANGE, 2)
+
+    def _draw_foot_visualization(
+        self,
+        frame: np.ndarray,
+        landmarks: LandmarkDict,
+        contact_state: ContactState,
+    ) -> None:
+        """Draw foot position visualization on frame."""
+        foot_x, foot_y = compute_average_foot_position(landmarks)
+        px, py = self._normalize_to_pixels(foot_x, foot_y)
+
+        color = self._get_contact_state_color(contact_state)
+        cv2.circle(frame, (px, py), FOOT_CIRCLE_RADIUS, 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 > FOOT_VISIBILITY_THRESHOLD:
+                    lx, ly = self._normalize_to_pixels(x, y)
+                    cv2.circle(frame, (lx, ly), FOOT_LANDMARK_RADIUS, CYAN, -1)
+
+    def _draw_phase_labels(
+        self,
+        frame: np.ndarray,
+        frame_idx: int,
+        metrics: DropJumpMetrics,
+    ) -> None:
+        """Draw phase labels (ground contact, flight, peak) on frame."""
+        # Phase configurations: (start_frame, end_frame, label, color)
+        # For range-based phases (ground contact, flight)
+        range_phase_configs = [
+            (metrics.contact_start_frame, metrics.contact_end_frame, "GROUND CONTACT", GREEN),
+            (metrics.flight_start_frame, metrics.flight_end_frame, "FLIGHT PHASE", RED),
+        ]
+
+        y_offset = PHASE_LABEL_START_Y
+        for start_frame, end_frame, label, color in range_phase_configs:
+            if start_frame and end_frame and start_frame <= frame_idx <= end_frame:
+                cv2.putText(
+                    frame,
+                    label,
+                    (10, y_offset),
+                    cv2.FONT_HERSHEY_SIMPLEX,
+                    0.7,
+                    color,
+                    2,
+                )
+                y_offset += PHASE_LABEL_LINE_HEIGHT
+
+        # Single-frame indicator (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),  # Magenta
+                2,
+            )
+
+    def _draw_info_box(
+        self,
+        frame: np.ndarray,
+        top_left: tuple[int, int],
+        bottom_right: tuple[int, int],
+        border_color: Color,
+    ) -> None:
+        """Draw a filled box with border for displaying information."""
+        cv2.rectangle(frame, top_left, bottom_right, BLACK, -1)
+        cv2.rectangle(frame, top_left, bottom_right, border_color, 2)
+
+    def _draw_metrics_summary(
+        self, frame: np.ndarray, frame_idx: int, metrics: DropJumpMetrics
+    ) -> None:
+        """Draw metrics summary in bottom right after flight phase ends."""
+        if metrics.flight_end_frame is None or frame_idx < metrics.flight_end_frame:
+            return
+
+        # Build metrics text list
+        metrics_text: list[str] = []
+
+        if metrics.ground_contact_time is not None:
+            metrics_text.append(f"Contact Time: {metrics.ground_contact_time * 1000:.0f}ms")
+
+        if metrics.flight_time is not None:
+            metrics_text.append(f"Flight Time: {metrics.flight_time * 1000:.0f}ms")
+
+        if metrics.jump_height is not None:
+            metrics_text.append(f"Jump Height: {metrics.jump_height:.3f}m")
+
+        # Calculate RSI (Reactive Strength Index)
+        if (
+            metrics.jump_height is not None
+            and metrics.ground_contact_time is not None
+            and metrics.ground_contact_time > 0
+        ):
+            rsi = metrics.jump_height / metrics.ground_contact_time
+            metrics_text.append(f"RSI: {rsi:.2f}")
+
+        if not metrics_text:
+            return
+
+        # Calculate box dimensions
+        box_height = len(metrics_text) * 30 + 20
+        top_left = (self.width - METRICS_BOX_WIDTH, self.height - box_height - 10)
+        bottom_right = (self.width - 10, self.height - 10)
+
+        self._draw_info_box(frame, top_left, bottom_right, GREEN)
+
+        # Draw metrics text
+        text_x = self.width - METRICS_BOX_WIDTH + 10
+        text_y = self.height - box_height + 10
+        for text in metrics_text:
+            cv2.putText(frame, text, (text_x, text_y), cv2.FONT_HERSHEY_SIMPLEX, 0.6, WHITE, 1)
+            text_y += 30
+
+    def render_frame(
+        self,
+        frame: np.ndarray,
+        landmarks: LandmarkDict | 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()
+
+        with self.timer.measure("debug_video_draw"):
+            # Draw skeleton and landmarks
+            if landmarks:
+                self._draw_skeleton(annotated, 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 = self._get_contact_state_color(contact_state)
+            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,
+                WHITE,
+                2,
+            )
+
+            # Draw phase labels and metrics summary
+            if metrics:
+                self._draw_phase_labels(annotated, frame_idx, metrics)
+                self._draw_metrics_summary(annotated, frame_idx, metrics)
+
+        return annotated