seavision-python 0.1.1__py3-none-any.whl

seavision/edge/writer.py

@@ -0,0 +1,167 @@
+"""
+Detection CSV writer for the edge runtime.
+
+Produces CSV files with the same column schema as SeaVIsion's DetectionWriter, 
+so edge detections can be loaded directly into the validation GUI. The writer
+ buffers rows in memory and flushes periodically to balance write performance
+ against data safety and memory usage.
+
+ Dependencies: Only python standard libraries.
+"""
+
+import csv
+import logging
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# CSV column order — must match seavision.engine.postprocessor.CSV_HEADERS
+CSV_COLUMNS = [
+    "source_file",
+    "timestamp",
+    "frame_number",
+    "xc",
+    "yc",
+    "width",
+    "height",
+    "confidence",
+    "label",
+    "track_id",
+]
+
+
+class EdgeDetectionWriter:
+    """
+    Writes detections to CSV files in SeaVision-compatible format.
+
+    Creates one CSV per recording session (or per video file if processing 
+    files rather than live camera). Buffers rows in memory and flushes every
+    `flush_interval` frames.
+
+    Attributes:
+        output_dir: Directory where CSV files will be saved.
+        flush_interval: Number of frames between flushes to disk.
+    """
+
+    def __init__(
+        self,
+        output_dir: str,
+        source_name: str = "camera",
+        flush_interval: int = 100,
+    ):
+        """
+        Initialise the writer.
+
+        Args:
+            output_dir: Directory for output files. Created if needed.
+            source_name: Name of the source, used in filenames and in
+                the source_file column.
+            flush_interval: Flush to disk every N frames.
+        """
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+        self.source_name = source_name
+        self.flush_interval = flush_interval
+
+        # Generate a timestamped filename
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        self._csv_path = self.output_dir / f"detections_{timestamp}.csv"
+
+        self._buffer: List[Dict] = []
+        self._file = None
+        self._writer = None
+        self._frames_since_flush = 0
+        self._total_detections = 0
+
+        # Open and write header
+        self._file = open(self._csv_path, "w", newline="")
+        self._writer = csv.DictWriter(self._file, fieldnames=CSV_COLUMNS)
+        self._writer.writeheader()
+        self._file.flush()
+
+        logger.info("Detection writer opened: %s", self._csv_path)
+
+    def write(
+        self,
+        detections: List[Tuple[float, float, float, float, float, int]],
+        frame_number: int,
+        timestamp: float = 0.0,
+        class_names: Optional[Dict[int, str]] = None,
+    ) -> None:
+        """
+        Write detections for a single frame.
+
+        Args:
+            detections: List of (x1, y1, x2, y2, confidence, class_id)
+                tuples in pixel coordinates.
+            frame_number: Frame index.
+            timestamp: Timestamp in seconds from start of source.
+            class_names: Optional mapping of class_id to label string.
+        """
+        for x1, y1, x2, y2, conf, cls_id in detections:
+            # Convert xyxy to xc,yc,w,h to match SeaVision's Detection format
+            w = x2 - x1
+            h = y2 - y1
+            xc = x1 + w / 2.0
+            yc = y1 + h / 2.0
+
+            label = ""
+            if class_names and cls_id in class_names:
+                label = class_names[cls_id]
+
+            self._buffer.append({
+                "source_file": self.source_name,
+                "timestamp": f"{timestamp:.3f}",
+                "frame_number": frame_number,
+                "xc": f"{xc:.1f}",
+                "yc": f"{yc:.1f}",
+                "width": f"{w:.1f}",
+                "height": f"{h:.1f}",
+                "confidence": f"{conf:.4f}",
+                "label": label,
+                "track_id": "",
+            })
+
+        self._total_detections += len(detections)
+        self._frames_since_flush += 1
+
+        if self._frames_since_flush >= self.flush_interval:
+            self.flush()
+
+    def flush(self) -> None:
+        """Write buffered rows to disk."""
+        if not self._buffer:
+            return
+        
+        if self._writer is not None and self._file is not None:
+            self._writer.writerows(self._buffer)
+            self._file.flush()
+            self._buffer.clear()
+            self._frames_since_flush = 0
+
+    def close(self) -> None:
+        """Flush remaining buffer and close the file."""
+        self.flush()
+        if self._file is not None:
+            self._file.close()
+            self._file = None
+
+        logger.info(
+            "Detection writer closed: %s (%d detections)",
+            self._csv_path, self._total_detections,
+        )
+
+    @property
+    def csv_path(self) -> Path:
+        """Path to the current CSV file."""
+        return self._csv_path
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False

