Canonical geometry API

panorai.geometry is the stable mathematical API for PanorAi 3.x. Shapes, coordinate conventions, dtype rules, and depth meaning are defined in PanorAi canonical spherical geometry.

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

Use the Geometry catalog to choose among coordinate conversions, configured projectors, specs and result types.

Composable projectors

Configured projectors accept their own result objects during back-projection; manual extraction of .data is optional:

import numpy as np

from panorai.geometry import GnomonicProjector, GnomonicSpec

erp = np.zeros((512, 1024), dtype=np.float32)
projector = GnomonicProjector(
    GnomonicSpec(output_shape_hw=(320, 640)), interpolation="bilinear"
)
view = projector.project(erp)
restored = projector.back_project(view, output_shape_hw=erp.shape[:2])

CubemapProjector.back_project likewise accepts the complete mapping returned by project. Both paths preserve NumPy/Torch backend, layout, dtype, device, batch, channels, and input-value autograd according to the geometry-v1 contract.

Invalid-aware bilinear sampling

invalid_policy="propagate" is the strict default. To interpolate only valid floating neighbours, construct a projector with invalid_policy="renormalize" and an explicit min_valid_weight, then pass a boolean validity_mask to project. Its result includes both the output validity_mask and the sampled valid_weight; passing that result directly to back_project carries its validity mask forward. Integer labels and boolean masks remain nearest-only.

Specification validation

Canonical specifications are immutable and normalized. Latitude is finite and within [-90, 90] degrees. Longitude and roll are stored in [-180, 180). Fields of view are finite and strictly within (0, 180). Shapes contain exactly two positive integers; booleans, numeric strings, and floating dimensions are rejected rather than coerced or truncated. An invalid interpolation name fails when a projector is constructed.

Typing and accepted arrays

The distribution includes py.typed. Public functions preserve their input array type through generic ProjectionResult and ERPPointProjection annotations. NumPy accepts HW and HWC numpy.ndarray values. Optional Torch accepts HW, CHW, and NCHW torch.Tensor values. ArrayLike and TensorLike provide public annotations without importing Torch at runtime; importing panorai.geometry therefore keeps the optional backend unloaded.

Registered camera frames (Experimental)

panorai.geometry.camera_rays_to_world_points(bearings_camera, radial_range, rotation_world_to_camera, center_world)

Back-project camera bearings and radial range into the world frame.

NumPy arrays and Torch tensors are supported. Torch inputs preserve dtype, device, and autograd. radial_range must be broadcast-compatible with bearings_camera[..., 0]. Validity is deliberately not inferred from numeric values; callers must apply their explicit validity mask first.

panorai.geometry.world_points_to_camera_rays(points_world, rotation_world_to_camera, center_world)

Project world points to unit camera bearings and radial ranges.

Points at the camera centre have no defined bearing and are rejected. The returned radial range uses the same units as points_world and center_world.

panorai.geometry.relative_camera_pose(rotation_world_to_reference, center_reference_world, rotation_world_to_source, center_source_world)

Return the source-from-reference rigid transform.

The result satisfies x_source = R @ x_reference + t and is the pose convention consumed by PanorAi’s registered spherical stereo engines. Inputs must all use one backend; the reference rotation selects the output dtype and device.

These additive helpers use x_camera = R @ (X - C) and are separately classified as Experimental; their presence does not expand the Stable geometry-v1 projection contract.

Canonical spherical-geometry API for PanorAi 3.x.

The canonical frame is +X right, +Y up and +Z forward. ERP coordinates refer to pixel centres, start at the top-left, wrap horizontally, and store latitude from +pi/2 at the top to -pi/2 at the bottom. Depth values are radial ranges. The geometry-v1 projection core is Stable; additive camera/world frame helpers are explicitly Experimental until their independent promotion gates pass.

class panorai.geometry.CubemapProjector(spec, interpolation='bilinear', fill_value=None, invalid_policy='propagate', min_valid_weight=None)

Configured ERP/cubemap projector with canonical face ordering.

spec

interpolation

fill_value

invalid_policy

min_valid_weight

back_project(faces, output_shape_hw, *, validity_masks=None)

project(erp, *, validity_mask=None)

class panorai.geometry.CubemapSpec(face_shape_hw=(1024, 1024))

Canonical cubemap configuration with a shared face shape.

face_shape_hw

class panorai.geometry.ERPPointProjection(pixels_xy, ranges, valid)

Cartesian rays or points projected onto ERP pixel coordinates.

pixels_xy

ranges

valid

class panorai.geometry.GnomonicFaceGeometry(face_id, spec, K, R_panorama_from_face, support_mask, source_pixels_xy=None)

Explicit pinhole geometry and provenance for one gnomonic face.

K follows the usual image convention of +x right and +y down. The columns of R_panorama_from_face are therefore the face-camera right, down, and forward axes expressed in PanorAi’s panorama frame. The y-axis convention change makes this an orthogonal direction transform with determinant -1, not an SO(3) pose; relative face transforms are proper rotations.

face_id

spec

K

R_panorama_from_face

support_mask

source_pixels_xy

class panorai.geometry.GnomonicPointProjection(pixels_xy, ranges, valid)

Panorama-frame rays projected onto a gnomonic raster.

pixels_xy

ranges

valid

class panorai.geometry.GnomonicProjector(spec, interpolation='bilinear', fill_value=None, invalid_policy='propagate', min_valid_weight=None)

Publicly immutable ERP/gnomonic projector with private reusable plans.

spec

interpolation

fill_value

invalid_policy

min_valid_weight

