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

kinemotion/core/video_io.py

@@ -2,10 +2,13 @@
 
 import json
 import subprocess
+import warnings
 
 import cv2
 import numpy as np
 
+from .timing import NULL_TIMER, Timer
+
 
 class VideoProcessor:
     """
@@ -15,14 +18,16 @@ class VideoProcessor:
     No dimensions are hardcoded - all dimensions are extracted from actual frame data.
     """
 
-    def __init__(self, video_path: str):
+    def __init__(self, video_path: str, timer: Timer | None = None) -> None:
         """
         Initialize video processor.
 
         Args:
             video_path: Path to input video file
+            timer: Optional Timer for measuring operations
         """
         self.video_path = video_path
+        self.timer = timer or NULL_TIMER
         self.cap = cv2.VideoCapture(video_path)
 
         if not self.cap.isOpened():
@@ -30,6 +35,8 @@ class VideoProcessor:
 
         self.fps = self.cap.get(cv2.CAP_PROP_FPS)
         self.frame_count = int(self.cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        self._frame_index: int = 0
+        self._current_timestamp_ms: int = 0  # Timestamp for the current frame
 
         # Read first frame to get actual dimensions
         # This is critical for preserving aspect ratio, especially with mobile videos
@@ -45,10 +52,14 @@ class VideoProcessor:
             self.width = int(self.cap.get(cv2.CAP_PROP_FRAME_WIDTH))
             self.height = int(self.cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
 
-        # Extract rotation metadata from video (iPhones store rotation in side_data_list)
-        # OpenCV ignores rotation metadata, so we need to extract and apply it manually
+        # Extract rotation metadata from video (iPhones store rotation in
+        # side_data_list). OpenCV ignores rotation metadata, so we need to
+        # extract and apply it manually
         self.rotation = 0  # Will be set by _extract_video_metadata()
 
+        # Extract codec information from video metadata
+        self.codec: str | None = None  # Will be set by _extract_video_metadata()
+
         # Calculate display dimensions considering SAR (Sample Aspect Ratio)
         # Mobile videos often have non-square pixels encoded in SAR metadata
         # OpenCV doesn't directly expose SAR, but we need to handle display correctly
@@ -65,6 +76,62 @@ class VideoProcessor:
                 self.display_width,
             )
 
+    @property
+    def current_timestamp_ms(self) -> int:
+        """Get the current frame timestamp in milliseconds.
+
+        Returns:
+            Timestamp in milliseconds for the frame most recently read.
+            For the first frame, this returns 0 ms.
+        """
+        return self._current_timestamp_ms
+
+    @property
+    def frame_index(self) -> int:
+        """Get the current frame index.
+
+        Returns:
+            Current frame number (0-based) - the frame most recently read
+        """
+        return self._frame_index
+
+    def _parse_sample_aspect_ratio(self, sar_str: str) -> None:
+        """
+        Parse SAR string and update display dimensions.
+
+        Args:
+            sar_str: SAR string in format "width:height" (e.g., "270:473")
+        """
+        if not sar_str or ":" not in sar_str:
+            return
+
+        sar_parts = sar_str.split(":")
+        sar_width = int(sar_parts[0])
+        sar_height = int(sar_parts[1])
+
+        # Calculate display dimensions if pixels are non-square
+        # DAR = (width * SAR_width) / (height * SAR_height)
+        if sar_width != sar_height:
+            self.display_width = int(self.width * sar_width / sar_height)
+            self.display_height = self.height
+
+    def _extract_rotation_from_stream(self, stream: dict) -> int:  # type: ignore[type-arg]
+        """
+        Extract rotation metadata from video stream.
+
+        Args:
+            stream: ffprobe stream dictionary
+
+        Returns:
+            Rotation angle in degrees (0, 90, -90, 180)
+        """
+        side_data_list = stream.get("side_data_list", [])
+        for side_data in side_data_list:
+            if side_data.get("side_data_type") == "Display Matrix":
+                rotation = side_data.get("rotation", 0)
+                return int(rotation)
+        return 0
+
     def _extract_video_metadata(self) -> None:
         """
         Extract video metadata including SAR and rotation using ffprobe.
@@ -94,37 +161,36 @@ class VideoProcessor:
                 timeout=5,
             )
 
-            if result.returncode == 0:
-                data = json.loads(result.stdout)
-                if "streams" in data and len(data["streams"]) > 0:
-                    stream = data["streams"][0]
-
-                    # Extract SAR (Sample Aspect Ratio)
-                    sar_str = stream.get("sample_aspect_ratio", "1:1")
-
-                    # Parse SAR (e.g., "270:473")
-                    if sar_str and ":" in sar_str:
-                        sar_parts = sar_str.split(":")
-                        sar_width = int(sar_parts[0])
-                        sar_height = int(sar_parts[1])
-
-                        # Calculate display dimensions
-                        # DAR = (width * SAR_width) / (height * SAR_height)
-                        if sar_width != sar_height:
-                            self.display_width = int(
-                                self.width * sar_width / sar_height
-                            )
-                            self.display_height = self.height
-
-                    # Extract rotation from side_data_list (common for iPhone videos)
-                    side_data_list = stream.get("side_data_list", [])
-                    for side_data in side_data_list:
-                        if side_data.get("side_data_type") == "Display Matrix":
-                            rotation = side_data.get("rotation", 0)
-                            # Convert to int and normalize to 0, 90, -90, 180
-                            self.rotation = int(rotation)
-        except (subprocess.TimeoutExpired, FileNotFoundError, json.JSONDecodeError):
-            # If ffprobe fails, keep original dimensions (square pixels)
+            if result.returncode != 0:
+                return
+
+            data = json.loads(result.stdout)
+            if "streams" not in data or len(data["streams"]) == 0:
+                return
+
+            stream = data["streams"][0]
+
+            # Extract codec name (e.g., "h264", "hevc", "vp9")
+            self.codec = stream.get("codec_name")
+
+            # Extract and parse SAR (Sample Aspect Ratio)
+            sar_str = stream.get("sample_aspect_ratio", "1:1")
+            self._parse_sample_aspect_ratio(sar_str)
+
+            # Extract rotation from side_data_list (common for iPhone videos)
+            self.rotation = self._extract_rotation_from_stream(stream)
+
+        except FileNotFoundError:
+            # ffprobe not found - warn user about reduced functionality
+            warnings.warn(
+                "ffprobe not found. Video rotation and aspect ratio metadata will be "
+                "ignored. This may cause issues with mobile/rotated videos. "
+                "Install FFmpeg for full video support: https://ffmpeg.org/download.html",
+                UserWarning,
+                stacklevel=2,
+            )
+        except (subprocess.TimeoutExpired, json.JSONDecodeError):
+            # If ffprobe fails for other reasons, silently continue with defaults
             pass
 
     def read_frame(self) -> np.ndarray | None:
@@ -133,34 +199,53 @@ class VideoProcessor:
 
         OpenCV ignores rotation metadata, so we manually apply rotation
         based on the display matrix metadata extracted from the video.
+
+        Returns:
+            Frame as numpy array or None if no more frames
         """
-        ret, frame = self.cap.read()
+        with self.timer.measure("frame_read"):
+            ret, frame = self.cap.read()
+
         if not ret:
             return None
 
-        # Apply rotation if video has rotation metadata
-        if self.rotation == -90 or self.rotation == 270:
-            # -90 degrees = rotate 90 degrees clockwise
-            frame = cv2.rotate(frame, cv2.ROTATE_90_CLOCKWISE)
-        elif self.rotation == 90 or self.rotation == -270:
-            # 90 degrees = rotate 90 degrees counter-clockwise
-            frame = cv2.rotate(frame, cv2.ROTATE_90_COUNTERCLOCKWISE)
-        elif self.rotation == 180 or self.rotation == -180:
-            # 180 degrees rotation
-            frame = cv2.rotate(frame, cv2.ROTATE_180)
+        # Calculate timestamp for this frame BEFORE incrementing index
+        # This ensures frame 0 has timestamp 0ms, frame 1 has timestamp 16ms, etc.
+        if self.fps > 0:
+            self._current_timestamp_ms = int(self._frame_index * 1000 / self.fps)
 
+        # Apply rotation if video has rotation metadata
+        with self.timer.measure("frame_rotation"):
+            if self.rotation == -90 or self.rotation == 270:
+                # -90 degrees = rotate 90 degrees clockwise
+                frame = cv2.rotate(frame, cv2.ROTATE_90_CLOCKWISE)
+            elif self.rotation == 90 or self.rotation == -270:
+                # 90 degrees = rotate 90 degrees counter-clockwise
+                frame = cv2.rotate(frame, cv2.ROTATE_90_COUNTERCLOCKWISE)
+            elif self.rotation == 180 or self.rotation == -180:
+                # 180 degrees rotation
+                frame = cv2.rotate(frame, cv2.ROTATE_180)
+
+        self._frame_index += 1
         return frame
 
-    def reset(self) -> None:
-        """Reset video to beginning."""
-        self.cap.set(cv2.CAP_PROP_POS_FRAMES, 0)
-
     def close(self) -> None:
         """Release video capture."""
         self.cap.release()
 
+    def __iter__(self) -> "VideoProcessor":
+        """Make the processor iterable."""
+        return self
+
+    def __next__(self) -> np.ndarray:
+        """Get the next frame during iteration."""
+        frame = self.read_frame()
+        if frame is None:
+            raise StopIteration
+        return frame
+
     def __enter__(self) -> "VideoProcessor":
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb) -> None:  # type: ignore[no-untyped-def]
+    def __exit__(self, _exc_type, _exc_val, _exc_tb) -> None:  # type: ignore[no-untyped-def]
         self.close()

kinemotion/dropjump/__init__.py

@@ -1,12 +1,12 @@
 """Drop jump analysis module."""
 
+from ..core.smoothing import interpolate_threshold_crossing
 from .analysis import (
     ContactState,
     calculate_adaptive_threshold,
     compute_average_foot_position,
     detect_ground_contact,
     find_interpolated_phase_transitions_with_curvature,
-    interpolate_threshold_crossing,
     refine_transition_with_curvature,
 )
 from .debug_overlay import DebugOverlayRenderer