feat(inspection): add frame extraction and cropping module

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

inspection/__init__.py

@@ -0,0 +1,6 @@
+"""Object Deep-Inspection backend module.
+
+Provides on-demand analysis of individual detected objects:
+frame extraction, mask retrieval, depth analysis, attention maps,
+super-resolution, and 3D point clouds.
+"""

inspection/frames.py

@@ -0,0 +1,110 @@
+"""Frame extraction and cropping from input videos.
+
+All operations use on-demand cv2.VideoCapture seeking — no frames are
+pre-extracted or stored in memory.
+"""
+
+import logging
+from typing import List, Optional, Tuple
+
+import cv2
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def extract_frame(video_path: str, frame_idx: int) -> np.ndarray:
+    """Extract a single frame from a video by index.
+
+    Args:
+        video_path: Path to the video file.
+        frame_idx: Zero-based frame index.
+
+    Returns:
+        HxWx3 BGR uint8 numpy array.
+
+    Raises:
+        ValueError: If frame_idx is out of range or video cannot be opened.
+        FileNotFoundError: If video_path does not exist.
+    """
+    cap = cv2.VideoCapture(video_path)
+    if not cap.isOpened():
+        raise FileNotFoundError(f"Cannot open video: {video_path}")
+
+    try:
+        total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        if frame_idx < 0 or frame_idx >= total:
+            raise ValueError(
+                f"Frame index {frame_idx} out of range [0, {total})"
+            )
+        cap.set(cv2.CAP_PROP_POS_FRAMES, frame_idx)
+        success, frame = cap.read()
+        if not success or frame is None:
+            raise ValueError(f"Failed to read frame {frame_idx}")
+        return frame
+    finally:
+        cap.release()
+
+
+def get_video_info(video_path: str) -> dict:
+    """Return video metadata (total_frames, fps, width, height)."""
+    cap = cv2.VideoCapture(video_path)
+    if not cap.isOpened():
+        raise FileNotFoundError(f"Cannot open video: {video_path}")
+    try:
+        return {
+            "total_frames": int(cap.get(cv2.CAP_PROP_FRAME_COUNT)),
+            "fps": cap.get(cv2.CAP_PROP_FPS) or 30.0,
+            "width": int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)),
+            "height": int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT)),
+        }
+    finally:
+        cap.release()
+
+
+def crop_frame(
+    frame: np.ndarray,
+    bbox: List[int],
+    padding: float = 0.15,
+) -> np.ndarray:
+    """Crop a frame to a bounding box with optional padding.
+
+    Args:
+        frame: HxWx3 BGR numpy array.
+        bbox: [x1, y1, x2, y2] in pixel coordinates.
+        padding: Fractional padding around the bbox (0.15 = 15% each side).
+
+    Returns:
+        Cropped HxWx3 BGR numpy array.
+    """
+    h, w = frame.shape[:2]
+    x1, y1, x2, y2 = bbox
+
+    bw = x2 - x1
+    bh = y2 - y1
+    pad_x = int(bw * padding)
+    pad_y = int(bh * padding)
+
+    cx1 = max(0, x1 - pad_x)
+    cy1 = max(0, y1 - pad_y)
+    cx2 = min(w, x2 + pad_x)
+    cy2 = min(h, y2 + pad_y)
+
+    return frame[cy1:cy2, cx1:cx2].copy()
+
+
+def frame_to_jpeg(frame: np.ndarray, quality: int = 90) -> bytes:
+    """Encode a BGR frame as JPEG bytes.
+
+    Args:
+        frame: HxWx3 BGR numpy array.
+        quality: JPEG quality (1-100).
+
+    Returns:
+        JPEG bytes.
+    """
+    encode_param = [int(cv2.IMWRITE_JPEG_QUALITY), quality]
+    success, buffer = cv2.imencode(".jpg", frame, encode_param)
+    if not success:
+        raise RuntimeError("Failed to encode frame as JPEG")
+    return buffer.tobytes()

