1 vin.types

vin.types

Aggregate import surface for VIN typed containers.

Leaf modules own the concrete dataclasses: backbone owns EVL exchange payloads, prediction owns scorer outputs, model_inputs owns forward-pass intermediates, and diagnostics owns debug payloads. This package initializer keeps aria_nbv.vin.types imports stable without owning duplicate definitions.

1.1 Classes

Name	Description
EvlBackboneOutput	Actor-visible EVL evidence exchanged with VIN scorers and caches.
FieldBundle	Voxel-aligned scene-field tensors built from actor-visible EVL outputs.
GlobalContext	Pose-conditioned global scene context tensors.
PoseFeatures	Reference-rig-frame features for VIN candidate views.
PreparedInputs	Prepared inputs for VIN v3-style forward passes.
QhScoreOutput	Candidate-aligned finite-horizon predictions before policy masking.
VinPrediction	VIN predictions for a candidate set.
VinV3ForwardDiagnostics	Candidate-aligned intermediate tensors from VIN-Core forward passes.

1.1.1 EvlBackboneOutput

vin.types.EvlBackboneOutput(
    t_world_voxel,
    voxel_extent,
    voxel_feat=None,
    occ_feat=None,
    obb_feat=None,
    occ_pr=None,
    occ_input=None,
    free_input=None,
    free_input_provenance=None,
    counts=None,
    counts_m=None,
    voxel_select_t=None,
    cent_pr=None,
    bbox_pr=None,
    clas_pr=None,
    cent_pr_nms=None,
    obbs_pr_nms=None,
    obb_pred=None,
    obb_pred_viz=None,
    obb_pred_sem_id_to_name=None,
    obb_pred_probs_full=None,
    obb_pred_probs_full_viz=None,
    pts_world=None,
    feat2d_upsampled=dict(),
    token2d=dict(),
)

Actor-visible EVL evidence exchanged with VIN scorers and caches.

The tensors are local to the EVL model configuration and checkpoint that produced them; they are learned evidence, not ground truth. This container does not embed source, config, or checkpoint hashes. Any durable offline payload must therefore pair it with provenance metadata that identifies the EVL source, resolved configuration, and checkpoint content.

1.1.1.1 Attributes

Name	Type	Description
t_world_voxel	`PoseTW`	`PoseTW["B 12"]` world←voxel pose for the voxel grid.
voxel_extent	`Tensor`	`Tensor["6", float32]` voxel grid extent in voxel frame `[x_min,x_max,y_min,y_max,z_min,z_max]` (meters).
voxel_feat	`Tensor` \| None	Optional `Tensor["B F D H W", float32]` raw voxel features from the 3D backbone.
occ_feat	`Tensor` \| None	Optional `Tensor["B C D H W", float32]` neck features for occupancy.
obb_feat	`Tensor` \| None	Optional `Tensor["B C D H W", float32]` neck features for OBB detection.
occ_pr	`Tensor` \| None	Optional `Tensor["B 1 D H W", float32]` EVL occupancy probability.
occ_input	`Tensor` \| None	Optional `Tensor["B 1 D H W", float32]` voxelized occupied evidence from input points.
free_input	`Tensor` \| None	Optional `Tensor["B 1 D H W", float32]` voxelized free-space evidence.
free_input_provenance	`FreeInputProvenance` \| None	Native EVL output or the explicit derived construction.
counts	`Tensor` \| None	Optional `Tensor["B D H W", int64]` per-voxel observation counts.
counts_m	`Tensor` \| None	Optional `Tensor["B D H W", int64]` masked/debug variant of counts.
voxel_select_t	`Tensor` \| None	Optional `Tensor["B 1", int64]` frame index anchoring the voxel grid.
cent_pr	`Tensor` \| None	Optional `Tensor["B 1 D H W", float32]` centerness probabilities.
bbox_pr	`Tensor` \| None	Optional `Tensor["B 7 D H W", float32]` bounding box regressions.
clas_pr	`Tensor` \| None	Optional `Tensor["B K D H W", float32]` class probabilities.
cent_pr_nms	`Tensor` \| None	Optional `Tensor["B 1 D H W", float32]` centerness after NMS.
obbs_pr_nms	`ObbTW` \| None	Optional `ObbTW["B M 34"]` OBB predictions after NMS (voxel frame).
obb_pred	`ObbTW` \| None	Optional `ObbTW["B M 34"]` OBB predictions in snippet coordinates.
obb_pred_viz	`ObbTW` \| None	Optional `ObbTW["B M 34"]` visualization OBB predictions in snippet coordinates.
obb_pred_sem_id_to_name	dict[int, str] \| None	Optional sparse semantic id to class-name map aligned with EVL taxonomy.
obb_pred_probs_full	list[`Tensor`] \| None	Optional list of per-OBB class probability tensors.
obb_pred_probs_full_viz	list[`Tensor`] \| None	Optional list of per-OBB class probability tensors for visualization.
pts_world	`Tensor` \| None	Optional `Tensor["B (D·H·W) 3", float32]` world-space voxel centers.
feat2d_upsampled	dict[str, `Tensor`]	Per-stream 2D feature maps keyed by stream name.
token2d	dict[str, `Tensor`]	Per-stream 2D tokens keyed by stream name.

