1 vin.encoders

vin.encoders

Encoder modules for VIN candidate, trajectory, and coordinate features.

The package owns torch.nn.Module encoders used by VIN scorer architectures. Use fourier for learnable continuous coordinate embeddings, pose for candidate SE(3) pose encoders, shell_pose for shell-sampled candidates, and trajectory for snippet trajectory summaries.

1.1 Attributes

Name	Description
TARGET_CURRENT_GEOMETRY_FEATURES	Column names for the emitted geometry values and availability mask.
TARGET_CURRENT_GEOMETRY_UNITS	Physical units in the order of TARGET_CURRENT_GEOMETRY_FEATURES.

1.2 Classes

Name	Description
FourierFeatures	Sin/cos Fourier features with optional learnable frequencies.
FourierFeaturesConfig	Config-as-factory wrapper for FourierFeatures.
LearnableFourierFeatures	Learnable Fourier Features (LFF) positional encoding.
LearnableFourierFeaturesConfig	Config-as-factory wrapper for LearnableFourierFeatures.
PointNeXtSEncoder	Adapt OpenPoints PointNeXt-S to a VIN semidense point-cloud embedding.
PointNeXtSEncoderConfig	Config-as-factory wrapper for PointNeXtSEncoder.
PoseEncoder	Base interface for encoders of poses already in a reference frame.
PoseEncodingOutput	Pose-encoding outputs for a pose expressed in a reference frame.
R6dLffPoseEncoder	Encode reference-frame translation and rotation-6D through LFF.
R6dLffPoseEncoderConfig	Configure reference-frame R6D plus LFF pose encoding.
ShellLffPoseEncoder	Encode canonical shell descriptors with learned Fourier features.
ShellLffPoseEncoderConfig	Config-as-factory wrapper for ShellLffPoseEncoder.
ShellShPoseEncoder	Encode shell-based pose descriptors using spherical harmonics.
ShellShPoseEncoderAdapter	Adapt ShellShPoseEncoder to the common pose-encoder interface.
ShellShPoseEncoderAdapterConfig	Config-as-factory wrapper for ShellShPoseEncoderAdapter.
ShellShPoseEncoderConfig	Config-as-factory wrapper for ShellShPoseEncoder.
TargetCurrentFrame	Canonical target/current frame shared by candidate and history encoders.
TargetCurrentGeometryEncoder	Encode candidates in a shared target/current canonical frame.
TargetCurrentGeometryEncoderConfig	Configure the fixed-layout target/current candidate geometry module.
TargetCurrentGeometryOutput	Candidate-aligned geometry values and measurement availability.
TrajectoryEncoder	Encode EFM trajectory poses with an R6D + LFF pose encoder.
TrajectoryEncoderConfig	Configure per-frame pose encoding and sequence reduction.
TrajectoryEncodingOutput	Trajectory encoding outputs.

1.2.1 FourierFeatures

vin.encoders.FourierFeatures(config)

Sin/cos Fourier features with optional learnable frequencies.

1.2.1.1 Parameters

Name	Type	Description	Default
config	'FourierFeaturesConfig'	Config-as-factory object defining input dimension, number of frequencies, raw-input concatenation, and frequency initialization.	required

1.2.1.2 Attributes

Name	Description
output_dim	Return the raw-input plus sine/cosine output width.

1.2.1.3 Methods

Name	Description
forward	Apply Fourier feature mapping to inputs.

1.2.1.3.1 forward

vin.encoders.FourierFeatures.forward(x)

Apply Fourier feature mapping to inputs.

1.2.1.3.1.1 Parameters

Name	Type	Description	Default
x	Tensor	Tensor["... D", float32] input vectors.	required

1.2.1.3.1.2 Returns

Name	Type	Description
	Tensor	Tensor["... output_dim", float32] Fourier-encoded features.

1.2.2 FourierFeaturesConfig

vin.encoders.FourierFeaturesConfig()

Config-as-factory wrapper for FourierFeatures.

The emitted module has no hidden MLP; it only returns raw inputs and normalized sin/cos features. Use aria_nbv.vin.encoders.fourier.LearnableFourierFeaturesConfig when the projection should be followed by a trainable MLP.

