Add mj_multiRay function to perform multiple ray intersection with the same source.

PiperOrigin-RevId: 528684535
Change-Id: I6e1747a4a0910e6061d6154e19ad8723f56c22e3

doc/APIreference/functions.rst

@@ -843,14 +843,25 @@ where jar = Jac*qacc-aref.
 Ray collisions
 ^^^^^^^^^^^^^^
 
-Ray collision functionality was added in MuJoCo 1.50. This is a new collision detection module that uses analytical
-formulas to intersect a ray ``(p + x*v, x >= 0)`` with a geom, where p is the origin of the ray and v is the vector
-specifying the direction. All functions in this family return the distance to the nearest geom surface, or -1 if there
-is no intersection. Note that if p is inside a geom, the ray will intersect the surface from the inside which still
-counts as an intersection.
+Ray collisions, also known as ray casting, find the distance ``x`` of a ray's intersection with a geom, where a ray is
+a line emanating from the 3D point ``p`` in the direction ``v`` i.e., ``(p + x*v, x >= 0)``. All functions in this
+family return the distance to the nearest geom surface, or -1 if there is no intersection. Note that if ``p`` is inside
+a geom, the ray will intersect the surface from the inside which still counts as an intersection.
 
 All ray collision functions rely on quantities computed by :ref:`mj_kinematics` (see :ref:`mjData`), so must be called
-after  :ref:`mj_kinematics`, or functions that call it (e.g. :ref:`mj_fwdPosition`).
+after  :ref:`mj_kinematics`, or functions that call it (e.g. :ref:`mj_fwdPosition`). The top level functions, which
+intersect with all geoms types, are :ref:`mj_ray` which casts a single ray, and :ref:`mj_multiRay` which casts multiple
+rays from a single point.
+
+.. _mj_multiRay:
+
+mj_multiRay
+~~~~~~~~~~~
+
+.. mujoco-include:: mj_multiRay
+
+Intersect multiple rays emanating from a single point.
+Similar semantics to mj_ray, but vec is an array of (nray x 3) directions.
 
 .. _mj_ray:
 

doc/APIreference/functions_override.rst

@@ -148,14 +148,15 @@ format of qpos.
 
 .. _Raycollisions:
 
-Ray collision functionality was added in MuJoCo 1.50. This is a new collision detection module that uses analytical
-formulas to intersect a ray ``(p + x*v, x >= 0)`` with a geom, where p is the origin of the ray and v is the vector
-specifying the direction. All functions in this family return the distance to the nearest geom surface, or -1 if there
-is no intersection. Note that if p is inside a geom, the ray will intersect the surface from the inside which still
-counts as an intersection.
+Ray collisions, also known as ray casting, find the distance ``x`` of a ray's intersection with a geom, where a ray is
+a line emanating from the 3D point ``p`` in the direction ``v`` i.e., ``(p + x*v, x >= 0)``. All functions in this
+family return the distance to the nearest geom surface, or -1 if there is no intersection. Note that if ``p`` is inside
+a geom, the ray will intersect the surface from the inside which still counts as an intersection.
 
 All ray collision functions rely on quantities computed by :ref:`mj_kinematics` (see :ref:`mjData`), so must be called
-after  :ref:`mj_kinematics`, or functions that call it (e.g. :ref:`mj_fwdPosition`).
+after  :ref:`mj_kinematics`, or functions that call it (e.g. :ref:`mj_fwdPosition`). The top level functions, which
+intersect with all geoms types, are :ref:`mj_ray` which casts a single ray, and :ref:`mj_multiRay` which casts multiple
+rays from a single point.
 
 .. _mj_ray:
 

doc/changelog.rst

@@ -15,7 +15,8 @@ Plugins
 - Added touch-grid sensor plugin. See `documentation <https://github.com/deepmind/mujoco/blob/main/plugin/sensor/README.md>`_
   for details, and associated `touch_grid.xml <https://github.com/deepmind/mujoco/blob/main/model/plugin/touch_grid.xml>`_
   example model. The plugin includes `in-scene visualisation <https://youtu.be/0LOJ3WMnqeA>`_.
-
+- Add ``mj_multiRay`` function for intersecting multiple rays emanating from a single point. This is significantly
+  faster than calling ``mj_ray`` multiple times.
 
 Version 2.3.5 (April 25, 2023)
 ------------------------------

doc/includes/references.h

@@ -2207,6 +2207,9 @@ void mj_loadPluginLibrary(const char* path);
 void mj_loadAllPluginLibraries(const char* directory, mjfPluginLibraryLoadCallback callback);
 int mj_version(void);
 const char* mj_versionString();
+void mj_multiRay(const mjModel* m, mjData* d, const mjtNum pnt[3], const mjtNum* vec,
+                 const mjtByte* geomgroup, mjtByte flg_static, int bodyexclude,
+                 int* geomid, mjtNum* dist, int nray);
 mjtNum mj_ray(const mjModel* m, const mjData* d, const mjtNum pnt[3], const mjtNum vec[3],
               const mjtByte* geomgroup, mjtByte flg_static, int bodyexclude,
               int geomid[1]);