1 vin.modules.qh_scene_encoders

vin.modules.qh_scene_encoders

Scene-carrier modules for the finite-horizon :math:Q_H scorer.

A scene carrier maps actor-visible geometric evidence to one fixed-width state feature per realized decision state. It is deliberately narrower than the complete scorer: it does not read candidates, targets, rewards, requested horizon, remaining budget, labels, or authoritative action validity. This boundary keeps three scientific questions separable:

• which observations constitute the causal scene state;
• how that state is compressed into a shared state feature; and
• how a candidate later queries the resulting memory.

QhRootMomentsSceneEncoder is the parameter-free root_moments_v1 control. Every configured root EVL channel contributes global mean, standard deviation, minimum, and maximum. Root semidense points contribute coordinate-wise mean and standard deviation in the rollout-root frame plus explicit presence and finite-support fraction. The fraction is normalized by each chain’s persisted point length, never by a collated batch width, so an actor state is invariant to batch composition and DDP partitioning. A later dynamic carrier must introduce its state axis explicitly rather than hiding a semantic change in this control.

QhSelectedSurfacePointSceneEncoder is the first S1-points carrier. It uses the canonical rendering backprojection for strictly causal selected CF-GT depth, expresses the resulting surface points from the factual current camera, and applies a bounded Deep-Sets-style shared point map followed by masked mean and maximum pooling. Its learned residual has exactly the root carrier width and its final projection is initialized to zero. S1 therefore starts as the exact H0 function under a matched seed rather than perturbing the control merely because another carrier exists. The projection itself can learn on the first backward pass; gradients reach the upstream point map only after that projection opens. Adding S1 leaves the scorer’s physical and scene projection widths unchanged, so every common downstream H0/S1 weight remains identical and only the named scene carrier adds parameters.

Global moments are intentionally lossy. They discard topology, occlusion, view direction, free-versus-unknown geometry, and selected-observation updates. The module is therefore a checkpoint-compatible control, not a claim that root evidence is a sufficient Markov state. Candidate-local point or ray queries belong to a later relation module rather than being hidden in this shared-carrier interface.

1.1 Attributes

Name	Description
QhSceneChannel	Persisted root-EVL channels admitted by root_moments_v1.
QhSceneEncoderConfig	Versioned S0/S1 scene-carrier configurations persisted with the scorer.

1.2 Classes

Name	Description
QhGeometryOnlySceneEncoder	Zero scene features without observing the scene payload.
QhGeometryOnlySceneEncoderConfig	Ablate root-scene evidence while retaining scorer geometry paths.
QhLegacySelectedSurfacePointSceneEncoderConfig	Read the historical S1 discriminator without granting reuse authority.
QhRootMomentsSceneEncoder	Encode immutable root evidence as global moments.
QhRootMomentsSceneEncoderConfig	Configure the explicit parameter-free S0 root-moments control.
QhSelectedSurfacePointSceneEncoder	Add a bounded causal selected-surface residual to root moments.
QhSelectedSurfacePointSceneEncoderConfig	Configure the privileged S1 selected-surface point memory.

1.2.1 QhGeometryOnlySceneEncoder

vin.modules.qh_scene_encoders.QhGeometryOnlySceneEncoder(
    config,
    *,
    scene_channels,
    dropout=0.0,
)

Zero scene features without observing the scene payload.

Candidate/target poses, causal pose history and budget/horizon remain in the enclosing scorer. This control tests the added value of root EVL and semidense evidence under identical downstream capacity and input admission. It does not establish sufficiency for value prediction. The enclosing scorer retains source-profile admission checks.

1.2.1.1 Methods

Name	Description
forward	Return float32 zeros of shape (B, F) on the actor device.

1.2.1.1.1 forward

vin.modules.qh_scene_encoders.QhGeometryOnlySceneEncoder.forward(actor)

Return float32 zeros of shape (B, F) on the actor device.

Only batch size and device of step_mask are read. Scene, point, depth, reward and label values do not contribute to the output.

1.2.2 QhGeometryOnlySceneEncoderConfig

