seavision-python 0.1.1__py3-none-any.whl

seavision/engine/source/__init__.py

@@ -0,0 +1,16 @@
+"""Video source handling."""
+
+from .base import FrameContext, VideoMetadata, VideoSource
+from .local import LocalVideoSource
+from .s3 import S3VideoSource
+from .discovery import discover_local_videos, discover_s3_videos
+
+__all__ = [
+    "FrameContext", 
+    "VideoMetadata",
+    "VideoSource", 
+    "LocalVideoSource",
+    "S3VideoSource",
+    "discover_local_videos",
+    "discover_s3_videos",
+]

seavision/engine/source/base.py

@@ -0,0 +1,87 @@
+"""Base classes for video source handling."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Iterator, Tuple
+import numpy as np
+
+
+@dataclass
+class VideoMetadata:
+    """
+    Metadata for a video source.
+
+    Attributes:
+        source_file: Path of the original source file.
+        fps: Frames per second of the video.
+        frame_count: Total number of frames in the video.
+        width: Width of the video frames (pixels).
+        height: Height of the video frames (pixels).
+        duration: Duration of the video (seconds).
+    """
+    source_file: str
+    fps: float
+    frame_count: int
+    width: int
+    height: int
+    duration: float
+
+
+@dataclass
+class FrameContext:
+    """Context information passed with each frame to detectors.
+    
+    Attributes:
+        source_file: Path or identifier of the source video.
+        frame_number: Frame index within the video.
+        timestamp: Timestamp within the video (seconds from start).
+        fps: Frames per second of the source video.
+    """
+    source_file: str
+    frame_number: int
+    timestamp: float
+    fps: float
+
+
+class VideoSource(ABC):
+    """Abstract base class for video sources.
+    
+    Provides a common interface for loading video frames from different
+    backends (local files, S3, etc.).
+    """
+    
+    @abstractmethod
+    def iter_frames(self) -> Iterator[Tuple[np.ndarray, FrameContext]]:
+        """Iterate over frames in the video.
+        
+        Yields:
+            Tuple of (frame, context) where frame is a BGR numpy array
+            and context contains metadata about the frame.
+        """
+        pass
+    
+    @abstractmethod
+    def get_metadata(self) -> VideoMetadata:
+        """Get metadata about the video source.
+        
+        Returns:
+            VideoMetadata object with file information.
+        """
+        pass
+    
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - performs cleanup."""
+        self.close()
+        return False
+    
+    def close(self) -> None:
+        """Release any resources held by the source.
+        
+        Override this method if your source needs cleanup
+        (e.g., closing file handles, network connections).
+        """
+        pass

seavision/engine/source/discovery.py

