kinemotion 0.75.0__py3-none-any.whl → 0.76.0__py3-none-any.whl

kinemotion/squat_jump/kinematics.py

@@ -0,0 +1,348 @@
+"""Squat Jump (SJ) metrics calculation."""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, TypedDict
+
+import numpy as np
+
+from ..core.formatting import format_float_metric
+from ..core.types import FloatArray
+
+if TYPE_CHECKING:
+    from ..core.metadata import ResultMetadata
+
+
+class SJDataDict(TypedDict, total=False):
+    """Type-safe dictionary for SJ measurement data."""
+
+    jump_height_m: float
+    flight_time_ms: float
+    squat_hold_duration_ms: float
+    concentric_duration_ms: float
+    peak_concentric_velocity_m_s: float
+    peak_force_n: float | None
+    peak_power_w: float | None
+    mean_power_w: float | None
+    squat_hold_start_frame: float | None
+    concentric_start_frame: float | None
+    takeoff_frame: float | None
+    landing_frame: float | None
+    mass_kg: float | None
+    tracking_method: str
+
+
+class SJResultDict(TypedDict, total=False):
+    """Type-safe dictionary for complete SJ result with data and metadata."""
+
+    data: SJDataDict
+    metadata: dict  # ResultMetadata.to_dict()
+    validation: dict  # ValidationResult.to_dict()
+
+
+@dataclass
+class SJMetrics:
+    """Metrics for a squat jump analysis.
+
+    Attributes:
+        jump_height: Maximum jump height in meters
+        flight_time: Time spent in the air in milliseconds
+        squat_hold_duration: Duration of static squat hold phase in milliseconds
+        concentric_duration: Duration of concentric phase in milliseconds
+        peak_concentric_velocity: Maximum upward velocity during concentric phase in m/s
+        peak_force: Maximum force during concentric phase in Newtons
+        peak_power: Maximum power during concentric phase in Watts
+        mean_power: Mean power during concentric phase in Watts
+        squat_hold_start_frame: Frame index where squat hold begins (0-indexed)
+        concentric_start_frame: Frame index where concentric phase begins (0-indexed)
+        takeoff_frame: Frame index where takeoff occurs (0-indexed)
+        landing_frame: Frame index where landing occurs (0-indexed)
+        mass_kg: Athlete mass in kilograms
+        tracking_method: Method used for position tracking
+        result_metadata: Metadata about the analysis process
+    """
+
+    jump_height: float
+    flight_time: float
+    squat_hold_duration: float
+    concentric_duration: float
+    peak_concentric_velocity: float
+    peak_force: float | None = None
+    peak_power: float | None = None
+    mean_power: float | None = None
+    squat_hold_start_frame: float | None = None
+    concentric_start_frame: float | None = None
+    takeoff_frame: float | None = None
+    landing_frame: float | None = None
+    mass_kg: float | None = None
+    tracking_method: str = "hip"
+    result_metadata: "ResultMetadata | None" = None
+
+    def to_dict(self) -> SJResultDict:
+        """Convert metrics to JSON-serializable dictionary.
+
+        Returns:
+            Dictionary containing all SJ metrics with proper formatting.
+        """
+        data: dict[str, float | None | str] = {
+            "jump_height_m": format_float_metric(self.jump_height, 1, 3),
+            "flight_time_ms": format_float_metric(self.flight_time, 1000, 2),
+            "squat_hold_duration_ms": format_float_metric(self.squat_hold_duration, 1000, 2),
+            "concentric_duration_ms": format_float_metric(self.concentric_duration, 1000, 2),
+            "peak_concentric_velocity_m_s": format_float_metric(
+                self.peak_concentric_velocity, 1, 4
+            ),
+        }
+
+        if self.peak_force is not None:
+            data["peak_force_n"] = format_float_metric(self.peak_force, 1, 1)
+        if self.peak_power is not None:
+            data["peak_power_w"] = format_float_metric(self.peak_power, 1, 1)
+        if self.mean_power is not None:
+            data["mean_power_w"] = format_float_metric(self.mean_power, 1, 1)
+
+        if self.squat_hold_start_frame is not None:
+            data["squat_hold_start_frame"] = float(self.squat_hold_start_frame)
+        if self.concentric_start_frame is not None:
+            data["concentric_start_frame"] = float(self.concentric_start_frame)
+        if self.takeoff_frame is not None:
+            data["takeoff_frame"] = float(self.takeoff_frame)
+        if self.landing_frame is not None:
+            data["landing_frame"] = float(self.landing_frame)
+        if self.mass_kg is not None:
+            data["mass_kg"] = float(self.mass_kg)
+        data["tracking_method"] = self.tracking_method
+
+        result: SJResultDict = {"data": data}  # type: ignore[typeddict-item]
+
+        if self.result_metadata is not None:
+            result["metadata"] = self.result_metadata.to_dict()
+
+        return result
+
+
+def calculate_sj_metrics(
+    positions: FloatArray,
+    velocities: FloatArray,
+    squat_hold_start: int,
+    concentric_start: int,
+    takeoff_frame: int,
+    landing_frame: int,
+    fps: float,
+    mass_kg: float | None = None,
+    tracking_method: str = "hip",
+) -> SJMetrics:
+    """Calculate Squat Jump metrics from phase transitions.
+
+    Args:
+        positions: 1D array of vertical positions in normalized coordinates
+        velocities: 1D array of vertical velocities in normalized coordinates
+        squat_hold_start: Frame index where squat hold begins
+        concentric_start: Frame index where concentric phase begins
+        takeoff_frame: Frame index where takeoff occurs
+        landing_frame: Frame index where landing occurs
+        fps: Video frames per second
+        mass_kg: Athlete mass in kilograms (for power calculations)
+        tracking_method: Method used for position tracking
+
+    Returns:
+        SJMetrics object containing all calculated metrics
+    """
+    # Calculate jump height from flight time
+    g = 9.81  # Gravity acceleration (m/s²)
+    flight_time = (landing_frame - takeoff_frame) / fps
+    jump_height = (g * flight_time**2) / 8
+
+    # Calculate concentric duration
+    concentric_duration = (takeoff_frame - concentric_start) / fps
+
+    # Calculate squat hold duration
+    squat_hold_duration = (concentric_start - squat_hold_start) / fps
+
+    # Calculate peak concentric velocity (upward is positive)
+    if takeoff_frame > concentric_start:
+        peak_concentric_velocity = np.max(np.abs(velocities[concentric_start:takeoff_frame]))
+    else:
+        peak_concentric_velocity = 0.0
+
+    # Calculate power and force if mass is provided
+    peak_power = calculate_peak_power(
+        positions, velocities, concentric_start, takeoff_frame, fps, mass_kg
+    )
+    mean_power = calculate_mean_power(
+        positions, velocities, concentric_start, takeoff_frame, fps, mass_kg
+    )
+    peak_force = calculate_peak_force(
+        positions, velocities, concentric_start, takeoff_frame, fps, mass_kg
+    )
+
+    return SJMetrics(
+        jump_height=jump_height,
+        flight_time=flight_time,
+        squat_hold_duration=squat_hold_duration,
+        concentric_duration=concentric_duration,
+        peak_concentric_velocity=peak_concentric_velocity,
+        peak_force=peak_force,
+        peak_power=peak_power,
+        mean_power=mean_power,
+        squat_hold_start_frame=float(squat_hold_start),
+        concentric_start_frame=float(concentric_start),
+        takeoff_frame=float(takeoff_frame),
+        landing_frame=float(landing_frame),
+        mass_kg=mass_kg,
+        tracking_method=tracking_method,
+    )
+
+
+def calculate_peak_power(
+    positions: FloatArray,
+    velocities: FloatArray,
+    concentric_start: int,
+    takeoff_frame: int,
+    fps: float,
+    mass_kg: float | None,
+) -> float | None:
+    """Calculate peak power using Sayers et al. (1999) regression equation.
+
+    Formula: Peak Power (W) = 60.7 × jump_height_cm + 45.3 × mass_kg − 2055
+
+    Validation (Sayers et al., 1999, N=108):
+    - R² = 0.87 (strong correlation with force plate data)
+    - SEE = 355.0 W
+    - Error: < 1% underestimation
+    - Superior to Lewis formula (73% error) and Harman equation
+
+    Args:
+        positions: 1D array of vertical positions (not used in regression)
+        velocities: 1D array of vertical velocities
+        concentric_start: Frame index where concentric phase begins
+        takeoff_frame: Frame index where takeoff occurs
+        fps: Video frames per second
+        mass_kg: Athlete mass in kilograms
+
+    Returns:
+        Peak power in Watts, or None if mass is not provided
+    """
+    if mass_kg is None:
+        return None
+
+    g = 9.81
+
+    # Calculate takeoff velocity (negative = upward in normalized coords)
+    if takeoff_frame > concentric_start:
+        takeoff_velocity = np.min(velocities[concentric_start:takeoff_frame])
+    else:
+        takeoff_velocity = 0.0
+
+    # Calculate jump height from takeoff velocity: h = v² / (2g)
+    # Use absolute value since v is negative for upward motion
+    jump_height_m = (takeoff_velocity**2) / (2 * g)
+
+    # Convert to centimeters for Sayers formula
+    jump_height_cm = jump_height_m * 100
+
+    # Sayers et al. (1999) regression equation
+    peak_power = 60.7 * jump_height_cm + 45.3 * mass_kg - 2055
+
+    return float(peak_power)
+
+
+def calculate_mean_power(
+    positions: FloatArray,
+    velocities: FloatArray,
+    concentric_start: int,
+    takeoff_frame: int,
+    fps: float,
+    mass_kg: float | None,
+) -> float | None:
+    """Calculate mean power during concentric phase using work-energy theorem.
+
+    Formula: Mean Power (W) = (mass × g × jump_height) / concentric_duration
+
+    This represents the true mean power output during the concentric phase.
+    Typical mean-to-peak power ratio: 60-75%.
+
+    Args:
+        positions: 1D array of vertical positions
+        velocities: 1D array of vertical velocities
+        concentric_start: Frame index where concentric phase begins
+        takeoff_frame: Frame index where takeoff occurs
+        fps: Video frames per second
+        mass_kg: Athlete mass in kilograms
+
+    Returns:
+        Mean power in Watts, or None if mass is not provided
+    """
+    if mass_kg is None:
+        return None
+
+    # Calculate concentric duration
+    concentric_duration = (takeoff_frame - concentric_start) / fps
+
+    if concentric_duration <= 0:
+        return None
+
+    # Calculate takeoff velocity (negative = upward in normalized coords)
+    if takeoff_frame > concentric_start:
+        takeoff_velocity = np.min(velocities[concentric_start:takeoff_frame])
+    else:
+        takeoff_velocity = 0.0
+
+    # Calculate jump height from takeoff velocity: h = v² / (2g)
+    g = 9.81
+    jump_height_m = (takeoff_velocity**2) / (2 * g)
+
+    # Work-energy theorem: Mean Power = Work / Time
+    mean_power = (mass_kg * g * jump_height_m) / concentric_duration
+
+    return float(mean_power)
+
+
+def calculate_peak_force(
+    positions: FloatArray,
+    velocities: FloatArray,
+    concentric_start: int,
+    takeoff_frame: int,
+    fps: float,
+    mass_kg: float | None,
+) -> float | None:
+    """Calculate peak force during concentric phase.
+
+    Args:
+        positions: 1D array of vertical positions
+        velocities: 1D array of vertical velocities
+        concentric_start: Frame index where concentric phase begins
+        takeoff_frame: Frame index where takeoff occurs
+        fps: Video frames per second
+        mass_kg: Athlete mass in kilograms
+
+    Returns:
+        Peak force in Newtons, or None if mass is not provided
+    """
+    if mass_kg is None:
+        return None
+
+    # Calculate concentric duration
+    concentric_duration = (takeoff_frame - concentric_start) / fps
+
+    if concentric_duration <= 0:
+        return None
+
+    # Calculate takeoff velocity (negative = upward in normalized coords)
+    if takeoff_frame > concentric_start:
+        takeoff_velocity = np.min(velocities[concentric_start:takeoff_frame])
+    else:
+        takeoff_velocity = 0.0
+
+    # Calculate average acceleration: a = v / t
+    # Use absolute value since we want magnitude of upward acceleration
+    g = 9.81
+    avg_acceleration = np.abs(takeoff_velocity) / concentric_duration
+
+    # Average force: F = ma + mg (overcoming gravity + accelerating)
+    avg_force = mass_kg * (avg_acceleration + g)
+
+    # Peak force is typically 1.2-1.5× average force
+    # Use 1.3 as validated in biomechanics literature
+    peak_force = 1.3 * avg_force
+
+    return float(peak_force)