kinemotion 0.45.1__py3-none-any.whl → 0.47.0__py3-none-any.whl

kinemotion/api.py

@@ -39,7 +39,7 @@ from .core.pipeline_utils import (
 )
 from .core.pose import PoseTracker
 from .core.quality import assess_jump_quality
-from .core.timing import PerformanceTimer
+from .core.timing import NULL_TIMER, PerformanceTimer, Timer
 from .core.video_io import VideoProcessor
 from .dropjump.analysis import (
     detect_ground_contact,
@@ -86,7 +86,7 @@ def _generate_debug_video(
     smoothed_landmarks: list,
     contact_states: list,
     metrics: DropJumpMetrics,
-    timer: PerformanceTimer | None,
+    timer: Timer | None,
     verbose: bool,
 ) -> None:
     """Generate debug video with overlay."""
@@ -96,6 +96,7 @@ def _generate_debug_video(
     if not frames:
         return
 
+    timer = timer or NULL_TIMER
     debug_h, debug_w = frames[0].shape[:2]
 
     if video_fps > 30:
@@ -129,11 +130,7 @@ def _generate_debug_video(
         timer=timer,
     )
 
-    if timer:
-        with timer.measure("debug_video_generation"):
-            with renderer_context as renderer:
-                _render_frames(renderer)
-    else:
+    with timer.measure("debug_video_generation"):
         with renderer_context as renderer:
             _render_frames(renderer)
 
@@ -154,7 +151,7 @@ def process_dropjump_video(
     detection_confidence: float | None = None,
     tracking_confidence: float | None = None,
     verbose: bool = False,
-    timer: PerformanceTimer | None = None,
+    timer: Timer | None = None,
     pose_tracker: "PoseTracker | None" = None,
 ) -> DropJumpMetrics:
     """
@@ -175,7 +172,7 @@ def process_dropjump_video(
         detection_confidence: Optional override for pose detection confidence
         tracking_confidence: Optional override for pose tracking confidence
         verbose: Print processing details
-        timer: Optional PerformanceTimer for measuring operations
+        timer: Optional Timer for measuring operations
         pose_tracker: Optional pre-initialized PoseTracker instance (reused if provided)
 
     Returns:
@@ -263,6 +260,7 @@ def process_dropjump_video(
                     visibilities=visibilities,
                     window_length=params.smoothing_window,
                     polyorder=params.polyorder,
+                    timer=timer,
                 )
 
             if verbose:
@@ -277,6 +275,7 @@ def process_dropjump_video(
                     smoothing_window=params.smoothing_window,
                     polyorder=params.polyorder,
                     use_curvature=params.use_curvature,
+                    timer=timer,
                 )
 
             if verbose:
@@ -391,13 +390,7 @@ def process_dropjump_video(
             metrics.result_metadata = result_metadata
 
             if json_output:
-                if timer:
-                    with timer.measure("json_serialization"):
-                        output_path = Path(json_output)
-                        metrics_dict = metrics.to_dict()
-                        json_str = json.dumps(metrics_dict, indent=2)
-                        output_path.write_text(json_str)
-                else:
+                with timer.measure("json_serialization"):
                     output_path = Path(json_output)
                     metrics_dict = metrics.to_dict()
                     json_str = json.dumps(metrics_dict, indent=2)
@@ -528,7 +521,7 @@ def process_cmj_video(
     detection_confidence: float | None = None,
     tracking_confidence: float | None = None,
     verbose: bool = False,
-    timer: PerformanceTimer | None = None,
+    timer: Timer | None = None,
     pose_tracker: "PoseTracker | None" = None,
 ) -> CMJMetrics:
     """
@@ -550,7 +543,7 @@ def process_cmj_video(
         detection_confidence: Optional override for pose detection confidence
         tracking_confidence: Optional override for pose tracking confidence
         verbose: Print processing details
-        timer: Optional PerformanceTimer for measuring operations
+        timer: Optional Timer for measuring operations
         pose_tracker: Optional pre-initialized PoseTracker instance (reused if provided)
 
     Returns:
@@ -644,6 +637,7 @@ def process_cmj_video(
                     window_length=params.smoothing_window,
                     polyorder=params.polyorder,
                     landing_positions=foot_positions,
+                    timer=timer,
                 )
 
             if phases is None:
@@ -738,23 +732,7 @@ def process_cmj_video(
                 step = max(1, int(video.fps / 30.0))
                 debug_fps = video.fps / step
 
-                if timer:
-                    with timer.measure("debug_video_generation"):
-                        with CMJDebugOverlayRenderer(
-                            output_video,
-                            debug_w,
-                            debug_h,
-                            debug_w,
-                            debug_h,
-                            debug_fps,
-                            timer=timer,
-                        ) as renderer:
-                            for frame, idx in zip(frames, frame_indices, strict=True):
-                                annotated = renderer.render_frame(
-                                    frame, smoothed_landmarks[idx], idx, metrics
-                                )
-                                renderer.write_frame(annotated)
-                else:
+                with timer.measure("debug_video_generation"):
                     with CMJDebugOverlayRenderer(
                         output_video,
                         debug_w,
@@ -799,13 +777,7 @@ def process_cmj_video(
             metrics.result_metadata = result_metadata
 
             if json_output:
-                if timer:
-                    with timer.measure("json_serialization"):
-                        output_path = Path(json_output)
-                        metrics_dict = metrics.to_dict()
-                        json_str = json.dumps(metrics_dict, indent=2)
-                        output_path.write_text(json_str)
-                else:
+                with timer.measure("json_serialization"):
                     output_path = Path(json_output)
                     metrics_dict = metrics.to_dict()
                     json_str = json.dumps(metrics_dict, indent=2)

kinemotion/cmj/analysis.py

@@ -7,6 +7,7 @@ from scipy.signal import savgol_filter
 
 from ..core.experimental import unused
 from ..core.smoothing import compute_acceleration_from_derivative
+from ..core.timing import NULL_TIMER, Timer
 
 
 def compute_signed_velocity(
@@ -545,6 +546,7 @@ def detect_cmj_phases(
     window_length: int = 5,
     polyorder: int = 2,
     landing_positions: np.ndarray | None = None,
+    timer: Timer | None = None,
 ) -> tuple[float | None, float, float, float] | None:
     """
     Detect all phases of a counter movement jump using a simplified, robust approach.
@@ -562,18 +564,22 @@ def detect_cmj_phases(
         polyorder: Polynomial order for Savitzky-Golay filter
         landing_positions: Optional array of positions for landing detection
             (e.g., Feet). If None, uses `positions` (Hips) for landing too.
+        timer: Optional Timer for measuring operations
 
     Returns:
         Tuple of (standing_end_frame, lowest_point_frame, takeoff_frame, landing_frame)
         with fractional precision, or None if phases cannot be detected.
     """
+    timer = timer or NULL_TIMER
+
     # Compute SIGNED velocities and accelerations for primary signal (Hips)
-    velocities = compute_signed_velocity(
-        positions, window_length=window_length, polyorder=polyorder
-    )
-    accelerations = compute_acceleration_from_derivative(
-        positions, window_length=window_length, polyorder=polyorder
-    )
+    with timer.measure("cmj_compute_derivatives"):
+        velocities = compute_signed_velocity(
+            positions, window_length=window_length, polyorder=polyorder
+        )
+        accelerations = compute_acceleration_from_derivative(
+            positions, window_length=window_length, polyorder=polyorder
+        )
 
     # Step 1: Find peak height (global minimum y = highest point in frame)
     peak_height_frame = int(np.argmin(positions))
@@ -581,34 +587,42 @@ def detect_cmj_phases(
         return None  # Peak too early, invalid
 
     # Step 2-4: Find all phases using helper functions
-    takeoff_frame = find_takeoff_frame(velocities, peak_height_frame, fps)
-    lowest_point = find_lowest_frame(velocities, positions, takeoff_frame, fps)
+    with timer.measure("cmj_find_takeoff"):
+        takeoff_frame = find_takeoff_frame(velocities, peak_height_frame, fps)
+
+    with timer.measure("cmj_find_lowest_point"):
+        lowest_point = find_lowest_frame(velocities, positions, takeoff_frame, fps)
 
     # Determine landing frame
-    if landing_positions is not None:
-        # Use specific landing signal (Feet) for landing detection
-        landing_velocities = compute_signed_velocity(
-            landing_positions, window_length=window_length, polyorder=polyorder
-        )
-        landing_accelerations = compute_acceleration_from_derivative(
-            landing_positions, window_length=window_length, polyorder=polyorder
-        )
-        # We still reference peak_height_frame from Hips, as Feet peak
-        # might be different/noisy but generally they align in time.
-        landing_frame = find_landing_frame(
-            landing_accelerations,
-            landing_velocities,
-            peak_height_frame,
-            fps,
-        )
-    else:
-        # Use primary signal (Hips)
-        landing_frame = find_landing_frame(
-            accelerations,
-            velocities,
-            peak_height_frame,
-            fps,
+    with timer.measure("cmj_find_landing"):
+        if landing_positions is not None:
+            # Use specific landing signal (Feet) for landing detection
+            landing_velocities = compute_signed_velocity(
+                landing_positions, window_length=window_length, polyorder=polyorder
+            )
+            landing_accelerations = compute_acceleration_from_derivative(
+                landing_positions, window_length=window_length, polyorder=polyorder
+            )
+            # We still reference peak_height_frame from Hips, as Feet peak
+            # might be different/noisy but generally they align in time.
+            landing_frame = find_landing_frame(
+                landing_accelerations,
+                landing_velocities,
+                peak_height_frame,
+                fps,
+            )
+        else:
+            # Use primary signal (Hips)
+            landing_frame = find_landing_frame(
+                accelerations,
+                velocities,
+                peak_height_frame,
+                fps,
+            )
+
+    with timer.measure("cmj_find_standing_end"):
+        standing_end = find_standing_end(
+            velocities, lowest_point, positions, accelerations
         )
 
-    standing_end = find_standing_end(velocities, lowest_point, positions, accelerations)
     return (standing_end, lowest_point, takeoff_frame, landing_frame)

kinemotion/core/__init__.py

@@ -22,7 +22,14 @@ from .smoothing import (
     smooth_landmarks,
     smooth_landmarks_advanced,
 )
-from .timing import PerformanceTimer
+from .timing import (
+    NULL_TIMER,
+    CompositeTimer,
+    NullTimer,
+    OpenTelemetryTimer,
+    PerformanceTimer,
+    Timer,
+)
 from .video_io import VideoProcessor
 
 __all__ = [
@@ -49,6 +56,11 @@ __all__ = [
     "calculate_position_stability",
     # Timing
     "PerformanceTimer",
+    "Timer",
+    "NullTimer",
+    "NULL_TIMER",
+    "CompositeTimer",
+    "OpenTelemetryTimer",
     # Video I/O
     "VideoProcessor",
 ]

kinemotion/core/debug_overlay_utils.py

@@ -10,7 +10,7 @@ from typing import Self
 import cv2
 import numpy as np
 
-from .timing import PerformanceTimer
+from .timing import NULL_TIMER, Timer
 
 
 def create_video_writer(
@@ -107,7 +107,7 @@ class BaseDebugOverlayRenderer:
         display_width: int,
         display_height: int,
         fps: float,
-        timer: PerformanceTimer | None = None,
+        timer: Timer | None = None,
     ):
         """
         Initialize overlay renderer.
@@ -119,12 +119,12 @@ class BaseDebugOverlayRenderer:
             display_width: Display width (considering SAR)
             display_height: Display height (considering SAR)
             fps: Frames per second
-            timer: Optional PerformanceTimer for measuring operations
+            timer: Optional Timer for measuring operations
         """
         self.output_path = output_path
         self.width = width
         self.height = height
-        self.timer = timer
+        self.timer = timer or NULL_TIMER
 
         # Optimize debug video resolution: Cap max dimension to 720p
         # Reduces software encoding time on single-core Cloud Run instances.
@@ -166,26 +166,14 @@ class BaseDebugOverlayRenderer:
 
         # Resize to display dimensions if needed (to handle SAR)
         if self.needs_resize:
-            if self.timer:
-                with self.timer.measure("debug_video_resize"):
-                    frame = cv2.resize(
-                        frame,
-                        (self.display_width, self.display_height),
-                        interpolation=cv2.INTER_LINEAR,
-                    )
-            else:
+            with self.timer.measure("debug_video_resize"):
                 frame = cv2.resize(
                     frame,
                     (self.display_width, self.display_height),
                     interpolation=cv2.INTER_LINEAR,
                 )
 
-        if self.timer:
-            with self.timer.measure("debug_video_write"):
-                write_overlay_frame(
-                    self.writer, frame, self.display_width, self.display_height
-                )
-        else:
+        with self.timer.measure("debug_video_write"):
             write_overlay_frame(
                 self.writer, frame, self.display_width, self.display_height
             )

kinemotion/core/pipeline_utils.py

@@ -12,7 +12,7 @@ from ..dropjump.analysis import compute_average_foot_position
 from .auto_tuning import AnalysisParameters, QualityPreset, VideoCharacteristics
 from .pose import PoseTracker
 from .smoothing import smooth_landmarks, smooth_landmarks_advanced
-from .timing import PerformanceTimer
+from .timing import NULL_TIMER, Timer
 from .video_io import VideoProcessor
 
 TResult = TypeVar("TResult")
@@ -182,7 +182,7 @@ def process_all_frames(
     video: VideoProcessor,
     tracker: PoseTracker,
     verbose: bool,
-    timer: PerformanceTimer | None = None,
+    timer: Timer | None = None,
     close_tracker: bool = True,
     target_debug_fps: float = 30.0,
     max_debug_dim: int = 720,
@@ -193,7 +193,7 @@ def process_all_frames(
         video: Video processor to read frames from
         tracker: Pose tracker for landmark detection
         verbose: Print progress messages
-        timer: Optional PerformanceTimer for measuring operations
+        timer: Optional Timer for measuring operations
         close_tracker: Whether to close the tracker after processing (default: True)
         target_debug_fps: Target FPS for debug video (default: 30.0)
         max_debug_dim: Max dimension for debug video frames (default: 720)
@@ -207,6 +207,7 @@ def process_all_frames(
     if verbose:
         print("Tracking pose landmarks...")
 
+    timer = timer or NULL_TIMER
     step = max(1, int(video.fps / target_debug_fps))
 
     w, h = video.display_width, video.display_height
@@ -218,12 +219,7 @@ def process_all_frames(
     debug_h = int(h * scale) // 2 * 2
     should_resize = (debug_w != video.width) or (debug_h != video.height)
 
-    if timer:
-        with timer.measure("pose_tracking"):
-            debug_frames, landmarks_sequence, frame_indices = _process_frames_loop(
-                video, tracker, step, should_resize, debug_w, debug_h
-            )
-    else:
+    with timer.measure("pose_tracking"):
         debug_frames, landmarks_sequence, frame_indices = _process_frames_loop(
             video, tracker, step, should_resize, debug_w, debug_h
         )
@@ -241,7 +237,7 @@ def apply_smoothing(
     landmarks_sequence: list,
     params: AnalysisParameters,
     verbose: bool,
-    timer: PerformanceTimer | None = None,
+    timer: Timer | None = None,
 ) -> list:
     """Apply smoothing to landmark sequence with auto-tuned parameters.
 
@@ -249,11 +245,12 @@ def apply_smoothing(
         landmarks_sequence: Sequence of landmarks from all frames
         params: Auto-tuned parameters containing smoothing settings
         verbose: Print progress messages
-        timer: Optional PerformanceTimer for measuring operations
+        timer: Optional Timer for measuring operations
 
     Returns:
         Smoothed landmarks sequence
     """
+    timer = timer or NULL_TIMER
     use_advanced = params.outlier_rejection or params.bilateral_filter
 
     if verbose:
@@ -273,6 +270,7 @@ def apply_smoothing(
                 polyorder=params.polyorder,
                 use_outlier_rejection=params.outlier_rejection,
                 use_bilateral=params.bilateral_filter,
+                timer=timer,
             )
         else:
             return smooth_landmarks(
@@ -281,10 +279,8 @@ def apply_smoothing(
                 polyorder=params.polyorder,
             )
 
-    if timer:
-        with timer.measure("smoothing"):
-            return _run_smoothing()
-    return _run_smoothing()
+    with timer.measure("smoothing"):
+        return _run_smoothing()
 
 
 def calculate_foot_visibility(frame_landmarks: dict) -> float:
@@ -341,7 +337,7 @@ def convert_timer_to_stage_names(
     """Convert timer metric names to human-readable stage names.
 
     Args:
-        timer_metrics: Dictionary from PerformanceTimer.get_metrics()
+        timer_metrics: Dictionary from Timer.get_metrics()
 
     Returns:
         Dictionary with human-readable stage names as keys
@@ -366,6 +362,24 @@ def convert_timer_to_stage_names(
         "debug_video_copy": "Debug video frame copy",
         "debug_video_draw": "Debug video drawing",
         "debug_video_write": "Debug video encoding",
+        # Granular metrics
+        "frame_conversion": "Frame BGR-RGB conversion",
+        "mediapipe_inference": "MediaPipe inference",
+        "landmark_extraction": "Landmark extraction",
+        "smoothing_outlier_rejection": "Smoothing (outlier rejection)",
+        "smoothing_bilateral": "Smoothing (bilateral)",
+        "smoothing_savgol": "Smoothing (Savitzky-Golay)",
+        "cmj_compute_derivatives": "CMJ derivatives computation",
+        "cmj_find_takeoff": "CMJ takeoff detection",
+        "cmj_find_lowest_point": "CMJ lowest point detection",
+        "cmj_find_landing": "CMJ landing detection",
+        "cmj_find_standing_end": "CMJ standing end detection",
+        "dj_compute_velocity": "DJ velocity computation",
+        "dj_find_contact_frames": "DJ contact frame search",
+        "dj_detect_drop_start": "DJ drop start detection",
+        "dj_find_phases": "DJ phase finding",
+        "dj_identify_contact": "DJ contact identification",
+        "dj_analyze_flight": "DJ flight analysis",
     }
     return {mapping.get(k, k): v for k, v in timer_metrics.items()}
 

kinemotion/core/pose.py

@@ -4,7 +4,7 @@ import cv2
 import mediapipe as mp
 import numpy as np
 
-from .timing import PerformanceTimer
+from .timing import NULL_TIMER, Timer
 
 
 class PoseTracker:
@@ -14,7 +14,7 @@ class PoseTracker:
         self,
         min_detection_confidence: float = 0.5,
         min_tracking_confidence: float = 0.5,
-        timer: PerformanceTimer | None = None,
+        timer: Timer | None = None,
     ) -> None:
         """
         Initialize the pose tracker.
@@ -22,9 +22,9 @@ class PoseTracker:
         Args:
             min_detection_confidence: Minimum confidence for pose detection
             min_tracking_confidence: Minimum confidence for pose tracking
-            timer: Optional PerformanceTimer for measuring operations
+            timer: Optional Timer for measuring operations
         """
-        self.timer = timer
+        self.timer = timer or NULL_TIMER
         self.mp_pose = mp.solutions.pose
         self.pose = self.mp_pose.Pose(
             static_image_mode=False,  # Use tracking mode for better performance
@@ -47,42 +47,41 @@ class PoseTracker:
             or None if no pose detected. Coordinates are normalized (0-1).
         """
         # Convert BGR to RGB
-        rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+        with self.timer.measure("frame_conversion"):
+            rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
 
         # Process the frame
-        if self.timer:
-            with self.timer.measure("mediapipe_inference"):
-                results = self.pose.process(rgb_frame)
-        else:
+        with self.timer.measure("mediapipe_inference"):
             results = self.pose.process(rgb_frame)
 
         if not results.pose_landmarks:
             return None
 
         # Extract key landmarks for feet tracking and CoM estimation
-        landmarks = {}
-        landmark_names = {
-            # Feet landmarks
-            self.mp_pose.PoseLandmark.LEFT_ANKLE: "left_ankle",
-            self.mp_pose.PoseLandmark.RIGHT_ANKLE: "right_ankle",
-            self.mp_pose.PoseLandmark.LEFT_HEEL: "left_heel",
-            self.mp_pose.PoseLandmark.RIGHT_HEEL: "right_heel",
-            self.mp_pose.PoseLandmark.LEFT_FOOT_INDEX: "left_foot_index",
-            self.mp_pose.PoseLandmark.RIGHT_FOOT_INDEX: "right_foot_index",
-            # Torso landmarks for CoM estimation
-            self.mp_pose.PoseLandmark.LEFT_HIP: "left_hip",
-            self.mp_pose.PoseLandmark.RIGHT_HIP: "right_hip",
-            self.mp_pose.PoseLandmark.LEFT_SHOULDER: "left_shoulder",
-            self.mp_pose.PoseLandmark.RIGHT_SHOULDER: "right_shoulder",
-            # Additional landmarks for better CoM estimation
-            self.mp_pose.PoseLandmark.NOSE: "nose",
-            self.mp_pose.PoseLandmark.LEFT_KNEE: "left_knee",
-            self.mp_pose.PoseLandmark.RIGHT_KNEE: "right_knee",
-        }
-
-        for landmark_id, name in landmark_names.items():
-            lm = results.pose_landmarks.landmark[landmark_id]
-            landmarks[name] = (lm.x, lm.y, lm.visibility)
+        with self.timer.measure("landmark_extraction"):
+            landmarks = {}
+            landmark_names = {
+                # Feet landmarks
+                self.mp_pose.PoseLandmark.LEFT_ANKLE: "left_ankle",
+                self.mp_pose.PoseLandmark.RIGHT_ANKLE: "right_ankle",
+                self.mp_pose.PoseLandmark.LEFT_HEEL: "left_heel",
+                self.mp_pose.PoseLandmark.RIGHT_HEEL: "right_heel",
+                self.mp_pose.PoseLandmark.LEFT_FOOT_INDEX: "left_foot_index",
+                self.mp_pose.PoseLandmark.RIGHT_FOOT_INDEX: "right_foot_index",
+                # Torso landmarks for CoM estimation
+                self.mp_pose.PoseLandmark.LEFT_HIP: "left_hip",
+                self.mp_pose.PoseLandmark.RIGHT_HIP: "right_hip",
+                self.mp_pose.PoseLandmark.LEFT_SHOULDER: "left_shoulder",
+                self.mp_pose.PoseLandmark.RIGHT_SHOULDER: "right_shoulder",
+                # Additional landmarks for better CoM estimation
+                self.mp_pose.PoseLandmark.NOSE: "nose",
+                self.mp_pose.PoseLandmark.LEFT_KNEE: "left_knee",
+                self.mp_pose.PoseLandmark.RIGHT_KNEE: "right_knee",
+            }
+
+            for landmark_id, name in landmark_names.items():
+                lm = results.pose_landmarks.landmark[landmark_id]
+                landmarks[name] = (lm.x, lm.y, lm.visibility)
 
         return landmarks