1 vin.geometry

vin.geometry

Geometry helpers shared by VIN scorer implementations.

The modules in this package own stateless SE(3), camera, frustum, and voxel geometry contracts used by aria_nbv.vin.models.scene_myopic and related diagnostic surfaces. Neural modules should import these helpers rather than keeping shape normalization or camera-space math in model classes.

1.1 Attributes

Name Description
SEMIDENSE_GRID_CHANNELS Channel count for semidense projection grid tensors.
SEMIDENSE_PROJ_DIM Feature dimension for semidense projection summary tensors.

1.2 Functions

Name Description
build_frustum_points_world_p3d Unproject a square image grid at fixed depths into world points.
build_projection_grid Build per-camera semidense projection grids for CNN encoders.
build_scene_field Build a compact voxel-aligned scene field from EVL evidence tensors.
candidate_valid_from_token Convert per-token validity into a per-candidate validity mask.
center_crop_grid Center-crop a voxel grid with trailing XYZ/channel values.
encode_projection_summary Summarize semidense projection coverage, visibility, and depth.
ensure_candidate_batch Ensure candidate camera poses are shaped as PoseTW["B N 12"].
ensure_pose_batch Broadcast one pose tensor to the VIN batch size.
frustum_points_world_from_cameras Generate per-candidate frustum sample points in world coordinates.
infer_padded_grid_shape Infer a symmetrically padded voxel-grid shape from a flattened count.
pool_voxel_points Downsample voxel center points to a pooled token grid.
pos_grid_from_pts_world Convert voxel centers to a normalized position grid in reference-rig frame.
project_points_to_candidate_cameras Project world points into a batch of candidate cameras.
sample_candidate_voxel_coverage Sample normalized voxel observation coverage at candidate camera centers.
sample_semidense_points Sample valid semidense world points from a VIN snippet.
sample_voxel_field Sample a voxel-aligned field at world points.
semidense_proj_feature_index Resolve a canonical semidense projection feature name to its index.

1.2.1 build_frustum_points_world_p3d

vin.geometry.build_frustum_points_world_p3d(cameras, *, grid_size, depths_m)

Unproject a square image grid at fixed depths into world points.

1.2.1.1 Parameters

Name Type Description Default
cameras PerspectiveCameras PyTorch3D camera batch with pixel image_size and principal_point parameters. required
grid_size int Number of image samples per side. required
depths_m list[float] Positive metric depths to sample along each image ray. required

1.2.1.2 Returns

Name Type Description
Tensor Tensor["Nc G*G*D 3"] of world-frame points, where Nc is the
Tensor camera count and D is len(depths_m).

1.2.2 build_projection_grid

vin.geometry.build_projection_grid(proj_data, *, device, dtype, grid_size)

Build per-camera semidense projection grids for CNN encoders.

1.2.2.1 Parameters

Name Type Description Default
proj_data dict[str, Tensor] | None Output from project_points_to_candidate_cameras. required
device torch.device Target device for the grid. required
dtype torch.dtype Output dtype consumed by the caller-owned CNN. required
grid_size int Screen-space bin count per side. required

1.2.2.2 Returns

Name Type Description
Tensor Tensor["B*N_q C_grid G G", float32] containing occupancy, mean
Tensor camera-frame depth in metres, and depth standard-deviation grids, with
Tensor C_grid == SEMIDENSE_GRID_CHANNELS.

1.2.3 build_scene_field

vin.geometry.build_scene_field(
    out,
    *,
    use_channels,
    occ_input_threshold,
    counts_norm_mode,
    occ_pr_is_logits,
)

Build a compact voxel-aligned scene field from EVL evidence tensors.

1.2.3.1 Parameters

Name Type Description Default
out Any Backbone output object exposing EVL head/evidence tensors. required
use_channels list[str] Ordered channel names to concatenate. required
occ_input_threshold float Threshold for deriving free-space evidence when free_input is absent. required
counts_norm_mode Literal['log1p', 'linear'] Observation-count normalization mode. required
occ_pr_is_logits bool Whether occ_pr must be passed through sigmoid. required

1.2.3.2 Returns

Name Type Description
Tensor Tensor["B C D H W"] with channels ordered by use_channels.

1.2.4 candidate_valid_from_token

vin.geometry.candidate_valid_from_token(token_valid, *, min_valid_frac)

Convert per-token validity into a per-candidate validity mask.

1.2.5 center_crop_grid

vin.geometry.center_crop_grid(grid, target_shape)

Center-crop a voxel grid with trailing XYZ/channel values.

1.2.6 encode_projection_summary

vin.geometry.encode_projection_summary(
    proj_data,
    *,
    batch_size,
    num_candidates,
    device,
    dtype,
    grid_size,
    obs_count_max,
    inv_dist_std_min,
    inv_dist_std_p95,
)

