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

kinemotion/core/overlay_constants.py

@@ -1,61 +0,0 @@
-"""Shared constants and type aliases for overlay renderers."""
-
-from typing import Any
-
-# Type aliases for overlay rendering
-Color = tuple[int, int, int]
-Landmark = tuple[float, float, float]
-LandmarkDict = dict[str, Landmark]
-CodecAttemptLog = list[dict[str, Any]]
-
-# Visibility thresholds
-VISIBILITY_THRESHOLD = 0.2
-VISIBILITY_THRESHOLD_HIGH = 0.3
-FOOT_VISIBILITY_THRESHOLD = 0.5
-
-# Video encoding constants
-MAX_VIDEO_DIMENSION = 720
-CODECS_TO_TRY = ["avc1", "mp4v"]
-FFMPEG_PRESET = "fast"
-FFMPEG_CRF = "23"
-FFMPEG_PIX_FMT = "yuv420p"
-
-# Common colors (BGR format for OpenCV)
-GREEN = (0, 255, 0)
-RED = (0, 0, 255)
-WHITE = (255, 255, 255)
-BLACK = (0, 0, 0)
-GRAY = (128, 128, 128)
-CYAN = (255, 255, 0)
-ORANGE = (0, 165, 255)
-
-# Joint colors for triple extension
-ANKLE_COLOR = (0, 255, 255)  # Cyan
-KNEE_COLOR = (255, 100, 100)  # Light blue
-HIP_COLOR = (100, 255, 100)  # Light green
-TRUNK_COLOR = (100, 100, 255)  # Light red
-
-# Angle thresholds
-FULL_EXTENSION_ANGLE = 160
-DEEP_FLEXION_ANGLE = 90
-
-# Circle sizes
-JOINT_CIRCLE_RADIUS = 6
-JOINT_OUTLINE_RADIUS = 8
-COM_CIRCLE_RADIUS = 15
-COM_OUTLINE_RADIUS = 17
-HIP_MARKER_RADIUS = 8
-FOOT_CIRCLE_RADIUS = 10
-FOOT_LANDMARK_RADIUS = 5
-ANGLE_ARC_RADIUS = 25
-NOSE_CIRCLE_RADIUS = 8
-NOSE_OUTLINE_RADIUS = 10
-
-# Box positioning
-JOINT_ANGLES_BOX_X_OFFSET = 180
-JOINT_ANGLES_BOX_HEIGHT = 150
-METRICS_BOX_WIDTH = 320
-
-# Phase label positioning
-PHASE_LABEL_START_Y = 110
-PHASE_LABEL_LINE_HEIGHT = 40

kinemotion/core/video_analysis_base.py

