Changes to inertia inference from meshes.

PiperOrigin-RevId: 726051033
Change-Id: I6edfc118280d103a2dd9d07f29f0094858769761

Author: powertj

doc/XMLreference.rst

@@ -1246,18 +1246,21 @@ The full list of processing steps applied by the compiler to each mesh is as fol
 
 .. _asset-mesh-inertia:
 
-:at:`inertia`: :at-val:`[convex, exact, legacy], "legacy"`
+:at:`inertia`: :at-val:`[convex, exact, legacy, shell], "legacy"`
    This attribute controls how the mesh is used when mass and inertia are
    :ref:`inferred from geometry<compiler-inertiafromgeom>`. The current default value :at-val:`legacy` will be changed
    to :at-val:`convex` in a future release.
 
-   :at-val:`convex`: Use the mesh's convex hull to compute volume and inertia.
+   :at-val:`convex`: Use the mesh's convex hull to compute volume and inertia, assuming uniform density.
 
-   :at-val:`exact`: Use an exact algorithm to compute volume and inertia. This algorithm requires a well-oriented,
-   watertight mesh and will error otherwise.
+   :at-val:`exact`: Compute volume and inertia exactly, even for non-convex meshes. This algorithm requires a
+   well-oriented, watertight mesh and will error otherwise.
 
-   :at-val:`legacy`: Use the legacy algorithm, which is similar to :at-val:`convex`, but leads to volume overcounting
-   for non-convex meshes.
+   :at-val:`legacy`: Use the legacy algorithm, leads to volume overcounting for non-convex meshes. Though currently the
+   default to avoid breakages, it is not recommended.
+
+   :at-val:`shell`: Assume mass is concentrated on the surface of the mesh. Use the mesh's surface to compute
+   the inertia, assuming uniform surface density.
 
 .. _asset-mesh-smoothnormal:
 
@@ -2457,8 +2460,10 @@ helps clarify the role of bodies and geoms in MuJoCo.
 .. _body-geom-shellinertia:
 
 :at:`shellinertia` :at-val:`[false, true], "false"`
-   If true, the geom's inertia is computed assuming that all the mass is concentrated on the boundary. In this case
-   :at:`density` is interpreted as surface density rather than volumetric density.
+   If true, the geom's inertia is computed assuming that all the mass is concentrated on the surface. In this case
+   :at:`density` is interpreted as surface rather than volumetric density. This attribute only applies to primitive
+   geoms and is ignored for meshes. Surface inertia for meshes can be specified by setting the
+   :ref:`asset/mesh/inertia<asset-mesh-inertia>` attribute to :at-val:`"shell"`.
 
 .. _body-geom-solmix:
 

doc/changelog.rst

@@ -34,6 +34,18 @@ General
 - Added :ref:`potential<sensor-e_potential>` and :ref:`kinetic<sensor-e_kinetic>` energy sensors.
 - Improved shadow rendering in the native renderer.
 
+.. admonition:: Breaking API changes
+   :class: attention
+
+   - Changes to inertia inference from meshes:
+
+     Previously, in order to specify that the mass lies on the surface, :ref:`geom/shellinertia<body-geom-shellinertia>`
+     could be used for any geom type. Now this attribute is ignored if the geom is a mesh; instead, inertia inference
+     for meshes is specified in the asset, using the :ref:`asset/mesh/inertia<asset-mesh-inertia>` attribute.
+
+     Previously, if the volumetric inertia computation failed (for example due to a very flat mesh), the compiler
+     would silently fall back to surface inertia computation. Now, the compiler will throw an informative error.
+
 MJX
 ^^^
 - Added support for spatial tendons with internal sphere and cylinder wrapping.

doc/includes/references.h

@@ -1652,10 +1652,11 @@ typedef enum mjtGeomInertia_ {     // type of inertia inference
   mjINERTIA_VOLUME = 0,            // mass distributed in the volume
   mjINERTIA_SHELL,                 // mass distributed on the surface
 } mjtGeomInertia;