1.1.1.2 Methods

Name	Description
to_serializable	Serialize this backbone output into a cache-friendly CPU payload.
from_serializable	Reconstruct one backbone output from a serialized payload.
to	Move all tensors to the specified device.

1.1.1.2.1 to_serializable

vin.types.EvlBackboneOutput.to_serializable(include_fields=None)

Serialize this backbone output into a cache-friendly CPU payload.

1.1.1.2.1.1 Parameters

Name	Type	Description	Default
include_fields	set[str] \| None	Optional dataclass field names to include. When omitted, all fields are serialized.	`None`

1.1.1.2.1.2 Returns

Name	Type	Description
	dict[str, Any]	CPU-only payload suitable for immutable offline-store records.

1.1.1.2.2 from_serializable

vin.types.EvlBackboneOutput.from_serializable(
    payload,
    *,
    device,
    include_fields=None,
)

Reconstruct one backbone output from a serialized payload.

1.1.1.2.2.1 Parameters

Name	Type	Description	Default
payload	dict[str, Any]	Serialized payload produced by `to_serializable`.	required
device	torch.device	Destination device for tensors and wrappers.	required
include_fields	set[str] \| None	Optional subset of fields to decode.	`None`

1.1.1.2.2.2 Returns

Name	Type	Description
	'EvlBackboneOutput'	Reconstructed backbone output.

1.1.1.2.3 to

vin.types.EvlBackboneOutput.to(device)

Move all tensors to the specified device.

1.1.2 FieldBundle

vin.types.FieldBundle(field_in, field, aux)

Voxel-aligned scene-field tensors built from actor-visible EVL outputs.

1.1.2.1 Attributes

Name	Description
field_in	`Tensor["B C_in D H W", float32]` raw scene field.
field	`Tensor["B C_out D H W", float32]` projected scene field.
aux	Auxiliary channels, such as normalized counts and occupancy probabilities.

1.1.3 GlobalContext

vin.types.GlobalContext(pos_grid, global_feat)

Pose-conditioned global scene context tensors.

1.1.3.1 Attributes

Name	Description
pos_grid	`Tensor["B 3 D H W", float32]` normalized voxel position grid.
global_feat	`Tensor["B N_q C", float32]` pose-conditioned global features.

1.1.4 PoseFeatures

vin.types.PoseFeatures(pose_enc, pose_vec, candidate_center_rig_m)

Reference-rig-frame features for VIN candidate views.

1.1.4.1 Attributes

Name	Description
pose_enc	`Tensor["B N_q E", float32]` pose encoder output.
pose_vec	`Tensor["B N_q D", float32]` pose vector fed into the encoder.
candidate_center_rig_m	`Tensor["B N_q 3", float32]` candidate centers in reference-rig metres.

1.1.5 PreparedInputs

vin.types.PreparedInputs(
    pose_world_cam,
    pose_world_rig_ref,
    t_world_voxel,
    batch_size,
    num_candidates,
    device,
    snippet,
)

Prepared inputs for VIN v3-style forward passes.

1.1.5.1 Attributes

Name	Type	Description
pose_world_cam	`PoseTW`	`PoseTW["B N_q 12"]` world-from-camera candidate poses.
pose_world_rig_ref	`PoseTW`	`PoseTW["B 12"]` reference rig pose in world frame.
t_world_voxel	`PoseTW`	`PoseTW["B 12"]` world←voxel pose for the EVL voxel grid.
batch_size	int	Batch size inferred from candidate poses.
num_candidates	int	Number of candidate views per batch item.
device	torch.device	Device used for tensors in the forward pass.
snippet	`VinSnippetView`	VIN snippet view with padded semidense evidence.

1.1.6 QhScoreOutput