@@ -0,0 +1,154 @@
+"""Video source discovery functions."""
+
+import logging
+from pathlib import Path
+from typing import List, Optional
+
+from .base import VideoSource
+from .local import LocalVideoSource
+
+logger = logging.getLogger(__name__)
+
+
+def discover_local_videos(
+        path: str,
+        pattern: str = "*.ts"
+) -> List[VideoSource]:
+    """
+    Discover video files on the local file system.
+
+    Args:
+        path: Path to a video file or directory containing videos.
+        pattern: Glob pattern to match video files in directories.
+    
+    Returns:
+        List of LocalVideoSource instances (unopened - will opened when iterated
+        in the pipeline).
+    
+    Raises:
+        FileNotFoundError: If the specified path does not exist.
+        ValueError: If no video files are found in the specified directory.
+    
+    Example:
+        sources = discover_local_videos("./footage/", "*.ts")
+        for source in sources:
+            with source:
+                for frame, context in source.iter_frames():
+                    # process frame        
+    """
+
+    input_path = Path(path)
+
+    if input_path.is_file():
+        logger.debug(f"Discovered single video: {input_path}")
+        return [LocalVideoSource(str(input_path))]
+
+    elif input_path.is_dir():
+        video_paths = list(input_path.glob(pattern))
+        
+        if not video_paths:
+            raise ValueError(
+                f"No files matching '{pattern}' found in {input_path}"
+            )
+        
+        logger.debug(f"Discovered {len(video_paths)} videos in: {input_path}")
+        return [LocalVideoSource(str(p)) for p in video_paths]
+    
+    else:
+        raise FileNotFoundError(f"Path not found: {input_path}")
+
+def discover_s3_videos(
+    bucket: str,
+    prefix: str = "",
+    pattern: str = "*.ts",
+    region_name: Optional[str] = None,
+    profile_name: Optional[str] = None,
+    endpoint_url: Optional[str] = None,
+) -> List[VideoSource]:
+    """
+    Discover video files in an S3 bucket.
+    
+    Args:
+        bucket: S3 bucket name.
+        prefix: Key prefix to filter objects (e.g., "footage/2025/").
+        pattern: Glob pattern for matching video filenames (e.g. "*.ts").
+        region_name: AWS region name, if None uses the default from config.
+        profile_name: AWS profile name for SSO authentication. If None,
+            uses default credentials chain.
+        endpoint_url: Custom S3-compatible endpoint URL (e.g. Wasabi).
+    
+    Returns:
+        List of S3VideoSource instances (not yet connected).
+    
+    Raises:
+        ImportError: If boto3 is not installed.
+        ValueError: If no matching video files are found.
+    
+    Example:
+        # Using SSO profile
+        sources = discover_s3_videos(
+            bucket="my-buoy-footage",
+            prefix="2025/10/",
+            pattern="*.ts",
+            profile_name="sso-profile-name"
+        )
+        for source in sources:
+            with source:
+                for frame, context in source.iter_frames():
+                    # process frame
+                    pass
+    """
+    try:
+        import boto3
+    except ImportError:
+        raise ImportError(
+            "boto3 is required for S3 support. "
+            "Install with `pip install boto3`."
+        )
+
+    from fnmatch import fnmatch
+    from .s3 import S3VideoSource
+
+    # Create S3 client via session (supports SSO profiles and custom endpoints)
+    session = boto3.Session(
+        profile_name=profile_name,
+        region_name=region_name,
+    )
+    s3_client = session.client("s3", endpoint_url=endpoint_url)
+    paginator = s3_client.get_paginator("list_objects_v2")
+
+    matching_keys = []
+
+    # Paginate through all objects in the bucket with the given prefix
+    page_iterator = paginator.paginate(Bucket=bucket, Prefix=prefix)
+
+    for page in page_iterator:
+        if "Contents" not in page:
+            continue
+
+        for obj in page["Contents"]:
+            key = obj["Key"]
+            filename = key.split("/")[-1]
+            
+            if fnmatch(filename, pattern):
+                matching_keys.append(key)
+
+    if not matching_keys:
+        raise ValueError(
+            f"No files matching '{pattern}' found in s3://{bucket}/{prefix}"
+        )
+    
+    # Sort for deterministic order
+    matching_keys.sort()
+
+    logger.debug(f"Discovered {len(matching_keys)} videos in s3://{bucket}/{prefix}")
+
+    return [
+        S3VideoSource(
+            f"s3://{bucket}/{key}",
+            region_name=region_name,
+            profile_name=profile_name,
+            endpoint_url=endpoint_url,
+        )
+        for key in matching_keys
+    ]

seavision/engine/source/local.py

