seavision 1.0.0__py3-none-any.whl

seavision/__init__.py

@@ -0,0 +1,38 @@
+"""SeaVision.
+
+Computer vision tools for R&D at SEA.AI.
+"""
+
+from . import calibration, geometry, inference, io
+from . import sensorfusion as sf
+from . import transforms as T
+from .calibration import *  # noqa: F403
+from .geometry import *  # noqa: F403
+from .inference import *  # noqa: F403
+from .io import *  # noqa: F403
+from .utils.general import pil_side_by_side, pil_up_down
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+except ImportError:
+    from importlib_metadata import PackageNotFoundError, version  # python 3.6 and 3.7
+
+try:
+    __version__ = version("seavision")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "geometry",
+    "inference",
+    "io",
+    "calibration",
+    "sf",
+    "T",
+    "pil_side_by_side",
+    "pil_up_down",
+]
+__all__.extend(inference.__all__)
+__all__.extend(io.__all__)
+__all__.extend(geometry.__all__)
+__all__.extend(calibration.__all__)

seavision/calibration/README.md

@@ -0,0 +1,41 @@
+# Online Calibration
+
+A local web tool for manually calibrating Sentry camera homography by adjusting pitch, yaw, and roll angles and visually inspecting the overlay against the RGB reference frame.
+
+## Usage
+
+```bash
+uv run -m seavision.calibration
+uv run -m seavision.calibration --recording /path/to/Sentry_recordings_2024_03_12_10_34_06
+uv run -m seavision.calibration --port 8323 --dry-run
+```
+
+Then open http://localhost:8323 in a browser.
+
+## Arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `--recording` | — | Path to a Sentry recording directory. Optional — can also be set via the UI. |
+| `--port` | `8323` | Port to listen on. |
+| `--host` | `0.0.0.0` | Host / IP to bind (`0.0.0.0` = all interfaces). |
+| `--dry-run` | `false` | Print calibration changes to terminal instead of writing to `sentry_sensors.json`. |
+
+## UI
+
+- **Recording** — paste a path or use the text input to load a recording directory
+- **Angles** — adjust pitch, yaw, roll for the selected camera; the overlay updates live
+- **Blend** — control the mix weight between the source and reference frame
+- **JSON tab** — toggle between the image overlay and a live view of `sentry_sensors.json`; changed values are highlighted in red
+- **Save** — writes updated values to `sentry_sensors.json`; the original is preserved as `original_sentry_sensors.json`
+
+## Structure
+
+```
+seavision/calibration/
+  __main__.py    Entry point
+  server.py      FastAPI server and API endpoints
+  utils.py       Recording loading, frame extraction, homography processing
+  static/
+    index.html   Single-page UI
+```

seavision/calibration/__init__.py

@@ -0,0 +1,7 @@
+"""Sentry homography calibration web tool."""
+
+from .parsers import CalibrationData
+
+__all__ = [
+    "CalibrationData",
+]

seavision/calibration/__main__.py

@@ -0,0 +1,45 @@
+"""Entry point for the Sentry homography calibration web server.
+
+Usage:
+    uv run -m seavision.calibration
+    uv run -m seavision.calibration --recording /path/to/Sentry_2024_03_12_10_34_06
+    uv run -m seavision.calibration --port 8323 --host 127.0.0.1 --dry-run
+"""
+
+import argparse
+
+from seavision.calibration.server import run_web_server
+
+parser = argparse.ArgumentParser(description="Sentry homography calibration server")
+parser.add_argument(
+    "--recording",
+    default=None,
+    help="Path to a Sentry recording directory (optional — can be set in the UI)",
+)
+parser.add_argument(
+    "--port", type=int, default=8323, help="Port to listen on (default: 8323)"
+)
+parser.add_argument(
+    "--host",
+    default="0.0.0.0",
+    help="Host / IP to bind (default: 0.0.0.0 — all interfaces)",
+)
+parser.add_argument(
+    "--reference-camera",
+    default=None,
+    help="Master view to project sources into (default: t_w)",
+)
+parser.add_argument(
+    "--dry-run",
+    action="store_true",
+    help="Print changes instead of writing to sentry_sensors.json",
+)
+args = parser.parse_args()
+
+run_web_server(
+    args.recording,
+    args.port,
+    host=args.host,
+    dry_run=args.dry_run,
+    reference_camera=args.reference_camera,
+)

