Stereo APIs

panorai.stereo is an Experimental direct matching surface for two same-shape central ERPs with known relative pose. It returns radial range in the translation unit together with explicit validity, cost, confidence, and the inverse-range hypothesis lattice.

Start with Tutorial: dense stereo from two spherical images. The full geometry, objective, four-path aggregation, refinement, consistency policy, complexity, and public validation limitations are derived in Direct spherical dense stereo: geometry and optimization.

The pose convention is

\[X_B = R_{BA} X_A + t_{BA}.\]

Supplying only a unit translation direction produces range in baseline units, not metres. Confidence is a best-versus-second-best separation on the current cost volume and is not a calibrated probability.

PanorAi also provides six Experimental non-learned baselines for an already-rectified pinhole pair under panorai.stereo.classical: StereoBM, AD-Census, StereoSGBM, Census + MGM/tMGM, an ELAS-style support prior, and PatchMatch Stereo. They are deliberately separate from the direct spherical estimator above. Use them after sampling and rectifying overlapping views, then return their dense fields through the object workflow.

The low-level classical surface follows Adding a public API component: matching costs, local aggregation and global optimization are reusable operations; domain-changing steps are public Stage objects; each complete baseline is an inspectable Pipeline; and panorai.applications supplies the task wrapper.

Start with Compare non-learned stereo pipelines for the common input, the six compositions, result semantics, and current validation limits.

For an A-to-Z workflow, use panorai.applications.PanoramicDenseStereo. It accepts two ERPs, optionally estimates relative pose, resolves metric or scale-free baseline, plans and streams paired rectified views, runs one of the classical matchers, and fuses radial range back into the reference ERP. See Run panoramic dense stereo from two ERPs.

panorai.applications.FullSphereDenseStereo extends the registered-pose case to an explicit RegisteredPanoramaSet containing one reference and multiple StereoSourceView relations. It streams an overlapping cube-oriented gnomonic atlas, evaluates radial hypotheses against every usable baseline and reports sampling support, stereo observability and accepted validity separately. A cubemap covers the raster sphere; only non-collinear baselines can cover the pairwise epipolar degeneracies. observable and observable_source_count depend only on source data support, parallax and the configured radial interval—not on Census/descriptor support or the range selected by the matcher. source_count records cost-valid evidence at that selected range. source_consensus_count is a separate per-pixel diagnostic; the optional minimum-consensus validity gate is disabled by default.

Stability boundary

The registered route has its own granular contract, panorai-registered-full-sphere-stereo/v1-experimental. It contains RegisteredPanoramaSet, StereoSourceView, PanoramicStereoPose, the full-sphere engine/result/options, and the panorai.applications.FullSphereDenseStereo facade. It does not include ResolveStereoPose or PanoramicDenseStereo.

FullSphereDenseStereo.reviewed_profile() constructs the exact profile frozen for prospective promotion evidence. describe() reports its profile identifier, pose_policy='provided-only', and any option family outside that profile. The profile remains Experimental until a new post-protocol held-out cohort, the installed-wheel platform matrix, streaming-memory evidence, and a distinct reviewer all pass. Confidence remains a within-result ranking score, not a calibrated probability.

FullSphereStereoOptions also separates the dense cost pipeline into matching_cost (intensity-gradient, ad-census or multiscale-ad-census), local_aggregation (none or box), and regularizer (none, sgm4 or tmgm). These stages run once, in that order, and are recorded in result diagnostics and serialized application configuration. The balanced default is reviewed ad-census + box + sgm4 with angular ERP and face taps. Explicit intensity-gradient and None tap values preserve the historical profile. This evidence-backed default does not make the full-sphere surface Stable.

multiscale-ad-census averages the reviewed angular AD-Census cost at one and two tap spacings before the same box aggregation and SGM4 stages. On a prospectively frozen, view-disjoint twelve-pair audit it improved fixed delta < 1.25 by 0.0039 on Stanford 2D-3D and 0.0054 on Matterport3D, reduced conditional gross error in both domains, lost at most 0.0052 aggregate coverage and cost 1.11x median paired runtime. All 24 numerical payloads and population masks reproduced exactly. The gain is real but small, so the single-scale reviewed default is unchanged and the multiscale cost remains an explicit Experimental option.