1.2.2.1 Attributes

Name	Description
target_type	Return the runtime module type constructed by this config.
input_dim	Input dimensionality.
num_frequencies	Number of Fourier frequencies.
include_input	Concatenate raw inputs to the Fourier features when True.
learnable	Whether the frequency matrix is learnable.
init_scale	Stddev used to initialize the frequency matrix.

1.2.3 LearnableFourierFeatures

vin.encoders.LearnableFourierFeatures(config)

Learnable Fourier Features (LFF) positional encoding.

This module maps continuous inputs \(x \in \mathbb{R}^D\) into a learned feature space by:

1. learning a projection matrix \(W_r\),
2. applying sinusoidal features, and
3. mapping them through a small MLP.

Compared to fixed random Fourier features, the learned projection and the MLP allow the encoding to adapt to the downstream task. This is a learned coordinate-feature inductive bias; the arbitrary projection and MLP do not enforce translation, rotation, or SE(3) equivariance.

1.2.3.1 Attributes

Name	Description
out_dim	Return the emitted feature dimension, including raw inputs when enabled.

1.2.3.2 Methods

Name	Description
forward	Encode vectors with learned sinusoidal features.

1.2.3.2.1 forward

vin.encoders.LearnableFourierFeatures.forward(x)

Encode vectors with learned sinusoidal features.

1.2.3.2.1.1 Parameters

Name	Type	Description	Default
x	Tensor	Tensor["... D"] input vectors with D == input_dim.	required

1.2.3.2.1.2 Returns

Name	Type	Description
	Tensor	Tensor["... E"] encoded vectors, optionally concatenated with
	Tensor	the raw input when LearnableFourierFeaturesConfig.include_input
	Tensor	is enabled.

1.2.4 LearnableFourierFeaturesConfig

vin.encoders.LearnableFourierFeaturesConfig()

Config-as-factory wrapper for LearnableFourierFeatures.

1.2.4.1 Attributes

Name	Description
target_type	Factory target for aria_nbv.configs.base.BaseConfig.setup_target.
out_dim	Return the width emitted by this configuration.
input_dim	Input dimensionality (default: 6 for SE(3) relative pose as translation + so(3) log).
fourier_dim	Fourier feature dimensionality (must be even).
hidden_dim	Hidden dimension of the internal MLP.
output_dim	Output positional encoding dimensionality (per input vector).
gamma	Initialization scale (paper parameter \(\gamma\)).
include_input	Concatenate raw inputs to the learned encoding when True.

1.2.5 PointNeXtSEncoder

vin.encoders.PointNeXtSEncoder(config)

Adapt OpenPoints PointNeXt-S to a VIN semidense point-cloud embedding.

1.2.5.1 Parameters

Name	Type	Description	Default
config	PointNeXtSEncoderConfig	Config-as-factory object containing OpenPoints config/checkpoint paths, output projection dimension, and freezing behavior.	required

1.2.5.2 Notes

The wrapped OpenPoints model is loaded lazily at module construction, not at package import time. Active scorer configs must explicitly own whether this optional path participates in a model.

The adapter makes no stronger symmetry claim than the configured OpenPoints model. Its final spatial mean is order-insensitive, but that alone does not establish graph-isomorphism or rigid-motion invariance for the upstream PointNeXt computation.

1.2.5.3 Methods

Name	Description
train	Switch training mode while keeping frozen OpenPoints weights in eval mode.
forward	Encode point clouds into a compact semidense embedding.

1.2.5.3.1 train

vin.encoders.PointNeXtSEncoder.train(mode=True)

Switch training mode while keeping frozen OpenPoints weights in eval mode.

1.2.5.3.2 forward

vin.encoders.PointNeXtSEncoder.forward(points)

Encode point clouds into a compact semidense embedding.

1.2.5.3.2.1 Parameters

Name	Type	Description	Default
points	Tensor	Tensor["B N 3", float32] or Tensor["B N C", float32] semidense points in the rig frame. When C > 3, the first three channels are XYZ and the remaining channels are treated as per-point features.	required

1.2.5.3.2.2 Returns

Name	Type	Description
	Tensor	Tensor["B out_dim", float32] semidense embeddings.