Summarize semidense projection coverage, visibility, and depth.

1.2.6.1 Parameters

Name Type Description Default
proj_data dict[str, Tensor] | None Output from project_points_to_candidate_cameras. required
batch_size int Batch size B. required
num_candidates int Candidate count N_q per batch item. required
device torch.device Target device for features. required
dtype torch.dtype Output dtype. required
grid_size int Screen-space bin count per side for coverage. required
obs_count_max int Saturation point for the log1p(n_obs) reliability factor. required
inv_dist_std_min float Lower bound for inverse depth-uncertainty scaling. required
inv_dist_std_p95 float Upper reference percentile for inverse depth-uncertainty scaling. required

1.2.6.2 Returns

Name Type Description
Tensor Tensor["B N_q F_proj", float32] with
Tensor F_proj == SEMIDENSE_PROJ_DIM, ordered by
Tensor SEMIDENSE_PROJ_FEATURES.

1.2.7 ensure_candidate_batch

vin.geometry.ensure_candidate_batch(candidate_poses_world_cam)

Ensure candidate camera poses are shaped as PoseTW["B N 12"].

1.2.7.1 Parameters

Name Type Description Default
candidate_poses_world_cam PoseBatchT Candidate camera poses T_w_c with shape PoseTW["N 12"] for one snippet or PoseTW["B N 12"] for a batch. required

1.2.7.2 Returns

Name Type Description
PoseBatchT Candidate poses with an explicit batch axis.

1.2.7.3 Raises

Name Type Description
ValueError If the pose tensor is neither (N, 12) nor (B, N, 12).

1.2.8 ensure_pose_batch

vin.geometry.ensure_pose_batch(pose, *, batch_size, name)

Broadcast one pose tensor to the VIN batch size.

1.2.8.1 Parameters

Name Type Description Default
pose PoseBatchT Pose tensor with shape PoseTW["12"], PoseTW["1 12"], or PoseTW["B 12"]. required
batch_size int Required batch size B. required
name str Human-readable input name used in validation errors. required

1.2.8.2 Returns

Name Type Description
PoseBatchT pose shaped as PoseTW["B 12"].

1.2.8.3 Raises

Name Type Description
ValueError If pose has an unsupported rank or a non-broadcastable batch dimension.

1.2.9 frustum_points_world_from_cameras

vin.geometry.frustum_points_world_from_cameras(
    poses_world_cam,
    *,
    p3d_cameras,
    grid_size,
    depths_m,
)

Generate per-candidate frustum sample points in world coordinates.

1.2.9.1 Parameters

Name Type Description Default
poses_world_cam PoseTW Candidate poses shaped as PoseTW["B N 12"]. The tensor supplies the desired B and N layout; projection uses the aligned p3d_cameras batch. required
p3d_cameras PerspectiveCameras PyTorch3D cameras aligned with candidates. The camera batch must be N when B == 1 or B * N otherwise. required
grid_size int Number of image samples per side. required
depths_m list[float] Positive metric depths sampled along each image ray. required

1.2.9.2 Returns

Name Type Description
Tensor Tensor["B N K 3"] world-frame frustum points.

1.2.10 infer_padded_grid_shape

vin.geometry.infer_padded_grid_shape(num_pts, target_shape)

Infer a symmetrically padded voxel-grid shape from a flattened count.

1.2.11 pool_voxel_points

vin.geometry.pool_voxel_points(pts_world, *, grid_shape, pool_grid)

Downsample voxel center points to a pooled token grid.

1.2.11.1 Parameters

Name Type Description Default
pts_world Tensor Voxel centers as Tensor["B D H W 3"] or flattened Tensor["B V 3"]. required
grid_shape tuple[int, int, int] Target (D, H, W) grid shape before pooling. required
pool_grid int Output side length G. required

1.2.11.2 Returns

Name Type Description
Tensor Tensor["B G*G*G 3"] pooled world-frame voxel centers.

1.2.12 pos_grid_from_pts_world

vin.geometry.pos_grid_from_pts_world(
    pts_world,
    *,
    t_world_voxel,
    pose_world_rig_ref,
    voxel_extent,
    grid_shape,
)

Convert voxel centers to a normalized position grid in reference-rig frame.

If pts_world corresponds to a padded grid (for example before a valid Conv3d shrink), the grid is center-cropped to grid_shape before normalization.

1.2.13 project_points_to_candidate_cameras

vin.geometry.project_points_to_candidate_cameras(
    points_world,
    p3d_cameras,
    *,
    batch_size,
    num_candidates,
    device,
)

Project world points into a batch of candidate cameras.

This is the shared projection path for semidense points and pooled voxel centers. It enforces the PyTorch3D camera batch contract used by aria_nbv.vin.models.scene_myopic.VinModelV3: the camera batch is either Nq when B == 1 or B * Nq for true batched inputs.

