warp.mesh\_query\_point
=======================

.. function:: warp._src.lang.mesh_query_point(id: uint64, point: vec3f, max_dist: float32) -> MeshQueryPoint

   .. hlist::
      :columns: 8

      * Kernel
      * Differentiable

   Compute the closest point on the :class:`warp.Mesh` with identifier ``id`` to the given ``point`` in space.
   
   The sign of the distance (inside/outside) is determined by casting three axis-aligned rays from
   ``point`` and taking a majority vote over the orientation of the closest hit along each ray; a ray
   that misses the mesh counts as an outside vote. Classification therefore relies on consistent,
   outward-facing winding and assumes a watertight mesh, and it is relatively robust but more expensive
   than :func:`mesh_query_point_sign_normal`. Sign classification examines the whole mesh and is not
   bounded by ``max_dist``, which only limits the returned closest point. See the other
   ``mesh_query_point_*`` functions for alternative sign-determination methods.
   
   Triangles that are degenerate or nearly degenerate relative to their edge lengths are excluded from
   the closest-point search, so such a face can be skipped even when it satisfies the distance
   constraint. If every face satisfying the distance constraint is excluded, the query returns no result.
   
   :param id: The mesh identifier
   :param point: The query point, in the mesh's local space
   :param max_dist: Maximum allowed distance to the returned closest point. The query returns no result if no face is strictly closer than this distance.
   
   :returns: A :class:`warp.MeshQueryPoint`. Check ``result`` first (``True`` if a face within
             ``max_dist`` was found), then read ``sign`` (< 0 if ``point`` is inside the mesh, >= 0 if
             outside), ``face`` (index of the closest face), and the barycentric coordinates ``u`` and
             ``v`` of the closest point on that face. Pass ``face``, ``u`` and ``v`` to
             :func:`mesh_eval_position` to obtain the closest point's position.
   
   .. rubric:: Example
   
   .. testcode::
   
       @wp.kernel
       def nearest(mesh_id: wp.uint64, p: wp.vec3, out_pos: wp.array[wp.vec3], out_inside: wp.array[wp.int32]):
           res = wp.mesh_query_point(mesh_id, p, 1.0e6)
           if res.result:
               out_pos[0] = wp.mesh_eval_position(mesh_id, res.face, res.u, res.v)
               out_inside[0] = wp.where(res.sign < 0.0, 1, 0)
   
       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_pos = wp.zeros(1, dtype=wp.vec3)
       out_inside = wp.zeros(1, dtype=wp.int32)
       wp.launch(nearest, dim=1, inputs=[mesh.id, wp.vec3(0.5, 0.5, 0.25)], outputs=[out_pos, out_inside])
       print(out_pos.numpy()[0], "inside:", bool(out_inside.numpy()[0]))
   
   .. testoutput::
   
       [0.5 0.5 0. ] inside: True