Spherical operations API

Use the Spherical Ops catalog to compare function, configured-object, algorithm and Torch-layer forms. This page records the namespace-level contracts and important validation rules.

Surface	Stability	Canonical import	Contract	Public components or entries
spherical-region-analysis-ops	Stable	panorai.ops.spherical	panorai-spherical-region-analysis/v1	ConnectedComponents, FillHoles, GeodesicDistanceTransform, RegionBoundaries, Skeletonize, connected_components, extract_boundaries, fill_holes, geodesic_distance_transform, measure_regions, region_adjacency_graph, region_boundaries, skeletonize, trace_contours, watershed, panorai.ops.spherical.functional.connected_components, panorai.ops.spherical.functional.extract_boundaries, panorai.ops.spherical.functional.fill_holes, panorai.ops.spherical.functional.geodesic_distance_transform, panorai.ops.spherical.functional.measure_regions, panorai.ops.spherical.functional.region_adjacency_graph, panorai.ops.spherical.functional.region_boundaries, panorai.ops.spherical.functional.skeletonize, panorai.ops.spherical.functional.trace_contours, panorai.ops.spherical.functional.watershed
supported-blenders	Stable	panorai.blenders	panorai-blenders/v1	BlenderRegistry, BaseBlender, AverageBlender, FeatheringBlender, GaussianBlender, ClosestBlender, OverlapCounterBlender, OverlapStdBlender, OverlapStdFeatheredBlender, HuberBlender, average, gaussian, feathering, closest, huber, counter, std, std_feathered
spherical-image-processing	Experimental	panorai.image_processing	panorai-spherical-image-processing/v1	SphericalGradient, native_filter_available, reconstruct_laplacian_pyramid, spherical_bilateral_filter, spherical_box_blur, spherical_canny, spherical_equalize_histogram, spherical_filter2d, spherical_gaussian_blur, spherical_gaussian_pyramid, spherical_gradient, spherical_laplacian, spherical_laplacian_pyramid, spherical_median_blur, spherical_resize, spherical_rotate, spherical_sobel
spherical-image-processing-slic	Stable	panorai.image_processing	panorai-spherical-slic/v1	spherical_slic
research-blenders	Experimental	panorai.blenders	panorai-research-blenders/v1	HuberNoConfidenceBlender, HuberSpatialBlender, BundleAdjustmentBlender, huber_no_confidence, huber_spatial, bundle_adjustment
spherical-core-numpy	Experimental	panorai.core.numpy	panorai-core-operations/v1	Module, Sequential, SphericalAreaMean, SphericalAreaSum, SphericalAvgPool2d, SphericalConv2d, SphericalConvTranspose2d, SphericalFilter2d, SphericalGaussianBlur2d, SphericalGradient, SphericalLaplacian, SphericalMaxPool2d, SphericalNeighborhoodMax, SphericalNeighborhoodMin, SphericalResize, SphericalScaleExtrema, native_filter_available, spherical_bilateral_filter, spherical_box_blur, spherical_filter2d, spherical_gaussian_blur, spherical_gradient, spherical_laplacian, spherical_median_blur, spherical_resize, spherical_rotate, spherical_sobel, spherical_solid_angle_weights
spherical-model-workflow-numpy	Experimental	panorai.workflow.numpy	panorai-spherical-model-workflow/v1	SphericalImageModule
spherical-ops-core	Stable	panorai.ops.spherical	panorai-spherical-ops/v1	AreaAverage, AreaHistogram, BilateralFilter, BoxBlur, Canny, Filter2D, GaussianBlur, Gradient, Laplacian, MedianBlur, Resample, Resize, Rotate, Sobel, GaussianPyramid, LaplacianPyramid, SphericalNMS, functional, area_average, area_histogram, bilateral_filter, box_blur, canny, filter2d, gaussian_blur, gradient, laplacian, median_blur, resample, resize, rotate, sobel, panorai.ops.spherical, panorai.ops.spherical.functional.area_average, panorai.ops.spherical.functional.area_histogram, panorai.ops.spherical.functional.bilateral_filter, panorai.ops.spherical.functional.box_blur, panorai.ops.spherical.functional.canny, panorai.ops.spherical.functional.filter2d, panorai.ops.spherical.functional.gaussian_blur, panorai.ops.spherical.functional.gradient, panorai.ops.spherical.functional.laplacian, panorai.ops.spherical.functional.median_blur, panorai.ops.spherical.functional.resample, panorai.ops.spherical.functional.resize, panorai.ops.spherical.functional.rotate, panorai.ops.spherical.functional.sobel
spherical-ops-morphology	Stable	panorai.ops.spherical	panorai-spherical-morphology/v1	Closing, Dilate, Erode, GeodesicDisk, Opening, closing, dilate, erode, opening, panorai.ops.spherical.functional.closing, panorai.ops.spherical.functional.dilate, panorai.ops.spherical.functional.erode, panorai.ops.spherical.functional.opening
spherical-ops-slic	Stable	panorai.ops.spherical	panorai-spherical-slic/v1	SLIC
spherical-ops-dog-detector	Experimental	panorai.ops.spherical	panorai-spherical-dog-detector/v2	DoGDetector
spherical-algorithms-general	Stable	panorai.ops.spherical	panorai-spherical-ops/v1	Canny, GaussianPyramid, LaplacianPyramid, SphericalNMS
spherical-algorithms-slic	Stable	panorai.ops.spherical	panorai-spherical-slic/v1	SLIC
spherical-algorithms-dog-detector	Experimental	panorai.ops.spherical	panorai-spherical-dog-detector/v2	DoGDetector
spherical-ops-auto-experimental	Experimental	panorai.ops.spherical	panorai-spherical-ops/auto-experimental	—

