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

kinemotion/squat_jump/kinematics.py

@@ -1,342 +0,0 @@
-"""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(velocities, concentric_start, takeoff_frame, 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(
-    velocities: FloatArray,
-    concentric_start: int,
-    takeoff_frame: int,
-    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:
-        velocities: 1D array of vertical velocities
-        concentric_start: Frame index where concentric phase begins
-        takeoff_frame: Frame index where takeoff occurs
-        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)