Applications API

Application stability is assigned per concrete wrapper and, where explicitly inventoried, per named profile factory. SphericalSLIC is Stable as panorai-spherical-slic/v1. SphericalDoGFeatures.reviewed_profile() is an immutable promotion candidate, but remains Experimental until its frozen external, installed-wheel and independent-review gates pass. The generic DoG, Stereo, Relative Pose, Dense Reconstruction, Mask R-CNN Workflow and Panorama Stitcher wrappers remain Experimental.

Surface	Stability	Canonical import	Contract	Public components or entries
panorama-stitching-application	Experimental	panorai.applications	panorai-panorama-stitching/v1-experimental	PanoramaStitcher
registered-full-sphere-stereo-application	Experimental	panorai.applications	panorai-registered-full-sphere-stereo/v1-experimental	FullSphereDenseStereo
spherical-applications-dog-reviewed-profile	Experimental	panorai.applications	panorai-spherical-dog-features/v1	SphericalDoGFeatures.reviewed_profile
spherical-applications	Experimental	panorai.applications	panorai-application/v1-experimental	Application, ApplicationConfigurationError, ADCensusStereoDepth, AssessRelativePoseCapture, CensusMGMStereoDepth, ELASStereoDepth, PipelineApplication, PatchMatchStereoDepth, PanoramicDenseStereo, InstanceHeuristicDecision, RelativePoseCaptureAssessment, RelativePoseCaptureError, RelativePoseCaptureInput, RelativePoseCaptureMetadata, RelativePoseCapturePolicy, RelativePoseProfile, SphericalDenseReconstruction, SphericalDoGFeatures, SphericalMaskRCNNPaper, SphericalMaskRCNNWorkflow, SphericalRelativePose, SphericalStereoDepth, SphericalStereoInput, StereoBMDepth, StereoSGBMDepth
spherical-applications-slic	Stable	panorai.applications	panorai-spherical-slic/v1	SphericalSLIC
spherical-applications-auto-experimental	Experimental	panorai.applications	panorai-application/auto-experimental	—

Use the Applications catalog to compare natural inputs, outputs, execution domains and the Pipeline exposed by every wrapper. This page documents exact classes and methods.

Stable application

class panorai.applications.SphericalSLIC(n_segments=100, compactness=10.0, max_num_iter=10, convergence_tol_deg=0.001, enforce_connectivity=True, min_size_factor=0.5, start_label=1)

Segment an ERP into intrinsic, seam-periodic spherical superpixels.

as_pipeline()

Build the equivalent low-level pipeline.

describe()

Return a JSON-friendly public contract description.

run(panorama, *, validity_mask=None)

Execute the application.

to_config()

Return a safe registered application configuration.

Common Experimental contracts

class panorai.applications.Application

Public high-level application contract with immutable configuration.

abstractmethod describe()

Return a JSON-friendly public contract description.

abstractmethod run(*args, **kwargs)

Execute the application.

abstractmethod to_config()

Return a safe registered application configuration.

class panorai.applications.PipelineApplication

Application whose public behavior is expressible as a Pipeline.

abstractmethod as_pipeline()

Build the equivalent low-level pipeline.

Experimental wrappers

class panorai.applications.SphericalDoGFeatures(config=SphericalDoGSIFTConfig(octaves=3, levels_per_octave=3, base_sigma_px=1.6, contrast_threshold=0.012, edge_threshold=10.0, max_features=1000, patch_size=48, descriptor_radius_sigmas=6.0, minimum_valid_fraction=0.99, minimum_valid_support_fraction=0.99, angular_dedup_threshold_deg=0.12, scale_dedup_log2=0.5, selection_policy='equal-area-round-robin', selection_grid_shape=(12, 24), descriptor_config=OpenCVTangentDescriptorV2Config(method='sift', keypoint_diameter_in_scales=1.25, scale_multipliers=(1.0,), orientation_policy='fixed-zero', orientation_bins=36, orientation_peak_ratio=0.8, max_orientations=2, photometric_normalization='local-standardization', minimum_descriptor_valid_fraction=0.99, root_sift=True, algorithm_parameters=(), minimum_opencv_version='4.9.0'), convolution_backend='auto'))

Detect spherical DoG keypoints and compute tangent-patch descriptors.

as_pipeline()

Build the equivalent low-level pipeline.

describe()

Return a JSON-friendly public contract description.

classmethod reviewed_profile(*, convolution_backend='auto')

Build the fixed candidate profile without promoting generic DoG.

The returned object is deliberately still Experimental until the protocol-bound external holdout, installed-artifact matrix and independent review all pass. A later tier-only change may promote this exact identity without making free-form configurations Stable.

run(panorama, *, panorama_id=None, validity_mask=None)

Execute the application.

to_config()

Return a safe registered application configuration.

