Geometry: control rays and projections

Choose Geometry when the application must own coordinates, view placement, projection shape, FOV, interpolation or back-projection. panorai.geometry is the mathematical source of truth used by every higher level.

Surface	Stability	Canonical import	Contract	Public components or entries
canonical-geometry	Stable	panorai.geometry	geometry-v1	CUBE_FACE_BASES, CUBE_FACE_ORDER, ArrayLike, CubemapProjector, CubemapSpec, ERPPointProjection, GnomonicFaceGeometry, GnomonicPointProjection, GnomonicProjector, GnomonicRayProjection, GnomonicSpec, Interpolation, InvalidPolicy, NumpyArray, ProjectionResult, ShapeHW, TensorLike, cubemap_to_equirectangular, equirectangular_to_cubemap, equirectangular_to_gnomonic, erp_pixels_to_rays, gnomonic_face_geometry, gnomonic_intrinsics, gnomonic_pixel_map, gnomonic_pixels_to_rays, gnomonic_rotation, gnomonic_to_equirectangular, rays_to_gnomonic_pixels, rays_to_erp_pixels
registered-camera-geometry	Experimental	panorai.geometry	panorai-registered-camera-geometry/v1-experimental	camera_rays_to_world_points, relative_camera_pose, world_points_to_camera_rays
core-geometry-preview	Compatibility	panorai.core.geometry	geometry-v1	CUBE_FACE_BASES, CUBE_FACE_ORDER, ArrayLike, CubemapProjector, CubemapSpec, ERPPointProjection, GnomonicFaceGeometry, GnomonicPointProjection, GnomonicProjector, GnomonicRayProjection, GnomonicSpec, Interpolation, InvalidPolicy, NumpyArray, ProjectionResult, ShapeHW, TensorLike, camera_rays_to_world_points, cubemap_to_equirectangular, equirectangular_to_cubemap, equirectangular_to_gnomonic, erp_pixels_to_rays, gnomonic_face_geometry, gnomonic_intrinsics, gnomonic_pixel_map, gnomonic_pixels_to_rays, gnomonic_rotation, gnomonic_to_equirectangular, rays_to_gnomonic_pixels, rays_to_erp_pixels, relative_camera_pose, tangent_offsets_to_rays, world_points_to_camera_rays
pinhole-camera-geometry	Experimental	panorai.calibration	panorai-pinhole-intrinsics/v1-experimental	PinholeIntrinsics, pinhole_pixels_to_rays, pinhole_rays_to_pixels

1. Convert ERP pixels to bearings

ERP pixel coordinates address pixel centres. Conversion returns unit bearings in the canonical panorama frame; the inverse returns pixels plus explicit projection information.

import numpy as np
from panorai.geometry import (
    GnomonicProjector,
    GnomonicSpec,
    erp_pixels_to_rays,
    rays_to_erp_pixels,
)

shape_hw = (18, 36)
pixels_xy = np.asarray([[17.5, 8.5], [26.5, 8.5]], dtype=np.float64)
rays_xyz = erp_pixels_to_rays(pixels_xy, shape_hw)
recovered = rays_to_erp_pixels(rays_xyz, shape_hw)
np.testing.assert_allclose(recovered.pixels_xy, pixels_xy, atol=1e-12)

spec = GnomonicSpec(
    center_lat_deg=10.0,
    center_lon_deg=25.0,
    hfov_deg=90.0,
    vfov_deg=70.0,
    output_shape_hw=(8, 10),
)
projector = GnomonicProjector(spec, interpolation="bilinear")
rgb = np.ones((*shape_hw, 3), dtype=np.float32)
view = projector.project(rgb)
assert view.data.shape == (8, 10, 3)
assert view.support_mask.shape == (8, 10)

2. Make a virtual camera explicit

GnomonicSpec fixes centre longitude/latitude, horizontal and vertical FOV, roll and output shape. GnomonicProjector adds interpolation and reusable projection planning. The returned ProjectionResult keeps data and support together for natural back-projection.

3. Select interpolation by modality

Floating RGB and continuous fields may use bilinear or nearest sampling. Integer labels and boolean masks require nearest sampling. Radial-range depth keeps validity separate from numeric zero and may use strict propagation or an explicit valid-weight renormalization policy.

4. Respect seams and poles

Longitude wraps horizontally in [-pi, pi). Exact poles lie on raster boundaries rather than pixel centres and have no unique longitude. Cubemap face order, tie rules and gnomonic roll/FOV conventions are fixed by geometry-v1 rather than by an application wrapper.

Read The geometry contract for the mental model, Geometry API for signatures and the normative specification for exact formulas and boundary behavior. The long-form projection tutorial continues into samplers and blenders.