1.2.6 PointNeXtSEncoderConfig

vin.encoders.PointNeXtSEncoderConfig()

Config-as-factory wrapper for PointNeXtSEncoder.

Paths are resolved against aria_nbv.configs.path_config.PathConfig so model configs can store repository-relative external checkpoint references. The target module expects CUDA tensors because OpenPoints PointNeXt-S uses CUDA-only kernels in the configured runtime.

1.2.6.1 Attributes

Name	Description
target_type	Factory target for aria_nbv.configs.base.BaseConfig.setup_target.
cfg_path	Path to the PointNeXt YAML config, relative to PathConfig.external_dir.
checkpoint_path	Optional pretrained checkpoint (PointNeXt/OpenPoints format).
out_dim	Output embedding dimension produced for the semidense point cloud.
max_points	Subsample semidense points to this count before encoding.
freeze	Whether to freeze PointNeXt-S weights during training.
strict_load	Whether to enforce strict checkpoint loading.

1.2.7 PoseEncoder

vin.encoders.PoseEncoder()

Base interface for encoders of poses already in a reference frame.

1.2.7.1 Attributes

Name	Description
pose_encoder_lff	Optional LFF submodule for diagnostics (None for SH-only encoders).
out_dim	Return the final pose-embedding feature width.

1.2.7.2 Methods

Name	Description
encode	Encode a pose expressed in the reference frame.
forward	Encode a reference-frame pose through PyTorch’s module call interface.

1.2.7.2.1 encode

vin.encoders.PoseEncoder.encode(pose_rig)

Encode a pose expressed in the reference frame.

1.2.7.2.2 forward

vin.encoders.PoseEncoder.forward(pose_rig)

Encode a reference-frame pose through PyTorch’s module call interface.

1.2.7.2.2.1 Parameters

Name	Type	Description	Default
pose_rig	PoseTW	PoseTW with floating storage shape ... 12; the caller selects the reference frame and translations are metres.	required

1.2.7.2.2.2 Returns

Name	Type	Description
	PoseEncodingOutput	The same differentiable PoseEncodingOutput as :meth:encode,
	PoseEncodingOutput	preserving leading pose axes. Calling the module also runs registered
	PoseEncodingOutput	hooks; no extra parameters or transformation are introduced here.

1.2.8 PoseEncodingOutput

vin.encoders.PoseEncodingOutput(
    center_m,
    pose_vec,
    pose_enc,
    center_dir=None,
    forward_dir=None,
    radius_m=None,
    view_alignment=None,
)

Pose-encoding outputs for a pose expressed in a reference frame.

1.2.8.1 Attributes

Name	Type	Description
center_m	Tensor	Tensor["... 3", float32] translation in the reference frame.
pose_vec	Tensor	Tensor["... D", float32] pose vector fed into the encoder.
pose_enc	Tensor	Tensor["... E", float32] encoded pose embedding.
center_dir	Tensor | None	Optional Tensor["... 3", float32] unit direction to center.
forward_dir	Tensor | None	Optional Tensor["... 3", float32] forward direction in ref frame.
radius_m	Tensor | None	Optional Tensor["... 1", float32] radius \|\|t\|\|.
view_alignment	Tensor | None	Optional Tensor["... 1", float32] dot <f, -u>.

1.2.9 R6dLffPoseEncoder

vin.encoders.R6dLffPoseEncoder(config)

Encode reference-frame translation and rotation-6D through LFF.

The representation is continuous for common rotations but is not an SE(3)-equivariant map: translation coordinates and rotation-matrix columns are interpreted in the caller-supplied reference rig frame.

1.2.9.1 Attributes

Name	Description
pose_encoder_lff	Registered shared Fourier encoder; follows module mode, device and checkpoint lifecycle.
out_dim	Return the configured LFF pose-embedding width.

1.2.9.2 Methods

Name	Description
encode	Encode poses in the reference rig frame.

1.2.9.2.1 encode

vin.encoders.R6dLffPoseEncoder.encode(pose_rig)

Encode poses in the reference rig frame.

1.2.9.2.1.1 Parameters

Name	Type	Description	Default
pose_rig	PoseTW	PoseTW["... 12"] pose in reference rig frame.	required