Panoramic fusion exposes matching_confidence and consistency_confidence separately. Face-edge taper affects radial-range fusion but is normalized out of matching confidence. Consistency is exp(-disagreement / radial_range) and the reported confidence is their product. These Experimental fields support diagnostics and within-result ranking; public multipair evidence rejects treating them as calibrated probabilities or applying one universal threshold.

A frozen public two-source audit excludes sky/no-return pixels and evaluates single-source, multibaseline, and strict-consensus routes on identical prediction-independent populations. Multibaseline aggregation improves fixed-population accuracy in five of six triplets, but strict two-source consensus retains only about 4% of Stanford and 10% of Matterport observable support. The result supports the multiview architecture while still rejecting Stable promotion of the current matcher and visibility policy.

A replayed weighted-mean source-cost ablation underperforms the existing lower median in both public domains. It is retained as an explicit policy, not promoted to the default; visibility-aware source selection remains an open promotion gate.

A fixed parameter-free confidence ablation also tested multiplying the reported score by half of one plus the fraction of source labels agreeing with the fused label. It slightly reduced top-quartile accuracy in both public domains and did not improve absolute-threshold transfer. The runtime confidence is therefore unchanged; source agreement remains a separate diagnostic rather than a calibrated probability.

An outcome-blind two-pass ablation then selected a fixed compatible source group from each source’s complete cost curve before recomputing the fused volume. It reduced Stanford gross outliers but reduced coverage and fixed- population accuracy in both domains, while Matterport gross outliers increased. The rejected policy is not a public option. Unary cost-curve sharpness is not a sufficient visibility or occlusion model.

A separately frozen three-source public protocol confirms that the existing true median reduces conditional gross-label outliers in both domains. It also reduces accepted coverage relative to two sources, so fixed-population accuracy does not improve overall. Requiring all three source costs yields almost the same result. The remaining gate is therefore a source-count-portable cost and acceptance scale, not merely another minimum-source switch.

These promotion metrics exclude sky/no-return with a prediction-independent positive finite dataset-range mask before applying geometric support and observability. Rejected predictions inside the remaining population are not silently removed from the fixed accuracy denominator.

A frozen acceptance-gate decomposition also shows that the current absolute matching-cost gate is inactive: disabling it changes none of sixty public two/three-source conditions. Removing the confidence gate recovers part of the third-source coverage loss, particularly on Matterport, while removing the texture gate raises absolute coverage but makes the source-count regression larger. No default changes. Per-reason rejection instrumentation and a prospectively specified source-count-aware confidence remain promotion gates.

FullSphereStereoResult.diagnostics includes a cumulative per-face acceptance audit. It reports counts after support, interior-label, finite-range, texture, confidence, cost, source-evidence, consensus, parallax and final acceptance predicates. Overlapping face samples remain separate by design; use the fixed non-sky ERP protocol—not these counts—for accuracy claims. Instrumented public replay preserved all prior output-array hashes and shows that boundary labels dominate the Stanford source-count loss while confidence dominates the Matterport loss.

Accepting endpoint winners as exact discrete ranges was evaluated prospectively and rejected. It raises coverage but slightly lowers fixed accuracy in both public domains and increases conditional gross error by more than the frozen tolerance. The candidate option is not exposed. Endpoint winners remain invalid rather than silently converting an out-of-range bound into a metric point estimate.

A second prospective protocol selected twelve entirely new public pairs before inference and compared the existing confidence threshold with report-only confidence on the same fixed non-sky populations. Report-only confidence improved coverage and fixed-population accuracy in both Stanford and Matterport, but Stanford conditional gross error regressed by 0.04386, above the frozen 0.04 limit. The result reproduced exactly, the candidate option was removed, and the threshold default is unchanged. Confidence remains a ranking score, not a calibrated probability; improving its cross-domain acceptance behavior is still a promotion gate.

Twelve additional view-disjoint public pairs prospectively compared the two available unary costs with box aggregation and SGM4 held fixed. AD-Census improved fixed-population accuracy in both domains, increased coverage, reduced Stanford gross error, stayed within the Matterport gross-error tolerance, and was faster in two complete runs. Numerical evidence and all 24 payloads reproduced exactly. A separate reviewer reproduced all numerical payloads, populations, metrics, and aggregates; the only raw-JSON difference was the additive angular-neighbourhood diagnostic introduced after the original run. AD-Census is therefore the integrated default for new option objects. Explicit intensity-gradient and old saved configurations retain historical behavior.

