1 oracle.evidence

oracle.evidence

Build lineage-preserving oracle evaluation point clouds for RRI scoring.

This module provides deterministic fusion, observed-prefix selection, and root point-cloud construction. It separates actor-visible geometry from oracle-only label geometry. The thesis-core default builds the root evaluation point cloud from ASE RGB ground-truth ray-distance depth frames, while semi-dense MPS points remain available as actor input and as a legacy diagnostic stream.

This module owns oracle root and target preparation adapters, frame/time provenance and typed invalidity outcomes. Pure geometric membership and surface intersection are delegated to geometry.crops; rendering retains candidate acquisition. These adapters do not decide candidate hard validity.

1.1 Classes

Name	Description
OracleEvidenceInvalidReason	Stable semantic reasons for expected Oracle evidence invalidity.
OracleRriState	Minimal actor/replay state consumed by Oracle RRI facades.
RootEvalPointCloud	Root oracle evaluation points with reproducible source lineage.
RriEvaluationPointCloudSource	Select the geometry source used for the root oracle evaluation cloud.
RriRewardMode	Choose the normalization used for a valid rollout candidate’s oracle gain.

1.1.1 OracleEvidenceInvalidReason

oracle.evidence.OracleEvidenceInvalidReason()

Stable semantic reasons for expected Oracle evidence invalidity.

1.1.2 OracleRriState

oracle.evidence.OracleRriState()

Minimal actor/replay state consumed by Oracle RRI facades.

1.1.2.1 Attributes

Name	Description
root_pose_world	Return the rollout root pose in world coordinates.
root_time_ns	Return the root timestamp when available.
root_trajectory_index	Return the root trajectory row when available.
root_frame_index	Return the root frame row when available.

1.1.2.2 Methods

Name	Description
accumulated_points_world	Return selected-history point clouds in world coordinates.
root_metric	Return the first finite persisted metric with name.

1.1.2.2.1 accumulated_points_world

oracle.evidence.OracleRriState.accumulated_points_world()

Return selected-history point clouds in world coordinates.

1.1.2.2.2 root_metric

oracle.evidence.OracleRriState.root_metric(name)

Return the first finite persisted metric with name.

1.1.3 RootEvalPointCloud

oracle.evidence.RootEvalPointCloud(
    points_world,
    source,
    frame_indices,
    trajectory_indices,
    root_time_ns,
    root_trajectory_index,
    root_frame_index,
    depth_convention,
    camera_label,
    stride,
    far_m,
    voxel_size_m,
    max_points,
)

Root oracle evaluation points with reproducible source lineage.

The points are label/evaluation geometry, even when the selected source is also available to the actor. Frame and trajectory indices preserve exactly which observed prefix was unprojected into the world frame.

1.1.3.1 Attributes

Name	Description
points_world	Tensor["P 3", float32] fused evaluation points in world frame, metres.
source	Root evaluation point-cloud source.
frame_indices	Tensor["F_eval", int64] camera/depth frame indices used by the ASE root.
trajectory_indices	Tensor["F_eval", int64] nearest trajectory rows used for world transforms.
root_time_ns	Root timestamp in nanoseconds used for observed-prefix filtering, if available.
root_trajectory_index	Root trajectory row used for observed-prefix filtering, if available.
root_frame_index	Root camera frame index used for observed-prefix filtering, if available.
depth_convention	Depth convention for lineage, e.g. ray_distance_m.
camera_label	Camera stream used to build points_world.
stride	Positive pixel stride applied after ray-distance unprojection.
far_m	Maximum retained ray distance in metres, if configured.
voxel_size_m	Voxel size used by canonical fusion; 0 disables voxel fusion.
max_points	Maximum retained points after deterministic fusion/downsampling.

1.1.4 RriEvaluationPointCloudSource

oracle.evidence.RriEvaluationPointCloudSource()

Select the geometry source used for the root oracle evaluation cloud.