Surface	Stability	Canonical import	Contract	Public components or entries
spherical-internimage-portability	Experimental	panorai.experimental.deep_learning	panorai-spherical-internimage/v1	DenseInternImageOutput, InternImageGAssets, InternImageGDenseClassifier, InternImageShardSpec, InternImageTermsNotAcceptedError, LoadedInternImageG, SphericalDCNv3, SphericalDCNv3Record, SphericalInternImagePortReport, acquire_internimage_g, attention_pool_class_contributions, load_pretrained_internimage_g, port_internimage_to_spherical, spherical_dcnv3_core, panorai.experimental.deep_learning.internimage.SPHERICAL_INTERNIMAGE_INTERFACE, panorai.experimental.deep_learning.internimage.INTERNIMAGE_G_REPOSITORY, panorai.experimental.deep_learning.internimage.INTERNIMAGE_G_REVISION, panorai.experimental.deep_learning.internimage.INTERNIMAGE_G_SHARDS, panorai.experimental.deep_learning.internimage.DenseInternImageOutput, panorai.experimental.deep_learning.internimage.InternImageGAssets, panorai.experimental.deep_learning.internimage.InternImageGDenseClassifier, panorai.experimental.deep_learning.internimage.InternImageShardSpec, panorai.experimental.deep_learning.internimage.InternImageTermsNotAcceptedError, panorai.experimental.deep_learning.internimage.LoadedInternImageG, panorai.experimental.deep_learning.internimage.SphericalDCNv3, panorai.experimental.deep_learning.internimage.SphericalDCNv3Record, panorai.experimental.deep_learning.internimage.SphericalInternImagePortReport, panorai.experimental.deep_learning.internimage.acquire_internimage_g, panorai.experimental.deep_learning.internimage.attention_pool_class_contributions, panorai.experimental.deep_learning.internimage.load_pretrained_internimage_g, panorai.experimental.deep_learning.internimage.port_internimage_to_spherical, panorai.experimental.deep_learning.internimage.spherical_dcnv3_core
deep-learning-support	Experimental	panorai.experimental.deep_learning	panorai-deep-learning-support/v1-experimental	DA3Assets, DA3METRIC_LARGE, DA3TermsNotAcceptedError, DA3_CANONICAL_FOCAL_PX, DA3_CHECKPOINT_REVISION, DA3_MODEL_ID, DA3_PATCH_SIZE, DA3_SOURCE, DA3_SOURCE_COMMIT, DenseFCNOutput, DenseSemanticEvidence, ExternalArtifactRecord, ExternalArtifactSpec, IMAGENET_PROXY_VOCABULARY, INTERNIMAGE_G_REPOSITORY, INTERNIMAGE_G_REVISION, INTERNIMAGE_G_SHARDS, ImageNetFCN, ImageNetWeightRecord, LoadedDA3MetricModel, LoadedImageNetModel, LoadedSphericalDepthModel, METRIC3D_CHECKPOINT_REVISION, METRIC3D_CONVNEXT_LARGE_V1, METRIC3D_CONVNEXT_TINY_V1, METRIC3D_SOURCE, METRIC3D_SOURCE_COMMIT, Metric3DAssets, PortedLayer, SPHERICAL_DA3_METRIC_DEPTH_INTERFACE, SPHERICAL_INTERNIMAGE_INTERFACE, SPHERICAL_METRIC_DEPTH_INTERFACE, SPHERICAL_PROXY_SEGMENTATION_INTERFACE, SPHERICAL_SEMANTIC_SEGMENTATION_INTERFACE, SPHERICAL_TORCH_CONVOLUTION_INTERFACE, SUPPORTED_IMAGENET_MODELS, Sam21Assets, Sam21HieraLargeSegmenter, Sam21TermsNotAcceptedError, SemanticProxyConcept, SphericalBinaryMask, SphericalConv2d, SphericalConvTranspose2d, SphericalResizeConv2d, SphericalMaskProposal, SphericalMaskProposalSet, SphericalMaxPool2d, SphericalPortReport, SphericalProxySegmenter, SphericalSeed, SphericalSegment, SphericalSegmentationConfig, SphericalSegmentationResult, SphericalSemanticSegmenter, UpstreamTermsNotAcceptedError, acquire_metric3d_convnext_large_v1, acquire_sam21_hiera_large, class_activation_map, concept_evidence_from_imagenet, fibonacci_coverage_seeds, load_pretrained_imagenet_model, load_sam21_hiera_large, load_spherical_metric3d_convnext_large_v1, merge_proposals, port_module, port_module_with_report, prefetch_imagenet_weights, resolve_panoptic_map, select_semantic_seeds, spherical_area_average, sphericalize, mask_rcnn, panorai.experimental.deep_learning.pretrained.SUPPORTED_IMAGENET_MODELS, panorai.experimental.deep_learning.pretrained.ImageNetWeightRecord, panorai.experimental.deep_learning.pretrained.LoadedImageNetModel, panorai.experimental.deep_learning.pretrained.load_pretrained_imagenet_model, panorai.experimental.deep_learning.pretrained.prefetch_imagenet_weights
spherical-core-torch	Stable	panorai.core.torch	panorai-core-operations/v1	SPHERICAL_TORCH_CONVOLUTION_INTERFACE, PortedLayer, Sequential, SphericalAreaMean, SphericalAreaSum, SphericalAvgPool2d, SphericalConv2d, SphericalConvTranspose2d, SphericalResizeConv2d, SphericalFilter2d, SphericalGaussianBlur2d, SphericalGradient, SphericalLaplacian, SphericalMaxPool2d, SphericalNeighborhoodMax, SphericalNeighborhoodMin, SphericalPortReport, SphericalResize, SphericalScaleExtrema, port_module, port_module_with_report, spherical_area_average, panorai.core.torch.porting.PortedLayer, panorai.core.torch.porting.SphericalPortReport, panorai.core.torch.porting.port_module, panorai.core.torch.porting.port_module_with_report, panorai.image_processing.torch.SPHERICAL_TORCH_CONVOLUTION_INTERFACE, panorai.image_processing.torch.PortedLayer, panorai.image_processing.torch.Sequential, panorai.image_processing.torch.SphericalAreaMean, panorai.image_processing.torch.SphericalAreaSum, panorai.image_processing.torch.SphericalAvgPool2d, panorai.image_processing.torch.SphericalConv2d, panorai.image_processing.torch.SphericalConvTranspose2d, panorai.image_processing.torch.SphericalResizeConv2d, panorai.image_processing.torch.SphericalFilter2d, panorai.image_processing.torch.SphericalGaussianBlur2d, panorai.image_processing.torch.SphericalGradient, panorai.image_processing.torch.SphericalLaplacian, panorai.image_processing.torch.SphericalMaxPool2d, panorai.image_processing.torch.SphericalNeighborhoodMax, panorai.image_processing.torch.SphericalNeighborhoodMin, panorai.image_processing.torch.SphericalPortReport, panorai.image_processing.torch.SphericalResize, panorai.image_processing.torch.SphericalScaleExtrema, panorai.image_processing.torch.port_module, panorai.image_processing.torch.port_module_with_report, panorai.image_processing.torch.spherical_area_average
spherical-model-workflow-torch	Experimental	panorai.workflow.torch	panorai-spherical-model-workflow/v1	SphericalImageModule
spherical-ops-torch	Stable	panorai.ops.spherical.nn	panorai-spherical-ops-torch/v1	AdaptiveAvgPool2d, AvgPool2d, Closing, Conv2d, ConvTranspose2d, Dilate, Erode, GlobalAveragePool, Interpolate, MaxPool2d, Opening, PlanarSpatialOperationError, Resize, Rotate, SphericalConv2d, SphericalConvTranspose2d, SphericalMaxPool2d, SphericalValidationReport, ValidatedLayer, from_planar, execute_with_masks, spherical_area_average, transform_grid, transform_mask, validate

