kinemotion 0.63.0__py3-none-any.whl → 0.65.0__py3-none-any.whl

kinemotion/cmj/analysis.py

@@ -8,11 +8,12 @@ from scipy.signal import savgol_filter
 from ..core.experimental import unused
 from ..core.smoothing import compute_acceleration_from_derivative
 from ..core.timing import NULL_TIMER, Timer
+from ..core.types import FloatArray
 
 
 def compute_signed_velocity(
-    positions: np.ndarray, window_length: int = 5, polyorder: int = 2
-) -> np.ndarray:
+    positions: FloatArray, window_length: int = 5, polyorder: int = 2
+) -> FloatArray:
     """
     Compute SIGNED velocity for CMJ phase detection.
 
@@ -59,8 +60,8 @@ class CMJPhase(Enum):
     since="0.34.0",
 )
 def find_standing_phase(
-    positions: np.ndarray,
-    velocities: np.ndarray,
+    positions: FloatArray,
+    velocities: FloatArray,
     fps: float,
     min_standing_duration: float = 0.5,
     velocity_threshold: float = 0.01,
@@ -112,7 +113,7 @@ def find_standing_phase(
     since="0.34.0",
 )
 def find_countermovement_start(
-    velocities: np.ndarray,
+    velocities: FloatArray,
     countermovement_threshold: float = 0.015,
     min_eccentric_frames: int = 3,
     standing_start: int | None = None,
@@ -152,8 +153,8 @@ def find_countermovement_start(
 
 
 def find_lowest_point(
-    positions: np.ndarray,
-    velocities: np.ndarray,
+    positions: FloatArray,
+    velocities: FloatArray,
     min_search_frame: int = 80,
 ) -> int:
     """