A subsequent development-only factorial on the previously observed VAL-098 pairs rejects resolution scaling as a free quality improvement. At a common 512x1024 evaluation grid, doubling the inverse-range lattice from 48 to 96 hypotheses improves fixed delta < 1.25 by 0.0312 on Stanford and 0.0010 on Matterport. Doubling face resolution from 128 to 256 with the unchanged pixel-window settings instead lowers fixed accuracy by about 0.034 in both domains. The current pixel-valued window controls both ERP feature construction and face-local aggregation, so angular support is not resolution invariant. This is now an explicit promotion blocker rather than a reason to advertise a larger input size.

FullSphereStereoOptions therefore exposes two additive Experimental controls: erp_feature_tap_deg for the tangent-plane ERP feature filter and face_cost_tap_deg for the common Census/aggregation tap grid on projected faces. None preserves the historical one-pixel behavior byte for byte. The face option is converted to a deterministic integer stride from actual centre-ray spacing; it preserves tap count and streaming memory rather than allocating a denser large descriptor. On the eleven development pairs, using both angular supports at 512x1024 improves fixed delta < 1.25 by about 0.11 in both Stanford and Matterport and exactly reproduces on replay. A prospectively frozen test on twelve new view-disjoint pairs then passed the fixed-accuracy, coverage, conditional-gross-error, and 1.35x runtime gates in both domains. Sky and no-return directions were excluded using the prediction-independent positive finite dataset-range proxy; geometric observability and prediction validity remained separate. The scientific evidence, 24 output payloads, and 24 population masks reproduced exactly. The angular configuration was independently reproduced exactly and is now the default for new option objects. Explicit None taps and saved configurations that predate these fields retain the historical one-pixel behavior. The stability tier remains Experimental until the remaining pose, uncertainty, and installed-wheel gates pass.

API

Experimental dense stereo for calibrated central spherical images.

The returned depth quantity is radial range from the reference camera centre. This package is Experimental: its API and numerical policy may change in a future minor release as real-scene validation expands.

class panorai.stereo.SphericalDenseStereo(options=None)

Reusable façade for Experimental direct spherical dense stereo.

estimate(reference_erp, target_erp, rotation_b_from_a, translation_b_from_a)

class panorai.stereo.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)

Configuration for direct spherical inverse-range plane sweep.

min_range and max_range use the same unit as the supplied metric translation. Results are metres only when translation_b_from_a is in metres. window_size defines an odd tangent-plane spherical neighbourhood. filter_backend='auto' selects PanorAi’s first-party C++ spherical-convolution kernel when it is available and otherwise uses the NumPy reference implementation. pyramid_levels > 1 enables an adaptive broad-coarse/local-fine inverse-range search without changing the supplied pose.

min_range

max_range

num_hypotheses

window_size

pole_margin_fraction

min_texture_std

min_confidence

max_matching_cost

intensity_weight

gradient_weight

smoothness_penalty_small

smoothness_penalty_large

bidirectional_consistency

consistency_relative_tolerance

consistency_absolute_tolerance

filter_backend

pyramid_levels

refinement_hypotheses

refinement_radius_steps

to_dict()

class panorai.stereo.SphericalStereoResult(range, validity_mask, confidence, matching_cost, hypothesis_index, inverse_range_hypotheses, options, interface='panorai-spherical-dense-stereo/v1-experimental', quantity='radial_range', hypothesis_mode='absolute_inverse_range', inverse_range_center=None, inverse_range_radius=None)

Dense radial-range estimate in the reference camera frame.

Invalid pixels contain NaN in range and are identified explicitly by validity_mask. Confidence is the normalized best-versus-second-best cost separation and is not a calibrated probability. In adaptive mode, inverse_range_hypotheses contains normalized offsets interpreted with the per-pixel inverse_range_center and inverse_range_radius maps.

range

validity_mask

confidence

matching_cost

hypothesis_index

inverse_range_hypotheses

options

interface

quantity

hypothesis_mode

inverse_range_center

inverse_range_radius

describe()

property range_map

Descriptive alias for the radial range map.

