kinemotion 0.17.0__py3-none-any.whl

kinemotion/cmj/joint_angles.py

@@ -0,0 +1,290 @@
+"""Joint angle calculations for triple extension analysis."""
+
+import math
+
+import numpy as np
+
+
+def calculate_angle_3_points(
+    point1: tuple[float, float],
+    point2: tuple[float, float],
+    point3: tuple[float, float],
+) -> float:
+    """
+    Calculate angle at point2 formed by three points.
+
+    Uses the law of cosines to find the angle at the middle point.
+
+    Args:
+        point1: First point (x, y) - e.g., foot
+        point2: Middle point (x, y) - e.g., knee (vertex of angle)
+        point3: Third point (x, y) - e.g., hip
+
+    Returns:
+        Angle in degrees (0-180)
+
+    Example:
+        >>> # Calculate knee angle
+        >>> ankle = (0.5, 0.8)
+        >>> knee = (0.5, 0.6)
+        >>> hip = (0.5, 0.4)
+        >>> angle = calculate_angle_3_points(ankle, knee, hip)
+        >>> # angle ≈ 180 (straight leg)
+    """
+    # Convert points to numpy arrays
+    p1 = np.array(point1)
+    p2 = np.array(point2)
+    p3 = np.array(point3)
+
+    # Calculate vectors from point2 to point1 and point3
+    v1 = p1 - p2
+    v2 = p3 - p2
+
+    # Calculate angle using dot product
+    # cos(angle) = (v1 · v2) / (|v1| * |v2|)
+    dot_product = np.dot(v1, v2)
+    magnitude1 = np.linalg.norm(v1)
+    magnitude2 = np.linalg.norm(v2)
+
+    # Avoid division by zero
+    if magnitude1 < 1e-9 or magnitude2 < 1e-9:
+        return 0.0
+
+    # Calculate angle in radians, then convert to degrees
+    cos_angle = dot_product / (magnitude1 * magnitude2)
+
+    # Clamp to [-1, 1] to avoid numerical errors with arccos
+    cos_angle = np.clip(cos_angle, -1.0, 1.0)
+
+    angle_rad = math.acos(cos_angle)
+    angle_deg = math.degrees(angle_rad)
+
+    return float(angle_deg)
+
+
+def calculate_ankle_angle(
+    landmarks: dict[str, tuple[float, float, float]], side: str = "right"
+) -> float | None:
+    """
+    Calculate ankle angle (dorsiflexion/plantarflexion).
+
+    Angle formed by: heel -> ankle -> knee
+    - 90° = neutral (foot perpendicular to shin)
+    - < 90° = dorsiflexion (toes up)
+    - > 90° = plantarflexion (toes down)
+
+    Args:
+        landmarks: Pose landmarks dictionary
+        side: Which side to measure ("left" or "right")
+
+    Returns:
+        Ankle angle in degrees, or None if landmarks not available
+    """
+    prefix = "left_" if side == "left" else "right_"
+
+    heel_key = f"{prefix}heel"
+    ankle_key = f"{prefix}ankle"
+    knee_key = f"{prefix}knee"
+
+    # Check visibility threshold
+    if heel_key not in landmarks or landmarks[heel_key][2] < 0.3:
+        return None
+    if ankle_key not in landmarks or landmarks[ankle_key][2] < 0.3:
+        return None
+    if knee_key not in landmarks or landmarks[knee_key][2] < 0.3:
+        return None
+
+    heel = (landmarks[heel_key][0], landmarks[heel_key][1])
+    ankle = (landmarks[ankle_key][0], landmarks[ankle_key][1])
+    knee = (landmarks[knee_key][0], landmarks[knee_key][1])
+
+    return calculate_angle_3_points(heel, ankle, knee)
+
+
+def calculate_knee_angle(
+    landmarks: dict[str, tuple[float, float, float]], side: str = "right"
+) -> float | None:
+    """
+    Calculate knee angle (flexion/extension).
+
+    Angle formed by: ankle -> knee -> hip
+    - 180° = full extension (straight leg)
+    - 90° = 90° flexion (deep squat)
+    - 0° = full flexion (not physiologically possible)
+
+    Args:
+        landmarks: Pose landmarks dictionary
+        side: Which side to measure ("left" or "right")
+
+    Returns:
+        Knee angle in degrees, or None if landmarks not available
+    """
+    prefix = "left_" if side == "left" else "right_"
+
+    ankle_key = f"{prefix}ankle"
+    knee_key = f"{prefix}knee"
+    hip_key = f"{prefix}hip"
+
+    # Check visibility
+    if ankle_key not in landmarks or landmarks[ankle_key][2] < 0.3:
+        # Fallback: use foot_index if ankle not visible
+        foot_key = f"{prefix}foot_index"
+        if foot_key in landmarks and landmarks[foot_key][2] > 0.3:
+            ankle_key = foot_key
+        else:
+            return None
+
+    if knee_key not in landmarks or landmarks[knee_key][2] < 0.3:
+        return None
+    if hip_key not in landmarks or landmarks[hip_key][2] < 0.3:
+        return None
+
+    ankle = (landmarks[ankle_key][0], landmarks[ankle_key][1])
+    knee = (landmarks[knee_key][0], landmarks[knee_key][1])
+    hip = (landmarks[hip_key][0], landmarks[hip_key][1])
+
+    return calculate_angle_3_points(ankle, knee, hip)
+
+
+def calculate_hip_angle(
+    landmarks: dict[str, tuple[float, float, float]], side: str = "right"
+) -> float | None:
+    """
+    Calculate hip angle (flexion/extension).
+
+    Angle formed by: knee -> hip -> shoulder
+    - 180° = standing upright (trunk and thigh aligned)
+    - 90° = 90° hip flexion (torso perpendicular to thigh)
+    - < 90° = deep flexion (squat position)
+
+    Args:
+        landmarks: Pose landmarks dictionary
+        side: Which side to measure ("left" or "right")
+
+    Returns:
+        Hip angle in degrees, or None if landmarks not available
+    """
+    prefix = "left_" if side == "left" else "right_"
+
+    knee_key = f"{prefix}knee"
+    hip_key = f"{prefix}hip"
+    shoulder_key = f"{prefix}shoulder"
+
+    # Check visibility
+    if knee_key not in landmarks or landmarks[knee_key][2] < 0.3:
+        return None
+    if hip_key not in landmarks or landmarks[hip_key][2] < 0.3:
+        return None
+    if shoulder_key not in landmarks or landmarks[shoulder_key][2] < 0.3:
+        return None
+
+    knee = (landmarks[knee_key][0], landmarks[knee_key][1])
+    hip = (landmarks[hip_key][0], landmarks[hip_key][1])
+    shoulder = (landmarks[shoulder_key][0], landmarks[shoulder_key][1])
+
+    return calculate_angle_3_points(knee, hip, shoulder)
+
+
+def calculate_trunk_tilt(
+    landmarks: dict[str, tuple[float, float, float]], side: str = "right"
+) -> float | None:
+    """
+    Calculate trunk tilt angle relative to vertical.
+
+    Measures forward/backward lean of the torso.
+    - 0° = perfectly vertical
+    - Positive = leaning forward
+    - Negative = leaning backward
+
+    Args:
+        landmarks: Pose landmarks dictionary
+        side: Which side to measure ("left" or "right")
+
+    Returns:
+        Trunk tilt angle in degrees, or None if landmarks not available
+    """
+    prefix = "left_" if side == "left" else "right_"
+
+    hip_key = f"{prefix}hip"
+    shoulder_key = f"{prefix}shoulder"
+
+    # Check visibility
+    if hip_key not in landmarks or landmarks[hip_key][2] < 0.3:
+        return None
+    if shoulder_key not in landmarks or landmarks[shoulder_key][2] < 0.3:
+        return None
+
+    hip = np.array([landmarks[hip_key][0], landmarks[hip_key][1]])
+    shoulder = np.array([landmarks[shoulder_key][0], landmarks[shoulder_key][1]])
+
+    # Vector from hip to shoulder
+    trunk_vector = shoulder - hip
+
+    # Vertical reference (in normalized coords, vertical is along y-axis)
+    # Negative y direction is up in frame coordinates
+    vertical = np.array([0, -1])
+
+    # Calculate angle from vertical
+    dot_product = np.dot(trunk_vector, vertical)
+    magnitude_trunk = np.linalg.norm(trunk_vector)
+
+    if magnitude_trunk < 1e-9:
+        return None
+
+    cos_angle = dot_product / magnitude_trunk
+    cos_angle = np.clip(cos_angle, -1.0, 1.0)
+
+    angle_rad = math.acos(cos_angle)
+    angle_deg = math.degrees(angle_rad)
+
+    # Determine if leaning forward or backward based on x-component
+    if trunk_vector[0] > 0:  # Shoulder to the right of hip = leaning forward
+        return float(angle_deg)
+    else:
+        return float(-angle_deg)
+
+
+def calculate_triple_extension(
+    landmarks: dict[str, tuple[float, float, float]], side: str = "right"
+) -> dict[str, float | None] | None:
+    """
+    Calculate all three joint angles for triple extension analysis.
+
+    Triple extension refers to simultaneous extension of ankle, knee, and hip joints
+    during the propulsive phase of jumping. This is a key indicator of proper technique.
+
+    NOTE: In side-view videos, ankle/knee may have low visibility from MediaPipe.
+    Returns partial results with None for unavailable angles.
+
+    Args:
+        landmarks: Pose landmarks dictionary
+        side: Which side to measure ("left" or "right")
+
+    Returns:
+        Dictionary with angle measurements:
+        - ankle_angle: Ankle angle or None
+        - knee_angle: Knee angle or None
+        - hip_angle: Hip angle or None
+        - trunk_tilt: Trunk lean angle or None
+        Returns None if NO angles can be calculated
+
+    Example:
+        >>> angles = calculate_triple_extension(landmarks, side="right")
+        >>> if angles and angles['knee_angle']:
+        ...     print(f"Knee: {angles['knee_angle']:.0f}°")
+    """
+    ankle = calculate_ankle_angle(landmarks, side)
+    knee = calculate_knee_angle(landmarks, side)
+    hip = calculate_hip_angle(landmarks, side)
+    trunk = calculate_trunk_tilt(landmarks, side)
+
+    # Return results even if some are None (at least trunk should be available)
+    if ankle is None and knee is None and hip is None and trunk is None:
+        return None  # No angles available at all
+
+    return {
+        "ankle_angle": ankle,
+        "knee_angle": knee,
+        "hip_angle": hip,
+        "trunk_tilt": trunk,
+    }