@@ -195,8 +196,8 @@ def find_lowest_point(
 
 
 def find_cmj_takeoff_from_velocity_peak(
-    positions: np.ndarray,
-    velocities: np.ndarray,
+    positions: FloatArray,
+    velocities: FloatArray,
     lowest_point_frame: int,
     fps: float,
 ) -> float:
@@ -232,9 +233,9 @@ def find_cmj_takeoff_from_velocity_peak(
 
 
 def find_cmj_landing_from_position_peak(
-    positions: np.ndarray,
-    velocities: np.ndarray,
-    accelerations: np.ndarray,
+    positions: FloatArray,
+    velocities: FloatArray,
+    accelerations: FloatArray,
     takeoff_frame: int,
     fps: float,
 ) -> float:
@@ -290,8 +291,8 @@ def find_cmj_landing_from_position_peak(
     since="0.34.0",
 )
 def find_interpolated_takeoff_landing(
-    positions: np.ndarray,
-    velocities: np.ndarray,
+    positions: FloatArray,
+    velocities: FloatArray,
     lowest_point_frame: int,
     window_length: int = 5,
     polyorder: int = 2,
@@ -334,7 +335,7 @@ def find_interpolated_takeoff_landing(
     return (takeoff_frame, landing_frame)
 
 
-def find_takeoff_frame(velocities: np.ndarray, peak_height_frame: int, fps: float) -> float:
+def find_takeoff_frame(velocities: FloatArray, peak_height_frame: int, fps: float) -> float:
     """Find takeoff frame as peak upward velocity before peak height.
 
     Robust detection: When velocities are nearly identical (flat), detects
@@ -364,7 +365,7 @@ def find_takeoff_frame(velocities: np.ndarray, peak_height_frame: int, fps: floa
 
 
 def find_lowest_frame(
-    velocities: np.ndarray, positions: np.ndarray, takeoff_frame: float, fps: float
+    velocities: FloatArray, positions: FloatArray, takeoff_frame: float, fps: float
 ) -> float:
     """Find lowest point frame before takeoff."""
     lowest_search_start = max(0, int(takeoff_frame) - int(fps * 0.4))
@@ -385,8 +386,8 @@ def find_lowest_frame(
 
 
 def find_landing_frame(
-    accelerations: np.ndarray,
-    velocities: np.ndarray,
+    accelerations: FloatArray,
+    velocities: FloatArray,
     peak_height_frame: int,
     fps: float,
 ) -> float:
@@ -455,8 +456,8 @@ def compute_average_hip_position(
     """
     hip_keys = ["left_hip", "right_hip"]
 
-    x_positions = []
-    y_positions = []
+    x_positions: list[float] = []
+    y_positions: list[float] = []
 
     for key in hip_keys:
         if key in landmarks:
@@ -472,10 +473,10 @@ def compute_average_hip_position(
 
 
 def find_standing_end(
-    velocities: np.ndarray,
+    velocities: FloatArray,
     lowest_point: float,
-    _positions: np.ndarray | None = None,
-    accelerations: np.ndarray | None = None,
+    _positions: FloatArray | None = None,
+    accelerations: FloatArray | None = None,
 ) -> float | None:
     """
     Find end of standing phase before lowest point.
@@ -535,11 +536,11 @@ def find_standing_end(
 
 
 def detect_cmj_phases(
-    positions: np.ndarray,
+    positions: FloatArray,
     fps: float,
     window_length: int = 5,
     polyorder: int = 2,
-    landing_positions: np.ndarray | None = None,
+    landing_positions: FloatArray | None = None,
     timer: Timer | None = None,
 ) -> tuple[float | None, float, float, float] | None:
     """

kinemotion/cmj/kinematics.py

@@ -4,9 +4,9 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, TypedDict
 
 import numpy as np
-from numpy.typing import NDArray
 
 from ..core.formatting import format_float_metric
+from ..core.types import FloatArray
 
 if TYPE_CHECKING:
     from ..core.cmj_metrics_validator import ValidationResult
@@ -136,7 +136,7 @@ class CMJMetrics:
 
 
 def _calculate_scale_factor(
-    positions: NDArray[np.float64],
+    positions: FloatArray,
     takeoff_frame: float,
     landing_frame: float,
     jump_height: float,
@@ -169,7 +169,7 @@ def _calculate_scale_factor(
 
 
 def _calculate_countermovement_depth(
-    positions: NDArray[np.float64],
+    positions: FloatArray,
     standing_start_frame: float | None,
     lowest_point_frame: float,
     scale_factor: float,
@@ -222,7 +222,7 @@ def _calculate_phase_durations(
 
 
 def _calculate_peak_velocities(
-    velocities: NDArray[np.float64],
+    velocities: FloatArray,
     standing_start_frame: float | None,
     lowest_point_frame: float,
     takeoff_frame: float,
@@ -261,7 +261,7 @@ def _calculate_peak_velocities(
 
 
 def _calculate_transition_time(
-    velocities: NDArray[np.float64],
+    velocities: FloatArray,
     lowest_point_frame: float,
     fps: float,
 ) -> float | None:
@@ -291,8 +291,8 @@ def _calculate_transition_time(
 
 
 def calculate_cmj_metrics(
-    positions: NDArray[np.float64],
-    velocities: NDArray[np.float64],
+    positions: FloatArray,
+    velocities: FloatArray,
     standing_start_frame: float | None,
     lowest_point_frame: float,
     takeoff_frame: float,

kinemotion/cmj/metrics_validator.py

@@ -16,6 +16,7 @@ from kinemotion.cmj.validation_bounds import (
     TripleExtensionBounds,
     estimate_athlete_profile,
 )
+from kinemotion.core.types import MetricsDict
 from kinemotion.core.validation import (
     AthleteProfile,
     MetricBounds,
@@ -80,7 +81,7 @@ class CMJMetricsValidator(MetricsValidator):
         """
         return data.get(key_with_suffix) or data.get(key_without_suffix)
 
-    def validate(self, metrics: dict) -> CMJValidationResult:
+    def validate(self, metrics: MetricsDict) -> CMJValidationResult:
         """Validate CMJ metrics comprehensively.
 
         Args:
@@ -128,7 +129,7 @@ class CMJMetricsValidator(MetricsValidator):
         return result
 
     def _check_flight_time(
-        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
+        self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate flight time."""
         flight_time_raw = self._get_metric_value(metrics, "flight_time_ms", "flight_time")
@@ -176,7 +177,7 @@ class CMJMetricsValidator(MetricsValidator):
             )
 
     def _check_jump_height(
-        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
+        self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate jump height."""
         jump_height = self._get_metric_value(metrics, "jump_height_m", "jump_height")
@@ -217,7 +218,7 @@ class CMJMetricsValidator(MetricsValidator):
             )
 
     def _check_countermovement_depth(
-        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
+        self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate countermovement depth."""
         depth = self._get_metric_value(metrics, "countermovement_depth_m", "countermovement_depth")
@@ -258,7 +259,7 @@ class CMJMetricsValidator(MetricsValidator):
             )
 
     def _check_concentric_duration(
-        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
+        self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate concentric duration (contact time)."""
         duration_raw = self._get_metric_value(
@@ -308,7 +309,7 @@ class CMJMetricsValidator(MetricsValidator):
             )
 
     def _check_eccentric_duration(
-        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
+        self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate eccentric duration."""
         duration_raw = self._get_metric_value(
@@ -349,7 +350,7 @@ class CMJMetricsValidator(MetricsValidator):
             )
 
     def _check_peak_velocities(
-        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
+        self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate peak eccentric and concentric velocities."""
         # Eccentric
@@ -419,7 +420,7 @@ class CMJMetricsValidator(MetricsValidator):
                 )
 
     def _check_flight_time_height_consistency(
-        self, metrics: dict, result: CMJValidationResult
+        self, metrics: MetricsDict, result: CMJValidationResult
     ) -> None:
         """Verify jump height is consistent with flight time."""
         flight_time_ms = metrics.get("flight_time_ms")
@@ -455,7 +456,7 @@ class CMJMetricsValidator(MetricsValidator):
             )
 
     def _check_velocity_height_consistency(
-        self, metrics: dict, result: CMJValidationResult
+        self, metrics: MetricsDict, result: CMJValidationResult
     ) -> None:
         """Verify peak velocity is consistent with jump height."""
         velocity = metrics.get("peak_concentric_velocity_m_s")
@@ -491,7 +492,7 @@ class CMJMetricsValidator(MetricsValidator):
             )
 
     def _check_rsi_validity(
-        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
+        self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate Reactive Strength Index."""
         flight_time_raw = self._get_metric_value(metrics, "flight_time_ms", "flight_time")
@@ -555,7 +556,7 @@ class CMJMetricsValidator(MetricsValidator):
                     bounds=(expected_min, expected_max),
                 )
 
-    def _check_depth_height_ratio(self, metrics: dict, result: CMJValidationResult) -> None:
+    def _check_depth_height_ratio(self, metrics: MetricsDict, result: CMJValidationResult) -> None:
         """Check countermovement depth to jump height ratio."""
         depth = metrics.get("countermovement_depth_m")
         jump_height = metrics.get("jump_height_m")
@@ -595,7 +596,9 @@ class CMJMetricsValidator(MetricsValidator):
                 value=ratio,
             )
 
-    def _check_contact_depth_ratio(self, metrics: dict, result: CMJValidationResult) -> None:
+    def _check_contact_depth_ratio(
+        self, metrics: MetricsDict, result: CMJValidationResult
+    ) -> None:
         """Check contact time to countermovement depth ratio."""
         contact_ms = metrics.get("concentric_duration_ms")
         depth = metrics.get("countermovement_depth_m")
@@ -636,7 +639,7 @@ class CMJMetricsValidator(MetricsValidator):
             )
 
     def _check_triple_extension(
-        self, metrics: dict, result: CMJValidationResult, profile: AthleteProfile
+        self, metrics: MetricsDict, result: CMJValidationResult, profile: AthleteProfile
     ) -> None:
         """Validate triple extension angles."""
         angles = metrics.get("triple_extension")

kinemotion/cmj/validation_bounds.py

@@ -15,6 +15,7 @@ References:
 - Bogdanis (2012): Plyometric training effects
 """
 
+from kinemotion.core.types import MetricsDict
 from kinemotion.core.validation import AthleteProfile, MetricBounds
 
 
@@ -299,7 +300,9 @@ ATHLETE_PROFILES = {
 }
 
 
-def estimate_athlete_profile(metrics_dict: dict, gender: str | None = None) -> AthleteProfile:
+def estimate_athlete_profile(
+    metrics_dict: MetricsDict, gender: str | None = None
+) -> AthleteProfile:
     """Estimate athlete profile from metrics.
 
     Uses jump height as primary classifier:

kinemotion/core/debug_overlay_utils.py

@@ -5,10 +5,10 @@ import shutil
 import subprocess
 import time
 from pathlib import Path
-from typing import Self
 
 import cv2
 import numpy as np
+from typing_extensions import Self
 
 from .timing import NULL_TIMER, Timer
 
@@ -48,7 +48,7 @@ def create_video_writer(
 
     for codec in codecs_to_try:
         try:
-            fourcc = cv2.VideoWriter_fourcc(*codec)
+            fourcc = cv2.VideoWriter_fourcc(*codec)  # type: ignore[attr-defined]
             writer = cv2.VideoWriter(output_path, fourcc, fps, (display_width, display_height))
             if writer.isOpened():
                 used_codec = codec

kinemotion/core/pose.py

@@ -25,7 +25,7 @@ class PoseTracker:
             timer: Optional Timer for measuring operations
         """
         self.timer = timer or NULL_TIMER
-        self.mp_pose = mp.solutions.pose
+        self.mp_pose = mp.solutions.pose  # type: ignore[attr-defined]
         self.pose = self.mp_pose.Pose(
             static_image_mode=False,  # Use tracking mode for better performance
             min_detection_confidence=min_detection_confidence,

kinemotion/core/smoothing.py

@@ -1,6 +1,6 @@
 """Landmark smoothing utilities to reduce jitter in pose tracking."""
 
-from typing import TypeAlias
+from collections.abc import Callable
 
 import numpy as np
 from scipy.signal import savgol_filter
@@ -10,11 +10,10 @@ from .filtering import (
     reject_outliers,
 )
 from .timing import NULL_TIMER, Timer
+from .types import FloatArray, LandmarkCoord, LandmarkSequence
 
-# Type aliases for landmark data structures
-LandmarkCoord: TypeAlias = tuple[float, float, float]  # (x, y, visibility)
-LandmarkFrame: TypeAlias = dict[str, LandmarkCoord] | None
-LandmarkSequence: TypeAlias = list[LandmarkFrame]
+# Type alias for smoothing function callback
+SmootherFn = Callable[[list[float], list[float], list[int]], tuple[FloatArray, FloatArray]]
 
 
 def _extract_landmark_coordinates(
@@ -31,9 +30,9 @@ def _extract_landmark_coordinates(
     Returns:
         Tuple of (x_coords, y_coords, valid_frames)
     """
-    x_coords = []
-    y_coords = []
-    valid_frames = []
+    x_coords: list[float] = []
+    y_coords: list[float] = []
+    valid_frames: list[int] = []
 
     for i, frame_landmarks in enumerate(landmark_sequence):
         if frame_landmarks is not None and landmark_name in frame_landmarks:
@@ -86,8 +85,8 @@ def _store_smoothed_landmarks(
     smoothed_sequence: LandmarkSequence,
     landmark_sequence: LandmarkSequence,
     landmark_name: str,
-    x_smooth: np.ndarray,
-    y_smooth: np.ndarray,
+    x_smooth: FloatArray,
+    y_smooth: FloatArray,
     valid_frames: list[int],
 ) -> None:
     """
@@ -103,7 +102,10 @@ def _store_smoothed_landmarks(
     """
     for idx, frame_idx in enumerate(valid_frames):
         if frame_idx >= len(smoothed_sequence):
-            smoothed_sequence.extend([{}] * (frame_idx - len(smoothed_sequence) + 1))
+            empty_frames: list[dict[str, LandmarkCoord]] = [{}] * (
+                frame_idx - len(smoothed_sequence) + 1
+            )
+            smoothed_sequence.extend(empty_frames)
 
         # Ensure smoothed_sequence[frame_idx] is a dict, not None
         if smoothed_sequence[frame_idx] is None:
@@ -130,7 +132,7 @@ def _smooth_landmarks_core(  # NOSONAR(S1172) - polyorder used via closure
     landmark_sequence: LandmarkSequence,
     window_length: int,
     polyorder: int,
-    smoother_fn,  # type: ignore[no-untyped-def]
+    smoother_fn: SmootherFn,
 ) -> LandmarkSequence:
     """
     Core smoothing logic shared by both standard and advanced smoothing.
@@ -150,7 +152,7 @@ def _smooth_landmarks_core(  # NOSONAR(S1172) - polyorder used via closure
     if landmark_names is None:
         return landmark_sequence
 
-    smoothed_sequence: list[dict[str, tuple[float, float, float]] | None] = []
+    smoothed_sequence: LandmarkSequence = []
 
     for landmark_name in landmark_names:
         x_coords, y_coords, valid_frames = _extract_landmark_coordinates(
@@ -202,9 +204,11 @@ def smooth_landmarks(
     if window_length % 2 == 0:
         window_length += 1
 
-    def savgol_smoother(x_coords, y_coords, _valid_frames):  # type: ignore[no-untyped-def]
-        x_smooth = savgol_filter(x_coords, window_length, polyorder)
-        y_smooth = savgol_filter(y_coords, window_length, polyorder)
+    def savgol_smoother(
+        x_coords: list[float], y_coords: list[float], _valid_frames: list[int]
+    ) -> tuple[FloatArray, FloatArray]:
+        x_smooth: FloatArray = savgol_filter(x_coords, window_length, polyorder)
+        y_smooth: FloatArray = savgol_filter(y_coords, window_length, polyorder)
         return x_smooth, y_smooth
 
     return _smooth_landmarks_core(landmark_sequence, window_length, polyorder, savgol_smoother)
@@ -376,9 +380,11 @@ def smooth_landmarks_advanced(
     if window_length % 2 == 0:
         window_length += 1
 
-    def advanced_smoother(x_coords, y_coords, _valid_frames):  # type: ignore[no-untyped-def]
-        x_array = np.array(x_coords)
-        y_array = np.array(y_coords)
+    def advanced_smoother(
+        x_coords: list[float], y_coords: list[float], _valid_frames: list[int]
+    ) -> tuple[FloatArray, FloatArray]:
+        x_array: FloatArray = np.array(x_coords)
+        y_array: FloatArray = np.array(y_coords)
 
         # Step 1: Outlier rejection
         if use_outlier_rejection:
@@ -414,8 +420,8 @@ def smooth_landmarks_advanced(
         else:
             # Standard Savitzky-Golay
             with timer.measure("smoothing_savgol"):
-                x_smooth = savgol_filter(x_array, window_length, polyorder)
-                y_smooth = savgol_filter(y_array, window_length, polyorder)
+                x_smooth: FloatArray = savgol_filter(x_array, window_length, polyorder)  # type: ignore[reportUnknownVariableType]
+                y_smooth: FloatArray = savgol_filter(y_array, window_length, polyorder)  # type: ignore[reportUnknownVariableType]
 
         return x_smooth, y_smooth
 

kinemotion/core/types.py

@@ -0,0 +1,42 @@
+"""Central type definitions for the kinemotion package.
+
+This module provides all type aliases used throughout the codebase to ensure
+consistent typing and better IDE support.
+"""
+
+from typing import Any, TypeAlias
+
+import numpy as np
+from numpy.typing import NDArray
+
+# NumPy array types for various use cases
+FloatArray: TypeAlias = NDArray[np.floating[Any]]
+Float64Array: TypeAlias = NDArray[np.float64]
+IntArray: TypeAlias = NDArray[np.integer[Any]]
+UInt8Array: TypeAlias = NDArray[np.uint8]
+BoolArray: TypeAlias = NDArray[np.bool_]
+
+# MediaPipe landmark types
+# Using dict-based representation since MediaPipe lacks proper type stubs
+LandmarkCoord: TypeAlias = tuple[float, float, float]  # (x, y, visibility)
+LandmarkFrame: TypeAlias = dict[str, LandmarkCoord] | None
+LandmarkSequence: TypeAlias = list[LandmarkFrame]
+
+# Metrics dictionary type
+# Uses Any because metrics can contain:
+# - Simple values: float, int, str
+# - Nested dicts: e.g. "triple_extension" contains angle data
+# - Wrapper structures: e.g. {"data": {...actual metrics...}}
+MetricsDict: TypeAlias = dict[str, Any]
+
+__all__ = [
+    "FloatArray",
+    "Float64Array",
+    "IntArray",
+    "UInt8Array",
+    "BoolArray",
+    "LandmarkCoord",
+    "LandmarkFrame",
+    "LandmarkSequence",
+    "MetricsDict",
+]

kinemotion/core/video_io.py

@@ -203,6 +203,17 @@ class VideoProcessor:
         """Release video capture."""
         self.cap.release()
 
+    def __iter__(self) -> "VideoProcessor":
+        """Make the processor iterable."""
+        return self
+
+    def __next__(self) -> np.ndarray:
+        """Get the next frame during iteration."""
+        frame = self.read_frame()
+        if frame is None:
+            raise StopIteration
+        return frame
+
     def __enter__(self) -> "VideoProcessor":
         return self
 

kinemotion/dropjump/analysis.py

@@ -11,6 +11,7 @@ from ..core.smoothing import (
     interpolate_threshold_crossing,
 )
 from ..core.timing import NULL_TIMER, Timer
+from ..core.types import BoolArray, FloatArray
 
 
 class ContactState(Enum):
@@ -27,7 +28,7 @@ class ContactState(Enum):
     since="0.34.0",
 )
 def calculate_adaptive_threshold(
-    positions: np.ndarray,
+    positions: FloatArray,
     fps: float,
     baseline_duration: float = 3.0,
     multiplier: float = 1.5,
@@ -110,7 +111,7 @@ def calculate_adaptive_threshold(
 
 
 def _find_stable_baseline(
-    positions: np.ndarray,
+    positions: FloatArray,
     min_stable_frames: int,
     stability_threshold: float = 0.01,
     debug: bool = False,
@@ -149,7 +150,7 @@ def _find_stable_baseline(
 
 
 def _find_drop_from_baseline(
-    positions: np.ndarray,
+    positions: FloatArray,
     baseline_start: int,
     baseline_position: float,
     stable_window: int,
@@ -188,7 +189,7 @@ def _find_drop_from_baseline(
 
 
 def detect_drop_start(
-    positions: np.ndarray,
+    positions: FloatArray,
     fps: float,
     min_stationary_duration: float = 1.0,
     position_change_threshold: float = 0.02,
@@ -254,10 +255,10 @@ def detect_drop_start(
 
 
 def _filter_stationary_with_visibility(
-    is_stationary: np.ndarray,
-    visibilities: np.ndarray | None,
+    is_stationary: BoolArray,
+    visibilities: FloatArray | None,
     visibility_threshold: float,
-) -> np.ndarray:
+) -> BoolArray:
     """Apply visibility filter to stationary flags.
 
     Args:
@@ -275,7 +276,7 @@ def _filter_stationary_with_visibility(
 
 
 def _find_contact_frames(
-    is_stationary: np.ndarray,
+    is_stationary: BoolArray,
     min_contact_frames: int,
 ) -> set[int]:
     """Find frames with sustained contact using minimum duration filter.
@@ -308,7 +309,7 @@ def _find_contact_frames(
 def _assign_contact_states(
     n_frames: int,
     contact_frames: set[int],
-    visibilities: np.ndarray | None,
+    visibilities: FloatArray | None,
     visibility_threshold: float,
 ) -> list[ContactState]:
     """Assign contact states based on contact frames and visibility.
@@ -334,11 +335,11 @@ def _assign_contact_states(
 
 
 def detect_ground_contact(
-    foot_positions: np.ndarray,
+    foot_positions: FloatArray,
     velocity_threshold: float = 0.02,
     min_contact_frames: int = 3,
     visibility_threshold: float = 0.5,
-    visibilities: np.ndarray | None = None,
+    visibilities: FloatArray | None = None,
     window_length: int = 5,
     polyorder: int = 2,
     timer: Timer | None = None,
@@ -426,7 +427,7 @@ def find_contact_phases(
 def _interpolate_phase_start(
     start_idx: int,
     state: ContactState,
-    velocities: np.ndarray,
+    velocities: FloatArray,
     velocity_threshold: float,
 ) -> float:
     """Interpolate start boundary of a phase with sub-frame precision.
@@ -454,7 +455,7 @@ def _interpolate_phase_start(
 def _interpolate_phase_end(
     end_idx: int,
     state: ContactState,
-    velocities: np.ndarray,
+    velocities: FloatArray,
     velocity_threshold: float,
     max_idx: int,
 ) -> float:
@@ -481,7 +482,7 @@ def _interpolate_phase_end(
 
 
 def find_interpolated_phase_transitions(
-    foot_positions: np.ndarray,
+    foot_positions: FloatArray,
     contact_states: list[ContactState],
     velocity_threshold: float,
     smoothing_window: int = 5,
@@ -523,7 +524,7 @@ def find_interpolated_phase_transitions(
 
 
 def refine_transition_with_curvature(
-    foot_positions: np.ndarray,
+    foot_positions: FloatArray,
     estimated_frame: float,
     transition_type: str,
     search_window: int = 3,
@@ -598,7 +599,7 @@ def refine_transition_with_curvature(
 
 
 def find_interpolated_phase_transitions_with_curvature(
-    foot_positions: np.ndarray,
+    foot_positions: FloatArray,
     contact_states: list[ContactState],
     velocity_threshold: float,
     smoothing_window: int = 5,
@@ -684,8 +685,8 @@ def find_interpolated_phase_transitions_with_curvature(
 
 
 def find_landing_from_acceleration(
-    positions: np.ndarray,
-    accelerations: np.ndarray,
+    positions: FloatArray,
+    accelerations: FloatArray,
     takeoff_frame: int,
     fps: float,
     search_duration: float = 0.7,

kinemotion/dropjump/metrics_validator.py

@@ -9,6 +9,7 @@ of metric issues.
 
 from dataclasses import dataclass
 
+from kinemotion.core.types import MetricsDict
 from kinemotion.core.validation import (
     MetricsValidator,
     ValidationResult,
@@ -57,7 +58,7 @@ class DropJumpValidationResult(ValidationResult):
 class DropJumpMetricsValidator(MetricsValidator):
     """Comprehensive drop jump metrics validator."""
 
-    def validate(self, metrics: dict) -> DropJumpValidationResult:
+    def validate(self, metrics: MetricsDict) -> DropJumpValidationResult:
         """Validate drop jump metrics comprehensively.
 
         Args:

kinemotion/dropjump/validation_bounds.py

@@ -15,6 +15,7 @@ References:
 - Covens et al. (2019): Drop jump kinetics across athletes
 """
 
+from kinemotion.core.types import MetricsDict
 from kinemotion.core.validation import AthleteProfile, MetricBounds
 
 
@@ -123,7 +124,7 @@ def _classify_combined_score(combined_score: float) -> AthleteProfile:
     return AthleteProfile.ELITE
 
 
-def estimate_athlete_profile(metrics: dict, gender: str | None = None) -> AthleteProfile:
+def estimate_athlete_profile(metrics: MetricsDict, gender: str | None = None) -> AthleteProfile:
     """Estimate athlete profile from drop jump metrics.
 
     Uses jump_height and contact_time to classify athlete level.

{kinemotion-0.63.0.dist-info → kinemotion-0.65.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.63.0
+Version: 0.65.0
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion
@@ -25,6 +25,7 @@ Requires-Dist: mediapipe>=0.10.9
 Requires-Dist: numpy>=1.26.0
 Requires-Dist: opencv-python>=4.9.0
 Requires-Dist: scipy>=1.11.0
+Requires-Dist: typing-extensions>=4.15.0
 Description-Content-Type: text/markdown
 
 # Kinemotion

{kinemotion-0.63.0.dist-info → kinemotion-0.65.0.dist-info}/RECORD

@@ -2,41 +2,42 @@ kinemotion/__init__.py,sha256=Ho_BUtsM0PBxBW1ye9RlUg0ZqBlgGudRI9bZTF7QKUI,966
 kinemotion/api.py,sha256=uG1e4bTnj2c-6cbZJEZ_LjMwFdaG32ba2KcK_XjE_NI,1040
 kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
 kinemotion/cmj/__init__.py,sha256=SkAw9ka8Yd1Qfv9hcvk22m3EfucROzYrSNGNF5kDzho,113
-kinemotion/cmj/analysis.py,sha256=ZtKVfDj1-qoegXPklMO1GX8_OtD8pYbTyTCW4FCeaS8,22140
+kinemotion/cmj/analysis.py,sha256=jM9ZX44h1__Cg2iIhAYRoo_5fPwIOeV5Q2FZ22rMvKY,22202
 kinemotion/cmj/api.py,sha256=Xu6PepQKQFzRWZMESaWvHyPV-dueCH1TQQeQdil1KiQ,16626
 kinemotion/cmj/cli.py,sha256=P2b77IIw6kqTSIkncxlShzhmjIwqMFBNd-pZxYP-TsI,9918
 kinemotion/cmj/debug_overlay.py,sha256=bX9aPLhXiLCCMZW9v8Y4OiOAaZO0i-UGr-Pl8HCsmbI,15810
 kinemotion/cmj/joint_angles.py,sha256=HmheIEiKcQz39cRezk4h-htorOhGNPsqKIR9RsAEKts,9960
-kinemotion/cmj/kinematics.py,sha256=5xAqBP_lwDGP4fcnMXozELj0XRzBcWYGmI0tsVMYbnw,13413
-kinemotion/cmj/metrics_validator.py,sha256=10Dx7-o5-ziQ9YXnzs98v_ZqJxi3ax3COwNY8M_KqqM,30835
-kinemotion/cmj/validation_bounds.py,sha256=1QXaX3uclU2ceZya90u5qVT1tWU4kGkUW0CQbvh317I,11989
+kinemotion/cmj/kinematics.py,sha256=KwA8uSj3g1SeNf0NXMSHsp3gIw6Gfa-6QWIwdYdRXYw,13362
+kinemotion/cmj/metrics_validator.py,sha256=3oFB331Xch2sRMTvqALiwOvsWkCUhrLQ7ZCZ4QhI2lA,30986
+kinemotion/cmj/validation_bounds.py,sha256=Ry915JdInPXbqjaVGNY_urnDO1PAkCSJqHwNKRq-VkU,12048
 kinemotion/core/__init__.py,sha256=U2fnLUGXQ0jbwpXhdksYKDXbeQndEHjn9gwTAEJ9Av0,1451
 kinemotion/core/auto_tuning.py,sha256=lhAqPc-eLjMYx9BCvKdECE7TD2Dweb9KcifV6JHaXOE,11278
 kinemotion/core/cli_utils.py,sha256=sQPbT6XWWau-sm9yuN5c3eS5xNzoQGGXwSz6hQXtRvM,1859
-kinemotion/core/debug_overlay_utils.py,sha256=YlDmKns6x37H4yvulGGEUJ_D8G0bDZFTSbV8ig2hfFQ,8400
+kinemotion/core/debug_overlay_utils.py,sha256=Ne8GqEWUySwwtkmAzbBs527mh2QsBW2hbgV9CbdJjxE,8441
 kinemotion/core/determinism.py,sha256=Frw-KAOvAxTL_XtxoWpXCjMbQPUKEAusK6JctlkeuRo,2509
 kinemotion/core/experimental.py,sha256=IK05AF4aZS15ke85hF3TWCqRIXU1AlD_XKzFz735Ua8,3640
 kinemotion/core/filtering.py,sha256=Oc__pV6iHEGyyovbqa5SUi-6v8QyvaRVwA0LRayM884,11355
 kinemotion/core/formatting.py,sha256=G_3eqgOtym9RFOZVEwCxye4A2cyrmgvtQ214vIshowU,2480
 kinemotion/core/metadata.py,sha256=bJAVa4nym__zx1hNowSZduMGKBSGOPxTbBQkjm6N0D0,7207
 kinemotion/core/pipeline_utils.py,sha256=q32c1AJ8KI4Ht-K3ZiI7ectQKtg8k_FLdLy6WPBPWkU,14927
-kinemotion/core/pose.py,sha256=b7RQF4prb40hb4Yr5ATBFsj3dvEX0ohkG4h65lqHf8E,8993
+kinemotion/core/pose.py,sha256=55zqk02N6ibOCvVO5c73ZegRcDWDeKCnU_lKsdwvN4s,9023
 kinemotion/core/quality.py,sha256=VUkRL2N6B7lfIZ2pE9han_U68JwarmZz1U0ygHkgkhE,13022
-kinemotion/core/smoothing.py,sha256=-RPZzNjgtBQ-Ri0o-inkwIfx30IKo7ZTSnxXJ3Itn9w,15616
+kinemotion/core/smoothing.py,sha256=ELMHL7pzSqYffjnLDBUMBJIgt1AwOssDInE8IiXBbig,15942
 kinemotion/core/timing.py,sha256=d1rjZc07Nbi5Jrio9AC-zeS0dNAlbPyNIydLz7X75Pk,7804
+kinemotion/core/types.py,sha256=A_HclzKpf3By5DiJ0wY9B-dQJrIVAAhUfGab7qTSIL8,1279
 kinemotion/core/validation.py,sha256=0xVv-ftWveV60fJ97kmZMuy2Qqqb5aZLR50dDIrjnhg,6773
-kinemotion/core/video_io.py,sha256=vCwpWnlW2y29l48dFXokdehQn42w_IQvayxbVTjpXqQ,7863
+kinemotion/core/video_io.py,sha256=ufbwfYkxuerat4ab6Hn1tkI5T9TAOvHwREIazJ0Q2tE,8174
 kinemotion/dropjump/__init__.py,sha256=tC3H3BrCg8Oj-db-Vrtx4PH_llR1Ppkd5jwaOjhQcLg,862
-kinemotion/dropjump/analysis.py,sha256=WQ2ol5fWAXA2y-0UDGXgF587qsOsKNgkWPQLXaNZMdU,28005
+kinemotion/dropjump/analysis.py,sha256=YomuoJF_peyrBSpeT89Q5_sBgY0kEDyq7TFrtEnRLjs,28049
 kinemotion/dropjump/api.py,sha256=uidio49CXisyWKd287CnCrM51GusG9DWAIUKGH85fpM,20584
 kinemotion/dropjump/cli.py,sha256=gUef9nmyR5952h1WnfBGyCdFXQvzVTlCKYAjJGcO4sE,16819
 kinemotion/dropjump/debug_overlay.py,sha256=9RQYXPRf0q2wdy6y2Ak2R4tpRceDwC8aJrXZzkmh3Wo,5942
 kinemotion/dropjump/kinematics.py,sha256=dx4PuXKfKMKcsc_HX6sXj8rHXf9ksiZIOAIkJ4vBlY4,19637
-kinemotion/dropjump/metrics_validator.py,sha256=367-TFal2bVDU3zwoCDpYY_lnYjSdXOrvNIIxVnIWiE,9190
-kinemotion/dropjump/validation_bounds.py,sha256=MUMJhGV62peFuIHdPR1uulMS4bI-i_JerGh5T9HF8Wk,5071
+kinemotion/dropjump/metrics_validator.py,sha256=lSfo4Lm5FHccl8ijUP6SA-kcSh50LS9hF8UIyWxcnW8,9243
+kinemotion/dropjump/validation_bounds.py,sha256=x4yjcFxyvdMp5e7MkcoUosGLeGsxBh1Lft6h__AQ2G8,5124
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.63.0.dist-info/METADATA,sha256=Q2P0wBnyPSTc8u5MrQm5jTnPm_FhBcd7mExg_5U4Pns,26020
-kinemotion-0.63.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-kinemotion-0.63.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.63.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.63.0.dist-info/RECORD,,
+kinemotion-0.65.0.dist-info/METADATA,sha256=nueJEdfl6jQRaClefXb9-6J-pTFJN0E_XJ33Bf2mja0,26061
+kinemotion-0.65.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+kinemotion-0.65.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.65.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.65.0.dist-info/RECORD,,