1.2.9.2.1.2 Returns

Name	Type	Description
	PoseEncodingOutput	PoseEncodingOutput containing translation, pose vector, and embedding.

1.2.10 R6dLffPoseEncoderConfig

vin.encoders.R6dLffPoseEncoderConfig()

Configure reference-frame R6D plus LFF pose encoding.

1.2.10.1 Attributes

Name	Description
target_type	Factory target for aria_nbv.configs.base.BaseConfig.setup_target.
out_dim	Return the complete pose-embedding width seen by consumers.
kind	Discriminator for pose-encoder selection.
pose_encoder_lff	LFF encoder for [t, r6d] pose vectors (input_dim=9).
pose_scale_init	Initial per-group scale for translation and rotation (t, r6d).
pose_scale_learnable	Whether pose scaling parameters are learned.
pose_scale_eps	Numerical epsilon for pose scaling.

1.2.11 ShellLffPoseEncoder

vin.encoders.ShellLffPoseEncoder(config)

Encode canonical shell descriptors with learned Fourier features.

The input pose must already be expressed in the reference rig frame. The emitted pose vector is [center_dir, forward_dir, radius_m, view_alignment] and has dimension 8.

1.2.11.1 Attributes

Name	Description
out_dim	Return the configured shell-LFF embedding width.

1.2.11.2 Methods

Name	Description
encode	Encode shell pose descriptors in the reference rig frame.

1.2.11.2.1 encode

vin.encoders.ShellLffPoseEncoder.encode(pose_rig)

Encode shell pose descriptors in the reference rig frame.

1.2.12 ShellLffPoseEncoderConfig

vin.encoders.ShellLffPoseEncoderConfig()

Config-as-factory wrapper for ShellLffPoseEncoder.

1.2.12.1 Attributes

Name	Description
target_type	Factory target for aria_nbv.configs.base.BaseConfig.setup_target.
kind	Discriminator for pose-encoder selection.
pose_encoder_lff	LFF encoder for shell pose vectors (input_dim=8).

1.2.13 ShellShPoseEncoder

vin.encoders.ShellShPoseEncoder(config)

Encode shell-based pose descriptors using spherical harmonics.

Inputs are unit vectors on \(\mathbb{S}^2\):

• \(u\): candidate position direction in the reference frame,
• \(f\): candidate forward direction in the reference frame,

plus a radius \(r=\lVert t\rVert\) and optional scalar pose terms (e.g. \(\langle f, -u \rangle\)). This representation uses only the forward direction and therefore does not encode roll about the forward axis. This is acceptable when roll jitter is small; use a full SO(3) encoding (e.g. R6D + LFF) when roll sensitivity is required.

The encoder computes real spherical harmonics up to degree lmax for \(u\) and \(f\) and projects them into a learnable embedding space. The radius is encoded via 1D Fourier features (on \(r\) by default) and projected to a learnable embedding.

Spherical harmonics supply a directional basis, but the independent dense projections, GELU layers, and concatenation do not preserve irreducible representations. The emitted embedding is therefore a reference-frame directional inductive bias, not an SO(3)-equivariant representation.

1.2.13.1 Parameters

Name	Type	Description	Default
lmax		Maximum spherical harmonics degree.	required
sh_out_dim		Output dimensionality after projecting each SH vector.	required
radius_num_frequencies		Number of Fourier frequencies for the radius encoding.	required
radius_out_dim		Output dimensionality after projecting the radius Fourier features.	required
radius_include_input		Concatenate the raw radius input to Fourier features when True.	required
radius_learnable		Make the radius Fourier frequency matrix learnable when True.	required
radius_init_scale		Stddev used to initialize the radius Fourier frequency matrix.	required
radius_log_input		Encode \(\log(r+\varepsilon)\) when True, else encode \(r\) directly.	required
include_radius		If True, include the radius embedding in the output.	required
scalar_in_dim		Number of additional scalar pose features.	required
scalar_out_dim		Output dimensionality of the scalar MLP.	required
scalar_hidden_dim		Hidden size for the scalar MLP.	required
normalization		e3nn SH normalization mode.	required
include_scalars		If True, include the scalar MLP output in the embedding.	required

