1 vin.geometry.voxel

vin.geometry.voxel

Voxel-field geometry helpers for VIN scorers.

This module owns stateless operations on EVL voxel fields: sampling fields at world points, deriving compact scene-field channels, converting flattened voxel centers into normalized grids, and pooling voxel center points. Model classes remain responsible for neural projections and scorer heads.

1.1 Functions

Name Description
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.
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.
sample_voxel_field Sample a voxel-aligned field at world points.

1.1.1 build_scene_field

vin.geometry.voxel.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.1.1.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.1.1.2 Returns

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

1.1.2 candidate_valid_from_token

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

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

1.1.3 center_crop_grid

vin.geometry.voxel.center_crop_grid(grid, target_shape)

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

1.1.4 infer_padded_grid_shape

vin.geometry.voxel.infer_padded_grid_shape(num_pts, target_shape)

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

1.1.5 pool_voxel_points

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

Downsample voxel center points to a pooled token grid.

1.1.5.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.1.5.2 Returns

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

1.1.6 pos_grid_from_pts_world

vin.geometry.voxel.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.1.7 sample_voxel_field

vin.geometry.voxel.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.1.7.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.1.7.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.
Back to top