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

kinemotion/{drop_jump → dropjump}/kinematics.py

@@ -10,10 +10,10 @@ from ..core.smoothing import compute_acceleration_from_derivative
 from ..core.timing import NULL_TIMER, Timer
 from .analysis import (
     ContactState,
-    _detect_drop_start,  # pyright: ignore[reportPrivateUsage]
-    _find_interpolated_phase_transitions_with_curvature,  # pyright: ignore[reportPrivateUsage]
-    _find_landing_from_acceleration,  # pyright: ignore[reportPrivateUsage]
+    detect_drop_start,
     find_contact_phases,
+    find_interpolated_phase_transitions_with_curvature,
+    find_landing_from_acceleration,
 )
 
 if TYPE_CHECKING:
@@ -159,7 +159,7 @@ def _determine_drop_start_frame(
     """
     if drop_start_frame is None:
         # Auto-detect where drop jump actually starts (skip initial stationary period)
-        return _detect_drop_start(
+        return detect_drop_start(
             foot_y_positions,
             fps,
             min_stationary_duration=0.5,
@@ -226,106 +226,14 @@ def _compute_robust_phase_position(
     return float(np.median(window_positions))
 
 
-def _detect_drop_jump_air_first_pattern(
-    air_phases_indexed: list[tuple[int, int, int]],
-    ground_phases: list[tuple[int, int, int]],
-) -> tuple[int, int] | None:
-    """Detect drop jump using air-first pattern (box + drop classified as IN_AIR).
-
-    Pattern: IN_AIR(box+drop) → ON_GROUND(contact) → IN_AIR(flight) → ON_GROUND(land)
-
-    Args:
-        air_phases_indexed: Air phases with indices
-        ground_phases: Ground phases with indices
-
-    Returns:
-        (contact_start, contact_end) if drop jump detected, None otherwise
-    """
-    if not air_phases_indexed or len(ground_phases) < 2:
-        return None
-
-    _, _, first_air_idx = air_phases_indexed[0]
-    first_ground_start, first_ground_end, first_ground_idx = ground_phases[0]
-
-    # Drop jump: first phase is IN_AIR (index 0), second phase is ground (index 1)
-    if first_air_idx != 0 or first_ground_idx != 1:
-        return None
-
-    # Check for flight phase after contact
-    air_after_contact = [i for _, _, i in air_phases_indexed if i > first_ground_idx]
-    if not air_after_contact:
-        return None
-
-    return first_ground_start, first_ground_end
-
-
-def _detect_drop_jump_height_pattern(
-    air_phases_indexed: list[tuple[int, int, int]],
-    ground_phases: list[tuple[int, int, int]],
-    foot_y_positions: NDArray[np.float64],
-) -> tuple[int, int] | None:
-    """Detect drop jump using height comparison (box detected as ground).
-
-    Legacy detection: first ground is on elevated box (lower y value).
-
-    Args:
-        air_phases_indexed: Air phases with indices
-        ground_phases: Ground phases with indices
-        foot_y_positions: Vertical position array
-
-    Returns:
-        (contact_start, contact_end) if drop jump detected, None otherwise
-    """
-    if not air_phases_indexed or len(ground_phases) < 2:
-        return None
-
-    _, _, first_air_idx = air_phases_indexed[0]
-    first_ground_start, first_ground_end, first_ground_idx = ground_phases[0]
-
-    # This pattern: first ground is before first air (athlete on box)
-    if first_ground_idx >= first_air_idx:
-        return None
-
-    ground_after_air = [
-        (start, end, idx) for start, end, idx in ground_phases if idx > first_air_idx
-    ]
-    if not ground_after_air:
-        return None
-
-    first_ground_y = _compute_robust_phase_position(
-        foot_y_positions, first_ground_start, first_ground_end
-    )
-    second_ground_start, second_ground_end, _ = ground_after_air[0]
-    second_ground_y = _compute_robust_phase_position(
-        foot_y_positions, second_ground_start, second_ground_end
-    )
-
-    # If second ground is significantly lower (>7% of frame), it's a drop jump
-    height_diff = second_ground_y - first_ground_y
-    if height_diff <= 0.07:
-        return None
-
-    return second_ground_start, second_ground_end
-
-
 def _identify_main_contact_phase(
-    phases: list[tuple[int, int, ContactState]],  # noqa: ARG001  # Used in caller for context
+    phases: list[tuple[int, int, ContactState]],
     ground_phases: list[tuple[int, int, int]],
     air_phases_indexed: list[tuple[int, int, int]],
     foot_y_positions: NDArray[np.float64],
 ) -> tuple[int, int, bool]:
     """Identify the main contact phase and determine if it's a drop jump.
 
-    Drop jump detection strategy:
-    1. With position-based filtering, box period is classified as IN_AIR
-    2. Pattern: IN_AIR(box+drop) → ON_GROUND(contact) → IN_AIR(flight) → ON_GROUND(land)
-    3. The FIRST ground phase is the contact phase (before the flight)
-    4. The LAST ground phase is the landing (after the flight)
-
-    The key differentiator from regular jump:
-    - Drop jump: starts with IN_AIR, has 2+ ground phases with air between them
-    - Regular jump: starts with ON_GROUND, may have multiple phases
-
     Args:
         phases: All phase tuples
         ground_phases: Ground phases with indices
@@ -335,21 +243,46 @@ def _identify_main_contact_phase(
     Returns:
         Tuple of (contact_start, contact_end, is_drop_jump)
     """
-    # Try air-first detection pattern (most common for clean videos)
-    result = _detect_drop_jump_air_first_pattern(air_phases_indexed, ground_phases)
-    if result is not None:
-        return result[0], result[1], True
-
-    # Try height-based detection (fallback for box-as-ground videos)
-    result = _detect_drop_jump_height_pattern(air_phases_indexed, ground_phases, foot_y_positions)
-    if result is not None:
-        return result[0], result[1], True
-
-    # Regular jump: use longest ground contact phase
-    contact_start, contact_end = max(
-        [(s, e) for s, e, _ in ground_phases], key=lambda p: p[1] - p[0]
-    )
-    return contact_start, contact_end, False
+    # Initialize with first ground phase as fallback
+    contact_start, contact_end = ground_phases[0][0], ground_phases[0][1]
+    is_drop_jump = False
+
+    # Detect if this is a drop jump or regular jump
+    if air_phases_indexed and len(ground_phases) >= 2:
+        first_ground_start, first_ground_end, first_ground_idx = ground_phases[0]
+        first_air_idx = air_phases_indexed[0][2]
+
+        # Find ground phase after first air phase
+        ground_after_air = [
+            (start, end, idx) for start, end, idx in ground_phases if idx > first_air_idx
+        ]
+
+        if ground_after_air and first_ground_idx < first_air_idx:
+            # Check if first ground is at higher elevation (lower y) than
+            # ground after air using robust temporal averaging
+            first_ground_y = _compute_robust_phase_position(
+                foot_y_positions, first_ground_start, first_ground_end
+            )
+            second_ground_start, second_ground_end, _ = ground_after_air[0]
+            second_ground_y = _compute_robust_phase_position(
+                foot_y_positions, second_ground_start, second_ground_end
+            )
+
+            # If first ground is significantly higher (>7% of frame), it's a drop jump
+            # Increased from 0.05 to 0.07 with 11-frame temporal averaging
+            # for reproducibility (balances detection sensitivity with noise robustness)
+            # Note: MediaPipe has inherent non-determinism (Google issue #3945)
+            if second_ground_y - first_ground_y > 0.07:
+                is_drop_jump = True
+                contact_start, contact_end = second_ground_start, second_ground_end
+
+    if not is_drop_jump:
+        # Regular jump: use longest ground contact phase
+        contact_start, contact_end = max(
+            [(s, e) for s, e, _ in ground_phases], key=lambda p: p[1] - p[0]
+        )
+
+    return contact_start, contact_end, is_drop_jump
 
 
 def _find_precise_phase_timing(
@@ -384,30 +317,6 @@ def _find_precise_phase_timing(
     return contact_start_frac, contact_end_frac
 
 
-def _find_landing_from_phases(
-    phases: list[tuple[int, int, ContactState]],
-    flight_start: int,
-) -> int | None:
-    """Find landing frame from phase detection.
-
-    Looks for the first ON_GROUND phase that starts after the flight_start frame.
-    This represents the first ground contact after the reactive jump.
-
-    Args:
-        phases: List of (start, end, state) phase tuples
-        flight_start: Frame where flight begins (takeoff)
-
-    Returns:
-        Landing frame (start of landing phase), or None if not found
-    """
-    for start, _, state in phases:
-        if state == ContactState.ON_GROUND and start > flight_start:
-            # Found the landing phase - return its start frame
-            return start
-
-    return None
-
-
 def _analyze_flight_phase(
     metrics: DropJumpMetrics,
     phases: list[tuple[int, int, ContactState]],
@@ -436,20 +345,22 @@ def _analyze_flight_phase(
     # Find takeoff frame (end of ground contact)
     flight_start = contact_end
 
-    # Use phase detection for landing (more accurate than position-based)
-    # Find the next ON_GROUND phase after the flight phase
-    flight_end = _find_landing_from_phases(phases, flight_start)
+    # Compute accelerations for landing detection
+    accelerations = compute_acceleration_from_derivative(
+        foot_y_positions, window_length=smoothing_window, polyorder=polyorder
+    )
 
-    # If phase detection fails, fall back to position-based detection
-    if flight_end is None:
-        accelerations = compute_acceleration_from_derivative(
-            foot_y_positions, window_length=smoothing_window, polyorder=polyorder
-        )
-        flight_end = _find_landing_from_acceleration(
-            foot_y_positions, accelerations, flight_start, fps
-        )
+    # Use acceleration-based landing detection (like CMJ)
+    # This finds the actual ground impact, not just when velocity drops
+    flight_end = find_landing_from_acceleration(
+        foot_y_positions, accelerations, flight_start, fps, search_duration=0.7
+    )
 
-    # Find precise sub-frame timing for takeoff and landing
+    # Store integer frame indices
+    metrics.flight_start_frame = flight_start
+    metrics.flight_end_frame = flight_end
+
+    # Find precise sub-frame timing for takeoff
     flight_start_frac = float(flight_start)
     flight_end_frac = float(flight_end)
 
@@ -462,20 +373,6 @@ def _analyze_flight_phase(
             flight_start_frac = end_frac
             break
 
-    # Find interpolated landing (start of landing ON_GROUND phase)
-    for start_frac, _, state in interpolated_phases:
-        if state == ContactState.ON_GROUND and int(start_frac) >= flight_end - 2:
-            flight_end_frac = start_frac
-            break
-
-    # Refine landing frame using floor of interpolated value
-    # This compensates for velocity-based detection being ~1-2 frames late
-    refined_flight_end = int(np.floor(flight_end_frac))
-
-    # Store integer frame indices (refined using interpolated values)
-    metrics.flight_start_frame = flight_start
-    metrics.flight_end_frame = refined_flight_end
-
     # Calculate flight time
     flight_frames_precise = flight_end_frac - flight_start_frac
     metrics.flight_time = flight_frames_precise / fps
@@ -559,7 +456,7 @@ def calculate_drop_jump_metrics(
     # Find contact phases
     with timer.measure("dj_find_phases"):
         phases = find_contact_phases(contact_states)
-        interpolated_phases = _find_interpolated_phase_transitions_with_curvature(
+        interpolated_phases = find_interpolated_phase_transitions_with_curvature(
             foot_y_positions,
             contact_states,
             velocity_threshold,
@@ -600,22 +497,15 @@ def calculate_drop_jump_metrics(
             phases, ground_phases, air_phases_indexed, foot_y_positions
         )
 
-    # Find precise timing for contact phase (uses curvature refinement)
+    # Store integer frame indices
+    metrics.contact_start_frame = contact_start
+    metrics.contact_end_frame = contact_end
+
+    # Find precise timing for contact phase
     contact_start_frac, contact_end_frac = _find_precise_phase_timing(
         contact_start, contact_end, interpolated_phases
     )
 
-    # Refine contact_start using floor of interpolated value
-    # This compensates for velocity-based detection being ~1-2 frames late
-    # because velocity settles AFTER initial impact. Using floor() biases
-    # toward earlier detection, matching the moment of first ground contact.
-    refined_contact_start = int(np.floor(contact_start_frac))
-
-    # Store integer frame indices (refined start, raw end)
-    # Contact end (takeoff) uses raw value as velocity-based detection is accurate
-    metrics.contact_start_frame = refined_contact_start
-    metrics.contact_end_frame = contact_end
-
     # Calculate ground contact time
     contact_frames_precise = contact_end_frac - contact_start_frac
     metrics.ground_contact_time = contact_frames_precise / fps

kinemotion/{drop_jump → dropjump}/metrics_validator.py

@@ -14,7 +14,7 @@ from kinemotion.core.validation import (
     MetricsValidator,
     ValidationResult,
 )
-from kinemotion.drop_jump.validation_bounds import (
+from kinemotion.dropjump.validation_bounds import (
     DropJumpBounds,
     estimate_athlete_profile,
 )
@@ -114,37 +114,63 @@ class DropJumpMetricsValidator(MetricsValidator):
     ) -> None:
         """Validate contact time."""
         contact_time_s = contact_time_ms / 1000.0
-        self._validate_metric_with_bounds(
-            name="contact_time",
-            value=contact_time_s,
-            bounds=DropJumpBounds.CONTACT_TIME,
-            profile=result.athlete_profile,
-            result=result,
-            format_str="{value:.3f}s",
-        )
+        bounds = DropJumpBounds.CONTACT_TIME
+
+        if not bounds.is_physically_possible(contact_time_s):
+            result.add_error(
+                "contact_time",
+                f"Contact time {contact_time_s:.3f}s physically impossible",
+                value=contact_time_s,
+                bounds=(bounds.absolute_min, bounds.absolute_max),
+            )
+        elif result.athlete_profile and not bounds.contains(
+            contact_time_s, result.athlete_profile
+        ):
+            profile_name = result.athlete_profile.value
+            result.add_warning(
+                "contact_time",
+                f"Contact time {contact_time_s:.3f}s unusual for {profile_name} athlete",
+                value=contact_time_s,
+            )
 
     def _check_flight_time(self, flight_time_ms: float, result: DropJumpValidationResult) -> None:
         """Validate flight time."""
         flight_time_s = flight_time_ms / 1000.0
-        self._validate_metric_with_bounds(
-            name="flight_time",
-            value=flight_time_s,
-            bounds=DropJumpBounds.FLIGHT_TIME,
-            profile=result.athlete_profile,
-            result=result,
-            format_str="{value:.3f}s",
-        )
+        bounds = DropJumpBounds.FLIGHT_TIME
+
+        if not bounds.is_physically_possible(flight_time_s):
+            result.add_error(
+                "flight_time",
+                f"Flight time {flight_time_s:.3f}s physically impossible",
+                value=flight_time_s,
+                bounds=(bounds.absolute_min, bounds.absolute_max),
+            )
+        elif result.athlete_profile and not bounds.contains(flight_time_s, result.athlete_profile):
+            profile_name = result.athlete_profile.value
+            result.add_warning(
+                "flight_time",
+                f"Flight time {flight_time_s:.3f}s unusual for {profile_name} athlete",
+                value=flight_time_s,
+            )
 
     def _check_jump_height(self, jump_height_m: float, result: DropJumpValidationResult) -> None:
         """Validate jump height."""
-        self._validate_metric_with_bounds(
-            name="jump_height",
-            value=jump_height_m,
-            bounds=DropJumpBounds.JUMP_HEIGHT,
-            profile=result.athlete_profile,
-            result=result,
-            format_str="{value:.3f}m",
-        )
+        bounds = DropJumpBounds.JUMP_HEIGHT
+
+        if not bounds.is_physically_possible(jump_height_m):
+            result.add_error(
+                "jump_height",
+                f"Jump height {jump_height_m:.3f}m physically impossible",
+                value=jump_height_m,
+                bounds=(bounds.absolute_min, bounds.absolute_max),
+            )
+        elif result.athlete_profile and not bounds.contains(jump_height_m, result.athlete_profile):
+            profile_name = result.athlete_profile.value
+            result.add_warning(
+                "jump_height",
+                f"Jump height {jump_height_m:.3f}m unusual for {profile_name} athlete",
+                value=jump_height_m,
+            )
 
     def _check_rsi(
         self,

kinemotion/{drop_jump → dropjump}/validation_bounds.py

@@ -124,7 +124,7 @@ def _classify_combined_score(combined_score: float) -> AthleteProfile:
     return AthleteProfile.ELITE
 
 
-def estimate_athlete_profile(metrics: MetricsDict, _gender: str | None = None) -> AthleteProfile:
+def estimate_athlete_profile(metrics: MetricsDict, gender: str | None = None) -> AthleteProfile:
     """Estimate athlete profile from drop jump metrics.
 
     Uses jump_height and contact_time to classify athlete level.

kinemotion/models/rtmpose-s_simcc-body7_pt-body7-halpe26_700e-256x192-7f134165_20230605.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:85c5d669aa0b0c7969799ea9e0620d3b8c1d3c2b6878243e98a1ef8351457986
+size 22793379

kinemotion/models/yolox_tiny_8xb8-300e_humanart-6f3252f9.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ceb11c07298f95c50d7c5abeb906d03340c85f23aa79e3e66966e7fb6c307250
+size 20283006

{kinemotion-0.76.3.dist-info → kinemotion-1.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.76.3
+Version: 1.0.0
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion
@@ -51,7 +51,6 @@ Description-Content-Type: text/markdown
 
 - **Drop Jump**: Ground contact time, flight time, reactive strength index
 - **Counter Movement Jump (CMJ)**: Jump height, flight time, countermovement depth, triple extension biomechanics
-- **Squat Jump (SJ)**: Pure concentric power, force production, requires athlete mass
 
 ## Features
 
@@ -84,14 +83,6 @@ Description-Content-Type: text/markdown
 - **Metrics**: Jump height, flight time, countermovement depth, eccentric/concentric durations
 - **Validated accuracy**: 50.6cm jump (±1 frame precision)
 
-### Squat Jump (SJ) Analysis
-
-- **Static squat start** - pure concentric power test (no countermovement)
-- **Power/Force calculations** - Sayers regression (R² = 0.87, \<1% error vs force plates)
-- **Mass required** - athlete body weight needed for kinetic calculations
-- **Metrics**: Jump height, flight time, squat hold/concentric durations, peak/mean power, peak force
-- **Phase detection**: Squat hold → concentric → flight → landing
-
 ## ⚠️ Validation Status
 
 **Current Status:** Pre-validation (not validated against force plates or motion capture systems)
@@ -237,22 +228,7 @@ kinemotion cmj-analyze video.mp4
 kinemotion cmj-analyze video.mp4 --output debug.mp4
 ```
 
-### Analyzing Squat Jump (SJ)
-
-Analyzes pure concentric power production:
-
-```bash
-# Mass is required for power/force calculations
-kinemotion sj-analyze video.mp4 --mass 75.0
-
-# Complete analysis with all outputs
-kinemotion sj-analyze video.mp4 --mass 75.0 \
-  --output debug.mp4 \
-  --json-output results.json \
-  --verbose
-```
-
-### Common Options (All Jump Types)
+### Common Options (Both Jump Types)
 
 ```bash
 # Save metrics to JSON
@@ -414,31 +390,6 @@ metrics = process_cmj_video("video.mp4", output_video="debug.mp4")
 # - Phase-coded visualization
 ```
 
-### Squat Jump (SJ) API
-
-```python
-from kinemotion import process_sj_video
-
-# Mass is required for power/force calculations
-metrics = process_sj_video(
-    video_path="athlete_sj.mp4",
-    mass_kg=75.0,  # Required: athlete body mass
-    quality="balanced",
-    verbose=True
-)
-
-# Access results
-print(f"Jump height: {metrics.jump_height:.3f}m")
-print(f"Squat hold: {metrics.squat_hold_duration*1000:.1f}ms")
-print(f"Concentric: {metrics.concentric_duration*1000:.1f}ms")
-
-# Power/force (only available if mass provided)
-if metrics.peak_power:
-    print(f"Peak power: {metrics.peak_power:.0f}W")
-    print(f"Mean power: {metrics.mean_power:.0f}W")
-    print(f"Peak force: {metrics.peak_force:.0f}N")
-```
-
 ### CSV Export Example
 
 ```python
@@ -625,9 +576,9 @@ The debug video includes:
 **Solutions**:
 
 1. **Check video quality**: Ensure the athlete is clearly visible in profile view
-2. **Increase smoothing**: Use `--smoothing-window 7` or higher
-3. **Adjust detection confidence**: Try `--detection-confidence 0.6` or `--tracking-confidence 0.6`
-4. **Generate debug video**: Use `--output` to visualize what's being tracked
+1. **Increase smoothing**: Use `--smoothing-window 7` or higher
+1. **Adjust detection confidence**: Try `--detection-confidence 0.6` or `--tracking-confidence 0.6`
+1. **Generate debug video**: Use `--output` to visualize what's being tracked
 
 ### No Pose Detected
 
@@ -636,9 +587,9 @@ The debug video includes:
 **Solutions**:
 
 1. **Verify video format**: OpenCV must be able to read the video
-2. **Check framing**: Ensure full body is visible in side view
-3. **Lower confidence thresholds**: Try `--detection-confidence 0.3 --tracking-confidence 0.3`
-4. **Test video playback**: Verify video opens correctly with standard video players
+1. **Check framing**: Ensure full body is visible in side view
+1. **Lower confidence thresholds**: Try `--detection-confidence 0.3 --tracking-confidence 0.3`
+1. **Test video playback**: Verify video opens correctly with standard video players
 
 ### Incorrect Contact Detection
 
@@ -647,11 +598,11 @@ The debug video includes:
 **Solutions**:
 
 1. **Generate debug video**: Visualize contact states to diagnose the issue
-2. **Adjust velocity threshold**:
+1. **Adjust velocity threshold**:
    - If missing contacts: decrease to `--velocity-threshold 0.01`
    - If false contacts: increase to `--velocity-threshold 0.03`
-3. **Adjust minimum frames**: `--min-contact-frames 5` for longer required contact
-4. **Check visibility**: Lower `--visibility-threshold 0.3` if feet are partially obscured
+1. **Adjust minimum frames**: `--min-contact-frames 5` for longer required contact
+1. **Check visibility**: Lower `--visibility-threshold 0.3` if feet are partially obscured
 
 ### Jump Height Seems Wrong
 
@@ -660,9 +611,9 @@ The debug video includes:
 **Solutions**:
 
 1. **Check video quality**: Ensure video frame rate is adequate (30fps or higher recommended)
-2. **Verify flight time detection**: Check `flight_start_frame` and `flight_end_frame` in JSON
-3. **Compare measurements**: JSON output includes both `jump_height_m` (primary) and `jump_height_kinematic_m` (kinematic-only)
-4. **Check for drop jump detection**: If doing a drop jump, ensure first phase is elevated enough (>5% of frame height)
+1. **Verify flight time detection**: Check `flight_start_frame` and `flight_end_frame` in JSON
+1. **Compare measurements**: JSON output includes both `jump_height_m` (primary) and `jump_height_kinematic_m` (kinematic-only)
+1. **Check for drop jump detection**: If doing a drop jump, ensure first phase is elevated enough (>5% of frame height)
 
 ### Video Codec Issues
 
@@ -671,30 +622,30 @@ The debug video includes:
 **Solutions**:
 
 1. **Install additional codecs**: Ensure OpenCV has proper video codec support
-2. **Try different output format**: Use `.avi` extension instead of `.mp4`
-3. **Check output path**: Ensure write permissions for output directory
+1. **Try different output format**: Use `.avi` extension instead of `.mp4`
+1. **Check output path**: Ensure write permissions for output directory
 
 ## How It Works
 
 1. **Pose Tracking**: MediaPipe extracts 2D pose landmarks (foot points: ankles, heels, foot indices) from each frame
-2. **Position Calculation**: Averages ankle, heel, and foot index positions to determine foot location
-3. **Smoothing**: Savitzky-Golay filter reduces tracking jitter while preserving motion dynamics
-4. **Contact Detection**: Analyzes vertical position velocity to identify ground contact vs. flight phases
-5. **Phase Identification**: Finds continuous ground contact and flight periods
+1. **Position Calculation**: Averages ankle, heel, and foot index positions to determine foot location
+1. **Smoothing**: Savitzky-Golay filter reduces tracking jitter while preserving motion dynamics
+1. **Contact Detection**: Analyzes vertical position velocity to identify ground contact vs. flight phases
+1. **Phase Identification**: Finds continuous ground contact and flight periods
    - Automatically detects drop jumps vs regular jumps
    - For drop jumps: identifies box → drop → ground contact → jump sequence
-6. **Sub-Frame Interpolation**: Estimates exact transition times between frames
+1. **Sub-Frame Interpolation**: Estimates exact transition times between frames
    - Uses Savitzky-Golay derivative for smooth velocity calculation
    - Linear interpolation of velocity to find threshold crossings
    - Achieves sub-millisecond timing precision (at 30fps: ±10ms vs ±33ms)
    - Reduces timing error by 60-70% for contact and flight measurements
    - Smoother velocity curves eliminate false threshold crossings
-7. **Trajectory Curvature Analysis**: Refines transitions using acceleration patterns
+1. **Trajectory Curvature Analysis**: Refines transitions using acceleration patterns
    - Computes second derivative (acceleration) from position trajectory
    - Detects landing impact by acceleration spike
    - Identifies takeoff by acceleration change patterns
    - Provides independent validation and refinement of velocity-based detection
-8. **Metric Calculation**:
+1. **Metric Calculation**:
    - Ground contact time = contact phase duration (using fractional frames)
    - Flight time = flight phase duration (using fractional frames)
    - Jump height = kinematic estimate from flight time: (g × t²) / 8
@@ -744,9 +695,9 @@ uv run ruff check && uv run pyright && uv run pytest
 Before committing code, ensure all checks pass:
 
 1. Format with Black
-2. Fix linting issues with ruff
-3. Ensure type safety with pyright
-4. Run all tests with pytest
+1. Fix linting issues with ruff
+1. Ensure type safety with pyright
+1. Run all tests with pytest
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and requirements, or [CLAUDE.md](CLAUDE.md) for detailed development guidelines.