1 vin.modules.qh_candidate_readout

vin.modules.qh_candidate_readout

Reduce persisted root EVL fields into candidate-aligned features.

The two readouts deliberately expose different spatial information. The summary readout reduces each complete voxel field to global statistics and broadcasts them over state and candidate axes. Its output depends only on root EVL evidence and its persisted presence bits; it is independent of the target, candidate poses, and action_mask. Broadcasting does not introduce conditioning on the receiving axes.

The spatial readout retains coordinates until it samples a target-oriented bounding-box (OBB) lattice and each candidate-to-target ray. It therefore depends on the root EVL fields, voxel geometry, target pose and extent, and the queried candidate pose. Each candidate is queried independently, so candidate permutations permute output rows without changing their values. Neither readout uses labels, selected future observations, or action validity.

For samples \(x_1,\ldots,x_K\) with support indicators \(m_k\in\{0,1\}\), :func:_reduce emits the supported mean, maximum, and support fraction:

\[ \bar{x}=\frac{\sum_k m_k x_k}{\max(\sum_k m_k,1)},\qquad x_{\max}=\max_{k:m_k=1}x_k,\qquad \rho=\frac{1}{K}\sum_k m_k. \]

The guarded denominator is the existing empty-support convention: mean and maximum are zero-filled when no sample is supported, while available distinguishes that missing result from an observed zero. See sample_voxel_field for the world-to-voxel sampling and support-envelope contract.

1.1 Attributes

Name	Description
QhCandidateReadoutConfig	Closed serialized choice between configured candidate readouts.

1.2 Classes

Name	Description
QhSpatialReadout	Read EVL evidence at a target OBB lattice and candidate-target rays.
QhSpatialReadoutConfig	Configure target-lattice and candidate-ray EVL sampling.
QhSummaryReadout	Broadcast target-independent global EVL statistics to candidates.
QhSummaryReadoutConfig	Configure target- and candidate-independent global EVL reductions.

1.2.1 QhSpatialReadout

vin.modules.qh_candidate_readout.QhSpatialReadout(config)

Read EVL evidence at a target OBB lattice and candidate-target rays.

The target region uses the Cartesian product \(u\in\{-\tfrac12,0,\tfrac12\}^3\). For target pose \(T_{WT}\) and side lengths \(e=(e_x,e_y,e_z)\), its 27 world samples are \(p_T(u)=T_{WT}(u\odot e)\). Because the complete signed lattice is sampled, permuting its signed target axes describes the same point set and leaves these permutation-invariant reductions unchanged.

Candidate \(n\) at state \(s\) contributes a ray from its world optical centre \(c_{sn}\) to the target centre \(t\): \(p_{sn}(\alpha)=(1-\alpha)c_{sn}+\alpha t\) for equally spaced \(\alpha\in[0,1]\). Target-region blocks depend on the target and root evidence but are broadcast over candidates. Ray blocks also depend on that row’s candidate pose. Reductions discard sample order and within-region arrangement while retaining supported mean, maximum, and the fraction of the fixed sample set with valid evidence.

Missing channels, absent voxel geometry, non-finite interpolation footprints, and samples outside the metric voxel-centre support envelope are unavailable. Zero support is represented by zero values plus the explicit availability mask. Source tensors remain attached to autograd. Frustum visibility is outside this interface because the actor carries no camera calibration from which to derive it.

1.2.1.1 Methods

Name	Description
forward	Sample and reduce target/ray evidence into candidate rows.

1.2.1.1.1 forward

vin.modules.qh_candidate_readout.QhSpatialReadout.forward(actor)

Sample and reduce target/ray evidence into candidate rows.

1.2.1.1.1.1 Parameters

Name	Type	Description	Default
actor	QhActorTensors	Batched root evidence, target geometry, and candidate poses. Candidate poses and masks use B,S,N leading axes; target extents are Tensor["B 3", float32] in target-frame metres. Root and target pose storage is exactly B,12; candidate storage is exactly B,S,N,12. Poses must be real floating tensors on the boolean masks’ device, including absent-evidence and empty-candidate calls. Singleton broadcasting is rejected; nonfinite inactive padding is allowed.	required

1.2.1.1.1.2 Returns

Name	Type	Description
	QhCandidateFeatures	class:QhCandidateFeatures with Tensor["B S N F", float32]
	QhCandidateFeatures	values and aligned boolean availability. Feature blocks follow the
	QhCandidateFeatures	region-major order target then ray. Empty N is valid and
	QhCandidateFeatures	returns the same rank without invoking the sampler.

1.2.1.1.1.3 Raises

Name	Type	Description
	ValueError	If declared-present EVL geometry, active poses, or target extents violate their shape, finiteness, or bounds contracts.

1.2.2 QhSpatialReadoutConfig

vin.modules.qh_candidate_readout.QhSpatialReadoutConfig()

Configure target-lattice and candidate-ray EVL sampling.

1.2.2.1 Attributes

Name	Description
kind	Closed serialization discriminator for the spatial readout.
channels	Unique EVL channels in output order; channel values are never mixed.
ray_samples	Equally spaced ray samples including candidate and target endpoints.
candidate_chunk_size	Maximum candidate rows sampled per interpolation call.
feature_spec	Return the static target/ray layout without model setup.
target_type	Return the concrete module for target and ray sampling.

1.2.3 QhSummaryReadout

vin.modules.qh_candidate_readout.QhSummaryReadout(config)

Broadcast target-independent global EVL statistics to candidates.

Each channel is flattened across its 1,D,H,W axes and reduced over all voxels. This retains its global supported mean, maximum, and finite-support fraction while discarding every spatial arrangement. The resulting B,F descriptor is copied across S,N; it cannot distinguish targets or candidates that share the same root EVL evidence.

1.2.3.1 Methods

Name	Description
forward	Return global statistics aligned with materialized candidate rows.

1.2.3.1.1 forward

vin.modules.qh_candidate_readout.QhSummaryReadout.forward(actor)

Return global statistics aligned with materialized candidate rows.

1.2.3.1.1.1 Parameters

Name	Type	Description	Default
actor	QhActorTensors	Batched actor state whose EVL fields have leading batch axis B and whose candidate materialization mask is Tensor["B S N", bool].	required

1.2.3.1.1.2 Returns

Name	Type	Description
	QhCandidateFeatures	class:QhCandidateFeatures with target- and candidate-independent
	QhCandidateFeatures	float32 values broadcast to shape B,S,N,F. Padded states
	QhCandidateFeatures	and candidates are unavailable and zero-filled. action_mask is
	QhCandidateFeatures	intentionally ignored.

1.2.4 QhSummaryReadoutConfig

vin.modules.qh_candidate_readout.QhSummaryReadoutConfig()

Configure target- and candidate-independent global EVL reductions.

1.2.4.1 Attributes

Name	Description
kind	Closed serialization discriminator for the global summary readout.
channels	Unique EVL channels in output order; channel values are never mixed.
feature_spec	Return the static layout of global reductions.
target_type	Return the concrete module for global summary reduction.