vin.modules.qh_scene_encoders.QhGeometryOnlySceneEncoderConfig()

Ablate root-scene evidence while retaining scorer geometry paths.

1.2.2.1 Attributes

Name	Description
kind	Explicit information-subset control; never aliases root moments.
target_type	Return the parameter-free zero scene carrier.

1.2.3 QhLegacySelectedSurfacePointSceneEncoderConfig

vin.modules.qh_scene_encoders.QhLegacySelectedSurfacePointSceneEncoderConfig()

Read the historical S1 discriminator without granting reuse authority.

The old ...selected_surface_points_v1 label did not say whether the residual projection was random- or identity-initialized. It can therefore reconstruct an archived state dictionary for inspection, but cannot define a new fit, warm start, inference runtime, or scientific bundle. New work uses QhSelectedSurfacePointSceneEncoderConfig, whose discriminator makes the zero-residual initialization part of architecture identity.

1.2.3.1 Attributes

Name	Description
kind	Ambiguous historical discriminator classified as unknown_legacy_v1.
pixel_stride	Historical deterministic raster stride.
view_chunk_size	Historical selected-view chunk bound.
point_hidden_dim	Historical shared point-feature width.
coordinate_scale_m	Historical current-camera coordinate divisor.
target_type	Return the runtime class solely for historical inspection.

1.2.4 QhRootMomentsSceneEncoder

vin.modules.qh_scene_encoders.QhRootMomentsSceneEncoder(
    config=None,
    *,
    scene_channels,
    dropout=0.0,
)

Encode immutable root evidence as global moments.

For every configured scalar EVL field :math:x_c, the encoder records :math:(\mu_c,\sigma_c,\min x_c,\max x_c). Let :math:T_{r\leftarrow w} be root-from-world and :math:p_k^w a supported semidense point. Root-frame points :math:p_k^r=T_{r\leftarrow w}p_k^w contribute coordinate-wise mean and population standard deviation. Two final scalars distinguish no points from measured all-zero geometry: presence is :math:1[|P|>0], while support is the finite supported-count divided by that chain’s persisted point length. The latter is the pre-collation row capacity carried by :attr:VinSnippet.lengths; batch padding is only a storage detail and cannot change a physical state feature. Empty chains use support zero rather than dividing by zero.

The resulting width is 4 * len(scene_channels) + 8. Source tensors are detached because this carrier consumes persisted actor observations; it is not an end-to-end EFM3D training path. Jointly translating the world points and root pose leaves the point moments invariant. The evidence is immutable within one stored chain; scorer orchestration owns repetition over states and downstream candidate and step masks.

1.2.4.1 Methods

Name	Description
forward	Return Tensor["B F", float32] root-scene features.

1.2.4.1.1 forward

vin.modules.qh_scene_encoders.QhRootMomentsSceneEncoder.forward(actor)

Return Tensor["B F", float32] root-scene features.

B is taken from actor.step_mask and F == output_dim. Missing configured EVL fields, non-finite source values, malformed point capacity, and non-finite active root poses fail closed instead of being encoded as ordinary zeros.

1.2.5 QhRootMomentsSceneEncoderConfig

vin.modules.qh_scene_encoders.QhRootMomentsSceneEncoderConfig()

Configure the explicit parameter-free S0 root-moments control.

1.2.5.1 Attributes

Name	Description
kind	Versioned scene-carrier discriminator persisted with the scorer.
target_type	Return the runtime root-moments encoder class.

1.2.6 QhSelectedSurfacePointSceneEncoder

vin.modules.qh_scene_encoders.QhSelectedSurfacePointSceneEncoder(
    config,
    *,
    scene_channels,
    dropout,
)

Add a bounded causal selected-surface residual to root moments.

For state :math:s_t, the carrier admits only selected observations :math:0\le j<t. Selection at decision :math:j realizes camera :math:\mathsf{C}_{j+1}. The persisted camera and pose define :math:\boldsymbol{T}_{\mathsf{C}_{j+1}}^{\mathsf{R}_0}; canonical backprojection therefore returns root-frame points. The scorer supplies factual :math:\boldsymbol{T}_{\mathsf{C}_t}^{\mathsf{R}_0}, and the encoder forms :math:p^{\mathsf{C}_t}=\boldsymbol{T}_{\mathsf{R}_0}^{\mathsf{C}_t}p^{\mathsf{R}_0}. Dividing XYZ by the configured metric scale yields each set element; no target, candidate, budget, horizon, reward, label, or authoritative action mask enters this path.