seavision/calibration/parsers.py

@@ -0,0 +1,58 @@
+"""Parsers for sensor calibration data."""
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Union
+
+from seavision.geometry.pinhole import Camera
+
+
+@dataclass(frozen=True)
+class CalibrationData:
+    """Calibration bundle loaded from JSON (Oscar / Sentry or legacy intrinsics)."""
+
+    cameras: dict[str, Camera]
+
+    @staticmethod
+    def _build_camera(camera_data: Dict[str, Any]) -> Camera:
+        """Build a Camera from one JSON camera block."""
+        if "focal_length_x" in camera_data:
+            width, height = camera_data["resolution"]["value"]
+            fx = camera_data["focal_length_x"]["value"]
+            fy = camera_data["focal_length_y"]["value"]
+            cx = camera_data["center_x"]["value"]
+            cy = camera_data["center_y"]["value"]
+        else:
+            height, width = camera_data["resolution"]["value"]
+            f_mm = camera_data["focal_length"]["value"]
+            pixel_mm = camera_data["pixel_size"]["value"]
+            if pixel_mm == 0:
+                raise ValueError(
+                    "pixel_size must be non-zero to derive focal length in pixels"
+                )
+            fx = fy = f_mm / pixel_mm
+            cx = width / 2.0
+            cy = height / 2.0
+        return Camera(
+            width=int(width),
+            height=int(height),
+            fx=float(fx),
+            fy=float(fy),
+            cx=float(cx),
+            cy=float(cy),
+            roll=float(camera_data["roll"]["value"]),
+            pitch=float(camera_data["pitch"]["value"]),
+            yaw=float(camera_data["yaw"]["value"]),
+        )
+
+    @classmethod
+    def from_json(cls, file_path: Union[str, Path]) -> "CalibrationData":
+        """Parse calibration data from a JSON file."""
+        with Path(file_path).open("r", encoding="utf-8") as f:
+            data = json.load(f)
+        cameras = {
+            camera_id: cls._build_camera(camera_data)
+            for camera_id, camera_data in data.get("cameras", {}).items()
+        }
+        return cls(cameras=cameras)

seavision/calibration/server.py