-typedef enum mjtMeshInertia_ {     // type of mesh inertia
-  mjINERTIA_CONVEX = 0,            // convex mesh inertia
-  mjINERTIA_EXACT,                 // exact mesh inertia
-  mjINERTIA_LEGACY,                // legacy mesh inertia
+typedef enum mjtMeshInertia_ {      // type of mesh inertia
+  mjMESH_INERTIA_CONVEX = 0,        // convex mesh inertia
+  mjMESH_INERTIA_EXACT,             // exact mesh inertia
+  mjMESH_INERTIA_LEGACY,            // legacy mesh inertia
+  mjMESH_INERTIA_SHELL              // shell mesh inertia
 } mjtMeshInertia;
 typedef enum mjtBuiltin_ {         // type of built-in procedural texture
   mjBUILTIN_NONE = 0,              // no built-in texture
@@ -2008,7 +2009,7 @@ typedef struct mjsMesh_ {          // mesh specification
   double refpos[3];                // reference position
   double refquat[4];               // reference orientation
   double scale[3];                 // rescale mesh
-  mjtMeshInertia inertia;          // inertia type (convex, legacy, exact)
+  mjtMeshInertia inertia;          // inertia type (convex, legacy, exact, shell)
   mjtByte smoothnormal;            // do not exclude large-angle faces from normals
   int maxhullvert;                 // maximum vertex count for the convex hull
   mjFloatVec* uservert;            // user vertex data

include/mujoco/mjspec.h

@@ -62,10 +62,11 @@ typedef enum mjtGeomInertia_ {     // type of inertia inference
 } mjtGeomInertia;
 
 
-typedef enum mjtMeshInertia_ {     // type of mesh inertia
-  mjINERTIA_CONVEX = 0,            // convex mesh inertia
-  mjINERTIA_EXACT,                 // exact mesh inertia
-  mjINERTIA_LEGACY,                // legacy mesh inertia
+typedef enum mjtMeshInertia_ {      // type of mesh inertia
+  mjMESH_INERTIA_CONVEX = 0,        // convex mesh inertia
+  mjMESH_INERTIA_EXACT,             // exact mesh inertia
+  mjMESH_INERTIA_LEGACY,            // legacy mesh inertia
+  mjMESH_INERTIA_SHELL              // shell mesh inertia
 } mjtMeshInertia;
 
 
@@ -459,7 +460,7 @@ typedef struct mjsMesh_ {          // mesh specification
   double refpos[3];                // reference position
   double refquat[4];               // reference orientation
   double scale[3];                 // rescale mesh
-  mjtMeshInertia inertia;          // inertia type (convex, legacy, exact)
+  mjtMeshInertia inertia;          // inertia type (convex, legacy, exact, shell)
   mjtByte smoothnormal;            // do not exclude large-angle faces from normals
   int maxhullvert;                 // maximum vertex count for the convex hull
   mjFloatVec* uservert;            // user vertex data

introspect/enums.py

@@ -734,9 +734,10 @@
          name='mjtMeshInertia',
          declname='enum mjtMeshInertia_',
          values=dict([
-             ('mjINERTIA_CONVEX', 0),
-             ('mjINERTIA_EXACT', 1),
-             ('mjINERTIA_LEGACY', 2),
+             ('mjMESH_INERTIA_CONVEX', 0),
+             ('mjMESH_INERTIA_EXACT', 1),
+             ('mjMESH_INERTIA_LEGACY', 2),
+             ('mjMESH_INERTIA_SHELL', 3),
          ]),
      )),
     ('mjtBuiltin',

introspect/structs.py

@@ -10415,7 +10415,7 @@
              StructFieldDecl(
                  name='inertia',
                  type=ValueType(name='mjtMeshInertia'),
-                 doc='inertia type (convex, legacy, exact)',
+                 doc='inertia type (convex, legacy, exact, shell)',
              ),
              StructFieldDecl(
                  name='smoothnormal',

src/user/user_init.c

@@ -245,7 +245,7 @@ void mjs_defaultMesh(mjsMesh* mesh) {
   mesh->refquat[0] = 1;
   mesh->scale[0] = mesh->scale[1] = mesh->scale[2] = 1;
   mesh->maxhullvert = -1;
-  mesh->inertia = mjINERTIA_LEGACY;
+  mesh->inertia = mjMESH_INERTIA_LEGACY;
 }