kinemotion 0.10.3__py3-none-any.whl → 0.10.5__py3-none-any.whl

kinemotion/api.py

@@ -9,18 +9,315 @@ from pathlib import Path
 import numpy as np
 
 from .core.auto_tuning import (
+    AnalysisParameters,
     QualityPreset,
+    VideoCharacteristics,
     analyze_video_sample,
     auto_tune_parameters,
 )
 from .core.pose import PoseTracker
 from .core.smoothing import smooth_landmarks, smooth_landmarks_advanced
 from .core.video_io import VideoProcessor
-from .dropjump.analysis import compute_average_foot_position, detect_ground_contact
+from .dropjump.analysis import (
+    ContactState,
+    compute_average_foot_position,
+    detect_ground_contact,
+)
 from .dropjump.debug_overlay import DebugOverlayRenderer
 from .dropjump.kinematics import DropJumpMetrics, calculate_drop_jump_metrics
 
 
+def _parse_quality_preset(quality: str) -> QualityPreset:
+    """Parse and validate quality preset string.
+
+    Args:
+        quality: Quality preset string ('fast', 'balanced', or 'accurate')
+
+    Returns:
+        QualityPreset enum value
+
+    Raises:
+        ValueError: If quality preset is invalid
+    """
+    try:
+        return QualityPreset(quality.lower())
+    except ValueError as e:
+        raise ValueError(
+            f"Invalid quality preset: {quality}. Must be 'fast', 'balanced', or 'accurate'"
+        ) from e
+
+
+def _determine_confidence_levels(
+    quality_preset: QualityPreset,
+    detection_confidence: float | None,
+    tracking_confidence: float | None,
+) -> tuple[float, float]:
+    """Determine detection and tracking confidence levels.
+
+    Confidence levels are set based on quality preset and can be overridden
+    by expert parameters.
+
+    Args:
+        quality_preset: Quality preset enum
+        detection_confidence: Optional expert override for detection confidence
+        tracking_confidence: Optional expert override for tracking confidence
+
+    Returns:
+        Tuple of (detection_confidence, tracking_confidence)
+    """
+    # Set initial confidence from quality preset
+    initial_detection_conf = 0.5
+    initial_tracking_conf = 0.5
+
+    if quality_preset == QualityPreset.FAST:
+        initial_detection_conf = 0.3
+        initial_tracking_conf = 0.3
+    elif quality_preset == QualityPreset.ACCURATE:
+        initial_detection_conf = 0.6
+        initial_tracking_conf = 0.6
+
+    # Override with expert values if provided
+    if detection_confidence is not None:
+        initial_detection_conf = detection_confidence
+    if tracking_confidence is not None:
+        initial_tracking_conf = tracking_confidence
+
+    return initial_detection_conf, initial_tracking_conf
+
+
+def _apply_expert_overrides(
+    params: AnalysisParameters,
+    smoothing_window: int | None,
+    velocity_threshold: float | None,
+    min_contact_frames: int | None,
+    visibility_threshold: float | None,
+) -> AnalysisParameters:
+    """Apply expert parameter overrides to auto-tuned parameters.
+
+    Args:
+        params: Auto-tuned parameters object
+        smoothing_window: Optional override for smoothing window
+        velocity_threshold: Optional override for velocity threshold
+        min_contact_frames: Optional override for minimum contact frames
+        visibility_threshold: Optional override for visibility threshold
+
+    Returns:
+        Modified params object (mutated in place)
+    """
+    if smoothing_window is not None:
+        params.smoothing_window = smoothing_window
+    if velocity_threshold is not None:
+        params.velocity_threshold = velocity_threshold
+    if min_contact_frames is not None:
+        params.min_contact_frames = min_contact_frames
+    if visibility_threshold is not None:
+        params.visibility_threshold = visibility_threshold
+    return params
+
+
+def _print_verbose_parameters(
+    video: VideoProcessor,
+    characteristics: VideoCharacteristics,
+    quality_preset: QualityPreset,
+    params: AnalysisParameters,
+) -> None:
+    """Print auto-tuned parameters in verbose mode.
+
+    Args:
+        video: Video processor with fps and dimensions
+        characteristics: Video analysis characteristics
+        quality_preset: Selected quality preset
+        params: Auto-tuned parameters
+    """
+    print("\n" + "=" * 60)
+    print("AUTO-TUNED PARAMETERS")
+    print("=" * 60)
+    print(f"Video FPS: {video.fps:.2f}")
+    print(
+        f"Tracking quality: {characteristics.tracking_quality} "
+        f"(avg visibility: {characteristics.avg_visibility:.2f})"
+    )
+    print(f"Quality preset: {quality_preset.value}")
+    print("\nSelected parameters:")
+    print(f"  smoothing_window: {params.smoothing_window}")
+    print(f"  polyorder: {params.polyorder}")
+    print(f"  velocity_threshold: {params.velocity_threshold:.4f}")
+    print(f"  min_contact_frames: {params.min_contact_frames}")
+    print(f"  visibility_threshold: {params.visibility_threshold}")
+    print(f"  detection_confidence: {params.detection_confidence}")
+    print(f"  tracking_confidence: {params.tracking_confidence}")
+    print(f"  outlier_rejection: {params.outlier_rejection}")
+    print(f"  bilateral_filter: {params.bilateral_filter}")
+    print(f"  use_curvature: {params.use_curvature}")
+    print("=" * 60 + "\n")
+
+
+def _process_all_frames(
+    video: VideoProcessor, tracker: PoseTracker, verbose: bool
+) -> tuple[list, list]:
+    """Process all frames from video and extract pose landmarks.
+
+    Args:
+        video: Video processor to read frames from
+        tracker: Pose tracker for landmark detection
+        verbose: Print progress messages
+
+    Returns:
+        Tuple of (frames, landmarks_sequence)
+
+    Raises:
+        ValueError: If no frames could be processed
+    """
+    if verbose:
+        print("Tracking pose landmarks...")
+
+    landmarks_sequence = []
+    frames = []
+
+    while True:
+        frame = video.read_frame()
+        if frame is None:
+            break
+
+        frames.append(frame)
+        landmarks = tracker.process_frame(frame)
+        landmarks_sequence.append(landmarks)
+
+    tracker.close()
+
+    if not landmarks_sequence:
+        raise ValueError("No frames could be processed from video")
+
+    return frames, landmarks_sequence
+
+
+def _apply_smoothing(
+    landmarks_sequence: list, params: AnalysisParameters, verbose: bool
+) -> list:
+    """Apply smoothing to landmark sequence with auto-tuned parameters.
+
+    Args:
+        landmarks_sequence: Sequence of landmarks from all frames
+        params: Auto-tuned parameters containing smoothing settings
+        verbose: Print progress messages
+
+    Returns:
+        Smoothed landmarks sequence
+    """
+    if params.outlier_rejection or params.bilateral_filter:
+        if verbose:
+            if params.outlier_rejection:
+                print("Smoothing landmarks with outlier rejection...")
+            if params.bilateral_filter:
+                print("Using bilateral temporal filter...")
+        return smooth_landmarks_advanced(
+            landmarks_sequence,
+            window_length=params.smoothing_window,
+            polyorder=params.polyorder,
+            use_outlier_rejection=params.outlier_rejection,
+            use_bilateral=params.bilateral_filter,
+        )
+    else:
+        if verbose:
+            print("Smoothing landmarks...")
+        return smooth_landmarks(
+            landmarks_sequence,
+            window_length=params.smoothing_window,
+            polyorder=params.polyorder,
+        )
+
+
+def _extract_vertical_positions(
+    smoothed_landmarks: list,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Extract vertical foot positions and visibilities from smoothed landmarks.
+
+    Args:
+        smoothed_landmarks: Smoothed landmark sequence
+
+    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)
+
+            # Average visibility of foot landmarks
+            foot_vis = []
+            for key in ["left_ankle", "right_ankle", "left_heel", "right_heel"]:
+                if key in frame_landmarks:
+                    foot_vis.append(frame_landmarks[key][2])
+            visibilities_list.append(float(np.mean(foot_vis)) if foot_vis else 0.0)
+        else:
+            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)
+
+
+def _generate_outputs(
+    metrics: DropJumpMetrics,
+    json_output: str | None,
+    output_video: str | None,
+    frames: list,
+    smoothed_landmarks: list,
+    contact_states: list[ContactState],
+    video: VideoProcessor,
+    verbose: bool,
+) -> None:
+    """Generate JSON and debug video outputs if requested.
+
+    Args:
+        metrics: Calculated drop jump metrics
+        json_output: Optional path for JSON output
+        output_video: Optional path for debug video
+        frames: List of video frames
+        smoothed_landmarks: Smoothed landmark sequence
+        contact_states: Ground contact state for each frame
+        video: Video processor with dimensions and fps
+        verbose: Print progress messages
+    """
+    # Save JSON if requested
+    if json_output:
+        import json
+
+        output_path = Path(json_output)
+        output_path.write_text(json.dumps(metrics.to_dict(), indent=2))
+        if verbose:
+            print(f"Metrics written to: {json_output}")
+
+    # Generate debug video if requested
+    if output_video:
+        if verbose:
+            print(f"Generating debug video: {output_video}")
+
+        with DebugOverlayRenderer(
+            output_video,
+            video.width,
+            video.height,
+            video.display_width,
+            video.display_height,
+            video.fps,
+        ) as renderer:
+            for i, frame in enumerate(frames):
+                annotated = renderer.render_frame(
+                    frame,
+                    smoothed_landmarks[i],
+                    contact_states[i],
+                    i,
+                    metrics,
+                    use_com=False,
+                )
+                renderer.write_frame(annotated)
+
+        if verbose:
+            print(f"Debug video saved: {output_video}")
+
+
 @dataclass
 class VideoResult:
     """Result of processing a single video."""
