1 vin.encoders.target_current_geometry

vin.encoders.target_current_geometry

Target/current canonical geometry for VIN candidate features.

The frame removes global translation and gravity-axis yaw while retaining metric scale, vertical displacement, and camera gaze. Its origin is the target centre, +Z is world gravity, and +X is the horizontal bearing from the target to the current camera. Target OBB rotation is discarded entirely: the target contributes only its centre and the unordered multiset of side lengths. An anisotropic box therefore has the same descriptor under any target rotation.

For root, target, current-camera, and candidate-camera poses, the module first composes root-relative poses into the world frame. It then expresses every candidate in the same target/current frame before delegating shell direction, radius, and gaze geometry to aria_nbv.vin.encoders.shell_descriptor.encode_shell_pose_descriptor. The resulting descriptor is invariant to a joint world translation and a joint yaw about gravity. It deliberately retains height, metric scale, candidate gaze, and changes to the gravity direction; sorting OBB side lengths retains physical extent magnitudes without their axis association. This orientation-free shape summary differs from aria_nbv.vin.modules.qh_candidate_readout.QhSpatialReadout, whose target-oriented lattice can retain OBB rotation through sampled spatial evidence.

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

1.2.1 TargetCurrentFrame

vin.encoders.target_current_geometry.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.1.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.2 TargetCurrentGeometryEncoder

vin.encoders.target_current_geometry.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.2.1 Attributes

Name	Description
output_dim	Return the ordered candidate feature width.

1.2.2.2 Methods

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

1.2.2.2.1 forward

vin.encoders.target_current_geometry.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.2.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.2.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.2.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.2.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.3 TargetCurrentGeometryEncoderConfig

vin.encoders.target_current_geometry.TargetCurrentGeometryEncoderConfig()

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

1.2.3.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.4 TargetCurrentGeometryOutput

vin.encoders.target_current_geometry.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.4.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.3 Functions

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

1.3.1 build_target_current_frame

vin.encoders.target_current_geometry.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.