Pipeline Stages catalog

A Stage is the smallest named transformation understood by panorai.pipeline.Pipeline. Public Stages implement execute(value) and return StageResult(value, details). They can be called through a one-step Pipeline, nested inside another Pipeline, or composed into an Application.

Registered Stage surfaces

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	—

Stable composition Stages

Core Stages from panorai.pipeline

Stage or factory	Input	Output	Domain	Purpose
OnSphere	ERP or selected ERP field	ERP, RasterField, or declared non-raster result	direct sphere	Run a registered spherical operation or validated Torch module while transforming grid and masks.
SampleViews	EquirectangularImage	GnomonicFaceSet	ERP → views	Sample cube, Fibonacci, icosphere or declared rotated views.
PerView	GnomonicFaceSet	face set or per-view result	views	Apply one planar callable independently to each selected view field.
PerView.parallel(...)	GnomonicFaceSet	mixed ResultBundle	views	Run named logical branches, optionally batched; no thread-level parallelism is promised.
ReconstructERP	face set or bundle containing views	ERP or bundle with reconstructed raster fields	views → ERP	Fuse selected raster modalities and preserve non-raster branches.
LiftToBearings	point, region or view observations	spherical observations	views → sphere	Lift non-raster evidence without pretending it is an ERP raster.
AggregateViews	per-view scores or embeddings	aggregated view evidence	spherical support	Reduce view evidence with an explicit coverage-aware reducer.
Parallel	any value accepted by every branch	ResultBundle	logical routing	Evaluate named branches against the same input in declaration order.
Select	nested bundle or typed object	selected value	logical routing	Select a dotted path such as views.depth or erp.labels.
Attach	bundle containing compatible raster data	object or bundle with attached field	logical routing	Attach only grid-compatible fields; reduced lattices require explicit regridding.

Output is a declaration used by OnSphere and PerView; it is not an execution Stage. It gives a callable result an explicit kind, units and invalid-data policy.

Experimental relative-pose Stages

Reusable image-to-pose Stages

Canonical import	Input	Output	Responsibility
panorai.applications.AssessRelativePoseCapture	RelativePoseCaptureInput	contained SphericalImagePair	Apply an explicit pre-estimation eligibility policy and retain the tri-state assessment.
panorai.features.ExtractSphericalFeaturePair	SphericalImagePair	SphericalFeaturePair	Extract features independently with the selected spherical frontend.
panorai.features.MatchSphericalFeatures	SphericalFeaturePair	SphericalFeatureMatches	Match the ordered reference/source feature sets.
panorai.features.ToBearingCorrespondences	SphericalFeatureMatches	SphericalBearingCorrespondences	Convert valid matches to weighted panorama-frame unit bearings.
panorai.estimators.EstimateRelativePose	matches or bearing correspondences	RelativePoseResult or None	Apply one configured estimator, sampler and acceptance policy.

The complete composition is exposed by SphericalRelativePose.as_pipeline(). The pose convention is always source-from-reference and translation is a unit direction, not metric scale.

Experimental registration and stitching Stages

Reusable central-rotation panorama Stages

Stage	Input	Output	Responsibility
panorai.stitching.DetectStitchingFeatures	StitchingInput	StitchingFeatures	Extract masked SIFT or ORB evidence independently from every source.
panorai.stitching.DiscoverOverlaps	StitchingFeatures	StitchingMatches	Form candidate image pairs using symmetric descriptor matching.
panorai.stitching.CalibrateAndRegister	StitchingMatches	RegisteredImageSet	Robustly validate homographies, estimate missing shared FOV, recover pairwise SO(3) rotations and optimize one connected orientation graph.
panorai.stitching.WarpRegisteredImages	RegisteredImageSet	WarpedImageSet	Warp values, support and validity independently to one ERP lattice.
panorai.stitching.CompensateExposure	WarpedImageSet	WarpedImageSet	Estimate optional global positive scalar gains from valid overlap.
panorai.stitching.BlendStitchingPanorama	WarpedImageSet	PanoramaStitchingResult	Average or feather valid contributions and retain diagnostics.

These Stages implement the Experimental central rotation-only profile. They do not imply translation, lens-distortion calibration, seam optimization or multi-band blending. See the stitching guide.

Experimental dense-reconstruction Stages

BuildRegisteredReferenceSets derives every source-from-reference pose from one registered metric scene. EstimateMultiViewRanges reuses FullSphereMultiViewStereo once per reference. FuseTSDF accepts either the resulting workspace or an externally produced MultiViewRangeSet; ExtractSurface, ColorizeSurface and ValidateDenseReconstruction complete the route. Unknown TSDF voxels keep weight zero, and the validator returns an auditable rejected result for scientific insufficiency rather than a fabricated surface.

Stable region-analysis Stages

SphericalWatershed reads named floating-gradient and integer-marker fields from one ERP and returns a typed label RasterField. AnalyzeRegions reads a label field and returns RegionAnalysisResult with measurements, adjacency, optional boundary samples and optional ordered contours. Both retain explicit grid, support and validity and are safe registered Pipeline components.

Experimental semantic-instance Stages

CAM/SAM and instance-fusion Stages from panorai.pipeline

Stage	Input	Output	Responsibility
SphericalCAM	ERP	CAMEvidenceFrame	Produce spherical class-evidence maps from a configured CAM adapter.
CAMRegionProposals	CAM evidence	CAMRegionProposalSet	Turn evidence into angular region proposals.
SAMMaskRefinement	proposal set	SAMMaskProposalBatch	Refine proposals with an explicitly supplied SAM adapter.
SphericalInstanceFusion	refined mask proposals	spherical segmentation result	Fuse masks with spherical support and overlap semantics.
CAMGuidedSphericalInstances	CAM evidence and configured SAM adapter	spherical segmentation result	Convenience composition of proposal, refinement and fusion Stages.

These Stages do not download checkpoints and remain Experimental. The trainable SphericalMaskRCNN topology is a different, deliberately unbound surface.

See Pipeline API for signatures and typed composition for the Stage contract.