Pipeline API

The generic Stage, typed-result, grid, routing, persistence and cache core is Stable as panorai-spherical-pipeline/v1. CAM/SAM proposal and instance stages exported by the namespace remain Experimental.

Surface	Stability	Canonical import	Contract	Public components or entries
spherical-region-analysis-pipeline	Stable	panorai.pipeline	panorai-spherical-region-analysis/v1	AnalyzeRegions, SphericalWatershed
spherical-model-workflow	Experimental	panorai.workflow	panorai-spherical-model-workflow/v1	SPHERICAL_MODEL_WORKFLOW_INTERFACE, AggregatedViewEvidence, EquirectangularImage, FacePointBatch, FaceRegionBatch, FaceViewOutput, GnomonicFace, GnomonicFaceSet, ObservationFusionResult, RasterFieldResult, RasterFieldSpec, SphericalBinaryMask, SphericalInputSpec, SphericalOutputSpec, SphericalOutputTree, SphericalPointObservation, SphericalPointSet, SphericalRegionObservation, SphericalRegionSet, SphericalViewObservation, SphericalViewSet
panorama-stitching-stages	Experimental	panorai.stitching	panorai-panorama-stitching/v1-experimental	BlendStitchingPanorama, CalibrateAndRegister, CompensateExposure, DetectStitchingFeatures, DiscoverOverlaps, StitchingRegistrationError, WarpRegisteredImages
spherical-pipeline-core	Stable	panorai.pipeline	panorai-spherical-pipeline/v1	AggregateViews, Attach, ClassificationResult, EmbeddingResult, LiftToBearings, OnSphere, Output, Parallel, PerView, PerViewResults, Pipeline, PipelineCacheError, PipelineRun, PipelineSerializationError, RasterField, RasterGrid, ReconstructERP, ResultBundle, SampleViews, Select, SphericalObservations, StageRecord, Stage, StageResult, ViewObservations, ViewResult, registered_pipeline_components, register_torch_module, registered_torch_modules
spherical-pipeline-semantic-instances	Experimental	panorai.pipeline	panorai-spherical-instance-pipeline/v1-experimental	CAMEvidenceFrame, CAMGuidedSphericalInstances, CAMRegionProposal, CAMRegionProposalSet, CAMRegionProposals, SAMMaskProposalBatch, SAMMaskRefinement, SphericalCAM, SphericalInstanceFusion
spherical-pipeline-root-convenience	Stable	panorai.pipeline	panorai-spherical-pipeline/v1	Pipeline, PipelineRun, Stage, StageResult, RasterField, ResultBundle, ClassificationResult, EmbeddingResult, SphericalObservations, OnSphere, Output, Parallel, SampleViews, PerView, ReconstructERP, Select, Attach, LiftToBearings, AggregateViews
spherical-pipeline-auto-experimental	Experimental	panorai.pipeline	panorai-spherical-pipeline/auto-experimental	—

Use the Stages catalog to choose by accepted input, produced output, execution domain and role. Use typed data and results for the values exchanged between Stages.

Composition

class panorai.pipeline.Pipeline(*steps, memory=None)

Compose sphere-native and projected-view stages linearly.

This Stable layer delegates all projections, per-view mapping and reconstruction to the existing Stable object workflow.

describe()

Return the static, JSON-friendly pipeline topology.

execute(value)

Execute this pipeline as one nestable public Stage.

classmethod from_config(config)

Construct a pipeline from a validated registered-component config.

classmethod load(directory)

Load and verify a registered-component pipeline archive.

run(value, *, retain=())

Execute and return provenance plus selected intermediate values.

save(directory, *, overwrite=False)

Write a checksum-verified JSON archive for registered components.

to_config()

Return a deterministic JSON-compatible registered-component config.

Arbitrary callables remain executable in memory but fail here with the exact parameter path. No pickle or dynamic import is used.

with_params(**params)

Return a new pipeline with selected stage parameters replaced.

class panorai.pipeline.Stage(*args, **kwargs)

A composable pipeline stage implemented through a public method.

Third-party stages only need to declare their input/output kinds and implement execute(). They do not inherit a PanorAi base class and never depend on a private executor hook.

execute(value)

Process value and return a typed execution result.

class panorai.pipeline.StageResult(value, details, grid=None)

Value and immutable execution metadata returned by a public stage.

grid is the spatial identity of the returned value when one exists. Non-spatial results use None. Stages may provide it explicitly; the constructor otherwise derives it from public raster fields and workflow containers.

class panorai.pipeline.PipelineRun

Immutable execution result containing output, retained values, ordered stage records and execution metadata. describe() and manifest() return JSON-friendly provenance.

Core stages

class panorai.pipeline.OnSphere(operation, output='image', input='image')

Execute a declared sphere-aware operation directly on an ERP and transform values, support, validity and grid identity together.

