ray360 0.1.0__py3-none-any.whl

ray360/__init__.py

@@ -0,0 +1,27 @@
+"""Perspective views, cubemaps and prediction mapping for stitched panoramas."""
+
+from .annotations import Box2D, Polygon2D, SphericalRegion
+from .cubemap import cube_projections, from_cubemap, to_cubemap
+from .panorama import Panorama, View
+from .projections import Equirectangular, Perspective, coverage_views
+from .remap import MapCache, ProjectionMap
+from .transforms import ViewTransform
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Box2D",
+    "Equirectangular",
+    "MapCache",
+    "Panorama",
+    "Perspective",
+    "Polygon2D",
+    "ProjectionMap",
+    "SphericalRegion",
+    "View",
+    "ViewTransform",
+    "coverage_views",
+    "cube_projections",
+    "from_cubemap",
+    "to_cubemap",
+]

ray360/annotations.py

@@ -0,0 +1,304 @@
+"""Boxes and their spherical interiors. Polygon output may have seam pieces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from .geometry import normalize, positive_int
+from .projections import (
+    Equirectangular,
+    Perspective,
+    Projection,
+    projection_from_dict,
+    projection_to_dict,
+)
+
+
+@dataclass(frozen=True, kw_only=True)
+class _Metadata:
+    label: str | int | None = None
+    score: float | None = None
+    track_id: str | int | None = None
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.score is not None:
+            if not 0 <= self.score <= 1:
+                raise ValueError("score must be between 0 and 1.")
+            object.__setattr__(self, "score", float(self.score))
+        object.__setattr__(self, "attributes", dict(self.attributes))
+
+    def metadata(self) -> dict[str, Any]:
+        return {
+            "label": self.label,
+            "score": self.score,
+            "track_id": self.track_id,
+            "attributes": dict(self.attributes),
+        }
+
+
+@dataclass(frozen=True)
+class Box2D(_Metadata):
+    """Positive-area pixel-edge coordinates, with optional prediction metadata."""
+
+    x1: float
+    y1: float
+    x2: float
+    y2: float
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if not np.isfinite(self.xyxy).all() or self.x2 <= self.x1 or self.y2 <= self.y1:
+            raise ValueError("Boxes require finite coordinates and positive width and height.")
+        for name in ("x1", "y1", "x2", "y2"):
+            object.__setattr__(self, name, float(getattr(self, name)))
+
+    @property
+    def xyxy(self) -> NDArray:
+        return np.array([self.x1, self.y1, self.x2, self.y2], dtype=np.float64)
+
+    @property
+    def area(self) -> float:
+        return (self.x2 - self.x1) * (self.y2 - self.y1)
+
+    def polygon(self) -> Polygon2D:
+        return Polygon2D(
+            np.array(
+                [[self.x1, self.y1], [self.x2, self.y1], [self.x2, self.y2], [self.x1, self.y2]]
+            ),
+            **self.metadata(),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"xyxy": self.xyxy.tolist(), **self.metadata()}
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> Box2D:
+        return cls(
+            *value["xyxy"],
+            **{k: value[k] for k in ("label", "score", "track_id", "attributes") if k in value},
+        )
+
+
+@dataclass(frozen=True)
+class Polygon2D(_Metadata):
+    """A rendered boundary. Combine rings with even-odd fill; is_hole marks holes."""
+
+    vertices: NDArray
+    is_hole: bool = False
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        vertices = np.array(self.vertices, dtype=np.float64, copy=True)
+        if (
+            vertices.ndim != 2
+            or vertices.shape[1] != 2
+            or len(vertices) < 3
+            or not np.isfinite(vertices).all()
+        ):
+            raise ValueError("A polygon needs at least three finite xy vertices.")
+        vertices.flags.writeable = False
+        object.__setattr__(self, "vertices", vertices)
+
+    def bbox(self) -> Box2D:
+        x1, y1 = self.vertices.min(0)
+        x2, y2 = self.vertices.max(0)
+        return Box2D(x1, y1, x2, y2, **self.metadata())
+
+
+@dataclass(frozen=True)
+class SphericalRegion:
+    """One object defined by a box and its projection, including its intended interior.
+
+    Equirectangular boxes may cross the seam using unwrapped x, such as 350..370
+    in a 360-pixel panorama. Their width cannot exceed one revolution.
+    """
+
+    box: Box2D
+    projection: Projection
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.box, Box2D) or not isinstance(
+            self.projection, (Equirectangular, Perspective)
+        ):
+            raise TypeError(
+                "A region requires a Box2D and an Equirectangular or Perspective projection."
+            )
+        b, p = self.box, self.projection
+        if b.y1 < 0 or b.y2 > p.height:
+            raise ValueError("Box y coordinates must lie within the projection.")
+        if isinstance(p, Equirectangular):
+            if b.x2 - b.x1 > p.width:
+                raise ValueError("A panorama box cannot span more than one revolution.")
+        elif b.x1 < 0 or b.x2 > p.width:
+            raise ValueError("Box x coordinates must lie within the perspective view.")
+
+    def contains(self, rays: ArrayLike) -> NDArray:
+        xy, visible = self.projection.project(normalize(rays))
+        b = self.box
+        x = xy[..., 0]
+        if isinstance(self.projection, Equirectangular):
+            distance = (x - b.x1) % self.projection.width
+            inside_x = (distance <= b.x2 - b.x1 + 1e-8) | (distance >= self.projection.width - 1e-8)
+        else:
+            inside_x = (x >= b.x1 - 1e-8) & (x <= b.x2 + 1e-8)
+        return visible & inside_x & (xy[..., 1] >= b.y1 - 1e-8) & (xy[..., 1] <= b.y2 + 1e-8)
+
+    def boundary(self, samples_per_edge: int = 32) -> NDArray:
+        """Sample all four source edges and return world-space unit rays."""
+        positive_int(samples_per_edge, "samples_per_edge")
+        return self.projection.unproject(_densify(self.box.polygon().vertices, samples_per_edge))[0]
+
+    def rasterize(self, target: Projection) -> NDArray:
+        """Authoritative membership at target pixel centers."""
+        mask = np.empty((target.height, target.width), bool)
+        for start in range(0, target.height, 128):
+            stop = min(start + 128, target.height)
+            rays, valid = target.unproject(target.pixel_grid(start, stop))
+            mask[start:stop] = valid & self.contains(rays)
+        return mask
+
+    def polygons(self, target: Projection, *, samples_per_edge: int = 32) -> list[Polygon2D]:
+        """Render boundaries in the target image.
+
+        Perspective-source edges are sampled approximations. Panorama-source
+        regions use pixel-edge contours, preserving wide interiors and both poles
+        under rotation. Subpixel regions may disappear in that raster fallback.
+        """
+        positive_int(samples_per_edge, "samples_per_edge")
+        if not isinstance(target, (Equirectangular, Perspective)):
+            raise TypeError("Unsupported target projection.")
+        if isinstance(self.projection, Equirectangular):
+            return [
+                replace(p, **self.box.metadata()) for p in _mask_to_polygons(self.rasterize(target))
+            ]
+        rays = self.boundary(samples_per_edge)
+        if isinstance(target, Perspective):
+            local = rays @ target.rotation
+            for normal in (
+                [0, 0, 1],
+                [1, 0, target.width / (2 * target.focal)],
+                [-1, 0, target.width / (2 * target.focal)],
+                [0, 1, target.height / (2 * target.focal)],
+                [0, -1, target.height / (2 * target.focal)],
+            ):
+                local = _clip(local, np.asarray(normal))
+            if len(local) < 3:
+                return []
+            xy, _ = target.project(normalize(local) @ target.rotation.T)
+            return self._polygons([_clip_image(xy, target.width, target.height)])
+        xy, _ = target.project(np.concatenate((rays, rays[:1])))
+        x = np.unwrap(xy[:, 0] / target.width * (2 * np.pi)) / (2 * np.pi) * target.width
+        boundary = np.column_stack((x, xy[:, 1]))
+        if abs(x[-1] - x[0]) > target.width * 0.5:
+            north = self.contains(np.array([0, 1, 0]) @ target.rotation.T)
+            pole_y = 0 if north else target.height
+            boundary = np.concatenate((boundary, [[x[-1], pole_y], [x[0], pole_y]]))
+        lo, hi = int(np.floor(np.min(x) / target.width)), int(np.floor(np.max(x) / target.width))
+        return self._polygons(
+            [
+                _clip_image(boundary - [shift * target.width, 0], target.width, target.height)
+                for shift in range(lo, hi + 1)
+            ]
+        )
+
+    def _polygons(self, pieces: list[NDArray]) -> list[Polygon2D]:
+        return [
+            Polygon2D(xy, **self.box.metadata())
+            for xy in pieces
+            if len(xy) >= 3 and abs(_signed_area(xy)) > 1e-8
+        ]
+
+    def boxes(self, target: Projection) -> list[Box2D]:
+        """Approximate enclosing rectangles for outer components; holes are excluded."""
+        return [p.bbox() for p in self.polygons(target) if not p.is_hole]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schema_version": 1,
+            "box": self.box.to_dict(),
+            "projection": projection_to_dict(self.projection),
+        }
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> SphericalRegion:
+        if value.get("schema_version") != 1:
+            raise ValueError("Unsupported region schema_version.")
+        return cls(Box2D.from_dict(value["box"]), projection_from_dict(value["projection"]))
+
+
+def _signed_area(xy: NDArray) -> float:
+    return float(np.sum(xy[:, 0] * np.roll(xy[:, 1], -1) - xy[:, 1] * np.roll(xy[:, 0], -1)) / 2)
+
+
+def _clip(vertices: NDArray, normal: NDArray, offset: float = 0) -> NDArray:
+    """Sutherland-Hodgman against dot(vertex, normal) + offset >= 0."""
+    if len(vertices) == 0:
+        return vertices
+    output = []
+    a = vertices[-1]
+    da = float(a @ normal + offset)
+    for b in vertices:
+        db = float(b @ normal + offset)
+        if (da >= 0) != (db >= 0):
+            output.append(a + da / (da - db) * (b - a))
+        if db >= 0:
+            output.append(b)
+        a, da = b, db
+    return np.asarray(output).reshape(-1, vertices.shape[-1])
+
+
+def _clip_image(vertices: NDArray, width: float, height: float) -> NDArray:
+    for normal, offset in (([1, 0], 0), ([-1, 0], width), ([0, 1], 0), ([0, -1], height)):
+        vertices = _clip(vertices, np.asarray(normal), offset)
+    return vertices
+
+
+def _densify(vertices: NDArray, samples_per_edge: int) -> NDArray:
+    t = np.arange(samples_per_edge) / samples_per_edge
+    return np.concatenate(
+        [
+            a[None] * (1 - t[:, None]) + b[None] * t[:, None]
+            for a, b in zip(vertices, np.roll(vertices, -1, axis=0), strict=True)
+        ]
+    )
+
+
+def _mask_to_polygons(mask: NDArray) -> list[Polygon2D]:
+    """Trace pixel-edge contours, including hole rings (opposite winding)."""
+    mask = np.asarray(mask, bool)
+    if mask.ndim != 2:
+        raise ValueError("mask must be HW.")
+    padded = np.pad(mask, 1)
+    edges: dict[tuple[int, int], list[tuple[int, int]]] = {}
+    for dy, dx, a, b in (
+        (-1, 0, (0, 0), (1, 0)),
+        (0, 1, (1, 0), (1, 1)),
+        (1, 0, (1, 1), (0, 1)),
+        (0, -1, (0, 1), (0, 0)),
+    ):
+        neighbor = padded[1 + dy : 1 + dy + mask.shape[0], 1 + dx : 1 + dx + mask.shape[1]]
+        ys, xs = np.nonzero(mask & ~neighbor)
+        for x, y in zip(xs.tolist(), ys.tolist(), strict=True):
+            edges.setdefault((x + a[0], y + a[1]), []).append((x + b[0], y + b[1]))
+    polygons = []
+    while edges:
+        first = next(iter(edges))
+        point = first
+        ring = []
+        while True:
+            ring.append(point)
+            following = edges[point].pop()
+            if not edges[point]:
+                del edges[point]
+            point = following
+            if point == first:
+                break
+        if len(ring) >= 3:
+            vertices = np.asarray(ring)
+            polygons.append(Polygon2D(vertices, is_hole=_signed_area(vertices) < 0))
+    return polygons

ray360/cubemap.py

@@ -0,0 +1,149 @@
+"""Six named 90-degree cube faces, with filtering across shared edges."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .geometry import positive_int
+from .panorama import Panorama
+from .projections import Equirectangular, Perspective
+from .remap import DEFAULT_CACHE, Interpolation, MapCache, sample, validate_image
+
+_ORIENTATIONS = {
+    "front": (0, 0),
+    "right": (90, 0),
+    "back": (180, 0),
+    "left": (-90, 0),
+    "up": (0, 90),
+    "down": (0, -90),
+}
+
+
+def cube_projections(size: int) -> dict[str, Perspective]:
+    """World-aligned square faces: front +Z, right +X, back -Z, left -X, up +Y, down -Y.
+
+    All faces have zero roll. The top of the up face points toward -Z;
+    the top of the down face points toward +Z. No atlas layout is assumed.
+    """
+    positive_int(size, "size")
+    return {
+        name: Perspective(size, size, yaw=yaw, pitch=pitch, hfov=90)
+        for name, (yaw, pitch) in _ORIENTATIONS.items()
+    }
+
+
+def to_cubemap(
+    panorama: Panorama,
+    size: int = 512,
+    *,
+    interpolation: Interpolation = "bilinear",
+    cache: MapCache | None = DEFAULT_CACHE,
+) -> dict[str, NDArray]:
+    """Convert a declared panorama into six named, world-aligned arrays.
+
+    To retain prediction transforms, use panorama.view on cube_projections instead.
+    """
+    if not isinstance(panorama, Panorama):
+        raise TypeError("to_cubemap requires a Panorama.")
+    return {
+        name: panorama.view(projection, interpolation=interpolation, cache=cache).image
+        for name, projection in cube_projections(size).items()
+    }
+
+
+def _owners(rays: NDArray) -> NDArray:
+    # Ties prefer X, then Y, then Z. Each ray belongs to exactly one face.
+    axis = np.argmax(np.abs(rays), axis=-1)
+    positive = np.take_along_axis(rays, axis[..., None], axis=-1)[..., 0] >= 0
+    return np.where(positive, np.array([1, 4, 0])[axis], np.array([3, 5, 2])[axis])
+
+
+def _nearest(
+    faces: Mapping[str, NDArray], projections: Mapping[str, Perspective], rays: NDArray
+) -> NDArray:
+    first = faces["front"]
+    output = np.empty((*rays.shape[:-1], *first.shape[2:]), dtype=first.dtype)
+    owners = _owners(rays)
+    for index, (name, projection) in enumerate(projections.items()):
+        chosen = owners == index
+        if chosen.any():
+            xy, _ = projection.project(rays[chosen])
+            output[chosen] = sample(faces[name], xy, interpolation="nearest")
+    return output
+
+
+def _face_sample(
+    faces: Mapping[str, NDArray],
+    projections: Mapping[str, Perspective],
+    name: str,
+    xy: NDArray,
+    interpolation: Interpolation,
+) -> NDArray:
+    face = faces[name]
+    output = sample(face, xy, interpolation=interpolation)
+    if interpolation == "nearest":
+        return output
+    size = face.shape[0]
+    border = ((xy < 0.5) | (xy > size - 0.5)).any(-1)
+    if not border.any():
+        return output
+    # Only the edge samples need cross-face taps. Interior pixels use the common sampler.
+    centers = xy[border] - 0.5
+    lower = np.floor(centers)
+    fraction = centers - lower
+    dtype = np.result_type(face.dtype, np.float32)
+    filtered = np.zeros((len(centers), *face.shape[2:]), dtype=dtype)
+    for dx, dy in ((0, 0), (1, 0), (0, 1), (1, 1)):
+        taps = lower + [dx + 0.5, dy + 0.5]
+        rays, _ = projections[name].unproject(taps)
+        values = _nearest(faces, projections, rays).astype(dtype)
+        weight = (fraction[:, 0] if dx else 1 - fraction[:, 0]) * (
+            fraction[:, 1] if dy else 1 - fraction[:, 1]
+        )
+        if face.ndim == 3:
+            weight = weight[:, None]
+        filtered += values * weight.astype(dtype)
+    if face.dtype.kind in "ui":
+        limits = np.iinfo(face.dtype)
+        filtered = np.clip(np.rint(filtered), limits.min, limits.max)
+    output[border] = filtered.astype(face.dtype)
+    return output
+
+
+def from_cubemap(
+    faces: Mapping[str, NDArray],
+    target: Equirectangular,
+    *,
+    interpolation: Interpolation = "bilinear",
+    chunk_rows: int = 128,
+) -> NDArray:
+    """Convert six matching square faces to a full equirectangular array.
+
+    Bilinear taps crossing a face edge sample the adjacent face. Nearest sampling
+    preserves class IDs. Face orientation follows cube_projections, including poles.
+    """
+    if not isinstance(target, Equirectangular):
+        raise TypeError("from_cubemap requires an Equirectangular target.")
+    positive_int(chunk_rows, "chunk_rows")
+    if set(faces) != set(_ORIENTATIONS):
+        raise ValueError("Expected exactly front, right, back, left, up, and down faces.")
+    arrays = {name: validate_image(array) for name, array in faces.items()}
+    first = arrays["front"]
+    if first.shape[0] != first.shape[1]:
+        raise ValueError("Cubemap faces must be square.")
+    if any(array.shape != first.shape or array.dtype != first.dtype for array in arrays.values()):
+        raise ValueError("Cubemap faces must have matching shapes and dtypes.")
+    projections = cube_projections(first.shape[0])
+    output = np.empty((target.height, target.width, *first.shape[2:]), dtype=first.dtype)
+    for start in range(0, target.height, chunk_rows):
+        stop = min(target.height, start + chunk_rows)
+        rays, _ = target.unproject(target.pixel_grid(start, stop))
+        owners = _owners(rays)
+        for index, (name, projection) in enumerate(projections.items()):
+            chosen = owners == index
+            xy, _ = projection.project(rays[chosen])
+            output[start:stop][chosen] = _face_sample(arrays, projections, name, xy, interpolation)
+    return output

