Spherical raster fields and observations

panorai-spherical-observations/v1 is the Stable typed-output layer of the object workflow. Its canonical imports live in panorai.data. Projection formulas remain owned by Canonical geometry API.

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

Use the typed data and results catalog to compare these observation topologies with Pipeline fields, bundles and execution records.

Four output topologies

Planar output	Face-set operation	Spherical result and reduction
dense raster	map(..., spec=RasterFieldSpec(...))	reconstruct() with a declared blend
points	map_points() / face.lift_points()	SphericalPointSet.angular_nms()
boxes, polygons, or masks	map_regions() / face.lift_regions()	solid-angle nms() or merge()
one score vector or embedding per view	map_views() / face.lift_view()	explicit coverage_mean or score-only max

Raster fields

RasterFieldSpec declares continuous or categorical semantics, units, interpolation, default blend, and optional component IDs. Continuous fields cover CAM, logits, confidence, and dense embeddings whose components do not change with the local basis. Categorical fields require nearest sampling and closest-view fusion. Optical flow, normals, vectors, and covectors are rejected by this contract because transporting their components requires an explicit Jacobian and frame convention.

RasterFieldResult lets an operator return data, data validity, and geometric support separately. If validity is absent, map() inherits the input validity intersected with output support. A supplied validity mask is also intersected with support. Numeric zero remains valid evidence.

Use EquirectangularImage.from_field() for a field-only ERP, with_field() for a multimodal bundle, and apply_spherical() for a shape-preserving operator that already works directly on the ERP. Existing image, radial depth, and labels calls retain their 3.x behavior.

Points

FacePointBatch uses N×2 continuous face pixels plus aligned validity, scores, class IDs, and attributes. Lifting records the original face pixel, source ERP pixel when known, unit bearing, face ID, source ID, projection spec, and validity. angular_nms() is deterministic: score descends first, then face ID and observation order resolve ties. Invalid inputs stay auditable but do not participate in reduction.

Regions

Boxes use continuous xyxy pixel-centre coordinates; the complete face is (-0.5, -0.5, W-0.5, H-0.5). Boxes and polygons retain a boundary of unit bearings connected by great-circle arcs. Masks require an explicit boolean dtype, are support-clipped, nearest-neighbour reprojected, and stored as SphericalBinaryMask; integer or floating masks are never thresholded or cast implicitly. Finite geometry outside a face is clipped and marked; inverted or non-finite geometry fails.

Region IoU and containment are weighted by ERP pixel solid angle. NMS retains one observation and a complete suppression report. Merge stores only the compact union mask and provenance; temporary dense comparison masks are not part of the result contract. Class-aware operations do not combine incompatible class IDs. When source regions have no score, merge keeps the score absent rather than inventing a numeric confidence.

View evidence

FaceViewOutput carries scores, class IDs, an embedding, or both. Every lifted observation retains the exact GnomonicSpec and effective support. coverage_mean first divides overlapping contributions per direction, then integrates with solid-angle weights. max is allowed for scores only. Embedding L2 normalization is controlled explicitly.

Region-analysis evidence

RegionAnalysisResult combines solid-angle RegionMeasurements, a RegionAdjacencyGraph and optional SphericalBoundarySet. Each RegionMeasurement records pixel count, physical area, support fraction, angular perimeter, boundary against missing data, spherical centroid and a conservative enclosing cap. These Experimental types describe direct ERP region analysis and are distinct from face-lifted SphericalRegionObservation objects.

class panorai.data.RegionAnalysisResult(measurements, adjacency, boundaries=None, contours=None, interface='panorai-spherical-region-analysis/v1')

Measurements, adjacency and optional boundaries for one label field.

class panorai.data.RegionMeasurements(shape_hw, support_solid_angle_sr, regions, interface='panorai-spherical-region-analysis/v1')

Measurements for every positive label in one canonical ERP.

class panorai.data.RegionMeasurement(label, pixel_count, solid_angle_sr, support_fraction, angular_perimeter_rad, unsupported_boundary_rad, centroid_bearing_xyz, enclosing_cap, interface='panorai-spherical-region-analysis/v1')

Geometry-aware measurements for one positive integer label.

class panorai.data.RegionAdjacencyGraph(labels, edges, interface='panorai-spherical-region-analysis/v1')

Deterministic region adjacency graph with angular contact lengths.

class panorai.data.RegionAdjacencyEdge(labels, shared_boundary_rad, interface='panorai-spherical-region-analysis/v1')

One undirected contact between two positive labels.

class panorai.data.SphericalBoundarySet(shape_hw, boundaries, interface='panorai-spherical-region-analysis/v1')

Boundary samples for each positive label in one ERP.

class panorai.data.SphericalBoundary(label, bearings_xyz, angular_length_rad, interface='panorai-spherical-region-analysis/v1')

Unordered pixel-centre samples of one label’s spherical boundary.

class panorai.data.EnclosingSphericalCap(center_bearing_xyz, radius_deg, interface='panorai-spherical-region-analysis/v1')

A conservative spherical cap enclosing sampled region centres.

Backend and mutability

Dense raster processing preserves NumPy or Torch backend, dtype, device, and batch. Non-raster observations are copied to read-only NumPy arrays. Their ordinary constructors reject Torch tensors; from_torch() performs the visible detach → CPU → NumPy conversion. Importing panorai.data does not import Torch.