Add support for mesh site types with insidesite detector integration, and mj_insideSite API function.

PiperOrigin-RevId: 977453785
Change-Id: I5b6872e6ed0f46a566a1bd75f2fd43ac0ee2a815

Author: yuvaltassa

doc/APIreference/functions.rst

@@ -696,6 +696,15 @@ found, the function will return ``distmax`` and ``fromto``, if given, will be se
    As explained in :ref:`Collision Detection<coDistance>`, distances are inaccurate when using the
    :ref:`legacy CCD pipeline<coCCD>`, and its use is discouraged.
 
+.. _mj_insideSite:
+
+`mj_insideSite <#mj_insideSite>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mj_insideSite
+
+Return 1 if point is inside a site (convex hull for meshes), 0 otherwise.
+
 .. _mj_contactForce:
 
 `mj_contactForce <#mj_contactForce>`__

doc/XMLreference.rst

@@ -14,7 +14,8 @@ XML schema
 ~~~~~~~~~~
 
 The dropdown below summarizes the XML elements and their attributes in MJCF. All information in MJCF is entered through
-elements and attributes. Text content in elements is not used (except for CDATA in :ref:`custom text<custom-text>` elements); if present, the parser ignores it.
+elements and attributes. Text content in elements is not used (except for CDATA in :ref:`custom text<custom-text>`
+elements); if present, the parser ignores it.
 
 .. only:: html
 
@@ -3023,7 +3024,7 @@ tendons, constructing slider-crank transmissions for actuators.
 
 .. _body-site-type:
 
-:at:`type`: :at-val:`[sphere, capsule, ellipsoid, cylinder, box], "sphere"`
+:at:`type`: :at-val:`[sphere, capsule, ellipsoid, cylinder, box, mesh], "sphere"`
    Type of geometric shape. This is used for rendering, and also determines the active sensor zone for :ref:`touch
    sensors <sensor-touch>`.
 
@@ -3038,6 +3039,11 @@ tendons, constructing slider-crank transmissions for actuators.
 :at:`material`: :at-val:`string, optional`
    Material used to specify the visual properties of the site.
 
+.. _body-site-mesh:
+
+:at:`mesh`: :at-val:`string, optional`
+   Mesh asset name. This attribute is required if the site type is "mesh".
+
 .. _body-site-rgba:
 
 :at:`rgba`: :at-val:`real(4), "0.5 0.5 0.5 1"`
@@ -3594,9 +3600,11 @@ This sub-element adjusts the attributes of the sites in the composite object. Ot
 
 .. _composite-site-material:
 
+.. _composite-site-mesh:
+
 .. _composite-site-rgba:
 
-:at:`group`, :at:`size`, :at:`material`, :at:`rgba`
+:at:`group`, :at:`size`, :at:`material`, :at:`mesh`, :at:`rgba`
    Same meaning as regular :ref:`site <body-site>` attributes.
 
 
@@ -10034,6 +10042,8 @@ if omitted.
 
 .. _default-site-material:
 
+.. _default-site-mesh:
+
 .. _default-site-size:
 
 .. _default-site-fromto:

doc/XMLschema.rst

@@ -1037,6 +1037,9 @@
             .. grid-item::
                :ref:`material<body-site-material>`
 
+            .. grid-item::
+               :ref:`mesh<body-site-mesh>`
+
             .. grid-item::
                :ref:`size<body-site-size>`
 
@@ -1406,6 +1409,9 @@
                .. grid-item::
                   :ref:`rgba<composite-site-rgba>`
 
+               .. grid-item::
+                  :ref:`mesh<composite-site-mesh>`
+
 
          .. dropdown:: :ref:`plugin<composite-plugin>` |*|
 
@@ -5768,6 +5774,9 @@
             .. grid-item::
                :ref:`material<default-site-material>`
 
+            .. grid-item::
+               :ref:`mesh<default-site-mesh>`
+
             .. grid-item::
                :ref:`size<default-site-size>`
 

doc/changelog.rst

@@ -9,6 +9,9 @@ General
 ^^^^^^^
 - The :ref:`.mjz <MJZArchives>` encoder now writes the root file as ``model.xml`` in the archive as this is less
   susceptible to breakage due to file renaming.
+- Site geometries can now also be associated with meshes (:ref:`type="mesh"<body-site-type>` with
+  :ref:`mesh="name"<body-site-mesh>`), supporting visualization, the :ref:`insidesite<sensor-insidesite>`
+  sensor, and the new :ref:`mj_insideSite` function.
 - Added support for Python 3.15 (GIL and Free-Threading).
 
 Engine

