seavision-python 0.1.1__py3-none-any.whl

seavision/__init__.py

@@ -0,0 +1,3 @@
+"""SeaVision - Human-in-the-loop Computer Vision for Marine Environments."""
+
+__version__ = "0.1.1"

seavision/defaults.py

@@ -0,0 +1,38 @@
+"""Helpers for packaged default configuration files."""
+
+from importlib.resources import files
+from pathlib import Path
+
+_DEFAULT_PIPELINE_CONFIG = files("seavision").joinpath("resources/default.yaml")
+
+def default_pipeline_config_text() -> str:
+    """Return the packaged default pipeline configuration as text."""
+    return _DEFAULT_PIPELINE_CONFIG.read_text(encoding="utf-8")
+
+def write_default_pipeline_config(
+    destination: str | Path,
+    overwrite: bool = False,
+) -> Path:
+    """
+    Write the packaged default pipeline configuration to a user-selected path.
+
+    Args:
+        destination: Output path for the YAML file.
+        overwrite: If True, replace an existing file.
+
+    Returns:
+        The resolved output path.
+
+    Raises:
+        FileExistsError: If the file already exists and overwrite is False.
+    """
+    output_path = Path(destination)
+
+    if output_path.exists() and not overwrite:
+        raise FileExistsError(
+            f"Refusing to overwrite existing file: {output_path}"
+        )
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(default_pipeline_config_text(), encoding="utf-8")
+    return output_path.resolve()

seavision/edge/__init__.py

