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

kinemotion/drop_jump/debug_overlay.py

@@ -1,241 +0,0 @@
-"""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

kinemotion/squat_jump/__init__.py

@@ -1,5 +0,0 @@
-"""Squat Jump (SJ) analysis module."""
-
-from .kinematics import SJMetrics
-
-__all__ = ["SJMetrics"]

kinemotion/squat_jump/analysis.py

@@ -1,377 +0,0 @@
-"""Phase detection logic for Squat Jump (SJ) analysis."""
-
-from enum import Enum
-
-import numpy as np
-from scipy.signal import savgol_filter
-
-from ..core.types import FloatArray
-
-
-class SJPhase(Enum):
-    """Phases of a squat jump."""
-
-    SQUAT_HOLD = "squat_hold"
-    CONCENTRIC = "concentric"
-    FLIGHT = "flight"
-    LANDING = "landing"
-    UNKNOWN = "unknown"
-
-
-def detect_sj_phases(
-    positions: FloatArray,
-    fps: float,
-    velocity_threshold: float = 0.1,
-    window_length: int = 5,
-    polyorder: int = 2,
-) -> tuple[int, int, int, int] | None:
-    """Detect phases in a squat jump video.
-
-    Squat Jump phase detection follows this progression:
-    1. Squat hold - static squat position
-    2. Concentric - upward movement from squat
-    3. Takeoff - feet leave ground
-    4. Flight - in the air
-    5. Landing - feet contact ground
-
-    Args:
-        positions: 1D array of vertical positions (normalized coordinates)
-        fps: Video frames per second
-        velocity_threshold: Threshold for detecting flight phase (m/s)
-        window_length: Window size for velocity smoothing
-        polyorder: Polynomial order for smoothing
-
-    Returns:
-        Tuple of (squat_hold_start, concentric_start, takeoff_frame, landing_frame)
-        or None if phases cannot be detected
-    """
-    if len(positions) < 20:  # Minimum viable sequence length
-        return None
-
-    # Ensure window length is appropriate for derivative calculations
-    if window_length % 2 == 0:
-        window_length += 1
-
-    # Step 1: Detect squat hold start
-    squat_hold_start = _detect_squat_start(
-        positions,
-        fps,
-        velocity_threshold=velocity_threshold,
-        window_length=window_length,
-        polyorder=polyorder,
-    )
-
-    if squat_hold_start is None:
-        # If no squat hold detected, start from reasonable beginning
-        squat_hold_start = len(positions) // 4
-
-    # Step 2: Compute signed velocities for phase detection
-    if len(positions) < window_length:
-        # Fallback for short sequences
-        velocities = np.diff(positions, prepend=positions[0])
-    else:
-        velocities = savgol_filter(
-            positions, window_length, polyorder, deriv=1, delta=1.0, mode="interp"
-        )
-
-    # Step 3: Detect takeoff (this marks the start of concentric phase)
-    takeoff_frame = _detect_takeoff(
-        positions, velocities, fps, velocity_threshold=velocity_threshold
-    )
-
-    if takeoff_frame is None:
-        return None
-
-    # Concentric start begins when upward movement starts after squat hold
-    # This is just before takeoff when velocity becomes significantly negative
-    concentric_start = takeoff_frame
-    # Look backward from takeoff to find where concentric phase truly begins
-    for i in range(takeoff_frame - 1, max(squat_hold_start, 0), -1):
-        if velocities[i] <= -velocity_threshold * 0.5:  # Start of upward movement
-            concentric_start = i
-            break
-
-    # Step 4: Detect landing
-    landing_frame = _detect_landing(
-        positions,
-        velocities,
-        fps,
-        velocity_threshold=velocity_threshold,
-        min_flight_frames=5,
-        landing_search_window_s=0.5,
-        window_length=window_length,
-        polyorder=polyorder,
-    )
-
-    if landing_frame is None:
-        # Fallback: estimate landing from peak height + typical flight time
-        # takeoff_frame is guaranteed to be an int here (we returned earlier if None)
-        peak_search_start = takeoff_frame
-        peak_search_end = min(len(positions), takeoff_frame + int(fps * 1.0))
-        if peak_search_end > peak_search_start:
-            flight_positions = positions[peak_search_start:peak_search_end]
-            peak_idx = int(np.argmin(flight_positions))
-            peak_frame = peak_search_start + peak_idx
-            # Estimate landing as 0.3s after peak (typical SJ flight time)
-            landing_frame = peak_frame + int(fps * 0.3)
-        else:
-            return None
-
-    # Validate the detected phases
-    if landing_frame <= takeoff_frame or takeoff_frame <= squat_hold_start:
-        # Invalid phase sequence
-        return None
-
-    # Return all detected phases
-    return (squat_hold_start, concentric_start, takeoff_frame, landing_frame)
-
-
-def _detect_squat_start(
-    positions: FloatArray,
-    fps: float,
-    velocity_threshold: float = 0.1,
-    min_hold_duration: float = 0.15,
-    min_search_frame: int = 20,
-    window_length: int = 5,
-    polyorder: int = 2,
-) -> int | None:
-    """Detect start of squat hold phase.
-
-    Squat hold is detected when the athlete maintains a relatively stable
-    position with low velocity for a minimum duration.
-
-    Args:
-        positions: 1D array of vertical positions (normalized coordinates)
-        fps: Video frames per second
-        velocity_threshold: Maximum velocity to consider stationary (m/s)
-        min_hold_duration: Minimum duration to maintain stable position (seconds)
-        min_search_frame: Minimum frame to start searching (avoid initial settling)
-        window_length: Window size for velocity smoothing
-        polyorder: Polynomial order for smoothing
-
-    Returns:
-        Frame index where squat hold begins, or None if not detected
-    """
-    if len(positions) < min_search_frame + 10:
-        return None
-
-    # Compute velocity to detect stationary periods
-    if len(positions) < window_length:
-        velocities = np.abs(np.diff(positions, prepend=positions[0]))
-    else:
-        if window_length % 2 == 0:
-            window_length += 1
-        velocities = np.abs(
-            savgol_filter(positions, window_length, polyorder, deriv=1, delta=1.0, mode="interp")
-        )
-
-    # Search for stable period with low velocity
-    min_hold_frames = int(min_hold_duration * fps)
-    start_search = min_search_frame
-    end_search = len(positions) - min_hold_frames
-
-    # Look for consecutive frames with velocity below threshold
-    for i in range(start_search, end_search):
-        # Check if we have a stable period of sufficient duration
-        stable_period = velocities[i : i + min_hold_frames]
-        if np.all(stable_period <= velocity_threshold):
-            # Found a stable period - return start of this period
-            return i
-
-    return None
-
-
-def _find_takeoff_threshold_crossing(
-    velocities: FloatArray,
-    search_start: int,
-    search_end: int,
-    velocity_threshold: float,
-    min_duration_frames: int,
-) -> int | None:
-    """Find first frame where velocity exceeds threshold for minimum duration."""
-    above_threshold = velocities[search_start:search_end] <= -velocity_threshold
-    if not np.any(above_threshold):
-        return None
-
-    threshold_indices = np.nonzero(above_threshold)[0]
-    for idx in threshold_indices:
-        if idx + min_duration_frames < len(above_threshold):
-            if np.all(above_threshold[idx : idx + min_duration_frames]):
-                return search_start + idx
-    return None
-
-
-def _detect_takeoff(
-    positions: FloatArray,
-    velocities: FloatArray,
-    fps: float,
-    velocity_threshold: float = 0.1,
-    min_duration_frames: int = 5,
-    search_window_s: float = 0.3,
-) -> int | None:
-    """Detect takeoff frame in squat jump.
-
-    Takeoff occurs at peak upward velocity during the concentric phase.
-    For SJ, this is simply the maximum negative velocity after squat hold
-    before the upward movement.
-
-    Args:
-        positions: 1D array of vertical positions (normalized coordinates)
-        velocities: 1D array of SIGNED vertical velocities (negative = upward)
-        fps: Video frames per second
-        velocity_threshold: Minimum velocity threshold for takeoff (m/s)
-        min_duration_frames: Minimum frames above threshold to confirm takeoff
-        search_window_s: Time window to search for takeoff after squat hold (seconds)
-
-    Returns:
-        Frame index where takeoff occurs, or None if not detected
-    """
-    if len(positions) == 0 or len(velocities) == 0:
-        return None
-
-    # Find squat start to determine where to begin search
-    squat_start = _detect_squat_start(positions, fps)
-    if squat_start is None:
-        # If no squat start detected, start from reasonable middle point
-        squat_start = len(positions) // 3
-
-    # Search for takeoff after squat start
-    search_start = squat_start
-    search_end = min(len(velocities), int(squat_start + search_window_s * fps))
-
-    if search_end <= search_start:
-        return None
-
-    # Focus on concentric phase where velocity becomes negative (upward)
-    concentric_velocities = velocities[search_start:search_end]
-
-    # Find the most negative velocity (peak upward velocity = takeoff)
-    takeoff_idx = int(np.argmin(concentric_velocities))
-    takeoff_frame = search_start + takeoff_idx
-
-    # Verify velocity exceeds threshold
-    if velocities[takeoff_frame] > -velocity_threshold:
-        # Velocity not high enough - actual takeoff may be later
-        # Look for frames where velocity exceeds threshold with duration filter
-        return _find_takeoff_threshold_crossing(
-            velocities, search_start, search_end, velocity_threshold, min_duration_frames
-        )
-
-    return takeoff_frame if velocities[takeoff_frame] <= -velocity_threshold else None
-
-
-def _detect_impact_landing(
-    accelerations: FloatArray,
-    search_start: int,
-    search_end: int,
-) -> int | None:
-    """Detect landing by finding the maximum acceleration spike."""
-    landing_accelerations = accelerations[search_start:search_end]
-    if len(landing_accelerations) == 0:
-        return None
-
-    # Find maximum acceleration spike (impact)
-    landing_idx = int(np.argmax(landing_accelerations))
-    return search_start + landing_idx
-
-
-def _refine_landing_by_velocity(
-    velocities: FloatArray,
-    landing_frame: int,
-) -> int:
-    """Refine landing frame by looking for positive (downward) velocity."""
-    if landing_frame < len(velocities) and velocities[landing_frame] < 0:
-        # Velocity still upward - landing might not be detected yet
-        # Look ahead for where velocity becomes positive
-        for i in range(landing_frame, min(landing_frame + 10, len(velocities))):
-            if velocities[i] >= 0:
-                return i
-    return landing_frame
-
-
-def _detect_landing(
-    positions: FloatArray,
-    velocities: FloatArray,
-    fps: float,
-    velocity_threshold: float = 0.1,
-    min_flight_frames: int = 5,
-    landing_search_window_s: float = 0.5,
-    window_length: int = 5,
-    polyorder: int = 2,
-) -> int | None:
-    """Detect landing frame in squat jump.
-
-    Landing occurs after peak height when feet contact the ground.
-    Similar to CMJ - find position peak, then detect maximum deceleration
-    which corresponds to impact.
-
-    Args:
-        positions: 1D array of vertical positions (normalized coordinates)
-        velocities: 1D array of SIGNED vertical velocities (negative = up, positive = down)
-        fps: Video frames per second
-        velocity_threshold: Maximum velocity threshold for landing detection
-        min_flight_frames: Minimum frames in flight before landing
-        landing_search_window_s: Time window to search for landing after peak (seconds)
-        window_length: Window size for velocity smoothing
-        polyorder: Polynomial order for smoothing
-
-    Returns:
-        Frame index where landing occurs, or None if not detected
-    """
-    if len(positions) == 0 or len(velocities) == 0:
-        return None
-
-    # Find takeoff first (needed to determine where to start peak search)
-    takeoff_frame = _detect_takeoff(
-        positions, velocities, fps, velocity_threshold, 5, landing_search_window_s
-    )
-    if takeoff_frame is None:
-        return None
-
-    # Find peak height after takeoff
-    search_start = takeoff_frame
-    search_duration = int(fps * 0.7)  # Search next 0.7 seconds for peak
-    search_end = min(len(positions), search_start + search_duration)
-
-    if search_end <= search_start:
-        return None
-
-    # Find peak height (minimum position value in normalized coords = highest point)
-    flight_positions = positions[search_start:search_end]
-    peak_frame = search_start + int(np.argmin(flight_positions))
-
-    # After peak, look for landing using impact detection
-    landing_search_start = peak_frame + min_flight_frames
-    landing_search_end = min(
-        len(positions),
-        landing_search_start + int(landing_search_window_s * fps),
-    )
-
-    if landing_search_end <= landing_search_start:
-        return None
-
-    # Compute accelerations for impact detection
-    if len(positions) >= 5:
-        landing_window = window_length
-        if landing_window % 2 == 0:
-            landing_window += 1
-        # Use polyorder for smoothing (must be at least 2 for deriv=2)
-        eff_polyorder = max(2, polyorder)
-        accelerations = np.abs(
-            savgol_filter(
-                positions, landing_window, eff_polyorder, deriv=2, delta=1.0, mode="interp"
-            )
-        )
-    else:
-        # Fallback for short sequences
-        velocities_abs = np.abs(velocities)
-        accelerations = np.abs(np.diff(velocities_abs, prepend=velocities_abs[0]))
-
-    # Find impact: maximum positive acceleration (deceleration spike)
-    landing_frame = _detect_impact_landing(accelerations, landing_search_start, landing_search_end)
-
-    if landing_frame is None:
-        return None
-
-    # Additional verification: velocity should be positive (downward) at landing
-    return _refine_landing_by_velocity(velocities, landing_frame)