ray360/experimental.py

@@ -0,0 +1,55 @@
+"""Experimental sampled overlap and NMS; excluded from the stable root API.
+
+Small regions can miss all samples. These methods neither fuse partial detections
+nor establish detector accuracy. Increase samples and validate on the target data.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .annotations import SphericalRegion
+from .geometry import fibonacci_sphere
+
+
+def spherical_iou(a: SphericalRegion, b: SphericalRegion, *, samples: int = 65536) -> float:
+    """Approximate solid-angle IoU using equal-area samples, not panorama pixel area.
+
+    Increase samples for small objects; a union missed by all samples yields 0.
+    """
+    rays = fibonacci_sphere(samples)
+    aa, bb = a.contains(rays), b.contains(rays)
+    union = int(np.count_nonzero(aa | bb))
+    return int(np.count_nonzero(aa & bb)) / union if union else 0.0
+
+
+def spherical_nms(
+    regions: list[SphericalRegion],
+    threshold: float = 0.5,
+    *,
+    samples: int = 65536,
+    class_agnostic: bool = False,
+) -> list[SphericalRegion]:
+    if not 0 <= threshold <= 1:
+        raise ValueError("threshold must be between 0 and 1.")
+    rays = fibonacci_sphere(samples)
+    # Evaluate each region once, rather than resampling every pair.
+    ordered = sorted(
+        regions, key=lambda r: r.box.score if r.box.score is not None else 1.0, reverse=True
+    )
+    kept: list[tuple[SphericalRegion, NDArray]] = []
+    for region in ordered:
+        mask = region.contains(rays)
+        suppressed = False
+        for other, other_mask in kept:
+            if not class_agnostic and region.box.label != other.box.label:
+                continue
+            union = int(np.count_nonzero(mask | other_mask))
+            overlap = int(np.count_nonzero(mask & other_mask)) / union if union else 0
+            if overlap > threshold:
+                suppressed = True
+                break
+        if not suppressed:
+            kept.append((region, mask))
+    return [region for region, _ in kept]

ray360/geometry.py

@@ -0,0 +1,78 @@
+"""Spherical coordinates. Rays use x=right, y=up, z=forward."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+FloatArray = NDArray[np.float64]
+
+
+def normalize(vectors: ArrayLike) -> FloatArray:
+    values = np.asarray(vectors, dtype=np.float64)
+    if values.ndim < 1 or values.shape[-1] != 3:
+        raise ValueError("Expected vectors with shape (..., 3).")
+    scale = np.max(np.abs(values), axis=-1, keepdims=True)
+    if not np.all(np.isfinite(values)) or np.any(scale == 0):
+        raise ValueError("Rays must be finite and nonzero.")
+    scaled = values / scale
+    return scaled / np.linalg.norm(scaled, axis=-1, keepdims=True)
+
+
+def lonlat_to_rays(lonlat: ArrayLike) -> FloatArray:
+    """Convert (..., 2) longitude/latitude in degrees to unit rays."""
+    ll = np.asarray(lonlat, dtype=np.float64)
+    if ll.ndim < 1 or ll.shape[-1] != 2 or not np.all(np.isfinite(ll)):
+        raise ValueError("Expected finite longitude/latitude pairs.")
+    if np.any(np.abs(ll[..., 1]) > 90):
+        raise ValueError("Latitude must be between -90 and 90 degrees.")
+    lon, lat = np.moveaxis(np.deg2rad(ll), -1, 0)
+    return np.stack((np.sin(lon) * np.cos(lat), np.sin(lat), np.cos(lon) * np.cos(lat)), -1)
+
+
+def rays_to_lonlat(rays: ArrayLike) -> FloatArray:
+    rays = normalize(rays)
+    lon = np.rad2deg(np.arctan2(rays[..., 0], rays[..., 2]))
+    lon = (lon + 180) % 360 - 180
+    lat = np.rad2deg(np.arctan2(rays[..., 1], np.hypot(rays[..., 0], rays[..., 2])))
+    return np.stack((lon, lat), -1)
+
+
+def rotation_matrix(yaw: float = 0, pitch: float = 0, roll: float = 0) -> FloatArray:
+    """Camera-to-world rotation: yaw right, pitch up, roll camera-right toward down."""
+    if not np.all(np.isfinite([yaw, pitch, roll])):
+        raise ValueError("Rotation angles must be finite.")
+    y, p, r = np.deg2rad([yaw, pitch, roll])
+    cy, sy, cp, sp, cr, sr = np.cos(y), np.sin(y), np.cos(p), np.sin(p), np.cos(r), np.sin(r)
+    ry = np.array([[cy, 0, sy], [0, 1, 0], [-sy, 0, cy]])
+    rx = np.array([[1, 0, 0], [0, cp, sp], [0, -sp, cp]])
+    rz = np.array([[cr, sr, 0], [-sr, cr, 0], [0, 0, 1]])
+    return ry @ rx @ rz
+
+
+def angular_distance(a: ArrayLike, b: ArrayLike) -> FloatArray:
+    """Great-circle angular distance in degrees, with NumPy broadcasting."""
+    a, b = normalize(a), normalize(b)
+    return np.rad2deg(np.arctan2(np.linalg.norm(np.cross(a, b), axis=-1), np.sum(a * b, -1)))
+
+
+def fibonacci_sphere(samples: int = 65536) -> FloatArray:
+    """Deterministic approximately equal-area samples, useful for spherical IoU."""
+    positive_int(samples, "samples")
+    index = np.arange(samples, dtype=np.float64)
+    y = 1 - 2 * (index + 0.5) / samples
+    lon = index * (np.pi * (3 - np.sqrt(5)))
+    r = np.sqrt(1 - y * y)
+    return np.stack((r * np.sin(lon), y, r * np.cos(lon)), -1)
+
+
+def positive_int(value: int, name: str) -> None:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise ValueError(f"{name} must be a positive integer.")
+
+
+def points2d(points: ArrayLike) -> FloatArray:
+    xy = np.asarray(points, dtype=np.float64)
+    if xy.ndim < 1 or xy.shape[-1] != 2 or not np.isfinite(xy).all():
+        raise ValueError("Expected finite coordinates with shape (..., 2).")
+    return xy

