kinemotion 0.10.4__tar.gz → 0.10.5__tar.gz

{kinemotion-0.10.4 → kinemotion-0.10.5}/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.10.5 (2025-11-03)
+
+### Bug Fixes
+
+- **kinematics**: Reduce cognitive complexity in calculate_drop_jump_metrics
+  ([`d6a06f3`](https://github.com/feniix/kinemotion/commit/d6a06f3671eb370a971c73c98270668d5aefe9b1))
+
+
 ## v0.10.4 (2025-11-03)
 
 ### Bug Fixes

{kinemotion-0.10.4 → kinemotion-0.10.5}/PKG-INFO

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

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

{kinemotion-0.10.4 → kinemotion-0.10.5}/src/kinemotion/dropjump/kinematics.py

@@ -104,113 +104,89 @@ class DropJumpMetrics:
         }
 
 
-def calculate_drop_jump_metrics(
-    contact_states: list[ContactState],
+def _determine_drop_start_frame(
+    drop_start_frame: int | None,
     foot_y_positions: np.ndarray,
     fps: float,
-    drop_height_m: float | None = None,
-    drop_start_frame: int | None = None,
-    velocity_threshold: float = 0.02,
-    smoothing_window: int = 5,
-    polyorder: int = 2,
-    use_curvature: bool = True,
-    kinematic_correction_factor: float = 1.0,
-) -> DropJumpMetrics:
-    """
-    Calculate drop-jump metrics from contact states and positions.
+    smoothing_window: int,
+) -> int:
+    """Determine the drop start frame for analysis.
 
     Args:
-        contact_states: Contact state for each frame
-        foot_y_positions: Vertical positions of feet (normalized 0-1)
+        drop_start_frame: Manual drop start frame or None for auto-detection
+        foot_y_positions: Vertical positions array
         fps: Video frame rate
-        drop_height_m: Known drop box/platform height in meters for calibration (optional)
-        velocity_threshold: Velocity threshold used for contact detection (for interpolation)
-        smoothing_window: Window size for velocity/acceleration smoothing (must be odd)
-        polyorder: Polynomial order for Savitzky-Golay filter (default: 2)
-        use_curvature: Whether to use curvature analysis for refining transitions
-        kinematic_correction_factor: Correction factor for kinematic jump height calculation
-            (default: 1.0 = no correction). Historical testing suggested 1.35, but this is
-            unvalidated. Use calibrated measurement (--drop-height) for validated results.
+        smoothing_window: Smoothing window size
 
     Returns:
-        DropJumpMetrics object with calculated values
+        Drop start frame (0 if not detected/provided)
     """
-    metrics = DropJumpMetrics()
-
-    # Detect or use manually specified drop jump start frame
     if drop_start_frame is None:
         # Auto-detect where drop jump actually starts (skip initial stationary period)
-        drop_start_frame = detect_drop_start(
+        detected_frame = detect_drop_start(
             foot_y_positions,
             fps,
-            min_stationary_duration=0.5,  # 0.5s stable period (~30 frames @ 60fps)
-            position_change_threshold=0.005,  # 0.5% of frame height - sensitive to drop start
+            min_stationary_duration=0.5,
+            position_change_threshold=0.005,
             smoothing_window=smoothing_window,
         )
-    # If manually specified or auto-detected, use it; otherwise start from frame 0
-    drop_start_frame_value: int
-    if drop_start_frame is None:  # pyright: ignore[reportUnnecessaryComparison]
-        drop_start_frame_value = 0
-    else:
-        drop_start_frame_value = drop_start_frame
+        return detected_frame if detected_frame is not None else 0
+    return drop_start_frame
 
-    phases = find_contact_phases(contact_states)
 
-    # Get interpolated phases with curvature-based refinement
-    # Combines velocity interpolation + acceleration pattern analysis
-    interpolated_phases = find_interpolated_phase_transitions_with_curvature(
-        foot_y_positions,
-        contact_states,
-        velocity_threshold,
-        smoothing_window,
-        polyorder,
-        use_curvature,
-    )
-
-    if not phases:
-        return metrics
+def _filter_phases_after_drop(
+    phases: list[tuple[int, int, ContactState]],
+    interpolated_phases: list[tuple[float, float, ContactState]],
+    drop_start_frame: int,
+) -> tuple[
+    list[tuple[int, int, ContactState]], list[tuple[float, float, ContactState]]
+]:
+    """Filter phases to only include those after drop start.
 
-    # Filter phases to only include those after drop start
-    # This removes the initial stationary period where athlete is standing on box
-    if drop_start_frame_value > 0:
-        phases = [
-            (start, end, state)
-            for start, end, state in phases
-            if end >= drop_start_frame_value
-        ]
-        interpolated_phases = [
-            (start, end, state)
-            for start, end, state in interpolated_phases
-            if end >= drop_start_frame_value
-        ]
+    Args:
+        phases: Integer frame phases
+        interpolated_phases: Sub-frame precision phases
+        drop_start_frame: Frame where drop starts
 
-    if not phases:
-        return metrics
+    Returns:
+        Tuple of (filtered_phases, filtered_interpolated_phases)
+    """
+    if drop_start_frame <= 0:
+        return phases, interpolated_phases
 
-    # Find the main contact phase
-    # For drop jumps: find first ON_GROUND after first IN_AIR (the landing after drop)
-    # For regular jumps: use longest ON_GROUND phase
-    ground_phases = [
-        (start, end, i)
-        for i, (start, end, state) in enumerate(phases)
-        if state == ContactState.ON_GROUND
+    filtered_phases = [
+        (start, end, state) for start, end, state in phases if end >= drop_start_frame
     ]
-    air_phases_indexed = [
-        (start, end, i)
-        for i, (start, end, state) in enumerate(phases)
-        if state == ContactState.IN_AIR
+    filtered_interpolated = [
+        (start, end, state)
+        for start, end, state in interpolated_phases
+        if end >= drop_start_frame
     ]
+    return filtered_phases, filtered_interpolated
 
-    if not ground_phases:
-        return metrics
 
-    # Initialize contact variables with first ground phase as fallback
-    # (will be overridden by drop jump or regular jump detection logic)
+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,
+) -> tuple[int, int, bool]:
+    """Identify the main contact phase and determine if it's a drop jump.
+
+    Args:
+        phases: All phase tuples
+        ground_phases: Ground phases with indices
+        air_phases_indexed: Air phases with indices
+        foot_y_positions: Vertical position array
+
+    Returns:
+        Tuple of (contact_start, contact_end, is_drop_jump)
+    """
+    # Initialize with first ground phase as fallback
     contact_start, contact_end = ground_phases[0][0], ground_phases[0][1]
+    is_drop_jump = False
 
     # Detect if this is a drop jump or regular jump
-    # Drop jump: first ground phase is elevated (lower y), followed by drop, then landing (higher y)
-    is_drop_jump = False
     if air_phases_indexed and len(ground_phases) >= 2:
         first_ground_start, first_ground_end, first_ground_idx = ground_phases[0]
         first_air_idx = air_phases_indexed[0][2]
@@ -243,17 +219,29 @@ def calculate_drop_jump_metrics(
             [(s, e) for s, e, _ in ground_phases], key=lambda p: p[1] - p[0]
         )
 
-    # Store integer frame indices (for visualization)
-    metrics.contact_start_frame = contact_start
-    metrics.contact_end_frame = contact_end
+    return contact_start, contact_end, is_drop_jump
+
 
-    # Find corresponding interpolated phase for precise timing
+def _find_precise_phase_timing(
+    contact_start: int,
+    contact_end: int,
+    interpolated_phases: list[tuple[float, float, ContactState]],
+) -> tuple[float, float]:
+    """Find precise sub-frame timing for contact phase.
+
+    Args:
+        contact_start: Integer contact start frame
+        contact_end: Integer contact end frame
+        interpolated_phases: Sub-frame precision phases
+
+    Returns:
+        Tuple of (contact_start_frac, contact_end_frac)
+    """
     contact_start_frac = float(contact_start)
     contact_end_frac = float(contact_end)
 
     # Find the matching ground phase in interpolated_phases
     for start_frac, end_frac, state in interpolated_phases:
-        # Match by checking if integer frames are within this phase
         if (
             state == ContactState.ON_GROUND
             and int(start_frac) <= contact_start <= int(end_frac) + 1
@@ -263,43 +251,82 @@ def calculate_drop_jump_metrics(
             contact_end_frac = end_frac
             break
 
-    # Calculate ground contact time using fractional frames
-    contact_frames_precise = contact_end_frac - contact_start_frac
-    metrics.ground_contact_time = contact_frames_precise / fps
-    metrics.contact_start_frame_precise = contact_start_frac
-    metrics.contact_end_frame_precise = contact_end_frac
+    return contact_start_frac, contact_end_frac
+
 
-    # Calculate calibration scale factor from drop height if provided
+def _calculate_calibration_scale(
+    drop_height_m: float | None,
+    phases: list[tuple[int, int, ContactState]],
+    air_phases_indexed: list[tuple[int, int, int]],
+    foot_y_positions: np.ndarray,
+) -> float:
+    """Calculate calibration scale factor from known drop height.
+
+    Args:
+        drop_height_m: Known drop height in meters
+        phases: All phase tuples
+        air_phases_indexed: Air phases with indices
+        foot_y_positions: Vertical position array
+
+    Returns:
+        Scale factor (1.0 if no calibration possible)
+    """
     scale_factor = 1.0
-    if drop_height_m is not None and len(phases) >= 2:
-        # Find the initial drop by looking for first IN_AIR phase
-        # This represents the drop from the box
-
-        if air_phases_indexed and ground_phases:
-            # Get first air phase (the drop)
-            first_air_start, first_air_end, _ = air_phases_indexed[0]
-
-            # Initial position: at start of drop (on the box)
-            # Look back a few frames to get stable position on box
-            lookback_start = max(0, first_air_start - 5)
-            if lookback_start < first_air_start:
-                initial_position = float(
-                    np.mean(foot_y_positions[lookback_start:first_air_start])
-                )
-            else:
-                initial_position = float(foot_y_positions[first_air_start])
-
-            # Landing position: at the ground after drop
-            # Use position at end of first air phase
-            landing_position = float(foot_y_positions[first_air_end])
-
-            # Drop distance in normalized coordinates (y increases downward)
-            drop_normalized = landing_position - initial_position
-
-            if drop_normalized > 0.01:  # Sanity check (at least 1% of frame height)
-                # Calculate scale factor: real_meters / normalized_distance
-                scale_factor = drop_height_m / drop_normalized
 
+    if drop_height_m is None or len(phases) < 2:
+        return scale_factor
+
+    if not air_phases_indexed:
+        return scale_factor
+
+    # Get first air phase (the drop)
+    first_air_start, first_air_end, _ = air_phases_indexed[0]
+
+    # Initial position: at start of drop (on the box)
+    lookback_start = max(0, first_air_start - 5)
+    if lookback_start < first_air_start:
+        initial_position = float(
+            np.mean(foot_y_positions[lookback_start:first_air_start])
+        )
+    else:
+        initial_position = float(foot_y_positions[first_air_start])
+
+    # Landing position: at the ground after drop
+    landing_position = float(foot_y_positions[first_air_end])
+
+    # Drop distance in normalized coordinates (y increases downward)
+    drop_normalized = landing_position - initial_position
+
+    if drop_normalized > 0.01:  # Sanity check
+        scale_factor = drop_height_m / drop_normalized
+
+    return scale_factor
+
+
+def _analyze_flight_phase(
+    metrics: DropJumpMetrics,
+    phases: list[tuple[int, int, ContactState]],
+    interpolated_phases: list[tuple[float, float, ContactState]],
+    contact_end: int,
+    foot_y_positions: np.ndarray,
+    fps: float,
+    drop_height_m: float | None,
+    scale_factor: float,
+    kinematic_correction_factor: float,
+) -> None:
+    """Analyze flight phase and calculate jump height metrics.
+
+    Args:
+        metrics: DropJumpMetrics object to populate
+        phases: All phase tuples
+        interpolated_phases: Sub-frame precision phases
+        contact_end: End of contact phase
+        foot_y_positions: Vertical position array
+        fps: Video frame rate
+        drop_height_m: Known drop height (optional)
+        scale_factor: Calibration scale factor
+        kinematic_correction_factor: Correction for kinematic method
+    """
     # Find flight phase after ground contact
     flight_phases = [
         (start, end)
@@ -307,94 +334,179 @@ def calculate_drop_jump_metrics(
         if state == ContactState.IN_AIR and start > contact_end
     ]
 
-    if flight_phases:
-        flight_start, flight_end = flight_phases[0]
-
-        # Store integer frame indices (for visualization)
-        metrics.flight_start_frame = flight_start
-        metrics.flight_end_frame = flight_end
-
-        # Find corresponding interpolated phase for precise timing
-        flight_start_frac = float(flight_start)
-        flight_end_frac = float(flight_end)
-
-        # Find the matching air phase in interpolated_phases
-        for start_frac, end_frac, state in interpolated_phases:
-            # Match by checking if integer frames are within this phase
-            if (
-                state == ContactState.IN_AIR
-                and int(start_frac) <= flight_start <= int(end_frac) + 1
-                and int(start_frac) <= flight_end <= int(end_frac) + 1
-            ):
-                flight_start_frac = start_frac
-                flight_end_frac = end_frac
-                break
-
-        # Calculate flight time using fractional frames
-        flight_frames_precise = flight_end_frac - flight_start_frac
-        metrics.flight_time = flight_frames_precise / fps
-        metrics.flight_start_frame_precise = flight_start_frac
-        metrics.flight_end_frame_precise = flight_end_frac
-
-        # Calculate jump height using flight time (kinematic method)
-        # h = (g * t^2) / 8, where t is total flight time
-        g = 9.81  # m/s^2
-        jump_height_kinematic = (g * metrics.flight_time**2) / 8
-
-        # Calculate jump height from trajectory (position-based method)
-        # This measures actual vertical displacement from takeoff to peak
-        takeoff_position = foot_y_positions[flight_start]
-        flight_positions = foot_y_positions[flight_start : flight_end + 1]
-
-        if len(flight_positions) > 0:
-            peak_idx = np.argmin(flight_positions)
-            metrics.peak_height_frame = int(flight_start + peak_idx)
-            peak_position = np.min(flight_positions)
-
-            # Height in normalized coordinates (0-1 range)
-            height_normalized = float(takeoff_position - peak_position)
-
-            # Store trajectory value (in normalized coordinates)
-            metrics.jump_height_trajectory = height_normalized
-
-            # Choose measurement method based on calibration availability
-            if drop_height_m is not None and scale_factor > 1.0:
-                # Use calibrated trajectory measurement (most accurate)
-                metrics.jump_height = height_normalized * scale_factor
-                metrics.jump_height_kinematic = jump_height_kinematic
-            else:
-                # Apply kinematic correction factor to kinematic method
-                # ⚠️ WARNING: Kinematic correction factor is EXPERIMENTAL and UNVALIDATED
-                #
-                # The kinematic method h = (g × t²) / 8 may underestimate jump height due to:
-                # 1. Contact detection timing (may detect landing slightly early/late)
-                # 2. Frame rate limitations (30 fps = 33ms intervals between samples)
-                # 3. Foot position vs center of mass difference (feet land before CoM peak)
-                #
-                # Default correction factor is 1.0 (no correction). Historical testing
-                # suggested 1.35 could improve accuracy, but:
-                # - This value has NOT been validated against gold standards
-                #   (force plates, motion capture)
-                # - The actual correction needed may vary by athlete, jump type, and video quality
-                # - Using a correction factor without validation is experimental
-                #
-                # For validated measurements, use:
-                # - Calibrated measurement with --drop-height parameter
-                # - Or compare against validated measurement systems
-                metrics.jump_height = (
-                    jump_height_kinematic * kinematic_correction_factor
-                )
-                metrics.jump_height_kinematic = jump_height_kinematic
+    if not flight_phases:
+        return
+
+    flight_start, flight_end = flight_phases[0]
+
+    # Store integer frame indices
+    metrics.flight_start_frame = flight_start
+    metrics.flight_end_frame = flight_end
+
+    # Find precise timing
+    flight_start_frac = float(flight_start)
+    flight_end_frac = float(flight_end)
+
+    for start_frac, end_frac, state in interpolated_phases:
+        if (
+            state == ContactState.IN_AIR
+            and int(start_frac) <= flight_start <= int(end_frac) + 1
+            and int(start_frac) <= flight_end <= int(end_frac) + 1
+        ):
+            flight_start_frac = start_frac
+            flight_end_frac = end_frac
+            break
+
+    # Calculate flight time
+    flight_frames_precise = flight_end_frac - flight_start_frac
+    metrics.flight_time = flight_frames_precise / fps
+    metrics.flight_start_frame_precise = flight_start_frac
+    metrics.flight_end_frame_precise = flight_end_frac
+
+    # Calculate jump height using kinematic method
+    g = 9.81  # m/s^2
+    jump_height_kinematic = (g * metrics.flight_time**2) / 8
+
+    # Calculate jump height from trajectory
+    takeoff_position = foot_y_positions[flight_start]
+    flight_positions = foot_y_positions[flight_start : flight_end + 1]
+
+    if len(flight_positions) > 0:
+        peak_idx = np.argmin(flight_positions)
+        metrics.peak_height_frame = int(flight_start + peak_idx)
+        peak_position = np.min(flight_positions)
+
+        height_normalized = float(takeoff_position - peak_position)
+        metrics.jump_height_trajectory = height_normalized
+
+        # Choose measurement method based on calibration availability
+        if drop_height_m is not None and scale_factor > 1.0:
+            metrics.jump_height = height_normalized * scale_factor
+            metrics.jump_height_kinematic = jump_height_kinematic
         else:
-            # Fallback to kinematic if no position data
-            if drop_height_m is None:
-                # Apply kinematic correction factor (see detailed comment above)
-                metrics.jump_height = (
-                    jump_height_kinematic * kinematic_correction_factor
-                )
-            else:
-                metrics.jump_height = jump_height_kinematic
+            metrics.jump_height = jump_height_kinematic * kinematic_correction_factor
             metrics.jump_height_kinematic = jump_height_kinematic
+    else:
+        # Fallback to kinematic if no position data
+        if drop_height_m is None:
+            metrics.jump_height = jump_height_kinematic * kinematic_correction_factor
+        else:
+            metrics.jump_height = jump_height_kinematic
+        metrics.jump_height_kinematic = jump_height_kinematic
+
+
+def calculate_drop_jump_metrics(
+    contact_states: list[ContactState],
+    foot_y_positions: np.ndarray,
+    fps: float,
+    drop_height_m: float | None = None,
+    drop_start_frame: int | None = None,
+    velocity_threshold: float = 0.02,
+    smoothing_window: int = 5,
+    polyorder: int = 2,
+    use_curvature: bool = True,
+    kinematic_correction_factor: float = 1.0,
+) -> DropJumpMetrics:
+    """
+    Calculate drop-jump metrics from contact states and positions.
+
+    Args:
+        contact_states: Contact state for each frame
+        foot_y_positions: Vertical positions of feet (normalized 0-1)
+        fps: Video frame rate
+        drop_height_m: Known drop box/platform height in meters for calibration (optional)
+        velocity_threshold: Velocity threshold used for contact detection (for interpolation)
+        smoothing_window: Window size for velocity/acceleration smoothing (must be odd)
+        polyorder: Polynomial order for Savitzky-Golay filter (default: 2)
+        use_curvature: Whether to use curvature analysis for refining transitions
+        kinematic_correction_factor: Correction factor for kinematic jump height calculation
+            (default: 1.0 = no correction). Historical testing suggested 1.35, but this is
+            unvalidated. Use calibrated measurement (--drop-height) for validated results.
+
+    Returns:
+        DropJumpMetrics object with calculated values
+    """
+    metrics = DropJumpMetrics()
+
+    # Determine drop start frame
+    drop_start_frame_value = _determine_drop_start_frame(
+        drop_start_frame, foot_y_positions, fps, smoothing_window
+    )
+
+    # Find contact phases
+    phases = find_contact_phases(contact_states)
+    interpolated_phases = find_interpolated_phase_transitions_with_curvature(
+        foot_y_positions,
+        contact_states,
+        velocity_threshold,
+        smoothing_window,
+        polyorder,
+        use_curvature,
+    )
+
+    if not phases:
+        return metrics
+
+    # Filter phases to only include those after drop start
+    phases, interpolated_phases = _filter_phases_after_drop(
+        phases, interpolated_phases, drop_start_frame_value
+    )
+
+    if not phases:
+        return metrics
+
+    # Separate ground and air phases
+    ground_phases = [
+        (start, end, i)
+        for i, (start, end, state) in enumerate(phases)
+        if state == ContactState.ON_GROUND
+    ]
+    air_phases_indexed = [
+        (start, end, i)
+        for i, (start, end, state) in enumerate(phases)
+        if state == ContactState.IN_AIR
+    ]
+
+    if not ground_phases:
+        return metrics
+
+    # Identify main contact phase
+    contact_start, contact_end, _ = _identify_main_contact_phase(
+        phases, ground_phases, air_phases_indexed, foot_y_positions
+    )
+
+    # Store integer frame indices
+    metrics.contact_start_frame = contact_start
+    metrics.contact_end_frame = contact_end
+
+    # Find precise timing for contact phase
+    contact_start_frac, contact_end_frac = _find_precise_phase_timing(
+        contact_start, contact_end, interpolated_phases
+    )
+
+    # Calculate ground contact time
+    contact_frames_precise = contact_end_frac - contact_start_frac
+    metrics.ground_contact_time = contact_frames_precise / fps
+    metrics.contact_start_frame_precise = contact_start_frac
+    metrics.contact_end_frame_precise = contact_end_frac
+
+    # Calculate calibration scale factor
+    scale_factor = _calculate_calibration_scale(
+        drop_height_m, phases, air_phases_indexed, foot_y_positions
+    )
+
+    # Analyze flight phase and calculate jump height
+    _analyze_flight_phase(
+        metrics,
+        phases,
+        interpolated_phases,
+        contact_end,
+        foot_y_positions,
+        fps,
+        drop_height_m,
+        scale_factor,
+        kinematic_correction_factor,
+    )
 
     return metrics
 

{kinemotion-0.10.4 → kinemotion-0.10.5}/uv.lock

@@ -603,7 +603,7 @@ wheels = [
 
 [[package]]
 name = "kinemotion"
-version = "0.10.3"
+version = "0.10.4"
 source = { editable = "." }
 dependencies = [
     { name = "click" },