kinemotion 0.20.2__tar.gz → 0.21.0__tar.gz

{kinemotion-0.20.2 → kinemotion-0.21.0}/.pre-commit-config.yaml

@@ -15,12 +15,12 @@ repos:
       - id: mixed-line-ending
 
   - repo: https://github.com/psf/black
-    rev: 25.9.0
+    rev: 25.11.0
     hooks:
       - id: black
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.3
+    rev: v0.14.4
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]

{kinemotion-0.20.2 → kinemotion-0.21.0}/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.21.0 (2025-11-10)
+
+### Features
+
+- Add TypedDict and type aliases for improved type safety
+  ([`053e010`](https://github.com/feniix/kinemotion/commit/053e010cf80e1c91d5900c39d49b1d7ac2ac6ab4))
+
+
 ## v0.20.2 (2025-11-10)
 
 ### Bug Fixes

{kinemotion-0.20.2 → kinemotion-0.21.0}/CLAUDE.md

@@ -19,7 +19,7 @@ uv run kinemotion cmj-analyze video.mp4
 
 **Development:**
 ```bash
-uv run pytest                           # Run all 75 tests with coverage (50.75%)
+uv run pytest                           # Run all 146 tests with coverage (57.57%)
 uv run pytest --cov-report=html         # Generate HTML coverage report
 uv run ruff check --fix && uv run pyright  # Lint + type check
 ```
@@ -64,7 +64,7 @@ src/kinemotion/
 ├── dropjump/               # Drop jump: cli, analysis, kinematics, debug_overlay
 └── cmj/                    # CMJ: cli, analysis, kinematics, joint_angles, debug_overlay
 
-tests/                      # 75 tests total (61 drop jump, 9 CMJ, 5 CLI import)
+tests/                      # 146 tests total (comprehensive coverage across all modules)
 docs/                       # CMJ_GUIDE, TRIPLE_EXTENSION, REAL_TIME_ANALYSIS, etc.
 ```
 
@@ -168,7 +168,7 @@ OpenCV vs NumPy ordering:
 ```bash
 uv run ruff check --fix   # Auto-fix linting
 uv run pyright            # Type check (strict)
-uv run pytest             # All 75 tests with coverage
+uv run pytest             # All 146 tests with coverage
 ```
 
 ### Standards
@@ -177,22 +177,22 @@ uv run pytest             # All 75 tests with coverage
 - Ruff (100 char lines)
 - Conventional Commits (see below)
 - **Code duplication target: < 3%**
-- **Test coverage: ≥ 50% (current: 50.75% with branch coverage)**
+- **Test coverage: ≥ 50% (current: 57.57% with branch coverage)**
 
 ### Coverage Analysis
 
-Current coverage: **50.75%** (2184 statements, 752 branches)
+Current coverage: **57.57%** (2225 statements, 752 branches)
 
 **Well-tested modules (>80%):**
 - Core filtering: 87.80%
 - Core pose tracking: 88.46%
-- Drop jump kinematics: 83.94%
-- CMJ kinematics: 94.67%
+- Drop jump kinematics: 85.71%
+- CMJ kinematics: 95.65%
+- CMJ joint angles: 100.00%
 
-**Needs improvement (<30%):**
+**Expected lower coverage (<30%):**
 - CLI modules: 22-23% (expected - minimal integration tests)
 - Debug overlays: 10-36% (visualization code)
-- Joint angles: 6.20% (feature module)
 
 View detailed report: `uv run pytest --cov-report=html && open htmlcov/index.html`
 
@@ -268,6 +268,63 @@ metrics = process_cmj_video("video.mp4", quality="balanced")
 1. Convert NumPy types in `to_dict()`: `int()`, `float()`
 2. Type all functions (pyright strict)
 3. Handle None in optional fields
+4. Use TypedDict for dictionary returns
+5. Use type aliases for complex nested types
+
+### Modern Type Hints (NumPy 2.x)
+
+The project uses NumPy 2.x-compatible type hints:
+
+**TypedDict for type-safe dictionaries:**
+```python
+from typing import TypedDict
+
+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
+    # ... IDE autocomplete and type checking!
+```
+
+**Type aliases for cleaner signatures:**
+```python
+from typing import TypeAlias
+
+LandmarkCoord: TypeAlias = tuple[float, float, float]  # (x, y, visibility)
+LandmarkFrame: TypeAlias = dict[str, LandmarkCoord] | None
+LandmarkSequence: TypeAlias = list[LandmarkFrame]
+
+def smooth_landmarks(landmark_sequence: LandmarkSequence) -> LandmarkSequence:
+    # Much cleaner than list[dict[str, tuple[float, float, float]] | None]!
+```
+
+**NDArray with dtype specificity:**
+```python
+from numpy.typing import NDArray
+
+def calculate_metrics(
+    positions: NDArray[np.float64],  # Explicit dtype for arrays
+    velocities: NDArray[np.float64],
+) -> CMJMetrics:
+    ...
+```
+
+### Dependencies
+
+**Key versions:**
+- Python: 3.12.7
+- NumPy: 2.3.4 (benefits: better type hints, improved SciPy compatibility)
+- pytest: 9.0.0 (features: per-test timing, strict mode)
+- MediaPipe: 0.10.14
+
+**Pytest 9 configuration** (`pyproject.toml`):
+```toml
+[tool.pytest]
+minversion = "9.0"
+testpaths = ["tests"]
+console_output_style = "times"  # Shows execution time per test
+strict = true                    # Enables all strictness options
+```
 
 ## Documentation
 

{kinemotion-0.20.2 → kinemotion-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.20.2
+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.2 → kinemotion-0.21.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kinemotion"
-version = "0.20.2"
+version = "0.21.0"
 description = "Video-based kinematic analysis for athletic performance"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"
@@ -62,8 +62,11 @@ dev = [
 ]
 
 
-[tool.pytest.ini_options]
+[tool.pytest]
+minversion = "9.0"
 testpaths = ["tests"]
+console_output_style = "times"
+strict = true
 addopts = [
     "--cov=src/kinemotion",
     "--cov-report=term-missing",

{kinemotion-0.20.2 → kinemotion-0.21.0}/src/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-0.20.2 → kinemotion-0.21.0}/src/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-0.20.2 → kinemotion-0.21.0}/src/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,