seavision/engine/__init__.py

@@ -0,0 +1,52 @@
+"""M3B detection package."""
+
+from .source import (
+    FrameContext,
+    VideoMetadata,
+    VideoSource,
+    LocalVideoSource,
+    S3VideoSource,
+    discover_local_videos,
+    discover_s3_videos,
+)
+from .detectors import Detection, DetectorBase
+from .postprocessor import (
+    OutputMode,
+    CSVWriterConfig,
+    DetectionWriter,
+    FramePostprocessor,
+    VideoPostprocessor,
+    LabelFilterConfig,
+    LabelFilter,
+    PerFrameNmsConfig,
+    PerFrameNmsPostprocessor,
+    MotionTrackVideoConfig,
+    MotionTrackVideoPostprocessor,
+    PostprocessStage,
+    build_postprocess_stages,
+)
+
+__all__ = [
+    "FrameContext",
+    "VideoMetadata", 
+    "VideoSource",
+    "Detection",
+    "DetectorBase",
+    "LocalVideoSource",
+    "S3VideoSource",
+    "discover_local_videos",
+    "discover_s3_videos",
+    "OutputMode",
+    "CSVWriterConfig",
+    "DetectionWriter",
+    "FramePostprocessor",
+    "VideoPostprocessor",
+    "LabelFilterConfig",
+    "LabelFilter",
+    "PerFrameNmsConfig",
+    "PerFrameNmsPostprocessor",
+    "MotionTrackVideoConfig",
+    "MotionTrackVideoPostprocessor",
+    "PostprocessStage",
+    "build_postprocess_stages",
+]

seavision/engine/detectors/__init__.py

@@ -0,0 +1,90 @@
+"""Detection data structures and detector interface.
+
+Base classes (Detection, DetectorBase) are imported eagerly.
+Optional detector implementations (SAM3, YOLO) use lazy imports
+to avoid pulling in torch/ultralytics at package initialisation time.
+This allows lightweight consumers (like the GUI) to import Detection
+without triggering heavy dependency loads.
+"""
+
+from .base import Detection, DetectorBase
+
+__all__ = ["Detection", "DetectorBase"]
+
+# Lazy-loaded flags — None means "not yet checked"
+_SAM3_AVAILABLE = None
+_YOLO_AVAILABLE = None
+
+# Names that trigger lazy loading when accessed
+_SAM3_NAMES = frozenset({
+    "SAM3Detector", "SAM3DetectorConfig", "PromptType",
+    "HybridStrategy", "PrompterConfig", "PromptConfig",
+    "SAM3_AVAILABLE",
+})
+_YOLO_NAMES = frozenset({
+    "YOLODetector", "YOLODetectorConfig",
+    "YOLO_AVAILABLE",
+})
+
+
+def __getattr__(name):
+    """Lazy import for optional detector implementations."""
+    global _SAM3_AVAILABLE, _YOLO_AVAILABLE
+
+    if name in _SAM3_NAMES:
+        if _SAM3_AVAILABLE is None:
+            try:
+                from .sam3 import (
+                    SAM3Detector,
+                    SAM3DetectorConfig,
+                    PromptType,
+                    HybridStrategy,
+                    PrompterConfig,
+                    PromptConfig,
+                )
+                _SAM3_AVAILABLE = True
+                # Inject into module namespace so subsequent access is fast
+                globals().update({
+                    "SAM3Detector": SAM3Detector,
+                    "SAM3DetectorConfig": SAM3DetectorConfig,
+                    "PromptType": PromptType,
+                    "HybridStrategy": HybridStrategy,
+                    "PrompterConfig": PrompterConfig,
+                    "PromptConfig": PromptConfig,
+                    "SAM3_AVAILABLE": True,
+                })
+            except Exception:
+                _SAM3_AVAILABLE = False
+                globals()["SAM3_AVAILABLE"] = False
+
+        if name == "SAM3_AVAILABLE":
+            return _SAM3_AVAILABLE
+        if not _SAM3_AVAILABLE:
+            raise ImportError(
+                f"{name} is not available (SAM3 dependencies not installed)"
+            )
+        return globals()[name]
+
+    if name in _YOLO_NAMES:
+        if _YOLO_AVAILABLE is None:
+            try:
+                from .yolo import YOLODetector, YOLODetectorConfig
+                _YOLO_AVAILABLE = True
+                globals().update({
+                    "YOLODetector": YOLODetector,
+                    "YOLODetectorConfig": YOLODetectorConfig,
+                    "YOLO_AVAILABLE": True,
+                })
+            except Exception:
+                _YOLO_AVAILABLE = False
+                globals()["YOLO_AVAILABLE"] = False
+
+        if name == "YOLO_AVAILABLE":
+            return _YOLO_AVAILABLE
+        if not _YOLO_AVAILABLE:
+            raise ImportError(
+                f"{name} is not available (YOLO dependencies not installed)"
+            )
+        return globals()[name]
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