NumPy operations

panorai.ops.spherical.functional contains direct functions. Matching immutable objects are exported from panorai.ops.spherical. Algorithms are SLIC, DoGDetector, SphericalNMS, Canny, GaussianPyramid and LaplacianPyramid.

The general NumPy operations are Stable as panorai-spherical-ops/v1. GeodesicDisk, Dilate, Erode, Opening, Closing and their lower-case function forms are separately Stable as panorai-spherical-morphology/v1. They accept boolean or scalar floating ERP rasters, use nearest sampling, preserve the grid and propagate support and validity strictly. Integer labels and untyped NumPy HWC vectors fail explicitly because neither has a canonical max/min ordering. The Torch NCHW form treats channels as independent scalar fields. SLIC is separately Stable as panorai-spherical-slic/v1. DoGDetector and the mixed algorithms gateway remain Experimental; the direct imports of the other listed general operations retain the Stable contract.

Region analysis

The Stable panorai-spherical-region-analysis/v1 surface provides connected_components, geodesic_distance_transform, region_boundaries, fill_holes, marker-controlled watershed, measure_regions, region_adjacency_graph, extract_boundaries, trace_contours and skeletonize. Reusable one-input forms are ConnectedComponents, GeodesicDistanceTransform, RegionBoundaries, FillHoles and Skeletonize.