1.1.4.1 Attributes

Name	Description
ASE_GT_DEPTH_ROOT	Observed-prefix ASE GT ray-distance depth, used by thesis target labels.
LEGACY_SEMIDENSE_ROOT	MPS semi-dense world points, retained for actor/legacy diagnostics only.
RENDERED_LOGGED_DEPTH_ROOT	Reserved rendered-root parity ablation; current construction raises.

1.1.5 RriRewardMode

oracle.evidence.RriRewardMode()

Choose the normalization used for a valid rollout candidate’s oracle gain.

1.1.5.1 Attributes

Name	Description
ROOT_NORMALIZED_GAIN	Normalize every step by the fixed rollout-root error for telescoping returns.
STATE_RELATIVE_RRI	Normalize one-step improvement by the current-state error for diagnostics.

1.2 Functions

Name	Description
build_root_eval_pointcloud	Build the observed-prefix root cloud used by oracle rollout labels.
canonical_fuse_points	Filter, deterministically voxel-fuse, and cap metric-frame points.
crop_mesh_to_obb	Crop a scene mesh to an oriented target box.
crop_padded_pointclouds_to_obb	Crop and fuse each padded candidate point cloud to an oriented box.
crop_points_to_obb	Return finite world points inside an oriented target box.
observed_prefix_frame_indices	Select camera frames and matched trajectory rows in the observed prefix.
target_aabb_from_points	Return an axis-aligned scoring extent around prepared target points.
target_gt_obb_world	Resolve an Oracle-selected target’s matched GT OBB in world coordinates.

1.2.1 build_root_eval_pointcloud

oracle.evidence.build_root_eval_pointcloud(
    sample,
    *,
    source=RriEvaluationPointCloudSource.ASE_GT_DEPTH_ROOT,
    camera_label='rgb',
    reference_pose_world=None,
    reference_time_ns=None,
    reference_trajectory_index=None,
    reference_frame_index=None,
    stride=1,
    far_m=20.0,
    voxel_size_m=0.02,
    max_points=200000,
)

Build the observed-prefix root cloud used by oracle rollout labels.

ASE_GT_DEPTH_ROOT uses all observed camera/depth frames up to the rollout reference pose. LEGACY_SEMIDENSE_ROOT returns the collapsed MPS semi-dense point cloud for diagnostics only. RENDERED_LOGGED_DEPTH_ROOT is intentionally reserved for the rendered-root ablation and should be implemented separately from ASE ray-distance preprocessing.

1.2.1.1 Parameters

Name	Type	Description	Default
sample	EfmSnippetView	EFM snippet containing camera calibration, ray-distance depth, trajectory poses, and optional MPS semi-dense points.	required
source	RriEvaluationPointCloudSource | str	Evaluation-geometry source. The thesis default is oracle-only ASE GT depth; the semi-dense option is a legacy diagnostic.	RriEvaluationPointCloudSource.ASE_GT_DEPTH_ROOT
camera_label	CameraLabel	Calibrated EFM camera stream used for ASE depth.	'rgb'
reference_pose_world	object | None	Optional world-from-rig root pose. It is used only when it exactly matches a trajectory row.	None
reference_time_ns	int | None	Explicit root timestamp in nanoseconds; this has precedence over frame, trajectory, and pose-derived timestamps.	None
reference_trajectory_index	int | None	Optional root trajectory row.	None
reference_frame_index	int | None	Optional root camera frame row.	None
stride	int	Positive spatial sampling stride after unprojection.	1
far_m	float | None	Optional maximum retained ray distance in metres.	20.0
voxel_size_m	float	Voxel edge length in metres for canonical fusion; 0 disables aggregation.	0.02
max_points	int | None	Optional deterministic point cap after fusion.	200000

1.2.1.2 Returns

