Registration and stitching API

The Experimental panorai.stitching namespace contains the typed data and composable Stages used by panorai.applications.PanoramaStitcher.

Input and configuration

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

Configuration for the central rotation-only stitching profile.

class panorai.stitching.StitchingImage(image_id, values, support=None, validity=None, horizontal_fov_deg=None, interface='panorai-stitching-image/v1-experimental', stability='experimental')

One planar source image with explicit geometric support and validity.

class panorai.stitching.StitchingInput(images: 'tuple[StitchingImage, ...]', interface: 'str' = 'panorai-stitching-input/v1-experimental', stability: 'str' = 'experimental')

Stages

class panorai.stitching.DetectStitchingFeatures(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))

Extract planar local evidence while retaining source-image identity.

class panorai.stitching.DiscoverOverlaps(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))

Match every unordered image pair to discover an overlap graph.

class panorai.stitching.CalibrateAndRegister(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))

Fit pair models, calibrate FOV and optimize one connected SO(3) graph.

class panorai.stitching.WarpRegisteredImages(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))

Inverse-warp registered pinhole sources onto one canonical ERP grid.

class panorai.stitching.CompensateExposure(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))

Estimate robust global gains from valid ERP overlaps.

class panorai.stitching.BlendStitchingPanorama(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))

Blend valid warped samples and return a typed ERP plus diagnostics.

exception panorai.stitching.StitchingRegistrationError

The image set cannot support the requested central panorama model.

Intermediate and result values

class panorai.stitching.StitchingFeatureSet(image_id: 'str', pixels_xy: 'np.ndarray', descriptors: 'np.ndarray', responses: 'np.ndarray', method: 'str')

class panorai.stitching.StitchingFeatures(source: 'StitchingInput', features: 'tuple[StitchingFeatureSet, ...]')

class panorai.stitching.ImagePairMatches(index_a: 'int', index_b: 'int', feature_indices_a: 'np.ndarray', feature_indices_b: 'np.ndarray', descriptor_distances: 'np.ndarray')

class panorai.stitching.StitchingMatches(features: 'StitchingFeatures', pairs: 'tuple[ImagePairMatches, ...]')

class panorai.stitching.ImagePairRegistration(index_a: 'int', index_b: 'int', rotation_b_from_a: 'np.ndarray', calibration: 'RotationCalibrationResult', match_indices: 'np.ndarray', homography: 'np.ndarray', homography_inlier_count: 'int')

class panorai.stitching.RegisteredImageSet(source: 'StitchingInput', intrinsics: 'tuple[PinholeIntrinsics, ...]', camera_to_world: 'tuple[np.ndarray, ...]', pairwise: 'tuple[ImagePairRegistration, ...]', feature_counts: 'tuple[int, ...]', reference_index: 'int', rotation_initial_cost: 'float', rotation_final_cost: 'float', rejected_pairs: 'tuple[str, ...]')

class panorai.stitching.WarpedImageSet(registered: 'RegisteredImageSet', values: 'tuple[np.ndarray, ...]', support: 'tuple[np.ndarray, ...]', validity: 'tuple[np.ndarray, ...]', weights: 'tuple[np.ndarray, ...]', gains: 'tuple[float, ...]')

class panorai.stitching.StitchingDiagnostics(input_image_count: 'int', feature_counts: 'tuple[int, ...]', candidate_pair_count: 'int', accepted_pair_count: 'int', rejected_pairs: 'tuple[str, ...]', reference_image_id: 'str', estimated_fov_count: 'int', rotation_initial_cost: 'float', rotation_final_cost: 'float', coverage: 'float', overlap_fraction: 'float', gains: 'tuple[float, ...]', model: 'str' = 'central-rotation')

class panorai.stitching.PanoramaStitchingResult(panorama: 'EquirectangularImage', registered: 'RegisteredImageSet', contribution_map: 'np.ndarray', support_count: 'np.ndarray', diagnostics: 'StitchingDiagnostics', interface: 'str' = 'panorai-panorama-stitching/v1-experimental', stability: 'str' = 'experimental')

The output panorama may cover only part of the ERP lattice. Inspect support, validity, support_count, contribution_map and diagnostics rather than assuming rectangular coverage.

Start with the progressive guide and read the registration concept before using the lower-level Stages.