1 vin.geometry.volume_fusion

vin.geometry.volume_fusion

Construct and update a fixed metric evidence volume for volumetric VIN.

Selected metric depth is fused by inverse rendering: volume-cell centres are projected into the calibrated raster, then compared with the measured camera-z return at the nearest pixel. A centre in front of the return contributes free support, a centre inside the tolerance band contributes surface support, and a centre behind the return stays unknown. This keeps invalid rays and occluded space from being silently carved free.

1.1 Classes

Name Description
VolumeFusionConfig Configuration for deterministic root initialization and selected-depth fusion.

1.1.1 VolumeFusionConfig

vin.geometry.volume_fusion.VolumeFusionConfig()

Configuration for deterministic root initialization and selected-depth fusion.

1.1.1.1 Attributes

Name Description
grid_size Dense volume shape (D,H,W); metric axes are (z,y,x).
margin_m Metric context added to every side of the persisted EVL chart.
depth_noise_m Additional camera-z tolerance beyond half the largest voxel spacing.
count_normalization Fixed log1p scale for root and selected observation counts.
recency_normalization Fixed selected-observation-index scale for the network recency channel.
root_support_semantics Versioned root support: v2 excludes image-feature projection counts.

1.2 Functions

Name Description
fuse_actor_observation Fuse one causal selected-prefix slot without exposing frame composition to callers.
fuse_observation Fuse one calibrated camera-z depth observation into a fresh state.
initialize_volume Initialize immutable root evidence on the expanded EVL chart.

1.2.1 fuse_actor_observation

vin.geometry.volume_fusion.fuse_actor_observation(
    state,
    actor,
    *,
    state_index,
    observation_index,
    depth_noise_m=None,
)

Fuse one causal selected-prefix slot without exposing frame composition to callers.

1.2.2 fuse_observation

vin.geometry.volume_fusion.fuse_observation(
    state,
    *,
    depth_m,
    valid_mask,
    camera,
    pose_world_camera,
    observation_id,
    active=True,
    depth_noise_m=None,
)

Fuse one calibrated camera-z depth observation into a fresh state.

Every cell receives at most one surface or free vote from this observation. Reusing an observation id for one batch row is a no-op for that row. Invalid pixels never establish free space, and cells behind the first valid return remain unknown.

1.2.3 initialize_volume

vin.geometry.volume_fusion.initialize_volume(actor, config)

Initialize immutable root evidence on the expanded EVL chart.

1.2.3.1 Parameters

Name Type Description Default
actor QhActorTensors Batched actor tensors. static_context must provide finite world-from-voxel geometry and an explicit eight-entry source mask. required
config VolumeFusionConfig Fixed volume geometry and normalization identity. required

1.2.3.2 Returns

Name Type Description
VolumeEvidence A fresh VolumeEvidence with zero selected-depth accumulators.

1.2.3.3 Raises

Name Type Description
ValueError If geometry, source presence, tensor layout, or active semidense rows violate the rich actor contract.
Back to top