kinemotion 0.71.0__py3-none-any.whl → 0.72.0__py3-none-any.whl

kinemotion/cmj/joint_angles.py

@@ -5,6 +5,54 @@ import math
 import numpy as np
 
 
+def _get_side_prefix(side: str) -> str:
+    """Get the landmark key prefix for a given side.
+
+    Args:
+        side: Which side ("left" or "right")
+
+    Returns:
+        The prefix string for landmark keys
+    """
+    return "left_" if side == "left" else "right_"
+
+
+def _is_landmark_visible(
+    landmarks: dict[str, tuple[float, float, float]],
+    key: str,
+    threshold: float = 0.3,
+) -> bool:
+    """Check if a landmark meets the minimum visibility threshold.
+
+    Args:
+        landmarks: Pose landmarks dictionary
+        key: Landmark key to check
+        threshold: Minimum visibility threshold (default: 0.3)
+
+    Returns:
+        True if landmark exists and meets visibility threshold
+    """
+    return key in landmarks and landmarks[key][2] >= threshold
+
+
+def _get_landmark_xy(
+    landmarks: dict[str, tuple[float, float, float]],
+    key: str,
+) -> tuple[float, float] | None:
+    """Extract x, y coordinates from a landmark.
+
+    Args:
+        landmarks: Pose landmarks dictionary
+        key: Landmark key to extract
+
+    Returns:
+        Tuple of (x, y) coordinates, or None if key not found
+    """
+    if key not in landmarks:
+        return None
+    return (landmarks[key][0], landmarks[key][1])
+
+
 def calculate_angle_3_points(
     point1: tuple[float, float],
     point2: tuple[float, float],
@@ -88,7 +136,7 @@ def calculate_ankle_angle(
     Returns:
         Ankle angle in degrees, or None if landmarks not available
     """
-    prefix = "left_" if side == "left" else "right_"
+    prefix = _get_side_prefix(side)
 
     foot_index_key = f"{prefix}foot_index"
     heel_key = f"{prefix}heel"
@@ -96,23 +144,28 @@ def calculate_ankle_angle(
     knee_key = f"{prefix}knee"
 
     # Check ankle and knee visibility (required)
-    if ankle_key not in landmarks or landmarks[ankle_key][2] < 0.3:
+    if not _is_landmark_visible(landmarks, ankle_key):
         return None
-    if knee_key not in landmarks or landmarks[knee_key][2] < 0.3:
+    if not _is_landmark_visible(landmarks, knee_key):
         return None
 
-    ankle = (landmarks[ankle_key][0], landmarks[ankle_key][1])
-    knee = (landmarks[knee_key][0], landmarks[knee_key][1])
+    ankle = _get_landmark_xy(landmarks, ankle_key)
+    knee = _get_landmark_xy(landmarks, knee_key)
+
+    if ankle is None or knee is None:
+        return None
 
     # Try foot_index first (primary: toe tip for plantarflexion accuracy)
-    if foot_index_key in landmarks and landmarks[foot_index_key][2] > 0.5:
-        foot_point = (landmarks[foot_index_key][0], landmarks[foot_index_key][1])
-        return calculate_angle_3_points(foot_point, ankle, knee)
+    if _is_landmark_visible(landmarks, foot_index_key, threshold=0.5):
+        foot_point = _get_landmark_xy(landmarks, foot_index_key)
+        if foot_point is not None:
+            return calculate_angle_3_points(foot_point, ankle, knee)
 
     # Fallback to heel if foot_index visibility is insufficient
-    if heel_key in landmarks and landmarks[heel_key][2] > 0.3:
-        foot_point = (landmarks[heel_key][0], landmarks[heel_key][1])
-        return calculate_angle_3_points(foot_point, ankle, knee)
+    if _is_landmark_visible(landmarks, heel_key):
+        foot_point = _get_landmark_xy(landmarks, heel_key)
+        if foot_point is not None:
+            return calculate_angle_3_points(foot_point, ankle, knee)
 
     # No valid foot landmark available
     return None
@@ -136,29 +189,32 @@ def calculate_knee_angle(
     Returns:
         Knee angle in degrees, or None if landmarks not available
     """
-    prefix = "left_" if side == "left" else "right_"
+    prefix = _get_side_prefix(side)
 
     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:
+    if not _is_landmark_visible(landmarks, ankle_key):
         # 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:
+        if _is_landmark_visible(landmarks, foot_key):
             ankle_key = foot_key
         else:
             return None
 
-    if knee_key not in landmarks or landmarks[knee_key][2] < 0.3:
+    if not _is_landmark_visible(landmarks, knee_key):
         return None
-    if hip_key not in landmarks or landmarks[hip_key][2] < 0.3:
+    if not _is_landmark_visible(landmarks, hip_key):
         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])
