1 vin.modules.qh_directional_history

vin.modules.qh_directional_history

Directional and radial summaries of the factual selected-pose prefix.

The module describes where previously selected cameras lie around the target in the target/current frame. Real spherical-harmonic (SH) means retain angular coverage up to a configured degree, while radial mean and standard deviation retain metric stand-off. The representation consumes only the complete strictly causal prefix \(j<s\); padding and future pose payloads cannot affect it.

Uniform aggregation is an order-invariant set function. Optional exponential recency uses explicit physical ages, rather than storage position, and remains order-invariant when poses, masks, and ages are permuted together. Directional and radial quantities use separately normalized support populations because a selected camera at zero target radius has a valid radius but no direction.

1.1 Attributes

Name Description
QhDirectionalWeighting Supported set-aggregation rules for selected history measurements.

1.2 Classes

Name Description
QhDirectionalHistory Aggregate selected camera centres in the target/current frame.
QhDirectionalHistoryConfig Configure factual selected-prefix directional and radial coverage.
QhDirectionalHistoryFeatures Candidate-independent selected-prefix coverage features.
QhDirectionalHistorySpec Ordered meaning of the emitted directional-history columns.

1.2.1 QhDirectionalHistory

vin.modules.qh_directional_history.QhDirectionalHistory(config)

Aggregate selected camera centres in the target/current frame.

Let \(c_{sj}\in\mathbb{R}^3\) be selected camera centre \(j\) expressed in state \(s\)’s target/current frame, \(r_{sj}=\|c_{sj}\|_2\), and \(d_{sj}=c_{sj}/r_{sj}\). Radial support is the factual causal mask \(M^r_{sj}\); directional support is \(M^d_{sj}=M^r_{sj}[r_{sj}>\epsilon]\).

For either support population \(M\), the module computes a normalized weighted mean \(\mu(x;M)=\sum_j M_jw_jx_j/\sum_j M_jw_j\). Uniform weights are one. With physical age \(a_j\) and half-life \(h\), recency weights are proportional to \(2^{-(a_j-a_{min})/h}\), where \(a_{min}\) is taken over that same support population for numerical stability. Directional and radial weights are therefore normalized separately.

Angular columns are \(\mu(Y^l_m(d);M^d)\) for all \(0\leq l\leq l_{max}\) and \(-l\leq m\leq l\), using the registered e3nn real spherical-harmonic basis child with normalize=True and the configured output normalization. Radial columns are \(\bar r=\mu(r;M^r)\) and \(\sigma_r=\sqrt{\mu((r-\bar r)^2;M^r)}\). The final count \(\sum_j M^r_j\) is deliberately unweighted.

Uniform weighting is invariant to a joint permutation of supported poses and masks. Recency weighting has the same invariance when ages are permuted with their poses. A numeric zero remains distinct from missing measurement through :class:QhDirectionalHistoryFeatures.available.

1.2.1.1 Attributes

Name Description
out_dim Return the feature width declared by spec.

1.2.1.2 Methods

Name Description
forward Summarize the complete strictly causal selected-pose prefix.
1.2.1.2.1 forward
vin.modules.qh_directional_history.QhDirectionalHistory.forward(
    history_pose_relative_root,
    history_mask,
    step_mask,
    *,
    root_pose_world,
    target_current_frame,
    history_age_s=None,
)

Summarize the complete strictly causal selected-pose prefix.

1.2.1.2.1.1 Parameters
Name Type Description Default
history_pose_relative_root PoseTW PoseTW["B S S 12"] root-rig-from- selected-camera poses. Only entries selected by history_mask may affect the output. required
history_mask Tensor Tensor["B S S", bool] exact factual prefix; true precisely at realized state s for history slot j < s. required
step_mask Tensor Tensor["B S", bool] realized state support. required
root_pose_world PoseTW PoseTW["B 12"] world-from-root-rig pose. required
target_current_frame TargetCurrentFrame Target-centred, world-up frame for each state; its t_world_frame has shape PoseTW["B S 12"]. required
history_age_s Tensor | None Optional Tensor["B S S", float32] nonnegative age of each selected pose relative to its query state, seconds. Required exactly when weighting is exponential_recency. None
1.2.1.2.1.2 Returns
Name Type Description
QhDirectionalHistoryFeatures class:QhDirectionalHistoryFeatures containing real-SH means,
QhDirectionalHistoryFeatures radial mean and population standard deviation, and unweighted
QhDirectionalHistoryFeatures selected count. Empty realized prefixes emit zeros with only
QhDirectionalHistoryFeatures selected_count available; padded states emit zeros with no
QhDirectionalHistoryFeatures available columns.
1.2.1.2.1.3 Theory

Poses compose as \(T_{FC}=T_{FW}T_{WR}T_{RC}\), where F is the target/current frame, W world, R root rig, and C the selected camera. The translation of \(T_{FC}\) is \(c_{sj}\). See the class contract for the supported SH, radial, and recency equations.

1.2.2 QhDirectionalHistoryConfig

vin.modules.qh_directional_history.QhDirectionalHistoryConfig()

Configure factual selected-prefix directional and radial coverage.

1.2.2.1 Attributes

Name Description
lmax Largest real SH degree; emits every degree from zero through lmax.
normalization e3nn real-SH output normalization on the unit sphere.
weighting Uniform set aggregation or normalized explicit-age exponential recency.
recency_half_life_s Positive half-life in seconds, required exactly for recency weighting.
direction_epsilon_m Strict radius threshold in metres below which direction is unavailable.
target_type Return the configured directional-history module class.
feature_names Return ordered output names without constructing the module.
out_dim Return output width without module construction or a dummy forward.

1.2.3 QhDirectionalHistoryFeatures

vin.modules.qh_directional_history.QhDirectionalHistoryFeatures(
    values,
    available,
    spec,
)

Candidate-independent selected-prefix coverage features.

Directional columns may be unavailable while radial columns remain available when every selected camera has zero target radius. A realized empty prefix has an observed count of zero but no directional or radial measurement. Padded states have neither measurements nor an observed count.

1.2.3.1 Attributes

Name Description
values Tensor["B S F", float32] SH moments, radial moments, then selected count.
available Tensor["B S F", bool] per-column support; false values are zero-filled.
spec Static names, units, and weighting whose length equals feature width F.

1.2.4 QhDirectionalHistorySpec

vin.modules.qh_directional_history.QhDirectionalHistorySpec(
    names,
    units,
    weighting,
)

Ordered meaning of the emitted directional-history columns.

Columns are ordered by increasing SH degree \(l\), then order \(m=-l,\ldots,l\), followed by radial mean, radial standard deviation, and selected count. Thus the SH block has \((l_{max}+1)^2\) columns.

1.2.4.1 Attributes

Name Description
names Unique feature names aligned with the final F axis of values.
units Units aligned with names: "1" for SH/count and "m" for radii.
weighting Aggregation rule used for the directional and radial moment columns.
out_dim Return the number of declared output columns.
Back to top