warp.volume\_sample
===================

.. function:: warp._src.lang.volume_sample(id: uint64, uvw: vec3f, sampling_mode: int32, dtype: Any) -> Any

   .. hlist::
      :columns: 8

      * 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 :func:`~warp.volume_world_to_index`. ``sampling_mode`` must be
   :attr:`warp.Volume.CLOSEST` or :attr:`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
   :func:`~warp.volume_sample_index`. See
   :class:`warp.Volume` and the :ref:`Volume sampling <volume_sampling>` user-guide examples.
   
   :param id: The ``id`` of a :class:`warp.Volume` to sample.
   :param uvw: Sampling location in index space (voxel coordinates); may be fractional.
   :param sampling_mode: :attr:`warp.Volume.CLOSEST` or :attr:`warp.Volume.LINEAR`; use ``CLOSEST`` for
                         integer data.
   :param dtype: Value type stored by the volume. ``dtype`` must be one of ``int32``, ``int64``,
                 ``uint32``, ``float32``, ``float64``, :class:`warp.vec3f`, :class:`warp.vec3d`,
                 :class:`warp.vec4f`, or :class:`warp.vec4d`.
   
   :returns: The sampled value of type ``dtype``. Locations without a stored value use the volume's
             background value.
   
   .. rubric:: Example
   
   .. testcode::
   
       @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))
   
   .. testoutput::
   
       0.5