seavision-python 0.1.1__py3-none-any.whl

seavision/engine/detectors/motion/detector.py

@@ -0,0 +1,218 @@
+"""Motion detector combining stabilisation and background modelling."""
+
+from dataclasses import dataclass, field
+from typing import Dict, Iterator, Optional
+import cv2
+import numpy as np
+
+from ...source import FrameContext
+from ..base import Detection, DetectorBase
+from .stabiliser import FrameStabiliser, StabiliserConfig
+from .background import BackgroundModel, BackgroundConfig
+
+
+@dataclass
+class MotionDetectorConfig:
+    """
+    Configuration for the motion detector.
+    
+    Attributes:
+        stabiliser: Configuration for the frame stabiliser.
+        background: Confiuguration for the background subtraction.
+        stabilisation_enabled: Whether to enable frame stabilisation.
+        min_area: Minimum area (pixels) for motion contours to be considered.
+        max_area: Maximum area (pixels) for motion contours to be considered.
+        morph_kernel_size: Kernel size for morphological operations.
+        morph_iterations: Number of iterations for morphological operations.
+    """
+
+    stabiliser: StabiliserConfig = field(
+        default_factory=StabiliserConfig
+    )
+    background: BackgroundConfig = field(
+        default_factory=BackgroundConfig
+    )
+    stabilisation_enabled: bool = True
+    min_area: int = 100  # pixels
+    max_area: int = 50000  # pixels
+    morph_kernel_size: int = 5
+    morph_iterations: int = 2
+
+    # Persistence filtering
+    persistence_enabled: bool = True
+    min_persistence: int = 3      # Frames before emitting detection
+    max_frames_missing: int = 5   # Frames before dropping track
+    iou_threshold: float = 0.3    # Minimum IoU to match detections
+
+
+class MotionDetector(DetectorBase):
+    """
+    Detects motion in video frames using background subtraction in the
+    following pipeline:
+        1. (Optional) Stabilise frame to compensate for camera motion.
+        2. Apply background subtraction to get a foreground mask.
+        3. Clean mask with morphological operations.
+        4. Find countours and filter by area.
+        5. Emit Detection objects for valid contours.
+
+    Example:
+        config = MotionDetectorConfig(min_area=200)
+
+        with MotionDetector(config) as detector:
+            for frame, context in video_source.iter_frames():
+                for detection in detector.process_frame(frame, context):
+                    # process detection
+                    pass
+    """
+
+    def __init__(self, config: Optional[MotionDetectorConfig] = None):
+        """
+        Initialise the motion detector.
+
+        Args:
+            config: Configuration for the motion detector. If None, defaults
+                are used.
+        """
+
+        self.config = config or MotionDetectorConfig()
+
+        self._stabiliser = FrameStabiliser(self.config.stabiliser)
+        self._background = BackgroundModel(self.config.background)
+
+        # Morphological operation kernel
+        self._morph_kernel = cv2.getStructuringElement(
+            cv2.MORPH_ELLIPSE,
+            (self.config.morph_kernel_size, self.config.morph_kernel_size)
+        )
+
+        # Persistence tracker
+        if self.config.persistence_enabled:
+            from .tracker import PersistenceTracker, TrackerConfig
+            tracker_config = TrackerConfig(
+                min_persistence=self.config.min_persistence,
+                max_frames_missing=self.config.max_frames_missing,
+                iou_threshold=self.config.iou_threshold
+            )
+            self._tracker = PersistenceTracker(tracker_config)
+        else:
+            self._tracker = None
+
+    
+    def process_frame(
+        self,
+        frame: np.ndarray,
+        context: FrameContext
+    ) -> Iterator[Detection]:
+        """
+        Process a single video frame and yield motion detections.
+
+        Args:
+            frame: BGR image as a numpy array (H x W x 3).
+            context: Metadata about the current frame (FrameContext class).
+        
+        Yields:
+            Detection objects for each motion contour found in the frame.
+        """
+
+        # Stage 1: Stabilisation
+        if self.config.stabilisation_enabled:
+            stabilised, _ = self._stabiliser.stabilise(frame)
+        else:
+            stabilised = frame
+
+        # Stage 2: Background subtraction
+        mask = self._background.apply(stabilised)
+
+        # Stage 3: Morphological cleaning
+        mask = self._clean_mask(mask)
+
+        # Stage 4: Extract raw detections
+        raw_detections = list(self._extract_detections(mask, context))
+
+        # Stage 5: Persistence filtering
+        if self._tracker is not None:
+            confirmed_tracks = self._tracker.update(raw_detections)
+
+            for track in confirmed_tracks:
+                yield Detection(
+                    source_file=context.source_file,
+                    timestamp=context.timestamp,
+                    frame_number=context.frame_number,
+                    xc=track.xc,
+                    yc=track.yc,
+                    width=track.width,
+                    height=track.height,
+                    confidence=None  # No confidence score for motion detection
+                )
+        else:
+            # No tracking - emit all detections
+            for det in raw_detections:
+                yield Detection(
+                    source_file=context.source_file,
+                    timestamp=context.timestamp,
+                    frame_number=context.frame_number,
+                    **det
+                )
+    
+    def _clean_mask(self, mask: np.ndarray) -> np.ndarray:
+        """
+        Apply morphological operations to clean the foreground mask.
+        """
+
+        # Opening (erosion then dilation) removes small noise
+        mask = cv2.morphologyEx(
+            mask,
+            cv2.MORPH_OPEN,
+            self._morph_kernel,
+            iterations=self.config.morph_iterations
+        )
+
+        # Closing (dilation then erosion) fills small holes
+        mask = cv2.morphologyEx(
+            mask,
+            cv2.MORPH_CLOSE,
+            self._morph_kernel,
+            iterations=self.config.morph_iterations
+        )
+
+        return mask
+    
+
+    def _extract_detections(
+        self,
+        mask: np.ndarray,
+        context: FrameContext
+    ) -> Iterator[Dict]:
+        """
+        Find contours in the mask and yield Detection dicts (for tracker input).
+        """
+
+        contours, _ = cv2.findContours(
+            mask,
+            cv2.RETR_EXTERNAL,
+            cv2.CHAIN_APPROX_SIMPLE
+        )
+
+        for contour in contours:
+            area = cv2.contourArea(contour)
+
+            # Filter by size
+            if area < self.config.min_area or area > self.config.max_area:
+                continue
+
+            # Get bounding box
+            x, y, w, h = cv2.boundingRect(contour)
+            
+            yield {
+                "xc": x + w / 2,
+                "yc": y + h / 2,
+                "width": w,
+                "height": h,
+            }
+    
+    def reset(self) -> None:
+        """Reset internal state between videos."""
+        self._stabiliser.reset()
+        self._background.reset()
+        if self._tracker is not None:
+            self._tracker.reset()

