Composed spherical API

Surface	Stability	Canonical import	Contract	Public components or entries
legacy-composition	Compatibility	panorai	panorai-3x-compatibility/v1	EquirectangularImage, GnomonicFace, GnomonicFaceSet, ConfigManager, PanoraiFactory, panorai.projections.GnomonicProjection, panorai.projections.ProjectionRegistry, panorai.projections.base.BaseProjectionStrategy, panorai.projections.base.BaseGridGeneration, panorai.projections.base.BaseInterpolation, panorai.projections.base.BaseCoordinateTransformer, panorai.projections.base.ProjectionError, panorai.projections.base.ConfigurationError, panorai.projections.base.RegistrationError, panorai.projections.base.ProcessingError, panorai.projections.base.GridGenerationError, panorai.projections.base.TransformationError, panorai.projections.base.InterpolationError, panorai.samplers.SamplerRegistry, panorai.samplers.Sampler, panorai.samplers.CubeSampler, panorai.samplers.IcosahedronSampler, panorai.samplers.FibonacciSampler, panorai.samplers.BlueNoiseSampler, panorai.samplers.SpiralSampler, panorai.utils.ResizerConfig, panorai.utils.ImageResizer, panorai.utils.PreprocessEquirectangularImage, panorai.utils.setup_logging
root-convenience-exports	Compatibility	panorai.features	panorai-root-convenience/v1	SphericalFeaturePipeline, __version__
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
spherical-instance-pipeline-root-convenience	Experimental	panorai.pipeline	panorai-spherical-instance-pipeline/v1-experimental	CAMGuidedSphericalInstances, CAMRegionProposals, SAMMaskRefinement, SphericalCAM, SphericalInstanceFusion

Note

The generic Pipeline, typed grid/result, routing, persistence, cache, general NumPy spherical-operation contracts, and generic Torch layer grammar are Stable. The Stable Torch device contract covers CPU float32 and float64; CUDA and MPS remain outside that guarantee. SphericalSLIC and the SLIC operation are separately Stable as panorai-spherical-slic/v1. The generic application framework, DoG, Stereo, Mask R-CNN Workflow, and CAM/SAM instance stages remain Experimental. A shared namespace never promotes an Experimental name by implication. The original Stable object workflow remains panorai.EquirectangularImage, panorai.GnomonicFace, and panorai.GnomonicFaceSet.

The composition API has four levels. Start at the highest level that expresses the task; descend only when an application needs different stages.

1. Applications

SLIC

from panorai.applications import SphericalSLIC

application = SphericalSLIC(n_segments=100, compactness=10.0)
labels = application(rgb)

labels is a RasterField(kind="labels") on the canonical ERP grid. Support and data validity remain independent, and label resampling is nearest only. application.as_pipeline() exposes the exact lower-level composition. The wrapper, configured operation, and historical function share the Stable panorai-spherical-slic/v1 contract.

DoG features

from panorai.applications import SphericalDoGFeatures

features = SphericalDoGFeatures()(rgb, panorama_id="frame-0001")
bearings = features.bearings
descriptors = features.descriptors

This wrapper delegates to SphericalDoGSIFTExtractor. It does not create a second scale-space implementation. OpenCV SIFT is an external optional dependency.

Stereo depth

from panorai.applications import SphericalStereoDepth

estimate = SphericalStereoDepth()(reference, source, R_source_from_reference, t)

The result is radial range in the unit of t, plus confidence, validity and matching diagnostics. The pose convention is X_source = R_source_from_reference @ X_reference + t.

Mask R-CNN workflow

from panorai.experimental.deep_learning import mask_rcnn

method = mask_rcnn.workflow(
    proposal_mode="cam",
    proposal=cam_adapter,
    mask=sam_adapter,
    heuristic=instance_heuristic,
    concepts=("pipe", "equipment"),
    num_classes=3,
)
instances = method(rgb)

In CAM mode, CAM generates spherical search regions and SAM refines their masks. In SAM mode, SAM generates the proposals and reuse_proposal_masks=True makes those masks the MaskHead output. The heuristic makes abstaining per-instance decisions in the BoxHead role; it is not described as a learned classifier. mask_rcnn.paper() remains a deprecated compatibility alias for the original Experimental factory name.

2. Pipeline composition