1.2.13.2 Attributes

Name	Description
out_dim	Return the concatenated direction, radius, and scalar width.

1.2.13.3 Methods

Name	Description
forward	Encode directions and scalar pose features.

1.2.13.3.1 forward

vin.encoders.ShellShPoseEncoder.forward(u, f, *, r, scalars=None)

Encode directions and scalar pose features.

1.2.13.3.1.1 Parameters

Name	Type	Description	Default
u	Tensor	Tensor["... 3", float32] unit direction from reference to candidate center.	required
f	Tensor	Tensor["... 3", float32] unit forward direction of the candidate camera.	required
r	Tensor	Tensor["... 1", float32] radius \(\lVert t\rVert\) of the candidate center in the reference frame.	required
scalars	Tensor | None	Optional Tensor["... scalar_in_dim", float32] scalar pose features.	None

1.2.13.3.1.2 Returns

Name	Type	Description
	Tensor	Tensor["... out_dim", float32] pose embedding.

This lower-level module receives the shell descriptor tensors directly. Use aria_nbv.vin.encoders.shell_pose.ShellShPoseEncoderAdapter when the input is an efm3d.aria.pose.PoseTW pose.

1.2.14 ShellShPoseEncoderAdapter

vin.encoders.ShellShPoseEncoderAdapter(config)

Adapt ShellShPoseEncoder to the common pose-encoder interface.

The adapter accepts efm3d.aria.pose.PoseTW poses, derives the canonical shell descriptor with encode_shell_pose_descriptor, and delegates the direction/radius tensors to aria_nbv.vin.encoders.spherical.ShellShPoseEncoder.

1.2.14.1 Attributes

Name	Description
out_dim	Return the adapted spherical-harmonics embedding width.

1.2.14.2 Methods

Name	Description
encode	Encode shell pose descriptors with spherical harmonics.

1.2.14.2.1 encode

vin.encoders.ShellShPoseEncoderAdapter.encode(pose_rig)

Encode shell pose descriptors with spherical harmonics.

1.2.15 ShellShPoseEncoderAdapterConfig

vin.encoders.ShellShPoseEncoderAdapterConfig()

Config-as-factory wrapper for ShellShPoseEncoderAdapter.

1.2.15.1 Attributes

Name	Description
target_type	Factory target for aria_nbv.configs.base.BaseConfig.setup_target.
kind	Discriminator for pose-encoder selection.
sh_encoder	Spherical-harmonics encoder configuration.

1.2.16 ShellShPoseEncoderConfig

vin.encoders.ShellShPoseEncoderConfig()

Config-as-factory wrapper for ShellShPoseEncoder.

1.2.16.1 Attributes

Name	Description
target_type	Return the runtime shell encoder type constructed by this config.
kind	Discriminator for pose-encoder selection.
lmax	Maximum spherical harmonics degree.
sh_out_dim	Projection dimension for each SH vector (for \(u\) and \(f\)).
radius_num_frequencies	Number of Fourier frequencies for the 1D radius encoding.
radius_out_dim	Projection dimension for the encoded radius.
radius_include_input	Concatenate the raw radius input to Fourier features when True.
radius_learnable	Make the radius Fourier frequency matrix learnable when True.
radius_init_scale	Stddev used to initialize the radius Fourier frequency matrix.
radius_log_input	Encode \(r\) directly by default; set to True to encode $(r+)`` instead.
include_radius	Include radius features in the embedding when True.
scalar_in_dim	Number of additional scalar pose features (e.g. \(\langle f, -u \rangle\)).
scalar_out_dim	Output dimension of the scalar MLP.
scalar_hidden_dim	Hidden dimension of the scalar MLP.
normalization	e3nn spherical harmonics normalization mode.
include_scalars	Include scalar features in the embedding when True.

1.2.17 TargetCurrentFrame

vin.encoders.TargetCurrentFrame(
    t_world_frame,
    horizontal_distance_m,
    height_m,
    active,
)

Canonical target/current frame shared by candidate and history encoders.

Active rows are target-centred, world-gravity aligned, and oriented toward the current camera in the horizontal plane. Inactive rows contain a neutral identity pose at the world origin plus zero distances; active distinguishes that padding from measured zero.