doc/includes/references.h

@@ -835,6 +835,7 @@ typedef struct mjModel_ {
   // sites
   int*      site_type;            // geom type for rendering (mjtGeom)        (nsite x 1)
   int*      site_bodyid;          // id of site's body                        (nsite x 1)
+  int*      site_dataid;          // id of site's mesh; -1: none              (nsite x 1)
   int*      site_matid;           // material id for rendering; -1: none      (nsite x 1)
   int*      site_group;           // group for visibility                     (nsite x 1)
   mjtByte*  site_sameframe;       // same frame as body (mjtSameframe)        (nsite x 1)
@@ -1978,6 +1979,7 @@ typedef struct mjsSite_ {          // site specification
   float rgba[4];                   // rgba when material is omitted
 
   // other
+  mjString* meshname;              // mesh attached to site
   mjDoubleVec* userdata;           // user data
   mjString* info;                  // message appended to compiler errors
 } mjsSite;
@@ -3809,6 +3811,7 @@ void mj_objectAcceleration(const mjModel* m, const mjData* d,
                            int objtype, int objid, mjtNum res[6], int flg_local);
 mjtNum mj_geomDistance(const mjModel* m, mjData* d, int geom1, int geom2, mjtNum distmax,
                        mjtNum fromto[6]);
+int mj_insideSite(const mjModel* m, const mjData* d, int siteid, const mjtNum point[3]);
 void mj_contactForce(const mjModel* m, const mjData* d, int id, mjtNum result[6]);
 void mj_differentiatePos(const mjModel* m, mjtNum* qvel, mjtNum dt,
                          const mjtNum* qpos1, const mjtNum* qpos2);

include/mujoco/mjmodel.h

@@ -485,6 +485,7 @@ typedef struct mjModel_ {
   // sites
   int*      site_type;            // geom type for rendering (mjtGeom)        (nsite x 1)
   int*      site_bodyid;          // id of site's body                        (nsite x 1)
+  int*      site_dataid;          // id of site's mesh; -1: none              (nsite x 1)
   int*      site_matid;           // material id for rendering; -1: none      (nsite x 1)
   int*      site_group;           // group for visibility                     (nsite x 1)
   mjtByte*  site_sameframe;       // same frame as body (mjtSameframe)        (nsite x 1)

include/mujoco/mjspec.h

@@ -402,6 +402,7 @@ typedef struct mjsSite_ {          // site specification
   float rgba[4];                   // rgba when material is omitted
 
   // other
+  mjString* meshname;              // mesh attached to site
   mjDoubleVec* userdata;           // user data
   mjString* info;                  // message appended to compiler errors
 } mjsSite;

include/mujoco/mjspecmacro.h

@@ -213,6 +213,7 @@
     X   ( mjString*,      material, 1 ) \
     X   ( int,            group,    1 ) \
     XVEC( float,          rgba,     4 ) \
+    X   ( mjString*,      meshname, 1 ) \
     X   ( mjDoubleVec*,   userdata, 1 ) \
     X   ( mjString*,      info,     1 )
 

include/mujoco/mjxmacro.h

@@ -394,6 +394,7 @@
 #define MJMODEL_POINTERS_SITE                                                   \
     X   ( int,     site_type,             nsite,         1                    ) \
     X   ( int,     site_bodyid,           nsite,         1                    ) \
+    X   ( int,     site_dataid,           nsite,         1                    ) \
     X   ( int,     site_matid,            nsite,         1                    ) \
     X   ( int,     site_group,            nsite,         1                    ) \
     X   ( mjtByte, site_sameframe,        nsite,         1                    ) \

include/mujoco/mujoco.h

@@ -640,6 +640,9 @@ MJAPI void mj_objectAcceleration(const mjModel* m, const mjData* d,
 MJAPI mjtNum mj_geomDistance(const mjModel* m, mjData* d, int geom1, int geom2, mjtNum distmax,
                              mjtNum fromto[6]);
 
+// Return 1 if point is inside a site (convex hull for meshes), 0 otherwise.
+MJAPI int mj_insideSite(const mjModel* m, const mjData* d, int siteid, const mjtNum point[3]);
+
 // Extract 6D force:torque given contact id, in the contact frame.
 MJAPI void mj_contactForce(const mjModel* m, const mjData* d, int id, mjtNum result[6]);