ray360/image.py

@@ -0,0 +1,81 @@
+"""Optional Pillow loading, saving and outline overlays for stitched images."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .annotations import Box2D, Polygon2D, SphericalRegion
+from .panorama import Panorama
+from .projections import Equirectangular, Projection
+
+
+def _pillow() -> Any:
+    try:
+        from PIL import Image
+    except ImportError as exc:
+        raise ImportError("Image helpers require Pillow; install 'ray360[image]'.") from exc
+    return Image
+
+
+def read_panorama(path: str | Path, *, projection: Equirectangular | None = None) -> Panorama:
+    """Read uint8 RGB pixels. Calling this explicitly declares the input stitched.
+
+    EXIF orientation is not applied: the supplied projection refers to stored pixels.
+    Use arrays directly for label images or high-bit-depth data.
+    """
+    with _pillow().open(path) as image:
+        array = np.array(image.convert("RGB"))
+    return Panorama(array, projection, source_id=str(path))
+
+
+def write_image(path: str | Path, image: NDArray, *, overwrite: bool = False) -> None:
+    """Write an array to the exact filename, refusing existing files by default."""
+    encoded = _pillow().fromarray(np.asarray(image))
+    path = Path(path)
+    extension = path.suffix.lower()
+    formats = _pillow().registered_extensions()
+    if extension not in formats:
+        raise ValueError(f"Unknown image extension {extension!r}.")
+    with path.open("wb" if overwrite else "xb") as stream:
+        encoded.save(stream, format=formats[extension])
+
+
+def overlay(
+    image: NDArray,
+    annotations: Iterable[Box2D | Polygon2D | SphericalRegion],
+    *,
+    projection: Projection | None = None,
+    color: tuple[int, int, int] = (255, 60, 40),
+    width: int = 2,
+) -> NDArray:
+    """Return RGB pixels with outlines. Spherical regions require a target projection."""
+    from .geometry import positive_int
+
+    positive_int(width, "width")
+    Image = _pillow()
+    from PIL import ImageDraw
+
+    base = Image.fromarray(np.asarray(image)).convert("RGB")
+    if projection is not None and projection.size != base.size:
+        raise ValueError("Overlay projection must match image dimensions.")
+    draw = ImageDraw.Draw(base)
+    for annotation in annotations:
+        if isinstance(annotation, SphericalRegion):
+            if projection is None:
+                raise ValueError("Spherical overlays require a target projection.")
+            polygons = annotation.polygons(projection)
+        elif isinstance(annotation, Box2D):
+            polygons = [annotation.polygon()]
+        elif isinstance(annotation, Polygon2D):
+            polygons = [annotation]
+        else:
+            raise TypeError("Expected a box, rendered polygon or spherical region.")
+        for polygon in polygons:
+            points = [tuple(p) for p in polygon.vertices.tolist()]
+            draw.line(points + points[:1], fill=color, width=width)
+    return np.array(base)