@@ -0,0 +1,155 @@
+"""Loading a locally stored video file as a video source."""
+
+from pathlib import Path
+from typing import Iterator, Tuple
+import cv2
+import numpy as np
+import subprocess
+
+from .base import FrameContext, VideoMetadata, VideoSource
+
+
+class LocalVideoSource(VideoSource):
+    """
+    Loads video frames from a local file using OpenCV.
+    
+    Attributes:
+        file_path: Path to the local video file.
+
+    Methods:
+        get_metadata: Get metadata about the video file.
+        iter_frames: Iterate over frames in the video file.
+        process_gopro: Process GoPro video to strip audio stream.
+        close: Release the video capture resource.
+    
+    Example:
+        with LocalVideoSource("footage/clip_001.ts") as source:
+            metadata = source.get_metadata()
+            print(f"Processing {metadata.duration:.1f}s video")
+            
+            for frame, context in source.iter_frames():
+                # process frame
+                pass
+    """
+
+    def __init__(self, filepath: str):
+        """
+        Initialise the video source.
+
+        Args:
+            filepath: Path to the local video file.
+        
+        Raises:
+            ValueError: If the video file cannot be opened
+        """
+
+        self.filepath = filepath
+        self._cap = cv2.VideoCapture(filepath)
+        
+        if not self._cap.isOpened():
+            raise ValueError(f"Cannot open video file: {filepath}")
+
+    def get_metadata(self) -> VideoMetadata:
+        """
+        Get metadata about the video file.
+
+        Returns:
+            VideoMetadata object with file propoerties.
+        """
+
+        fps = self._cap.get(cv2.CAP_PROP_FPS)
+        frame_count = int(self._cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        width = int(self._cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(self._cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        duration = frame_count / fps if fps > 0 else 0.0
+
+        return VideoMetadata(
+            source_file=self.filepath,
+            fps=fps,
+            frame_count=frame_count,
+            width=width,
+            height=height,
+            duration=duration
+        )
+    
+    def iter_frames(self) -> Iterator[Tuple[np.ndarray, FrameContext]]:
+        """
+        Iterate over frames in the video file.
+
+        Yields:
+            Tuple of (frame, context) where frame is a BGR numpy array
+            and context contains metadata about the frame.
+        """
+
+        fps = self._cap.get(cv2.CAP_PROP_FPS)
+        frame_number = 0
+
+        while True:
+            ret, frame = self._cap.read()
+
+            if not ret:
+                break
+            
+            timestamp = frame_number / fps if fps > 0 else 0.0
+            context = FrameContext(
+                source_file=self.filepath,
+                frame_number=frame_number,
+                timestamp=timestamp,
+                fps=fps
+            )
+
+            yield frame, context
+            frame_number += 1
+
+    def process_gopro(self, processed_path: Path, overwrite: bool = False) -> None:
+        """
+        Method for processing local GoPro video to strip audio stream. This
+        method uses ffmpeg to strip the audio stream from the video and save
+        the processed video to the specified path.
+
+        The LocalVideoSource object will point to the updated processed file
+        after this method is called.
+
+        An ffmpeg installation is required for this method to work.
+
+        Args:
+            processed_path: Path at which the processed output should be
+                saved.
+            overwrite: Whether to overwrite an existing processed file.
+        
+        Raises:
+            FileExistsError: If the processed file already exists and
+                overwrite is False.
+        """
+
+        # Ensure output path exists
+        processed_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Check if the file already exists
+        if processed_path.exists() and not overwrite:
+            raise FileExistsError(f"Processed file already exists: {processed_path}")
+
+        cmd = [
+            "ffmpeg",
+            "-i", str(self.filepath),
+            "-y", # Overwrite output files without asking
+            "-map", "0:v",  # Map only the video stream
+            "-c", "copy",
+            str(processed_path)
+        ]
+
+        subprocess.run(cmd, check=True)
+        
+        # Update path
+        self.filepath = str(processed_path)
+
+        # Update capture object
+        self._cap.release()
+        self._cap = cv2.VideoCapture(self.filepath)
+
+    
+    def close(self) -> None:
+        """Release the video capture resource."""
+        if self._cap is not None and self._cap.isOpened():
+            self._cap.release()
+            self._cap = None

seavision/engine/source/s3.py

@@ -0,0 +1,231 @@
+"""Loading video files from AWS S3 as a video source."""
+
+import logging
+import re
+from typing import Iterator, Optional, Tuple
+
+import cv2
+import numpy as np
+
+try:
+    import boto3
+    from botocore.exceptions import ClientError
+    BOTO3_AVAILABLE = True
+except ImportError:
+    BOTO3_AVAILABLE = False
+
+from .base import FrameContext, VideoMetadata, VideoSource
+
+logger = logging.getLogger(__name__)
+
+
+def parse_s3_uri(uri: str) -> Tuple[str, str]:
+    """
+    Parse an S3 URI into bucket and key components.
+
+    Args:
+        uri: S3 URI (e.g., "s3://bucket-name/path/to/.file.ts").
+
+    Returns:
+        Tuple of (bucket_name, key).
+    
+    Raises:
+        ValueError: If the URI is not a valid S3 URI.
+    """
+
+    match = re.match(r"^s3://([^/]+)/(.+)$", uri)
+    if not match:
+        raise ValueError(
+            f"Invalid S3 URI: {uri}. Expected format: s3://bucket/key"
+        )
+    return match.group(1), match.group(2)
+
+
+class S3VideoSource(VideoSource):
+    """
+    Loads video frames from an AWS S3 bucket using pre-signed URLs.
+    
+    Uses OpenCV's HTTP streaming capability to read video directly from S3
+    without downloading to a temporary file.
+    
+    Attributes:
+        uri: S3 URI to the video file (e.g., "s3://bucket-name/path/to/.file.ts").
+    
+    Example:
+        with S3VideoSource("s3://my-bucket/footage/clip_001.ts") as source:
+            metadata = source.get_metadata()
+            print(f"Processing {metadata.duration:.1f}s video")
+            
+            for frame, context in source.iter_frames():
+                # process frame
+                pass
+    
+    Note:
+        Requires boto3 to be installed and AWS credentials configured.
+        Credentials are read from environment variables, ~/.aws/credentials,
+        IAM role (if running on AWS infrastructure), or SSO profile.
+    """
+
+    def __init__(
+        self,
+        uri: str,
+        presigned_url_expiry: int = 14400,
+        region_name: Optional[str] = None,
+        profile_name: Optional[str] = None,
+        endpoint_url: Optional[str] = None,
+    ):
+        """
+        Initialise the S3 video source.
+
+        Args:
+            uri: S3 URI to the video file (e.g., "s3://bucket/path/video.ts").
+            presigned_url_expiry: Expiry time in seconds for the presigned URL.
+                Default is 14400 (4 hours).
+            region_name: AWS region name. If None, uses default region from 
+                config.
+            profile_name: AWS profile name for SSO authentication. If None,
+                uses default credentials chain.
+            endpoint_url: Custom S3-compatible endpoint URL (e.g. Wasabi).
+        
+        Raises:
+            ImportError: If boto3 is not installed.
+            ValueError: If the URI is invalid.
+        """
+        
+        if not BOTO3_AVAILABLE:
+            raise ImportError(
+                "boto3 is required for S3 support. "
+                "Install with `pip install boto3`."
+            )
+        
+        self.uri = uri
+        self.presigned_url_expiry = presigned_url_expiry
+        self.bucket, self.key = parse_s3_uri(uri)
+
+        # Create S3 client via session (supports SSO profiles and custom endpoints)
+        session = boto3.Session(
+            profile_name=profile_name,
+            region_name=region_name,
+        )
+        self._s3_client = session.client("s3", endpoint_url=endpoint_url)
+
+        # State - lazy initialisation
+        self._presigned_url: Optional[str] = None
+        self._cap: Optional[cv2.VideoCapture] = None
+        self._metadata: Optional[VideoMetadata] = None
+
+    
+    def _ensure_connected(self) -> None:
+        """
+        Ensure the video capture is connected and ready.
+
+        Generates pre-signed URL and open VideoCapture on first call.
+
+        Raises:
+            RuntimeError: If unable to open video stream.
+        """
+
+        if self._cap is not None:
+            return  # Already connected
+
+        # Generate pre-signed URL
+        try:
+            self._presigned_url = self._s3_client.generate_presigned_url(
+                "get_object",
+                Params={"Bucket": self.bucket, "Key": self.key},
+                ExpiresIn=self.presigned_url_expiry,
+            )
+            logger.debug(f"Generated pre-signed URL for {self.uri}")
+        except ClientError as e:
+            raise RuntimeError(
+                f"Failed to generate pre-signed URL for {self.uri}: {e}"
+            )
+        
+        # Open video capture
+        self._cap = cv2.VideoCapture(self._presigned_url)
+
+        if not self._cap.isOpened():
+            raise RuntimeError(
+                f"Cannot open video stream from S3: {self.uri}. "
+                "OpenCV may not support streaming this format via HTTP."
+            )
+
+        # Validate we can read metadata
+        frame_count = int(self._cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        if frame_count <= 0:
+            logger.warning(
+                f"Frame count not available for {self.uri}. "
+                "Progress tracking may be inaccurate."
+            )
+
+
+    def get_metadata(self) -> VideoMetadata:
+        """
+        Get metadata about the video file.
+
+        Returns:
+            VideoMetadata object with file properties.
+        """       
+        self._ensure_connected()
+        
+        if self._metadata is not None:
+            return self._metadata
+        
+        fps = self._cap.get(cv2.CAP_PROP_FPS)
+        frame_count = int(self._cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        width = int(self._cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(self._cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        duration = frame_count / fps if fps > 0 else 0.0
+
+        self._metadata = VideoMetadata(
+            source_file=self.uri,
+            fps=fps,
+            frame_count=frame_count,
+            width=width,
+            height=height,
+            duration=duration,
+        )
+        
+        return self._metadata
+
+
+    def iter_frames(self) -> Iterator[Tuple[np.ndarray, FrameContext]]:
+        """
+        Iterate over frames in the video file.
+
+        Yields:
+            Tuple of (frame, context) where frame is a BGR numpy array
+            and context contains metadata about the frame.
+        """
+        self._ensure_connected()
+
+        fps = self._cap.get(cv2.CAP_PROP_FPS)
+        frame_number = 0
+
+        while True:
+            ret, frame = self._cap.read()
+            
+            if not ret:
+                break  # End of video
+
+            timestamp = frame_number / fps if fps > 0 else 0.0
+
+            context = FrameContext(
+                source_file=self.uri,
+                frame_number=frame_number,
+                timestamp=timestamp,
+                fps=fps,
+            )
+
+            yield frame, context
+            frame_number += 1
+
+
+    
+    def close(self) -> None:
+        """Release the video capture resource."""
+        if self._cap is not None and self._cap.isOpened():
+            self._cap.release()
+            self._cap = None
+        self._presigned_url = None
+        self._metadata = None

seavision/engine/visualiser/__init__.py

@@ -0,0 +1,62 @@
+"""Visualiser module for detection overlay on video."""
+
+from .config import (
+    OutputMode,
+    LabelPosition,
+    BoundingBoxStyle,
+    LabelStyle,
+    OverlayStyle,
+    VideoOutputConfig,
+    VisualiserConfig
+)
+from .annotator import FrameAnnotator
+from .writer import (
+    VideoWriterHandle,
+    OutputNameFunction,
+    extract_output_stem,
+    sanitise_filename
+)
+from .loader import (
+    DetectionSource,
+    FrameDetections,
+    CSVDetectionLoader,
+    IteratorDetectionSource,
+    ListDetectionSource,
+    load_detections_from_csv,
+)
+from .visualiser import (
+    AnnotatedFrame,
+    VisualisationResult,
+    LiveVisualiser,
+    PostHocVisualiser
+)
+
+__all__ = [
+    # Config
+    "OutputMode",
+    "LabelPosition", 
+    "BoundingBoxStyle",
+    "LabelStyle",
+    "OverlayStyle",
+    "VideoOutputConfig",
+    "VisualiserConfig",
+    # Writer utilities
+    "VideoWriterHandle",
+    "OutputNameFunction",
+    "extract_output_stem",
+    "sanitise_filename",
+    # Annotator
+    "FrameAnnotator",
+    # Loaders
+    "DetectionSource",
+    "FrameDetections",
+    "CSVDetectionLoader",
+    "IteratorDetectionSource",
+    "ListDetectionSource",
+    "load_detections_from_csv",
+    # Visualisers
+    "AnnotatedFrame",
+    "VisualisationResult",
+    "LiveVisualiser",
+    "PostHocVisualiser",
+]