seavision/engine/detectors/base.py

@@ -0,0 +1,179 @@
+"""Base classes for the detectors."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Iterator, Optional
+import numpy as np
+from ..source import FrameContext
+
+@dataclass
+class Detection:
+    """
+    Represents a single detection in a video frame.
+    
+    Attributes:
+        source_file: Path of the original source file.
+        timestamp: Timestamp within the video (seconds from the start).
+        frame_number: Frame index within the video.
+        xc: X coordinate of the detection center (pixels).
+        yc: Y coordinate of the detection center (pixels).
+        width: Width of the detection bounding box (pixels).
+        height: Height of the detection bounding box (pixels).
+        confidence: Confidence score of the detection (0.0 to 1.0), or None
+            if not applicable.
+        label: Optional class label for the detection.
+        track_id: Optional track ID for the detection (if tracking is used).
+        mask: Optional Segmentation mask as numpy array (H x W, uint8, 255=object).
+        metadata: Optional additional detector-specific data
+    """
+
+    source_file: str
+    timestamp: float
+    frame_number: int
+    xc: float
+    yc: float
+    width: float
+    height: float
+    confidence: Optional[float] = None
+    label: Optional[str] = None
+    track_id: Optional[int] = None
+    mask: Optional[np.ndarray] = field(default=None, repr=False)
+    metadata: Optional[dict] = field(default=None, repr=False)
+
+    def to_csv_row(self) -> dict:
+        """Convert the detection to a CSV row string. (dictionary)"""
+        row = {
+            "source_file": self.source_file,
+            "timestamp": f"{self.timestamp:.3f}",
+            "frame_number": self.frame_number,
+            "xc": f"{self.xc:.1f}",
+            "yc": f"{self.yc:.1f}",
+            "width": f"{self.width:.1f}",
+            "height": f"{self.height:.1f}",
+        }
+        
+        # Add optional fields if present
+        if self.confidence is not None:
+            row["confidence"] = f"{self.confidence:.3f}"
+        else:
+            row["confidence"] = ""
+            
+        if self.label is not None:
+            row["label"] = self.label
+        else:
+            row["label"] = ""
+            
+        if self.track_id is not None:
+            row["track_id"] = str(self.track_id)
+        else:
+            row["track_id"] = ""
+        
+        # Note: mask and metadata are not included in CSV
+        # (masks should be saved separately if needed)
+        
+        return row
+    
+    @property
+    def bbox(self) -> tuple:
+        """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)
+    
+    @property
+    def area(self) -> float:
+        """Get area of the bounding box."""
+        return self.width * self.height
+    
+    @classmethod
+    def from_bbox(
+        cls,
+        source_file: str,
+        timestamp: float,
+        frame_number: int,
+        x1: float,
+        y1: float,
+        x2: float,
+        y2: float,
+        **kwargs,
+    ) -> "Detection":
+        """
+        Create a Detection from corner-format bounding box.
+        
+        Args:
+            source_file: Path of the source file.
+            timestamp: Timestamp in seconds.
+            frame_number: Frame index.
+            x1, y1: Top-left corner.
+            x2, y2: Bottom-right corner.
+            **kwargs: Optional fields (confidence, label, track_id, etc.)
+        
+        Returns:
+            Detection with center-format coordinates.
+        """
+        xc = (x1 + x2) / 2
+        yc = (y1 + y2) / 2
+        width = x2 - x1
+        height = y2 - y1
+        
+        return cls(
+            source_file=source_file,
+            timestamp=timestamp,
+            frame_number=frame_number,
+            xc=xc,
+            yc=yc,
+            width=width,
+            height=height,
+            **kwargs,
+        )
+
+
+class DetectorBase(ABC):
+    """
+    Abstract base class for all detectors.
+
+    Subclasses must implement the `process_frame` method to analyse individual
+    frame and yield detections.
+
+    The detector maintains internal state between frames (e.g. background 
+    models, tracking state) and should be reset between video files.
+    """
+
+    @abstractmethod
+    def process_frame(
+        self,
+        frame: np.ndarray,
+        context: FrameContext
+    ) -> Iterator[Detection]:
+        """
+        Process a single video frame and yield 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 candidate found in the frame.
+        """
+        pass
+
+    def reset(self) -> None:
+        """
+        Reset detector state for a new video file.
+        
+        Override this method if your detector maintains state that should be
+        cleared between video files (e.g. background models, trackers).
+        The default implementation does nothing.
+        """
+        pass
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - performs cleanup."""
+        self.reset()
+        return False

seavision/engine/detectors/motion/__init__.py

@@ -0,0 +1,14 @@
+"""Motion detection module."""
+
+from .detector import MotionDetector, MotionDetectorConfig
+from .stabiliser import FrameStabiliser, StabiliserConfig
+from .background import BackgroundModel, BackgroundConfig
+
+__all__ = [
+    "MotionDetector", 
+    "MotionDetectorConfig", 
+    "FrameStabiliser", 
+    "StabiliserConfig",
+    "BackgroundModel",
+    "BackgroundConfig"
+]

seavision/engine/detectors/motion/background.py

@@ -0,0 +1,92 @@
+"""Background subtraction for foreground detection."""
+
+from dataclasses import dataclass
+from typing import Optional
+import cv2
+import numpy as np
+
+
+@dataclass
+class BackgroundConfig:
+    """
+    Configuration for background subtraction.
+    
+    Attributes:
+        history: Number of frames used to build the background model.
+        var_threshold:Variance threshold for foreground classification.
+        detect_shadows: Whether to detect shadows in the foreground mask.
+        learning_rate: Background model learning rate. Use -1 for auto,
+            or a value in [0,1] where higher = faster adaptation.
+    """
+
+    history: int = 600 # 1 minute at 10 FPS
+    var_threshold: float = 16.0
+    detect_shadows: bool = True
+    learning_rate: float = -1.0  # Auto
+
+
+class BackgroundModel:
+    """
+    Adaptive background subtraction using MOG2.
+
+    Maintains a per-pixel Gaussian mixture model (GMM) to distinguish forground
+    (moving objects) from background (static scene).
+
+    Example:
+        bg_model = BackgroundModel()
+        
+        for frame in stabilised_frames:
+            fg_mask = bg_model.apply(frame)
+            # mask is binary image where 255 = foreground; 0 = background
+    """
+
+    def __init__(self, config: Optional[BackgroundConfig] = None):
+        """
+        Initialise the background model.
+
+        Args:
+            config: Configuration for the background model. If None, defaults
+                are used.
+        """
+
+        self.config = config or BackgroundConfig()
+
+        self._subtractor = cv2.createBackgroundSubtractorMOG2(
+            history=self.config.history,
+            varThreshold=self.config.var_threshold,
+            detectShadows=self.config.detect_shadows,
+        )
+    
+    def apply(self, frame: np.ndarray) -> np.ndarray:
+        """
+        Apply background subtraction to a frame.
+
+        Args:
+            frame: Input BGR frame as a numpy array - should already be 
+                stabilised.
+
+        Returns:
+            Foreground mask as a binary numpy array (uint8) where:
+            255 = foreground; 0 = background.
+        """
+
+        mask = self._subtractor.apply(
+            frame,
+            learningRate=self.config.learning_rate
+        )
+
+        # Ensure binary output (MOG2 can produce grey values for shadows)
+        _, mask = cv2.threshold(mask, 127, 255, cv2.THRESH_BINARY)
+
+        return mask
+    
+    def reset(self) -> None:
+        """
+        Reset the background model to initial state.
+        """
+
+        self._subtractor = cv2.createBackgroundSubtractorMOG2(
+            history=self.config.history,
+            varThreshold=self.config.var_threshold,
+            detectShadows=self.config.detect_shadows,
+        )