A shared MLP maps every valid sampled point independently. Masked mean and elementwise maximum are invariant to point order. They are not generally invariant to partial duplication: overlapping observations receive one vote per valid sampled pixel, so S1 is explicitly a density-weighted surface-set control. Three diagnostics remain learned inputs: presence, valid sampled pixels divided by causal sampled-pixel capacity, and observations with any valid point divided by causal observation count. Empty prefixes produce an exact zero residual.

Geometry validation, backprojection, frame transforms, and point-set reductions remain float32 under mixed-precision training. Autocast is retained for the learned point encoder and final residual projection, so reduced-precision execution cannot change geometric support or make the float32 sum/max accumulators dtype-incompatible.

The output is Tensor["B S F_root", float32]. It adds a learned point update to the unchanged static root moments and zeros padded states. Let :math:g_t^{\mathrm{S1}} denote the pooled point statistic and :math:W_{\mathrm{pt}} the bias-free final projection. Initializing :math:W_{\mathrm{pt}}^{(0)}=0 makes :math:\Phi_t^{\mathrm{S1},(0)}=\Phi_t^{\mathrm{root}} exactly. This is an experimental-control property, not a claim that the surface branch is initially useless: for downstream loss :math:L, :math:\partial L/\partial W_{\mathrm{pt}} can be nonzero immediately because :math:g_t^{\mathrm{S1}} is already nonzero. The upstream point MLP receives zero gradient on that first step through the zero projection and begins learning once the projection departs from zero.

The fixed width and identity start prevent S1 from changing downstream scorer shapes or initial predictions. This carrier still cannot distinguish observed free space from unknown space or retain ray direction after fusion; those are S2 responsibilities.

1.2.6.1 Methods

Name	Description
forward	Return fixed-width state features for every realized decision state.

1.2.6.1.1 forward

vin.modules.qh_scene_encoders.QhSelectedSurfacePointSceneEncoder.forward(
    actor,
    *,
    current_pose_relative_root,
)

Return fixed-width state features for every realized decision state.

1.2.6.1.1.1 Parameters

Name	Type	Description	Default
actor	QhActorTensors	Batched CF+ actor whose selected-observation prefix has exact [B,S,S,H,W] causal support.	required
current_pose_relative_root	PoseTW	PoseTW["B S 12"] storing root-from-current-camera poses derived once by the scorer.	required

1.2.6.1.1.2 Returns

Name	Type	Description
	Tensor	Tensor["B S F_root", float32] equal to repeated root moments
	Tensor	plus the selected-surface residual on realized states, and zero on
	Tensor	padded states.

1.2.7 QhSelectedSurfacePointSceneEncoderConfig

vin.modules.qh_scene_encoders.QhSelectedSurfacePointSceneEncoderConfig()

Configure the privileged S1 selected-surface point memory.

The raster stride and view-chunk bound are representation identity. They determine which stored pixels become set elements and the largest number of selected views backprojected at once. coordinate_scale_m only nondimensionalizes current-camera XYZ before the shared point MLP; it is neither a clipping radius nor an asserted scene extent. The residual’s zero-output initialization is part of this versioned architecture: a fresh S1 model is exactly its source-matched H0 control, without adding a config switch or a second initialization profile.

1.2.7.1 Attributes

Name	Description
kind	Active identity-start S1 carrier and representation_semantics value.
pixel_stride	Deterministic row/column stride applied before canonical depth backprojection.
view_chunk_size	Maximum flattened selected-view rows backprojected in one call.
point_hidden_dim	Shared point-feature width before invariant mean/maximum pooling.
coordinate_scale_m	Metric divisor for current-camera XYZ supplied to the point MLP.
target_type	Return the runtime selected-surface encoder class.