1.2.17.1 Attributes

Name	Description
t_world_frame	PoseTW["... 12"] float32 world-from-frame transform on the input pose device.
horizontal_distance_m	Tensor["... 1", float32] target-to-current XY-plane range in metres.
height_m	Tensor["... 1", float32] signed current-camera height above target in metres.
active	Tensor["...", bool] input-mask alias marking realized state geometry, not padding.

1.2.18 TargetCurrentGeometryEncoder

vin.encoders.TargetCurrentGeometryEncoder(config)

Encode candidates in a shared target/current canonical frame.

The module exposes one fixed 12-column interface. Candidate order affects only the corresponding output rows; the shared frame depends on target and current-camera poses plus state support. See TARGET_CURRENT_GEOMETRY_FEATURES for column identity. Target rotation is intentionally outside this interface: target shape is represented only by its centre and sorted side lengths. Use a spatial readout when orientation relative to scene evidence must remain observable.

1.2.18.1 Attributes

Name	Description
output_dim	Return the ordered candidate feature width.

1.2.18.2 Methods

Name	Description
forward	Encode target-relative candidate direction, range, gaze, and scale.

1.2.18.2.1 forward

vin.encoders.TargetCurrentGeometryEncoder.forward(
    root_pose_world,
    target_pose_relative_root,
    current_pose_relative_root,
    candidate_pose_relative_root,
    target_extents,
    candidate_mask,
    *,
    state_mask=None,
)

Encode target-relative candidate direction, range, gaze, and scale.

1.2.18.2.1.1 Parameters

Name	Type	Description	Default
root_pose_world	PoseTW	PoseTW["B 12"] world-from-root poses, broadcast over state and candidate axes.	required
target_pose_relative_root	PoseTW	PoseTW["B 12"] root-from-target OBB poses. Target translation influences the output; target rotation is discarded even for an anisotropic OBB.	required
current_pose_relative_root	PoseTW	PoseTW["B S 12"] root-from-current-camera poses defining one frame per realized state.	required
candidate_pose_relative_root	PoseTW	PoseTW["B S N 12"] root-from-candidate-camera poses. Translation and the local +Z optical axis influence the descriptor; roll about that axis does not.	required
target_extents	Tensor	Tensor["B 3", float32] target OBB side lengths in metres on the pose tensors’ device. Values are sorted before encoding, retaining the unordered side-length multiset without associating lengths with target axes.	required
candidate_mask	Tensor	Tensor["B S N", bool] materialized candidate support. The mask and all pose tensors share a device; state_mask uses that device when supplied.	required
state_mask	Tensor | None	Optional Tensor["B S", bool] realized-state support. Defaults to states containing at least one candidate. Explicit support keeps the shared frame available for history features when a realized state has zero candidates.	None

1.2.18.2.1.2 Returns

Name	Type	Description
	TargetCurrentGeometryOutput	TargetCurrentGeometryOutput with float32 values ordered as
	TargetCurrentGeometryOutput	[u_x, u_y, u_z, f_x, f_y, f_z, r, p_z, | | | [TargetCurrentGeometryOutput](`aria_nbv.vin.encoders.target_current_geometry.TargetCurrentGeometryOutput`) | dot(f, -u), e_min, e_mid, e_max]. Here candidate direction u,
	TargetCurrentGeometryOutput	forward direction f, radius r, and alignment reuse
	TargetCurrentGeometryOutput	func:aria_nbv.vin.encoders.shell_descriptor.encode_shell_pose_descriptor;
	TargetCurrentGeometryOutput	p_z is candidate height in the canonical frame and e_* are
	TargetCurrentGeometryOutput	sorted target side lengths. Direction and gaze alignment are
	TargetCurrentGeometryOutput	zero/unavailable when \(r\le\epsilon_d\); radius, height, forward
	TargetCurrentGeometryOutput	direction, and extents remain measured. Padded rows have no
	TargetCurrentGeometryOutput	available channels. Gradients propagate through active pose and
	TargetCurrentGeometryOutput	extent values.

1.2.18.2.1.3 Raises