1.2.13.1 Parameters

Name Type Description Default
points_world Tensor | None Tensor["P C", float32] or Tensor["B P C", float32] in the world frame; XYZ is measured in metres. C must include XYZ; additional channels are propagated as inv_dist_std and optional obs_count when present. required
p3d_cameras PerspectiveCameras PyTorch3D candidate camera batch with image_size. required
batch_size int Batch size B. required
num_candidates int Candidate count N_q per batch item. required
device torch.device Target device for projection tensors. required

1.2.13.2 Returns

Name Type Description
dict[str, Tensor] Dictionary with screen coordinates x/y, camera depth z,
dict[str, Tensor] finite and valid masks, optional reliability channels,
dict[str, Tensor] image_size, and scalar num_cams.

1.2.14 sample_candidate_voxel_coverage

vin.geometry.sample_candidate_voxel_coverage(
    counts_norm,
    *,
    candidate_centers_world,
    pose_finite,
    t_world_voxel,
    voxel_extent,
)

Sample normalized voxel observation coverage at candidate camera centers.

1.2.14.1 Parameters

Name Type Description Default
counts_norm Tensor Tensor["B 1 D H W", float32] normalized observation-count field from the VIN scene-field bundle. required
candidate_centers_world Tensor Tensor["B N 3", float32] candidate camera centers in the world frame. required
pose_finite Tensor Tensor["B N", bool] mask for finite candidate pose encodings. Non-finite poses are forced to zero coverage. required
t_world_voxel PoseTW PoseTW["B 12"] world-from-voxel transform for the EVL grid. required
voxel_extent Tensor Tensor["B 6"] or Tensor["6"] voxel-frame grid bounds. required

1.2.14.2 Returns

Name Type Description
Tensor Tensor["B N", float32] per-candidate coverage in [0, 1].

1.2.14.3 Notes

This helper keeps candidate-center voxel sampling out of scorer forward methods. It is intentionally stateless and differentiability-neutral: sample_voxel_field uses nearest-neighbor EVL sampling, and this helper only folds in hard geometric validity plus pose finiteness.

1.2.15 sample_semidense_points

vin.geometry.sample_semidense_points(snippet, *, device, max_points)

Sample valid semidense world points from a VIN snippet.

1.2.15.1 Parameters

Name Type Description Default
snippet Any Object with the aria_nbv.data_handling.vin_store.views.VinSnippetView point contract. It must expose points_world as Tensor["P C", float32] or Tensor["B P C", float32] and optional lengths. XYZ is measured in metres, 1/sigma_d in inverse metres, and optional n_obs in channel five is a dimensionless count. required
device torch.device Target device for the returned tensor. required
max_points int Maximum sampled point count per batch item. Batched inputs are padded to this length with NaNs so candidate projection keeps a rectangular Tensor["B P_fr C", float32] layout. required

1.2.15.2 Returns

Name Type Description
Tensor Tensor["P_fr C", float32] or Tensor["B P_max C", float32] on
Tensor device.

1.2.15.3 Raises

Name Type Description
RuntimeError If the snippet has no valid points.
ValueError If the point tensor has an invalid shape, insufficient channels, mismatched lengths, or non-finite XYZ values.

1.2.16 sample_voxel_field

vin.geometry.sample_voxel_field(
    field,
    *,
    points_world,
    t_world_voxel,
    voxel_extent,
)

Sample a voxel-aligned field at world points.

World-space query points are transformed into EVL’s metric voxel frame with T_voxel_world = T_world_voxel.inverse() and then converted to voxel-grid indices with voxel_extent.

1.2.16.1 Parameters

Name Type Description Default
field Tensor Tensor["B C D H W"] voxel-aligned feature field. required
points_world Tensor Tensor["B N K 3"] world points where N is the candidate count and K is the query count per candidate. required
t_world_voxel PoseTW PoseTW["B 12"] world-from-voxel transform. required
voxel_extent Tensor Tensor["B 6"] voxel-frame bounds ordered as [x_min, x_max, y_min, y_max, z_min, z_max]. required

1.2.16.2 Returns

Name Type Description
Tensor Tuple (tokens, valid):
Tensor - tokens: Tensor["B N K C"] sampled field values.
tuple[Tensor, Tensor] - valid: Tensor["B N K", bool] extent and grid validity mask.

1.2.17 semidense_proj_feature_index

vin.geometry.semidense_proj_feature_index(name)

Resolve a canonical semidense projection feature name to its index.

1.2.17.1 Parameters

name: Canonical feature name from SEMIDENSE_PROJ_FEATURES.

1.2.17.2 Returns

int Zero-based channel index in the projection summary tensor.

1.2.17.3 Raises

ValueError If name does not identify a known projection summary feature.

Back to top