back_project(face, output_shape_hw, *, validity_mask=None)

project(erp, *, validity_mask=None, return_source_pixels=False)

class panorai.geometry.GnomonicRayProjection(rays_xyz, valid)

Gnomonic pixels converted to panorama-frame unit rays.

rays_xyz

valid

class panorai.geometry.GnomonicSpec(center_lat_deg=0.0, center_lon_deg=0.0, hfov_deg=90.0, vfov_deg=90.0, roll_deg=0.0, output_shape_hw=(1024, 1024))

Canonical description of a rectangular gnomonic view.

Angles are expressed in degrees. output_shape_hw follows (H, W).

center_lat_deg

center_lon_deg

hfov_deg

vfov_deg

roll_deg

output_shape_hw

classmethod from_config(config)

Convert a legacy GnomonicConfig without requiring new fields.

class panorai.geometry.ProjectionResult(data, support_mask, validity_mask=None, valid_weight=None, source_pixels_xy=None)

Projected data and masks with support kept distinct from validity.

validity_mask and valid_weight are populated by the opt-in validity-normalized bilinear mode. Their defaults preserve construction and access of the original two-field result contract. source_pixels_xy is an optional raster-to-source coordinate map.

data

support_mask

validity_mask

valid_weight

source_pixels_xy

class panorai.geometry.TensorLike(*args, **kwargs)

Structural minimum shared by supported Torch tensor inputs.

The protocol keeps Torch optional at import time. Runtime geometry still accepts concrete numpy.ndarray and torch.Tensor objects only.

property dtype

property ndim

property shape

panorai.geometry.cubemap_to_equirectangular(faces, output_shape_hw, *, interpolation='bilinear', invalid_policy='propagate', validity_masks=None, min_valid_weight=None)

Convert six canonical cubemap faces into an ERP image.

panorai.geometry.camera_rays_to_world_points(bearings_camera, radial_range, rotation_world_to_camera, center_world)

Back-project camera bearings and radial range into the world frame.

NumPy arrays and Torch tensors are supported. Torch inputs preserve dtype, device, and autograd. radial_range must be broadcast-compatible with bearings_camera[..., 0]. Validity is deliberately not inferred from numeric values; callers must apply their explicit validity mask first.

panorai.geometry.equirectangular_to_cubemap(image, face_shape_hw, *, interpolation='bilinear', invalid_policy='propagate', validity_mask=None, min_valid_weight=None)

Convert ERP data into the six canonical cubemap faces.

panorai.geometry.equirectangular_to_gnomonic(image, spec, *, interpolation='bilinear', invalid_policy='propagate', validity_mask=None, min_valid_weight=None, return_source_pixels=False)

Sample an ERP image into a canonical rectangular gnomonic view.

panorai.geometry.erp_pixels_to_rays(pixels_xy, image_shape_hw)

Convert ERP pixel-centre coordinates to unit Cartesian rays.

pixels_xy must have a final dimension of length two. Coordinates use a top-left image origin and may be fractional. Horizontal coordinates wrap.

panorai.geometry.gnomonic_face_geometry(face_id, spec, support_mask, *, erp_shape_hw=None, include_source_pixels=False)

Construct explicit virtual-camera metadata for a materialized face.

panorai.geometry.gnomonic_intrinsics(spec, *, like=None)

Return the pinhole intrinsic matrix equivalent to spec.

Pixel coordinates follow PanorAi’s pixel-centre convention. The local camera raster uses +x right and +y down, as expected by OpenCV and COLMAP.

panorai.geometry.gnomonic_pixel_map(spec, erp_shape_hw, *, like=None)

Return the face-to-ERP source pixel map used by canonical sampling.

panorai.geometry.gnomonic_pixels_to_rays(pixels_xy, spec)

Convert gnomonic pixel-centre coordinates to panorama-frame unit rays.

The final dimension of pixels_xy is (x, y). valid is true for finite coordinates inside the closed raster footprint [-0.5, W-0.5] x [-0.5, H-0.5]. Invalid rays are returned as NaN. Floating NumPy dtype and Torch dtype/device are preserved.

panorai.geometry.gnomonic_rotation(spec, *, like=None)

Return R_panorama_from_face for the rolled virtual camera.

Columns are the face camera’s right, down, and forward axes expressed in the canonical panorama frame (+X right, +Y up, +Z forward). Because raster y is down while panorama Y is up, this orthogonal direction transform has determinant -1; relative face transforms are rotations.

panorai.geometry.gnomonic_to_equirectangular(image, spec, output_shape_hw, *, interpolation='bilinear', fill_value=None, invalid_policy='propagate', validity_mask=None, min_valid_weight=None)

Back-project a gnomonic view and return its exact rectangular support.

panorai.geometry.rays_to_gnomonic_pixels(rays_xyz, spec)

Project panorama-frame rays or points onto a gnomonic raster.

panorai.geometry.rays_to_erp_pixels(rays, image_shape_hw)

Project Cartesian rays or points onto ERP pixel-centre coordinates.

panorai.geometry.relative_camera_pose(rotation_world_to_reference, center_reference_world, rotation_world_to_source, center_source_world)

Return the source-from-reference rigid transform.

The result satisfies x_source = R @ x_reference + t and is the pose convention consumed by PanorAi’s registered spherical stereo engines. Inputs must all use one backend; the reference rotation selects the output dtype and device.

panorai.geometry.world_points_to_camera_rays(points_world, rotation_world_to_camera, center_world)

Project world points to unit camera bearings and radial ranges.

Points at the camera centre have no defined bearing and are rejected. The returned radial range uses the same units as points_world and center_world.