Name	Type	Description
	ValueError	If support masks or pose/value shapes violate the interface, a candidate is materialized outside state support, active poses or extents are invalid, or an active state cannot define the target/current frame.

1.2.18.2.1.4 Theory

Each candidate pose is composed into the canonical frame as

\[ T_{F\leftarrow Q}=T_{W\leftarrow F}^{-1} T_{W\leftarrow R}T_{R\leftarrow Q}. \]

The fixed frame makes the descriptor invariant to joint world translation and gravity-axis yaw. Candidate gaze, height, and metric distance remain visible. Target rotation is discarded entirely, while sorting extents preserves only the unordered side-length multiset. Thus any rotation of an anisotropic target OBB leaves this descriptor unchanged; changing its centre or side lengths, the gravity direction, or candidate pose can change it.

1.2.19 TargetCurrentGeometryEncoderConfig

vin.encoders.TargetCurrentGeometryEncoderConfig()

Configure the fixed-layout target/current candidate geometry module.

1.2.19.1 Attributes

Name	Description
kind	Stable discriminator for the world-Z-up target/current feature contract.
horizontal_epsilon_m	Largest horizontal range treated as unable to define the frame, in metres.
direction_epsilon_m	Largest candidate radius with unavailable centre direction and gaze alignment, in metres.
target_type	Return the configured geometry module type.
output_dim	Return the feature width without constructing the module.

1.2.20 TargetCurrentGeometryOutput

vin.encoders.TargetCurrentGeometryOutput(frame, values, available)

Candidate-aligned geometry values and measurement availability.

values and available use the exact column order in TARGET_CURRENT_GEOMETRY_FEATURES. An unavailable zero is padding or an undefined direction, whereas an available zero is a measured descriptor.

1.2.20.1 Attributes

Name	Description
frame	State-aligned frame independent of candidate pose values once state support is established.
values	Tensor["... N 12", float32] named values on the pose device; unavailable entries are zero.
available	Tensor["... N 12", bool] fresh measurement mask; padded candidate rows are all false.

1.2.21 TrajectoryEncoder

vin.encoders.TrajectoryEncoder(config)

Encode EFM trajectory poses with an R6D + LFF pose encoder.

1.2.21.1 Attributes

Name	Description
out_dim	Return the per-frame and pooled trajectory embedding width.

1.2.21.2 Methods

Name	Description
encode_poses	Encode a batch of trajectory poses.
forward	Encode a trajectory’s world←rig poses.

1.2.21.2.1 encode_poses

vin.encoders.TrajectoryEncoder.encode_poses(poses)

Encode a batch of trajectory poses.

1.2.21.2.1.1 Parameters

Name	Type	Description	Default
poses	PoseTW	PoseTW["B F 12"] or PoseTW["F 12"] trajectory poses.	required

1.2.21.2.1.2 Returns

Name	Type	Description
	TrajectoryEncodingOutput	TrajectoryEncodingOutput with per-frame encodings and pooled embedding.

1.2.21.2.2 forward

vin.encoders.TrajectoryEncoder.forward(trajectory)

Encode a trajectory’s world←rig poses.

1.2.21.2.2.1 Parameters

Name	Type	Description	Default
trajectory	EfmTrajectoryView	aria_nbv.data_handling.ase_efm.views.EfmTrajectoryView.	required

1.2.21.2.2.2 Returns

Name	Type	Description
	TrajectoryEncodingOutput	TrajectoryEncodingOutput with per-frame encodings and pooled embedding.

1.2.22 TrajectoryEncoderConfig

vin.encoders.TrajectoryEncoderConfig()

Configure per-frame pose encoding and sequence reduction.

1.2.22.1 Attributes

Name	Description
target_type	Factory target for aria_nbv.configs.base.BaseConfig.setup_target.
pose_encoder	Pose encoder configuration (R6D + LFF).
pool_mode	Pooling mode over frames: mean, final, or none.

1.2.23 TrajectoryEncodingOutput

vin.encoders.TrajectoryEncodingOutput(per_frame, pooled)

Trajectory encoding outputs.

1.2.23.1 Attributes

Name	Type	Description
per_frame	PoseEncodingOutput	PoseEncodingOutput for each frame.
pooled	Tensor | None	Tensor["B E", float32] pooled trajectory embedding (or None).