vin.types.QhScoreOutput(conditional_q, feasibility_logits, value_auxiliary=None)

Candidate-aligned finite-horizon predictions before policy masking.

The scorer owns construction and float32 conversion. This passive container does not validate, copy, or detach tensors: autograd and storage ownership remain with their producers. B is batch, S is query state, N is candidate; a queried horizon conditions Q separately from the factual remaining budget.

1.1.6.1 Attributes

Name	Type	Description
conditional_q	Tensor	`Tensor["B S N", float32]` values conditional on an action being feasible. Materialized invalid rows are deliberately finite but are neither Q-supervised nor deployable.
feasibility_logits	Tensor	`Tensor["B S N", float32]` binary-validity logits. Positive values denote greater predicted feasibility.
value_auxiliary	QhCoralAuxiliary \| None	Optional decoder-specific training payload. CORAL supplies cumulative threshold logits and fixed Q-bin edges; regression supplies `None`. Bellman backup and online ranking always consume `conditional_q`, never this auxiliary payload.

1.1.7 VinPrediction

vin.types.VinPrediction(
    logits,
    prob,
    expected,
    expected_normalized,
    candidate_valid,
    voxel_valid_frac=None,
    semidense_candidate_vis_frac=None,
)

VIN predictions for a candidate set.

This is the primary output of aria_nbv.vin.models.scene_myopic.VinModelV3. It is consumed by the Lightning training loop (loss + metrics) and by downstream NBV selection (ranking candidates by predicted improvement). The expected score is a learned one-step ranking proxy; rollout-level endpoint metrics and cumulative target RRI are produced by rollout stores and oracle re-scoring, not by this container.

The candidate axis is row-aligned with the input poses and PyTorch3D camera batch. VinModelV3 uses row-wise maps, shared-token queries, and symmetric normalization without candidate-index embeddings. A joint permutation of aligned inputs therefore produces the same permutation of every N_q output in deterministic evaluation; training-time dropout preserves this symmetry only in distribution.

Typical usage in training (see aria_nbv/lightning/one_step/module.py): - logits / prob: CORAL ordinal loss and optional auxiliary losses. - expected_normalized: correlation/top-k metrics and candidate ranking proxy. - voxel_valid_frac / semidense_candidate_vis_frac: optional scheduled coverage reweighting of the loss + diagnostics. - candidate_valid: conservative validity heuristic used for logging and optional filtering in analysis/visualization.

1.1.7.1 Attributes

Name	Description
logits	`Tensor["B N_q K-1", float32]` CORAL threshold logits.
prob	`Tensor["B N_q K", float32]` class probabilities from the logits.
expected	`Tensor["B N_q", float32]` expected class value in `[0, K-1]`.
expected_normalized	`Tensor["B N_q", float32]` expected value normalized to `[0, 1]`.
candidate_valid	`Tensor["B N_q", bool]` candidate validity diagnostic.
voxel_valid_frac	`Tensor["B N_q", float32]` candidate voxel-coverage proxy, if available.
semidense_candidate_vis_frac	`Tensor["B N_q", float32]` candidate semidense-visibility proxy, if available.
semidense_valid_frac	Read-only compatibility alias for `semidense_candidate_vis_frac`.

1.1.8 VinV3ForwardDiagnostics

vin.types.VinV3ForwardDiagnostics(
    backbone_out,
    candidate_center_rig_m,
    pose_enc,
    pose_vec,
    field_in,
    field,
    global_feat,
    candidate_valid,
    feats,
    voxel_valid_frac=None,
    semidense_candidate_vis_frac=None,
    pos_grid=None,
    semidense_proj=None,
    semidense_grid_feat=None,
    voxel_proj=None,
    traj_feat=None,
    traj_ctx=None,
    traj_pose_vec=None,
    traj_pose_enc=None,
)

Candidate-aligned intermediate tensors from VIN-Core forward passes.

1.1.8.1 Attributes