@@ -0,0 +1,265 @@
+"""FastAPI server for the Sentry homography calibration tool."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import numpy as np
+import uvicorn
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+
+from seavision.calibration import CalibrationData
+from seavision.calibration.utils import (
+    CAMERA_PATTERNS,
+    DEFAULT_REFERENCE_CAMERA,
+    image_to_base64,
+    load_first_frames,
+    load_sentry_config,
+    process_calibration,
+    read_sensors_json,
+    source_cameras_for_reference,
+    update_sensors_json,
+)
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+app = FastAPI(title="Seavision")
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+
+@dataclass
+class _ServerState:
+    """Mutable server state shared across request handlers."""
+
+    sentry: Optional[CalibrationData] = None
+    frames: Dict[str, np.ndarray] = field(default_factory=dict)
+    recording_path: Optional[str] = None
+    reference_camera: str = DEFAULT_REFERENCE_CAMERA
+    current_camera: Optional[str] = None
+    camera_ui_values: Dict[str, Dict[str, float]] = field(default_factory=dict)
+    dry_run: bool = False
+    recordings_root: Optional[Path] = None
+
+
+_state = _ServerState()
+
+
+def resolve_recording_path(path: str) -> Path:
+    """Resolve and validate a recording path against the configured root."""
+    resolved = Path(path).expanduser().resolve()
+    if _state.recordings_root is not None:
+        try:
+            resolved.relative_to(_state.recordings_root)
+        except ValueError as e:
+            raise ValueError("Access outside recordings root is not allowed") from e
+    return resolved
+
+
+def _apply_recording(path: str) -> None:
+    """Load recording data into server state (atomic: commits only on full success)."""
+    resolved = resolve_recording_path(path)
+    sentry = load_sentry_config(str(resolved), reference_camera=_state.reference_camera)
+    frames = load_first_frames(str(resolved))
+    _state.sentry = sentry
+    _state.frames = frames
+    _state.recording_path = str(resolved)
+    _state.current_camera = None
+    _state.camera_ui_values = {}
+
+
+@app.get("/", response_class=HTMLResponse)
+def index() -> str:
+    """Serve the calibration UI."""
+    return (STATIC_DIR / "index.html").read_text()
+
+
+@app.get("/api/camera_sources")
+def camera_sources() -> Dict[str, Any]:
+    """List source cameras for the current reference (fixed at server start)."""
+    return {"cameras": source_cameras_for_reference(_state.reference_camera)}
+
+
+@app.get("/api/select_camera_source")
+def select_camera_source(camera: str = Query(...)) -> Dict[str, Any]:
+    """Select the active camera and return its current UI values."""
+    allowed = source_cameras_for_reference(_state.reference_camera)
+    if camera not in allowed:
+        raise HTTPException(400, f"Invalid camera: {camera}; allowed: {allowed}")
+    _state.current_camera = camera
+    if camera not in _state.camera_ui_values:
+        _state.camera_ui_values[camera] = (
+            _state.sentry.cameras[camera].extrinsics()
+            if _state.sentry is not None and camera in _state.sentry.cameras
+            else {"pitch": 0.0, "yaw": 0.0, "roll": 0.0}
+        )
+    return {"camera": camera, "values": _state.camera_ui_values[camera]}
+
+
+@app.get("/api/process")
+def process(
+    pitch: float = Query(0.0),
+    yaw: float = Query(0.0),
+    roll: float = Query(0.0),
+    weight: float = Query(0.5),
+) -> Dict[str, Any]:
+    """Run calibration and return base64-encoded result images."""
+    if _state.sentry is None or not _state.frames:
+        raise HTTPException(400, "No recording loaded")
+    if _state.current_camera is None:
+        raise HTTPException(400, "No camera source selected")
+    _state.camera_ui_values[_state.current_camera] = {
+        "pitch": pitch,
+        "yaw": yaw,
+        "roll": roll,
+    }
+    result = process_calibration(
+        _state.sentry,
+        _state.frames,
+        _state.current_camera,
+        pitch,
+        yaw,
+        roll,
+        weight,
+        reference_camera=_state.reference_camera,
+    )
+    return {"mixed": image_to_base64(result["mixed"])}
+
+
+@app.get("/api/reset_camera")
+def reset_camera(camera: str = Query(...)) -> Dict[str, Any]:
+    """Reset a camera's UI values to the original values from the recording."""
+    allowed = source_cameras_for_reference(_state.reference_camera)
+    if camera not in allowed:
+        raise HTTPException(400, f"Invalid camera: {camera}; allowed: {allowed}")
+    if _state.sentry is None:
+        raise HTTPException(400, "No recording loaded")
+    if camera not in _state.sentry.cameras:
+        raise HTTPException(400, f"Camera not found: {camera}")
+    _state.camera_ui_values[camera] = _state.sentry.cameras[camera].extrinsics()
+    return {"camera": camera, "values": _state.camera_ui_values[camera]}
+
+
+@app.get("/api/load_recording")
+def load_recording(path: str = Query(...)) -> Dict[str, Any]:
+    """Load a recording directory into server state."""
+    try:
+        _apply_recording(path)
+    except Exception as e:
+        raise HTTPException(400, str(e)) from e
+    return {"status": "loaded", "path": path}
+
+
+@app.get("/api/browse_root")
+def browse_root() -> Dict[str, Any]:
+    """Return the initial directory for the file browser."""
+    root = _state.recordings_root or Path("~").expanduser().resolve()
+    return {"path": str(root)}
+
+
+@app.get("/api/browse")
+def browse(path: str = Query(...)) -> Dict[str, Any]:
+    """List subdirectories of path, flagging valid recordings."""
+    base = Path(path).expanduser().resolve()
+    if not base.is_dir():
+        raise HTTPException(400, f"Not a directory: {path}")
+    if _state.recordings_root is not None:
+        try:
+            base.relative_to(_state.recordings_root)
+        except ValueError as e:
+            raise HTTPException(
+                403, "Access outside recordings root is not allowed"
+            ) from e
+    entries = sorted(
+        (
+            {
+                "name": e.name,
+                "is_recording": (e / "POWER_Const" / "sentry_sensors.json").exists(),
+            }
+            for e in base.iterdir()
+            if e.is_dir()
+        ),
+        key=lambda e: (not e["is_recording"], e["name"]),
+    )
+    root = _state.recordings_root or base.anchor
+    return {
+        "path": str(base),
+        "parent": str(base.parent),
+        "root": str(root),
+        "entries": entries,
+    }
+
+
+@app.get("/api/sensors_json")
+def get_sensors_json() -> Dict[str, Any]:
+    """Return the current on-disk sentry_sensors.json and pending UI values."""
+    if _state.recording_path is None:
+        raise HTTPException(400, "No recording loaded")
+    return {
+        "data": read_sensors_json(_state.recording_path),
+        "pending": _state.camera_ui_values,
+    }
+
+
+@app.get("/api/save_sensors_json")
+def save_sensors_json() -> Dict[str, str]:
+    """Write pending UI values to sentry_sensors.json."""
+    if _state.recording_path is None:
+        raise HTTPException(400, "No recording loaded")
+    if _state.dry_run:
+        for camera, values in _state.camera_ui_values.items():
+            print(
+                f"[dry-run] {camera}: "
+                f"pitch={values['pitch']:.4f}  "
+                f"yaw={values['yaw']:.4f}  "
+                f"roll={values['roll']:.4f}"
+            )
+    else:
+        update_sensors_json(_state.recording_path, _state.camera_ui_values)
+    return {"status": "dry-run (see terminal)" if _state.dry_run else "saved"}
+
+
+def configure_server(
+    recording_path: Optional[str] = None,
+    dry_run: bool = False,
+    reference_camera: Optional[str] = None,
+    recordings_root: Optional[str] = None,
+) -> None:
+    """Apply startup configuration to server state. Raises SystemExit for bad inputs."""
+    _state.dry_run = dry_run
+    if recordings_root is not None:
+        _state.recordings_root = Path(recordings_root).expanduser().resolve()
+    if reference_camera is not None:
+        if reference_camera not in CAMERA_PATTERNS:
+            raise SystemExit(
+                f"calibration: unknown reference {reference_camera!r}; "
+                f"expected one of: {sorted(CAMERA_PATTERNS)}"
+            )
+        _state.reference_camera = reference_camera
+    if recording_path is not None:
+        _apply_recording(recording_path)
+        print(f"Loaded recording: {recording_path}")
+    print(f"Reference (master) camera: {_state.reference_camera}")
+
+
+def run_web_server(
+    recording_path: Optional[str] = None,
+    port: int = 8323,
+    host: str = "0.0.0.0",
+    dry_run: bool = False,
+    reference_camera: Optional[str] = None,
+    recordings_root: Optional[str] = None,
+) -> None:
+    """Start the calibration web server, optionally with a pre-loaded recording."""
+    configure_server(
+        recording_path=recording_path,
+        dry_run=dry_run,
+        reference_camera=reference_camera,
+        recordings_root=recordings_root,
+    )
+    open_url = (
+        f"http://127.0.0.1:{port}" if host == "0.0.0.0" else f"http://{host}:{port}"
+    )
+    print(f"Calibration server listening on {host}:{port} — open {open_url}")
+    uvicorn.run(app, host=host, port=port, log_level="warning")

