Add shellinertia support for primitives: sphere, capsule, cylinder, ellipsoid, and box.

PiperOrigin-RevId: 661407997
Change-Id: Icddac58c540c71ea26ac7a3be874788443bd1122

doc/XMLreference.rst

@@ -2451,14 +2451,15 @@ helps clarify the role of bodies and geoms in MuJoCo.
    given mass, using the geom shape and the assumption of uniform density. The computed density is then used to obtain
    the geom inertia. Recall that the geom mass and inertia are only used during compilation, to infer the body mass and
    inertia if necessary. At runtime only the body inertial properties affect the simulation; the geom mass and inertia
-   are not even saved in mjModel.
+   are not saved in mjModel.
 
 .. _body-geom-density:
 
 :at:`density`: :at-val:`real, "1000"`
    Material density used to compute the geom mass and inertia. The computation is based on the geom shape and the
    assumption of uniform density. The internal default of 1000 is the density of water in SI units. This attribute is
-   used only when the mass attribute above is unspecified.
+   used only when the mass attribute above is unspecified. If `shellinertia` is "false" (the default), density has
+   semantics of mass/volume; if "true", it has semantics of mass/area.
 
 .. _body-geom-shellinertia:
 

doc/changelog.rst

@@ -2,6 +2,13 @@
 Changelog
 =========
 
+Upcoming version (not yet released)
+-----------------------------------
+
+General
+^^^^^^^
+- :ref:`shellinertia <body-geom-shellinertia>` is now supported by all geom types.
+
 Version 3.2.2 (Aug 8, 2024)
 ---------------------------
 
@@ -34,7 +41,8 @@ MJX
 Python bindings
 ^^^^^^^^^^^^^^^
 10. Added support for asset dictionary argument in ``mujoco.spec.from_file``, ``mujoco.spec.from_string`` and
-   ``mujoco.spec.compile``.
+    ``mujoco.spec.compile``.
+
 
 Bug fixes
 ^^^^^^^^^

doc/overview.rst

@@ -851,10 +851,14 @@ Geoms (short for geometric primitive) are used to specify appearance and collisi
 and is rigidly attached to that body. Multiple geoms can be attached to the same body. This is particularly useful in
 light of the fact that MuJoCo's collision detector assumes that all geoms are convex (it internally replaces meshes with
 their convex hulls if the meshes are not convex). Thus if you want to model a non-convex shape, you have to decompose it
-into a union of convex geoms and attach all of them to the same body. Geoms can also have mass and inertia in the XML
-model (or rather material density which is used to compute the mass and inertia), but that is only used to compute the
-body mass and inertia in the model compiler. In the actual ``mjModel`` being simulated geoms do not have inertial
-properties.
+into a union of convex geoms and attach all of them to the same body.
+
+A geom can also have density or mass values specified in the XML, which the model compiler uses to compute the parent
+body's mass and inertia. Mass is either specified or computed from a geom's volume and :ref:`density
+<body-geom-density>`. Inertia is computed from the mass, shape, and uniform density assumption. If the
+:ref:`shellinertia <body-geom-shellinertia>` flag is set, mass is assumed to be uniformly distributed on the **surface**,
+:at:`density` is interpreted as mass-per-area, and the inertia contribution to the parent body is computed accordingly.
+In the actual ``mjModel`` being simulated, geoms do not have inertial properties.
 
 Sites are light geoms. They have the same appearance properties but cannot participate in collisions and cannot be used
 to infer body masses. On the other hand sites can do things that geoms cannot do: they can specify the volumes of touch