Name	Description
backbone_out	EVL backbone outputs used to build the scene field.
candidate_center_rig_m	`Tensor["B N_q 3", float32]` candidate centers in reference-rig metres.
pose_enc	`Tensor["B N_q E_pose", float32]` pose encoder output.
pose_vec	`Tensor["B N_q D_pose", float32]` pose vector fed into the encoder.
field_in	`Tensor["B C_in D H W", float32]` Raw scene field before projection.
field	`Tensor["B C_out D H W", float32]` Projected scene field.
global_feat	`Tensor["B N_q C_global", float32]` pose-conditioned global features.
candidate_valid	`Tensor["B N_q", bool]` diagnostic candidate-valid mask.
feats	`Tensor["B N_q F", float32]` concatenated VIN candidate features.
voxel_valid_frac	`Tensor["B N_q", float32]` candidate voxel-coverage proxy, if computed.
semidense_candidate_vis_frac	`Tensor["B N_q", float32]` candidate semidense visibility, if computed.
semidense_valid_frac	Read-only compatibility alias for `semidense_candidate_vis_frac`.
pos_grid	`Tensor["B 3 D H W", float32]` Normalized voxel position grid (if computed).
semidense_proj	`Tensor["B N_q C_proj", float32]` semidense projection features.
semidense_grid_feat	`Tensor["B N_q C_cnn", float32]` CNN projection-grid features.
voxel_proj	`Tensor["B N_q C_proj", float32]` voxel-projection features.
traj_feat	`Tensor["B F_traj", float32]` Pooled trajectory embedding (if enabled).
traj_ctx	`Tensor["B N_q F_pose", float32]` trajectory context per candidate query.
traj_pose_vec	`Tensor["B T D_v", float32]` Per-frame trajectory pose vectors.
traj_pose_enc	`Tensor["B T F_traj", float32]` Per-frame trajectory pose encodings.

1.2 Functions

Name	Description
validate_free_input_provenance	Validate and narrow the persisted free-input provenance label.

1.2.1 validate_free_input_provenance

vin.types.validate_free_input_provenance(value)

Validate and narrow the persisted free-input provenance label.