seavision/engine/detectors/motion/stabiliser.py

@@ -0,0 +1,174 @@
+"""Frame stabilisation using feature-based homography."""
+
+from dataclasses import dataclass
+from typing import Optional, Tuple
+import cv2
+import numpy as np
+
+
+@dataclass
+class StabiliserConfig:
+    """
+    Configuration for frame stabilisation.
+
+    # TODO: Glossary document which defines these things?
+    Attributes:
+        feature_detector: Feature detector type (e.g. 'ORB', 'AKAZE').
+        max_features: Maximum number of features to detect.
+        match_ratio: Lowe's ratio test threshold for feature matching.
+        min_matches: Minimum number of matches to compute homography.
+        ransac_threshold: RANSAC reprojection threshold for homography.
+    """
+
+    feature_detector: str = "ORB"
+    max_features: int = 500
+    match_ratio: float = 0.75
+    min_matches: int = 10
+    ransac_threshold: float = 5.0
+
+
+class FrameStabiliser:
+    """
+    Stabilises frames by aligning to the previous frame.
+
+    Uses feature-based homography estimation to compensate for camera motion.
+
+    Example:
+        stabiliser = FrameStabiliser()
+        
+        for frame in video_frames:
+            stable_frame = stabiliser.stabilise(frame)
+            # process stable_frame
+    """
+
+    def __init__(self, config: Optional[StabiliserConfig] = None):
+        """
+        Initialise the frame stabiliser.
+
+        Args:
+            config: Configuration for the stabiliser. If None, defaults are used.
+        """
+
+        self.config = config or StabiliserConfig()
+
+        # Initialise the feature detector
+        # TODO: Are there any more obvious detector options that should be implemented?
+        if self.config.feature_detector == "ORB":
+            self._detector = cv2.ORB_create(nfeatures=self.config.max_features)
+        elif self.config.feature_detector == "AKAZE":
+            self._detector = cv2.AKAZE_create()
+        else:
+            raise ValueError(f"Unknown detector: {self.config.feature_detector}")
+        
+        # Brute-force matcher with Hamming distance (for binary descriptors)
+        # TODO: What is a matcher? this should be in the glossary
+        self._matcher = cv2.BFMatcher(cv2.NORM_HAMMING, crossCheck=False)
+
+        # State
+        self._prev_grey: Optional[np.ndarray] = None
+        self._prev_keypoints: Optional[list] = None
+        self._prev_descriptors: Optional[np.ndarray] = None
+
+    def stabilise(self, frame: np.ndarray) -> Tuple[np.ndarray, bool]:
+        """
+        Stabilise a frame by aligning it to the previous frame.
+
+        Args:
+            frame: Input BGR frame as a numpy array.
+
+        Returns:
+            Tuple of (stabilised_frame, is_stabilised) where stabilised_frame
+            is the aligned frame and is_stabilised indicates if alignment was 
+            applied. Returns the original frame if is_stabilised is False.
+        """
+
+        # Convert to greyscale - feature detection works on intensity values
+        grey = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+        
+        # Detect distinctive visual features (corners, edges) and compute
+        # binary descriptors that summarise the local appearance around each
+        keypoints, descriptors = self._detector.detectAndCompute(grey, None)
+
+        # First frame - nothing to align to
+        if self._prev_grey is None:
+            self._update_reference(grey, keypoints, descriptors)
+            return frame, True
+        
+        # Not enough features in current frame
+        if descriptors is None or len(keypoints) < self.config.min_matches:
+            self._update_reference(grey, keypoints, descriptors)
+            return frame, False
+        
+        # Match features to previous frame. For each feature in the previous
+        # frame, find the 2 most similar features in the current frame (k=2).
+        # Similarity is measured by Hamming distance between binary descriptors.
+        matches = self._matcher.knnMatch(
+            self._prev_descriptors, descriptors, k=2
+        )
+
+        # Apply Lowe's ratio test to filter ambiguous matches. A match is
+        # considered good if the best match (m) is significantly better than
+        # the second-best match (n). This rejects features that could match
+        # multiple locations (e.g., repetitive patterns).
+        good_matches = []
+        for m, n in matches:
+            if m.distance < self.config.match_ratio * n.distance:
+                good_matches.append(m)
+        
+        # Not enough good matches
+        if len(good_matches) < self.config.min_matches:
+            self._update_reference(grey, keypoints, descriptors)
+            return frame, False
+        
+        # Extract matched point coordinates:
+        # - src_pts: where features were located in the PREVIOUS frame
+        # - dst_pts: where those same features are in the CURRENT frame
+        # The difference between these tells us how the camera moved.
+        src_pts = np.float32([
+            self._prev_keypoints[m.queryIdx].pt for m in good_matches
+        ]).reshape(-1, 1, 2)
+        dst_pts = np.float32([
+            keypoints[m.trainIdx].pt for m in good_matches
+        ]).reshape(-1, 1, 2)
+
+        # Compute homography matrix H that maps dst_pts -> src_pts.
+        # H is a 3x3 transformation matrix that describes the camera motion
+        # (rotation, translation, perspective change) between frames.
+        # RANSAC robustly estimates H by ignoring outlier matches (e.g., from
+        # moving objects or mismatches).
+        H, mask = cv2.findHomography(
+            dst_pts, src_pts, 
+            cv2.RANSAC, 
+            self.config.ransac_threshold
+        )
+
+        if H is None:
+            self._update_reference(grey, keypoints, descriptors)
+            return frame, False
+        
+        # Warp current frame to align with previous frame.
+        # This applies the inverse camera motion, so stationary background
+        # objects appear in the same position as the previous frame.
+        height, width = frame.shape[:2]
+        stabilised_frame = cv2.warpPerspective(frame, H, (width, height))
+
+        # Update reference frame
+        self._update_reference(grey, keypoints, descriptors)
+        return stabilised_frame, True
+    
+    def _update_reference(
+        self, 
+        grey: np.ndarray, 
+        keypoints: Tuple, 
+        descriptors: Optional[np.ndarray]
+    ) -> None:
+        """Update the reference frame and features."""
+        self._prev_grey = grey
+        self._prev_keypoints = keypoints
+        self._prev_descriptors = descriptors
+
+    def reset(self) -> None:
+        """Reset the stabiliser state."""
+        self._prev_grey = None
+        self._prev_keypoints = None
+        self._prev_descriptors = None

