kinemotion 0.10.6__py3-none-any.whl → 0.67.0__py3-none-any.whl

kinemotion/dropjump/analysis.py

@@ -4,10 +4,14 @@ from enum import Enum
 
 import numpy as np
 
+from ..core.experimental import unused
 from ..core.smoothing import (
     compute_acceleration_from_derivative,
     compute_velocity_from_derivative,
+    interpolate_threshold_crossing,
 )
+from ..core.timing import NULL_TIMER, Timer
+from ..core.types import BoolArray, FloatArray
 
 
 class ContactState(Enum):
@@ -18,8 +22,13 @@ class ContactState(Enum):
     UNKNOWN = "unknown"
 
 
+@unused(
+    reason="Not called by analysis pipeline - awaiting CLI integration",
+    remove_in="1.0.0",
+    since="0.34.0",
+)
 def calculate_adaptive_threshold(
-    positions: np.ndarray,
+    positions: FloatArray,
     fps: float,
     baseline_duration: float = 3.0,
     multiplier: float = 1.5,
@@ -29,6 +38,18 @@ def calculate_adaptive_threshold(
     """
     Calculate adaptive velocity threshold based on baseline motion characteristics.
 
+    .. warning::
+        **Status: Implemented but Not Integrated**
+
+        This function is fully implemented and tested but not called by the
+        analysis pipeline. See ``docs/development/errors-findings.md`` for details.
+
+        **To integrate**: Add CLI parameter ``--use-adaptive-threshold`` and
+        call this function before contact detection.
+
+        **Roadmap**: Planned for Phase 2 if users report issues with varying
+        video conditions.
+
     Analyzes the first few seconds of video (assumed to be relatively stationary,
     e.g., athlete standing on box) to determine the noise floor, then sets threshold
     as a multiple of this baseline noise.
@@ -89,8 +110,86 @@ def calculate_adaptive_threshold(
     return adaptive_threshold
 
 
+def _find_stable_baseline(
+    positions: FloatArray,
+    min_stable_frames: int,
+    stability_threshold: float = 0.01,
+    debug: bool = False,
+) -> tuple[int, float]:
+    """Find first stable period and return baseline position.
+
+    Returns:
+        Tuple of (baseline_start_frame, baseline_position). Returns (-1, 0.0)
+        if not found.
+    """
+    stable_window = min_stable_frames
+
+    for start_idx in range(0, len(positions) - stable_window, 5):
+        window = positions[start_idx : start_idx + stable_window]
+        window_std = float(np.std(window))
+
+        if window_std < stability_threshold:
+            baseline_start = start_idx
+            baseline_position = float(np.median(window))
+
+            if debug:
+                end_frame = baseline_start + stable_window - 1
+                print("[detect_drop_start] Found stable period:")
+                print(f"  frames {baseline_start}-{end_frame}")
+                print(f"  baseline_position: {baseline_position:.4f}")
+                print(f"  baseline_std: {window_std:.4f} < {stability_threshold:.4f}")
+
+            return baseline_start, baseline_position
+
+    if debug:
+        print(
+            f"[detect_drop_start] No stable period found "
+            f"(variance always > {stability_threshold:.4f})"
+        )
+    return -1, 0.0
+
+
+def _find_drop_from_baseline(
+    positions: FloatArray,
+    baseline_start: int,
+    baseline_position: float,
+    stable_window: int,
+    position_change_threshold: float,
+    smoothing_window: int,
+    debug: bool = False,
+) -> int:
+    """Find drop start after stable baseline period.
+
+    Returns:
+        Drop frame index, or 0 if not found.
+    """
+    search_start = baseline_start + stable_window
+    window_size = max(3, smoothing_window)
+
+    for i in range(search_start, len(positions) - window_size):
+        window_positions = positions[i : i + window_size]
+        avg_position = float(np.mean(window_positions))
+        position_change = avg_position - baseline_position
+
+        if position_change > position_change_threshold:
+            drop_frame = max(baseline_start, i - window_size)
+
+            if debug:
+                print(f"[detect_drop_start] Drop detected at frame {drop_frame}")
+                print(
+                    f"  position_change: {position_change:.4f} > {position_change_threshold:.4f}"
+                )
+                print(f"  avg_position: {avg_position:.4f} vs baseline: {baseline_position:.4f}")
+
+            return drop_frame
+
+    if debug:
+        print("[detect_drop_start] No drop detected after stable period")
+    return 0
+
+
 def detect_drop_start(
-    positions: np.ndarray,
+    positions: FloatArray,
     fps: float,
     min_stationary_duration: float = 1.0,
     position_change_threshold: float = 0.02,
@@ -98,7 +197,8 @@ def detect_drop_start(
     debug: bool = False,
 ) -> int:
     """
-    Detect when the drop jump actually starts by finding stable period then detecting drop.
+    Detect when the drop jump actually starts by finding stable period then
+    detecting drop.
 
     Strategy:
     1. Scan forward to find first STABLE period (low variance over N frames)
@@ -110,7 +210,8 @@ def detect_drop_start(
     Args:
         positions: Array of vertical positions (0-1 normalized, y increases downward)
         fps: Video frame rate
-        min_stationary_duration: Minimum duration (seconds) of stable period (default: 1.0s)
+        min_stationary_duration: Minimum duration (seconds) of stable period
+            (default: 1.0s)
         position_change_threshold: Position change indicating start of drop
             (default: 0.02 = 2% of frame)
         smoothing_window: Window for computing position variance
@@ -126,99 +227,127 @@ def detect_drop_start(
         - Returns: 119
     """
     min_stable_frames = int(fps * min_stationary_duration)
-    if len(positions) < min_stable_frames + 30:  # Need some frames after stable period
+    if len(positions) < min_stable_frames + 30:
         if debug:
-            min_frames_needed = min_stable_frames + 30
             print(
-                f"[detect_drop_start] Video too short: {len(positions)} < {min_frames_needed}"
+                f"[detect_drop_start] Video too short: {len(positions)} < {min_stable_frames + 30}"
             )
         return 0
 
-    # STEP 1: Find first stable period by scanning forward
-    # Look for window with low variance (< 1% of frame height)
-    stability_threshold = 0.01  # 1% of frame height
-    stable_window = min_stable_frames
+    # Find stable baseline period
+    baseline_start, baseline_position = _find_stable_baseline(
+        positions, min_stable_frames, debug=debug
+    )
 
-    baseline_start = -1
-    baseline_position = 0.0
+    if baseline_start < 0:
+        return 0
 
-    # Scan from start, looking for stable window
-    for start_idx in range(0, len(positions) - stable_window, 5):  # Step by 5 frames
-        window = positions[start_idx : start_idx + stable_window]
-        window_std = float(np.std(window))
+    # Find drop from baseline
+    return _find_drop_from_baseline(
+        positions,
+        baseline_start,
+        baseline_position,
+        min_stable_frames,
+        position_change_threshold,
+        smoothing_window,
+        debug,
+    )
 
-        if window_std < stability_threshold:
-            # Found stable period!
-            baseline_start = start_idx
-            baseline_position = float(np.median(window))
 
-            if debug:
-                end_frame = baseline_start + stable_window - 1
-                print("[detect_drop_start] Found stable period:")
-                print(f"  frames {baseline_start}-{end_frame}")
-                print(f"  baseline_position: {baseline_position:.4f}")
-                print(f"  baseline_std: {window_std:.4f} < {stability_threshold:.4f}")
-            break
+def _filter_stationary_with_visibility(
+    is_stationary: BoolArray,
+    visibilities: FloatArray | None,
+    visibility_threshold: float,
+) -> BoolArray:
+    """Apply visibility filter to stationary flags.
 
-    if baseline_start < 0:
-        if debug:
-            msg = (
-                f"No stable period found (variance always > {stability_threshold:.4f})"
-            )
-            print(f"[detect_drop_start] {msg}")
-        return 0
+    Args:
+        is_stationary: Boolean array indicating stationary frames
+        visibilities: Optional visibility scores for each frame
+        visibility_threshold: Minimum visibility to trust landmark
 
-    # STEP 2: Find when position changes significantly from baseline
-    # Start searching after stable period ends
-    search_start = baseline_start + stable_window
-    window_size = max(3, smoothing_window)
+    Returns:
+        Filtered is_stationary array
+    """
+    if visibilities is not None:
+        is_visible = visibilities > visibility_threshold
+        return is_stationary & is_visible
+    return is_stationary
 
-    for i in range(search_start, len(positions) - window_size):
-        # Average position over small window to reduce noise
-        window_positions = positions[i : i + window_size]
-        avg_position = float(np.mean(window_positions))
 
-        # Check if position has increased (dropped) significantly
-        position_change = avg_position - baseline_position
+def _find_contact_frames(
+    is_stationary: BoolArray,
+    min_contact_frames: int,
+) -> set[int]:
+    """Find frames with sustained contact using minimum duration filter.
 
-        if position_change > position_change_threshold:
-            # Found start of drop - back up slightly to catch beginning
-            drop_frame_candidate = i - window_size
-            if drop_frame_candidate < baseline_start:
-                drop_frame = baseline_start
-            else:
-                drop_frame = drop_frame_candidate
+    Args:
+        is_stationary: Boolean array indicating stationary frames
+        min_contact_frames: Minimum consecutive frames to confirm contact
 
-            if debug:
-                print(f"[detect_drop_start] Drop detected at frame {drop_frame}")
-                print(
-                    f"  position_change: {position_change:.4f} > {position_change_threshold:.4f}"
-                )
-                print(
-                    f"  avg_position: {avg_position:.4f} vs baseline: {baseline_position:.4f}"
-                )
+    Returns:
+        Set of frame indices that meet minimum contact duration
+    """
+    contact_frames: set[int] = set()
+    current_run = []
 
-            return drop_frame
+    for i, stationary in enumerate(is_stationary):
+        if stationary:
+            current_run.append(i)
+        else:
+            if len(current_run) >= min_contact_frames:
+                contact_frames.update(current_run)
+            current_run = []
 
-    # No significant position change detected
-    if debug:
-        print("[detect_drop_start] No drop detected after stable period")
-    return 0
+    # Handle last run
+    if len(current_run) >= min_contact_frames:
+        contact_frames.update(current_run)
+
+    return contact_frames
+
+
+def _assign_contact_states(
+    n_frames: int,
+    contact_frames: set[int],
+    visibilities: FloatArray | None,
+    visibility_threshold: float,
+) -> list[ContactState]:
+    """Assign contact states based on contact frames and visibility.
+
+    Args:
+        n_frames: Total number of frames
+        contact_frames: Set of frames with confirmed contact
+        visibilities: Optional visibility scores for each frame
+        visibility_threshold: Minimum visibility to trust landmark
+
+    Returns:
+        List of ContactState for each frame
+    """
+    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.append(ContactState.IN_AIR)
+    return states
 
 
 def detect_ground_contact(
-    foot_positions: np.ndarray,
+    foot_positions: FloatArray,
     velocity_threshold: float = 0.02,
     min_contact_frames: int = 3,
     visibility_threshold: float = 0.5,
-    visibilities: np.ndarray | None = None,
+    visibilities: FloatArray | None = None,
     window_length: int = 5,
     polyorder: int = 2,
+    timer: Timer | None = None,
 ) -> list[ContactState]:
     """
     Detect when feet are in contact with ground based on vertical motion.
 
-    Uses derivative-based velocity calculation via Savitzky-Golay filter for smooth,
+    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.
 
@@ -230,57 +359,37 @@ def detect_ground_contact(
         visibilities: Array of visibility scores for each frame
         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
 
     Returns:
         List of ContactState for each frame
     """
+    timer = timer or NULL_TIMER
     n_frames = len(foot_positions)
-    states = [ContactState.UNKNOWN] * n_frames
 
     if n_frames < 2:
-        return states
+        return [ContactState.UNKNOWN] * n_frames
 
     # Compute vertical velocity using derivative-based method
-    # This provides smoother, more accurate velocity estimates than frame-to-frame differences
-    # and is consistent with the velocity calculation used for sub-frame interpolation
-    velocities = compute_velocity_from_derivative(
-        foot_positions, window_length=window_length, polyorder=polyorder
-    )
+    with timer.measure("dj_compute_velocity"):
+        velocities = compute_velocity_from_derivative(
+            foot_positions, window_length=window_length, polyorder=polyorder
+        )
 
-    # Detect potential contact frames based on low velocity
+    # Detect stationary frames based on velocity threshold
     is_stationary = np.abs(velocities) < velocity_threshold
 
     # Apply visibility filter
-    if visibilities is not None:
-        is_visible = visibilities > visibility_threshold
-        is_stationary = is_stationary & is_visible
-
-    # Apply minimum contact duration filter
-    contact_frames = []
-    current_run = []
-
-    for i, stationary in enumerate(is_stationary):
-        if stationary:
-            current_run.append(i)
-        else:
-            if len(current_run) >= min_contact_frames:
-                contact_frames.extend(current_run)
-            current_run = []
-
-    # Don't forget the last run
-    if len(current_run) >= min_contact_frames:
-        contact_frames.extend(current_run)
+    is_stationary = _filter_stationary_with_visibility(
+        is_stationary, visibilities, visibility_threshold
+    )
 
-    # Set states
-    for i in range(n_frames):
-        if visibilities is not None and visibilities[i] < visibility_threshold:
-            states[i] = ContactState.UNKNOWN
-        elif i in contact_frames:
-            states[i] = ContactState.ON_GROUND
-        else:
-            states[i] = ContactState.IN_AIR
+    # Find frames with sustained contact
+    with timer.measure("dj_find_contact_frames"):
+        contact_frames = _find_contact_frames(is_stationary, min_contact_frames)
 
-    return states
+    # Assign states
+    return _assign_contact_states(n_frames, contact_frames, visibilities, visibility_threshold)
 
 
 def find_contact_phases(
@@ -315,42 +424,65 @@ def find_contact_phases(
     return phases
 
 
-def interpolate_threshold_crossing(
-    vel_before: float,
-    vel_after: float,
+def _interpolate_phase_start(
+    start_idx: int,
+    state: ContactState,
+    velocities: FloatArray,
     velocity_threshold: float,
 ) -> float:
+    """Interpolate start boundary of a phase with sub-frame precision.
+
+    Returns:
+        Fractional start frame, or float(start_idx) if no interpolation.
     """
-    Find fractional offset where velocity crosses threshold between two frames.
+    if start_idx <= 0 or start_idx >= len(velocities):
+        return float(start_idx)
 
-    Uses linear interpolation assuming velocity changes linearly between frames.
+    vel_before = velocities[start_idx - 1]
+    vel_at = velocities[start_idx]
 
-    Args:
-        vel_before: Velocity at frame boundary N (absolute value)
-        vel_after: Velocity at frame boundary N+1 (absolute value)
-        velocity_threshold: Threshold value
+    # 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(
+    end_idx: int,
+    state: ContactState,
+    velocities: FloatArray,
+    velocity_threshold: float,
+    max_idx: int,
+) -> float:
+    """Interpolate end boundary of a phase with sub-frame precision.
 
     Returns:
-        Fractional offset from frame N (0.0 to 1.0)
+        Fractional end frame, or float(end_idx) if no interpolation.
     """
-    # Handle edge cases
-    if abs(vel_after - vel_before) < 1e-9:  # Velocity not changing
-        return 0.5
+    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]
 
-    # Linear interpolation: at what fraction t does velocity equal threshold?
-    # vel(t) = vel_before + t * (vel_after - vel_before)
-    # Solve for t when vel(t) = threshold:
-    # threshold = vel_before + t * (vel_after - vel_before)
-    # t = (threshold - vel_before) / (vel_after - vel_before)
+    # 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
 
-    t = (velocity_threshold - vel_before) / (vel_after - vel_before)
+    if is_takeoff or is_landing:
+        offset = interpolate_threshold_crossing(vel_at, vel_after, velocity_threshold)
+        return end_idx + offset
 
-    # Clamp to [0, 1] range
-    return float(max(0.0, min(1.0, t)))
+    return float(end_idx)
 
 
 def find_interpolated_phase_transitions(
-    foot_positions: np.ndarray,
+    foot_positions: FloatArray,
     contact_states: list[ContactState],
     velocity_threshold: float,
     smoothing_window: int = 5,
@@ -371,13 +503,10 @@ def find_interpolated_phase_transitions(
     Returns:
         List of (start_frame, end_frame, state) tuples with fractional frame indices
     """
-    # First get integer frame phases
     phases = find_contact_phases(contact_states)
     if not phases or len(foot_positions) < 2:
         return []
 
-    # Compute velocities from derivative of smoothed trajectory
-    # This gives much smoother velocity estimates than simple frame differences
     velocities = compute_velocity_from_derivative(
         foot_positions, window_length=smoothing_window, polyorder=2
     )
@@ -385,64 +514,17 @@ def find_interpolated_phase_transitions(
     interpolated_phases: list[tuple[float, float, ContactState]] = []
 
     for start_idx, end_idx, state in phases:
-        start_frac = float(start_idx)
-        end_frac = float(end_idx)
-
-        # Interpolate start boundary (transition INTO this phase)
-        if start_idx > 0 and start_idx < len(velocities):
-            vel_before = (
-                velocities[start_idx - 1] if start_idx > 0 else velocities[start_idx]
-            )
-            vel_at = velocities[start_idx]
-
-            # Check if we're crossing the threshold at this boundary
-            if state == ContactState.ON_GROUND:
-                # Transition air→ground: velocity dropping below threshold
-                if vel_before > velocity_threshold > vel_at:
-                    # Interpolate between start_idx-1 and start_idx
-                    offset = interpolate_threshold_crossing(
-                        vel_before, vel_at, velocity_threshold
-                    )
-                    start_frac = (start_idx - 1) + offset
-            elif state == ContactState.IN_AIR:
-                # Transition ground→air: velocity rising above threshold
-                if vel_before < velocity_threshold < vel_at:
-                    # Interpolate between start_idx-1 and start_idx
-                    offset = interpolate_threshold_crossing(
-                        vel_before, vel_at, velocity_threshold
-                    )
-                    start_frac = (start_idx - 1) + offset
-
-        # Interpolate end boundary (transition OUT OF this phase)
-        if end_idx < len(foot_positions) - 1 and end_idx + 1 < len(velocities):
-            vel_at = velocities[end_idx]
-            vel_after = velocities[end_idx + 1]
-
-            # Check if we're crossing the threshold at this boundary
-            if state == ContactState.ON_GROUND:
-                # Transition ground→air: velocity rising above threshold
-                if vel_at < velocity_threshold < vel_after:
-                    # Interpolate between end_idx and end_idx+1
-                    offset = interpolate_threshold_crossing(
-                        vel_at, vel_after, velocity_threshold
-                    )
-                    end_frac = end_idx + offset
-            elif state == ContactState.IN_AIR:
-                # Transition air→ground: velocity dropping below threshold
-                if vel_at > velocity_threshold > vel_after:
-                    # Interpolate between end_idx and end_idx+1
-                    offset = interpolate_threshold_crossing(
-                        vel_at, vel_after, velocity_threshold
-                    )
-                    end_frac = end_idx + offset
-
+        start_frac = _interpolate_phase_start(start_idx, state, velocities, velocity_threshold)
+        end_frac = _interpolate_phase_end(
+            end_idx, state, velocities, velocity_threshold, len(foot_positions)
+        )
         interpolated_phases.append((start_frac, end_frac, state))
 
     return interpolated_phases
 
 
 def refine_transition_with_curvature(
-    foot_positions: np.ndarray,
+    foot_positions: FloatArray,
     estimated_frame: float,
     transition_type: str,
     search_window: int = 3,
@@ -517,7 +599,7 @@ def refine_transition_with_curvature(
 
 
 def find_interpolated_phase_transitions_with_curvature(
-    foot_positions: np.ndarray,
+    foot_positions: FloatArray,
     contact_states: list[ContactState],
     velocity_threshold: float,
     smoothing_window: int = 5,
@@ -602,6 +684,57 @@ def find_interpolated_phase_transitions_with_curvature(
     return refined_phases
 
 
+def find_landing_from_acceleration(
+    positions: FloatArray,
+    accelerations: FloatArray,
+    takeoff_frame: int,
+    fps: float,
+    search_duration: float = 0.7,
+) -> int:
+    """
+    Find landing frame by detecting impact acceleration after 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)
+        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: 0.7s)
+
+    Returns:
+        Landing frame index (integer)
+    """
+    # Find peak height (minimum y value = highest point)
+    search_start = takeoff_frame
+    search_end = min(len(positions), takeoff_frame + int(fps * search_duration))
+
+    if search_end <= search_start:
+        return min(len(positions) - 1, takeoff_frame + int(fps * 0.3))
+
+    flight_positions = positions[search_start:search_end]
+    peak_idx = int(np.argmin(flight_positions))
+    peak_frame = search_start + peak_idx
+
+    # 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))
+
+    if landing_search_end <= landing_search_start:
+        return min(len(positions) - 1, peak_frame + int(fps * 0.2))
+
+    # 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]],
 ) -> tuple[float, float]:
@@ -637,3 +770,55 @@ def compute_average_foot_position(
         return (0.5, 0.5)  # Default to center if no visible feet
 
     return (float(np.mean(x_positions)), float(np.mean(y_positions)))
+
+
+def _calculate_average_visibility(
+    frame_landmarks: dict[str, tuple[float, float, float]],
+) -> float:
+    """Calculate average visibility of foot landmarks in a frame.
+
+    Args:
+        frame_landmarks: Landmark dictionary for a single frame
+
+    Returns:
+        Average visibility of foot landmarks (0.0 if none visible)
+    """
+    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
+
+
+@unused(
+    reason="Alternative implementation not called by pipeline",
+    since="0.34.0",
+)
+def extract_foot_positions_and_visibilities(
+    smoothed_landmarks: list[dict[str, tuple[float, float, float]] | None],
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Extract vertical positions and average visibilities from smoothed
+    landmarks.
+
+    This utility function eliminates code duplication between CLI and
+    programmatic usage.
+
+    Args:
+        smoothed_landmarks: Smoothed landmark sequence from tracking
+
+    Returns:
+        Tuple of (vertical_positions, visibilities) as numpy arrays
+    """
+    position_list: list[float] = []
+    visibilities_list: list[float] = []
+
+    for frame_landmarks in smoothed_landmarks:
+        if frame_landmarks:
+            _, foot_y = compute_average_foot_position(frame_landmarks)
+            position_list.append(foot_y)
+            visibilities_list.append(_calculate_average_visibility(frame_landmarks))
+        else:
+            # Fill missing frames with last known position or default
+            position_list.append(position_list[-1] if position_list else 0.5)
+            visibilities_list.append(0.0)
+
+    return np.array(position_list), np.array(visibilities_list)