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

.. function:: warp._src.lang.volume_sample_index(id: uint64, uvw: vec3f, sampling_mode: int32, voxel_data: Array[Any], background: Any) -> Any

   .. hlist::
      :columns: 8

      * Kernel
      * Differentiable

   Sample the volume given by ``id`` at the index-space point ``uvw``, reading voxel values from
   a separate ``voxel_data`` array.
   
   Each indexable voxel maps to a zero-based element of ``voxel_data``. ``background`` is used when
   a sampled location has no indexable voxel. This lets several fields share one topology. See
   :meth:`warp.Volume.allocate_by_voxels` and :func:`~warp.volume_lookup_index`.
   
   ``uvw`` is in index space (voxel coordinates) and may be fractional. Sampling modes and boundary
   conventions match :func:`~warp.volume_sample`; use ``CLOSEST`` for integer data. For
   floating-point scalar and vector data, ``LINEAR`` is differentiable with respect to ``uvw``,
   ``voxel_data``, and ``background``. See the
   :ref:`Volume sampling <volume_sampling>` user-guide examples.
   
   :param id: The ``id`` of a :class:`warp.Volume` providing the topology and voxel indices.
   :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 voxel_data: Per-voxel values indexed by each voxel's linear index. The array must provide at
                      least :func:`~warp.volume_voxel_count` entries; use
                      :meth:`warp.Volume.get_voxel_count` when allocating it from Python. Its dtype must match
                      ``background``.
   :param background: Value used when a sampled location has no indexable voxel; its dtype must match
                      ``voxel_data``.
   
   :returns: The sampled value, of the same dtype as ``voxel_data``.
   
   .. rubric:: Example
   
   .. testcode::
   
       @wp.kernel
       def fill(vid: wp.uint64, d: wp.array[wp.float32]):
           i, j, k = wp.tid()
           idx = wp.volume_lookup_index(vid, i, j, k)
           if idx >= 0:
               d[idx] = wp.float32(i) * 10.0
   
       @wp.kernel
       def sample(vid: wp.uint64, d: wp.array[wp.float32], out: wp.array[wp.float32]):
           out[0] = wp.volume_sample_index(vid, wp.vec3(0.5, 0.0, 0.0), wp.Volume.LINEAR, d, 0.0)
   
       voxels = wp.array([[0, 0, 0], [1, 0, 0]], dtype=wp.vec3i)
       volume = wp.Volume.allocate_by_voxels(voxels, voxel_size=1.0)
       data = wp.zeros(volume.get_voxel_count(), dtype=wp.float32)
       out = wp.zeros(1, dtype=wp.float32)
       wp.launch(fill, dim=(2, 1, 1), inputs=[volume.id, data])
       wp.launch(sample, dim=1, inputs=[volume.id, data], outputs=[out])
       print(round(float(out.numpy()[0]), 1))
   
   .. testoutput::
   
       5.0