# vin.types { #aria_nbv.vin.types } `vin.types` Aggregate import surface for VIN typed containers. Leaf modules own the concrete dataclasses: `backbone` owns EVL exchange payloads, `prediction` owns scorer outputs, `model_inputs` owns forward-pass intermediates, and `diagnostics` owns debug payloads. This package initializer keeps `aria_nbv.vin.types` imports stable without owning duplicate definitions. ## Classes | Name | Description | | --- | --- | | [EvlBackboneOutput](#aria_nbv.vin.types.EvlBackboneOutput) | Actor-visible EVL evidence exchanged with VIN scorers and caches. | | [FieldBundle](#aria_nbv.vin.types.FieldBundle) | Voxel-aligned scene-field tensors built from actor-visible EVL outputs. | | [GlobalContext](#aria_nbv.vin.types.GlobalContext) | Pose-conditioned global scene context tensors. | | [PoseFeatures](#aria_nbv.vin.types.PoseFeatures) | Reference-rig-frame features for VIN candidate views. | | [PreparedInputs](#aria_nbv.vin.types.PreparedInputs) | Prepared inputs for VIN v3-style forward passes. | | [QhScoreOutput](#aria_nbv.vin.types.QhScoreOutput) | Candidate-aligned finite-horizon predictions before policy masking. | | [VinPrediction](#aria_nbv.vin.types.VinPrediction) | VIN predictions for a candidate set. | | [VinV3ForwardDiagnostics](#aria_nbv.vin.types.VinV3ForwardDiagnostics) | Candidate-aligned intermediate tensors from VIN-Core forward passes. | ### EvlBackboneOutput { #aria_nbv.vin.types.EvlBackboneOutput } ```python vin.types.EvlBackboneOutput( t_world_voxel, voxel_extent, voxel_feat=None, occ_feat=None, obb_feat=None, occ_pr=None, occ_input=None, free_input=None, free_input_provenance=None, counts=None, counts_m=None, voxel_select_t=None, cent_pr=None, bbox_pr=None, clas_pr=None, cent_pr_nms=None, obbs_pr_nms=None, obb_pred=None, obb_pred_viz=None, obb_pred_sem_id_to_name=None, obb_pred_probs_full=None, obb_pred_probs_full_viz=None, pts_world=None, feat2d_upsampled=dict(), token2d=dict(), ) ``` Actor-visible EVL evidence exchanged with VIN scorers and caches. The tensors are local to the EVL model configuration and checkpoint that produced them; they are learned evidence, not ground truth. This container does not embed source, config, or checkpoint hashes. Any durable offline payload must therefore pair it with provenance metadata that identifies the EVL source, resolved configuration, and checkpoint content. #### Attributes {.doc-section .doc-section-attributes} | Name | Type | Description | |-------------------------|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------| | t_world_voxel | [PoseTW](`efm3d.aria.pose.PoseTW`) | ``PoseTW["B 12"]`` world←voxel pose for the voxel grid. | | voxel_extent | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) | ``Tensor["6", float32]`` voxel grid extent in voxel frame ``[x_min,x_max,y_min,y_max,z_min,z_max]`` (meters). | | voxel_feat | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B F D H W", float32]`` raw voxel features from the 3D backbone. | | occ_feat | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B C D H W", float32]`` neck features for occupancy. | | obb_feat | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B C D H W", float32]`` neck features for OBB detection. | | occ_pr | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B 1 D H W", float32]`` EVL occupancy probability. | | occ_input | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B 1 D H W", float32]`` voxelized occupied evidence from input points. | | free_input | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B 1 D H W", float32]`` voxelized free-space evidence. | | free_input_provenance | [FreeInputProvenance](`aria_nbv.vin.types.backbone.FreeInputProvenance`) \| None | Native EVL output or the explicit derived construction. | | counts | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B D H W", int64]`` per-voxel observation counts. | | counts_m | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B D H W", int64]`` masked/debug variant of counts. | | voxel_select_t | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B 1", int64]`` frame index anchoring the voxel grid. | | cent_pr | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B 1 D H W", float32]`` centerness probabilities. | | bbox_pr | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B 7 D H W", float32]`` bounding box regressions. | | clas_pr | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B K D H W", float32]`` class probabilities. | | cent_pr_nms | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B 1 D H W", float32]`` centerness after NMS. | | obbs_pr_nms | [ObbTW](`efm3d.aria.obb.ObbTW`) \| None | Optional ``ObbTW["B M 34"]`` OBB predictions after NMS (voxel frame). | | obb_pred | [ObbTW](`efm3d.aria.obb.ObbTW`) \| None | Optional ``ObbTW["B M 34"]`` OBB predictions in snippet coordinates. | | obb_pred_viz | [ObbTW](`efm3d.aria.obb.ObbTW`) \| None | Optional ``ObbTW["B M 34"]`` visualization OBB predictions in snippet coordinates. | | obb_pred_sem_id_to_name | [dict](`dict`)\[[int](`int`), [str](`str`)\] \| None | Optional sparse semantic id to class-name map aligned with EVL taxonomy. | | obb_pred_probs_full | [list](`list`)\[[Tensor](`aria_nbv.vin.types.backbone.Tensor`)\] \| None | Optional list of per-OBB class probability tensors. | | obb_pred_probs_full_viz | [list](`list`)\[[Tensor](`aria_nbv.vin.types.backbone.Tensor`)\] \| None | Optional list of per-OBB class probability tensors for visualization. | | pts_world | [Tensor](`aria_nbv.vin.types.backbone.Tensor`) \| None | Optional ``Tensor["B (D·H·W) 3", float32]`` world-space voxel centers. | | feat2d_upsampled | [dict](`dict`)\[[str](`str`), [Tensor](`aria_nbv.vin.types.backbone.Tensor`)\] | Per-stream 2D feature maps keyed by stream name. | | token2d | [dict](`dict`)\[[str](`str`), [Tensor](`aria_nbv.vin.types.backbone.Tensor`)\] | Per-stream 2D tokens keyed by stream name. | #### Methods | Name | Description | | --- | --- | | [to_serializable](#aria_nbv.vin.types.EvlBackboneOutput.to_serializable) | Serialize this backbone output into a cache-friendly CPU payload. | | [from_serializable](#aria_nbv.vin.types.EvlBackboneOutput.from_serializable) | Reconstruct one backbone output from a serialized payload. | | [to](#aria_nbv.vin.types.EvlBackboneOutput.to) | Move all tensors to the specified device. | ##### to_serializable { #aria_nbv.vin.types.EvlBackboneOutput.to_serializable } ```python vin.types.EvlBackboneOutput.to_serializable(include_fields=None) ``` Serialize this backbone output into a cache-friendly CPU payload. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |----------------|--------------------------------------|-------------------------------------------------------------------------------------|-----------| | include_fields | [set](`set`)\[[str](`str`)\] \| None | Optional dataclass field names to include. When omitted, all fields are serialized. | `None` | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|-----------------------------------------------------|----------------------------------------------------------------| | | [dict](`dict`)\[[str](`str`), [Any](`typing.Any`)\] | CPU-only payload suitable for immutable offline-store records. | ##### from_serializable { #aria_nbv.vin.types.EvlBackboneOutput.from_serializable } ```python vin.types.EvlBackboneOutput.from_serializable( payload, *, device, include_fields=None, ) ``` Reconstruct one backbone output from a serialized payload. ###### Parameters {.doc-section .doc-section-parameters} | Name | Type | Description | Default | |----------------|-----------------------------------------------------|---------------------------------------------------|------------| | payload | [dict](`dict`)\[[str](`str`), [Any](`typing.Any`)\] | Serialized payload produced by `to_serializable`. | _required_ | | device | [torch](`torch`).[device](`torch.device`) | Destination device for tensors and wrappers. | _required_ | | include_fields | [set](`set`)\[[str](`str`)\] \| None | Optional subset of fields to decode. | `None` | ###### Returns {.doc-section .doc-section-returns} | Name | Type | Description | |--------|-----------------------|--------------------------------| | | \'EvlBackboneOutput\' | Reconstructed backbone output. | ##### to { #aria_nbv.vin.types.EvlBackboneOutput.to } ```python vin.types.EvlBackboneOutput.to(device) ``` Move all tensors to the specified device. ### FieldBundle { #aria_nbv.vin.types.FieldBundle } ```python vin.types.FieldBundle(field_in, field, aux) ``` Voxel-aligned scene-field tensors built from actor-visible EVL outputs. #### Attributes | Name | Description | | --- | --- | | [field_in](#aria_nbv.vin.types.FieldBundle.field_in) | ``Tensor["B C_in D H W", float32]`` raw scene field. | | [field](#aria_nbv.vin.types.FieldBundle.field) | ``Tensor["B C_out D H W", float32]`` projected scene field. | | [aux](#aria_nbv.vin.types.FieldBundle.aux) | Auxiliary channels, such as normalized counts and occupancy probabilities. | ### GlobalContext { #aria_nbv.vin.types.GlobalContext } ```python vin.types.GlobalContext(pos_grid, global_feat) ``` Pose-conditioned global scene context tensors. #### Attributes | Name | Description | | --- | --- | | [pos_grid](#aria_nbv.vin.types.GlobalContext.pos_grid) | ``Tensor["B 3 D H W", float32]`` normalized voxel position grid. | | [global_feat](#aria_nbv.vin.types.GlobalContext.global_feat) | ``Tensor["B N_q C", float32]`` pose-conditioned global features. | ### PoseFeatures { #aria_nbv.vin.types.PoseFeatures } ```python vin.types.PoseFeatures(pose_enc, pose_vec, candidate_center_rig_m) ``` Reference-rig-frame features for VIN candidate views. #### Attributes | Name | Description | | --- | --- | | [pose_enc](#aria_nbv.vin.types.PoseFeatures.pose_enc) | ``Tensor["B N_q E", float32]`` pose encoder output. | | [pose_vec](#aria_nbv.vin.types.PoseFeatures.pose_vec) | ``Tensor["B N_q D", float32]`` pose vector fed into the encoder. | | [candidate_center_rig_m](#aria_nbv.vin.types.PoseFeatures.candidate_center_rig_m) | ``Tensor["B N_q 3", float32]`` candidate centers in reference-rig metres. | ### PreparedInputs { #aria_nbv.vin.types.PreparedInputs } ```python vin.types.PreparedInputs( pose_world_cam, pose_world_rig_ref, t_world_voxel, batch_size, num_candidates, device, snippet, ) ``` Prepared inputs for VIN v3-style forward passes. #### Attributes {.doc-section .doc-section-attributes} | Name | Type | Description | |--------------------|-----------------------------------------------------------|-------------------------------------------------------------| | pose_world_cam | [PoseTW](`efm3d.aria.pose.PoseTW`) | ``PoseTW["B N_q 12"]`` world-from-camera candidate poses. | | pose_world_rig_ref | [PoseTW](`efm3d.aria.pose.PoseTW`) | ``PoseTW["B 12"]`` reference rig pose in world frame. | | t_world_voxel | [PoseTW](`efm3d.aria.pose.PoseTW`) | ``PoseTW["B 12"]`` world←voxel pose for the EVL voxel grid. | | batch_size | [int](`int`) | Batch size inferred from candidate poses. | | num_candidates | [int](`int`) | Number of candidate views per batch item. | | device | [torch](`torch`).[device](`torch.device`) | Device used for tensors in the forward pass. | | snippet | [VinSnippetView](`aria_nbv.data_handling.VinSnippetView`) | VIN snippet view with padded semidense evidence. | ### QhScoreOutput { #aria_nbv.vin.types.QhScoreOutput } ```python vin.types.QhScoreOutput(conditional_q, feasibility_logits, value_auxiliary=None) ``` Candidate-aligned finite-horizon predictions before policy masking. The scorer owns construction and float32 conversion. This passive container does not validate, copy, or detach tensors: autograd and storage ownership remain with their producers. B is batch, S is query state, N is candidate; a queried horizon conditions Q separately from the factual remaining budget. #### Attributes {.doc-section .doc-section-attributes} | Name | Type | Description | |--------------------|------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | conditional_q | [Tensor](`torch.Tensor`) | ``Tensor["B S N", float32]`` values conditional on an action being feasible. Materialized invalid rows are deliberately finite but are neither Q-supervised nor deployable. | | feasibility_logits | [Tensor](`torch.Tensor`) | ``Tensor["B S N", float32]`` binary-validity logits. Positive values denote greater predicted feasibility. | | value_auxiliary | [QhCoralAuxiliary](`aria_nbv.vin.types.prediction.QhCoralAuxiliary`) \| None | Optional decoder-specific training payload. CORAL supplies cumulative threshold logits and fixed Q-bin edges; regression supplies ``None``. Bellman backup and online ranking always consume ``conditional_q``, never this auxiliary payload. | ### VinPrediction { #aria_nbv.vin.types.VinPrediction } ```python vin.types.VinPrediction( logits, prob, expected, expected_normalized, candidate_valid, voxel_valid_frac=None, semidense_candidate_vis_frac=None, ) ``` VIN predictions for a candidate set. This is the primary output of `aria_nbv.vin.models.scene_myopic.VinModelV3`. It is consumed by the Lightning training loop (loss + metrics) and by downstream NBV selection (ranking candidates by predicted improvement). The expected score is a learned one-step ranking proxy; rollout-level endpoint metrics and cumulative target RRI are produced by rollout stores and oracle re-scoring, not by this container. The candidate axis is row-aligned with the input poses and PyTorch3D camera batch. ``VinModelV3`` uses row-wise maps, shared-token queries, and symmetric normalization without candidate-index embeddings. A joint permutation of aligned inputs therefore produces the same permutation of every ``N_q`` output in deterministic evaluation; training-time dropout preserves this symmetry only in distribution. Typical usage in training (see ``aria_nbv/lightning/one_step/module.py``): - ``logits`` / ``prob``: CORAL ordinal loss and optional auxiliary losses. - ``expected_normalized``: correlation/top-k metrics and candidate ranking proxy. - ``voxel_valid_frac`` / ``semidense_candidate_vis_frac``: optional scheduled coverage reweighting of the loss + diagnostics. - ``candidate_valid``: conservative validity heuristic used for logging and optional filtering in analysis/visualization. #### Attributes | Name | Description | | --- | --- | | [logits](#aria_nbv.vin.types.VinPrediction.logits) | ``Tensor["B N_q K-1", float32]`` CORAL threshold logits. | | [prob](#aria_nbv.vin.types.VinPrediction.prob) | ``Tensor["B N_q K", float32]`` class probabilities from the logits. | | [expected](#aria_nbv.vin.types.VinPrediction.expected) | ``Tensor["B N_q", float32]`` expected class value in ``[0, K-1]``. | | [expected_normalized](#aria_nbv.vin.types.VinPrediction.expected_normalized) | ``Tensor["B N_q", float32]`` expected value normalized to ``[0, 1]``. | | [candidate_valid](#aria_nbv.vin.types.VinPrediction.candidate_valid) | ``Tensor["B N_q", bool]`` candidate validity diagnostic. | | [voxel_valid_frac](#aria_nbv.vin.types.VinPrediction.voxel_valid_frac) | ``Tensor["B N_q", float32]`` candidate voxel-coverage proxy, if available. | | [semidense_candidate_vis_frac](#aria_nbv.vin.types.VinPrediction.semidense_candidate_vis_frac) | ``Tensor["B N_q", float32]`` candidate semidense-visibility proxy, if available. | | [semidense_valid_frac](#aria_nbv.vin.types.VinPrediction.semidense_valid_frac) | Read-only compatibility alias for ``semidense_candidate_vis_frac``. | ### VinV3ForwardDiagnostics { #aria_nbv.vin.types.VinV3ForwardDiagnostics } ```python vin.types.VinV3ForwardDiagnostics( backbone_out, candidate_center_rig_m, pose_enc, pose_vec, field_in, field, global_feat, candidate_valid, feats, voxel_valid_frac=None, semidense_candidate_vis_frac=None, pos_grid=None, semidense_proj=None, semidense_grid_feat=None, voxel_proj=None, traj_feat=None, traj_ctx=None, traj_pose_vec=None, traj_pose_enc=None, ) ``` Candidate-aligned intermediate tensors from VIN-Core forward passes. #### Attributes | Name | Description | | --- | --- | | [backbone_out](#aria_nbv.vin.types.VinV3ForwardDiagnostics.backbone_out) | EVL backbone outputs used to build the scene field. | | [candidate_center_rig_m](#aria_nbv.vin.types.VinV3ForwardDiagnostics.candidate_center_rig_m) | ``Tensor["B N_q 3", float32]`` candidate centers in reference-rig metres. | | [pose_enc](#aria_nbv.vin.types.VinV3ForwardDiagnostics.pose_enc) | ``Tensor["B N_q E_pose", float32]`` pose encoder output. | | [pose_vec](#aria_nbv.vin.types.VinV3ForwardDiagnostics.pose_vec) | ``Tensor["B N_q D_pose", float32]`` pose vector fed into the encoder. | | [field_in](#aria_nbv.vin.types.VinV3ForwardDiagnostics.field_in) | ``Tensor["B C_in D H W", float32]`` Raw scene field before projection. | | [field](#aria_nbv.vin.types.VinV3ForwardDiagnostics.field) | ``Tensor["B C_out D H W", float32]`` Projected scene field. | | [global_feat](#aria_nbv.vin.types.VinV3ForwardDiagnostics.global_feat) | ``Tensor["B N_q C_global", float32]`` pose-conditioned global features. | | [candidate_valid](#aria_nbv.vin.types.VinV3ForwardDiagnostics.candidate_valid) | ``Tensor["B N_q", bool]`` diagnostic candidate-valid mask. | | [feats](#aria_nbv.vin.types.VinV3ForwardDiagnostics.feats) | ``Tensor["B N_q F", float32]`` concatenated VIN candidate features. | | [voxel_valid_frac](#aria_nbv.vin.types.VinV3ForwardDiagnostics.voxel_valid_frac) | ``Tensor["B N_q", float32]`` candidate voxel-coverage proxy, if computed. | | [semidense_candidate_vis_frac](#aria_nbv.vin.types.VinV3ForwardDiagnostics.semidense_candidate_vis_frac) | ``Tensor["B N_q", float32]`` candidate semidense visibility, if computed. | | [semidense_valid_frac](#aria_nbv.vin.types.VinV3ForwardDiagnostics.semidense_valid_frac) | Read-only compatibility alias for ``semidense_candidate_vis_frac``. | | [pos_grid](#aria_nbv.vin.types.VinV3ForwardDiagnostics.pos_grid) | ``Tensor["B 3 D H W", float32]`` Normalized voxel position grid (if computed). | | [semidense_proj](#aria_nbv.vin.types.VinV3ForwardDiagnostics.semidense_proj) | ``Tensor["B N_q C_proj", float32]`` semidense projection features. | | [semidense_grid_feat](#aria_nbv.vin.types.VinV3ForwardDiagnostics.semidense_grid_feat) | ``Tensor["B N_q C_cnn", float32]`` CNN projection-grid features. | | [voxel_proj](#aria_nbv.vin.types.VinV3ForwardDiagnostics.voxel_proj) | ``Tensor["B N_q C_proj", float32]`` voxel-projection features. | | [traj_feat](#aria_nbv.vin.types.VinV3ForwardDiagnostics.traj_feat) | ``Tensor["B F_traj", float32]`` Pooled trajectory embedding (if enabled). | | [traj_ctx](#aria_nbv.vin.types.VinV3ForwardDiagnostics.traj_ctx) | ``Tensor["B N_q F_pose", float32]`` trajectory context per candidate query. | | [traj_pose_vec](#aria_nbv.vin.types.VinV3ForwardDiagnostics.traj_pose_vec) | ``Tensor["B T D_v", float32]`` Per-frame trajectory pose vectors. | | [traj_pose_enc](#aria_nbv.vin.types.VinV3ForwardDiagnostics.traj_pose_enc) | ``Tensor["B T F_traj", float32]`` Per-frame trajectory pose encodings. | ## Functions | Name | Description | | --- | --- | | [validate_free_input_provenance](#aria_nbv.vin.types.validate_free_input_provenance) | Validate and narrow the persisted free-input provenance label. | ### validate_free_input_provenance { #aria_nbv.vin.types.validate_free_input_provenance } ```python vin.types.validate_free_input_provenance(value) ``` Validate and narrow the persisted free-input provenance label.