chenlin/Mujoco_WASM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Breaking change: Add surface normal output to MuJoCo raycast functions.

Browse Source 
PiperOrigin-RevId: 855781592
Change-Id: Id96b1ca7eaf722e260cc69d7706c28dc51f52d92
This commit is contained in:
Yuval Tassa
2026-01-13 10:21:31 -08:00
committed by Copybara-Service
parent 37762e3f70
commit 218226fc95
17 changed files with 457 additions and 326 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/APIreference/functions.rst
+30 -20
View File
@@ -1150,19 +1150,6 @@ after :ref:`mj_kinematics`, or functions that call it (e.g. :ref:`mj_fwdPositio
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 <#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.
*Nullable:* ``geomgroup``
.. _mj_ray:
`mj_ray <#mj_ray>`__
@@ -1174,12 +1161,29 @@ Intersect ray ``pnt+x*vec, x >= 0`` with geoms.
- Return distance ``x`` to nearest surface, or -1 if no intersection.
- If ``geomid`` is not NULL, write the id of the intersected geom or -1 if not intersection.
- If ``normal`` is not NULL, write the surface normal at the intersection point. The normal always points **out of the
geometry**, regardless of the ray's direction (i.e., including rays hitting the surface from the inside).
- Exclude geoms in body with id ``bodyexclude``, use -1 to include all bodies.
- ``geomgroup`` is an array of length :ref:`mjNGROUP<glNumeric>`, where 1 means the group should be included. Pass
NULL to skip geom group exclusion.
- If ``flg_static`` is 0, static geoms will be excluded.
*Nullable:* ``geomgroup``, ``geomid``
*Nullable:* ``geomgroup``, ``geomid``, ``normal``
.. _mj_multiRay:
`mj_multiRay <#mj_multiRay>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. mujoco-include:: mj_multiRay
Intersect multiple rays emanating from a single point, compute normals if given.
Similar semantics to mj_ray, but vec, normal and dist are arrays.
Geoms further than cutoff are ignored.
*Nullable:* ``geomgroup``, ``geomid``, ``normal``
.. _mj_rayHfield:
@@ -1190,6 +1194,8 @@ Intersect ray ``pnt+x*vec, x >= 0`` with geoms.
Intersect ray with hfield; return nearest distance or -1 if no intersection.
*Nullable:* ``normal``
.. _mj_rayMesh:
`mj_rayMesh <#mj_rayMesh>`__
@@ -1199,6 +1205,8 @@ Intersect ray with hfield; return nearest distance or -1 if no intersection.
Intersect ray with mesh; return nearest distance or -1 if no intersection.
*Nullable:* ``normal``
.. _mju_rayGeom:
`mju_rayGeom <#mju_rayGeom>`__
@@ -1208,17 +1216,19 @@ Intersect ray with mesh; return nearest distance or -1 if no intersection.
Intersect ray with pure geom; return nearest distance or -1 if no intersection.
.. _mju_rayFlex:
*Nullable:* ``normal``
`mju_rayFlex <#mju_rayFlex>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _mj_rayFlex:
.. mujoco-include:: mju_rayFlex
`mj_rayFlex <#mj_rayFlex>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. mujoco-include:: mj_rayFlex
Intersect ray with flex; return nearest distance or -1 if no intersection,
and also output nearest vertex id.
and also output nearest vertex id and surface normal.
*Nullable:* ``vertid``
*Nullable:* ``vertid``, ``normal``
.. _mju_raySkin:
doc/APIreference/functions_override.rst
+3 -1
View File
@@ -332,12 +332,14 @@ Intersect ray ``pnt+x*vec, x >= 0`` with geoms.
- Return distance ``x`` to nearest surface, or -1 if no intersection.
- If ``geomid`` is not NULL, write the id of the intersected geom or -1 if not intersection.
- If ``normal`` is not NULL, write the surface normal at the intersection point. The normal always points **out of the
geometry**, regardless of the ray's direction (i.e., including rays hitting the surface from the inside).
- Exclude geoms in body with id ``bodyexclude``, use -1 to include all bodies.
- ``geomgroup`` is an array of length :ref:`mjNGROUP<glNumeric>`, where 1 means the group should be included. Pass
NULL to skip geom group exclusion.
- If ``flg_static`` is 0, static geoms will be excluded.
*Nullable:* ``geomgroup``, ``geomid``
*Nullable:* ``geomgroup``, ``geomid``, ``normal``
.. _Interaction:
doc/changelog.rst
+12 -1
View File
@@ -8,6 +8,17 @@ Upcoming version (not yet released)
.. admonition:: Breaking API changes
:class: attention
- Ray-cast functions now optionally compute the surface normal at the ray intersection. This is a breaking change due
to the addition of the ``mjtNum normal[3]`` argument. The modified functions are :ref:`mj_ray`, :ref:`mj_multiRay`,
:ref:`mju_rayGeom`, :ref:`mj_rayFlex`, :ref:`mj_rayHfield` and :ref:`mj_rayMesh`.
**Migration:** In C/C++, pass ``NULL`` to the ``normal`` argument (last argument for all functions except
:ref:`mj_multiRay`). Note that in the Python bindings, if the new ``normal`` argument is last, it defaults to
``None``, so no changes are required.
- ``mju_rayFlex`` has been renamed to :ref:`mj_rayFlex` for consistency with other functions that take
``mjModel*`` and ``mjData*`` arguments.
- The ``mjModel.cam_orthographic`` field has been renamed to ``cam_projection``, with the semantic of a new enum type
:ref:`mjtProjection`. This will allow for more projection types in the future like fisheye cameras.
Relatedly, the ``camera/orthographic`` MJCF attribute for cameras has been renamed to
@@ -68,7 +79,7 @@ Bug fixes
- Multi threaded mesh processing, enabled by the :ref:`usethread<compiler-usethread>` compiler flag (on by default), was
in fact disabled by the flag. Fixing this bug speeds up compilation of mesh-heavy models by (up to) the number of
available cores.
- The ``vertid`` argument of :ref:`mju_rayFlex` and :ref:`mju_raySkin` was marked as nullable but was not; it is now
- The ``vertid`` argument of :ref:`mj_rayFlex` and :ref:`mju_raySkin` was marked as nullable but was not; it is now
nullable.
Version 3.4.0 (December 5, 2025)
doc/includes/references.h
+12 -10
View File
@@ -3255,21 +3255,23 @@ void mj_loadPluginLibrary(const char* path);
void mj_loadAllPluginLibraries(const char* directory, mjfPluginLibraryLoadCallback callback);
int mj_version(void);
const char* mj_versionString(void);
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 cutoff);
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]);
int geomid[1], mjtNum normal[3]);
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, mjtNum* normal, int nray, mjtNum cutoff);
mjtNum mj_rayHfield(const mjModel* m, const mjData* d, int geomid,
const mjtNum pnt[3], const mjtNum vec[3]);
const mjtNum pnt[3], const mjtNum vec[3], mjtNum normal[3]);
mjtNum mj_rayMesh(const mjModel* m, const mjData* d, int geomid,
const mjtNum pnt[3], const mjtNum vec[3]);
const mjtNum pnt[3], const mjtNum vec[3], mjtNum normal[3]);
mjtNum mju_rayGeom(const mjtNum pos[3], const mjtNum mat[9], const mjtNum size[3],
const mjtNum pnt[3], const mjtNum vec[3], int geomtype);
mjtNum mju_rayFlex(const mjModel* m, const mjData* d, int flex_layer, mjtByte flg_vert,
mjtByte flg_edge, mjtByte flg_face, mjtByte flg_skin, int flexid,
const mjtNum pnt[3], const mjtNum vec[3], int vertid[1]);
const mjtNum pnt[3], const mjtNum vec[3], int geomtype,
mjtNum normal[3]);
mjtNum mj_rayFlex(const mjModel* m, const mjData* d, int flex_layer,
mjtByte flg_vert, mjtByte flg_edge, mjtByte flg_face,
mjtByte flg_skin, int flexid, const mjtNum pnt[3],
const mjtNum vec[3], int vertid[1], mjtNum normal[3]);
mjtNum mju_raySkin(int nface, int nvert, const int* face, const float* vert,
const mjtNum pnt[3], const mjtNum vec[3], int vertid[1]);
void mjv_defaultCamera(mjvCamera* cam);