1 vin.encoders.spherical

vin.encoders.spherical

Spherical-harmonics pose encoding for VIN.

VIN candidate generation samples camera centers on a (possibly biased) spherical shell around a reference pose. A natural descriptor for such candidates is therefore expressed in terms of directions on \(\mathbb{S}^2\) and a scalar radius.

This module provides a lightweight pose encoder based on real spherical harmonics computed via e3nn, plus a 1D Fourier-feature encoding for the radius and a small MLP for additional scalar pose terms.

1.1 Classes

Name	Description
ShellShPoseEncoder	Encode shell-based pose descriptors using spherical harmonics.
ShellShPoseEncoderConfig	Config-as-factory wrapper for ShellShPoseEncoder.

1.1.1 ShellShPoseEncoder

vin.encoders.spherical.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.1.1.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.1.1.2 Attributes

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

1.1.1.3 Methods

Name	Description
forward	Encode directions and scalar pose features.

1.1.1.3.1 forward

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

Encode directions and scalar pose features.

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

vin.encoders.spherical.ShellShPoseEncoderConfig()

Config-as-factory wrapper for ShellShPoseEncoder.

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