1 vin.geometry.semidense_projection

vin.geometry.semidense_projection

Semidense point projection helpers shared by VIN scorers.

The active aria_nbv.vin.models.scene_myopic scorer uses semidense ASE/EFM points as actor-visible scene evidence. This module owns the stateless tensor operations for that path:

• sample valid VinSnippetView.points_world rows,
• project world points into PyTorch3D candidate cameras,
• encode scalar projection statistics, and
• build screen-space grids consumed by model-owned CNN encoders.

Keeping those operations outside the scorer class makes the geometry contract testable without constructing the full model while preserving the neural module ownership boundary in aria_nbv.vin.models.scene_myopic.VinModelV3.

1.1 Functions

Name	Description
build_projection_grid	Build per-camera semidense projection grids for CNN encoders.
encode_projection_summary	Summarize semidense projection coverage, visibility, and depth.
project_points_to_candidate_cameras	Project world points into a batch of candidate cameras.
sample_semidense_points	Sample valid semidense world points from a VIN snippet.

1.1.1 build_projection_grid

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

Build per-camera semidense projection grids for CNN encoders.

1.1.1.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.1.1.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.1.2 encode_projection_summary

vin.geometry.semidense_projection.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.1.2.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.1.2.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.1.3 project_points_to_candidate_cameras

vin.geometry.semidense_projection.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.1.3.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.1.3.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.1.4 sample_semidense_points

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

Sample valid semidense world points from a VIN snippet.

1.1.4.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.1.4.2 Returns

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

1.1.4.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.