kinemotion 0.12.1__tar.gz → 0.12.3__tar.gz

{kinemotion-0.12.1 → kinemotion-0.12.3}/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.12.3 (2025-11-06)
+
+### Bug Fixes
+
+- Resolve SonarCloud cognitive complexity violations
+  ([`5b20c48`](https://github.com/feniix/kinemotion/commit/5b20c488e058ac3628b0e20847d3fe2539a687c4))
+
+### Refactoring
+
+- **core**: Reduce cognitive complexity in video_io and auto_tuning
+  ([`14076fe`](https://github.com/feniix/kinemotion/commit/14076fe9d1f9b41ef2ff9bd643b17cf566e18654))
+
+- **dropjump**: Add shared utility for foot position extraction
+  ([`5222cc4`](https://github.com/feniix/kinemotion/commit/5222cc471b9f4406116de0b7fc193f07d21cd88a))
+
+- **dropjump**: Reduce cognitive complexity in CLI functions
+  ([`6fc887f`](https://github.com/feniix/kinemotion/commit/6fc887f6288e870a306aa1e3ffc7b8a46c21c3fc))
+
+- **examples**: Simplify programmatic usage with shared utility
+  ([`5e1bc19`](https://github.com/feniix/kinemotion/commit/5e1bc194f5784a24cfcbc7e6372ebd26a95225aa))
+
+
+## v0.12.2 (2025-11-06)
+
+### Bug Fixes
+
+- **core**: Suppress false positive for polyorder parameter
+  ([`ae5ffea`](https://github.com/feniix/kinemotion/commit/ae5ffea708741592e1cd356cdf35dcc388cbe97f))
+
+- **dropjump**: Remove unused parameters from calculate_drop_jump_metrics
+  ([`6130c11`](https://github.com/feniix/kinemotion/commit/6130c113be71dcd8c278b1f31a3b5e300a6b4532))
+
+### Refactoring
+
+- **core**: Reduce cognitive complexity in pose.py
+  ([`f0a3805`](https://github.com/feniix/kinemotion/commit/f0a380561844e54b4372f57c93b82f8c8a1440ee))
+
+- **dropjump**: Reduce cognitive complexity in analysis.py
+  ([`180bb37`](https://github.com/feniix/kinemotion/commit/180bb373f63675ef6ecacaea8e9ee9f63c3d3746))
+
+- **dropjump**: Reduce cognitive complexity in debug_overlay.py
+  ([`076cb56`](https://github.com/feniix/kinemotion/commit/076cb560c55baaff0ba93d0631eb38d69f8a7d7b))
+
+
 ## v0.12.1 (2025-11-06)
 
 ### Bug Fixes

{kinemotion-0.12.1 → kinemotion-0.12.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.12.1
+Version: 0.12.3
 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.12.1 → kinemotion-0.12.3}/examples/programmatic_usage.py

@@ -2,14 +2,12 @@
 
 from typing import Any
 
-import numpy as np
-
 from kinemotion.core.pose import PoseTracker
 from kinemotion.core.smoothing import smooth_landmarks
 from kinemotion.core.video_io import VideoProcessor
 from kinemotion.dropjump.analysis import (
-    compute_average_foot_position,
     detect_ground_contact,
+    extract_foot_positions_and_visibilities,
 )
 from kinemotion.dropjump.kinematics import calculate_drop_jump_metrics
 
@@ -48,29 +46,8 @@ def analyze_video(video_path: str) -> dict[str, Any]:
     # Smooth landmarks
     smoothed = smooth_landmarks(landmarks_sequence, window_length=5)
 
-    # Extract foot positions
-    foot_positions_list: list[float] = []
-    visibilities_list: list[float] = []
-
-    for frame_landmarks in smoothed:
-        if frame_landmarks:
-            _, foot_y = compute_average_foot_position(frame_landmarks)
-            foot_positions_list.append(foot_y)
-
-            # Average foot visibility
-            foot_vis = []
-            for key in ["left_ankle", "right_ankle", "left_heel", "right_heel"]:
-                if key in frame_landmarks:
-                    foot_vis.append(frame_landmarks[key][2])
-            visibilities_list.append(float(np.mean(foot_vis)) if foot_vis else 0.0)
-        else:
-            foot_positions_list.append(
-                foot_positions_list[-1] if foot_positions_list else 0.5
-            )
-            visibilities_list.append(0.0)
-
-    foot_positions: np.ndarray[Any, Any] = np.array(foot_positions_list)
-    visibilities: np.ndarray[Any, Any] = np.array(visibilities_list)
+    # Extract foot positions and visibilities using shared utility
+    foot_positions, visibilities = extract_foot_positions_and_visibilities(smoothed)
 
     # Detect contact
     contact_states = detect_ground_contact(

{kinemotion-0.12.1 → kinemotion-0.12.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kinemotion"
-version = "0.12.1"
+version = "0.12.3"
 description = "Video-based kinematic analysis for athletic performance"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"

{kinemotion-0.12.1 → kinemotion-0.12.3}/src/kinemotion/api.py

@@ -463,13 +463,11 @@ def process_video(
             contact_states,
             vertical_positions,
             video.fps,
-            drop_height_m=None,
             drop_start_frame=drop_start_frame,
             velocity_threshold=params.velocity_threshold,
             smoothing_window=params.smoothing_window,
             polyorder=params.polyorder,
             use_curvature=params.use_curvature,
-            kinematic_correction_factor=1.0,
         )
 
         # Generate outputs (JSON and debug video)

{kinemotion-0.12.1 → kinemotion-0.12.3}/src/kinemotion/core/auto_tuning.py

@@ -216,6 +216,59 @@ def auto_tune_parameters(
     )
 
 
+def _collect_foot_visibility_and_positions(
+    frame_landmarks: dict[str, tuple[float, float, float]],
+) -> tuple[list[float], list[float]]:
+    """
+    Collect visibility scores and Y positions from foot landmarks.
+
+    Args:
+        frame_landmarks: Landmarks for a single frame
+
+    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:
+        if key in frame_landmarks:
+            _, y, vis = frame_landmarks[key]  # x not needed for analysis
+            frame_vis.append(vis)
+            frame_y_positions.append(y)
+
+    return frame_vis, frame_y_positions
+
+
+def _check_stable_period(positions: list[float]) -> bool:
+    """
+    Check if video has a stable period at the start.
+
+    A stable period (low variance in first 30 frames) indicates
+    the subject is standing on an elevated platform before jumping.
+
+    Args:
+        positions: List of average Y positions per frame
+
+    Returns:
+        True if stable period detected, False otherwise
+    """
+    if len(positions) < 30:
+        return False
+
+    first_30_std = float(np.std(positions[:30]))
+    return first_30_std < 0.01  # Very stable = on platform
+
+
 def analyze_video_sample(
     landmarks_sequence: list[dict[str, tuple[float, float, float]] | None],
     fps: float,
@@ -235,35 +288,22 @@ def analyze_video_sample(
     Returns:
         VideoCharacteristics with analyzed properties
     """
-    # Calculate average landmark visibility
     visibilities = []
     positions = []
 
+    # Collect visibility and position data from all frames
     for frame_landmarks in landmarks_sequence:
-        if frame_landmarks:
-            # Collect visibility scores from foot landmarks
-            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:
-                if key in frame_landmarks:
-                    _, y, vis = frame_landmarks[key]  # x not needed for analysis
-                    frame_vis.append(vis)
-                    frame_y_positions.append(y)
-
-            if frame_vis:
-                visibilities.append(float(np.mean(frame_vis)))
-            if frame_y_positions:
-                positions.append(float(np.mean(frame_y_positions)))
+        if not frame_landmarks:
+            continue
+
+        frame_vis, frame_y_positions = _collect_foot_visibility_and_positions(
+            frame_landmarks
+        )
+
+        if frame_vis:
+            visibilities.append(float(np.mean(frame_vis)))
+        if frame_y_positions:
+            positions.append(float(np.mean(frame_y_positions)))
 
     # Compute metrics
     avg_visibility = float(np.mean(visibilities)) if visibilities else 0.5
@@ -273,11 +313,7 @@ def analyze_video_sample(
     tracking_quality = analyze_tracking_quality(avg_visibility)
 
     # Check for stable period (indicates drop jump from elevated platform)
-    # Simple check: do first 30 frames have low variance?
-    has_stable_period = False
-    if len(positions) >= 30:
-        first_30_std = float(np.std(positions[:30]))
-        has_stable_period = first_30_std < 0.01  # Very stable = on platform
+    has_stable_period = _check_stable_period(positions)
 
     return VideoCharacteristics(
         fps=fps,

{kinemotion-0.12.1 → kinemotion-0.12.3}/src/kinemotion/core/pose.py

@@ -81,6 +81,100 @@ class PoseTracker:
         self.pose.close()
 
 
+def _add_head_segment(
+    segments: list,
+    weights: list,
+    visibilities: list,
+    landmarks: dict[str, tuple[float, float, float]],
+    vis_threshold: float,
+) -> None:
+    """Add head segment (8% body mass) if visible."""
+    if "nose" in landmarks:
+        x, y, vis = landmarks["nose"]
+        if vis > vis_threshold:
+            segments.append((x, y))
+            weights.append(0.08)
+            visibilities.append(vis)
+
+
+def _add_trunk_segment(
+    segments: list,
+    weights: list,
+    visibilities: list,
+    landmarks: dict[str, tuple[float, float, float]],
+    vis_threshold: float,
+) -> None:
+    """Add trunk segment (50% body mass) if visible."""
+    trunk_keys = ["left_shoulder", "right_shoulder", "left_hip", "right_hip"]
+    trunk_pos = [
+        (x, y, vis)
+        for key in trunk_keys
+        if key in landmarks
+        for x, y, vis in [landmarks[key]]
+        if vis > vis_threshold
+    ]
+    if len(trunk_pos) >= 2:
+        trunk_x = float(np.mean([p[0] for p in trunk_pos]))
+        trunk_y = float(np.mean([p[1] for p in trunk_pos]))
+        trunk_vis = float(np.mean([p[2] for p in trunk_pos]))
+        segments.append((trunk_x, trunk_y))
+        weights.append(0.50)
+        visibilities.append(trunk_vis)
+
+
+def _add_limb_segment(
+    segments: list,
+    weights: list,
+    visibilities: list,
+    landmarks: dict[str, tuple[float, float, float]],
+    side: str,
+    proximal_key: str,
+    distal_key: str,
+    segment_weight: float,
+    vis_threshold: float,
+) -> None:
+    """Add a limb segment (thigh or lower leg) if both endpoints visible."""
+    prox_full = f"{side}_{proximal_key}"
+    dist_full = f"{side}_{distal_key}"
+
+    if prox_full in landmarks and dist_full in landmarks:
+        px, py, pvis = landmarks[prox_full]
+        dx, dy, dvis = landmarks[dist_full]
+        if pvis > vis_threshold and dvis > vis_threshold:
+            seg_x = (px + dx) / 2
+            seg_y = (py + dy) / 2
+            seg_vis = (pvis + dvis) / 2
+            segments.append((seg_x, seg_y))
+            weights.append(segment_weight)
+            visibilities.append(seg_vis)
+
+
+def _add_foot_segment(
+    segments: list,
+    weights: list,
+    visibilities: list,
+    landmarks: dict[str, tuple[float, float, float]],
+    side: str,
+    vis_threshold: float,
+) -> None:
+    """Add foot segment (1.5% body mass per foot) if visible."""
+    foot_keys = [f"{side}_ankle", f"{side}_heel", f"{side}_foot_index"]
+    foot_pos = [
+        (x, y, vis)
+        for key in foot_keys
+        if key in landmarks
+        for x, y, vis in [landmarks[key]]
+        if vis > vis_threshold
+    ]
+    if foot_pos:
+        foot_x = float(np.mean([p[0] for p in foot_pos]))
+        foot_y = float(np.mean([p[1] for p in foot_pos]))
+        foot_vis = float(np.mean([p[2] for p in foot_pos]))
+        segments.append((foot_x, foot_y))
+        weights.append(0.015)
+        visibilities.append(foot_vis)
+
+
 def compute_center_of_mass(
     landmarks: dict[str, tuple[float, float, float]],
     visibility_threshold: float = 0.5,
@@ -106,114 +200,59 @@ def compute_center_of_mass(
         (x, y, visibility) tuple for estimated CoM position
         visibility = average visibility of all segments used
     """
-    # Define segment representatives and their weights (as fraction of body mass)
-    # Each segment uses midpoint or average of its bounding landmarks
-    segments = []
-    segment_weights = []
-    visibilities = []
+    segments: list = []
+    weights: list = []
+    visibilities: list = []
 
-    # Head segment: 8% (use nose as proxy)
-    if "nose" in landmarks:
-        x, y, vis = landmarks["nose"]
-        if vis > visibility_threshold:
-            segments.append((x, y))
-            segment_weights.append(0.08)
-            visibilities.append(vis)
+    # Add body segments
+    _add_head_segment(segments, weights, visibilities, landmarks, visibility_threshold)
+    _add_trunk_segment(segments, weights, visibilities, landmarks, visibility_threshold)
 
-    # Trunk segment: 50% (midpoint between shoulders and hips)
-    trunk_landmarks = ["left_shoulder", "right_shoulder", "left_hip", "right_hip"]
-    trunk_positions = [
-        (x, y, vis)
-        for key in trunk_landmarks
-        if key in landmarks
-        for x, y, vis in [landmarks[key]]
-        if vis > visibility_threshold
-    ]
-    if len(trunk_positions) >= 2:
-        trunk_x = float(np.mean([pos[0] for pos in trunk_positions]))
-        trunk_y = float(np.mean([pos[1] for pos in trunk_positions]))
-        trunk_vis = float(np.mean([pos[2] for pos in trunk_positions]))
-        segments.append((trunk_x, trunk_y))
-        segment_weights.append(0.50)
-        visibilities.append(trunk_vis)
-
-    # Thigh segment: 20% total (midpoint hip to knee for each leg)
+    # Add bilateral limb segments
     for side in ["left", "right"]:
-        hip_key = f"{side}_hip"
-        knee_key = f"{side}_knee"
-        if hip_key in landmarks and knee_key in landmarks:
-            hip_x, hip_y, hip_vis = landmarks[hip_key]
-            knee_x, knee_y, knee_vis = landmarks[knee_key]
-            if hip_vis > visibility_threshold and knee_vis > visibility_threshold:
-                thigh_x = (hip_x + knee_x) / 2
-                thigh_y = (hip_y + knee_y) / 2
-                thigh_vis = (hip_vis + knee_vis) / 2
-                segments.append((thigh_x, thigh_y))
-                segment_weights.append(0.10)  # 10% per leg
-                visibilities.append(thigh_vis)
-
-    # Lower leg segment: 10% total (midpoint knee to ankle for each leg)
-    for side in ["left", "right"]:
-        knee_key = f"{side}_knee"
-        ankle_key = f"{side}_ankle"
-        if knee_key in landmarks and ankle_key in landmarks:
-            knee_x, knee_y, knee_vis = landmarks[knee_key]
-            ankle_x, ankle_y, ankle_vis = landmarks[ankle_key]
-            if knee_vis > visibility_threshold and ankle_vis > visibility_threshold:
-                leg_x = (knee_x + ankle_x) / 2
-                leg_y = (knee_y + ankle_y) / 2
-                leg_vis = (knee_vis + ankle_vis) / 2
-                segments.append((leg_x, leg_y))
-                segment_weights.append(0.05)  # 5% per leg
-                visibilities.append(leg_vis)
-
-    # Foot segment: 3% total (average of ankle, heel, foot_index)
-    for side in ["left", "right"]:
-        foot_keys = [f"{side}_ankle", f"{side}_heel", f"{side}_foot_index"]
-        foot_positions = [
-            (x, y, vis)
-            for key in foot_keys
-            if key in landmarks
-            for x, y, vis in [landmarks[key]]
-            if vis > visibility_threshold
-        ]
-        if foot_positions:
-            foot_x = float(np.mean([pos[0] for pos in foot_positions]))
-            foot_y = float(np.mean([pos[1] for pos in foot_positions]))
-            foot_vis = float(np.mean([pos[2] for pos in foot_positions]))
-            segments.append((foot_x, foot_y))
-            segment_weights.append(0.015)  # 1.5% per foot
-            visibilities.append(foot_vis)
-
-    # If no segments found, fall back to hip average
+        _add_limb_segment(
+            segments,
+            weights,
+            visibilities,
+            landmarks,
+            side,
+            "hip",
+            "knee",
+            0.10,
+            visibility_threshold,
+        )
+        _add_limb_segment(
+            segments,
+            weights,
+            visibilities,
+            landmarks,
+            side,
+            "knee",
+            "ankle",
+            0.05,
+            visibility_threshold,
+        )
+        _add_foot_segment(
+            segments, weights, visibilities, landmarks, side, visibility_threshold
+        )
+
+    # Fallback if no segments found
     if not segments:
         if "left_hip" in landmarks and "right_hip" in landmarks:
             lh_x, lh_y, lh_vis = landmarks["left_hip"]
             rh_x, rh_y, rh_vis = landmarks["right_hip"]
-            return (
-                (lh_x + rh_x) / 2,
-                (lh_y + rh_y) / 2,
-                (lh_vis + rh_vis) / 2,
-            )
-        # Ultimate fallback: center of frame
+            return ((lh_x + rh_x) / 2, (lh_y + rh_y) / 2, (lh_vis + rh_vis) / 2)
         return (0.5, 0.5, 0.0)
 
-    # Normalize weights to sum to 1.0
-    total_weight = sum(segment_weights)
-    normalized_weights = [w / total_weight for w in segment_weights]
+    # Normalize weights and compute weighted average
+    total_weight = sum(weights)
+    normalized_weights = [w / total_weight for w in weights]
 
-    # Compute weighted average of segment positions
     com_x = float(
-        sum(
-            pos[0] * weight
-            for pos, weight in zip(segments, normalized_weights, strict=True)
-        )
+        sum(p[0] * w for p, w in zip(segments, normalized_weights, strict=True))
     )
     com_y = float(
-        sum(
-            pos[1] * weight
-            for pos, weight in zip(segments, normalized_weights, strict=True)
-        )
+        sum(p[1] * w for p, w in zip(segments, normalized_weights, strict=True))
     )
     com_visibility = float(np.mean(visibilities)) if visibilities else 0.0
 

{kinemotion-0.12.1 → kinemotion-0.12.3}/src/kinemotion/core/smoothing.py

@@ -117,7 +117,7 @@ def _store_smoothed_landmarks(
             )
 
 
-def _smooth_landmarks_core(
+def _smooth_landmarks_core(  # NOSONAR(S1172) - polyorder used via closure capture in smoother_fn
     landmark_sequence: list[dict[str, tuple[float, float, float]] | None],
     window_length: int,
     polyorder: int,
@@ -129,7 +129,7 @@ def _smooth_landmarks_core(
     Args:
         landmark_sequence: List of landmark dictionaries from each frame
         window_length: Length of filter window (must be odd)
-        polyorder: Order of polynomial used to fit samples
+        polyorder: Order of polynomial used to fit samples (captured by smoother_fn closure)
         smoother_fn: Function that takes (x_coords, y_coords, valid_frames)
             and returns (x_smooth, y_smooth)
 

{kinemotion-0.12.1 → kinemotion-0.12.3}/src/kinemotion/core/video_io.py

@@ -65,6 +65,43 @@ class VideoProcessor:
                 self.display_width,
             )
 
+    def _parse_sample_aspect_ratio(self, sar_str: str) -> None:
+        """
+        Parse SAR string and update display dimensions.
+
+        Args:
+            sar_str: SAR string in format "width:height" (e.g., "270:473")
+        """
+        if not sar_str or ":" not in sar_str:
+            return
+
+        sar_parts = sar_str.split(":")
+        sar_width = int(sar_parts[0])
+        sar_height = int(sar_parts[1])
+
+        # Calculate display dimensions if pixels are non-square
+        # DAR = (width * SAR_width) / (height * SAR_height)
+        if sar_width != sar_height:
+            self.display_width = int(self.width * sar_width / sar_height)
+            self.display_height = self.height
+
+    def _extract_rotation_from_stream(self, stream: dict) -> int:  # type: ignore[type-arg]
+        """
+        Extract rotation metadata from video stream.
+
+        Args:
+            stream: ffprobe stream dictionary
+
+        Returns:
+            Rotation angle in degrees (0, 90, -90, 180)
+        """
+        side_data_list = stream.get("side_data_list", [])
+        for side_data in side_data_list:
+            if side_data.get("side_data_type") == "Display Matrix":
+                rotation = side_data.get("rotation", 0)
+                return int(rotation)
+        return 0
+
     def _extract_video_metadata(self) -> None:
         """
         Extract video metadata including SAR and rotation using ffprobe.
@@ -94,35 +131,22 @@ class VideoProcessor:
                 timeout=5,
             )
 
-            if result.returncode == 0:
-                data = json.loads(result.stdout)
-                if "streams" in data and len(data["streams"]) > 0:
-                    stream = data["streams"][0]
-
-                    # Extract SAR (Sample Aspect Ratio)
-                    sar_str = stream.get("sample_aspect_ratio", "1:1")
-
-                    # Parse SAR (e.g., "270:473")
-                    if sar_str and ":" in sar_str:
-                        sar_parts = sar_str.split(":")
-                        sar_width = int(sar_parts[0])
-                        sar_height = int(sar_parts[1])
-
-                        # Calculate display dimensions
-                        # DAR = (width * SAR_width) / (height * SAR_height)
-                        if sar_width != sar_height:
-                            self.display_width = int(
-                                self.width * sar_width / sar_height
-                            )
-                            self.display_height = self.height
-
-                    # Extract rotation from side_data_list (common for iPhone videos)
-                    side_data_list = stream.get("side_data_list", [])
-                    for side_data in side_data_list:
-                        if side_data.get("side_data_type") == "Display Matrix":
-                            rotation = side_data.get("rotation", 0)
-                            # Convert to int and normalize to 0, 90, -90, 180
-                            self.rotation = int(rotation)
+            if result.returncode != 0:
+                return
+
+            data = json.loads(result.stdout)
+            if "streams" not in data or len(data["streams"]) == 0:
+                return
+
+            stream = data["streams"][0]
+
+            # Extract and parse SAR (Sample Aspect Ratio)
+            sar_str = stream.get("sample_aspect_ratio", "1:1")
+            self._parse_sample_aspect_ratio(sar_str)
+
+            # Extract rotation from side_data_list (common for iPhone videos)
+            self.rotation = self._extract_rotation_from_stream(stream)
+
         except (subprocess.TimeoutExpired, FileNotFoundError, json.JSONDecodeError):
             # If ffprobe fails, keep original dimensions (square pixels)
             pass