panorai.stereo.colorize_spherical_range(range_map, validity_mask=None, *, value_range=None, percentile_range=(2.0, 98.0), colormap='turbo', invalid_color=(0, 0, 0))

Convert an HW radial-range map to an RGB uint8 visualization.

When value_range is omitted, the color limits are the requested percentiles of finite, positive, valid samples. Invalid pixels receive invalid_color. The returned image is for display only; it must not be used as a numeric depth representation.

panorai.stereo.estimate_spherical_range(reference_erp, target_erp, rotation_b_from_a, translation_b_from_a, *, options=None)

Estimate reference-camera radial range from two central ERPs.

The pose convention is X_b = R_b_from_a @ X_a + t_b_from_a. Both panoramas must use the same ERP shape and PanorAi’s canonical camera frame.

panorai.stereo.render_spherical_stereo_result(reference_erp, result, *, target_erp=None, reference_range=None, value_range=None)

Render a labeled RGB panel for a spherical stereo result.

The panel always contains the reference ERP, estimated radial range and accepted-pixel confidence. If supplied, the target ERP is included too. Supplying metric reference_range adds reference range and relative error panels using the same color limits as the estimate.

Classical rectified stereo

Experimental, non-learned stereo primitives and reference pipelines.

Inputs are already rectified pinhole pairs. Spherical sampling, rectification, and fusion stay in PanorAi’s geometry/object workflow so the same stereo stages can be applied independently to projected views.

class panorai.stereo.classical.ADCensusConfig(min_disparity: 'int' = 0, max_disparity: 'int' = 64, census_radius: 'int' = 2, aggregation_arm: 'int' = 5, aggregation_threshold: 'float' = 0.08, aggregation_passes: 'int' = 2, p1: 'float' = 0.03, p2: 'float' = 0.18, paths: 'int' = 8, validation: 'StereoValidationConfig' = StereoValidationConfig(uniqueness_margin=0.02, left_right_tolerance=1.0, speckle_window_size=0, speckle_range=1.0, median_kernel=0))

class panorai.stereo.classical.ADCensusCost(census_radius=2, ad_weight=0.25, census_weight=0.75, ad_truncation=0.2)

AD-Census unary cost used by the complete AD-Census pipeline.

class panorai.stereo.classical.AbsoluteDifferenceCost(truncation=0.25)

Truncated absolute intensity-difference cost.

class panorai.stereo.classical.BirchfieldTomasiCost(truncation=0.25)

Sampling-insensitive Birchfield–Tomasi intensity cost.

class panorai.stereo.classical.BoxCostAggregation(window_size=5)

Fixed-window valid-normalized cost aggregation.

class panorai.stereo.classical.BuildStereoCost(operation, min_disparity=0, max_disparity=64)

Build a bidirectional cost volume with a configured cost operation.

class panorai.stereo.classical.CensusCost(radius=2)

Normalized Hamming distance between Census descriptors.

class panorai.stereo.classical.CensusMGMConfig(min_disparity: 'int' = 0, max_disparity: 'int' = 64, census_radius: 'int' = 2, aggregation_window: 'int' = 3, variant: 'str' = 'tmgm', p1: 'float' = 0.03, p2: 'float' = 0.18, validation: 'StereoValidationConfig' = StereoValidationConfig(uniqueness_margin=0.02, left_right_tolerance=1.0, speckle_window_size=0, speckle_range=1.0, median_kernel=0))

class panorai.stereo.classical.ClassicalStereoResult(disparity, validity, confidence, matching_cost, occlusion, mismatch, radial_range, method, diagnostics, interface='panorai-classical-dense-stereo/v1-experimental')

Dense rectified disparity and optional radial range.

Invalid disparity and range samples are NaN. Validity, occlusion and mismatch are explicit and are never inferred from numeric zero.

class panorai.stereo.classical.CrossBasedCostAggregation(maximum_arm=5, intensity_threshold=0.08, passes=2)

Color-adaptive cross support aggregation (CBCA).

class panorai.stereo.classical.ELASConfig(min_disparity: 'int' = 0, max_disparity: 'int' = 64, census_radius: 'int' = 2, aggregation_window: 'int' = 3, support_step: 'int' = 8, support_uniqueness: 'float' = 0.08, support_radius: 'float' = 4.0, prior_weight: 'float' = 0.2, p1: 'float' = 0.02, p2: 'float' = 0.12, validation: 'StereoValidationConfig' = StereoValidationConfig(uniqueness_margin=0.02, left_right_tolerance=1.0, speckle_window_size=0, speckle_range=1.0, median_kernel=0))