@@ -1,132 +0,0 @@
-"""Base types and patterns for video analysis APIs.
-
-This module defines shared infrastructure for jump-type-specific analysis modules.
-Each jump type (CMJ, Drop Jump, etc.) has its own analysis algorithms, but they
-share common patterns for:
-
-1. Configuration (VideoConfig dataclass)
-2. Results (VideoResult dataclass)
-3. Parameter overrides (AnalysisOverrides dataclass)
-4. Bulk processing utilities
-
-To add a new jump type:
-1. Create a new module: src/kinemotion/{jump_type}/
-2. Implement analysis algorithms in {jump_type}/analysis.py
-3. Use the patterns in this module for API structure
-4. Import process_videos_bulk_generic from pipeline_utils for bulk processing
-"""
-
-from abc import ABC, abstractmethod
-from dataclasses import dataclass
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from ..auto_tuning import QualityPreset
-    from ..timing import Timer
-
-__all__ = [
-    "AnalysisOverrides",
-    "VideoAnalysisConfig",
-    "VideoAnalysisResult",
-    "JumpAnalysisPipeline",
-]
-
-
-@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.
-
-    Common overrides across all jump types:
-    - smoothing_window: Number of frames for Savitzky-Golay smoothing
-    - velocity_threshold: Threshold for phase detection
-    - min_contact_frames: Minimum frames for ground contact
-    - visibility_threshold: Minimum landmark visibility (0-1)
-    """
-
-    smoothing_window: int | None = None
-    velocity_threshold: float | None = None
-    min_contact_frames: int | None = None
-    visibility_threshold: float | None = None
-
-
-@dataclass
-class VideoAnalysisConfig:
-    """Base configuration for video analysis.
-
-    Subclasses should add jump-type-specific fields (e.g., drop_start_frame
-    for Drop Jump, or additional overrides for CMJ).
-    """
-
-    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
-    verbose: bool = False
-    timer: "Timer | None" = None
-
-
-@dataclass
-class VideoAnalysisResult:
-    """Base result for video analysis.
-
-    Subclasses should add jump-type-specific fields.
-    """
-
-    video_path: str
-    success: bool
-    metrics: object | None = None  # Will be CMJMetrics, DropJumpMetrics, etc.
-    error: str | None = None
-    processing_time: float = 0.0
-
-
-class JumpAnalysisPipeline(ABC):
-    """Abstract base class for jump analysis pipelines.
-
-    Defines the common structure for processing jump videos. Each jump type
-    implements the specific analysis logic while following this pattern.
-
-    Example:
-        class CMJPipeline(JumpAnalysisPipeline):
-            def analyze(self) -> CMJMetrics:
-                # CMJ-specific analysis (backward search algorithm)
-                ...
-
-        class DropJumpPipeline(JumpAnalysisPipeline):
-            def analyze(self) -> DropJumpMetrics:
-                # Drop jump-specific analysis (forward search algorithm)
-                ...
-    """
-
-    def __init__(
-        self,
-        video_path: str,
-        quality_preset: "QualityPreset",
-        overrides: AnalysisOverrides | None,
-        timer: "Timer",
-    ) -> None:
-        """Initialize the analysis pipeline."""
-        self.video_path = video_path
-        self.quality_preset = quality_preset
-        self.overrides = overrides
-        self.timer = timer
-
-    @abstractmethod
-    def analyze(self) -> object:
-        """Run the jump-specific analysis algorithm.
-
-        Returns:
-            Metrics object with jump-type-specific results.
-        """
-        ...
-
-    def validate_video_exists(self) -> None:
-        """Validate that the input video file exists."""
-        if not Path(self.video_path).exists():
-            raise FileNotFoundError(f"Video file not found: {self.video_path}")

kinemotion/countermovement_jump/debug_overlay.py

@@ -1,325 +0,0 @@
-"""Debug overlay rendering for CMJ analysis."""
-
-import cv2
-import numpy as np
-
-from ..core.debug_overlay_utils import BaseDebugOverlayRenderer
-from ..core.overlay_constants import (
-    ANGLE_ARC_RADIUS,
-    ANKLE_COLOR,
-    BLACK,
-    CYAN,
-    DEEP_FLEXION_ANGLE,
-    FOOT_LANDMARK_RADIUS,
-    FOOT_VISIBILITY_THRESHOLD,
-    FULL_EXTENSION_ANGLE,
-    GRAY,
-    GREEN,
-    HIP_COLOR,
-    JOINT_ANGLES_BOX_HEIGHT,
-    JOINT_ANGLES_BOX_X_OFFSET,
-    KNEE_COLOR,
-    METRICS_BOX_WIDTH,
-    ORANGE,
-    RED,
-    TRUNK_COLOR,
-    VISIBILITY_THRESHOLD_HIGH,
-    WHITE,
-    Color,
-    LandmarkDict,
-)
-from .analysis import CMJPhase
-from .joint_angles import calculate_triple_extension
-from .kinematics import CMJMetrics
-
-
-class CMJDebugOverlayRenderer(BaseDebugOverlayRenderer):
-    """Renders debug information on CMJ video frames."""
-
-    # Phase colors (BGR format)
-    PHASE_COLORS: dict[CMJPhase, Color] = {
-        CMJPhase.STANDING: (255, 200, 100),  # Light blue
-        CMJPhase.ECCENTRIC: (0, 165, 255),  # Orange
-        CMJPhase.TRANSITION: (255, 0, 255),  # Magenta/Purple
-        CMJPhase.CONCENTRIC: (0, 255, 0),  # Green
-        CMJPhase.FLIGHT: (0, 0, 255),  # Red
-        CMJPhase.LANDING: (255, 255, 255),  # White
-    }
-    DEFAULT_PHASE_COLOR: Color = GRAY
-
-    def _determine_phase(self, frame_idx: int, metrics: CMJMetrics) -> CMJPhase:
-        """Determine which phase the current frame is in."""
-        if metrics.standing_start_frame and frame_idx < metrics.standing_start_frame:
-            return CMJPhase.STANDING
-
-        if frame_idx < metrics.lowest_point_frame:
-            return CMJPhase.ECCENTRIC
-
-        # Brief transition at lowest point (within 2 frames)
-        if abs(frame_idx - metrics.lowest_point_frame) < 2:
-            return CMJPhase.TRANSITION
-
-        if frame_idx < metrics.takeoff_frame:
-            return CMJPhase.CONCENTRIC
-
-        if frame_idx < metrics.landing_frame:
-            return CMJPhase.FLIGHT
-
-        return CMJPhase.LANDING
-
-    def _get_phase_color(self, phase: CMJPhase) -> Color:
-        """Get color for each phase."""
-        return self.PHASE_COLORS.get(phase, self.DEFAULT_PHASE_COLOR)
-
-    def _get_triple_extension_angles(
-        self, landmarks: LandmarkDict
-    ) -> tuple[dict[str, float | None], str] | None:
-        """Get triple extension angles, trying right side first then left.
-
-        Returns tuple of (angles_dict, side_used) or None if unavailable.
-        """
-        for side in ["right", "left"]:
-            angles = calculate_triple_extension(landmarks, side=side)
-            if angles is not None:
-                return angles, side
-        return None
-
-    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_joint_angles(
-        self, frame: np.ndarray, landmarks: LandmarkDict, phase_color: Color
-    ) -> None:
-        """Draw joint angles for triple extension analysis.
-
-        Args:
-            frame: Frame to draw on (modified in place)
-            landmarks: Pose landmarks
-            phase_color: Current phase color
-        """
-        result = self._get_triple_extension_angles(landmarks)
-        if result is None:
-            return
-
-        angles, side_used = result
-
-        # Position for angle text display (right side of frame)
-        text_x = self.width - JOINT_ANGLES_BOX_X_OFFSET
-        text_y = 100
-        box_height = JOINT_ANGLES_BOX_HEIGHT
-
-        # Draw background box
-        self._draw_info_box(
-            frame,
-            (text_x - 10, text_y - 30),
-            (self.width - 10, text_y + box_height),
-            phase_color,
-        )
-
-        # Title
-        cv2.putText(
-            frame,
-            "TRIPLE EXTENSION",
-            (text_x, text_y - 5),
-            cv2.FONT_HERSHEY_SIMPLEX,
-            0.5,
-            WHITE,
-            1,
-        )
-
-        # Angle display configuration: (label, angle_key, color, joint_suffix)
-        angle_config = [
-            ("Ankle", "ankle_angle", ANKLE_COLOR, "ankle"),
-            ("Knee", "knee_angle", KNEE_COLOR, "knee"),
-            ("Hip", "hip_angle", HIP_COLOR, "hip"),
-            ("Trunk", "trunk_tilt", TRUNK_COLOR, None),
-        ]
-
-        y_offset = text_y + 25
-        for label, angle_key, color, joint_suffix in angle_config:
-            angle = angles.get(angle_key)
-
-            # Draw text
-            if angle is not None:
-                text = f"{label}: {angle:.0f}"
-                text_color = color
-            else:
-                text = f"{label}: N/A"
-                text_color = GRAY
-
-            cv2.putText(
-                frame, text, (text_x, y_offset), cv2.FONT_HERSHEY_SIMPLEX, 0.5, text_color, 2
-            )
-            y_offset += 30
-
-            # Draw arc at joint if angle available and has associated joint
-            if angle is not None and joint_suffix is not None:
-                self._draw_angle_arc(frame, landmarks, f"{side_used}_{joint_suffix}", angle)
-
-    def _get_extension_color(self, angle: float) -> Color:
-        """Get color based on joint extension angle.
-
-        Green for extended (>160 deg), red for flexed (<90 deg), orange for moderate.
-        """
-        if angle > FULL_EXTENSION_ANGLE:
-            return GREEN
-        if angle < DEEP_FLEXION_ANGLE:
-            return RED
-        return ORANGE
-
-    def _draw_angle_arc(
-        self, frame: np.ndarray, landmarks: LandmarkDict, joint_key: str, angle: float
-    ) -> None:
-        """Draw a circle at a joint to visualize the angle.
-
-        Args:
-            frame: Frame to draw on (modified in place)
-            landmarks: Pose landmarks
-            joint_key: Key of the joint landmark
-            angle: Angle value in degrees
-        """
-        if joint_key not in landmarks:
-            return
-        landmark = landmarks[joint_key]
-        if not self._is_visible(landmark, VISIBILITY_THRESHOLD_HIGH):
-            return
-
-        point = self._landmark_to_pixel(landmark)
-        arc_color = self._get_extension_color(angle)
-        cv2.circle(frame, point, ANGLE_ARC_RADIUS, arc_color, 2)
-
-    def _draw_foot_landmarks(
-        self, frame: np.ndarray, landmarks: LandmarkDict, phase_color: Color
-    ) -> None:
-        """Draw foot landmarks and average position."""
-        foot_keys = ["left_ankle", "right_ankle", "left_heel", "right_heel"]
-        foot_positions: list[tuple[int, int]] = []
-
-        for key in foot_keys:
-            if key not in landmarks:
-                continue
-            landmark = landmarks[key]
-            if landmark[2] > FOOT_VISIBILITY_THRESHOLD:
-                point = self._landmark_to_pixel(landmark)
-                foot_positions.append(point)
-                cv2.circle(frame, point, FOOT_LANDMARK_RADIUS, CYAN, -1)
-
-        # Draw average foot position with phase color
-        if foot_positions:
-            avg_x = int(np.mean([p[0] for p in foot_positions]))
-            avg_y = int(np.mean([p[1] for p in foot_positions]))
-            cv2.circle(frame, (avg_x, avg_y), 12, phase_color, -1)
-            cv2.circle(frame, (avg_x, avg_y), 14, WHITE, 2)
-
-    def _draw_phase_banner(
-        self, frame: np.ndarray, phase: CMJPhase | None, phase_color: Color
-    ) -> None:
-        """Draw phase indicator banner."""
-        if phase is None:
-            return
-
-        phase_text = f"Phase: {phase.value.upper()}"
-        text_size = cv2.getTextSize(phase_text, cv2.FONT_HERSHEY_SIMPLEX, 1, 2)[0]
-        cv2.rectangle(frame, (5, 5), (text_size[0] + 15, 45), phase_color, -1)
-        cv2.putText(frame, phase_text, (10, 35), cv2.FONT_HERSHEY_SIMPLEX, 1, BLACK, 2)
-
-    def _draw_key_frame_markers(
-        self, frame: np.ndarray, frame_idx: int, metrics: CMJMetrics
-    ) -> None:
-        """Draw markers for key frames (standing start, lowest, takeoff, landing)."""
-        # Key frame definitions: (frame_value, label)
-        key_frames: list[tuple[float | None, str]] = [
-            (metrics.standing_start_frame, "COUNTERMOVEMENT START"),
-            (metrics.lowest_point_frame, "LOWEST POINT"),
-            (metrics.takeoff_frame, "TAKEOFF"),
-            (metrics.landing_frame, "LANDING"),
-        ]
-
-        y_offset = 120
-        for key_frame, label in key_frames:
-            if key_frame is not None and frame_idx == int(key_frame):
-                cv2.putText(frame, label, (10, y_offset), cv2.FONT_HERSHEY_SIMPLEX, 0.7, CYAN, 2)
-                y_offset += 35
-
-    def _draw_metrics_summary(
-        self, frame: np.ndarray, frame_idx: int, metrics: CMJMetrics
-    ) -> None:
-        """Draw metrics summary in bottom right (last 30 frames after landing)."""
-        if frame_idx < int(metrics.landing_frame):
-            return
-
-        metrics_text = [
-            f"Jump Height: {metrics.jump_height:.3f}m",
-            f"Flight Time: {metrics.flight_time * 1000:.0f}ms",
-            f"CM Depth: {metrics.countermovement_depth:.3f}m",
-            f"Ecc Duration: {metrics.eccentric_duration * 1000:.0f}ms",
-            f"Con Duration: {metrics.concentric_duration * 1000:.0f}ms",
-        ]
-
-        # 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,
-        frame_idx: int,
-        metrics: CMJMetrics | None = None,
-    ) -> np.ndarray:
-        """Render debug overlay on frame.
-
-        Args:
-            frame: Original video frame
-            landmarks: Pose landmarks for this frame
-            frame_idx: Current frame index
-            metrics: CMJ metrics (optional)
-
-        Returns:
-            Frame with debug overlay
-        """
-        annotated = frame.copy()
-
-        # Determine current phase and color
-        phase: CMJPhase | None = None
-        phase_color: Color = WHITE
-        if metrics:
-            phase = self._determine_phase(frame_idx, metrics)
-            phase_color = self._get_phase_color(phase)
-
-        # Draw skeleton and joint visualization if landmarks available
-        if landmarks:
-            self._draw_skeleton(annotated, landmarks)
-            self._draw_joint_angles(annotated, landmarks, phase_color)
-            self._draw_foot_landmarks(annotated, landmarks, phase_color)
-
-        # Draw phase indicator and frame number
-        self._draw_phase_banner(annotated, phase, phase_color)
-        cv2.putText(
-            annotated, f"Frame: {frame_idx}", (10, 80), cv2.FONT_HERSHEY_SIMPLEX, 0.7, WHITE, 2
-        )
-
-        # Draw key frame markers and metrics summary
-        if metrics:
-            self._draw_key_frame_markers(annotated, frame_idx, metrics)
-            self._draw_metrics_summary(annotated, frame_idx, metrics)
-
-        return annotated