@@ -0,0 +1,38 @@
+"""
+SeaVision edge inference runtime.
+
+Lightweight inference package for edge devices (Raspberry Pi, Jetson,
+etc.). Runs ONNX models with minimal dependencies — no PyTorch, no
+Ultralytics.
+
+Public API:
+- EdgeConfig: Runtime configuration (always importable).
+- EdgeRuntime: Main inference loop (requires onnxruntime at access time).
+- FrameCapture: Video/camera input (requires opencv).
+- EdgeDetectionWriter: CSV output (no special dependencies).
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from .config import EdgeConfig
+
+if TYPE_CHECKING:
+    # Only imported during type checking, not at runtime.
+    # Keeps onnxruntime optional on the land-side tooling.
+    from .runtime import EdgeRuntime
+
+# EdgeRuntime is imported lazily because it depends on onnxruntime,
+# which is only installed on the edge device. This allows the land-side
+# export tooling to import seavision.edge (for EdgeConfig and
+# artifact builders) without requiring onnxruntime.
+
+
+def __getattr__(name: str):
+    if name == "EdgeRuntime":
+        from .runtime import EdgeRuntime
+        return EdgeRuntime
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = ["EdgeConfig", "EdgeRuntime"]

seavision/edge/bundle.py

@@ -0,0 +1,189 @@
+"""Artifact builder for wheel-first edge deployment.
+
+Creates an artifact directory containing the exported model, runtime config,
+export metadata, and a manifest with compatibility and integrity information.
+The SeaVision wheel is installed separately on the edge device.
+"""
+
+import hashlib
+import json
+import logging
+import shutil
+from pathlib import Path
+from typing import Optional
+
+from seavision import __version__
+
+from .config import (
+    ARTIFACT_MANIFEST_FILENAME,
+    ArtifactFile,
+    ArtifactManifest,
+    EdgeConfig,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ArtifactBuilder:
+    """
+    Package an exported model into a deployable edge artifact directory.
+
+    The resulting directory is copied to the edge device separately from the
+    SeaVision wheel. The runtime then loads the artifact via
+    ``seavision-edge --artifact-dir <path>``.
+    """
+
+    def __init__(
+        self,
+        exported_model_path: str,
+        export_metadata_path: str,
+        output_dir: str = "./artifact",
+        edge_config: Optional[EdgeConfig] = None,
+    ):
+        """
+        Initialise the builder.
+
+        Args:
+            exported_model_path: Path to the exported model file (e.g.
+                model.onnx).
+            export_metadata_path: Path to the export_metadata.json file
+                written by ModelExporter.
+            output_dir: Directory to create the artifact in.
+            edge_config: Optional pre-configured EdgeConfig. If None,
+                defaults are populated from the export metadata.
+        """
+        self.exported_model_path = Path(exported_model_path)
+        self.export_metadata_path = Path(export_metadata_path)
+        self.output_dir = Path(output_dir)
+        self.edge_config = edge_config
+
+    def build(self) -> str:
+        """
+        Build the deployment artifact.
+
+        Returns:
+            Path to the artifact directory.
+
+        Raises:
+            FileNotFoundError: If the model or metadata file is missing.
+        """
+        if not self.exported_model_path.exists():
+            raise FileNotFoundError(
+                f"Exported model not found: {self.exported_model_path}"
+            )
+        if not self.export_metadata_path.exists():
+            raise FileNotFoundError(
+                f"Export metadata not found: {self.export_metadata_path}"
+            )
+
+        # Load export metadata
+        with open(self.export_metadata_path, "r", encoding="utf-8") as f:
+            metadata = json.load(f)
+
+        artifact_dir = self.output_dir
+        artifact_dir.mkdir(parents=True, exist_ok=True)
+
+        # --- 1. Copy model ---
+        model_dest = artifact_dir / self.exported_model_path.name
+        if self.exported_model_path.is_dir():
+            if model_dest.exists():
+                shutil.rmtree(model_dest)
+            shutil.copytree(self.exported_model_path, model_dest)
+        else:
+            shutil.copy2(self.exported_model_path, model_dest)
+        logger.info("Copied model to artifact: %s", model_dest.name)
+
+        # --- 2. Copy metadata ---
+        shutil.copy2(
+            self.export_metadata_path, artifact_dir / "export_metadata.json"
+        )
+
+        # --- 3. Build and write EdgeConfig ---
+        config = self._build_edge_config(metadata, model_dest.name)
+        config_path = artifact_dir / "config.json"
+        config.to_file(str(config_path))
+
+        # --- 4. Write artifact manifest ---
+        manifest = self._build_manifest(
+            artifact_version=__version__,
+            model_path=model_dest,
+            config_path=config_path,
+            metadata_path=artifact_dir / "export_metadata.json",
+        )
+        manifest.to_file(artifact_dir / ARTIFACT_MANIFEST_FILENAME)
+
+        logger.info("Artifact created: %s", artifact_dir)
+        return str(artifact_dir)
+
+    def _build_edge_config(
+        self,
+        metadata: dict,
+        model_filename: str,
+    ) -> EdgeConfig:
+        """
+        Build an EdgeConfig from export metadata, overriding with any
+        user-provided config values.
+        """
+        # Start from user config or defaults
+        config = self.edge_config or EdgeConfig()
+
+        # Override with export metadata (these must match the export)
+        config.model_path = model_filename
+        config.imgsz = metadata.get("imgsz", config.imgsz)
+        config.num_classes = metadata.get("num_classes", config.num_classes)
+
+        class_names_raw = metadata.get("class_names", {})
+        config.class_names = {int(k): v for k, v in class_names_raw.items()}
+
+        return config
+    
+    def _build_manifest(
+        self,
+        artifact_version: str,
+        model_path: Path,
+        config_path: Path,
+        metadata_path: Path,
+    ) -> ArtifactManifest:
+        """Build the artifact manifest for runtime loading and validation."""
+        return ArtifactManifest(
+            artifact_version=artifact_version,
+            runtime_version_range=self._default_runtime_version_range(),
+            model=ArtifactFile(
+                path=model_path.name,
+                sha256=self._sha256_for_path(model_path),
+            ),
+            runtime_config=ArtifactFile(
+                path=config_path.name,
+                sha256=self._sha256_for_path(config_path),
+            ),
+            export_metadata=ArtifactFile(
+                path=metadata_path.name,
+                sha256=self._sha256_for_path(metadata_path),
+            ),
+        )
+
+    @staticmethod
+    def _default_runtime_version_range() -> str:
+        import re
+
+        match = re.match(r"^(\d+)\.(\d+)\.(\d+)", __version__)
+        if not match:
+            raise ValueError(f"Unsupported SeaVision version format: {__version__}")
+
+        major = int(match.group(1))
+        minor = int(match.group(2))
+        return f">={__version__},<{major}.{minor + 1}.0"
+
+    @staticmethod
+    def _sha256_for_path(path: Path) -> str:
+        if path.is_dir():
+            return ""
+
+        digest = hashlib.sha256()
+        with open(path, "rb") as file_obj:
+            for chunk in iter(lambda: file_obj.read(8192), b""):
+                digest.update(chunk)
+        return digest.hexdigest()
+
+
+BundleBuilder = ArtifactBuilder

seavision/edge/capture.py

@@ -0,0 +1,107 @@
+"""
+Frame capture for the edge runtime.
+
+Provides a simple iterator over frames from a camera device or video
+file. This is the edge equivalent of SeaVision's VideoSource, stripped
+to the minimum needed for continuous inference.
+
+Dependencies: opencv-python-headless only.
+"""
+
+import logging
+from typing import Iterator, Optional, Tuple
+
+import cv2
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+class CaptureError(Exception):
+    """Raised when the video source cannot be opened."""
+    pass
+
+
+class FrameCapture:
+    """
+    Reads frames from a camera or video file via OpenCV.
+
+    Attributes:
+        source: The source string or device index passed at construction.
+        fps: Frames per second of the source (0 if unknown/camera).
+        width: Frame width in pixels.
+        height: Frame height in pixels.
+    """
+
+    def __init__(self, source: str):
+        """
+        Open a video source.
+
+        Args:
+            source: Either a string path to a video file, an RTSP URL, or a
+                string-encoded integer for a cmaera device index 
+                (e.g. "0" for /dev/video0).
+        
+        Raises:
+            CaptureError: If the source cannot be opened.
+        """
+        self.source = source
+
+        # Try to interpret as camera index
+        try:
+            device_index = int(source)
+            self._cap = cv2.VideoCapture(device_index)
+        except ValueError:
+            # If it is a filepath or URL.
+            self._cap = cv2.VideoCapture(source)
+        
+        if not self._cap.isOpened():
+            raise CaptureError(f"Could not open video source: {source}")
+        
+        self.fps = self._cap.get(cv2.CAP_PROP_FPS) or 0.0
+        self.width = int(self._cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        self.height = int(self._cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+
+        logger.info(
+            "Opened source: %s (%dx%d @ %.1f fps)",
+            source, self.width, self.height, self.fps,
+        )
+
+    def iter_frames(
+        self,
+        frame_skip: int = 1,
+    ) -> Iterator[Tuple[np.ndarray, int]]:
+        """
+        Yield (frame, frame_number) tuples.
+
+        Args:
+            frame_skip: Process every Nth frame (1 = every frame)
+        
+        Yields:
+            Tuple of (BGR numpy array, frame number).
+        """
+        frame_number = 0
+
+        while True:
+            ret, frame = self._cap.read()
+            if not ret:
+                logger.info("End of source reached at frame %d", frame_number)
+                break
+
+            if frame_number % frame_skip == 0:
+                yield frame, frame_number
+
+            frame_number += 1
+
+    def release(self) -> None:
+        """Release the underlying VideoCapture."""
+        if self._cap is not None:
+            self._cap.release()
+            logger.info("Capture released: %s", self.source)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.release()
+        return False

seavision/edge/config.py

@@ -0,0 +1,219 @@
+"""
+Configuration for the SeaVision edge inference runtime.
+
+This module has no dependencies on PyTorch or Ultralytics. It must be importable
+in the minimal edge enviroment: Python + numpy + OpenCV + PNNX Runtime.
+"""
+
+import dataclasses
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict
+
+logger = logging.getLogger(__name__)
+
+ARTIFACT_MANIFEST_FILENAME = "manifest.json"
+
+
+@dataclass
+class ArtifactFile:
+    """File entry recorded in an edge artifact manifest."""
+
+    path: str
+    sha256: str = ""
+
+
+@dataclass
+class ArtifactManifest:
+    """Manifest describing a wheel-first edge artifact directory."""
+
+    schema_version: int = 1
+    artifact_version: str = "0.1.0"
+    runtime_version_range: str = ">=0.1.0,<0.2.0"
+    model: ArtifactFile = field(default_factory=lambda: ArtifactFile("model.onnx"))
+    runtime_config: ArtifactFile = field(
+        default_factory=lambda: ArtifactFile("config.json")
+    )
+    export_metadata: ArtifactFile = field(
+        default_factory=lambda: ArtifactFile("export_metadata.json")
+    )
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> "ArtifactManifest":
+        """Load an artifact manifest from disk."""
+        manifest_path = Path(path)
+        if not manifest_path.exists():
+            raise FileNotFoundError(f"Artifact manifest not found: {manifest_path}")
+
+        with open(manifest_path, "r", encoding="utf-8") as file_obj:
+            data = json.load(file_obj)
+
+        return cls(
+            schema_version=data.get("schema_version", 1),
+            artifact_version=data.get("artifact_version", "0.1.0"),
+            runtime_version_range=data.get(
+                "runtime_version_range", ">=0.1.0,<0.2.0"
+            ),
+            model=ArtifactFile(**data.get("model", {"path": "model.onnx"})),
+            runtime_config=ArtifactFile(
+                **data.get("runtime_config", {"path": "config.json"})
+            ),
+            export_metadata=ArtifactFile(
+                **data.get(
+                    "export_metadata", {"path": "export_metadata.json"}
+                )
+            ),
+        )
+
+    def to_file(self, path: str | Path) -> None:
+        """Write the manifest to disk."""
+        with open(path, "w", encoding="utf-8") as file_obj:
+            json.dump(dataclasses.asdict(self), file_obj, indent=2)
+
+
+@dataclass
+class EdgeConfig:
+    """
+    COnfiguration for the edge inference runtime.
+
+    This dataclass is the single source of truth for all runtime parameters. It
+    can be loaded from a JSON config file (generated by the bundle builder) or
+    constructed programmatically.
+
+    Attributes:
+        model_path: Path to the exported model file (e.g. model.onnx).
+        source: Video source — either a string-encoded integer for a
+            camera device index (e.g. "0" for /dev/video0) or a string
+            path to a video file or RTSP URL. Default "0" = default
+            camera.
+        output_dir: Directory for detection CSVs and validation clips.
+            Created if it does not exist.
+        imgsz: Input image size. Must match the export imgsz exactly.
+            Using a different size will produce incorrect or degraded
+            detections. The bundle builder sets this automatically from
+            the export metadata.
+        conf_threshold: Minimum confidence score for detections. Higher
+            values reduce false positives but may miss real detections.
+        iou_threshold: IoU threshold for non-maximum suppression.
+        num_classes: Number of detection classes in the model. Set
+            automatically from export metadata.
+        class_names: Mapping of class index to human-readable name.
+            Set automatically from export metadata.
+        validation_clip_interval_s: Seconds between validation clips.
+            Set to 0 to disable validation clip recording. Default is
+            3600 (one clip per hour).
+        validation_clip_duration_s: Duration of each validation clip in
+            seconds. Default 30.
+        frame_skip: Process every Nth frame. Set to 1 to process every
+            frame (default). Higher values reduce CPU load at the cost
+            of potentially missing fast-moving objects. For continuous
+            monitoring at 25fps, frame_skip=5 (effective 5fps) is often
+            a good trade-off on Pi 4.
+        ort_threads: Number of ONNX Runtime intra-op threads. Default 0
+            means "use all available CPU cores", which matches the
+            behaviour in the m3b_pi_benchmark.
+        ort_optimization: ONNX Runtime graph optimization level.
+            Default "all" enables all optimisations (equivalent to
+            ORT_ENABLE_ALL). Use "basic" if you encounter issues.
+        csv_flush_interval: Write buffered detections to disk every N
+            frames. Lower values are safer (less data loss on crash) but
+            cause more disk I/O. Default 100.
+        log_level: Python logging level string. Default "INFO".
+    """
+
+    model_path: str = "model.onnx"
+    artifact_dir: str = ""
+    source: str = "0"
+    output_dir: str = "./detections"
+
+    imgsz: int = 640
+    conf_threshold: float = 0.25
+    iou_threshold: float = 0.45
+    num_classes: int = 80
+    class_names: Dict[int, str] = field(default_factory=dict)
+
+    validation_clip_interval_s: int = 3600
+    validation_clip_duration_s: int = 30
+    frame_skip: int = 1
+
+    ort_threads: int = 0
+    ort_optimization: str = "all"
+
+    csv_flush_interval: int = 100
+    log_level: str = "INFO"
+    runtime_version_range: str = ""
+
+    @classmethod
+    def from_file(cls, path: str) -> "EdgeConfig":
+        """
+        Load config from a JSON file.
+        
+        The bundle builder generates this file automatically. Users can edit it
+        to tune runtime parameters without modifying code.
+
+        Args:
+            path: Path to the JSON configuration file.
+
+        Returns:
+            An EdgeConfig instance populated with the values from the file.
+
+        Raises:
+            FileNotFoundError: If the config file does not exist.
+            json.JSONDecodeError: If the file is not valid JSON.
+        """
+        config_path = Path(path)
+        if not config_path.exists():
+            raise FileNotFoundError(f"Config file not found: {path}")
+
+        with open(config_path, "r") as f:
+            data = json.load(f)
+
+        # Convert class_names keys from string (JSON limitation) to int
+        if "class_names" in data and isinstance(data["class_names"], dict):
+            data["class_names"] = {
+                int(k): v for k, v in data["class_names"].items()
+            }
+
+        return cls(**{
+            k: v for k, v in data.items()
+            if k in cls.__dataclass_fields__
+        })
+
+    @classmethod
+    def from_artifact_dir(cls, path: str | Path) -> "EdgeConfig":
+        """Load runtime config from a wheel-first artifact directory."""
+        artifact_dir = Path(path)
+        manifest = ArtifactManifest.from_file(
+            artifact_dir / ARTIFACT_MANIFEST_FILENAME
+        )
+
+        config = cls.from_file(artifact_dir / manifest.runtime_config.path)
+
+        config.artifact_dir = str(artifact_dir)
+        model_path = artifact_dir / manifest.model.path
+        config.model_path = str(model_path)
+        config.runtime_version_range = manifest.runtime_version_range
+        return config
+    
+    def to_file(self, path: str) -> None:
+        """
+        Save configuration to a JSON file.
+
+        Args:
+            path: Path to write the configuration file.
+        """
+
+        data = dataclasses.asdict(self)
+
+        # Convert class_names keys to strings for JSON compatibility
+        if "class_names" in data:
+            data["class_names"] = {
+                str(k): v for k, v in data["class_names"].items()
+            }
+
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+        logger.info("Edge config saved to %s", path)