class panorai.stereo.classical.ELASSupportPrior(support_step=8, uniqueness=0.08, radius=4.0, prior_weight=0.2)

ELAS-style triangulated support-point prior over disparity labels.

class panorai.stereo.classical.MoreGlobalMatching(variant='mgm', p1=0.03, p2=0.18, edge_threshold=0.08)

Two-dimensional MGM/tMGM min-sum aggregation.

class panorai.stereo.classical.OpenCVStereoMatcher(method, min_disparity=0, max_disparity=64, block_size=9, uniqueness_ratio=10, texture_threshold=10, p1=None, p2=None)

Run OpenCV’s complete StereoBM or StereoSGBM implementation.

class panorai.stereo.classical.PatchMatchConfig(min_disparity: 'int' = 0, max_disparity: 'int' = 64, iterations: 'int' = 3, patch_radius: 'int' = 2, random_seed: 'int' = 0, validation: 'StereoValidationConfig' = StereoValidationConfig(uniqueness_margin=0.0, left_right_tolerance=1.5, speckle_window_size=0, speckle_range=1.0, median_kernel=0))

class panorai.stereo.classical.PatchMatchStereo(min_disparity=0, max_disparity=64, iterations=3, patch_radius=2, random_seed=0)

Run the deterministic slanted-plane PatchMatch reference matcher.

class panorai.stereo.classical.RectifiedStereoGeometry(focal_length_x, baseline, focal_length_y=None, principal_point_x=None, principal_point_y=None)

Metric geometry for a rectified pinhole pair.

Pixel coordinates use PanorAi’s pixel-centre convention. baseline and returned radial range use the same unit. Disparity is x_left-x_right.

radial_range(disparity, validity)

Convert rectified disparity to radial range from the left centre.

class panorai.stereo.classical.RectifiedStereoPair(reference, source, reference_support=None, source_support=None, geometry=None)

Prepared rectified pair with explicit support and optional geometry.

class panorai.stereo.classical.RefineStereoDisparity(method, uniqueness_margin=0.02, left_right_tolerance=1.0, speckle_window_size=0, speckle_range=1.0, median_kernel=0)

Apply uniqueness, support, LR consistency, speckle and range output.

class panorai.stereo.classical.SelectStereoDisparity(subpixel=True)

Select bidirectional disparities from an optimized cost volume.

class panorai.stereo.classical.SemiGlobalMatching(p1=0.03, p2=0.18, paths=8, edge_threshold=0.08)

Four- or eight-path Hirschmüller-style cost regularization.

class panorai.stereo.classical.StereoBMConfig(min_disparity: 'int' = 0, max_disparity: 'int' = 64, block_size: 'int' = 9, uniqueness_ratio: 'int' = 10, texture_threshold: 'int' = 10, validation: 'StereoValidationConfig' = StereoValidationConfig(uniqueness_margin=0.0, left_right_tolerance=1.0, speckle_window_size=0, speckle_range=1.0, median_kernel=0))

class panorai.stereo.classical.StereoCostVolume(pair, disparities, left, right, metadata)

Bidirectional dense matching costs for one rectified pair.

class panorai.stereo.classical.StereoDisparityCandidate(pair, left, right, left_cost, left_second_cost, backend_validity, metadata)

Selected left/right disparities before consistency refinement.

class panorai.stereo.classical.StereoSGBMConfig(min_disparity: 'int' = 0, max_disparity: 'int' = 64, block_size: 'int' = 5, uniqueness_ratio: 'int' = 10, p1: 'int | None' = None, p2: 'int | None' = None, validation: 'StereoValidationConfig' = StereoValidationConfig(uniqueness_margin=0.0, left_right_tolerance=1.0, speckle_window_size=0, speckle_range=1.0, median_kernel=0))

class panorai.stereo.classical.StereoValidationConfig(uniqueness_margin=0.02, left_right_tolerance=1.0, speckle_window_size=0, speckle_range=1.0, median_kernel=0)

Common explicit validation policy for classical stereo outputs.