seavision/engine/detectors/motion/tracker.py

@@ -0,0 +1,174 @@
+"""Simple multi-object tracker for persistence filtering."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+import numpy as np
+
+
+@dataclass
+class TrackedObject:
+    """A tracked detection across multiple frames."""
+
+    track_id: int
+    xc: float
+    yc: float
+    width: float
+    height: float
+    age: int = 1 # Frames since first seen
+    frames_since_update: int = 0 # Frames since last matched
+
+
+    def update(self, xc: float, yc: float, width: float, height: float) -> None:
+        """Update the tracked object with new detection data."""
+        self.xc = xc
+        self.yc = yc
+        self.width = width
+        self.height = height
+        self.age += 1
+        self.frames_since_update = 0
+
+    def mark_missed(self) -> None:
+        """Mark that no detection matched this frame."""
+        self.frames_since_update += 1
+
+    @property
+    def bbox(self) -> Tuple[float, float, float, float]:
+        """Get bounding box as (x1, y1, x2, y2)."""
+        x1 = self.xc - self.width / 2
+        y1 = self.yc - self.height / 2
+        x2 = self.xc + self.width / 2
+        y2 = self.yc + self.height / 2
+        return (x1, y1, x2, y2)
+
+
+@dataclass
+class TrackerConfig:
+    """Configuration for the persistence tracker."""
+
+    min_persistence: int = 3      # Frames before emitting detection
+    max_frames_missing: int = 5   # Frames before dropping track
+    iou_threshold: float = 0.3    # Minimum IoU to match detections
+
+
+def compute_iou(box1: Tuple[float, float, float, float], 
+                box2: Tuple[float, float, float, float]) -> float:
+    """Compute Intersection over Union between two boxes (x1,y1,x2,y2)."""
+    x1 = max(box1[0], box2[0])
+    y1 = max(box1[1], box2[1])
+    x2 = min(box1[2], box2[2])
+    y2 = min(box1[3], box2[3])
+    
+    intersection = max(0, x2 - x1) * max(0, y2 - y1)
+    
+    area1 = (box1[2] - box1[0]) * (box1[3] - box1[1])
+    area2 = (box2[2] - box2[0]) * (box2[3] - box2[1])
+    union = area1 + area2 - intersection
+    
+    return intersection / union if union > 0 else 0
+
+
+class PersistenceTracker:
+    """
+    tracks detections across frames and filters out transient noise.
+
+    Only emits detections that have persisted for min_persistence frames.
+
+    Example:
+        tracker = PersistenceTracker(TrackerConfig(min_persistence=3))
+        
+        for frame_detections in all_detections:
+            confirmed = tracker.update(frame_detections)
+            # confirmed only contains detections seen for 3+ frames
+    """
+
+    def __init__(self, config: Optional[TrackerConfig] = None):
+        self.config = config or TrackerConfig()
+        self._tracks: Dict[int, TrackedObject] = {}
+        self._next_id: int = 0
+
+    def update(self, detections: List[dict]) -> List[TrackedObject]:
+        """
+        Update tracker with new frame detections.
+
+        Args:
+            detections: List of detection dicts with keys:
+                'xc', 'yc', 'width', 'height'.
+        
+        Returns:
+            A list of tracked objects that have a persistence >= 
+            min_persistence frames.
+        """
+
+        # Convert detections to bbox format for matching
+        det_boxes = []
+        for det in detections:
+            x1 = det["xc"] - det["width"] / 2
+            y1 = det["yc"] - det["height"] / 2
+            x2 = det["xc"] + det["width"] / 2
+            y2 = det["yc"] + det["height"] / 2
+            det_boxes.append((x1, y1, x2, y2))
+
+        # Match detections to existing tracks using IoU
+        matched_tracks = set()
+        matched_dets = set()
+
+        # Greedy matching, highest IoU first
+        if self._tracks and det_boxes:
+            iou_matrix = []
+
+            for track_id, track in self._tracks.items():
+                for det_idx, det_box in enumerate(det_boxes):
+                    iou = compute_iou(track.bbox, det_box)
+                    if iou >= self.config.iou_threshold:
+                        iou_matrix.append((iou, track_id, det_idx))
+            
+            # Sort by IoU descending
+            iou_matrix.sort(reverse=True, key=lambda x: x[0])
+
+            for iou, track_id, det_idx in iou_matrix:
+                if track_id not in matched_tracks and det_idx not in matched_dets:
+                    # Update track with matched detection
+                    det = detections[det_idx]
+                    self._tracks[track_id].update(
+                        det["xc"], det["yc"], det["width"], det["height"]
+                    )
+                    matched_tracks.add(track_id)
+                    matched_dets.add(det_idx)
+        
+        # Mark unmatched tracks as missed
+        for track_id in self._tracks:
+            if track_id not in matched_tracks:
+                self._tracks[track_id].mark_missed()
+        
+        # Create new tracks for unmatched detections
+        for det_idx, det in enumerate(detections):
+            if det_idx not in matched_dets:
+                self._tracks[self._next_id] = TrackedObject(
+                    track_id=self._next_id,
+                    xc=det["xc"],
+                    yc=det["yc"],
+                    width=det["width"],
+                    height=det["height"],
+                )
+                self._next_id += 1
+
+        # Remove stale tracks
+        stale_ids = [
+            track_id for track_id, track in self._tracks.items()
+            if track.frames_since_update > self.config.max_frames_missing
+        ]
+        for track_id in stale_ids:
+            del self._tracks[track_id]
+
+        # Return only tracks that have persisted long enough
+        confirmed = [
+            track for track in self._tracks.values()
+            if track.age >= self.config.min_persistence
+        ]
+
+        return confirmed
+    
+    def reset(self) -> None:
+        """Reset the tracker state for a new video."""
+        self._tracks.clear()
+        self._next_id = 0

seavision/engine/detectors/sam3/__init__.py

@@ -0,0 +1,23 @@
+"""SAM 3 (Segment Anything Model 3) detector module."""
+
+from .config import (
+    PromptType,
+    HybridStrategy,
+    PrompterConfig,
+    PromptConfig,
+    SAM3DetectorConfig,
+)
+from .detector import SAM3Detector
+from .native import SAM3NativeDetector
+
+__all__ = [
+    # Config
+    "PromptType",
+    "HybridStrategy",
+    "PrompterConfig",
+    "PromptConfig",
+    "SAM3DetectorConfig",
+    # Detector
+    "SAM3Detector",
+    "SAM3NativeDetector",
+]