kinemotion 0.20.1__py3-none-any.whl → 0.21.0__py3-none-any.whl

kinemotion/cmj/kinematics.py

@@ -1,9 +1,30 @@
 """Counter Movement Jump (CMJ) metrics calculation."""
 
 from dataclasses import dataclass
-from typing import Any
+from typing import TypedDict
 
 import numpy as np
+from numpy.typing import NDArray
+
+
+class CMJMetricsDict(TypedDict, total=False):
+    """Type-safe dictionary for CMJ metrics JSON output."""
+
+    jump_height_m: float
+    flight_time_s: float
+    countermovement_depth_m: float
+    eccentric_duration_s: float
+    concentric_duration_s: float
+    total_movement_time_s: float
+    peak_eccentric_velocity_m_s: float
+    peak_concentric_velocity_m_s: float
+    transition_time_s: float | None
+    standing_start_frame: float | None
+    lowest_point_frame: float
+    takeoff_frame: float
+    landing_frame: float
+    video_fps: float
+    tracking_method: str
 
 
 @dataclass
@@ -44,7 +65,7 @@ class CMJMetrics:
     video_fps: float
     tracking_method: str
 
-    def to_dict(self) -> dict[str, Any]:
+    def to_dict(self) -> CMJMetricsDict:
         """Convert metrics to JSON-serializable dictionary.
 
         Returns:
@@ -78,8 +99,8 @@ class CMJMetrics:
 
 
 def calculate_cmj_metrics(
-    positions: np.ndarray,
-    velocities: np.ndarray,
+    positions: NDArray[np.float64],
+    velocities: NDArray[np.float64],
     standing_start_frame: float | None,
     lowest_point_frame: float,
     takeoff_frame: float,

kinemotion/core/smoothing.py

@@ -1,5 +1,7 @@
 """Landmark smoothing utilities to reduce jitter in pose tracking."""
 
+from typing import TypeAlias
+
 import numpy as np
 from scipy.signal import savgol_filter
 
@@ -8,9 +10,14 @@ from .filtering import (
     reject_outliers,
 )
 
+# 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]
+
 
 def _extract_landmark_coordinates(
-    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    landmark_sequence: LandmarkSequence,
     landmark_name: str,
 ) -> tuple[list[float], list[float], list[int]]:
     """