class panorai.stereo.classical.TransformStereoCost(operation, role)

Apply a reusable aggregation, prior, or optimization operation.

panorai.stereo.classical.elas_pipeline(config=ELASConfig(min_disparity=0, max_disparity=64, census_radius=2, aggregation_window=3, support_step=8, support_uniqueness=0.08, support_radius=4.0, prior_weight=0.2, p1=0.02, p2=0.12, validation=StereoValidationConfig(uniqueness_margin=0.02, left_right_tolerance=1.0, speckle_window_size=0, speckle_range=1.0, median_kernel=0)))

Build the documented PanorAi ELAS-style reference composition.

This is an inspectable support-point/triangulation-prior pipeline. It is not presented as binary-equivalent to the original libELAS implementation.

Panoramic stereo workflow

End-to-end dense stereo for registered or unregistered ERP pairs.

The classical route uses spherical geometry to create finite rectified views, runs an interchangeable pinhole matcher on one pair at a time, converts disparity to radial range, and fuses range back in the reference ERP. The alternative sphere-native route exposes the existing direct ERP plane sweep through the same result contract.

class panorai.stereo.panoramic.BackProjectStereoRange

Backproject pair ranges and accumulate confidence in ERP space online.

class panorai.stereo.panoramic.DenseStereoPerPair(matcher)

Run one rectified matcher at a time and release its cost volume.

class panorai.stereo.panoramic.FuseStereoRange(min_weight: 'float' = 1e-06)

class panorai.stereo.panoramic.FullSphereMultiViewStereo(options=None)

Estimate dense radial range with an overlapping cubemap and many baselines.

describe()

Return the registered-pose contract and selected profile provenance.

estimate(registered)

Estimate range for one explicit reference-centred registered set.

class panorai.stereo.panoramic.FullSphereStereoOptions(planner=<factory>, stereo=<factory>, 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)

Configuration for cube-atlas multibaseline plane sweep.

property experimental_extensions

Return option families outside the reviewed promotion profile.

property profile_id

Identify the reviewed supplied-pose profile, if selected exactly.

classmethod reviewed_profile(*, filter_backend='auto')

Return the exact supplied-pose profile used by promotion evidence.

The profile is deliberately explicit. It does not include the multiscale cost, tMGM, automatic pose estimation, or a calibrated uncertainty model. filter_backend='auto' preserves normal public portability; evidence runners must select 'native' or 'numpy' explicitly when backend identity is part of the oracle.

class panorai.stereo.panoramic.FullSphereStereoResult(radial_range, validity, confidence, disagreement, sampling_support, observable, max_parallax_deg, observable_source_count, source_count, source_consensus_count, contribution_count, source_ids, diagnostics, interface='panorai-registered-full-sphere-stereo/v1-experimental', matching_confidence=None, consistency_confidence=None)

Fused reference-ERP radial range and explicit evidence masks.

diagnostics['face_acceptance_cumulative_counts'] reports the exact cumulative predicates used by the Experimental face estimator. Counts are face pixels, so overlapping faces are intentionally counted separately; they are not unique ERP directions or evaluation metrics.

describe()

Describe result semantics without interpreting confidence as probability.

property range

Compatibility-style alias for radial range.

class panorai.stereo.panoramic.OverlappingCubemapPlanner(face_size=128, face_fov_deg=100.0)

Plan six cube-oriented gnomonic tiles with deliberate edge overlap.

plan()

Return canonical front/right/back/left/up/down tile specifications.

class panorai.stereo.panoramic.PanoramicStereoInput(reference, source, rotation_source_from_reference=None, translation_source_from_reference=None, baseline=None, units=None, reference_validity=None, source_validity=None, scale_status=None, pose_provenance=None)

Two canonical ERPs and optional relative pose/scale information.

class panorai.stereo.panoramic.PanoramicStereoPose(rotation_source_from_reference, translation_source_from_reference, baseline, units, scale_status, provenance)

Relative pose using X_source = R @ X_reference + t.

translation is metric only when scale_status == 'metric'. A pose estimated from two central cameras has direction but no scale; PanorAi then uses a unit baseline and labels the result baseline-units.