+    ankle = _get_landmark_xy(landmarks, ankle_key)
+    knee = _get_landmark_xy(landmarks, knee_key)
+    hip = _get_landmark_xy(landmarks, hip_key)
+
+    if ankle is None or knee is None or hip is None:
+        return None
 
     return calculate_angle_3_points(ankle, knee, hip)
 
@@ -181,23 +237,26 @@ def calculate_hip_angle(
     Returns:
         Hip angle in degrees, or None if landmarks not available
     """
-    prefix = "left_" if side == "left" else "right_"
+    prefix = _get_side_prefix(side)
 
     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:
+    if not _is_landmark_visible(landmarks, knee_key):
         return None
-    if hip_key not in landmarks or landmarks[hip_key][2] < 0.3:
+    if not _is_landmark_visible(landmarks, hip_key):
         return None
-    if shoulder_key not in landmarks or landmarks[shoulder_key][2] < 0.3:
+    if not _is_landmark_visible(landmarks, shoulder_key):
         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])
+    knee = _get_landmark_xy(landmarks, knee_key)
+    hip = _get_landmark_xy(landmarks, hip_key)
+    shoulder = _get_landmark_xy(landmarks, shoulder_key)
+
+    if knee is None or hip is None or shoulder is None:
+        return None
 
     return calculate_angle_3_points(knee, hip, shoulder)
 
@@ -220,19 +279,25 @@ def calculate_trunk_tilt(
     Returns:
         Trunk tilt angle in degrees, or None if landmarks not available
     """
-    prefix = "left_" if side == "left" else "right_"
+    prefix = _get_side_prefix(side)
 
     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:
+    if not _is_landmark_visible(landmarks, hip_key):
+        return None
+    if not _is_landmark_visible(landmarks, shoulder_key):
         return None
-    if shoulder_key not in landmarks or landmarks[shoulder_key][2] < 0.3:
+
+    hip_xy = _get_landmark_xy(landmarks, hip_key)
+    shoulder_xy = _get_landmark_xy(landmarks, shoulder_key)
+
+    if hip_xy is None or shoulder_xy is None:
         return None
 
-    hip = np.array([landmarks[hip_key][0], landmarks[hip_key][1]])
-    shoulder = np.array([landmarks[shoulder_key][0], landmarks[shoulder_key][1]])
+    hip = np.array([hip_xy[0], hip_xy[1]])
+    shoulder = np.array([shoulder_xy[0], shoulder_xy[1]])
 
     # Vector from hip to shoulder
     trunk_vector = shoulder - hip

kinemotion/cmj/metrics_validator.py

@@ -81,6 +81,23 @@ class CMJMetricsValidator(MetricsValidator):
         """
         return data.get(key_with_suffix) or data.get(key_without_suffix)
 
+    @staticmethod
+    def _convert_raw_duration_to_seconds(value_raw: float) -> float:
+        """Convert raw duration value to seconds.
+
+        Handles legacy values that may be in seconds (<10) vs milliseconds (>10).
+        This heuristic works because no CMJ duration metric is between 10ms and 10s.
+
+        Args:
+            value_raw: Raw duration value (may be seconds or milliseconds)
+
+        Returns:
+            Duration in seconds
+        """
+        if value_raw < 10:  # Likely in seconds
+            return value_raw
+        return value_raw / 1000.0
+
     def validate(self, metrics: MetricsDict) -> CMJValidationResult:
         """Validate CMJ metrics comprehensively.
 
@@ -136,12 +153,7 @@ class CMJMetricsValidator(MetricsValidator):
         if flight_time_raw is None:
             return
 
-        # If value is in seconds (legacy), use as-is; if in ms, convert
-        if flight_time_raw < 10:  # Likely in seconds
-            flight_time = flight_time_raw
-        else:  # In milliseconds
-            flight_time = flight_time_raw / 1000.0
-
+        flight_time = self._convert_raw_duration_to_seconds(flight_time_raw)
         bounds = CMJBounds.FLIGHT_TIME
 
         if not bounds.is_physically_possible(flight_time):
@@ -268,13 +280,7 @@ class CMJMetricsValidator(MetricsValidator):
         if duration_raw is None:
             return
 
-        # If value is in seconds (legacy), convert to ms first
-        # Values >10 are assumed to be in ms, <10 assumed to be in seconds
-        if duration_raw < 10:  # Likely in seconds
-            duration = duration_raw
-        else:  # In milliseconds
-            duration = duration_raw / 1000.0
-
+        duration = self._convert_raw_duration_to_seconds(duration_raw)
         bounds = CMJBounds.CONCENTRIC_DURATION
 
         if not bounds.is_physically_possible(duration):
@@ -311,12 +317,7 @@ class CMJMetricsValidator(MetricsValidator):
         if duration_raw is None:
             return
 
-        # If value is in seconds (legacy), use as-is; if in ms, convert
-        if duration_raw < 10:  # Likely in seconds
-            duration = duration_raw
-        else:  # In milliseconds
-            duration = duration_raw / 1000.0
-
+        duration = self._convert_raw_duration_to_seconds(duration_raw)
         bounds = CMJBounds.ECCENTRIC_DURATION
 
         if not bounds.is_physically_possible(duration):
@@ -493,16 +494,8 @@ class CMJMetricsValidator(MetricsValidator):
         ):
             return
 