See the region-analysis concept and how-to guide.

panorai.ops.spherical.connected_components(mask, *, support=None, validity=None, connectivity=8)

Label a boolean ERP using longitude-periodic 4- or 8-connectivity.

Zero is background. Positive components are ordered by their first ERP raster index. Unsupported or invalid pixels remain zero and never connect otherwise separate regions.

panorai.ops.spherical.geodesic_distance_transform(mask, *, target=True, support=None, validity=None, units='degrees')

Distance from every valid ERP centre to the nearest selected centre.

panorai.ops.spherical.region_boundaries(values, *, support=None, validity=None, connectivity=4, include_support_boundary=False)

Return inner boundary pixels for a boolean mask or positive labels.

panorai.ops.spherical.fill_holes(mask, *, max_hole_solid_angle_sr, support=None, validity=None, connectivity=8)

Fill small background components that do not touch missing data.

A sphere has no distinguished exterior. Therefore the maximum solid angle is mandatory and defines which closed background components count as holes. Components adjacent to unsupported or invalid pixels are preserved.

panorai.ops.spherical.watershed(gradient, markers, *, support=None, validity=None, connectivity=8)

Deterministic marker-controlled minimax watershed on the ERP graph.

Flooding minimizes the maximum gradient encountered along a path from a marker, then path length. Remaining equal-cost conflicts select the smaller positive marker label. Marker pixels remain fixed.

