kinemotion 0.12.0__py3-none-any.whl → 0.12.2__py3-none-any.whl

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/core/cli_utils.py

@@ -210,5 +210,3 @@ def common_output_options(func: Callable) -> Callable:  # type: ignore[type-arg]
         help="Path for JSON metrics output (default: stdout)",
     )(func)
     return func
-
-    return func

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/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/dropjump/analysis.py

@@ -89,6 +89,87 @@ def calculate_adaptive_threshold(
     return adaptive_threshold
 
 
+def _find_stable_baseline(
+    positions: np.ndarray,
+    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: np.ndarray,
+    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} > "
+                    f"{position_change_threshold:.4f}"
+                )
+                print(
+                    f"  avg_position: {avg_position:.4f} vs "
+                    f"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,
     fps: float,
@@ -126,84 +207,32 @@ 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)} < "
+                f"{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
-
-    baseline_start = -1
-    baseline_position = 0.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))
-
-        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
+    # Find stable baseline period
+    baseline_start, baseline_position = _find_stable_baseline(
+        positions, min_stable_frames, debug=debug
+    )
 
     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
 
-    # 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)
-
-    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
-
-        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
-
-            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
-
-    # No significant position change detected
-    if debug:
-        print("[detect_drop_start] No drop detected after stable period")
-    return 0
+    # Find drop from baseline
+    return _find_drop_from_baseline(
+        positions,
+        baseline_start,
+        baseline_position,
+        min_stable_frames,
+        position_change_threshold,
+        smoothing_window,
+        debug,
+    )
 
 
 def detect_ground_contact(
@@ -349,6 +378,71 @@ def interpolate_threshold_crossing(
     return float(max(0.0, min(1.0, t)))
 
 
+def _interpolate_phase_start(
+    start_idx: int,
+    state: ContactState,
+    velocities: np.ndarray,
+    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.
+    """
+    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(
+    end_idx: int,
+    state: ContactState,
+    velocities: np.ndarray,
+    velocity_threshold: float,
+    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.
+    """
+    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(
     foot_positions: np.ndarray,
     contact_states: list[ContactState],
@@ -371,13 +465,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,57 +476,12 @@ 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

kinemotion/dropjump/cli.py

@@ -413,13 +413,11 @@ def _process_single(
                 contact_states,
                 vertical_positions,
                 video.fps,
-                drop_height_m=None,
                 drop_start_frame=expert_params.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,
             )
 
             # Output metrics

kinemotion/dropjump/debug_overlay.py

@@ -12,6 +12,109 @@ from .kinematics import DropJumpMetrics
 class DebugOverlayRenderer(BaseDebugOverlayRenderer):
     """Renders debug information on video frames."""
 
+    def _draw_com_visualization(
+        self,
+        frame: np.ndarray,
+        landmarks: dict[str, tuple[float, float, float]],
+        contact_state: ContactState,
+    ) -> None:
+        """Draw center of mass visualization on frame."""
+        com_x, com_y, _ = compute_center_of_mass(landmarks)
+        px = int(com_x * self.width)
+        py = int(com_y * self.height)
+
+        color = (0, 255, 0) if contact_state == ContactState.ON_GROUND else (0, 0, 255)
+        cv2.circle(frame, (px, py), 15, color, -1)
+        cv2.circle(frame, (px, py), 17, (255, 255, 255), 2)
+
+        # Draw hip midpoint reference
+        if "left_hip" in landmarks and "right_hip" in landmarks:
+            lh_x, lh_y, _ = landmarks["left_hip"]
+            rh_x, rh_y, _ = landmarks["right_hip"]
+            hip_x = int((lh_x + rh_x) / 2 * self.width)
+            hip_y = int((lh_y + rh_y) / 2 * self.height)
+            cv2.circle(frame, (hip_x, hip_y), 8, (255, 165, 0), -1)
+            cv2.line(frame, (hip_x, hip_y), (px, py), (255, 165, 0), 2)
+
+    def _draw_foot_visualization(
+        self,
+        frame: np.ndarray,
+        landmarks: dict[str, tuple[float, float, float]],
+        contact_state: ContactState,
+    ) -> None:
+        """Draw foot position visualization on frame."""
+        foot_x, foot_y = compute_average_foot_position(landmarks)
+        px = int(foot_x * self.width)
+        py = int(foot_y * self.height)
+
+        color = (0, 255, 0) if contact_state == ContactState.ON_GROUND else (0, 0, 255)
+        cv2.circle(frame, (px, py), 10, color, -1)
+
+        # Draw individual foot landmarks
+        foot_keys = ["left_ankle", "right_ankle", "left_heel", "right_heel"]
+        for key in foot_keys:
+            if key in landmarks:
+                x, y, vis = landmarks[key]
+                if vis > 0.5:
+                    lx = int(x * self.width)
+                    ly = int(y * self.height)
+                    cv2.circle(frame, (lx, ly), 5, (255, 255, 0), -1)
+
+    def _draw_phase_labels(
+        self,
+        frame: np.ndarray,
+        frame_idx: int,
+        metrics: DropJumpMetrics,
+    ) -> None:
+        """Draw phase labels (ground contact, flight, peak) on frame."""
+        y_offset = 110
+
+        # Ground contact phase
+        if (
+            metrics.contact_start_frame
+            and metrics.contact_end_frame
+            and metrics.contact_start_frame <= frame_idx <= metrics.contact_end_frame
+        ):
+            cv2.putText(
+                frame,
+                "GROUND CONTACT",
+                (10, y_offset),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                0.7,
+                (0, 255, 0),
+                2,
+            )
+            y_offset += 40
+
+        # Flight phase
+        if (
+            metrics.flight_start_frame
+            and metrics.flight_end_frame
+            and metrics.flight_start_frame <= frame_idx <= metrics.flight_end_frame
+        ):
+            cv2.putText(
+                frame,
+                "FLIGHT PHASE",
+                (10, y_offset),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                0.7,
+                (0, 0, 255),
+                2,
+            )
+            y_offset += 40
+
+        # Peak height
+        if metrics.peak_height_frame == frame_idx:
+            cv2.putText(
+                frame,
+                "PEAK HEIGHT",
+                (10, y_offset),
+                cv2.FONT_HERSHEY_SIMPLEX,
+                0.7,
+                (255, 0, 255),
+                2,
+            )
+
     def render_frame(
         self,
         frame: np.ndarray,
@@ -37,67 +140,20 @@ class DebugOverlayRenderer(BaseDebugOverlayRenderer):
         """
         annotated = frame.copy()
 
-        # Draw landmarks if available
+        # Draw landmarks
         if landmarks:
             if use_com:
-                # Draw center of mass position
-                com_x, com_y, _ = compute_center_of_mass(landmarks)  # com_vis not used
-                px = int(com_x * self.width)
-                py = int(com_y * self.height)
-
-                # Draw CoM with larger circle
-                color = (
-                    (0, 255, 0)
-                    if contact_state == ContactState.ON_GROUND
-                    else (0, 0, 255)
-                )
-                cv2.circle(annotated, (px, py), 15, color, -1)
-                cv2.circle(annotated, (px, py), 17, (255, 255, 255), 2)  # White border
-
-                # Draw body segments for reference
-                # Draw hip midpoint
-                if "left_hip" in landmarks and "right_hip" in landmarks:
-                    lh_x, lh_y, _ = landmarks["left_hip"]
-                    rh_x, rh_y, _ = landmarks["right_hip"]
-                    hip_x = int((lh_x + rh_x) / 2 * self.width)
-                    hip_y = int((lh_y + rh_y) / 2 * self.height)
-                    cv2.circle(
-                        annotated, (hip_x, hip_y), 8, (255, 165, 0), -1
-                    )  # Orange
-                    # Draw line from hip to CoM
-                    cv2.line(annotated, (hip_x, hip_y), (px, py), (255, 165, 0), 2)
+                self._draw_com_visualization(annotated, landmarks, contact_state)
             else:
-                # Draw foot position (original method)
-                foot_x, foot_y = compute_average_foot_position(landmarks)
-                px = int(foot_x * self.width)
-                py = int(foot_y * self.height)
-
-                # Draw foot position circle
-                color = (
-                    (0, 255, 0)
-                    if contact_state == ContactState.ON_GROUND
-                    else (0, 0, 255)
-                )
-                cv2.circle(annotated, (px, py), 10, color, -1)
-
-                # Draw individual foot landmarks
-                foot_keys = ["left_ankle", "right_ankle", "left_heel", "right_heel"]
-                for key in foot_keys:
-                    if key in landmarks:
-                        x, y, vis = landmarks[key]
-                        if vis > 0.5:
-                            lx = int(x * self.width)
-                            ly = int(y * self.height)
-                            cv2.circle(annotated, (lx, ly), 5, (255, 255, 0), -1)
+                self._draw_foot_visualization(annotated, landmarks, contact_state)
 
         # Draw contact state
-        state_text = f"State: {contact_state.value}"
         state_color = (
             (0, 255, 0) if contact_state == ContactState.ON_GROUND else (0, 0, 255)
         )
         cv2.putText(
             annotated,
-            state_text,
+            f"State: {contact_state.value}",
             (10, 30),
             cv2.FONT_HERSHEY_SIMPLEX,
             1,
@@ -116,52 +172,8 @@ class DebugOverlayRenderer(BaseDebugOverlayRenderer):
             2,
         )
 
-        # Draw metrics if in relevant phase
+        # Draw phase labels
         if metrics:
-            y_offset = 110
-            if (
-                metrics.contact_start_frame
-                and metrics.contact_end_frame
-                and metrics.contact_start_frame
-                <= frame_idx
-                <= metrics.contact_end_frame
-            ):
-                cv2.putText(
-                    annotated,
-                    "GROUND CONTACT",
-                    (10, y_offset),
-                    cv2.FONT_HERSHEY_SIMPLEX,
-                    0.7,
-                    (0, 255, 0),
-                    2,
-                )
-                y_offset += 40
-
-            if (
-                metrics.flight_start_frame
-                and metrics.flight_end_frame
-                and metrics.flight_start_frame <= frame_idx <= metrics.flight_end_frame
-            ):
-                cv2.putText(
-                    annotated,
-                    "FLIGHT PHASE",
-                    (10, y_offset),
-                    cv2.FONT_HERSHEY_SIMPLEX,
-                    0.7,
-                    (0, 0, 255),
-                    2,
-                )
-                y_offset += 40
-
-            if metrics.peak_height_frame == frame_idx:
-                cv2.putText(
-                    annotated,
-                    "PEAK HEIGHT",
-                    (10, y_offset),
-                    cv2.FONT_HERSHEY_SIMPLEX,
-                    0.7,
-                    (255, 0, 255),
-                    2,
-                )
+            self._draw_phase_labels(annotated, frame_idx, metrics)
 
         return annotated

kinemotion/dropjump/kinematics.py

@@ -255,55 +255,6 @@ def _find_precise_phase_timing(
     return contact_start_frac, contact_end_frac
 
 
-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 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]],
@@ -311,9 +262,6 @@ def _analyze_flight_phase(
     contact_end: int,
     foot_y_positions: np.ndarray,
     fps: float,
-    drop_height_m: float | None,
-    scale_factor: float,
-    kinematic_correction_factor: float,
     smoothing_window: int,
     polyorder: int,
 ) -> None:
@@ -329,9 +277,6 @@ def _analyze_flight_phase(
         contact_end: End of contact phase
         foot_y_positions: Vertical position array
         fps: Video frame rate
-        drop_height_m: Known drop height (optional, for RSI calculation)
-        scale_factor: Calibration scale factor
-        kinematic_correction_factor: Correction for kinematic method
         smoothing_window: Window size for acceleration computation
         polyorder: Polynomial order for Savitzky-Golay filter
     """
@@ -398,29 +343,26 @@ 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.
 
+    Jump height is calculated from flight time using kinematic formula: h = g × t² / 8
+
     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)
+        drop_start_frame: Optional manual drop start frame
         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
@@ -489,11 +431,6 @@ def calculate_drop_jump_metrics(
     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,
@@ -502,9 +439,6 @@ def calculate_drop_jump_metrics(
         contact_end,
         foot_y_positions,
         fps,
-        drop_height_m,
-        scale_factor,
-        kinematic_correction_factor,
         smoothing_window,
         polyorder,
     )

{kinemotion-0.12.0.dist-info → kinemotion-0.12.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.12.0
+Version: 0.12.2
 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.0.dist-info → kinemotion-0.12.2.dist-info}/RECORD

@@ -1,5 +1,5 @@
 kinemotion/__init__.py,sha256=REBC9wrwYC_grvCS00qEOyign65Zc1sc-5buLpyqQxA,654
-kinemotion/api.py,sha256=-m4KnlpXWswNyHc_keuNtKZKy8EONSUqrSTNtvoq_OA,31193
+kinemotion/api.py,sha256=jcUVn8UHysj8GNzdNShf3y2pp20G4iTBb1jvkpptUvU,31116
 kinemotion/cli.py,sha256=cqYV_7URH0JUDy1VQ_EDLv63FmNO4Ns20m6s1XAjiP4,464
 kinemotion/cmj/__init__.py,sha256=Ynv0-Oco4I3Y1Ubj25m3h9h2XFqeNwpAewXmAYOmwfU,127
 kinemotion/cmj/analysis.py,sha256=4HYGn4VDIB6oExAees-VcPfpNgWOltpgwjyNTU7YAb4,18263
@@ -9,20 +9,20 @@ kinemotion/cmj/joint_angles.py,sha256=8ucpDGPvbt4iX3tx9eVxJEUv0laTm2Y58_--VzJCog
 kinemotion/cmj/kinematics.py,sha256=Xl_PlC2OqMoA-zOc3SRB_GqI0AgLlJol5FTPe5J_qLc,7573
 kinemotion/core/__init__.py,sha256=3yzDhb5PekDNjydqrs8aWGneUGJBt-lB0SoB_Y2FXqU,1010
 kinemotion/core/auto_tuning.py,sha256=cvmxUI-CbahpOJQtR2r5jOx4Q6yKPe3DO1o15hOQIdw,10508
-kinemotion/core/cli_utils.py,sha256=uCGOsXRpxhRpu8VW9b3tAsHBySyaVl_YMMVCrEZqB-Y,7271
+kinemotion/core/cli_utils.py,sha256=Pq1JF7yvK1YbH0tOUWKjplthCbWsJQt4Lv7esPYH4FM,7254
 kinemotion/core/debug_overlay_utils.py,sha256=TyUb5okv5qw8oeaX3jsUO_kpwf1NnaHEAOTm-8LwTno,4587
 kinemotion/core/filtering.py,sha256=f-m-aA59e4WqE6u-9MA51wssu7rI-Y_7n1cG8IWdeRQ,11241
-kinemotion/core/pose.py,sha256=Wfd1RR-2ZznYpWeQUbySwcV3mvReqn8n3XO6S7pGq4M,8390
-kinemotion/core/smoothing.py,sha256=Zdhqw4NyCrZaEb-Jo3sASzP-QlEL5sVTgHoXU8zT_xU,14136
+kinemotion/core/pose.py,sha256=ztemdZ_ysVVK3gbXabm8qS_dr1VfJX9KZjmcO-Z-iNE,8532
+kinemotion/core/smoothing.py,sha256=C9GK3PAN16RpqJw2UWeVslSTJZEvALeVADjtnJnSF88,14240
 kinemotion/core/video_io.py,sha256=UtmUndw22uFnZBK_BmeE912yRYH1YnU_P8LjuN33DPc,6461
 kinemotion/dropjump/__init__.py,sha256=yc1XiZ9vfo5h_n7PKVSiX2TTgaIfGL7Y7SkQtiDZj_E,838
-kinemotion/dropjump/analysis.py,sha256=crO0SUq8TiMHdK5hPuHHuOFrEGhGdPoeb5rXQUvqCog,26103
-kinemotion/dropjump/cli.py,sha256=emnMlg2Td4iS7go9ckTFnolPEytX9MKoPRhfjBwyArU,21731
-kinemotion/dropjump/debug_overlay.py,sha256=2L4VAZwWFnaOQ7LAF3ALXCjEaVNzkfpLT5-h0qKL_6g,5707
-kinemotion/dropjump/kinematics.py,sha256=bHQFeBHGNDKyusHKN_hHmeNHLEK2xMIHBMvL2tScm88,17935
+kinemotion/dropjump/analysis.py,sha256=PoBzlqciBFB_O7ejdjBhpnk19a_VoD31tDjXuN1-ovo,25764
+kinemotion/dropjump/cli.py,sha256=90GddzgMLwEKKwcG0VW94HeXFwEK5zSJm6w6UkPbaRk,21646
+kinemotion/dropjump/debug_overlay.py,sha256=LkPw6ucb7beoYWS4L-Lvjs1KLCm5wAWDAfiznUeV2IQ,5668
+kinemotion/dropjump/kinematics.py,sha256=txDxpDti3VJVctWGbe3aIrlIx83UY8-ynzlX01TOvTA,15577
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.12.0.dist-info/METADATA,sha256=bwCv7u1ErLWVmzFcFYK_Lx7_XRAOajSp6YFTYWtXhRg,18990
-kinemotion-0.12.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.12.0.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.12.0.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.12.0.dist-info/RECORD,,
+kinemotion-0.12.2.dist-info/METADATA,sha256=FE1-EfYL73UDQE9xBj-qRCQ51PN6F1SylDmVJrt974s,18990
+kinemotion-0.12.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kinemotion-0.12.2.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.12.2.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.12.2.dist-info/RECORD,,