class panorai.applications.SphericalStereoDepth(options=SphericalStereoOptions(min_range=0.3, max_range=12.0, num_hypotheses=96, window_size=7, pole_margin_fraction=0.04, min_texture_std=0.015, min_confidence=0.015, max_matching_cost=0.65, intensity_weight=0.75, gradient_weight=0.25, smoothness_penalty_small=0.02, smoothness_penalty_large=0.1, bidirectional_consistency=True, consistency_relative_tolerance=0.05, consistency_absolute_tolerance=0.05, filter_backend='auto', pyramid_levels=1, refinement_hypotheses=9, refinement_radius_steps=4.0))

Estimate radial range from two calibrated central ERPs.

as_pipeline()

Build the equivalent low-level pipeline.

describe()

Return a JSON-friendly public contract description.

run(reference, source, rotation_source_from_reference, translation_source_from_reference)

Execute the application.

class panorai.applications.SphericalRelativePose(frontend_config=None, options=<factory>, sampler=<factory>, quality_policy=<factory>, profile=None, capture_policy=None, capture_mode='enforce')

Estimate spherical Essential, rotation, and translation direction.

By default the image frontend calls SphericalFeaturePipeline.for_relative_pose() exactly. Passing a frontend_config explicitly selects a custom extraction/matching configuration. The result never claims metric translation scale.

as_pipeline()

Build the equivalent low-level pipeline.

assess_capture(metadata, *, policy=None)

Assess capture facts without extracting features or estimating pose.

describe()

Return a JSON-friendly public contract description.

estimate_correspondences(correspondences)

Estimate pose from precomputed weighted bearing correspondences.

estimate_matches(matches)

Estimate pose from already matched panorama-frame features.

classmethod from_profile(profile, *, capture_policy=None, capture_mode='enforce')

Construct an application from an inspectable computation profile.

classmethod reference(*, capture_policy=None, capture_mode='enforce')

Construct the named evidence-backed v1 computation profile.

run(reference, source, *, reference_id=None, source_id=None, reference_validity=None, source_validity=None, capture_metadata=None)

Execute the application.

class panorai.applications.SphericalDenseReconstruction(*, voxel_size, bounds=None, mvs_options=FullSphereStereoOptions(planner=OverlappingCubemapPlanner(face_size=128, face_fov_deg=100.0), stereo=SphericalStereoOptions(min_range=0.3, max_range=12.0, num_hypotheses=96, window_size=7, pole_margin_fraction=0.0, min_texture_std=0.015, min_confidence=0.015, max_matching_cost=0.65, intensity_weight=0.75, gradient_weight=0.25, smoothness_penalty_small=0.02, smoothness_penalty_large=0.1, bidirectional_consistency=False, consistency_relative_tolerance=0.05, consistency_absolute_tolerance=0.05, filter_backend='auto', pyramid_levels=1, refinement_hypotheses=9, refinement_radius_steps=4.0), min_parallax_deg=0.25, min_source_evidence=1, max_sources_per_hypothesis=None, source_aggregation='median', matching_cost='ad-census', local_aggregation='box', regularizer='sgm4', census_radius=2, ad_weight=0.25, census_weight=0.75, ad_truncation=0.2, erp_feature_tap_deg=0.703125, face_cost_tap_deg=1.0667900072919114, range_consensus_tolerance_steps=2, min_range_consensus_sources=0), truncation_distance=None, max_voxels=8000000, chunk_voxels=262144, min_surface_views=2, min_valid_weight=1.0, weighting='uniform', colorize=True, retain_intermediates='ranges', profile_id=None)

Reconstruct a world-frame surface from registered metric ERPs.

The application is Experimental. reviewed_profile freezes the intended future Stable subset, but does not itself claim Stable maturity.

as_pipeline()

Build the equivalent low-level pipeline.

describe()

Return a JSON-friendly public contract description.

classmethod reviewed_profile(*, voxel_size, bounds=None, filter_backend='auto')

Build the frozen candidate profile; external promotion gates remain open.

run(scene)

Execute the application.

to_config()

Return a safe registered application configuration.

class panorai.applications.RelativePoseProfile(profile_id, frontend_config, options, sampler, quality_policy, evidence_scope)

Complete, named configuration of the relative-pose computation.

Capture eligibility is intentionally not part of this object: it is an independent pre-estimation policy with different evidence and inputs.

classmethod evidence_backed_v1()

Return the frozen frontend plus selected MSAC/refit estimator.

class panorai.applications.RelativePoseCaptureMetadata(registered_cloud_overlap_min=None, baseline_m=None, representative_scene_distance_m=None, predicted_parallax_deg=None, capture_rate_hz=None, step_translation_m=None, step_rotation_deg=None)

Operator-visible facts about one ordered two-panorama capture.

These values are not inferred from RGB pixels. Registered-cloud overlap requires independently registered depth support; metric baseline and scene distance require an external metric source. Missing information remains None rather than being replaced by a numeric sentinel.

property baseline_depth_ratio

Return baseline / representative distance when both are known.

