Spherical evaluation API

panorai.evaluation provides NumPy-canonical evaluation without downloading datasets, executing models, choosing thresholds, or changing the stability tier of the algorithm under test. Region, feature, pose and radial-range evaluation is Stable. Surface-reconstruction evaluation is a separate Experimental component.

Surface	Stability	Canonical import	Contract	Public components or entries
spherical-evaluation	Stable	panorai.evaluation	panorai-spherical-evaluation/v1	BinaryRegionEvaluation, DepthEvaluation, EvaluationProtocol, EvaluationRecord, FeatureEvaluation, PoseEvaluation, evaluate_binary_regions, evaluate_features, evaluate_pose, evaluate_radial_range, solid_angle_weights
spherical-surface-reconstruction-evaluation	Experimental	panorai.evaluation	panorai-surface-reconstruction-evaluation/v1-experimental	SurfaceReconstructionEvaluation, SurfaceReconstructionEvaluationReport, aggregate_surface_reconstruction, evaluate_surface_reconstruction

Metrics

panorai.evaluation.solid_angle_weights(shape_hw)

Return exact canonical-ERP pixel solid angles in steradians.

panorai.evaluation.evaluate_binary_regions(prediction, reference, *, support=None, prediction_validity=None, reference_validity=None, boundary_tolerance_deg=1.0)

Evaluate two binary canonical-ERP regions with exact area weights.

support is geometric coverage. The two validity masks are data validity and are intersected only for comparison; neither is inferred from the binary values. Boundary matching uses great-circle distance between ERP pixel centres and longitude-periodic four-neighbour boundaries.

panorai.evaluation.evaluate_features(predicted_bearings, reference_bearings, *, threshold_deg, prediction_validity=None, reference_validity=None, predicted_scales=None, reference_scales=None)

Compute deterministic one-to-one angular feature repeatability.

panorai.evaluation.evaluate_pose(estimated_rotation, reference_rotation, *, estimated_translation_direction=None, reference_translation_direction=None, translation_sign_invariant=False)

Evaluate source-from-reference rotation and optional translation direction.

panorai.evaluation.evaluate_radial_range(prediction, reference, *, units, support=None, prediction_validity=None, reference_validity=None, confidence=None)

Evaluate radial range without inferring validity from numeric values.

Experimental surface reconstruction metrics

panorai.evaluation.evaluate_surface_reconstruction(prediction, reference, *, distance_threshold, reference_observed=None)

Evaluate one reconstructed mesh against a world-frame reference mesh.

Distances are exact point-to-triangle distances from each mesh’s vertices to the other surface. reference_observed can restrict completeness to externally established observable reference vertices; it is never derived from color, coordinate values, or the prediction.

panorai.evaluation.aggregate_surface_reconstruction(per_scene)

Aggregate a preregistered cohort without weighting large meshes more.

Every scene must use the same units and frozen distance threshold. Each reported metric is the median of the scene-level metric, matching the promotion protocol’s per-corpus median interpretation.

Typed results and evidence

class panorai.evaluation.BinaryRegionEvaluation(iou, dice, precision, recall, coverage, boundary_precision, boundary_recall, boundary_f1, supported_solid_angle_sr, comparable_solid_angle_sr, prediction_solid_angle_sr, reference_solid_angle_sr, intersection_solid_angle_sr, union_solid_angle_sr, boundary_tolerance_deg, interface='panorai-spherical-evaluation/v1')

Solid-angle and boundary comparison for two binary ERP regions.

class panorai.evaluation.FeatureEvaluation(predicted_count, reference_count, matched_count, precision, recall, repeatability, median_angular_error_deg, maximum_angular_error_deg, median_scale_error_levels, maximum_scale_error_levels, threshold_deg, matched_indices, interface='panorai-spherical-evaluation/v1')

One-to-one angular repeatability result for spherical keypoints.

class panorai.evaluation.PoseEvaluation(rotation_error_deg, translation_direction_error_deg, translation_sign_invariant, interface='panorai-spherical-evaluation/v1')

SO(3) and optional translation-direction error.

class panorai.evaluation.DepthEvaluation(coverage, mae, rmse, abs_rel, delta1, delta2, delta3, relative_coverage, confidence_error_spearman, top_confidence_quartile_mae, bottom_confidence_quartile_mae, comparable_count, supported_count, relative_count, comparable_solid_angle_sr, supported_solid_angle_sr, units, interface='panorai-spherical-evaluation/v1')

Area-weighted radial-range accuracy, coverage and confidence evidence.

Experimental surface reconstruction results

class panorai.evaluation.SurfaceReconstructionEvaluation(accuracy_mean, accuracy_median, completeness_mean_distance, completeness_median_distance, precision, recall, fscore, normal_consistency, median_normal_error_deg, observed_surface_coverage, distance_threshold, prediction_sample_count, reference_sample_count, units, interface='panorai-surface-evaluation/v1-experimental')

Bidirectional point-to-triangle surface metrics for one scene.

class panorai.evaluation.SurfaceReconstructionEvaluationReport(per_scene, aggregate, scene_count, distance_threshold, units, aggregation='unweighted-scene-median', interface='panorai-surface-evaluation-report/v1-experimental')

Per-scene results and an unweighted median across a frozen cohort.

class panorai.evaluation.EvaluationProtocol(protocol_id, version, evaluator, metric_names, parameters=<factory>, interface='panorai-spherical-evaluation/v1')

Frozen evaluator identity and parameters selected before evaluation.

class panorai.evaluation.EvaluationRecord(protocol, subject_id, input_id, reference_id, split, algorithm_id, algorithm_config, package_version, backend, metrics, status='evaluated', reasons=(), artifact_sha256=None, geometry_contract='geometry-v1', environment=<factory>, interface='panorai-spherical-evaluation/v1')

One JSON-safe result bound to data, algorithm, protocol and artifact.

All ERP metrics use pixel-centre geometry. Region and radial-range metrics use exact per-pixel solid angle; support and validity are separate boolean inputs. Torch tensors are rejected so an implicit device transfer cannot become part of an evaluation protocol.

See the concept for the measurement contract and the how-to guide for a reproducible record.