kinemotion 0.76.3__py3-none-any.whl → 1.0.0__py3-none-any.whl

kinemotion/{drop_jump → dropjump}/analysis.py

@@ -11,7 +11,7 @@ from ..core.smoothing import (
     interpolate_threshold_crossing,
 )
 from ..core.timing import NULL_TIMER, Timer
-from ..core.types import FOOT_KEYS, BoolArray, FloatArray
+from ..core.types import BoolArray, FloatArray
 
 
 class ContactState(Enum):
@@ -27,7 +27,7 @@ class ContactState(Enum):
     remove_in="1.0.0",
     since="0.34.0",
 )
-def _calculate_adaptive_threshold(
+def calculate_adaptive_threshold(
     positions: FloatArray,
     fps: float,
     baseline_duration: float = 3.0,
@@ -188,7 +188,7 @@ def _find_drop_from_baseline(
     return 0
 
 
-def _detect_drop_start(
+def detect_drop_start(
     positions: FloatArray,
     fps: float,
     min_stationary_duration: float = 1.0,
@@ -314,8 +314,6 @@ def _assign_contact_states(
 ) -> list[ContactState]:
     """Assign contact states based on contact frames and visibility.
 
-    Vectorized implementation for 2-3x speedup over loop-based version.
-
     Args:
         n_frames: Total number of frames
         contact_frames: Set of frames with confirmed contact
@@ -325,75 +323,15 @@ def _assign_contact_states(
     Returns:
         List of ContactState for each frame
     """
-    # Integer mapping for vectorized operations: IN_AIR=0, ON_GROUND=1, UNKNOWN=2
-    _state_order = [ContactState.IN_AIR, ContactState.ON_GROUND, ContactState.UNKNOWN]
-
-    # Initialize with IN_AIR (default)
-    states = np.zeros(n_frames, dtype=np.int8)
-
-    # Mark ON_GROUND where visibility is sufficient
-    if contact_frames:
-        contact_array = np.fromiter(contact_frames, dtype=int)
-        # Filter to valid indices only
-        valid_mask = (contact_array >= 0) & (contact_array < n_frames)
-        valid_contacts = contact_array[valid_mask]
-
-        # Only mark ON_GROUND for frames with good visibility
-        if visibilities is not None:
-            good_visibility = visibilities[valid_contacts] >= visibility_threshold
-            states[valid_contacts[good_visibility]] = 1
+    states = []
+    for i in range(n_frames):
+        if visibilities is not None and visibilities[i] < visibility_threshold:
+            states.append(ContactState.UNKNOWN)
+        elif i in contact_frames:
+            states.append(ContactState.ON_GROUND)
         else:
-            states[valid_contacts] = 1
-
-    # Mark UNKNOWN last (highest priority - overrides ON_GROUND)
-    if visibilities is not None:
-        unknown_mask = visibilities < visibility_threshold
-        states[unknown_mask] = 2
-
-    # Convert integer indices back to ContactState
-    return [_state_order[s] for s in states]
-
-
-def _compute_near_ground_mask(
-    foot_positions: FloatArray,
-    height_tolerance: float = 0.35,
-) -> BoolArray:
-    """Compute mask for frames where feet are near ground level.
-
-    Uses position-based filtering to identify frames near ground baseline.
-    In normalized coordinates: y=1 is bottom (ground), y=0 is top.
-
-    The ground baseline is established as the 90th percentile of positions,
-    which represents the typical ground level while handling outliers.
-
-    The tolerance is set at 35% of the position range by default, which is
-    generous enough to capture the full reactive contact phase (where athletes
-    maintain an athletic stance) while still filtering out the jump apex
-    (where y is much lower than ground level).
-
-    Args:
-        foot_positions: Array of foot y-positions (normalized, 0-1)
-        height_tolerance: Fraction of position range allowed above ground (default 35%)
-
-    Returns:
-        Boolean array where True indicates frame is near ground level
-    """
-    # Ground baseline: 90th percentile (where feet are typically on ground)
-    # Using 90th instead of 95th to be less sensitive to final landing positions
-    ground_baseline = float(np.percentile(foot_positions, 90))
-
-    # Compute position range for tolerance calculation
-    position_range = float(np.max(foot_positions) - np.min(foot_positions))
-
-    # Minimum absolute tolerance to handle small movements
-    min_tolerance = 0.03  # 3% of normalized range
-
-    # Height tolerance: percentage of position range or minimum
-    tolerance = max(position_range * height_tolerance, min_tolerance)
-
-    # Frames are near ground if y >= ground_baseline - tolerance
-    # (Remember: higher y = closer to ground in normalized coords)
-    return foot_positions >= (ground_baseline - tolerance)
+            states.append(ContactState.IN_AIR)
+    return states
 
 
 def detect_ground_contact(
@@ -405,14 +343,13 @@ def detect_ground_contact(
     window_length: int = 5,
     polyorder: int = 2,
     timer: Timer | None = None,
-    height_tolerance: float = 0.35,
 ) -> list[ContactState]:
     """
-    Detect when feet are in contact with ground based on vertical motion AND position.
+    Detect when feet are in contact with ground based on vertical motion.
 
-    Uses derivative-based velocity calculation via Savitzky-Golay filter for smooth,
-    accurate velocity estimates. Additionally uses position-based filtering to prevent
-    false ON_GROUND classification at jump apex where velocity approaches zero.
+    Uses derivative-based velocity calculation via Savitzky-Goyal filter for smooth,
+    accurate velocity estimates. This is consistent with the velocity calculation used
+    throughout the pipeline for sub-frame interpolation and curvature analysis.
 
     Args:
         foot_positions: Array of foot y-positions (normalized, 0-1, where 1 is bottom)
@@ -423,7 +360,6 @@ def detect_ground_contact(
         window_length: Window size for velocity derivative calculation (must be odd)
         polyorder: Polynomial order for Savitzky-Golay filter (default: 2)
         timer: Optional Timer for measuring operations
-        height_tolerance: Fraction of position range to allow above ground baseline (default 35%)
 
     Returns:
         List of ContactState for each frame
@@ -443,14 +379,6 @@ def detect_ground_contact(
     # Detect stationary frames based on velocity threshold
     is_stationary = np.abs(velocities) < velocity_threshold
 
-    # Position-based filtering to prevent false ON_GROUND at jump apex
-    # In normalized coords: y=1 is bottom (ground), y=0 is top
-    # Ground baseline is the 95th percentile (handles outliers)
-    is_near_ground = _compute_near_ground_mask(foot_positions, height_tolerance)
-
-    # Both conditions must be true: low velocity AND near ground
-    is_stationary = is_stationary & is_near_ground
-
     # Apply visibility filter
     is_stationary = _filter_stationary_with_visibility(
         is_stationary, visibilities, visibility_threshold
@@ -496,57 +424,6 @@ def find_contact_phases(
     return phases
 
 
-def _interpolate_phase_boundary(
-    boundary_idx: int,
-    state: ContactState,
-    velocities: FloatArray,
-    velocity_threshold: float,
-    is_start: bool,
-) -> float:
-    """Interpolate phase boundary with sub-frame precision.
-
-    Args:
-        boundary_idx: Index of the boundary frame
-        state: Contact state of the phase
-        velocities: Velocity array
-        velocity_threshold: Threshold value for crossing detection
-        is_start: True for phase start, False for phase end
-
-    Returns:
-        Fractional frame index, or float(boundary_idx) if no interpolation.
-    """
-    n_velocities = len(velocities)
-
-    if is_start:
-        # For start boundary, look at velocity before and at the boundary
-        if boundary_idx <= 0 or boundary_idx >= n_velocities:
-            return float(boundary_idx)
-        vel_before = velocities[boundary_idx - 1]
-        vel_at = velocities[boundary_idx]
-        # Check threshold crossing based on state
-        is_crossing = (
-            state == ContactState.ON_GROUND and vel_before > velocity_threshold > vel_at
-        ) or (state == ContactState.IN_AIR and vel_before < velocity_threshold < vel_at)
-        if is_crossing:
-            offset = interpolate_threshold_crossing(vel_before, vel_at, velocity_threshold)
-            return (boundary_idx - 1) + offset
-        return float(boundary_idx)
-
-    # For end boundary, look at velocity at and after the boundary
-    if boundary_idx + 1 >= n_velocities:
-        return float(boundary_idx)
-    vel_at = velocities[boundary_idx]
-    vel_after = velocities[boundary_idx + 1]
-    # Check threshold crossing based on state
-    is_crossing = (
-        state == ContactState.ON_GROUND and vel_at < velocity_threshold < vel_after
-    ) or (state == ContactState.IN_AIR and vel_at > velocity_threshold > vel_after)
-    if is_crossing:
-        offset = interpolate_threshold_crossing(vel_at, vel_after, velocity_threshold)
-        return boundary_idx + offset
-    return float(boundary_idx)
-
-
 def _interpolate_phase_start(
     start_idx: int,
     state: ContactState,
@@ -558,9 +435,21 @@ def _interpolate_phase_start(
     Returns:
         Fractional start frame, or float(start_idx) if no interpolation.
     """
-    return _interpolate_phase_boundary(
-        start_idx, state, velocities, velocity_threshold, is_start=True
-    )
+    if start_idx <= 0 or start_idx >= len(velocities):
+        return float(start_idx)
+
+    vel_before = velocities[start_idx - 1]
+    vel_at = velocities[start_idx]
+
+    # Check threshold crossing based on state
+    is_landing = state == ContactState.ON_GROUND and vel_before > velocity_threshold > vel_at
+    is_takeoff = state == ContactState.IN_AIR and vel_before < velocity_threshold < vel_at
+
+    if is_landing or is_takeoff:
+        offset = interpolate_threshold_crossing(vel_before, vel_at, velocity_threshold)
+        return (start_idx - 1) + offset
+
+    return float(start_idx)
 
 
 def _interpolate_phase_end(
@@ -568,19 +457,31 @@ def _interpolate_phase_end(
     state: ContactState,
     velocities: FloatArray,
     velocity_threshold: float,
-    _max_idx: int,
+    max_idx: int,
 ) -> float:
     """Interpolate end boundary of a phase with sub-frame precision.
 
     Returns:
         Fractional end frame, or float(end_idx) if no interpolation.
     """
-    return _interpolate_phase_boundary(
-        end_idx, state, velocities, velocity_threshold, is_start=False
-    )
+    if end_idx >= max_idx - 1 or end_idx + 1 >= len(velocities):
+        return float(end_idx)
+
+    vel_at = velocities[end_idx]
+    vel_after = velocities[end_idx + 1]
+
+    # Check threshold crossing based on state
+    is_takeoff = state == ContactState.ON_GROUND and vel_at < velocity_threshold < vel_after
+    is_landing = state == ContactState.IN_AIR and vel_at > velocity_threshold > vel_after
+
+    if is_takeoff or is_landing:
+        offset = interpolate_threshold_crossing(vel_at, vel_after, velocity_threshold)
+        return end_idx + offset
 
+    return float(end_idx)
 
-def _find_interpolated_phase_transitions(
+
+def find_interpolated_phase_transitions(
     foot_positions: FloatArray,
     contact_states: list[ContactState],
     velocity_threshold: float,
@@ -622,7 +523,7 @@ def _find_interpolated_phase_transitions(
     return interpolated_phases
 
 
-def _refine_transition_with_curvature(
+def refine_transition_with_curvature(
     foot_positions: FloatArray,
     estimated_frame: float,
     transition_type: str,
@@ -697,49 +598,7 @@ def _refine_transition_with_curvature(
     return refined_frame
 
 
-def _refine_phase_boundaries(
-    foot_positions: FloatArray,
-    start_frac: float,
-    end_frac: float,
-    start_type: str,
-    end_type: str,
-    smoothing_window: int,
-    polyorder: int,
-) -> tuple[float, float]:
-    """Refine phase boundary frames using curvature analysis.
-
-    Args:
-        foot_positions: Array of foot y-positions (normalized, 0-1)
-        start_frac: Start frame (fractional)
-        end_frac: End frame (fractional)
-        start_type: Transition type for start ("landing" or "takeoff")
-        end_type: Transition type for end ("landing" or "takeoff")
-        smoothing_window: Window size for acceleration computation
-        polyorder: Polynomial order for Savitzky-Golay filter
-
-    Returns:
-        Tuple of (refined_start, refined_end) fractional frame indices
-    """
-    refined_start = _refine_transition_with_curvature(
-        foot_positions,
-        start_frac,
-        start_type,
-        search_window=3,
-        smoothing_window=smoothing_window,
-        polyorder=polyorder,
-    )
-    refined_end = _refine_transition_with_curvature(
-        foot_positions,
-        end_frac,
-        end_type,
-        search_window=3,
-        smoothing_window=smoothing_window,
-        polyorder=polyorder,
-    )
-    return refined_start, refined_end
-
-
-def _find_interpolated_phase_transitions_with_curvature(
+def find_interpolated_phase_transitions_with_curvature(
     foot_positions: FloatArray,
     contact_states: list[ContactState],
     velocity_threshold: float,
@@ -767,7 +626,7 @@ def _find_interpolated_phase_transitions_with_curvature(
         List of (start_frame, end_frame, state) tuples with fractional frame indices
     """
     # Get interpolated phases using velocity
-    interpolated_phases = _find_interpolated_phase_transitions(
+    interpolated_phases = find_interpolated_phase_transitions(
         foot_positions, contact_states, velocity_threshold, smoothing_window
     )
 
@@ -778,63 +637,77 @@ def _find_interpolated_phase_transitions_with_curvature(
     refined_phases: list[tuple[float, float, ContactState]] = []
 
     for start_frac, end_frac, state in interpolated_phases:
+        refined_start = start_frac
+        refined_end = end_frac
+
         if state == ContactState.ON_GROUND:
-            # ON_GROUND: landing at start, takeoff at end
-            refined_start, refined_end = _refine_phase_boundaries(
+            # Refine landing (start of ground contact)
+            refined_start = refine_transition_with_curvature(
                 foot_positions,
                 start_frac,
-                end_frac,
                 "landing",
+                search_window=3,
+                smoothing_window=smoothing_window,
+                polyorder=polyorder,
+            )
+            # Refine takeoff (end of ground contact)
+            refined_end = refine_transition_with_curvature(
+                foot_positions,
+                end_frac,
                 "takeoff",
-                smoothing_window,
-                polyorder,
+                search_window=3,
+                smoothing_window=smoothing_window,
+                polyorder=polyorder,
             )
+
         elif state == ContactState.IN_AIR:
-            # IN_AIR: takeoff at start, landing at end
-            refined_start, refined_end = _refine_phase_boundaries(
+            # For flight phases, takeoff is at start, landing is at end
+            refined_start = refine_transition_with_curvature(
                 foot_positions,
                 start_frac,
-                end_frac,
                 "takeoff",
+                search_window=3,
+                smoothing_window=smoothing_window,
+                polyorder=polyorder,
+            )
+            refined_end = refine_transition_with_curvature(
+                foot_positions,
+                end_frac,
                 "landing",
-                smoothing_window,
-                polyorder,
+                search_window=3,
+                smoothing_window=smoothing_window,
+                polyorder=polyorder,
             )
-        else:
-            refined_start, refined_end = start_frac, end_frac
 
         refined_phases.append((refined_start, refined_end, state))
 
     return refined_phases
 
 
-def _find_landing_from_acceleration(
+def find_landing_from_acceleration(
     positions: FloatArray,
     accelerations: FloatArray,
     takeoff_frame: int,
     fps: float,
-    search_duration: float = 1.5,
+    search_duration: float = 0.7,
 ) -> int:
     """
-    Find landing frame using position-based detection with acceleration refinement.
+    Find landing frame by detecting impact acceleration after takeoff.
 
-    Primary method: Find when feet return to near-takeoff level after peak.
-    Secondary: Refine with acceleration spike if present.
-
-    For drop jumps, landing is defined as the first ground contact after the
-    reactive jump, when feet return to approximately the same level as takeoff.
+    Detects the moment of initial ground contact, characterized by a sharp
+    deceleration (positive acceleration spike) as downward velocity is arrested.
 
     Args:
-        positions: Array of vertical positions (normalized 0-1, where higher = closer to ground)
+        positions: Array of vertical positions (normalized 0-1)
         accelerations: Array of accelerations (second derivative)
         takeoff_frame: Frame at takeoff (end of ground contact)
         fps: Video frame rate
-        search_duration: Duration in seconds to search for landing (default: 1.5s)
+        search_duration: Duration in seconds to search for landing (default: 0.7s)
 
     Returns:
         Landing frame index (integer)
     """
-    # Extended search window to capture full flight
+    # Find peak height (minimum y value = highest point)
     search_start = takeoff_frame
     search_end = min(len(positions), takeoff_frame + int(fps * search_duration))
 
@@ -842,91 +715,61 @@ def _find_landing_from_acceleration(
         return min(len(positions) - 1, takeoff_frame + int(fps * 0.3))
 
     flight_positions = positions[search_start:search_end]
-
-    # Find peak height (minimum y value = highest point)
     peak_idx = int(np.argmin(flight_positions))
     peak_frame = search_start + peak_idx
 
-    # Get takeoff position as reference for landing detection
-    takeoff_position = positions[takeoff_frame]
-
-    # Position-based landing: find first frame after peak where position
-    # returns to within 5% of takeoff level (or 95% of the way back)
-    landing_threshold = takeoff_position - 0.05 * (takeoff_position - positions[peak_frame])
+    # After peak, look for landing (impact with ground)
+    # Landing is detected by maximum positive acceleration (deceleration on impact)
+    landing_search_start = peak_frame + 2
+    landing_search_end = min(len(accelerations), landing_search_start + int(fps * 0.6))
 
-    # Search for landing after peak
-    landing_frame = None
-    for i in range(peak_frame + 2, min(len(positions), search_end)):
-        if positions[i] >= landing_threshold:
-            landing_frame = i
-            break
+    if landing_search_end <= landing_search_start:
+        return min(len(positions) - 1, peak_frame + int(fps * 0.2))
 
-    # If position-based detection fails, use end of search window
-    if landing_frame is None:
-        landing_frame = min(len(positions) - 1, search_end - 1)
-
-    # Refine with acceleration if there's a clear impact spike
-    # Look for significant acceleration in a small window around the position-based landing
-    refine_start = max(peak_frame + 2, landing_frame - int(fps * 0.1))
-    refine_end = min(len(accelerations), landing_frame + int(fps * 0.1))
-
-    if refine_end > refine_start:
-        window_accelerations = accelerations[refine_start:refine_end]
-        # Check if there's a significant acceleration spike (> 3x median)
-        median_acc = float(np.median(np.abs(window_accelerations)))
-        max_acc_idx = int(np.argmax(np.abs(window_accelerations)))
-        max_acc = float(np.abs(window_accelerations[max_acc_idx]))
-
-        if median_acc > 0 and max_acc > 3 * median_acc:
-            # Use acceleration-refined landing frame
-            landing_frame = refine_start + max_acc_idx
+    # Find impact: maximum negative acceleration after peak (deceleration on impact)
+    # The impact creates a large upward force (negative acceleration in Y-down)
+    landing_accelerations = accelerations[landing_search_start:landing_search_end]
+    impact_idx = int(np.argmin(landing_accelerations))
+    landing_frame = landing_search_start + impact_idx
 
     return landing_frame
 
 
 def compute_average_foot_position(
     landmarks: dict[str, tuple[float, float, float]],
-    visibility_threshold: float = 0.5,
 ) -> tuple[float, float]:
     """
     Compute average foot position from ankle and foot landmarks.
 
-    Uses tiered visibility approach to avoid returning center (0.5, 0.5)
-    which can cause false phase transitions in contact detection.
-
     Args:
         landmarks: Dictionary of landmark positions
-        visibility_threshold: Minimum visibility to include landmark (default: 0.5)
 
     Returns:
         (x, y) average foot position in normalized coordinates
     """
-    # Collect all foot landmarks with their visibility
-    foot_data: list[tuple[float, float, float]] = []
-    for key in FOOT_KEYS:
-        if key in landmarks:
-            x, y, visibility = landmarks[key]
-            foot_data.append((x, y, visibility))
+    foot_keys = [
+        "left_ankle",
+        "right_ankle",
+        "left_heel",
+        "right_heel",
+        "left_foot_index",
+        "right_foot_index",
+    ]
 
-    if not foot_data:
-        # No foot landmarks at all - return center as last resort
-        return (0.5, 0.5)
+    x_positions = []
+    y_positions = []
 
-    # Tier 1: Use landmarks above visibility threshold
-    high_vis = [(x, y) for x, y, v in foot_data if v > visibility_threshold]
-    if high_vis:
-        xs, ys = zip(*high_vis, strict=False)
-        return (float(np.mean(xs)), float(np.mean(ys)))
+    for key in foot_keys:
+        if key in landmarks:
+            x, y, visibility = landmarks[key]
+            if visibility > 0.5:  # Only use visible landmarks
+                x_positions.append(x)
+                y_positions.append(y)
 
-    # Tier 2: Use landmarks with any reasonable visibility (> 0.1)
-    low_vis = [(x, y) for x, y, v in foot_data if v > 0.1]
-    if low_vis:
-        xs, ys = zip(*low_vis, strict=False)
-        return (float(np.mean(xs)), float(np.mean(ys)))
+    if not x_positions:
+        return (0.5, 0.5)  # Default to center if no visible feet
 
-    # Tier 3: Use highest visibility landmark regardless of threshold
-    best = max(foot_data, key=lambda t: t[2])
-    return (best[0], best[1])
+    return (float(np.mean(x_positions)), float(np.mean(y_positions)))
 
 
 def _calculate_average_visibility(
@@ -940,13 +783,8 @@ def _calculate_average_visibility(
     Returns:
         Average visibility of foot landmarks (0.0 if none visible)
     """
-    # Only use ankles and heels for visibility (foot_index can be noisy)
-    visibility_keys = ("left_ankle", "right_ankle", "left_heel", "right_heel")
-    foot_vis = [
-        frame_landmarks[key][2]
-        for key in FOOT_KEYS
-        if key in frame_landmarks and key in visibility_keys
-    ]
+    foot_keys = ["left_ankle", "right_ankle", "left_heel", "right_heel"]
+    foot_vis = [frame_landmarks[key][2] for key in foot_keys if key in frame_landmarks]
     return float(np.mean(foot_vis)) if foot_vis else 0.0
 
 
@@ -954,7 +792,7 @@ def _calculate_average_visibility(
     reason="Alternative implementation not called by pipeline",
     since="0.34.0",
 )
-def _extract_foot_positions_and_visibilities(
+def extract_foot_positions_and_visibilities(
     smoothed_landmarks: list[dict[str, tuple[float, float, float]] | None],
 ) -> tuple[np.ndarray, np.ndarray]:
     """