The geometry contract¶
Geometry is the common language beneath every PanorAi API level. It fixes what a pixel means, how a ray is oriented and which samples are covered before any application or operation is chosen.
Surface |
Stability |
Canonical import |
Contract |
Public components or entries |
|---|---|---|---|---|
spherical-region-analysis-data |
Stable |
panorai.data |
panorai-spherical-region-analysis/v1 |
EnclosingSphericalCap, RegionAdjacencyEdge, RegionAdjacencyGraph, RegionAnalysisResult, RegionMeasurement, RegionMeasurements, SphericalBoundary, SphericalBoundarySet, SphericalContour, SphericalContourSet, panorai.data.regions.EnclosingSphericalCap, panorai.data.regions.RegionAdjacencyEdge, panorai.data.regions.RegionAdjacencyGraph, panorai.data.regions.RegionAnalysisResult, panorai.data.regions.RegionMeasurement, panorai.data.regions.RegionMeasurements, panorai.data.regions.SphericalBoundary, panorai.data.regions.SphericalBoundarySet, panorai.data.regions.SphericalContour, panorai.data.regions.SphericalContourSet |
spherical-observations |
Stable |
panorai.data |
panorai-spherical-observations/v1 |
AggregatedViewEvidence, DataFactory, EquirectangularImage, FacePointBatch, FaceRegionBatch, FaceViewOutput, GnomonicFace, GnomonicFaceSet, ObservationFusionResult, RasterFieldResult, RasterFieldSpec, SphericalBinaryMask, SphericalPointObservation, SphericalPointSet, SphericalRegionObservation, SphericalRegionSet, SphericalTranspose, SphericalViewObservation, SphericalViewSet, XYZImageDataset, panorai.data.utils.PanoraiError, panorai.data.utils.InvalidDataError, panorai.data.utils.ChannelMismatchError, panorai.data.utils.MetadataValidationError, panorai.data.utils.DataConversionError, panorai.data.utils.MissingChannelError, panorai.data.utils.ensure_type_consistency, panorai.data.utils.ShapeManager, panorai.data.xyz_image_dataset.XYZImageDataset, panorai.data.xyz_image_dataset.extract_hw_from_ply_filename, panorai.data.xyz_image_dataset.read_encrypted_ply_xyz_image, panorai.data.xyz_image_dataset.read_ply_xyz_image |
spherical-core-contracts |
Experimental |
panorai.core |
panorai-core-operations/v1 |
SPHERICAL_CORE_INTERFACE, SphericalConv2dSpec, SphericalExecutionSpec, SphericalGridSpec, SphericalNeighborhoodSpec, SphericalPool2dSpec, SphericalResizeSpec, panorai.core.specs.BackendName, panorai.core.specs.Interpolation, panorai.core.specs.Layout, panorai.core.specs.SphericalConv2dSpec, panorai.core.specs.SphericalExecutionSpec, panorai.core.specs.SphericalGridSpec, panorai.core.specs.SphericalNeighborhoodSpec, panorai.core.specs.SphericalPool2dSpec, panorai.core.specs.SphericalResizeSpec |
panorama-stitching-data |
Experimental |
panorai.stitching |
panorai-panorama-stitching/v1-experimental |
ImagePairMatches, ImagePairRegistration, PanoramaStitchingResult, RegisteredImageSet, StitchingDiagnostics, StitchingFeatureSet, StitchingFeatures, StitchingImage, StitchingInput, StitchingMatches, StitchingOptions, WarpedImageSet |
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 |
Coordinate frame and pixels¶
PanorAi uses +X right, +Y up and +Z forward. Raster coordinates
start at the top-left and address pixel centres. Longitude is periodic in
[-pi, pi) and latitude runs north to south. ERP pixels convert to unit
bearings; a radial range multiplies a bearing to produce a 3-D point.
Depth is radial range¶
Unqualified depth means distance from the panorama centre along the bearing,
not the Z component of a virtual camera. APIs that use axial depth must say
so and convert with an explicit frame and projection.
Support, validity and value¶
Geometric support answers whether a projection covers a sample. Data validity
answers whether a usable observation contributed. Numeric value is the
measurement. A black RGB pixel, label zero or range zero can be valid; a
non-zero fill value can be unsupported. These three facts must never be
collapsed into value != 0.
Sampling follows modality¶
Continuous fields may use nearest or bilinear interpolation under a declared invalid-data policy. Integer labels and boolean masks use nearest sampling. Projection results carry support and validity so back-projection and blending do not infer either from color or magnitude.
Specs make virtual cameras reproducible¶
Immutable gnomonic and cubemap specs define view direction, full FOV, roll, output shape and face order. Projectors bind those specs to interpolation and reusable plans. The normative geometry-v1 specification defines seams, poles, boundaries and tie rules precisely.
See the Geometry tutorial and Geometry API.