class panorai.stereo.panoramic.PanoramicStereoResult(radial_range, validity, confidence, disagreement, contribution_count, pose, view_pairs, view_selection, pair_diagnostics, diagnostics, interface='panorai-panoramic-dense-stereo/v1-experimental', matching_confidence=None, consistency_confidence=None)

Dense radial range in the reference ERP and complete audit metadata.

property range

Compatibility alias for radial range.

class panorai.stereo.panoramic.PlanRectifiedStereoViews(planner: 'RectifiedStereoViewPlanner')

class panorai.stereo.panoramic.ProjectStereoViewPairs

Create a lazy stream: only one RGB pair is materialized at a time.

class panorai.stereo.panoramic.RectifiedStereoViewPlanner(hfov_deg=90.0, vfov_deg=100.0, overlap_deg=20.0, output_shape_hw=(512, 512))

Plan a ring of virtual pinhole pairs rectified by construction.

The local x-axis follows the physical A-to-B baseline. Corresponding epipolar great circles therefore become horizontal raster rows in both faces. The two epipolar singularities are deliberately left outside the finite pinhole coverage and reported by the plan.

class panorai.stereo.panoramic.RectifiedStereoViewSpec(pair_id, reference_spec, source_spec, longitude_index)

One deterministically paired rectified virtual-camera specification.

class panorai.stereo.panoramic.RegisteredPanoramaSet(*, reference_id, reference, sources, reference_validity=None)

A reference panorama and every source registered to that reference.

Registration is a relation among views, so the aggregate—not an individual image—is the public stereo input. Every source pose maps from the reference frame named by reference_id into that source frame.

class panorai.stereo.panoramic.ResolveStereoPose(pose_mode='auto', require_quality_acceptance=True)

Use a supplied relative pose or estimate direction with spherical features.

class panorai.stereo.panoramic.ResolveStereoScale

Resolve metric baseline or preserve an explicit scale-free contract.

class panorai.stereo.panoramic.SelectStereoViewPairs(min_joint_support: 'float' = 0.1, min_texture_std: 'float' = 0.005, min_pose_inliers: 'int' = 0, max_epipolar_row_error_px: 'float' = 2.0, matcher: 'Any | None' = None)

class panorai.stereo.panoramic.SphereNativeStereo(options: 'SphericalStereoOptions')

class panorai.stereo.panoramic.SphericalStereoViewPairer(*, min_score=0.2, min_angular_overlap=0.05, max_pairs_per_reference=3)

Score many-to-many pairs for independently sampled spherical views.

match(reference_views, source_views, *, pose, sparse_matches=None, inlier_mask=None)

Match independently sampled views with the documented façade.

class panorai.stereo.panoramic.StereoPairDiagnostic(pair_id, valid_fraction, median_confidence, median_range, method)

Compact per-pair result retained after its cost volume is released.

class panorai.stereo.panoramic.StereoSourceView(*, source_id, panorama, pose, validity=None)

One source view and its directed relation to a set reference.

This object is not independently “registered”. Its pose has meaning only inside RegisteredPanoramaSet and uses X_source = R_source_from_reference @ X_reference + t. Translation scale defines the output radial-range unit.

class panorai.stereo.panoramic.StereoViewDescriptor(view_id, spec, support_mask=None)

Geometry and support used to pair independently sampled views.

class panorai.stereo.panoramic.StereoViewPairScore(reference_view_id, source_view_id, score, angular_overlap, sparse_inlier_coverage, epipolar_consistency, support_fraction)

Auditable score for one candidate pair of independently sampled views.

class panorai.stereo.panoramic.StereoViewSelectionDiagnostic(pair_id, accepted, joint_support_fraction, texture_std, pose_inliers, median_epipolar_row_error_px, disparity_interval_viable, rejection_reasons)

Quality-gate decision made before constructing a dense cost volume.

class panorai.stereo.panoramic.StereoViewPlan(pairs, baseline_axis_reference, estimated_angular_coverage, omitted_epipolar_cone_deg)

A finite ring of rectified pinhole pairs around the stereo baseline.

class panorai.stereo.panoramic.ValidatePanoramicStereo(min_valid_fraction=0.0)

Enforce the common panoramic result contract for either execution route.

panorai.stereo.panoramic.spec_from_axes(forward, right, *, hfov_deg, vfov_deg, output_shape_hw)

Create a rolled gnomonic spec from desired forward and right axes.