seavision/calibration/static/css/base.css

@@ -0,0 +1,161 @@
+/* SEA.AI design tokens — DARK (default) + LIGHT */
+
+:root {
+  /* Neutral surfaces */
+  --surface-neutral-1: #101214;
+  --surface-neutral-2: #181b1e;
+  --surface-neutral-3: #202428;
+  --surface-neutral-4: #292e33;
+  --surface-neutral-5: #31373d;
+
+  /* Semantic surfaces */
+  --surface-primary-3: #0a67c2;
+  --surface-danger-3: #c20a20;
+  --surface-warning-3: #f1b80d;
+  --surface-success-3: #2b9e6e;
+
+  /* Content on neutral backgrounds */
+  --text-1: #e8eaed;
+  --text-2: #8a919a;
+  --text-3: #565e69;
+
+  /* Content on colored surfaces */
+  --content-primary-2: #cfe5fc;
+  --content-danger-1: #fa9ea9;
+  --content-warning-1: #fae39e;
+  --content-success-1: #a7f3d0;
+
+  /* Focus / accent */
+  --accent-primary-2: #0a67c2;
+  --accent-danger-2: #c20a20;
+  --stroke-normal: 1.5px;
+
+  /* JSON syntax (neutral semantics: structure vs data) */
+  --json-string: #8ecf8a;
+  --json-number: #c5a9f5;
+
+  /* Shape */
+  --radius-s: 4px;
+  --radius-m: 8px;
+  --radius-l: 16px;
+
+  /* Spacing */
+  --space-component-xs: 4px;
+  --space-component-s: 8px;
+  --space-component-m: 12px;
+  --space-component-l: 16px;
+  --space-component-2xl: 24px;
+  --space-component-3xl: 32px;
+
+  /* Legacy aliases (components, inline) */
+  --surface-1: var(--surface-neutral-1);
+  --surface-2: var(--surface-neutral-2);
+  --surface-3: var(--surface-neutral-3);
+  --surface-4: var(--surface-neutral-4);
+  --surface-5: var(--surface-neutral-5);
+  --primary: var(--surface-primary-3);
+  --primary-hover: #0856a3;
+  --danger: var(--surface-danger-3);
+  --warning: var(--surface-warning-3);
+  --success: var(--surface-success-3);
+  --content-primary: var(--content-primary-2);
+  --content-danger: var(--content-danger-1);
+  --content-warning: var(--content-warning-1);
+  --content-success: var(--content-success-1);
+  --space-xs: var(--space-component-xs);
+  --space-s: var(--space-component-s);
+  --space-m: var(--space-component-m);
+  --space-l: var(--space-component-l);
+  --space-2xl: var(--space-component-2xl);
+  --space-3xl: var(--space-component-3xl);
+  --button-height: 48px;
+  --input-height: 40px;
+  --theme-button-height: 30px;
+}
+
+[data-theme="light"] {
+  --surface-neutral-1: #b9bdc1;
+  --surface-neutral-2: #cbced1;
+  --surface-neutral-3: #dcdee0;
+  --surface-neutral-4: #eeeff0;
+  --surface-neutral-5: #ffffff;
+
+  --surface-primary-3: #0a67c2;
+  --surface-danger-3: #c20a20;
+  --surface-warning-3: #f1b80d;
+  --surface-success-3: #1a7a4f;
+
+  --text-1: #101214;
+  --text-2: #31373d;
+  --text-3: #565e69;
+
+  /* On colored surfaces: same as DARK per design spec */
+  --content-primary-2: #cfe5fc;
+  --content-danger-1: #fa9ea9;
+  --content-warning-1: #fae39e;
+  --content-success-1: #a7f3d0;
+
+  --json-string: #2d7a3a;
+  --json-number: #7b5ab5;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+/* Typography — Saira Condensed; card-* uppercase for chrome */
+body {
+  font-family: "Saira Condensed", "Arial Narrow", Arial, sans-serif;
+  background: var(--surface-neutral-3);
+  color: var(--text-1);
+  min-height: 100vh;
+  -webkit-font-smoothing: antialiased;
+}
+
+.card-label-s {
+  font-weight: 500;
+  font-size: 16px;
+  line-height: 24px;
+  letter-spacing: 0;
+  text-transform: uppercase;
+}
+
+.card-title-s {
+  font-weight: 400;
+  font-size: 20px;
+  line-height: 28px;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+}
+
+.main-body-xs {
+  font-weight: 400;
+  font-size: 12px;
+  line-height: 20px;
+  letter-spacing: 0;
+}
+
+.element-button-m {
+  font-weight: 500;
+  font-size: 16px;
+  line-height: 24px;
+  letter-spacing: 0.015em;
+}
+
+::-webkit-scrollbar {
+  width: 4px;
+}
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+::-webkit-scrollbar-thumb {
+  background: var(--surface-neutral-5);
+  border-radius: 2px;
+}
+::-webkit-scrollbar-thumb:hover {
+  background: var(--text-3);
+}