warp.mesh\_query\_ray
=====================

.. function:: warp._src.lang.mesh_query_ray(id: uint64, start: vec3f, dir: vec3f, max_t: float32, root: int32) -> MeshQueryRay

   .. hlist::
      :columns: 8

      * Kernel
      * Differentiable

   Compute the closest ray hit on the :class:`warp.Mesh` with identifier ``id``.
   
   ``start`` and ``dir`` are given in the mesh's local space. ``dir`` need not be normalized, but
   ``max_t`` and the returned ``t`` are measured in multiples of its length, so normalize it for
   them to be distances in mesh-space units.
   
   The ``root`` parameter can be obtained using the :func:`mesh_get_group_root` function when creating a grouped mesh.
   When ``root`` is a valid (>=0) value, the traversal will be confined to the subtree starting from the root.
   If ``root`` is -1 (default), traversal starts at the mesh's global root.
   
   :param id: The mesh identifier
   :param start: The ray origin, in the mesh's local space
   :param dir: The ray direction, in the mesh's local space (see above on normalization)
   :param max_t: The maximum distance along the ray to check for intersections (in multiples of ``dir``'s length)
   :param root: The root node index for grouped BVH queries, or -1 for global root (optional, default: -1)
   
   :returns: A :class:`warp.MeshQueryRay`. Check ``result`` first (``True`` if a hit within ``max_t`` was
             found), then read ``t`` (distance to the hit, in multiples of ``dir``'s length), ``face``
             (index of the hit face), ``normal`` (the unit face normal, oriented by the face's winding
             order), ``sign`` (> 0 if the ray hit the front of the face, < 0 the back), and the
             barycentric coordinates ``u`` and ``v`` of the hit. The hit position is ``start + t * dir``.
   
   .. rubric:: Example
   
   .. testcode::
   
       @wp.kernel
       def cast(mesh_id: wp.uint64, origin: wp.vec3, dir: wp.vec3, out_t: wp.array[wp.float32], out_n: wp.array[wp.vec3]):
           hit = wp.mesh_query_ray(mesh_id, origin, dir, 1.0e6)
           if hit.result:
               out_t[0] = hit.t
               out_n[0] = hit.normal
   
       points = wp.array([[0,0,0],[1,0,0],[1,1,0],[0,1,0],[0,0,1],[1,0,1],[1,1,1],[0,1,1]], dtype=wp.vec3)
       indices = wp.array([0,3,2, 0,2,1,  4,5,6, 4,6,7,  0,1,5, 0,5,4,
                           2,3,7, 2,7,6,  0,4,7, 0,7,3,  1,2,6, 1,6,5], dtype=wp.int32)
       mesh = wp.Mesh(points=points, indices=indices)
   
       out_t = wp.zeros(1, dtype=wp.float32)
       out_n = wp.zeros(1, dtype=wp.vec3)
       wp.launch(cast, dim=1, inputs=[mesh.id, wp.vec3(0.5, 0.5, -2.0), wp.vec3(0.0, 0.0, 1.0)], outputs=[out_t, out_n])
       print("t =", out_t.numpy()[0], "normal =", out_n.numpy()[0])
   
   .. testoutput::
   
       t = 2.0 normal = [ 0.  0. -1.]