Apply a pinhole method over the sphere

Level: Start · Strategy: Projection-domain · Stability: Stable object workflow

Use this route when the operation already consumes an ordinary perspective image. PanorAi owns the spherical sampling and reconstruction; the face function remains caller-owned.

What the workflow guarantees

The callback receives a normal HWC image, but it is not an arbitrary crop. Its pixels are sampled along the rays described by face.spec; face.support identifies directions that really belong to the source panorama. The inverse mapping uses the same geometry, so overlap is resolved on the sphere rather than by pasting rectangular faces.

import cv2
import numpy as np
from panorai import EquirectangularImage

rgb = np.zeros((128, 256, 3), dtype=np.uint8)
panorama = EquirectangularImage(rgb)
views = panorama.views("icosahedron", size=128, fov=100)
processed = views.map(lambda face: cv2.GaussianBlur(face, (5, 5), 1.0))
result = processed.reconstruct(blend="gaussian")

The result is another EquirectangularImage. Access the reconstructed RGB with result.image and retain result.support; black pixels are not an implicit invalid mask.

When to use the explicit stages

Keep views, processed and result separate when you need to inspect a failed face, batch a model, or return something other than a raster. For a single raster callback, panorama.process_views(...) executes the same views().map().reconstruct() composition.

Typical face-local functions include OpenCV filters, a detector, a semantic segmenter, or a monocular depth model. Their outputs do not all use the same return path: continuous rasters are blended, labels use nearest/closest, and points or regions are lifted as observations.

Failure checks

  • If seams appear, inspect overlap, border support and the selected blender.

  • If integer labels acquire new IDs, bilinear sampling was used incorrectly.

  • If a method fails near face edges, increase overlap or reject an edge margin.

  • If a face needs a camera matrix, derive it from face.spec; do not reuse an ERP width as a pinhole focal length.

Next: choose sampling and fusion, or read the complete projection tutorial.