panorai.ops.spherical.measure_regions(labels, *, support=None, validity=None)

Measure positive ERP labels using solid angle and angular geometry.

panorai.ops.spherical.region_adjacency_graph(labels, *, support=None, validity=None)

Return positive-label contacts and shared angular boundary lengths.

panorai.ops.spherical.extract_boundaries(labels, *, support=None, validity=None)

Lift each label’s inner boundary pixel centres to unit bearings.

panorai.ops.spherical.trace_contours(labels, *, support=None, validity=None, include_support_boundary=False)

Trace ordered sub-pixel contours along canonical ERP cell interfaces.

Longitude is periodic and all cell corners on either polar edge are one spherical vertex. The returned vertices therefore remain ordered across the displayed ERP seam without inventing a latitude wrap. Boundaries adjacent to missing support or invalid data are omitted by default, which yields honest open contours; callers may include those interfaces explicitly with include_support_boundary=True.

panorai.ops.spherical.skeletonize(mask, *, support=None, validity=None, minimum_radius_deg=0.0, connectivity=8)

Return deterministic ridges of the intrinsic distance-to-background.

The result is a sampled spherical medial axis. A centre is retained when it is a strict local ridge across at least one opposite neighbour pair. Distances are exact great-circle angles between ERP pixel centres; this is not a planar row/column thinning pass. Missing support and invalid data are absent domain vertices and are never crossed. A region filling its entire supported domain has no observable background and is rejected.

class panorai.ops.spherical.ConnectedComponents(connectivity=8)

Configured longitude-periodic connected-component operation.

class panorai.ops.spherical.GeodesicDistanceTransform(target=True, units='degrees')

Configured exact pixel-centre great-circle distance transform.

class panorai.ops.spherical.RegionBoundaries(connectivity=4, include_support_boundary=False)

Configured inner-boundary extraction operation.

class panorai.ops.spherical.FillHoles(max_hole_solid_angle_sr, connectivity=8)

Configured solid-angle-bounded hole filling.

class panorai.ops.spherical.Skeletonize(minimum_radius_deg=0.0, connectivity=8)

Configured intrinsic distance-ridge skeleton operation.

Torch operations

The optional, Stable panorai.ops.spherical.nn namespace provides Conv2d, ConvTranspose2d, MaxPool2d, AvgPool2d, AdaptiveAvgPool2d, GlobalAveragePool, Resize, Rotate, Interpolate, from_planar and validate. It also provides Dilate, Erode, Opening and Closing for floating NCHW tensors. Importing the NumPy or Pipeline namespaces does not require Torch. The Stable device contract covers CPU float32 and float64; CUDA and MPS may work through Torch but remain outside the compatibility guarantee until each has an independently reproduced matrix.

See Spherical morphology for the geodesic footprint and algebraic contract, then run the mask-cleaning tutorial.

Validation is deliberately fail-closed. Conventional planar spatial layers, unknown leaves, custom containers with opaque forward semantics, and functional spatial calls that cannot be inspected are rejected. Use nn.Sequential with declared spherical layers, or implement explicit grid and mask transforms at the Pipeline boundary. Custom pointwise modules require the trusted spherical_semantics="pointwise" declaration during Pipeline registration. Forward hooks are rejected, and runtime mask-shape checks prevent an explicitly declared module from silently changing the spatial lattice.

Mask R-CNN roles

panorai.experimental.deep_learning.mask_rcnn exposes Backbone, ProposalGenerator/RPN, RoIAlign, BoxHead, MaskHead and RoIHeads records, paper() for the executable CAM/SAM method, and the deliberately unbound SphericalMaskRCNN trainable topology.