Changes to inertia inference from meshes.

PiperOrigin-RevId: 726051033
Change-Id: I6edfc118280d103a2dd9d07f29f0094858769761

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