1.3 Functions

Name	Description
build_target_current_frame	Build the gravity-aligned target/current frame for active actor rows.
infer_pose_vec_groups	Infer semantic groups for a pose-encoder input vector.
validate_pos_grid_xyz_encoder	Require a position-grid Fourier encoder to consume XYZ coordinates.

1.3.1 build_target_current_frame

vin.encoders.build_target_current_frame(
    root_pose_world,
    target_pose_relative_root,
    current_pose_relative_root,
    active_mask,
    *,
    horizontal_epsilon_m=1e-06,
)

Build the gravity-aligned target/current frame for active actor rows.

1.3.1.1 Parameters

Name	Type	Description	Default
root_pose_world	PoseTW	PoseTW["... 12"] world-from-root pose. Its batch shape may be a prefix of the current-pose batch shape.	required
target_pose_relative_root	PoseTW	PoseTW["... 12"] root-from-target pose; only its target centre is used, so equivalent OBB axes/signs do not affect the frame.	required
current_pose_relative_root	PoseTW	PoseTW["... 12"] root-from-current-camera pose.	required
active_mask	Tensor	Tensor["...", bool] rows that require a physical frame. Inactive rows receive a fixed neutral padding frame and remain explicitly marked unavailable. The mask and all poses share a device.	required
horizontal_epsilon_m	float	Largest horizontal target-to-current distance treated as degenerate, in metres.	1e-06

1.3.1.2 Returns

Name	Type	Description
	TargetCurrentFrame	TargetCurrentFrame with target-centred world-Z-up transforms, float32
	TargetCurrentFrame	distances in metres, and the unchanged boolean support mask.

1.3.1.3 Raises

Name	Type	Description
	ValueError	If the threshold is nonpositive, the support dtype or shapes are invalid, active poses are non-finite, or an active target-to-current bearing is vertical or coincident.

1.3.1.4 Theory

Let \(T_{W\leftarrow R}\) be the world-from-root pose, \(T_{R\leftarrow T}\) root-from-target, and \(T_{R\leftarrow C}\) root-from-current-camera. Composition gives

\[ T_{W\leftarrow T}=T_{W\leftarrow R}T_{R\leftarrow T},\qquad T_{W\leftarrow C}=T_{W\leftarrow R}T_{R\leftarrow C}. \]

For target-to-current displacement \(d=p_W^C-p_W^T\) in metres and world gravity axis \(z=(0,0,1)^\mathsf{T}\), the horizontal projection and right-handed orthonormal basis are

\[ h=d-(d^\mathsf{T}z)z,\quad x=\frac{h}{\lVert h\rVert_2},\quad y=z\times x,\quad R_{W\leftarrow F}=[x\;y\;z]. \]

The frame pose is \(T_{W\leftarrow F}=(R_{W\leftarrow F},p_W^T)\); the stored horizontal distance is \(\lVert h\rVert_2\) and height is \(d^\mathsf{T}z\). Active rows with \(\lVert h\rVert_2\le\epsilon_h\) are rejected because a vertical or coincident bearing cannot define \(x\). Inactive rows use a neutral frame and do not need physical poses.

1.3.2 infer_pose_vec_groups

vin.encoders.infer_pose_vec_groups(pose_vec_dim)

Infer semantic groups for a pose-encoder input vector.

1.3.2.1 Parameters

Name	Type	Description	Default
pose_vec_dim	int	Size of the pose vector D.	required

1.3.2.2 Returns

Name	Type	Description
	list[tuple[str, slice]]	Ordered list of (name, slice) entries describing how to split the
	list[tuple[str, slice]]	pose vector into semantic groups. Falls back to a single pose_vec
	list[tuple[str, slice]]	group when the dimensionality is unknown.

1.3.3 validate_pos_grid_xyz_encoder

vin.encoders.validate_pos_grid_xyz_encoder(value)

Require a position-grid Fourier encoder to consume XYZ coordinates.

VIN positional grids are passed as metric 3D coordinates before LearnableFourierFeatures expands them. The encoder therefore must keep input_dim == 3; any other input width indicates a config/schema mismatch rather than a recoverable runtime condition.