1 vin.scorer_context

vin.scorer_context

Shared tensor preparation for VIN scorer forward passes.

The helpers in this module are intentionally stateless. Model classes own their torch.nn.Module instances, while this sidecar owns the repeatable pose-frame and voxel-position transformations used by the maintained v2 and v3 scorers.

1.1 Functions

Name Description
apply_vin_scorer_film Apply FiLM modulation to per-candidate global scene features.
build_vin_scorer_scene_field Build the soft-coverage scene field used by maintained VIN scorers.
compute_global_context Pool pose-conditioned scene context over the shared voxel field.
encode_pose_features Encode candidates after converting world-camera poses into the reference rig frame.
encode_trajectory_context Encode snippet rig trajectory poses in the reference rig frame.

1.1.1 apply_vin_scorer_film

vin.scorer_context.apply_vin_scorer_film(global_feat, cond_feat, *, film, norm)

Apply FiLM modulation to per-candidate global scene features.

Concrete scorer models own the trainable FiLM projection and optional normalization modules. This stateless helper only applies the shared global * (1 + gamma) + beta formula and preserves candidate-axis broadcasting when cond_feat has shape Tensor["B 1 F"].

1.1.1.1 Parameters

Name Type Description Default
global_feat Tensor Tensor["B Nq F_g"] global features to modulate. required
cond_feat Tensor Tensor["B Nq F_c"] or Tensor["B 1 F_c"] conditioning features consumed by film. required
film nn.Module Module that maps cond_feat to 2 * F_g FiLM parameters. required
norm nn.GroupNorm | None Optional GroupNorm over F_g channels. required

1.1.1.2 Returns

Name Type Description
Tensor Tensor["B Nq F_g"] after FiLM and optional normalization.

1.1.2 build_vin_scorer_scene_field

vin.scorer_context.build_vin_scorer_scene_field(
    backbone_out,
    *,
    scene_field_channels,
    model_name,
)

Build the soft-coverage scene field used by maintained VIN scorers.

This helper preserves the V2/V3 scorer contract where unknown is defined as 1 - counts_norm rather than the geometry helper’s binary 1 - observed contract. The returned field_in is still unprojected; concrete models own the trainable field_proj module and wrap the result in aria_nbv.vin.types.FieldBundle.

1.1.2.1 Parameters

Name Type Description Default
backbone_out EvlBackboneOutput EVL backbone outputs with occupancy, centerness, observation count, and optional free-space tensors. required
scene_field_channels Sequence[str] Ordered channel names to concatenate. required
model_name str Name included in validation errors, e.g. "VinModelV3". required

1.1.2.2 Returns

Name Type Description
Tensor Tuple of (field_in, field_aux) where field_in has shape
dict[str, Tensor] Tensor["B C D H W"] and field_aux maps every derived channel to
tuple[Tensor, dict[str, Tensor]] its single-channel tensor.

1.1.3 compute_global_context

vin.scorer_context.compute_global_context(
    global_pooler,
    field,
    pose_enc,
    pts_world,
    t_world_voxel,
    pose_world_rig_ref,
    voxel_extent,
)

Pool pose-conditioned scene context over the shared voxel field.

The positional grid is expressed relative to the reference rig frame before PoseConditionedGlobalPool consumes it. The returned tensors preserve the field device and dtype so downstream scorer heads can concatenate features without implicit casts.

1.1.4 encode_pose_features

vin.scorer_context.encode_pose_features(
    pose_encoder,
    pose_world_cam,
    pose_world_rig_ref,
)

Encode candidates after converting world-camera poses into the reference rig frame.

1.1.4.1 Parameters

Name Type Description Default
pose_encoder Any Encoder object exposing encode(PoseTW). required
pose_world_cam PoseTW Candidate camera poses as PoseTW with shape compatible with Tensor["B Q ..."]. required
pose_world_rig_ref PoseTW Reference rig pose for each batch item. required

1.1.4.2 Returns

Name Type Description
PoseFeatures PoseFeatures containing the pose embedding, raw pose vector, and
PoseFeatures candidate centers in reference-rig meters.

1.1.5 encode_trajectory_context

vin.scorer_context.encode_trajectory_context(
    traj_encoder,
    snippet,
    pose_world_rig_ref,
    batch_size,
    device,
    dtype,
)

Encode snippet rig trajectory poses in the reference rig frame.

Maintained VIN scorers use this helper to share the deterministic trajectory preparation step while keeping attention modules and scorer-head ownership inside each model. The snippet trajectory is interpreted as world-from-rig poses T_w_rig_t and converted to reference-rig coordinates via T_r_ref_rig_t = (T_w_r_ref)^-1 @ T_w_rig_t before the configured aria_nbv.vin.encoders.trajectory.TrajectoryEncoder consumes it.

1.1.5.1 Parameters

Name Type Description Default
traj_encoder Any | None Optional trajectory encoder. When None, the helper returns (None, None, None). required
snippet EfmSnippetView | VinSnippetView | None VIN or EFM snippet view carrying t_world_rig. Missing trajectories produce a zero pooled feature and no per-frame tensors, preserving the existing V2/V3 fallback. required
pose_world_rig_ref PoseTW PoseTW["B 12"] reference rig poses T_w_r. required
batch_size int Batch size B used for broadcast validation. required
device torch.device Target device for trajectory tensors and outputs. required
dtype torch.dtype Output dtype. required

1.1.5.2 Returns

Name Type Description
Tensor | None Tuple (traj_feat, traj_pose_vec, traj_pose_enc) where
Tensor | None traj_feat is Tensor["B F_traj"] when an encoder is configured,
Tensor | None and the per-frame tensors are None when no trajectory poses are
tuple[Tensor | None, Tensor | None, Tensor | None] available.
Back to top