class panorai.pipeline.SampleViews(layout='cube', size=None, fov=90.0, count=None, subdivisions=0, rotations=(), depth_policy='propagate', min_valid_weight=None, projector=None)

Create canonical gnomonic views through EquirectangularImage.views.

class panorai.pipeline.PerView(operation, input=None, output=None, units=None, replace=False)

Apply one planar callable using the Stable GnomonicFaceSet.map.

classmethod parallel(*, input=None, replace=False, batch=None, max_batch_elements=16777216, **operations)

Build a logical multi-head stage over the same original views.

Branches execute sequentially in declaration order. Each branch sees the selected field from the input face set, rather than the output of a preceding branch.

class panorai.pipeline.ReconstructERP(blend=None, modalities='all', eq_shape=None, **field_blends)

Reconstruct selected view fields with the Stable workflow implementation.

class panorai.pipeline.LiftToBearings(require_footprint_valid=True)

Lift detector-neutral view geometry through canonical gnomonic rays.

class panorai.pipeline.AggregateViews(reducer='mean')

Aggregate per-view global results or spherical observations.

Stable region-analysis stages

class panorai.pipeline.SphericalWatershed(gradient='features', markers='labels', output='labels', connectivity=8)

Partition an ERP from named gradient and marker fields.

class panorai.pipeline.AnalyzeRegions(input='labels', include_boundaries=True, include_contours=False)

Convert a named ERP label field into typed region evidence.

Sparse relative-pose stages

The Experimental image-to-pose composition uses panorai.applications.AssessRelativePoseCapture when an explicit capture policy is configured, followed by panorai.features.ExtractSphericalFeaturePair, panorai.features.MatchSphericalFeatures, panorai.features.ToBearingCorrespondences and panorai.estimators.EstimateRelativePose. These stages preserve the ordered source-from-reference convention and return unit translation direction, not metric scale. They reuse the Stable Pipeline protocol but retain the Experimental status of relative pose.

The capture Stage consumes RelativePoseCaptureInput and returns the contained SphericalImagePair. In enforcing mode, ineligible or unsupported metadata stops the pipeline before feature extraction. In advisory mode, the same tri-state assessment is retained in the Stage record without claiming that capture eligibility guarantees pose correctness.

Routing

class panorai.pipeline.Parallel(**branches)

Run independent logical branches sequentially on the same input.

The name describes topology, not concurrency. None is an explicit identity branch and is useful as an attachment target.

class panorai.pipeline.Select(path)

Select one branch or typed raster field by a dotted path.

class panorai.pipeline.Attach(*, target, replace=False, **fields)

Attach compatible typed branch fields to one target branch.

Example:

Attach(target="base", depth="prediction.depth")

Typed values

class panorai.pipeline.Output(operation, kind=None, units=None, invalid_policy='propagate', min_valid_weight=None)

Declare the typed raster or non-raster semantics of an operation.

class panorai.pipeline.RasterGrid(domain, shape_hw, erp_shape_hw, alignment, view_ids=(), view_specs=(), first_center_px_yx=None, pixel_stride_yx=None, angular_stride_rad=None, longitude_periodic=None, transforms=())

Explicit spatial identity for one ERP, view, or derived raster lattice.

Pixel coordinates are expressed in the reference ERP lattice and identify pixel centres, not pixel corners. A derived lattice therefore retains the first sampled centre and stride instead of masquerading as a smaller ERP. angular_stride_rad is (latitude, longitude); it is unavailable for gnomonic view grids because their angular spacing is not uniform.

class panorai.pipeline.RasterField(name, values, kind, support, validity, grid, units=None, invalid_policy='propagate')

A raster with explicit semantics, support, validity, and grid identity.

values is one array/tensor for ERP or derived fields and a tuple in the exact face order for view fields. Support and validity remain independent.

class panorai.pipeline.ResultBundle(values, *, descriptions=None)

Immutable named results produced by logical pipeline branches.

class panorai.pipeline.ClassificationResult(value=None, *, items=(), source_field=None, erp_shape_hw=None)

Typed classification logits, scores, probabilities, or class id.

class panorai.pipeline.EmbeddingResult(value=None, *, items=(), source_field=None, erp_shape_hw=None)

Typed global or per-view embedding that preserves autograd in memory.

class panorai.pipeline.SphericalObservations(bearings_xyz, *, footprints_xyz, scores, support, data_validity, valid, source_face_ids, source_indices, source_pixels_xy, geometry, labels=None, features=None, metadata=())

Observations expressed as unit bearings in the panorama frame.

bearings_xyz contains one representative bearing per observation. footprints_xyz retains every point, box corner, or polygon vertex. Geometric support, source-data validity, and final observation validity remain separate arrays.

Start with the Pipeline tutorial and read Typed pipeline composition for the data model.