seavision-python 0.1.1__py3-none-any.whl

seavision/engine/visualiser/visualiser.py

@@ -0,0 +1,402 @@
+"""High level visualiser orchestrators."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Iterator, List, Optional
+import numpy as np
+
+from ..source.base import VideoSource, VideoMetadata, FrameContext
+from ..detectors.base import Detection
+from .config import VisualiserConfig, OutputMode
+from .annotator import FrameAnnotator
+from .writer import VideoWriterHandle, OutputNameFunction
+from .loader import DetectionSource, CSVDetectionLoader
+
+
+@dataclass
+class AnnotatedFrame:
+    """Container for an annotated frame (for streaming output)."""
+    frame: np.ndarray
+    frame_number: int
+    timestamp: float
+    detections: List[Detection]
+    source_file: str
+
+
+@dataclass
+class VisualisationResult:
+    """Result statistics from visualisation."""
+    source_file: str
+    output_path: Optional[str]
+    total_frames: int
+    frames_with_detections: int
+    total_detections: int
+
+    def summary(self) -> str:
+        """Create a human readable output of validation results."""
+        return (
+            f"Visualised: {Path(self.source_file).name}\n"
+            f"  Output: {self.output_path or '(stream only)'}\n"
+            f"  Frames: {self.total_frames} "
+            f"({self.frames_with_detections} with detections)\n"
+            f"  Detections: {self.total_detections}"
+        )
+
+
+class LiveVisualiser:
+    """
+    Visualiser for integration with the detection pipeline.
+    
+    Designed to be called frame-by-frame as detections are generated,
+    rather than loading detections from CSV post-hoc.
+    
+    Lifecycle:
+        1. Create LiveVisualiser with config
+        2. Call start_video() when beginning a new video
+        3. Call process_frame() for each frame + its detections
+        4. Call end_video() when finished with that video
+    
+    Example (pipeline integration):
+        visualiser = LiveVisualiser(config)
+        
+        for source in sources:
+            visualiser.start_video(source.get_metadata())
+            
+            for frame, context in source.iter_frames():
+                detections = list(detector.process_frame(frame, context))
+                annotated = visualiser.process_frame(frame, detections, context)
+            
+            result = visualiser.end_video()
+            print(result.summary())
+    
+    Example (custom naming):
+        def device_date_namer(meta: VideoMetadata) -> str:
+            # Parse S3 URI to extract device and date
+            parts = meta.source_file.split('/')
+            device = parts[-4]  # e.g., "cam-3-0"
+            date = parts[-2]    # e.g., "2025-01-15"
+            stem = Path(meta.source_file).stem
+            return f"{device}_{date}_{stem}"
+        
+        visualiser = LiveVisualiser(config, name_function=device_date_namer)
+    """
+
+    def __init__(
+        self, 
+        config: Optional[VisualiserConfig] = None,
+        name_function: Optional[OutputNameFunction] = None
+    ):
+        """
+        Initialise the live visualiser.
+
+        Args:
+            config: Visualisation configuration. If None, defaults are used.
+            name_function: Optional custom function to generate output filenames.
+                Takes VideoMetadata, returns the filename stem (without suffix
+                or extension). If None, uses default naming based on source path.
+        """
+        self._config = config or VisualiserConfig()
+        self._name_function = name_function
+        self._annotator = FrameAnnotator(
+            self._config.bbox_style,
+            self._config.label_style,
+            self._config.overlay_style,
+        )
+        
+        # Per-video state
+        self._writer: Optional[VideoWriterHandle] = None
+        self._metadata: Optional[VideoMetadata] = None
+        self._frames_processed: int = 0
+        self._frames_with_detections: int = 0
+        self._total_detections: int = 0
+
+    def start_video(self, metadata: VideoMetadata) -> None:
+        """
+        Begin visualisation for a new video.
+        
+        Args:
+            metadata: Metadata for the video being processed.
+        
+        Raises:
+            RuntimeError: If called while another video is in progress.
+        """
+
+        if self._writer is not None:
+            raise RuntimeError(
+                "Previous video not ended. Call end_video() first."
+            )
+        
+        self._metadata = metadata
+        self._frames_processed = 0
+        self._frames_with_detections = 0
+        self._total_detections = 0
+
+        # Open video writer if outputting to file
+        if self._config.output_mode in (OutputMode.FILE, OutputMode.BOTH):
+            self._writer = VideoWriterHandle(
+                self._config.video_output,
+                metadata,
+                name_function=self._name_function
+            )
+    
+    def process_frame(
+        self, frame: np.ndarray,
+        detections: List[Detection],
+        context: FrameContext
+    ) -> Optional[AnnotatedFrame]:
+        """
+        Process a single frame with its detections.
+        
+        Args:
+            frame: BGR image as numpy array
+            detections: List of detections for this frame
+            context: Frame context with metadata
+
+        Returns:
+            AnnotatedFrame if output_mode includes STREAM, else None.
+        
+        Raises:
+            RuntimeError: If called when no video is in progress.
+        """
+
+        if self._metadata is None:
+            raise RuntimeError(
+                "No video in progress. Call start_video() first."
+            )
+        
+        # Apply confidence filter
+        if self._config.min_confidence is not None:
+            detections = [
+                d for d in detections
+                if d.confidence is None
+                or d.confidence >= self._config.min_confidence
+            ]
+
+        # Skip frames without detections if configured
+        if self._config.only_frames_with_detections and not detections:
+            return None
+        
+        # Update statistics
+        self._frames_processed += 1
+        self._total_detections += len(detections)
+        if detections:
+            self._frames_with_detections += 1
+
+        # Annotate frame
+        annotated = self._annotator.annotate_frame(
+            frame, detections, context, copy=True
+        )
+
+        # Write to video file if configured
+        if self._writer is not None:
+            self._writer.write(annotated)
+        
+        # Return for streaming if configured
+        if self._config.output_mode in (OutputMode.STREAM, OutputMode.BOTH):
+            return AnnotatedFrame(
+                frame=annotated,
+                frame_number=context.frame_number,
+                timestamp=context.timestamp,
+                detections=detections,
+                source_file=self._metadata.source_file
+            )
+
+        return None
+    
+    def end_video(self) -> VisualisationResult:
+        """
+        Finish visualisation for the current video.
+        
+        Returns:
+            VisualisationResult with summary statistics.
+        
+        Raises:
+            RuntimeError: If called when no video is in progress.
+        """
+
+        if self._metadata is None:
+            raise RuntimeError("No video in progress")
+
+        # Close video writer
+        output_path = None
+        if self._writer is not None:
+            output_path = str(self._writer.output_path)
+            self._writer.close()
+            self._writer = None
+
+        result = VisualisationResult(
+            source_file=self._metadata.source_file,
+            output_path=output_path,
+            total_frames=self._frames_processed,
+            frames_with_detections=self._frames_with_detections,
+            total_detections=self._total_detections,
+        )
+
+        # Reset state
+        self._metadata = None
+
+        return result
+    
+
+    def __enter__(self) -> "LiveVisualiser":
+        return self
+    
+    
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        # Clean up if video was not properly ended
+        if self._writer is not None:
+            self._writer.close()
+            self._writer = None
+        return False
+
+
+class PostHocVisualiser:
+    """
+    Visualiser for post-hoc processing from CSV detection files.
+    
+    Reads detections from CSV and overlays them on the source video.
+    
+    Example:
+        visualiser = PostHocVisualiser(config)
+        
+        with LocalVideoSource("footage/video.ts") as source:
+            result = visualiser.visualise(source, "results/video_detections.csv")
+            print(result.summary())
+    
+    Example (custom naming):
+        def custom_namer(meta: VideoMetadata) -> str:
+            return f"reviewed_{Path(meta.source_file).stem}"
+        
+        visualiser = PostHocVisualiser(config, name_function=custom_namer)
+    """
+
+    def __init__(
+        self, 
+        config: Optional[VisualiserConfig] = None,
+        name_function: Optional[OutputNameFunction] = None
+    ):
+        self._config = config or VisualiserConfig()
+        self._name_function = name_function
+        self._annotator = FrameAnnotator(
+            self._config.bbox_style,
+            self._config.label_style,
+            self._config.overlay_style,
+        )
+
+
+    def visualise(
+        self,
+        video_source: VideoSource,
+        csv_path: str,
+    ) -> Iterator[AnnotatedFrame]:
+        """
+        Visualise a video using detections from a CSV file.
+
+        Args:
+            video_source: VideoSource to read frames from.
+            csv_path: Path to CSV file with detections.
+        
+        Yields:
+            AnnotatedFrame objects if output_mode includes STREAM.
+        """
+
+        detection_source = CSVDetectionLoader(
+            csv_path,
+            source_file=video_source.get_metadata().source_file
+        )
+        yield from self._visualise(video_source, detection_source)
+
+
+    def visualise_from_source(
+            self,
+            video_source: VideoSource,
+            detection_source: DetectionSource,
+    ) -> Iterator[AnnotatedFrame]:
+        """
+        Visualise a video using a detection source.
+
+        Args:
+            video_source: VideoSource to read frames from.
+            detection_source: DetectionSource to provide detections.
+        
+        Yields:
+            AnnotatedFrame objects if output_mode includes STREAM.
+        """
+        yield from self._visualise(video_source, detection_source)
+
+    
+    def _visualise(
+        self,
+        video_source: VideoSource,
+        detection_source: DetectionSource,
+    ) -> Iterator[AnnotatedFrame]:
+        """Core visualisation loop for post-hoc mode."""
+
+        metadata = video_source.get_metadata()
+        writer = None
+
+        # Statistics
+        frames_processed = 0
+        frames_with_detections = 0
+        total_detections = 0
+
+        if self._config.output_mode in (OutputMode.FILE, OutputMode.BOTH):
+            writer = VideoWriterHandle(
+                self._config.video_output,
+                metadata,
+                name_function=self._name_function
+            )
+
+        try:
+            for frame, context in video_source.iter_frames():
+                # Frame skipping
+                if context.frame_number % self._config.frame_skip != 0:
+                    continue
+                    
+                # Get detections for this frame
+                detections = detection_source.get_detections_for_frame(
+                    context.frame_number
+                )
+
+                # Apply confidence filter
+                if self._config.min_confidence is not None:
+                    detections = [
+                        d for d in detections
+                        if d.confidence is None
+                        or d.confidence >= self._config.min_confidence
+                    ]
+
+                # Skip frames without detections if configured
+                if self._config.only_frames_with_detections and not detections:
+                    continue
+
+                # Update statistics
+                frames_processed += 1
+                if detections:
+                    frames_with_detections += 1
+                    total_detections += len(detections)
+
+                # Annotate frame
+                annotated = self._annotator.annotate_frame(
+                    frame, detections, context
+                )
+
+                # Write to file
+                if writer is not None:
+                    writer.write(annotated)
+
+                # Yield for streaming
+                if self._config.output_mode in (OutputMode.STREAM, OutputMode.BOTH):
+                    yield AnnotatedFrame(
+                        frame=annotated,
+                        frame_number=context.frame_number,
+                        timestamp=context.timestamp,
+                        detections=detections,
+                        source_file=metadata.source_file
+                    )
+        finally:
+            if writer is not None:
+                writer.close()
+                
+
+

seavision/engine/visualiser/writer.py

@@ -0,0 +1,245 @@
+"""Video file writing management."""
+
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+from typing import Callable, Optional
+import re
+import cv2
+import numpy as np
+
+from ..source.base import VideoMetadata
+from .config import VideoOutputConfig
+
+
+# Type alias for custom naming functions
+# Takes VideoMatadata, returns the output filename stem 
+# (without suffix/extension)
+OutputNameFunction = Callable[[VideoMetadata], str]
+
+def extract_output_stem(
+    source_file: str,
+    include_parents: int = 2
+) -> str:
+    """
+    Extract a suitable output filename stem from a source file path or URI.
+
+    Handles both local paths and S3 URIs, including enough path components to
+    avoid collisions when multiple videos have the same filename.
+
+    Args:
+        source_file: Source file path or S3 URI.
+        include_parents: Number of parent directories to include in the output
+            stem to help avoid name collisions. Default is 2.
+
+    Returns:
+        A sanitised string suitable for use as a filename stem.
+
+    Examples:
+        # Local path
+        extract_output_stem("/home/user/footage/2025-01-15/video_001.ts")
+        # -> "2025-01-15_video_001"
+        
+        # S3 URI
+        extract_output_stem("s3://bucket/device1/cam1/2025-01-15/video_001.ts")
+        # -> "cam1_2025-01-15_video_001"
+        
+        # S3 URI with more context
+        extract_output_stem("s3://bucket/device1/cam1/2025-01-15/video_001.ts", include_parents=3)
+        # -> "device1_cam1_2025-01-15_video_001"
+    """
+
+    # Handle S3 URIs - extract the key portion
+    s3_match = re.match(r"^s3://[^/]+/(.+)$", source_file)
+    if s3_match:
+        # Use PurePosixPath for S3 keys (always forward slashes)
+        path = PurePosixPath(s3_match.group(1))
+    else:
+        # Local path
+        path = Path(source_file)    
+
+    # Get the filename stem
+    stem = path.stem
+
+    # Build output stem with parent directories
+    parts = []
+    for i in range(min(include_parents, len(list(path.parents)) - 1)):
+        parent_name = path.parents[i].name
+        if parent_name:  # Skip empty names (root)
+            parts.insert(0, parent_name)
+    parts.append(stem)
+
+    # Join with underscores and sanitise
+    output_stem = "_".join(parts)
+    
+    # Remove any characters that might cause filesystem issues
+    output_stem = re.sub(r'[<>:"/\\|?*]', '_', output_stem)
+    
+    return output_stem
+
+
+def sanitise_filename(name: str) -> str:
+    """
+    Sanitise a string to be safe for use as a filename.
+
+    Replaces or removes characters that are invalid in filenames across
+    common operating systems.
+
+    Args:
+        name: Input string to sanitize.
+
+    Returns:
+        Sanitized filename string.
+    """
+    # Replace problematic characters with underscores
+    sanitised = re.sub(r'[<>:"/\\|?*\x00-\x1f]', '_', name)
+    
+    # Collapse multiple underscores
+    sanitised = re.sub(r'_+', '_', sanitised)
+    
+    # Strip leading/trailing underscores and whitespace
+    sanitised = sanitised.strip('_ ')
+    
+    # Ensure we have something left
+    if not sanitised:
+        sanitised = "output"
+    
+    return sanitised
+
+
+@dataclass
+class VideoWriterHandle:
+    """
+    Manages the lifecycle of a video file writer.
+
+    Handles opening, writing frames, and closing video files.
+    Uses context manager pattern for safe resource cleanup.
+
+    Output naming priority:
+        1. Custom naming function (if provided)
+        2. Default naming using extact_output_stem()
+
+    Example with custom naming:
+        def my_namer(meta: VideoMetadata) -> str:
+            # Extract device and date from S3 path
+            parts = meta.source_file.split('/')
+            return f"{parts[-3]}_{parts[-2]}_{Path(meta.source_file).stem}"
+        
+        with VideoWriterHandle(config, metadata, name_function=my_namer) as writer:
+            ...
+    """
+
+    config: VideoOutputConfig
+    metadata: VideoMetadata
+    name_function: Optional[OutputNameFunction] = None
+    _writer: Optional[cv2.VideoWriter] = field(default=None, init=False)
+    _output_path: Optional[Path] = field(default=None, init=False)
+    _frame_count: int = field(default=0, init=False)
+
+    def __post_init__(self):
+        """Initialise and open the video writer."""
+        self._output_path = self._build_output_path()
+        self._ensure_output_dir()
+        self._check_overwrite()
+        self._open_writer()
+
+    def _build_output_path(self) -> Path:
+        """
+        Build the output file path from config and metadata.
+        
+        Uses custom name function if provided, otherwise falls back to
+        extract_output_stem() with configured parent directory depth.
+        """
+        output_dir = Path(self.config.output_dir)
+        
+        # Determine the output stem
+        if self.name_function is not None:
+            # Use custom naming function
+            stem = self.name_function(self.metadata)
+            stem = sanitise_filename(stem)
+        else:
+            # Default naming with parent directory context
+            stem = extract_output_stem(
+                self.metadata.source_file,
+                include_parents=self.config.include_parent_dirs
+            )
+        
+        output_name = stem + self.config.filename_suffix + self.config.format
+        return output_dir / output_name
+    
+
+    def _ensure_output_dir(self) -> None:
+        """Create output directory if it doesn't exist."""
+        self._output_path.parent.mkdir(parents=True, exist_ok=True)
+
+
+    def _check_overwrite(self) -> None:
+        """Check if output file exists and handle based on config."""
+        if self._output_path.exists() and not self.config.overwrite:
+            raise FileExistsError(
+                f"Output file already exists: {self._output_path}. "
+                "Set overwrite=True to replace."
+            )
+
+
+    def _open_writer(self) -> None:
+        """Open the cv2 VideoWriter with the specified configuration."""
+
+        fourcc = cv2.VideoWriter_fourcc(*self.config.codec)
+        fps = self.config.fps or self.metadata.fps
+
+        self._writer = cv2.VideoWriter(
+            str(self._output_path),
+            fourcc,
+            fps,
+            (self.metadata.width, self.metadata.height)
+        )
+
+        if not self._writer.isOpened():
+            raise RuntimeError(
+                f"Failed to open video writer for {self._output_path}"
+            )
+    
+
+    def write(self, frame: np.ndarray) -> None:
+        """
+        Write a frame to the video file.
+
+        Args:
+            frame: BGR image as a numpy array.
+
+        Raises:
+            RuntimeError: If the writer is not opened.
+        """
+
+        if self._writer is None:
+            raise RuntimeError("Video writer is not opened.")
+        
+        self._writer.write(frame)
+        self._frame_count += 1
+    
+
+    def close(self) -> None:
+        """Release the video writer resource."""
+        if self._writer is not None:
+            self._writer.release()
+            self._writer = None
+
+
+    @property
+    def frame_count(self) -> int:
+        """Get the number of frames written."""
+        return self._frame_count
+
+    
+    @property
+    def output_path(self) -> Optional[Path]:
+        """Get the output file path."""
+        return self._output_path
+    
+
+    def __enter__(self) -> "VideoWriterHandle":
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        self.close()
+        return False

seavision/gui/app.py

@@ -0,0 +1,30 @@
+"""SeaVision GUI application entry point."""
+
+import sys
+
+def main():
+    """Launch the SeaVision GUI."""
+
+    # Import PySide6 with error handling if not available
+    try:
+        from PySide6.QtWidgets import QApplication
+    except ImportError:
+        print(
+            "PySide6 is required for the GUI. "
+            "Install with: pip install seavision[gui]"
+        )
+        sys.exit(1)
+    
+    app = QApplication(sys.argv)
+    app.setApplicationName("SeaVision")
+
+    from seavision.gui.main_window import MainWindow
+
+    window = MainWindow()
+    window.show()
+
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    main()