kinemotion/cmj/kinematics.py

@@ -0,0 +1,191 @@
+"""Counter Movement Jump (CMJ) metrics calculation."""
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+
+
+@dataclass
+class CMJMetrics:
+    """Metrics for a counter movement jump analysis.
+
+    Attributes:
+        jump_height: Maximum jump height in meters
+        flight_time: Time spent in the air in seconds
+        countermovement_depth: Vertical distance traveled during eccentric phase in meters
+        eccentric_duration: Time from countermovement start to lowest point in seconds
+        concentric_duration: Time from lowest point to takeoff in seconds
+        total_movement_time: Total time from countermovement start to takeoff in seconds
+        peak_eccentric_velocity: Maximum downward velocity during countermovement in m/s
+        peak_concentric_velocity: Maximum upward velocity during propulsion in m/s
+        transition_time: Duration at lowest point (amortization phase) in seconds
+        standing_start_frame: Frame where standing phase ends (countermovement begins)
+        lowest_point_frame: Frame at lowest point of countermovement
+        takeoff_frame: Frame where athlete leaves ground
+        landing_frame: Frame where athlete lands
+        video_fps: Frames per second of the analyzed video
+        tracking_method: Method used for tracking ("foot" or "com")
+    """
+
+    jump_height: float
+    flight_time: float
+    countermovement_depth: float
+    eccentric_duration: float
+    concentric_duration: float
+    total_movement_time: float
+    peak_eccentric_velocity: float
+    peak_concentric_velocity: float
+    transition_time: float | None
+    standing_start_frame: float | None
+    lowest_point_frame: float
+    takeoff_frame: float
+    landing_frame: float
+    video_fps: float
+    tracking_method: str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert metrics to JSON-serializable dictionary.
+
+        Returns:
+            Dictionary with all metrics, converting NumPy types to Python types.
+        """
+        return {
+            "jump_height_m": float(self.jump_height),
+            "flight_time_s": float(self.flight_time),
+            "countermovement_depth_m": float(self.countermovement_depth),
+            "eccentric_duration_s": float(self.eccentric_duration),
+            "concentric_duration_s": float(self.concentric_duration),
+            "total_movement_time_s": float(self.total_movement_time),
+            "peak_eccentric_velocity_m_s": float(self.peak_eccentric_velocity),
+            "peak_concentric_velocity_m_s": float(self.peak_concentric_velocity),
+            "transition_time_s": (
+                float(self.transition_time)
+                if self.transition_time is not None
+                else None
+            ),
+            "standing_start_frame": (
+                float(self.standing_start_frame)
+                if self.standing_start_frame is not None
+                else None
+            ),
+            "lowest_point_frame": float(self.lowest_point_frame),
+            "takeoff_frame": float(self.takeoff_frame),
+            "landing_frame": float(self.landing_frame),
+            "video_fps": float(self.video_fps),
+            "tracking_method": self.tracking_method,
+        }
+
+
+def calculate_cmj_metrics(
+    positions: np.ndarray,
+    velocities: np.ndarray,
+    standing_start_frame: float | None,
+    lowest_point_frame: float,
+    takeoff_frame: float,
+    landing_frame: float,
+    fps: float,
+    tracking_method: str = "foot",
+) -> CMJMetrics:
+    """Calculate all CMJ metrics from detected phases.
+
+    Args:
+        positions: Array of vertical positions (normalized coordinates)
+        velocities: Array of vertical velocities
+        standing_start_frame: Frame where countermovement begins (fractional)
+        lowest_point_frame: Frame at lowest point (fractional)
+        takeoff_frame: Frame at takeoff (fractional)
+        landing_frame: Frame at landing (fractional)
+        fps: Video frames per second
+        tracking_method: Tracking method used ("foot" or "com")
+
+    Returns:
+        CMJMetrics object with all calculated metrics.
+    """
+    # Calculate flight time from takeoff to landing
+    flight_time = (landing_frame - takeoff_frame) / fps
+
+    # Calculate jump height from flight time using kinematic formula
+    # h = g * t^2 / 8 (where t is total flight time)
+    g = 9.81  # gravity in m/s^2
+    jump_height = (g * flight_time**2) / 8
+
+    # Calculate countermovement depth
+    if standing_start_frame is not None:
+        standing_position = positions[int(standing_start_frame)]
+    else:
+        # Use position at start of recording if standing not detected
+        standing_position = positions[0]
+
+    lowest_position = positions[int(lowest_point_frame)]
+    countermovement_depth = abs(standing_position - lowest_position)
+
+    # Calculate phase durations
+    if standing_start_frame is not None:
+        eccentric_duration = (lowest_point_frame - standing_start_frame) / fps
+        total_movement_time = (takeoff_frame - standing_start_frame) / fps
+    else:
+        # If no standing phase detected, measure from start
+        eccentric_duration = lowest_point_frame / fps
+        total_movement_time = takeoff_frame / fps
+
+    concentric_duration = (takeoff_frame - lowest_point_frame) / fps
+
+    # Calculate peak velocities
+    # Eccentric phase: negative velocities (downward)
+    if standing_start_frame is not None:
+        eccentric_start_idx = int(standing_start_frame)
+    else:
+        eccentric_start_idx = 0
+
+    eccentric_end_idx = int(lowest_point_frame)
+    eccentric_velocities = velocities[eccentric_start_idx:eccentric_end_idx]
+
+    if len(eccentric_velocities) > 0:
+        # Peak eccentric velocity is most negative value
+        peak_eccentric_velocity = float(np.min(eccentric_velocities))
+    else:
+        peak_eccentric_velocity = 0.0
+
+    # Concentric phase: positive velocities (upward)
+    concentric_start_idx = int(lowest_point_frame)
+    concentric_end_idx = int(takeoff_frame)
+    concentric_velocities = velocities[concentric_start_idx:concentric_end_idx]
+
+    if len(concentric_velocities) > 0:
+        peak_concentric_velocity = float(np.max(concentric_velocities))
+    else:
+        peak_concentric_velocity = 0.0
+
+    # Estimate transition time (amortization phase)
+    # Look for period around lowest point where velocity is near zero
+    transition_threshold = 0.005  # Very low velocity threshold
+    search_window = int(fps * 0.1)  # Search within ±100ms
+
+    transition_start_idx = max(0, int(lowest_point_frame) - search_window)
+    transition_end_idx = min(len(velocities), int(lowest_point_frame) + search_window)
+
+    transition_frames = 0
+    for i in range(transition_start_idx, transition_end_idx):
+        if abs(velocities[i]) < transition_threshold:
+            transition_frames += 1
+
+    transition_time = transition_frames / fps if transition_frames > 0 else None
+
+    return CMJMetrics(
+        jump_height=jump_height,
+        flight_time=flight_time,
+        countermovement_depth=countermovement_depth,
+        eccentric_duration=eccentric_duration,
+        concentric_duration=concentric_duration,
+        total_movement_time=total_movement_time,
+        peak_eccentric_velocity=peak_eccentric_velocity,
+        peak_concentric_velocity=peak_concentric_velocity,
+        transition_time=transition_time,
+        standing_start_frame=standing_start_frame,
+        lowest_point_frame=lowest_point_frame,
+        takeoff_frame=takeoff_frame,
+        landing_frame=landing_frame,
+        video_fps=fps,
+        tracking_method=tracking_method,
+    )

kinemotion/core/__init__.py

@@ -0,0 +1,40 @@
+"""Core functionality shared across all jump analysis types."""
+
+from .filtering import (
+    adaptive_smooth_window,
+    bilateral_temporal_filter,
+    detect_outliers_median,
+    detect_outliers_ransac,
+    reject_outliers,
+    remove_outliers,
+)
+from .pose import PoseTracker, compute_center_of_mass
+from .smoothing import (
+    compute_acceleration_from_derivative,
+    compute_velocity,
+    compute_velocity_from_derivative,
+    smooth_landmarks,
+    smooth_landmarks_advanced,
+)
+from .video_io import VideoProcessor
+
+__all__ = [
+    # Pose tracking
+    "PoseTracker",
+    "compute_center_of_mass",
+    # Smoothing
+    "smooth_landmarks",
+    "smooth_landmarks_advanced",
+    "compute_velocity",
+    "compute_velocity_from_derivative",
+    "compute_acceleration_from_derivative",
+    # Filtering
+    "detect_outliers_ransac",
+    "detect_outliers_median",
+    "remove_outliers",
+    "reject_outliers",
+    "adaptive_smooth_window",
+    "bilateral_temporal_filter",
+    # Video I/O
+    "VideoProcessor",
+]