-        # Convert to seconds if needed
-        if flight_time_raw < 10:  # Likely in seconds
-            flight_time = flight_time_raw
-        else:  # In milliseconds
-            flight_time = flight_time_raw / 1000.0
-
-        if concentric_duration_raw < 10:  # Likely in seconds
-            concentric_duration = concentric_duration_raw
-        else:  # In milliseconds
-            concentric_duration = concentric_duration_raw / 1000.0
+        flight_time = self._convert_raw_duration_to_seconds(flight_time_raw)
+        concentric_duration = self._convert_raw_duration_to_seconds(concentric_duration_raw)
 
         rsi = flight_time / concentric_duration
         result.rsi = rsi

kinemotion/cmj/validation_bounds.py

@@ -170,17 +170,6 @@ class TripleExtensionBounds:
             return 125 <= angle <= 155
         return True
 
-    # TRUNK TILT (forward lean from vertical, degrees)
-    @staticmethod
-    def trunk_tilt_valid(angle: float | None, profile: AthleteProfile) -> bool:
-        """Check if trunk tilt is valid for profile."""
-        if angle is None:
-            return True
-        if angle < -15 or angle > 60:
-            return False  # Outside reasonable range
-        # Most athletes show 10-30° forward lean during takeoff
-        return -10 <= angle <= 45
-
 
 class RSIBounds:
     """Reactive Strength Index bounds."""
@@ -215,12 +204,6 @@ class RSIBounds:
         """Check if RSI is within physiological bounds."""
         return RSIBounds.MIN_VALID <= rsi <= RSIBounds.MAX_VALID
 