class panorai.applications.RelativePoseCapturePolicy(minimum_registered_overlap=0.5, preferred_registered_overlap=0.7, metric_baseline_interval_m=None, minimum_capture_rate_hz=None, target_max_step_translation_m=None, target_max_step_rotation_deg=None, maximum_step_translation_m=None, maximum_step_rotation_deg=None, profile_id='panorai-scanner-assisted-capture-v1-experimental', evidence_scope='retrospective public indoor and separately governed industrial eligibility evidence; not a universal precision guarantee')

Evidence-backed eligibility limits, separate from pose acceptance.

The default profile represents the scanner-assisted multidataset evidence: 50% minimum bidirectional registered-cloud overlap and 70% preferred overlap. It is an eligibility rule, not a calibrated probability of pose correctness. The policy deliberately carries no universal metric-baseline interval because the measured Matterport interval did not transfer as a physical law.

assess(metadata)

Classify capture eligibility without running the pose estimator.

classmethod hilti_fisheye_development()

Return the explicitly development-only Hilti temporal envelope.

classmethod scanner_assisted_reference()

Return the multidataset registered-overlap eligibility profile.

class panorai.applications.RelativePoseCaptureAssessment(decision, profile_id, reasons, warnings, observed, preferred, evidence_scope)

Auditable capture decision made before feature extraction.

class panorai.applications.RelativePoseCaptureInput(pair, metadata)

A spherical image pair plus independently supplied capture metadata.

class panorai.applications.RelativePoseCaptureError(assessment)

Capture metadata failed an enforced eligibility policy.

class panorai.applications.AssessRelativePoseCapture(policy, mode='enforce')

Pipeline Stage that checks capture facts before feature extraction.

class panorai.applications.SphericalMaskRCNNWorkflow(proposal_mode, proposal, heuristic, num_classes, mask=None, concepts=(), reuse_proposal_masks=False, config=SphericalSegmentationConfig(semantic_peaks_per_concept=12, semantic_peak_separation_degrees=12.0, semantic_relative_threshold=0.3, coverage_direction_count=96, discovery_fov_degrees=70.0, discovery_face_size=1024, prompt_grid_size=8, prompt_batch_size=16, minimum_pairwise_iou=0.5, minimum_predicted_iou=0.7, minimum_stability=0.85, minimum_pixels=64, expansion_fov_degrees=30.0, expansion_step_fraction=0.65, expansion_frontier_band_pixels=32, expansion_frontier_minimum_pixels=128, expansion_prior_retention=0.8, maximum_expansion_faces=24, duplicate_iou=0.8, merge_iou=0.55, merge_containment=0.8, semantic_minimum_mean=0.25, semantic_minimum_contrast=0.05), cam_proposals=CAMRegionProposals(maximum_per_concept=12, minimum_separation_degrees=12.0, relative_threshold=0.3, minimum_score=0.25, fov_degrees=70.0, face_size=1024), output_shape_hw=None, expand=True)

Executable Mask R-CNN workflow bound to CAM/SAM/heuristics.

proposal_mode='cam' uses CAM only to choose spherical search regions; SAM refines the masks. proposal_mode='sam' lets SAM generate and reuse proposal masks. The BoxHead responsibility is fulfilled by an explicit abstaining instance heuristic, not advertised as a trained classifier.

as_pipeline()

Build the equivalent low-level pipeline.

describe()

Return a JSON-friendly public contract description.

run(panorama, *, support_mask=None, validity_mask=None)

Execute the application.

class panorai.applications.PanoramaStitcher(options=StitchingOptions(feature_method='sift', max_features=4000, ratio_test=0.75, min_pair_matches=20, min_pair_inliers=12, max_transfer_error_px=3.0, max_angular_error_deg=1.0, max_median_angular_error_deg=0.35, min_horizontal_fov_deg=30.0, max_horizontal_fov_deg=140.0, min_spatial_coverage=0.02, output_shape_hw=(512, 1024), interpolation='bilinear', exposure_compensation='gain', blend='feather', random_seed=0))

Register overlapping pinhole images and construct one partial ERP.

The first profile is deliberately narrow: every input is assumed to come from a central pinhole camera rotating about one optical centre. Missing horizontal field of view may be estimated only when the matched evidence makes it observable. Translation, strong parallax, rolling shutter and disconnected overlap groups fail explicitly instead of being hidden by a visually plausible warp.

as_pipeline()

Build the equivalent low-level pipeline.

describe()

Return a JSON-friendly public contract description.

run(images, *, image_ids=None, support_masks=None, validity_masks=None, horizontal_fov_deg=None)

Execute the application.

to_config()

Return a safe registered application configuration.

SphericalMaskRCNNPaper is the compatibility alias for the original Experimental name. New code should use SphericalMaskRCNNWorkflow and mask_rcnn.workflow().

Start with the Applications tutorial and read Application wrappers for the contract rationale.