This section describes the Stable panorai-spherical-pipeline/v1 core. The CAM/SAM proposal and instance-fusion stages shown in the Mask R-CNN method remain Experimental.

from panorai.pipeline import (
    Output, PerView, Pipeline, ReconstructERP, SampleViews,
)

pipeline = Pipeline(
    SampleViews("fibonacci", count=100, size=256, fov=100),
    PerView.parallel(
        batch="auto",
        labels=Output(segmenter, kind="labels"),
        depth=Output(depth_model, kind="depth", units="m"),
        detections=Output(detector, kind="detections"),
    ),
    ReconstructERP(labels="closest", depth="gaussian"),
)

PerView.parallel is a logical multi-head branch, not a promise of threads. Raster outputs carry a RasterGrid; non-raster results retain face identity, projection, support and validity. Reconstruction consumes raster branches and keeps the other branches in the result bundle. Select and Attach route paths such as views.depth and erp.labels.

Third-party stages implement the public Stage protocol: declare input_kind and output_kind and return StageResult from execute(value). A Pipeline is itself a stage and can be nested.

Batching is deterministic. None executes each face, an integer fixes chunk size, and "auto" is available only to adapters that declare batch support. PanorAi does not retry silently after an out-of-memory failure.

3. Operations and Torch

panorai.ops.spherical.functional contains direct functions. Immutable objects with matching names are suitable for OnSphere and safe JSON topology persistence. panorai.ops.spherical.algorithms provides SLIC, DoG, spherical NMS, Canny, and Gaussian/Laplacian pyramids.

General NumPy operations are Stable as panorai-spherical-ops/v1. SLIC is Stable under its own panorai-spherical-slic/v1 contract. DoG and the mixed algorithms module remain Experimental until their remaining gates pass.

The optional, Stable panorai.ops.spherical.nn namespace provides Conv2d, ConvTranspose2d, max/average pooling, global pooling, resize, interpolation, from_planar and validate. Learned convolution uses strict validity propagation. Renormalization is defined only for mathematically normalized average/Gaussian operations; arbitrary learned weights are never renormalized. CPU float32 and float64 are the Stable device contract; CUDA and MPS remain outside that guarantee pending independent device matrices. The validator rejects opaque functional spatial calls and custom container semantics rather than guessing that they are sphere-safe.

Every spatial operation implements transform_grid(input_grid). Convolution and pooling retain anchor and stride history. A reduced lattice cannot be attached or reconstructed as canonical ERP without explicit regridding.

4. Contracts, persistence and architecture

Pipeline topology is canonical JSON over an explicit PanorAi allowlist. Files never name an arbitrary class to import. Registered Torch architectures store topology by identifier and weights in a checksum-bound weights.safetensors file. Built-in spherical layers and torch.nn.Sequential are registered. Trusted application code may call register_torch_module() for another architecture; the same registration must exist before loading. A custom direct OnSphere module must also declare spherical_semantics="pointwise" at registration when it preserves each spatial sample independently. Unknown custom modules and forward hooks fail closed.

Local cache entries use canonical JSON state, safe NumPy archives, checksums and atomic writes; pickle is forbidden. Cache identity includes values, support, validity, grid, layout, backend, device, PanorAi version, pipeline configuration and registered weight identity. Torch modules must be in eval mode. A tensor requiring gradients fails before caching so cache reuse cannot detach autograd silently.

method.architecture exposes Backbone, ProposalGenerator, RoIAlign, BoxHead, MaskHead and RoIHeads. SphericalMaskRCNN exposes the conventional future trainable Backbone→RPN→RoIAlign→Box/Mask topology, but execution raises UnboundMaskRCNNError. No trainer, dataset framework or checkpoint is part of PanorAi’s projection core.

Remaining Experimental promotion blockers

Each remaining application or scientific algorithm stays Experimental until its own frozen criteria pass. These failures do not revoke the Stable generic Pipeline, NumPy-operation, or SLIC contracts:

• DoG analytic blobs and external repeatability/localization/inlier thresholds;

• stereo analytic and independent Matterport3D/Stanford2D3D thresholds;

• real external CAM and SAM checkpoints plus annotated panoramic proposal, mask, semantic and support measurements;

• exact clean wheel/sdist consumers, benchmarks, license audit and independent review.

Missing external evidence blocks only the corresponding promotion; it is not converted into a passing source-only claim.