-    @staticmethod
-    def in_range_for_profile(rsi: float, profile: AthleteProfile) -> bool:
-        """Check if RSI is in expected range for profile."""
-        min_rsi, max_rsi = RSIBounds.get_rsi_range(profile)
-        return min_rsi <= rsi <= max_rsi
-
 
 class MetricConsistency:
     """Cross-validation tolerance for metric consistency checks."""
@@ -301,7 +284,7 @@ ATHLETE_PROFILES = {
 
 
 def estimate_athlete_profile(
-    metrics_dict: MetricsDict, gender: str | None = None
+    metrics_dict: MetricsDict, _gender: str | None = None
 ) -> AthleteProfile:
     """Estimate athlete profile from metrics.
 

kinemotion/core/__init__.py

@@ -13,7 +13,6 @@ from .pose import (
     MediaPipePoseTracker,
     PoseTrackerFactory,
     compute_center_of_mass,
-    get_tracker_info,
 )
 from .pose_landmarks import KINEMOTION_LANDMARKS, LANDMARK_INDICES
 from .quality import (
@@ -42,7 +41,6 @@ __all__ = [
     "MediaPipePoseTracker",
     "PoseTrackerFactory",
     "compute_center_of_mass",
-    "get_tracker_info",
     "LANDMARK_INDICES",
     "KINEMOTION_LANDMARKS",
     "get_model_path",

kinemotion/core/auto_tuning.py

@@ -5,6 +5,28 @@ from enum import Enum
 
 import numpy as np
 
+from .types import FOOT_KEYS
+
+
+@dataclass
+class _PresetConfig:
+    """Configuration modifiers for quality presets."""
+
+    velocity_multiplier: float  # Multiplier for velocity threshold
+    contact_frames_multiplier: float  # Multiplier for min contact frames
+    smoothing_offset: int  # Offset to smoothing window (added to base)
+    force_bilateral: bool | None  # None means use quality-based, True=force on, False=force off
+    detection_confidence: float
+    tracking_confidence: float
+
+
+@dataclass
+class _QualityAdjustment:
+    """Smoothing adjustments based on tracking quality."""
+
+    smoothing_add: int  # Frames to add to smoothing window
+    enable_bilateral: bool  # Whether to enable bilateral filtering
+
 
 class QualityPreset(str, Enum):
     """Quality presets for analysis."""
@@ -14,6 +36,46 @@ class QualityPreset(str, Enum):
     ACCURATE = "accurate"  # Research-grade analysis, slower
 
 
+# Quality preset configurations
+# FAST: Speed over accuracy
+# BALANCED: Default (uses quality-based settings)
+# ACCURATE: Maximum accuracy
+_PRESET_CONFIGS: dict[QualityPreset, _PresetConfig] = {
+    QualityPreset.FAST: _PresetConfig(
+        velocity_multiplier=1.5,
+        contact_frames_multiplier=0.67,
+        smoothing_offset=-2,
+        force_bilateral=False,
+        detection_confidence=0.3,
+        tracking_confidence=0.3,
+    ),
+    QualityPreset.BALANCED: _PresetConfig(
+        velocity_multiplier=1.0,
+        contact_frames_multiplier=1.0,
+        smoothing_offset=0,
+        force_bilateral=None,
+        detection_confidence=0.5,
+        tracking_confidence=0.5,
+    ),
+    QualityPreset.ACCURATE: _PresetConfig(
+        velocity_multiplier=0.5,
+        contact_frames_multiplier=1.0,
+        smoothing_offset=2,
+        force_bilateral=True,
+        detection_confidence=0.6,
+        tracking_confidence=0.6,
+    ),
+}
+
+
+# Quality-based adjustments
+_QUALITY_ADJUSTMENTS: dict[str, _QualityAdjustment] = {
+    "low": _QualityAdjustment(smoothing_add=2, enable_bilateral=True),
+    "medium": _QualityAdjustment(smoothing_add=1, enable_bilateral=True),
+    "high": _QualityAdjustment(smoothing_add=0, enable_bilateral=False),
+}
+
+
 @dataclass
 class VideoCharacteristics:
     """Characteristics extracted from video analysis."""
@@ -101,106 +163,48 @@ def auto_tune_parameters(
     fps = characteristics.fps
     quality = characteristics.tracking_quality
 
-    # =================================================================
-    # STEP 1: FPS-based baseline parameters
-    # These scale automatically with frame rate to maintain consistent
-    # temporal resolution and sensitivity
-    # =================================================================
-
-    # Velocity threshold: Scale inversely with fps
-    # Empirically validated with 45° oblique videos at 60fps:
-    # - Standing (stationary): ~0.001 mean, 0.0011 max
-    # - Flight/drop (moving): ~0.005-0.009
-    # Target threshold: 0.002 at 60fps for clear separation
-    # Formula: threshold = 0.004 * (30 / fps)
-    base_velocity_threshold = 0.004 * (30.0 / fps)
-
-    # Min contact frames: Scale with fps to maintain same time duration
-    # Goal: ~100ms minimum contact (3 frames @ 30fps, 6 frames @ 60fps)
-    # Formula: frames = round(3 * (fps / 30))
+    # Get preset configuration
+    preset = _PRESET_CONFIGS[quality_preset]
+
+    # Get quality-based adjustments
+    quality_adj = _QUALITY_ADJUSTMENTS[quality]
+
+    # Compute FPS-based baseline parameters
+    # Base velocity threshold: 0.012 at 30fps, scaled inversely by fps
+    # Must exceed typical MediaPipe landmark jitter (0.5-2% per frame)
+    # Previous value of 0.004 was below noise floor, causing false IN_AIR detections
+    base_velocity_threshold = 0.012 * (30.0 / fps)
     base_min_contact_frames = max(2, round(3.0 * (fps / 30.0)))
 
     # Smoothing window: Decrease with higher fps for better temporal resolution
-    # Lower fps (30fps): 5-frame window = 167ms
-    # Higher fps (60fps): 3-frame window = 50ms (same temporal resolution)
     if fps <= 30:
         base_smoothing_window = 5
-    elif fps <= 60:
-        base_smoothing_window = 3
     else:
-        base_smoothing_window = 3  # Even at 120fps, 3 is minimum for Savitzky-Golay
-
-    # =================================================================
-    # STEP 2: Quality-based adjustments
-    # Adapt smoothing and filtering based on tracking quality
-    # =================================================================
-
-    smoothing_adjustment = 0
-    enable_bilateral = False
-
-    if quality == "low":
-        # Poor tracking quality: aggressive smoothing and filtering
-        smoothing_adjustment = +2
-        enable_bilateral = True
-    elif quality == "medium":
-        # Moderate quality: slight smoothing increase
-        smoothing_adjustment = +1
-        enable_bilateral = True
-    else:  # high quality
-        # Good tracking: preserve detail, minimal smoothing
-        smoothing_adjustment = 0
-        enable_bilateral = False
-
-    # =================================================================
-    # STEP 3: Apply quality preset modifiers
-    # User can choose speed vs accuracy tradeoff
-    # =================================================================
-
-    if quality_preset == QualityPreset.FAST:
-        # Fast: Trade accuracy for speed
-        velocity_threshold = base_velocity_threshold * 1.5  # Less sensitive
-        min_contact_frames = max(2, int(base_min_contact_frames * 0.67))
-        smoothing_window = max(3, base_smoothing_window - 2 + smoothing_adjustment)
-        bilateral_filter = False  # Skip expensive filtering
-        detection_confidence = 0.3
-        tracking_confidence = 0.3
-
-    elif quality_preset == QualityPreset.ACCURATE:
-        # Accurate: Maximize accuracy, accept slower processing
-        velocity_threshold = base_velocity_threshold * 0.5  # More sensitive
-        min_contact_frames = base_min_contact_frames  # Don't increase (would miss brief)
-        smoothing_window = min(11, base_smoothing_window + 2 + smoothing_adjustment)
-        bilateral_filter = True  # Always use for best accuracy
-        detection_confidence = 0.6
-        tracking_confidence = 0.6
-
-    else:  # QualityPreset.BALANCED (default)
-        # Balanced: Good accuracy, reasonable speed
-        velocity_threshold = base_velocity_threshold
-        min_contact_frames = base_min_contact_frames
-        smoothing_window = max(3, base_smoothing_window + smoothing_adjustment)
-        bilateral_filter = enable_bilateral
-        detection_confidence = 0.5
-        tracking_confidence = 0.5
+        base_smoothing_window = 3  # 60fps+ use 3-frame window
+
+    # Apply preset modifiers and quality adjustments
+    velocity_threshold = base_velocity_threshold * preset.velocity_multiplier
+    min_contact_frames = max(2, int(base_min_contact_frames * preset.contact_frames_multiplier))
+
+    # Smoothing window = base + preset offset + quality adjustment
+    smoothing_window = base_smoothing_window + preset.smoothing_offset + quality_adj.smoothing_add
+    smoothing_window = max(3, min(11, smoothing_window))
 
     # Ensure smoothing window is odd (required for Savitzky-Golay)
     if smoothing_window % 2 == 0:
         smoothing_window += 1
 
-    # =================================================================
-    # STEP 4: Set fixed optimal values
-    # These are always the same regardless of video characteristics
-    # =================================================================
-
-    # Polyorder: Always 2 (quadratic) - optimal for jump physics (parabolic motion)
-    polyorder = 2
-
-    # Visibility threshold: Standard MediaPipe threshold
-    visibility_threshold = 0.5
+    # Bilateral filtering: preset can override, otherwise use quality-based
+    if preset.force_bilateral is not None:
+        bilateral_filter = preset.force_bilateral
+    else:
+        bilateral_filter = quality_adj.enable_bilateral
 
-    # Always enable proven accuracy features
-    outlier_rejection = True  # Removes tracking glitches (minimal cost)
-    use_curvature = True  # Trajectory curvature analysis (minimal cost)
+    # Fixed optimal values
+    polyorder = 2  # Quadratic - optimal for parabolic motion
+    visibility_threshold = 0.5  # Standard MediaPipe threshold
+    outlier_rejection = True  # Removes tracking glitches
+    use_curvature = True  # Trajectory curvature analysis
 
     return AnalysisParameters(
         smoothing_window=smoothing_window,
@@ -208,8 +212,8 @@ def auto_tune_parameters(
         velocity_threshold=velocity_threshold,
         min_contact_frames=min_contact_frames,
         visibility_threshold=visibility_threshold,
-        detection_confidence=detection_confidence,
-        tracking_confidence=tracking_confidence,
+        detection_confidence=preset.detection_confidence,
+        tracking_confidence=preset.tracking_confidence,
         outlier_rejection=outlier_rejection,
         bilateral_filter=bilateral_filter,
         use_curvature=use_curvature,
@@ -228,19 +232,10 @@ def _collect_foot_visibility_and_positions(
     Returns:
         Tuple of (visibility_scores, y_positions)
     """
-    foot_keys = [
-        "left_ankle",
-        "right_ankle",
-        "left_heel",
-        "right_heel",
-        "left_foot_index",
-        "right_foot_index",
-    ]
-
     frame_vis = []
     frame_y_positions = []
 
-    for key in foot_keys:
+    for key in FOOT_KEYS:
         if key in frame_landmarks:
             _, y, vis = frame_landmarks[key]  # x not needed for analysis
             frame_vis.append(vis)