@@ -94,12 +391,7 @@ def process_video(
         raise FileNotFoundError(f"Video file not found: {video_path}")
 
     # Convert quality string to enum
-    try:
-        quality_preset = QualityPreset(quality.lower())
-    except ValueError as e:
-        raise ValueError(
-            f"Invalid quality preset: {quality}. Must be 'fast', 'balanced', or 'accurate'"
-        ) from e
+    quality_preset = _parse_quality_preset(quality)
 
     # Initialize video processor
     with VideoProcessor(video_path) as video:
@@ -109,138 +401,46 @@ def process_video(
                 f"{video.frame_count} frames"
             )
 
-        # Determine initial detection/tracking confidence from quality preset
-        initial_detection_conf = 0.5
-        initial_tracking_conf = 0.5
-
-        if quality_preset == QualityPreset.FAST:
-            initial_detection_conf = 0.3
-            initial_tracking_conf = 0.3
-        elif quality_preset == QualityPreset.ACCURATE:
-            initial_detection_conf = 0.6
-            initial_tracking_conf = 0.6
-
-        # Override with expert values if provided
-        if detection_confidence is not None:
-            initial_detection_conf = detection_confidence
-        if tracking_confidence is not None:
-            initial_tracking_conf = tracking_confidence
+        # Determine detection/tracking confidence levels
+        detection_conf, tracking_conf = _determine_confidence_levels(
+            quality_preset, detection_confidence, tracking_confidence
+        )
 
-        # Initialize pose tracker
+        # Process all frames with pose tracking
         tracker = PoseTracker(
-            min_detection_confidence=initial_detection_conf,
-            min_tracking_confidence=initial_tracking_conf,
+            min_detection_confidence=detection_conf,
+            min_tracking_confidence=tracking_conf,
         )
-
-        # Process all frames
-        if verbose:
-            print("Tracking pose landmarks...")
-
-        landmarks_sequence = []
-        frames = []
-
-        while True:
-            frame = video.read_frame()
-            if frame is None:
-                break
-
-            frames.append(frame)
-            landmarks = tracker.process_frame(frame)
-            landmarks_sequence.append(landmarks)
-
-        tracker.close()
-
-        if not landmarks_sequence:
-            raise ValueError("No frames could be processed from video")
+        frames, landmarks_sequence = _process_all_frames(video, tracker, verbose)
 
         # Analyze video characteristics and auto-tune parameters
         characteristics = analyze_video_sample(
             landmarks_sequence, video.fps, video.frame_count
         )
-
         params = auto_tune_parameters(characteristics, quality_preset)
 
         # Apply expert overrides if provided
-        if smoothing_window is not None:
-            params.smoothing_window = smoothing_window
-        if velocity_threshold is not None:
-            params.velocity_threshold = velocity_threshold
-        if min_contact_frames is not None:
-            params.min_contact_frames = min_contact_frames
-        if visibility_threshold is not None:
-            params.visibility_threshold = visibility_threshold
+        params = _apply_expert_overrides(
+            params,
+            smoothing_window,
+            velocity_threshold,
+            min_contact_frames,
+            visibility_threshold,
+        )
 
         # Show selected parameters if verbose
         if verbose:
-            print("\n" + "=" * 60)
-            print("AUTO-TUNED PARAMETERS")
-            print("=" * 60)
-            print(f"Video FPS: {video.fps:.2f}")
-            print(
-                f"Tracking quality: {characteristics.tracking_quality} "
-                f"(avg visibility: {characteristics.avg_visibility:.2f})"
-            )
-            print(f"Quality preset: {quality_preset.value}")
-            print("\nSelected parameters:")
-            print(f"  smoothing_window: {params.smoothing_window}")
-            print(f"  polyorder: {params.polyorder}")
-            print(f"  velocity_threshold: {params.velocity_threshold:.4f}")
-            print(f"  min_contact_frames: {params.min_contact_frames}")
-            print(f"  visibility_threshold: {params.visibility_threshold}")
-            print(f"  detection_confidence: {params.detection_confidence}")
-            print(f"  tracking_confidence: {params.tracking_confidence}")
-            print(f"  outlier_rejection: {params.outlier_rejection}")
-            print(f"  bilateral_filter: {params.bilateral_filter}")
-            print(f"  use_curvature: {params.use_curvature}")
-            print("=" * 60 + "\n")
+            _print_verbose_parameters(video, characteristics, quality_preset, params)
 
         # Apply smoothing with auto-tuned parameters
-        if params.outlier_rejection or params.bilateral_filter:
-            if verbose:
-                if params.outlier_rejection:
-                    print("Smoothing landmarks with outlier rejection...")
-                if params.bilateral_filter:
-                    print("Using bilateral temporal filter...")
-            smoothed_landmarks = smooth_landmarks_advanced(
-                landmarks_sequence,
-                window_length=params.smoothing_window,
-                polyorder=params.polyorder,
-                use_outlier_rejection=params.outlier_rejection,
-                use_bilateral=params.bilateral_filter,
-            )
-        else:
-            if verbose:
-                print("Smoothing landmarks...")
-            smoothed_landmarks = smooth_landmarks(
-                landmarks_sequence,
-                window_length=params.smoothing_window,
-                polyorder=params.polyorder,
-            )
+        smoothed_landmarks = _apply_smoothing(landmarks_sequence, params, verbose)
 
         # Extract vertical positions from feet
         if verbose:
             print("Extracting foot positions...")
-
-        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)
-
-                # Average visibility of foot landmarks
-                foot_vis = []
-                for key in ["left_ankle", "right_ankle", "left_heel", "right_heel"]:
-                    if key in frame_landmarks:
-                        foot_vis.append(frame_landmarks[key][2])
-                visibilities_list.append(float(np.mean(foot_vis)) if foot_vis else 0.0)
-            else:
-                position_list.append(position_list[-1] if position_list else 0.5)
-                visibilities_list.append(0.0)
-
-        vertical_positions: np.ndarray = np.array(position_list)
-        visibilities: np.ndarray = np.array(visibilities_list)
+        vertical_positions, visibilities = _extract_vertical_positions(
+            smoothed_landmarks
+        )
 
         # Detect ground contact
         contact_states = detect_ground_contact(
@@ -273,41 +473,17 @@ def process_video(
             kinematic_correction_factor=1.0,
         )
 
-        # Save JSON if requested
-        if json_output:
-            import json
-
-            output_path = Path(json_output)
-            output_path.write_text(json.dumps(metrics.to_dict(), indent=2))
-            if verbose:
-                print(f"Metrics written to: {json_output}")
-
-        # Generate debug video if requested
-        if output_video:
-            if verbose:
-                print(f"Generating debug video: {output_video}")
-
-            with DebugOverlayRenderer(
-                output_video,
-                video.width,
-                video.height,
-                video.display_width,
-                video.display_height,
-                video.fps,
-            ) as renderer:
-                for i, frame in enumerate(frames):
-                    annotated = renderer.render_frame(
-                        frame,
-                        smoothed_landmarks[i],
-                        contact_states[i],
-                        i,
-                        metrics,
-                        use_com=False,
-                    )
-                    renderer.write_frame(annotated)
-
-            if verbose:
-                print(f"Debug video saved: {output_video}")
+        # Generate outputs (JSON and debug video)
+        _generate_outputs(
+            metrics,
+            json_output,
+            output_video,
+            frames,
+            smoothed_landmarks,
+            contact_states,
+            video,
+            verbose,
+        )
 
         if verbose:
             print("Analysis complete!")

kinemotion/dropjump/kinematics.py

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

{kinemotion-0.10.3.dist-info → kinemotion-0.10.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.10.3
+Version: 0.10.5
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion

{kinemotion-0.10.3.dist-info → kinemotion-0.10.5.dist-info}/RECORD

@@ -1,5 +1,5 @@
 kinemotion/__init__.py,sha256=Z85xg29NA-r4IjrSbAkJpMFigyxACFGUb-37AiMp6YY,350
-kinemotion/api.py,sha256=3Hswx5lfyWc-EanS6iV-4MPUa_uB5t8BpGe4EB4gIIQ,15453
+kinemotion/api.py,sha256=2MsiHsmmxfpvhHIbDXcZpvsCLROKi4MV8LQpKu2r_a8,20078
 kinemotion/cli.py,sha256=2IFA2_TE9a5zBtmGVzv5SnX39w7yPuBlw42dL7ca25U,402
 kinemotion/core/__init__.py,sha256=3yzDhb5PekDNjydqrs8aWGneUGJBt-lB0SoB_Y2FXqU,1010
 kinemotion/core/auto_tuning.py,sha256=cvmxUI-CbahpOJQtR2r5jOx4Q6yKPe3DO1o15hOQIdw,10508
@@ -11,10 +11,10 @@ kinemotion/dropjump/__init__.py,sha256=yc1XiZ9vfo5h_n7PKVSiX2TTgaIfGL7Y7SkQtiDZj
 kinemotion/dropjump/analysis.py,sha256=HfJt2t9IsMBiBUz7apIzdxbRH9QqzlFnDVVWcKhU3ow,23291
 kinemotion/dropjump/cli.py,sha256=C6v6E3g1W-KNFc0xUzSjg4wKve1WsPxKvUBJV7LiMNI,26468
 kinemotion/dropjump/debug_overlay.py,sha256=GMo-jCl5OPIv82uPxDbBVI7CsAMwATTvxZMeWfs8k8M,8701
-kinemotion/dropjump/kinematics.py,sha256=4G_7_KWnXiT09G9BduQNIgFtxvwjo2RyH1sP9SU3hSE,17949
+kinemotion/dropjump/kinematics.py,sha256=RM_O8Kdc6aEiPIu_99N4cu-4EhYSQxtBGASJF_dmQaU,19081
 kinemotion/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kinemotion-0.10.3.dist-info/METADATA,sha256=dZnaZxwMdOWr1eVeJI45_jCm6W6Mjm0_TvvHQZt3YBo,20333
-kinemotion-0.10.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-kinemotion-0.10.3.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
-kinemotion-0.10.3.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
-kinemotion-0.10.3.dist-info/RECORD,,
+kinemotion-0.10.5.dist-info/METADATA,sha256=I5dXmUcnNNtKS43uCbC_zbMLBMZAg_QpOMhwpnFSYcw,20333
+kinemotion-0.10.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+kinemotion-0.10.5.dist-info/entry_points.txt,sha256=zaqnAnjLvcdrk1Qvj5nvXZCZ2gp0prS7it1zTJygcIY,50
+kinemotion-0.10.5.dist-info/licenses/LICENSE,sha256=KZajvqsHw0NoOHOi2q0FZ4NBe9HdV6oey-IPYAtHXfg,1088
+kinemotion-0.10.5.dist-info/RECORD,,