Name	Type	Description
	RootEvalPointCloud	class:RootEvalPointCloud with Tensor["P 3", float32] world-frame
	RootEvalPointCloud	points in metres and observed-prefix lineage.

1.2.1.3 Notes

The returned geometry is consumed by the oracle label path. Selecting the legacy MPS source does not make GT mesh or candidate-rendered geometry actor-visible, and this function never converts missing data into a low RRI label.

1.2.2 canonical_fuse_points

oracle.evidence.canonical_fuse_points(
    points,
    *,
    voxel_size_m=0.0,
    max_points=None,
)

Filter, deterministically voxel-fuse, and cap metric-frame points.

1.2.2.1 Parameters

Name	Type	Description	Default
points Tensor["N D", float32]		Points in one metric coordinate frame. Only the first three coordinates are retained.	required
voxel_size_m	float	Edge length for mean voxel fusion. Values <=0 disable voxel aggregation.	0.0
max_points	int | None	Optional deterministic cap after voxel fusion.	None

1.2.2.2 Returns

Name	Type	Description
	Tensor	Tensor["K 3", float32] finite points in the input frame and units.
	Tensor	Voxel representatives are input-order arithmetic means in lexicographic
	Tensor	voxel-key order. Deterministic capping retains evenly spaced row
	Tensor	indices.

1.2.2.3 Notes

Stable grouping fixes the arithmetic order for a given input order. The regression contract guards repeatability on the pinned PyTorch/CUDA runtime; bit-exactness is not promised across devices or releases.

1.2.3 crop_mesh_to_obb

oracle.evidence.crop_mesh_to_obb(verts, faces, obb, *, margin_m=0.0)

Crop a scene mesh to an oriented target box.

1.2.4 crop_padded_pointclouds_to_obb

oracle.evidence.crop_padded_pointclouds_to_obb(
    points,
    lengths,
    obb,
    *,
    margin_m=0.0,
    voxel_size_m=0.0,
    max_points=None,
)

Crop and fuse each padded candidate point cloud to an oriented box.

1.2.5 crop_points_to_obb

oracle.evidence.crop_points_to_obb(points, obb, *, margin_m=0.0)

Return finite world points inside an oriented target box.

1.2.6 observed_prefix_frame_indices

oracle.evidence.observed_prefix_frame_indices(
    sample,
    *,
    camera_label='rgb',
    reference_pose_world=None,
    reference_time_ns=None,
    reference_trajectory_index=None,
    reference_frame_index=None,
)

Select camera frames and matched trajectory rows in the observed prefix.

Prefix membership is defined by camera timestamp and optional trajectory row, never by spatial nearest-neighbour pose matching. This prevents looped or revisited trajectories from admitting future ASE GT depth frames into a non-final rollout root.

1.2.6.1 Parameters

Name	Type	Description	Default
sample	EfmSnippetView	EFM snippet whose camera and trajectory timestamps share the snippet time domain.	required
camera_label	CameraLabel	Camera stream whose frame rows are selected.	'rgb'
reference_pose_world	object | None	Optional exact world-from-rig trajectory pose.	None
reference_time_ns	int | None	Optional explicit root timestamp in nanoseconds.	None
reference_trajectory_index	int | None	Optional maximum trajectory row.	None
reference_frame_index	int | None	Optional camera row used to derive root time.	None

1.2.6.2 Returns

Name	Type	Description
	Tensor	Tuple containing frame indices Tensor["F_eval", int64] and their
	Tensor	nearest trajectory rows Tensor["F_eval", int64]. Both are ordered
	tuple[Tensor, Tensor]	prefixes on the camera timestamp device.

1.2.7 target_aabb_from_points

oracle.evidence.target_aabb_from_points(points, *, margin_m=0.0)

Return an axis-aligned scoring extent around prepared target points.

1.2.8 target_gt_obb_world

oracle.evidence.target_gt_obb_world(task, sample)

Resolve an Oracle-selected target’s matched GT OBB in world coordinates.