tests/test_inspection_frames.py

@@ -0,0 +1,98 @@
+import numpy as np
+import pytest
+
+
+def test_extract_frame_returns_bgr_array(tmp_path):
+    """extract_frame should return an HxWx3 BGR numpy array."""
+    from inspection.frames import extract_frame
+
+    # Create a tiny test video (10 frames, 64x48)
+    import cv2
+    video_path = str(tmp_path / "test.mp4")
+    writer = cv2.VideoWriter(
+        video_path, cv2.VideoWriter_fourcc(*"mp4v"), 30, (64, 48)
+    )
+    for i in range(10):
+        frame = np.full((48, 64, 3), i * 25, dtype=np.uint8)
+        writer.write(frame)
+    writer.release()
+
+    frame = extract_frame(video_path, 0)
+    assert isinstance(frame, np.ndarray)
+    assert frame.shape == (48, 64, 3)
+    assert frame.dtype == np.uint8
+
+
+def test_extract_frame_different_indices(tmp_path):
+    """Different frame indices should return different pixel data."""
+    from inspection.frames import extract_frame
+    import cv2
+
+    video_path = str(tmp_path / "test.mp4")
+    writer = cv2.VideoWriter(
+        video_path, cv2.VideoWriter_fourcc(*"mp4v"), 30, (64, 48)
+    )
+    for i in range(10):
+        frame = np.full((48, 64, 3), i * 25, dtype=np.uint8)
+        writer.write(frame)
+    writer.release()
+
+    f0 = extract_frame(video_path, 0)
+    f5 = extract_frame(video_path, 5)
+    assert not np.array_equal(f0, f5)
+
+
+def test_extract_frame_out_of_range(tmp_path):
+    """Out-of-range frame index should raise ValueError."""
+    from inspection.frames import extract_frame
+    import cv2
+
+    video_path = str(tmp_path / "test.mp4")
+    writer = cv2.VideoWriter(
+        video_path, cv2.VideoWriter_fourcc(*"mp4v"), 30, (64, 48)
+    )
+    for i in range(10):
+        writer.write(np.zeros((48, 64, 3), dtype=np.uint8))
+    writer.release()
+
+    with pytest.raises(ValueError, match="out of range"):
+        extract_frame(video_path, 999)
+
+
+def test_crop_frame_to_bbox():
+    """crop_frame should extract the bbox region with padding."""
+    from inspection.frames import crop_frame
+
+    frame = np.zeros((200, 300, 3), dtype=np.uint8)
+    # Fill a known region with white
+    frame[50:100, 80:180] = 255
+
+    bbox = [80, 50, 180, 100]  # x1, y1, x2, y2
+    crop = crop_frame(frame, bbox, padding=0.0)
+    assert crop.shape == (50, 100, 3)
+    assert np.all(crop == 255)
+
+
+def test_crop_frame_with_padding():
+    """Padding should expand the crop region, clamped to frame bounds."""
+    from inspection.frames import crop_frame
+
+    frame = np.zeros((200, 300, 3), dtype=np.uint8)
+    bbox = [100, 50, 200, 150]  # 100x100 box
+    crop = crop_frame(frame, bbox, padding=0.5)
+    # 50% padding on a 100x100 box = 50px each side
+    # Expected: x=[50,250], y=[0,200] (clamped)
+    assert crop.shape[0] > 100
+    assert crop.shape[1] > 100
+
+
+def test_crop_frame_clamped_to_bounds():
+    """Padding that exceeds frame bounds should be clamped."""
+    from inspection.frames import crop_frame
+
+    frame = np.zeros((100, 100, 3), dtype=np.uint8)
+    bbox = [0, 0, 100, 100]
+    crop = crop_frame(frame, bbox, padding=1.0)
+    # Should not exceed original frame dimensions
+    assert crop.shape[0] <= 100
+    assert crop.shape[1] <= 100