@@ -38,7 +45,7 @@ def _extract_landmark_coordinates(
 
 
 def _get_landmark_names(
-    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    landmark_sequence: LandmarkSequence,
 ) -> list[str] | None:
     """
     Extract landmark names from first valid frame.
@@ -56,8 +63,8 @@ def _get_landmark_names(
 
 
 def _fill_missing_frames(
-    smoothed_sequence: list[dict[str, tuple[float, float, float]] | None],
-    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    smoothed_sequence: LandmarkSequence,
+    landmark_sequence: LandmarkSequence,
 ) -> None:
     """
     Fill in any missing frames in smoothed sequence with original data.
@@ -75,8 +82,8 @@ def _fill_missing_frames(
 
 
 def _store_smoothed_landmarks(
-    smoothed_sequence: list[dict[str, tuple[float, float, float]] | None],
-    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    smoothed_sequence: LandmarkSequence,
+    landmark_sequence: LandmarkSequence,
     landmark_name: str,
     x_smooth: np.ndarray,
     y_smooth: np.ndarray,
@@ -118,11 +125,11 @@ def _store_smoothed_landmarks(
 
 
 def _smooth_landmarks_core(  # NOSONAR(S1172) - polyorder used via closure capture in smoother_fn
-    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    landmark_sequence: LandmarkSequence,
     window_length: int,
     polyorder: int,
     smoother_fn,  # type: ignore[no-untyped-def]
-) -> list[dict[str, tuple[float, float, float]] | None]:
+) -> LandmarkSequence:
     """
     Core smoothing logic shared by both standard and advanced smoothing.
 
@@ -170,10 +177,10 @@ def _smooth_landmarks_core(  # NOSONAR(S1172) - polyorder used via closure captu
 
 
 def smooth_landmarks(
-    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    landmark_sequence: LandmarkSequence,
     window_length: int = 5,
     polyorder: int = 2,
-) -> list[dict[str, tuple[float, float, float]] | None]:
+) -> LandmarkSequence:
     """
     Smooth landmark trajectories using Savitzky-Golay filter.
 
@@ -330,7 +337,7 @@ def compute_acceleration_from_derivative(
 
 
 def smooth_landmarks_advanced(
-    landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
+    landmark_sequence: LandmarkSequence,
     window_length: int = 5,
     polyorder: int = 2,
     use_outlier_rejection: bool = True,
@@ -338,7 +345,7 @@ def smooth_landmarks_advanced(
     ransac_threshold: float = 0.02,
     bilateral_sigma_spatial: float = 3.0,
     bilateral_sigma_intensity: float = 0.02,
-) -> list[dict[str, tuple[float, float, float]] | None]:
+) -> LandmarkSequence:
     """
     Advanced landmark smoothing with outlier rejection and bilateral filtering.
 

kinemotion/dropjump/kinematics.py

@@ -1,6 +1,9 @@
 """Kinematic calculations for drop-jump metrics."""
 
+from typing import TypedDict
+
 import numpy as np
+from numpy.typing import NDArray
 
 from ..core.smoothing import compute_acceleration_from_derivative
 from .analysis import (
@@ -12,6 +15,25 @@ from .analysis import (
 )
 
 
+class DropJumpMetricsDict(TypedDict, total=False):
+    """Type-safe dictionary for drop jump metrics JSON output."""
+
+    ground_contact_time_ms: float | None
+    flight_time_ms: float | None
+    jump_height_m: float | None
+    jump_height_kinematic_m: float | None
+    jump_height_trajectory_normalized: float | None
+    contact_start_frame: int | None
+    contact_end_frame: int | None
+    flight_start_frame: int | None
+    flight_end_frame: int | None
+    peak_height_frame: int | None
+    contact_start_frame_precise: float | None
+    contact_end_frame_precise: float | None
+    flight_start_frame_precise: float | None
+    flight_end_frame_precise: float | None
+
+
 class DropJumpMetrics:
     """Container for drop-jump analysis metrics."""
 
@@ -32,7 +54,7 @@ class DropJumpMetrics:
         self.flight_start_frame_precise: float | None = None
         self.flight_end_frame_precise: float | None = None
 
-    def to_dict(self) -> dict:
+    def to_dict(self) -> DropJumpMetricsDict:
         """Convert metrics to dictionary for JSON output."""
         return {
             "ground_contact_time_ms": (
@@ -108,7 +130,7 @@ class DropJumpMetrics:
 
 def _determine_drop_start_frame(
     drop_start_frame: int | None,
-    foot_y_positions: np.ndarray,
+    foot_y_positions: NDArray[np.float64],
     fps: float,
     smoothing_window: int,
 ) -> int:
@@ -170,7 +192,7 @@ def _identify_main_contact_phase(
     phases: list[tuple[int, int, ContactState]],
     ground_phases: list[tuple[int, int, int]],
     air_phases_indexed: list[tuple[int, int, int]],
-    foot_y_positions: np.ndarray,
+    foot_y_positions: NDArray[np.float64],
 ) -> tuple[int, int, bool]:
     """Identify the main contact phase and determine if it's a drop jump.
 
@@ -260,7 +282,7 @@ def _analyze_flight_phase(
     phases: list[tuple[int, int, ContactState]],
     interpolated_phases: list[tuple[float, float, ContactState]],
     contact_end: int,
-    foot_y_positions: np.ndarray,
+    foot_y_positions: NDArray[np.float64],
     fps: float,
     smoothing_window: int,
     polyorder: int,
@@ -341,7 +363,7 @@ def _analyze_flight_phase(
 
 def calculate_drop_jump_metrics(
     contact_states: list[ContactState],
-    foot_y_positions: np.ndarray,
+    foot_y_positions: NDArray[np.float64],
     fps: float,
     drop_start_frame: int | None = None,
     velocity_threshold: float = 0.02,

{kinemotion-0.20.1.dist-info → kinemotion-0.21.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.20.1
+Version: 0.21.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

{kinemotion-0.20.1.dist-info → kinemotion-0.21.0.dist-info}/RECORD

@@ -6,23 +6,23 @@ kinemotion/cmj/analysis.py,sha256=4HYGn4VDIB6oExAees-VcPfpNgWOltpgwjyNTU7YAb4,18
 kinemotion/cmj/cli.py,sha256=bmDvNvL7cu65-R8YkRIZYKD0nuTA0IJnWLcLlH_kFm0,16843
 kinemotion/cmj/debug_overlay.py,sha256=D-y2FQKI01KY0WXFKTKg6p9Qj3AkXCE7xjau3Ais080,15886
 kinemotion/cmj/joint_angles.py,sha256=8ucpDGPvbt4iX3tx9eVxJEUv0laTm2Y58_--VzJCogE,9113
-kinemotion/cmj/kinematics.py,sha256=Xl_PlC2OqMoA-zOc3SRB_GqI0AgLlJol5FTPe5J_qLc,7573
+kinemotion/cmj/kinematics.py,sha256=bCtAQY2DIX2JMMou1Z8_Wil3a0sJhpw19pl1CsPKnBg,8202
 kinemotion/core/__init__.py,sha256=3yzDhb5PekDNjydqrs8aWGneUGJBt-lB0SoB_Y2FXqU,1010
 kinemotion/core/auto_tuning.py,sha256=j6cul_qC6k0XyryCG93C1AWH2MKPj3UBMzuX02xaqfI,11235
 kinemotion/core/cli_utils.py,sha256=Pq1JF7yvK1YbH0tOUWKjplthCbWsJQt4Lv7esPYH4FM,7254
 kinemotion/core/debug_overlay_utils.py,sha256=TyUb5okv5qw8oeaX3jsUO_kpwf1NnaHEAOTm-8LwTno,4587
 kinemotion/core/filtering.py,sha256=f-m-aA59e4WqE6u-9MA51wssu7rI-Y_7n1cG8IWdeRQ,11241
 kinemotion/core/pose.py,sha256=ztemdZ_ysVVK3gbXabm8qS_dr1VfJX9KZjmcO-Z-iNE,8532
-kinemotion/core/smoothing.py,sha256=C9GK3PAN16RpqJw2UWeVslSTJZEvALeVADjtnJnSF88,14240
+kinemotion/core/smoothing.py,sha256=x4o3BnG6k8OaV3emgpoJDF84CE9k5RYR7BeSYH_-8Es,14092
 kinemotion/core/video_io.py,sha256=0bJTheYidEqxGP5Y2dSO2x6sbOrnBDBu2TEiV8gT23A,7285
 kinemotion/dropjump/__init__.py,sha256=yc1XiZ9vfo5h_n7PKVSiX2TTgaIfGL7Y7SkQtiDZj_E,838
 kinemotion/dropjump/analysis.py,sha256=xx5NWy6s0eb9BEyO_FByY1Ahunaoh3TyaTAxjlPrvxg,27153
 kinemotion/dropjump/cli.py,sha256=J2F8ij-UcybY7YjK_bncQZiHNzrgS3Y7uTBkNo7y_L4,21328
 kinemotion/dropjump/debug_overlay.py,sha256=LkPw6ucb7beoYWS4L-Lvjs1KLCm5wAWDAfiznUeV2IQ,5668
-kinemotion/dropjump/kinematics.py,sha256=txDxpDti3VJVctWGbe3aIrlIx83UY8-ynzlX01TOvTA,15577
+kinemotion/dropjump/kinematics.py,sha256=VZWdytkw58Vk9dsNe8U15sFB84kfZKLo4argvt0CTPM,16361
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.20.1.dist-info/METADATA,sha256=pcFiZ7RCzsd1cdmJoaA_lWZaYgnNGPMTxLj5-WPHS60,20249
-kinemotion-0.20.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.20.1.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.20.1.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.20.1.dist-info/RECORD,,
+kinemotion-0.21.0.dist-info/METADATA,sha256=obRgyAAsu-63mzynO4130BaLZiLu6duW9bG-dAMV6PU,20249
+kinemotion-0.21.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kinemotion-0.21.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.21.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.21.0.dist-info/RECORD,,