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

Improve composite docs and changelog.

Browse Source 
PiperOrigin-RevId: 730394496
Change-Id: Ie993214deb82b526a96510e02f6ecff103c58607
This commit is contained in:
Alessio Quaglino
2025-02-24 04:25:38 -08:00
committed by Copybara-Service
parent 81b1948b46
commit b3aa5df68a
7 changed files with 78 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/modeling.rst
+48 -57
View File
@@ -1121,59 +1121,40 @@ Intrinsics
Composite objects
~~~~~~~~~~~~~~~~~
Composite objects are not new model elements. Instead, they are (large) collections of existing elements designed to
simulate particle systems, ropes, cloth, and soft bodies. These collections are generated by the model compiler
automatically. The user configures the automatic generator on a high level, using the new XML element
:ref:`composite <body-composite>` and its attributes and sub-elements, as described in the XML reference
chapter. If the compiled model is then saved, :el:`composite` is no longer present and is replaced with the collection
of regular model elements that were automatically generated. So think of it as a macro that gets expanded by the model
compiler.
Composite objects are not new model elements. Instead, they are collections of existing element originally designed to
simulate particle systems, ropes, cloth, and soft bodies. Over time, most of these types have been replaced by
:ref:`replicate<replicate>` (for repeated objects) and :ref:`flexcomp<body-flexcomp>` (for soft objects). Therefore, the
only supported composite type is now ``cable``, which produces an inextensible chain of bodies connected with ball
joints.
Composite objects are made up of regular MuJoCo bodies, which we call "element bodies" in this context. The element
bodies are created as children of the body within which :el:`composite` appears; thus a composite object appears in the
same place in the XML where a regular child body may have been defined. Each automatically-generated element body has a
single geom attached to it, usually a sphere but could also be a capsule or an ellipsoid. Thus the composite object is
essentially a particle system, however the particles can be constrained to move together in ways that simulate various
flexible objects. The initial positions of the element bodies form a regular grid in 1D, 2D or 3D. They could all be
children of the parent body (which can be the world or another regular body; composite objects cannot be nested) and
have joints allowing motion relative to the parent, or they could form a kinematic tree with joints between the element
bodies. They can also be connected with tendons with soft equality constraints on the tendon length, creating the
necessary coupling. Joint equality constraints are also used in some cases. The :at:`solref` and :at:`solimp` attributes
of these equality constraints can be adjusted by the user, thereby adjusting the softness and flexibility of the
composite objects.
Composite objects are made up of regular MuJoCo bodies, which we call "element bodies" in this context. The collection
of element bodies is generated by the model compiler automatically. The user configures the automatic generator on a
high level, using the new XML element :ref:`composite <body-composite>` and its attributes and sub-elements, as
described in the XML reference chapter. If the compiled model is then saved, :el:`composite` is no longer present and is
replaced with the collection of regular model elements that were automatically generated. So think of it as a macro that
gets expanded by the model compiler. The element bodies are created as children of the body within which :el:`composite`
appears; thus a composite object appears in the same place in the XML where a regular child body may have been defined.
Each automatically-generated element body has a single geom attached to it. We have designed the composite object
generator to have intuitive high-level controls as much as possible, but at the same time it exposes a large number of
options that interact with each other and can profoundly affect the resulting physics. So at some point users should
read the :ref:`reference documentation <body-composite>` carefully.
In addition to setting up the physics, the composite object generator creates suitable rendering. 2D and 3D objects
can be rendered as :ref:`skins <asset-skin>`. The skin is generated
automatically, and can be textured as well as subdivided using bi-cubic interpolation. The actual physics and in
particular the collision detection are based on the element bodies and their geoms, while the skin is purely a
visualization object. Yet in most situations we prefer to look at the skin representation. To facilitate this, the
generator places all geoms, sites and tendons in group 3 whose visualization is disabled by default. So when you load
a 2D grid for example, you will see a continuous flexible surface and not a collection of spheres connected with
tendons. However when fine-tuning the model and trying to understand the physics behind it, it is useful to be able to
render the spheres and tendons. To switch the rendering style, disable the rendering of skins and enable group 3 for
geoms and tendons.
We have designed the composite object generator to have intuitive high-level controls as much as possible, but at the
same time it exposes a large number of options that interact with each other and can profoundly affect the resulting
physics. So at some point users should read the :ref:`reference documentation <body-composite>` carefully.
As a quick start though, MuJoCo comes with an example of each composite object type. Below we go over these
examples and explain the less obvious aspects. In all examples we have a static scene which is included in the model,
followed by a single composite object. The static scene has a mocap body (large capsule) that can be moved around with
the mouse to probe the behavior of the system. The XML snippets below are just the definition of the composite object;
see the XML model files in the distribution for the complete examples.
**Particle**.
The particle type is deprecated. It is recommended to use the more generic :ref:`replicate<replicate>` instead, for
example `this model <https://github.com/google-deepmind/mujoco/blob/main/model/replicate/particle.xml>`__.
**Grid**.
The grid composite type has been removed. It is recommended to use 2D flex :ref:`deformable objects <CDeformable>` for
simulating thin elastic structures.
In addition to setting up the physics, the composite object generator creates suitable rendering. Objects can be
rendered as :ref:`skins <asset-skin>`. The skin is generated automatically, and can be textured as well as subdivided
using bi-cubic interpolation. The actual physics and in particular the collision detection are based on the element
bodies and their geoms, while the skin is purely a visualization object. Yet in some situations we prefer to look at the
skin representation, as in `this model
<https://github.com/google-deepmind/mujoco/blob/main/model/plugin/elasticity/belt.xml>`__, whose skin is a continuous
flexible surface and not a collection of discontinuous thin boxes. However when fine-tuning the model and trying to
understand the physics behind it, it is useful to be able to render the geoms. To switch the rendering style, disable
the rendering of skins and enable group 3 for geoms and tendons.
**Cable**.
As a quick start, MuJoCo comes with an example of composite cables. In all examples we have a static scene which is
included in the model, followed by a single composite object. The XML snippets below are just the definition of the
composite object; see the XML model files in the distribution for the complete examples.
|coil|
.. code-block:: xml
@@ -1207,6 +1188,16 @@ stiffnesses can be set independently. Moreover, it is possible to specify if the
curve, such as in the case of coil springs. The cable requires using a first-party :ref:`engine plugin<exPlugin>`, which
may be integrated directly into the engine in the future.
**Particle**.
The particle type is deprecated. It is recommended to use the more generic :ref:`replicate<replicate>` instead, for
example `this model <https://github.com/google-deepmind/mujoco/blob/main/model/replicate/particle.xml>`__.
**Grid**.
The grid composite type has been removed. It is recommended to use 2D flex :ref:`deformable objects <CDeformable>` for
simulating thin elastic structures.
**Rope and loop**.
The rope and loop are deprecated. It is recommended to use the cable for simulating inextensible elastic rods that are
@@ -1431,15 +1422,15 @@ mocap bodies around:
|particle|
The key thing to understand about mocap bodies is that the simulator treats them as being fixed. We are causing them
to move from one simulation time step to the next by updating their position and orientation directly, but as far as
the physics model is concerned their position and orientation are constant. So what happens if we make contact with a
regular dynamic body, as in the composite object examples provided with the MuJoCo distribution (recall that in
those example we have a capsule probe which is a mocap body that we move with the mouse). A contact between two
regular bodies will experience penetration as well as relative velocity, while contact with a mocap body is missing
the relative velocity component because the simulator does not know that the mocap body itself is moving. So the
resulting contact force is smaller and it takes longer for the contact to push the dynamic object away. Also, in more
complex simulations the fact that we are doing something inconsistent with the physics can cause instabilities.
The key thing to understand about mocap bodies is that the simulator treats them as being fixed. We are causing them to
move from one simulation time step to the next by updating their position and orientation directly, but as far as the
physics model is concerned their position and orientation are constant. So what happens if we make contact with a
regular dynamic body, as in the particle examples provided with the MuJoCo distribution (recall that in those example we
have a capsule probe which is a mocap body that we move with the mouse). A contact between two regular bodies will
experience penetration as well as relative velocity, while contact with a mocap body is missing the relative velocity
component because the simulator does not know that the mocap body itself is moving. So the resulting contact force is
smaller and it takes longer for the contact to push the dynamic object away. Also, in more complex simulations the fact
that we are doing something inconsistent with the physics can cause instabilities.
There is however a better-behaved alternative. In addition to the mocap body, we include a second regular body and
connect it to the mocap body with a weld equality constraint. In the plots below, the pink box is the mocap body and