warp.volume_sample

warp.volume_sample(

id: uint64,

uvw: vec3f,

sampling_mode: int32,

dtype: Any,

) → Any

Kernel

Differentiable

Sample the volume of type dtype given by id at the index-space point uvw.

uvw is expressed in index space (voxel coordinates) and may be fractional; convert a world-space position first with volume_world_to_index(). sampling_mode must be warp.Volume.CLOSEST or warp.Volume.LINEAR. CLOSEST rounds each coordinate to the nearest voxel. Currently, exact halfway cases are rounded away from zero. Use CLOSEST for integer data; LINEAR performs trilinear interpolation for floating-point scalar and vector data.

dtype must match the volume’s stored value type.

For floating-point scalar and vector data, LINEAR sampling is differentiable with respect to uvw away from integer voxel planes. The field is not generally differentiable at those planes. Currently, the derivative comes from the cell on the positive side, but callers should not rely on that behavior. The derivative is zero for CLOSEST. Currently, gradients are not propagated to the stored voxel values. To read values held in a separate array, use volume_sample_index(). See warp.Volume and the Volume sampling user-guide examples.

Parameters:

• id – The id of a warp.Volume to sample.

• uvw – Sampling location in index space (voxel coordinates); may be fractional.

• sampling_mode – warp.Volume.CLOSEST or warp.Volume.LINEAR; use CLOSEST for integer data.

• dtype – Value type stored by the volume. dtype must be one of int32, int64, uint32, float32, float64, warp.vec3f, warp.vec3d, warp.vec4f, or warp.vec4d.

Returns:

The sampled value of type dtype. Locations without a stored value use the volume’s background value.

Example

@wp.kernel
def sample(vid: wp.uint64, out: wp.array[wp.float32]):
    p = wp.volume_world_to_index(vid, wp.vec3(0.5, 0.0, 0.0))
    out[0] = wp.volume_sample(vid, p, wp.Volume.LINEAR, dtype=float)

values = np.zeros((2, 2, 2), dtype=np.float32)
values[1, :, :] = 1.0  # f(i, j, k) = i
volume = wp.Volume.load_from_numpy(values, voxel_size=1.0, bg_value=0.0)
out = wp.zeros(1, dtype=wp.float32)
wp.launch(sample, dim=1, inputs=[volume.id], outputs=[out])
print(round(float(out.numpy()[0]), 1))

0.5