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

Reflow all documentation source files to 120 chars.

Browse Source 
PiperOrigin-RevId: 479552166
Change-Id: I777df18cf96d35d5260b4003452b7a6da6707a26
This commit is contained in:
Yuval Tassa
2022-10-07 05:01:37 -07:00
committed by Copybara-Service
parent 6da125ea37
commit eac04ce5e9
8 changed files with 267 additions and 250 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/APIreference.rst
+9 -10
View File
@@ -2736,10 +2736,10 @@ X Macros
^^^^^^^^
The X Macros are not needed in most user projects. They are used internally to allocate the model, and are also
available for users who know how to use this programming technique. See the header file
`mjxmacro.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjxmacro.h>`_ for the actual definitions. They are particularly useful in writing MuJoCo wrappers
for scripting languages, where dynamic structures matching the MuJoCo data structures need to be constructed
programmatically.
available for users who know how to use this programming technique. See the header file `mjxmacro.h
<https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjxmacro.h>`_ for the actual definitions. They are
particularly useful in writing MuJoCo wrappers for scripting languages, where dynamic structures matching the MuJoCo
data structures need to be constructed programmatically.
.. _MJOPTION_SCALARS:
@@ -3238,12 +3238,11 @@ Numeric constants
API functions
-------------
The main header `mujoco.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mujoco.h>`_ exposes a very large number
of functions. However the functions that most users are likely to need are a small fraction. For example,
:ref:`simulate.cc <saSimulate>` which is as elaborate as a MuJoCo application is likely to get, calls around 40
of these functions, while ``basic.cc`` calls around 20. The rest are explosed just in case someone has a use for
them. This includes us as users of MuJoCo -- we do our own work with the public library instead of relying on
internal builds.
The main header `mujoco.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mujoco.h>`_ exposes a very large
number of functions. However the functions that most users are likely to need are a small fraction. For example,
:ref:`simulate.cc <saSimulate>` which is as elaborate as a MuJoCo application is likely to get, calls around 40 of these
functions, while ``basic.cc`` calls around 20. The rest are explosed just in case someone has a use for them. This
includes us as users of MuJoCo -- we do our own work with the public library instead of relying on internal builds.
.. _Activation:
doc/XMLreference.rst
+124 -117
View File
@@ -79,12 +79,13 @@ MJCF Reference
- The order of :ref:`joint <body-joint>` elements within a :ref:`body <body>` matters because joint transformations are
performed in sequence.
- The order of elements in a :ref:`spatial <tendon-spatial>` tendon matters because it determines the sequence of objects that
the tendon passes through or wraps around.
- The order of elements in a :ref:`spatial <tendon-spatial>` tendon matters because it determines the sequence of
objects that the tendon passes through or wraps around.
- The order of repeated sections matters when the same attribute is set multiple times to different values. In that
case the last setting takes effect for the entire model.
- The order of multiple actuator shortcuts in the same defaults class matters, because each shortcut sets the
attributes of the single :ref:`general <actuator-general>` element in that defaults class, overriding the previous settings.
attributes of the single :ref:`general <actuator-general>` element in that defaults class, overriding the previous
settings.
In the remainder of this chapter we describe all valid MJCF elements and their attributes. Some elements can be used in
multiple contexts, in which case their meaning depends on the parent element. This is why we always show the parent as a
@@ -165,10 +166,10 @@ any effect. The settings here are global and apply to the entire model.
compiler converts degrees into radians, and mjModel always uses radians. For URDF models the parser sets this
attribute to "radian" internally, regardless of the XML setting.
:at:`fitaabb`: :at-val:`[false, true], "false"`
The compiler is able to replace a mesh with a geometric primitive fitted to that mesh; see :ref:`geom <body-geom>` below.
If this attribute is "true", the fitting procedure uses the axis-aligned bounding box (aabb) of the mesh. Otherwise
it uses the equivalent-inertia box of the mesh. The type of geometric primitive used for fitting is specified
separately for each geom.
The compiler is able to replace a mesh with a geometric primitive fitted to that mesh; see :ref:`geom <body-geom>`
below. If this attribute is "true", the fitting procedure uses the axis-aligned bounding box (aabb) of the mesh.
Otherwise it uses the equivalent-inertia box of the mesh. The type of geometric primitive used for fitting is
specified separately for each geom.
:at:`eulerseq`: :at-val:`string, "xyz"`
This attribute specifies the sequence of Euler rotations for all euler attributes of elements that have spatial
frames, as explained in :ref:`COrientation`. This must be a string with exactly 3
@@ -365,9 +366,9 @@ adjust it properly through the XML.
:at:`implicit` integrator.
:at:`o_margin`: :at-val:`real, "0"`
This attribute replaces the margin parameter of all active contact pairs when :ref:`Contact override <COverride>` is
enabled. Otherwise MuJoCo uses the element-specific margin attribute of :ref:`geom <body-geom>` or :ref:`pair <contact-pair>`
depending on how the contact pair was generated. See also :ref:`Collision` in the Computation chapter. The related
gap parameter does not have a global override.
enabled. Otherwise MuJoCo uses the element-specific margin attribute of :ref:`geom <body-geom>` or :ref:`pair
<contact-pair>` depending on how the contact pair was generated. See also :ref:`Collision` in the Computation
chapter. The related gap parameter does not have a global override.
:at:`o_solref`, :at:`o_solimp`
These attributes replace the solref and solimp parameters of all active contact pairs when contact override is
enabled. See :ref:`CSolver` for details.
@@ -377,9 +378,9 @@ adjust it properly through the XML.
the Implicit-in-velocity Euler method.
:at:`collision`: :at-val:`[all, predefined, dynamic], "all"`
This attribute specifies which geom pairs should be checked for collision; recall :ref:`Collision` in the Computation
chapter. "predefined" means that only the explicitly-defined contact :ref:`pairs <contact-pair>` are checked. "dynamic" means
that only the contact pairs generated dynamically are checked. "all" means that the contact pairs from both sources
are checked.
chapter. "predefined" means that only the explicitly-defined contact :ref:`pairs <contact-pair>` are checked.
"dynamic" means that only the contact pairs generated dynamically are checked. "all" means that the contact pairs
from both sources are checked.
:at:`cone`: :at-val:`[pyramidal, elliptic], "pyramidal"`
The type of contact friction cone. Elliptic cones are a better model of the physical reality, but pyramidal cones
sometimes make the solver faster and more robust.
@@ -521,9 +522,9 @@ compilation.
The size of the field mjData.userdata of mjData. This field should be used to store custom dynamic variables. See
also :ref:`CUser`.
:at:`nkey`: :at-val:`int, "0"`
The number of key frames allocated in mjModel is the larger of this value and the number of :ref:`key <keyframe-key>` elements
below. Note that the interactive simulator has the ability to take snapshots of the system state and save them as key
frames.
The number of key frames allocated in mjModel is the larger of this value and the number of :ref:`key <keyframe-key>`
elements below. Note that the interactive simulator has the ability to take snapshots of the system state and save
them as key frames.
:at:`nuser_body`: :at-val:`int, "-1"`
The number of custom user parameters added to the definition of each body. See also :ref:`User parameters <CUser>`.
The parameter values are set via the user attribute of the :ref:`body <body>` element. These values are not accessed
@@ -605,15 +606,15 @@ is effectively a miscellaneous subsection.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This element specifies settings that affect the quality of the rendering. Larger values result in higher quality but
possibly slower speed. Note that :ref:`simulate.cc <saSimulate>` displays the frames per second (FPS). The target FPS is 60 Hz; if the
number shown in the visualizer is substantially lower, this means that the GPU is over-loaded and the visualization
should somehow be simplified.
possibly slower speed. Note that :ref:`simulate.cc <saSimulate>` displays the frames per second (FPS). The target FPS is
60 Hz; if the number shown in the visualizer is substantially lower, this means that the GPU is over-loaded and the
visualization should somehow be simplified.
:at:`shadowsize`: :at-val:`int, "4096"`
This attribute specifies the size of the square texture used for shadow mapping. Higher values result is smoother
shadows. The size of the area over which a :ref:`light <body-light>` can cast shadows also affects smoothness, so these
settings should be adjusted jointly. The default here is somewhat conservative. Most modern GPUs are able to handle
significantly larger textures without slowing down.
shadows. The size of the area over which a :ref:`light <body-light>` can cast shadows also affects smoothness, so
these settings should be adjusted jointly. The default here is somewhat conservative. Most modern GPUs are able to
handle significantly larger textures without slowing down.
:at:`offsamples`: :at-val:`int, "4"`
This attribute specifies the number of multi-samples for offscreen rendering. Larger values produce better
anti-aliasing but can slow down the GPU. Set this to 0 to disable multi-sampling. Note that this attribute only
@@ -836,17 +837,18 @@ parameters.
runtime this value scales the solver cost and gradient used for early termination.
:at:`meansize`: :at-val:`real, optional`
If this attribute is specified, it replaces the value of ``mjModel.stat.meansize`` computed by the compiler. At
runtime this value multiplies the attributes of the :ref:`scale <visual-scale>` element above, and acts as their length
unit. If specific lengths are desired, it can be convenient to set :at:`meansize` to a round number like 1 or 0.01 so
that :ref:`scale <visual-scale>` values are in recognized length units. This is the only semantic of :at:`meansize` and
setting it has no other side-effect. The automatically computed value is heuristic, representing the average body
radius. The heuristic is based on geom sizes when present, the distances between joints when present, and the sizes
of the body equivalent inertia boxes.
runtime this value multiplies the attributes of the :ref:`scale <visual-scale>` element above, and acts as their
length unit. If specific lengths are desired, it can be convenient to set :at:`meansize` to a round number like 1 or
0.01 so that :ref:`scale <visual-scale>` values are in recognized length units. This is the only semantic of
:at:`meansize` and setting it has no other side-effect. The automatically computed value is heuristic, representing
the average body radius. The heuristic is based on geom sizes when present, the distances between joints when
present, and the sizes of the body equivalent inertia boxes.
:at:`extent`: :at-val:`real, optional`
If this attribute is specified, it replaces the value of mjModel.stat.extent computed by the compiler. The computed
value is half the side of the bounding box of the model in the initial configuration. At runtime this value is
multiplied by some of the attributes of the :ref:`map <visual-map>` element above. When the model is first loaded, the free
camera's initial distance from the :at:`center` (see below) is 1.5 times the :at:`extent`. Must be strictly positive.
multiplied by some of the attributes of the :ref:`map <visual-map>` element above. When the model is first loaded,
the free camera's initial distance from the :at:`center` (see below) is 1.5 times the :at:`extent`. Must be strictly
positive.
:at:`center`: :at-val:`real(3), optional`
If this attribute is specified, it replaces the value of mjModel.stat.center computed by the compiler. The computed
value is the center of the bounding box of the entire model in the initial configuration. This 3D vector is used to
@@ -962,59 +964,59 @@ if omitted.
:el-prefix:`default/` **motor** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| This and the next three elements set the attributes of the :ref:`general <actuator-general>` element using :ref:`Actuator
shortcuts <CActuator>`. It does not make sense to use more than one such shortcut in the same defaults
class, because they set the same underlying attributes, replacing any previous settings.
| All :ref:`motor <actuator-motor>` attributes are available here except: name, class, joint, jointinparent, site, tendon,
slidersite, cranksite.
This and the next three elements set the attributes of the :ref:`general <actuator-general>` element using
:ref:`Actuator shortcuts <CActuator>`. It does not make sense to use more than one such shortcut in the same defaults
class, because they set the same underlying attributes, replacing any previous settings. All
:ref:`motor <actuator-motor>` attributes are available here except: name, class, joint, jointinparent, site, tendon,
slidersite, cranksite.
.. _default-position:
:el-prefix:`default/` **position** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All :ref:`position <actuator-position>` attributes are available here except: name, class, joint, jointinparent, site, tendon,
slidersite, cranksite.
All :ref:`position <actuator-position>` attributes are available here except: name, class, joint, jointinparent, site,
tendon, slidersite, cranksite.
.. _default-velocity:
:el-prefix:`default/` **velocity** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All :ref:`velocity <actuator-velocity>` attributes are available here except: name, class, joint, jointinparent, site, tendon,
slidersite, cranksite.
All :ref:`velocity <actuator-velocity>` attributes are available here except: name, class, joint, jointinparent, site,
tendon, slidersite, cranksite.
.. _default-intvelocity:
:el-prefix:`default/` **intvelocity** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All :ref:`intvelocity <actuator-intvelocity>` attributes are available here except: name, class, joint, jointinparent, site, tendon,
slidersite, cranksite.
All :ref:`intvelocity <actuator-intvelocity>` attributes are available here except: name, class, joint, jointinparent,
site, tendon, slidersite, cranksite.
.. _default-damper:
:el-prefix:`default/` **damper** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All :ref:`damper <actuator-damper>` attributes are available here except: name, class, joint, jointinparent, site, tendon,
slidersite, cranksite.
All :ref:`damper <actuator-damper>` attributes are available here except: name, class, joint, jointinparent, site,
tendon, slidersite, cranksite.
.. _default-cylinder:
:el-prefix:`default/` **cylinder** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All :ref:`cylinder <actuator-cylinder>` attributes are available here except: name, class, joint, jointinparent, site, tendon,
slidersite, cranksite.
All :ref:`cylinder <actuator-cylinder>` attributes are available here except: name, class, joint, jointinparent, site,
tendon, slidersite, cranksite.
.. _default-muscle:
:el-prefix:`default/` **muscle** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All :ref:`muscle <actuator-muscle>` attributes are available here except: name, class, joint, jointinparent, site, tendon,
slidersite, cranksite.
All :ref:`muscle <actuator-muscle>` attributes are available here except: name, class, joint, jointinparent, site,
tendon, slidersite, cranksite.
:el-prefix:`default/` **adhesion** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -1156,7 +1158,8 @@ chapter.
stretched. For planes this is not an issue because the plane is always normal to the local Z axis. For height fields
the sides enclosing the terrain map appear stretched, but in that case the effect is actually desirable. 2d textures
can be rectangular, unlike the sides of cube textures which must be square. The scaling can be controlled with the
texrepeat attribute of :ref:`material <asset-material>`. The data can be loaded from a singlefile or created procedurally.
texrepeat attribute of :ref:`material <asset-material>`. The data can be loaded from a singlefile or created
procedurally.
:at:`file`: :at-val:`string, optional`
If this attribute is specified, and the builtin attribute below is set to "none", the texture data is loaded from a
single file. See the texturedir attribute of :ref:`compiler <compiler>` regarding the file path.
@@ -1361,7 +1364,8 @@ MSH file format
Poorly designed meshes can display rendering artifacts. In particular, the shadow mapping mechanism relies on having
some distance between front and back-facing triangle faces. If the faces are repeated, with opposite normals as
determined by the vertex order in each triangle, this causes shadow aliasing. The solution is to remove the repeated
faces (which can be done in MeshLab) or use a better designed mesh. Flipped faces are checked by MuJoCo for meshes specified as OBJ or XML and an error message is returned.
faces (which can be done in MeshLab) or use a better designed mesh. Flipped faces are checked by MuJoCo for meshes
specified as OBJ or XML and an error message is returned.
The size of the mesh is determined by the 3D coordinates of the vertex data in the mesh file, multiplied by the
components of the :at:`scale` attribute below. Scaling is applied separately for each coordinate axis. Note that
@@ -1384,14 +1388,14 @@ whose origin is not inside the mesh. In contrast, MuJoCo expects the origin of a
geometric center of the shape. We resolve this discrepancy by pre-processing the mesh in the compiler, so that it is
centered around (0,0,0) and its principal axes of inertia are the coordinate axes. We also save the translation and
rotation offsets needed to achieve such alignment. These offsets are then applied to the referencing geom's position and
orientation; see also :at:`mesh` attribute of :ref:`geom <body-geom>` below. Fortunately most meshes used in robot models are
designed in a coordinate frame centered at the joint. This makes the corresponding MJCF model intuitive: we set the body
frame at the joint, so that the joint position is (0,0,0) in the body frame, and simply reference the mesh. Below is an
MJCF model fragment of a forearm, containing all the information needed to put the mesh where one would expect it to be.
The body position is specified relative to the parent body, namely the upper arm (not shown). It is offset by 35 cm
which is the typical length of the human upper arm. If the mesh vertex data were not designed in the above convention,
we would have to use the geom position and orientation (or the new refpos, refquat mechanism) to compensate, but in
practice this is rarely needed.
orientation; see also :at:`mesh` attribute of :ref:`geom <body-geom>` below. Fortunately most meshes used in robot
models are designed in a coordinate frame centered at the joint. This makes the corresponding MJCF model intuitive: we
set the body frame at the joint, so that the joint position is (0,0,0) in the body frame, and simply reference the mesh.
Below is an MJCF model fragment of a forearm, containing all the information needed to put the mesh where one would
expect it to be. The body position is specified relative to the parent body, namely the upper arm (not shown). It is
offset by 35 cm which is the typical length of the human upper arm. If the mesh vertex data were not designed in the
above convention, we would have to use the geom position and orientation (or the new refpos, refquat mechanism) to
compensate, but in practice this is rarely needed.
.. code-block:: xml
@@ -1404,9 +1408,12 @@ practice this is rarely needed.
<geom type="mesh" mesh="forearm"/>
</body>
The inertial computation mentioned above is part of an algorithm used not only to center and align the mesh, but also
to infer the mass and inertia of the body to which it is attached. This is done by computing the centroid of the
triangle faces, connecting each face with the centroid to form a triangular pyramid, computing the mass and signed inertia of all pyramids (considered solid or hollow if :at:`shellinertia` is true) and accumulating them. The sign ensures that pyramids on the outside of the surfaces are subtracted, as it can occur with concave geometries. This algorithm can be found in section 1.3.8 of Computational Geometry in C (Second Edition) by Joseph O'Rourke.
The inertial computation mentioned above is part of an algorithm used not only to center and align the mesh, but also to
infer the mass and inertia of the body to which it is attached. This is done by computing the centroid of the triangle
faces, connecting each face with the centroid to form a triangular pyramid, computing the mass and signed inertia of all
pyramids (considered solid or hollow if :at:`shellinertia` is true) and accumulating them. The sign ensures that
pyramids on the outside of the surfaces are subtracted, as it can occur with concave geometries. This algorithm can be
found in section 1.3.8 of Computational Geometry in C (Second Edition) by Joseph O'Rourke.
The full list of processing steps applied by the compiler to each mesh is as follows:
@@ -1576,12 +1583,12 @@ This element defines a bone of the skin. The bone is a regular MuJoCo body which
:el-prefix:`asset/` **material** (*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This element creates a material asset. It can be referenced from :ref:`skins <asset-skin>`, :ref:`geoms <body-geom>`, :ref:`sites
<body-site>` and :ref:`tendons <tendon>` to set their appearance. Note that all these elements also have a local rgba
attribute, which is more convenient when only colors need to be adjusted, because it does not require creating materials
and referencing them. Materials are useful for adjusting appearance properties beyond color. However once a material is
created, it is more natural the specify the color using the material, so that all appearance properties are grouped
together.
This element creates a material asset. It can be referenced from :ref:`skins <asset-skin>`, :ref:`geoms <body-geom>`,
:ref:`sites <body-site>` and :ref:`tendons <tendon>` to set their appearance. Note that all these elements also have a
local rgba attribute, which is more convenient when only colors need to be adjusted, because it does not require
creating materials and referencing them. Materials are useful for adjusting appearance properties beyond color. However
once a material is created, it is more natural the specify the color using the material, so that all appearance
properties are grouped together.
:at:`name`: :at-val:`string, required`
Name of the material, used for referencing.
@@ -1637,9 +1644,9 @@ together.
This element is used to construct the :ref:`kinematic tree <CTree>` via nesting. The element :el:`worldbody` is used for
the top-level body, while the element :el:`body` is used for all other bodies. The top-level body is a restricted type
of body: it cannot have child elements :ref:`inertial <body-inertial>` and :ref:`joint <body-joint>`, and also cannot have any
attributes. It corresponds to the origin of the world frame, within which the rest of the kinematic tree is defined. Its
body name is automatically defined as "world".
of body: it cannot have child elements :ref:`inertial <body-inertial>` and :ref:`joint <body-joint>`, and also cannot
have any attributes. It corresponds to the origin of the world frame, within which the rest of the kinematic tree is
defined. Its body name is automatically defined as "world".
:at:`name`: :at-val:`string, optional`
Name of the body.
@@ -1661,9 +1668,9 @@ body name is automatically defined as "world".
<CFrame>`. In local coordinates, if the body position is left undefined it defaults to (0,0,0). In global
coordinates, an undefined body position is inferred by the compiler through the following steps:
#. If the inertial frame is not defined via the :ref:`inertial <body-inertial>` element, it is inferred from the geoms
attached to the body. If there are no geoms, the inertial frame remains undefined. This step is applied in both
local and global coordinates.
#. If the inertial frame is not defined via the :ref:`inertial <body-inertial>` element, it is inferred from the
geoms attached to the body. If there are no geoms, the inertial frame remains undefined. This step is applied in
both local and global coordinates.
#. If both the body frame and the inertial frame are undefined, a compile error is generated.
#. If one of these two frames is defined and the other is not, the defined one is copied into the undefined one. At
this point both frames are defined, in global coordinates.
@@ -1839,10 +1846,10 @@ an XML shortcut for
<joint type="free" stiffness="0" damping="0" frictionloss="0" armature="0"/>
While this joint can evidently be created with the :ref:`joint <body-joint>` element, default joint settings could affect it.
This is usually undesirable as physical free bodies do not have nonzero stiffness, damping, friction or armature. To
avoid this complication, the :el:`freejoint` element was introduced, ensuring joint defaults are *not inherited*. If
the XML model is saved, it will appear as a regular joint of type :at:`free`.
While this joint can evidently be created with the :ref:`joint <body-joint>` element, default joint settings could
affect it. This is usually undesirable as physical free bodies do not have nonzero stiffness, damping, friction or
armature. To avoid this complication, the :el:`freejoint` element was introduced, ensuring joint defaults are *not
inherited*. If the XML model is saved, it will appear as a regular joint of type :at:`free`.
:at:`name`: :at-val:`string, optional`
Name of the joint.
@@ -1874,38 +1881,38 @@ helps clarify the role of bodies and geoms in MuJoCo.
:at:`class`: :at-val:`string, optional`
Defaults class for setting unspecified attributes.
:at:`type`: :at-val:`[plane, hfield, sphere, capsule, ellipsoid, cylinder, box, mesh], "sphere"`
Type of geometric shape. The keywords have the following meaning:
The **plane** type defines a plane which is infinite for collision detection purposes. It can only be attached to the
world body or static children of the world. The plane passes through a point specified via the pos attribute. It is
normal to the Z axis of the geom's local frame. The +Z direction corresponds to empty space. Thus the position and
orientation defaults of (0,0,0) and (1,0,0,0) would create a ground plane at Z=0 elevation, with +Z being the
vertical direction in the world (which is MuJoCo's convention). Since the plane is infinite, it could have been
defined using any other point in the plane. The specified position however has additional meaning with regard to
rendering. If either of the first two size parameters are positive, the plane is rendered as a rectangle of finite
size (in the positive dimensions). This rectangle is centered at the specified position. Three size parameters are
required. The first two specify the half-size of the rectangle along the X and Y axes. The third size parameter is
unusual: it specifies the spacing between the grid subdivisions of the plane for rendering purposes. The subdivisions
are revealed in wireframe rendering mode, but in general they should not be used to paint a grid over the ground
plane (textures should be used for that purpose). Instead their role is to improve lighting and shadows, similar to
the subdivisions used to render boxes. When planes are viewed from the back, the are automatically made
semi-transparent. Planes and the +Z faces of boxes are the only surfaces that can show reflections, if the
:ref:`material <asset-material>` applied to the geom has positive reflection. To render an infinite plane, set the first
two size parameters to zero.
Type of geometric shape. The keywords have the following meaning: The **plane** type defines a plane which is
infinite for collision detection purposes. It can only be attached to the world body or static children of the world.
The plane passes through a point specified via the pos attribute. It is normal to the Z axis of the geom's local
frame. The +Z direction corresponds to empty space. Thus the position and orientation defaults of (0,0,0) and
(1,0,0,0) would create a ground plane at Z=0 elevation, with +Z being the vertical direction in the world (which is
MuJoCo's convention). Since the plane is infinite, it could have been defined using any other point in the plane. The
specified position however has additional meaning with regard to rendering. If either of the first two size
parameters are positive, the plane is rendered as a rectangle of finite size (in the positive dimensions). This
rectangle is centered at the specified position. Three size parameters are required. The first two specify the half-
size of the rectangle along the X and Y axes. The third size parameter is unusual: it specifies the spacing between
the grid subdivisions of the plane for rendering purposes. The subdivisions are revealed in wireframe rendering mode,
but in general they should not be used to paint a grid over the ground plane (textures should be used for that
purpose). Instead their role is to improve lighting and shadows, similar to the subdivisions used to render boxes.
When planes are viewed from the back, the are automatically made semi-transparent. Planes and the +Z faces of boxes
are the only surfaces that can show reflections, if the :ref:`material <asset-material>` applied to the geom has
positive reflection. To render an infinite plane, set the first two size parameters to zero.
The **hfield** type defines a height field geom. The geom must reference the desired height field asset with the
hfield attribute below. The position and orientation of the geom set the position and orientation of the height
field. The size of the geom is ignored, and the size parameters of the height field asset are used instead. See the
description of the :ref:`hfield <asset-hfield>` element. Similar to planes, height field geoms can only be attached to the
world body or to static children of the world.
description of the :ref:`hfield <asset-hfield>` element. Similar to planes, height field geoms can only be attached
to the world body or to static children of the world.
The **sphere** type defines a sphere. This and the next four types correspond to built-in geometric primitives. These
primitives are treated as analytic surfaces for collision detection purposes, in many cases relying on custom
pair-wise collision routines. Models including only planes, spheres, capsules and boxes are the most efficient in
terms of collision detection. Other geom types invoke the general-purpose convex collider. The sphere is centered at
the geom's position. Only one size parameter is used, specifying the radius of the sphere. Rendering of geometric
primitives is done with automatically generated meshes whose density can be adjusted via :ref:`quality <visual-quality>`.
The sphere mesh is triangulated along the lines of latitude and longitude, with the Z axis passing through the north
and south pole. This can be useful in wireframe mode for visualizing frame orientation.
primitives are treated as analytic surfaces for collision detection purposes, in many cases relying on custom pair-
wise collision routines. Models including only planes, spheres, capsules and boxes are the most efficient in terms of
collision detection. Other geom types invoke the general-purpose convex collider. The sphere is centered at the
geom's position. Only one size parameter is used, specifying the radius of the sphere. Rendering of geometric
primitives is done with automatically generated meshes whose density can be adjusted via
:ref:`quality <visual-quality>`. The sphere mesh is triangulated along the lines of latitude and longitude,
with the Z axis passing through the north and south pole. This can be useful in wireframe mode for visualizing frame
orientation.
The **capsule** type defines a capsule, which is a cylinder capped with two half-spheres. It is oriented along the Z
axis of the geom's frame. When the geom frame is specified in the usual way, two size parameters are required: the
@@ -2214,29 +2221,29 @@ the direction specified by the dir attribute. It does not have a full spatial fr
:at:`class`: :at-val:`string, optional`
Defaults class for setting unspecified attributes.
:at:`mode`: :at-val:`[fixed, track, trackcom, targetbody, targetbodycom], "fixed"`
This is identical to the mode attribute of :ref:`camera <body-camera>` above. It specifies the how the light position and
orientation in world coordinates are computed in forward kinematics (which in turn determine what the light
This is identical to the mode attribute of :ref:`camera <body-camera>` above. It specifies the how the light position
and orientation in world coordinates are computed in forward kinematics (which in turn determine what the light
illuminates).
:at:`target`: :at-val:`string, optional`
This is identical to the target attribute of :ref:`camera <body-camera>` above. It specifies which body should be targeted
in "targetbody" and "targetbodycom" modes.
This is identical to the target attribute of :ref:`camera <body-camera>` above. It specifies which body should be
targeted in "targetbody" and "targetbodycom" modes.
:at:`directional`: :at-val:`[false, true], "false"`
The light is directional if this attribute is "true", otherwise it is a spotlight.
:at:`castshadow`: :at-val:`[false, true], "true"`
If this attribute is "true" the light will cast shadows. More precisely, the geoms illuminated by the light will cast
shadows, however this is a property of lights rather than geoms. Since each shadow-casting light causes one extra
rendering pass through all geoms, this attribute should be used with caution. Higher quality of the shadows is
achieved by increasing the value of the shadowsize attribute of :ref:`quality <visual-quality>`, as well as positioning
spotlights closer to the surface on which shadows appear, and limiting the volume in which shadows are cast. For
spotlights this volume is a cone, whose angle is the cutoff attribute below multiplied by the shadowscale attribute
of :ref:`map <visual-map>`. For directional lights this volume is a box, whose half-sizes in the directions orthogonal to
the light are the model extent multiplied by the shadowclip attribute of :ref:`map <visual-map>`. The model extent is
computed by the compiler but can also be overridden by specifying the extent attribute of :ref:`statistic
<statistic>`. Internally the shadow-mapping mechanism renders the scene from the light viewpoint (as if it were a
camera) into a depth texture, and then renders again from the camera viewpoint, using the depth texture to create
shadows. The internal rendering pass uses the same near and far clipping planes as regular rendering, i.e., these
clipping planes bound the cone or box shadow volume in the light direction. As a result, some shadows (especially
those very close to the light) may be clipped.
achieved by increasing the value of the shadowsize attribute of :ref:`quality <visual-quality>`, as well as
positioning spotlights closer to the surface on which shadows appear, and limiting the volume in which shadows are
cast. For spotlights this volume is a cone, whose angle is the cutoff attribute below multiplied by the shadowscale
attribute of :ref:`map <visual-map>`. For directional lights this volume is a box, whose half-sizes in the directions
orthogonal to the light are the model extent multiplied by the shadowclip attribute of :ref:`map <visual-map>`. The
model extent is computed by the compiler but can also be overridden by specifying the extent attribute of
:ref:`statistic <statistic>`. Internally the shadow-mapping mechanism renders the scene from the light viewpoint (as
if it were a camera) into a depth texture, and then renders again from the camera viewpoint, using the depth texture
to create shadows. The internal rendering pass uses the same near and far clipping planes as regular rendering, i.e.,
these clipping planes bound the cone or box shadow volume in the light direction. As a result, some shadows
(especially those very close to the light) may be clipped.
:at:`active`: :at-val:`[false, true], "true"`
The light is active if this attribute is "true". This can be used at runtime to turn lights on and off.
:at:`pos`: :at-val:`real(3), "0 0 0"`
doc/changelog.rst
+26 -21
View File
@@ -98,8 +98,9 @@ General
:height: 150px
#. Cartesian 6D end-effector control is now possible by adding a reference site to actuators with :at:`site`
transmission. See description of new :at:`refsite` attribute in the :ref:`actuator<actuator-general>` documentation and
`refsite.xml <https://github.com/deepmind/mujoco/tree/main/test/engine/testdata/refsite.xml>`_ example model.
transmission. See description of new :at:`refsite` attribute in the :ref:`actuator<actuator-general>` documentation
and `refsite.xml <https://github.com/deepmind/mujoco/tree/main/test/engine/testdata/refsite.xml>`_ example model.
#. Added :at:`autolimits` compiler option. If ``true``, joint and tendon :at:`limited` attributes and actuator
:at:`ctrllimited`, :at:`forcelimited` and :at:`actlimited` attributes will automatically be set to ``true`` if the
corresponding range *is defined* and ``false`` otherwise.
@@ -162,7 +163,8 @@ General
#. Added visualisation groups to skins.
#. Added actuator visualisation for ``free`` and ``ball`` joints and for actuators with ``site`` transmission.
#. Added visualisation for actuator activations.
#. Added ``<actuator-intvelocity>`` actuator shortcut for "integrated velocity" actuators, documented :ref:`here <actuator-intvelocity>`.
#. Added ``<actuator-intvelocity>`` actuator shortcut for "integrated velocity" actuators, documented
:ref:`here <actuator-intvelocity>`.
#. Added ``<actuator-damper>`` actuator shortcut for active-damping actuators, documented :ref:`here <actuator-damper>`.
#. ``mju_rotVecMat`` and ``mju_rotVecMatT`` now support in-place multiplication.
#. ``mjData.ctrl`` values are no longer clamped in-place, remain untouched by the engine.
@@ -231,11 +233,12 @@ General
#. Added ``implicit`` integrator. Using the analytic derivatives above, a new implicit-in-velocity integrator was added.
This integrator lies between the Euler and Runge Kutta integrators in terms of both stability and computational
cost. It is most useful for models which use fluid drag (e.g. for flying or swimming) and for models which use
:ref:`velocity actuators<actuator-velocity>`. For more details, see the :ref:`Numerical Integration<geIntegration>` section.
:ref:`velocity actuators<actuator-velocity>`. For more details, see the :ref:`Numerical Integration<geIntegration>`
section.
#. Added :at:`actlimited` and :at:`actrange` attributes to :ref:`general actuators<actuator-general>`, for clamping actuator
internal states (activations). This clamping is useful for integrated-velocity actuators, see the :ref:`Activation
clamping <CActRange>` section for details.
#. Added :at:`actlimited` and :at:`actrange` attributes to :ref:`general actuators<actuator-general>`, for clamping
actuator internal states (activations). This clamping is useful for integrated-velocity actuators, see the
:ref:`Activation clamping <CActRange>` section for details.
#. ``mjData`` fields ``qfrc_unc`` (unconstrained forces) and ``qacc_unc`` (unconstrained accelerations) were renamed
``qfrc_smooth`` and ``qacc_smooth``, respectively. While "unconstrained" is precise, "smooth" is more intelligible
@@ -245,7 +248,8 @@ General
other open source projects. Developers are encouraged to include MuJoCo public headers in their own codebase via
``#include <mujoco/filename.h>``.
#. The default shadow resolution specified by the :ref:`shadowsize<visual-quality>` attribute was increased from 1024 to 4096.
#. The default shadow resolution specified by the :ref:`shadowsize<visual-quality>` attribute was increased from 1024 to
4096.
#. Saved XMLs now use 2-space indents.
@@ -403,14 +407,15 @@ General
#. Increased the maximum number of lights in an :ref:`mjvScene` from 8 to 100.
#. Saved XML files only contain explicit :ref:`inertial <body-inertial>` elements if the original XML included them. Inertias
that were automatically inferred by the compiler's :ref:`inertiafromgeom <compiler>` mechanism remain unspecified.
#. Saved XML files only contain explicit :ref:`inertial <body-inertial>` elements if the original XML included them.
Inertias that were automatically inferred by the compiler's :ref:`inertiafromgeom <compiler>` mechanism remain
unspecified.
#. User-selected geoms are always rendered as opaque. This is useful in interactive visualizers.
#. Static geoms now respect their :ref:`geom group<body-geom>` for visualisation. Until this change rendering of static geoms
could only be toggled using the :ref:`mjVIS_STATIC<mjtVisFlag>` visualisation flag . After this change, both the geom
group and the visualisation flag need to be enabled for the geom to be rendered.
#. Static geoms now respect their :ref:`geom group<body-geom>` for visualisation. Until this change rendering of static
geoms could only be toggled using the :ref:`mjVIS_STATIC<mjtVisFlag>` visualisation flag . After this change, both
the geom group and the visualisation flag need to be enabled for the geom to be rendered.
#. Pointer parameters in function declarations in :ref:`mujoco.h<inHeader>` that are supposed to represent fixed-length
arrays are now spelled as arrays with extents, e.g. ``mjtNum quat[4]`` rather than ``mjtNum* quat``. From the
@@ -481,9 +486,9 @@ Bug Fixes
:ref:`weld <equality-weld>` constraints.
.. note::
Forces generated by :ref:`spatial tendons <tendon-spatial>` which are outside the kinematic tree (i.e., between bodies
which have no ancestral relationship) are still not taken into account by force and torque sensors. This remains a
future work item.
Forces generated by :ref:`spatial tendons <tendon-spatial>` which are outside the kinematic tree (i.e., between
bodies which have no ancestral relationship) are still not taken into account by force and torque sensors. This
remains a future work item.
Code samples
^^^^^^^^^^^^
@@ -510,11 +515,11 @@ Binary build
15. MacOS packaging. We now ship Universal binaries that natively support both Apple Silicon and Intel CPUs.
a. MuJoCo library is now packaged as a
`Framework Bundle <https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/FrameworkAnatomy.html>`_,
allowing it to be incorporated more easily into Xcode projects (including Swift projects). Developers are
encouraged to compile and link against MuJoCo using the ``-framework mujoco`` flag, however all header files and
the ``libmujoco.2.1.1.dylib`` library can still be directly accessed inside the framework.
a. MuJoCo library is now packaged as a `Framework Bundle
<https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/FrameworkAnato
my.html>`_, allowing it to be incorporated more easily into Xcode projects (including Swift projects). Developers
are encouraged to compile and link against MuJoCo using the ``-framework mujoco`` flag, however all header files
and the ``libmujoco.2.1.1.dylib`` library can still be directly accessed inside the framework.
#. Sample applications are now packaged into an Application Bundle called ``MuJoCo.app``. When launched via GUI,
the bundle launches the ``simulate`` executable. Other precompiled sample programs are shipped inside that bundle
(in ``MuJoCo.app/Contents/MacOS``) and can be launched via command line.
doc/computation.rst
+13 -13
View File
@@ -267,8 +267,8 @@ is attached; the possible attachment object types are :at:`joint`, :at:`tendon`,
:at:`slider-crank`, :at:`site`, and :at:`body`.
The :at:`joint` and :at:`tendon` transmission types act as expected and correspond to the actuator applying forces or
torques to the target object. Ball joints are special, see the :at:`joint` documentation in :ref:`actuator<actuator-general>`
reference for more details.
torques to the target object. Ball joints are special, see the :at:`joint` documentation in
:ref:`actuator<actuator-general>` reference for more details.
The :at:`jointinparent` transmission is unique to ball and free joint and asserts that rotation should be measured
in the parent rather than child frame.
@@ -362,9 +362,9 @@ with MuJoCo's operation as long as such user forces depend only on position and
MuJoCo can compute two types of passive forces: spring-dampers in joints and tendons, and fluid dynamics. When Euler
integration is used, joint damping is integrated implicitly (by modifying the inertia matrix internally) which
significantly increases stability. Thus, even though damping can be alternatively modeled as an actuator property, it is
better to model it as a joint property. Note also the XML :ref:`joint <body-joint>` attribute springdamper which automates
the creation of mass-spring-dampers with desired time constants and damping ratios; in that case the compiler computes
the stiffness and damping coefficients of the joint by taking the joint inertia into account.
better to model it as a joint property. Note also the XML :ref:`joint <body-joint>` attribute springdamper which
automates the creation of mass-spring-dampers with desired time constants and damping ratios; in that case the compiler
computes the stiffness and damping coefficients of the joint by taking the joint inertia into account.
Proper simulation of fluid dynamics is beyond the scope of MuJoCo, and would be too slow for the applications we aim to
facilitate. Nevertheless we provide a phenomenological model which is sufficient for simulating behaviors such as flying
@@ -1395,14 +1395,14 @@ checked in detail. The decision process involves two stages: generation and filt
Generation
First we generate a list of candidate geom pairs in one of two ways: "pair" or "dynamic". The user can also specify
"all" which merges both sources (and is the default). This is done via the setting ``mjModel.opt.collision``. "Pair"
refers to an explicit list of geom pairs defined with the :ref:`pair <contact-pair>` element in MJCF. It gives the user full
control, however it is a static mechanism (independent of the spatial arrangement of the geoms at runtime) and can be
tedious for large models. It is normally used to supplement the output of the "dynamic" mechanism. Dynamic generation
works with bodies rather than geoms; when a body pair is included this means that all geoms attached to one body can
collide with all geoms attached to the other body. The body pairs are generated via broad-phase collision detection
based on a modified sweep-and-prune algorithm. The modification is that the axis for sorting is chosen as the
principal eigenvector of the covariance matrix of all geom centers - which maximizes the spread. If broad-phase
collision detection is disabled by the user, all body pairs are included in this step.
refers to an explicit list of geom pairs defined with the :ref:`pair <contact-pair>` element in MJCF. It gives the
user full control, however it is a static mechanism (independent of the spatial arrangement of the geoms at runtime)
and can be tedious for large models. It is normally used to supplement the output of the "dynamic" mechanism. Dynamic
generation works with bodies rather than geoms; when a body pair is included this means that all geoms attached to
one body can collide with all geoms attached to the other body. The body pairs are generated via broad-phase
collision detection based on a modified sweep-and-prune algorithm. The modification is that the axis for sorting is
chosen as the principal eigenvector of the covariance matrix of all geom centers - which maximizes the spread. If
broad-phase collision detection is disabled by the user, all body pairs are included in this step.
Finally, the user can explicitly exclude certain body pairs using the :ref:`exclude <contact-exclude>` element
in MJCF. Exclusion is applied when "dynamic" or "all" are selected, but not when "pair" is selected. At the end of
doc/modeling.rst
+38 -36
View File
@@ -103,16 +103,17 @@ special and is called :el:`worldbody`. This tree organization is in contrast wit
links and then connects them with joints that specify a child and a parent link. In MJCF the child body is literally a
child of the parent body, in the sense of XML.
When a :ref:`joint <body-joint>` is defined inside a body, its function is not to connect the parent and child but rather to
create motion degrees of freedom between them. If no joints are defined within a given body, that body is welded to its
parent. A body in MJCF can contain multiple joints, thus there is no need to introduce dummy bodies for creating
composite joints. Instead simply define all the primitive joints that form the desired composite joint within the same
body. For example, two sliders and one hinge can be used to model a body moving in a plane.
When a :ref:`joint <body-joint>` is defined inside a body, its function is not to connect the parent and child but
rather to create motion degrees of freedom between them. If no joints are defined within a given body, that body is
welded to its parent. A body in MJCF can contain multiple joints, thus there is no need to introduce dummy bodies for
creating composite joints. Instead simply define all the primitive joints that form the desired composite joint within
the same body. For example, two sliders and one hinge can be used to model a body moving in a plane.
Other MJCF elements can be defined within the tree created by nested body elements, in particular :ref:`joint <body-joint>`,
:ref:`geom <body-geom>`, :ref:`site <body-site>`, :ref:`camera <body-camera>`, :ref:`light <body-light>`. When an element is defined within
a body, it is fixed to the local frame of that body and always moves with it. Elements that refer to multiple bodies, or
do not refer to bodies at all, are defined in separate sections outside the kinematic tree.
Other MJCF elements can be defined within the tree created by nested body elements, in particular
:ref:`joint <body-joint>`, :ref:`geom <body-geom>`, :ref:`site <body-site>`, :ref:`camera <body-camera>`, :ref:`light
<body-light>`. When an element is defined within a body, it is fixed to the local frame of that body and always moves
with it. Elements that refer to multiple bodies, or do not refer to bodies at all, are defined in separate sections
outside the kinematic tree.
.. _CDefault:
@@ -302,8 +303,8 @@ approximately
.. math::
a_1 + d \cdot (b v + k r) = (1 - d)\cdot a_0
Again, the parameters that are under the user's control are :math:`d, b, k`. The remaining quantities are functions of the
system state and are computed automatically at each time step.
Again, the parameters that are under the user's control are :math:`d, b, k`. The remaining quantities are functions of
the system state and are computed automatically at each time step.
First we explain the setting of the impedance :math:`d`. Recall that :math:`d` must lie between 0 and 1; internally
MuJoCo clamps it to the range [:ref:`mjMINIMP mjMAXIMP <glNumeric>`] which is currently set to [0.0001 0.9999]. It
@@ -459,12 +460,12 @@ User parameters
A number of MJCF elements have the optional attribute :at:`user`, which defines a custom element-specific parameter
array. This interacts with the corresponding "nuser_XXX" attribute of the :ref:`size <size>` element. If for example we
set :at:`nuser_geom` to 5, then every geom in mjModel will have a custom array of 5 real-valued parameters. These geom-
specific parameters are either defined in the MJCF file via the :at:`user` attribute of :ref:`geom <body-geom>`, or set to 0
by the compiler if this attribute is omitted. The default value of all "nuser_XXX" attributes is -1, which instructs the
compiler to automatically set this value to the length of the maximum associated :at:`user` attribute defined in the
model. MuJoCo does not use these parameters in any internal computations; instead they are available for custom
computations. The parser allows arrays of arbitrary length in the XML, and the compiler later resizes them to length
nuser_XXX.
specific parameters are either defined in the MJCF file via the :at:`user` attribute of :ref:`geom <body-geom>`, or set
to 0 by the compiler if this attribute is omitted. The default value of all "nuser_XXX" attributes is -1, which
instructs the compiler to automatically set this value to the length of the maximum associated :at:`user` attribute
defined in the model. MuJoCo does not use these parameters in any internal computations; instead they are available for
custom computations. The parser allows arrays of arbitrary length in the XML, and the compiler later resizes them to
length nuser_XXX.
Some element-specific parameters that are normally used in internal computations can also be used in custom
computations. This is done by installing user callbacks which override parts of the simulation pipeline. For example,
@@ -493,9 +494,9 @@ There is also a second Noslip solver, which is a post-processing step enabled by
noslip iterations. All these algorithm settings can be specified in the :ref:`option <option>` element.
The default settings work well for most models, but in some cases it is necessary to tune the algorithm. The best way to
do this is to experiment with the relevant settings and use the visual profiler in :ref:`simulate.cc <saSimulate>`, which
shows the timing of different computations as well as solver statistics per iteration. We can offer the following general
guidelines and observations:
do this is to experiment with the relevant settings and use the visual profiler in :ref:`simulate.cc <saSimulate>`,
which shows the timing of different computations as well as solver statistics per iteration. We can offer the following
general guidelines and observations:
- The constraint Jacobian should be dense for small models and sparse for large models. The default setting is 'auto';
it resolves to dense when the number of degrees of freedom is up to 60, and sparse over 60. Note however that the
@@ -547,17 +548,18 @@ Actuator shortcuts
As explained in the :ref:`Actuation model <geActuation>` section of the Computation chapter, MuJoCo offers a flexible
actuator model with transmission, activation dynamics and force generation components that can be specified
independently. The full functionality can be accessed via the XML element :ref:`general <actuator-general>` which allows the user
to create a variety of custom actuators. In addition, MJCF provides shortcuts for configuring common actuators. This is
done via the XML elements :ref:`motor <actuator-motor>`, :ref:`position <actuator-position>`, :ref:`velocity <actuator-velocity>`,
:ref:`intvelocity <actuator-intvelocity>`, :ref:`damper<actuator-damper>`, :ref:`cylinder<actuator-cylinder>`, :ref:`muscle <actuator-muscle>`, and
:ref:`adhesion <actuator-adhesion>`. These are *not* separate model elements. Internally MuJoCo supports only one actuator type -
which is why when an MJCF model is saved all actuators are written as :el:`general`. Shortcuts create general actuators
implicitly, set their attributes to suitable values, and expose a subset of attributes with possibly different names.
For example, :el:`position` creates a position servo with attribute :at:`kp` which is the servo gain. However
:el:`general` does not have an attribute :at:`kp`. Instead the parser adjusts the gain and bias parameters of the
general actuator in a coordinated way so as to mimic a position servo. The same effect could have been achieved by using
:el:`general` directly, and setting its attributes to certain values as described below.
independently. The full functionality can be accessed via the XML element :ref:`general <actuator-general>` which allows
the user to create a variety of custom actuators. In addition, MJCF provides shortcuts for configuring common actuators.
This is done via the XML elements :ref:`motor <actuator-motor>`, :ref:`position <actuator-position>`, :ref:`velocity
<actuator-velocity>`, :ref:`intvelocity <actuator-intvelocity>`, :ref:`damper<actuator-damper>`,
:ref:`cylinder<actuator-cylinder>`, :ref:`muscle <actuator-muscle>`, and :ref:`adhesion <actuator-adhesion>`. These are
*not* separate model elements. Internally MuJoCo supports only one actuator type -which is why when an MJCF model is
saved all actuators are written as :el:`general`. Shortcuts create general actuators implicitly, set their attributes to
suitable values, and expose a subset of attributes with possibly different names. For example, :el:`position` creates a
position servo with attribute :at:`kp` which is the servo gain. However :el:`general` does not have an attribute
:at:`kp`. Instead the parser adjusts the gain and bias parameters of the general actuator in a coordinated way so as to
mimic a position servo. The same effect could have been achieved by using :el:`general` directly, and setting its
attributes to certain values as described below.
Actuator shortcuts also interact with defaults. Recall that the :ref:`default setting <CDefault>` mechanism involves
classes, each of which has a complete collection of dummy elements (one of each element type) used to initialize the
@@ -757,9 +759,9 @@ muscle-specific constant :math:`F_0` to obtain the actual force:
The negative sign is because positive muscle activation generates pulling force. The constant :math:`F_0` is the peak
active force at zero velocity. It is related to the muscle thickness (i.e., physiological cross-sectional area or PCSA).
If known, it can be set with the attribute force of element :ref:`muscle <actuator-muscle>`. If it is not known, we set it to
:math:`-1` which is the default. In that case we rely on the fact that larger muscles tend to act on joints that move
more weight. The attribute scale defines this relationship as:
If known, it can be set with the attribute force of element :ref:`muscle <actuator-muscle>`. If it is not known, we set
it to :math:`-1` which is the default. In that case we rely on the fact that larger muscles tend to act on joints that
move more weight. The attribute scale defines this relationship as:
.. math::
F_0 = \text{scale} / \texttt{actuator\_acc0}
@@ -1248,8 +1250,8 @@ this?
The first step is to define a mocap body in the MJCF model, and implement code that reads the data stream at runtime and
sets mjModel.mocap_pos and mjModel.mocap_quat to the position and orientation received from the motion capture system.
The :ref:`simulate.cc <saSimulate>` code sample uses the mouse as a motion capture device, allowing the user to move mocap
bodies around:
The :ref:`simulate.cc <saSimulate>` code sample uses the mouse as a motion capture device, allowing the user to move
mocap bodies around:
|particle|
doc/overview.rst
+15 -14
View File
@@ -375,11 +375,11 @@ Height field
format described later. A height field is a rectangular grid of elevation data. The compiler normalizes the data to
the range [0-1]. The actual spatial extent of the height field is then determined by the size parameters of the
referencing geom. Height fields can only be referenced from geoms that are attached to the world body. For rendering
and collision detection purposes, the grid rectangles are automatically triangulated, thus the height field is treated
as a union of triangular prisms. Collision detection with such a composite object can in principle generate a large
number of contact points for a single geom pair. If that happens, only the first 64 contact points are kept. The
rationale is that height fields should be used to model terrain maps whose spatial features are large compared to the
other objects in the simulation, so the number of contacts will be small for well-designed models.
and collision detection purposes, the grid rectangles are automatically triangulated, thus the height field is
treated as a union of triangular prisms. Collision detection with such a composite object can in principle generate a
large number of contact points for a single geom pair. If that happens, only the first 64 contact points are kept.
The rationale is that height fields should be used to model terrain maps whose spatial features are large compared to
the other objects in the simulation, so the number of contacts will be small for well-designed models.
Texture
Textures can be loaded from PNG files or synthesized by the compiler based on user-defined procedural parameters.
@@ -483,8 +483,8 @@ Reference pose
of the joints when the model is in its initial configuration. In our earlier example the elbow was created in a bent
configuration at 90° angle. But MuJoCo does not know what an elbow is, and so by default it treats this joint
configuration as having numeric value of 0. We can override the default behavior and specify that the initial
configuration corresponds to 90°, using the ref attribute of :ref:`joint <body-joint>`. The reference values of all joints
are assembled into the vector ``mjModel.qpos0``. Whenever the simulation is reset, the joint configuration
configuration corresponds to 90°, using the ref attribute of :ref:`joint <body-joint>`. The reference values of all
joints are assembled into the vector ``mjModel.qpos0``. Whenever the simulation is reset, the joint configuration
``mjData.qpos`` is set to ``mjModel.qpos0``. At runtime the joint position vector is interpreted relative to the
reference pose. In particular, the amount of spatial transformation applied by the joints is ``mjData.qpos -
mjModel.qpos0``. This transformation is in addition to the parent-child translation and rotation offsets stored in
@@ -625,8 +625,8 @@ That said, users are encouraged to use MKS, as there are two places where MuJoCo
- The default value of :ref:`gravity<option>` is (0, 0, -9.81), which corresponds to Earth surface gravity in MKS.
Note that this does not really define system of units to be MKS, since we might be using CGS on
`Enceladus <https://en.wikipedia.org/wiki/Enceladus>`__.
- The default value of :ref:`geom density<body-geom>` (used to infer body masses and inertias) is 1000, which corresponds to
the density of water in MKS.
- The default value of :ref:`geom density<body-geom>` (used to infer body masses and inertias) is 1000, which
corresponds to the density of water in MKS.
Once a consistent system of basic units (length, mass, time) is chosen, all derived units correspond to this system, as
in `Dimensional Analysis <https://en.wikipedia.org/wiki/Dimensional_analysis>`__. For example if our model is
@@ -660,7 +660,8 @@ easy ways to avoid this problem:
:ref:`fluid viscosity<option>` in order to prevent your model from moving around too much.
2. Use :ref:`collision filtering<Collision>` to explicitly disable the unwanted collisions, either by setting the
relevant :at:`contype` and :at:`conaffinity` attributes, or by using a contact :ref:`exclude <contact-exclude>` directive.
relevant :at:`contype` and :at:`conaffinity` attributes, or by using a contact :ref:`exclude <contact-exclude>`
directive.
.. _NotObject:
@@ -729,10 +730,10 @@ The size of each array (``njnt`` in this case) is also given in ``mjModel``. The
first, followed by the limits of the second joint etc. This ordering reflects the fact that all matrices in MuJoCo have
row-major format.
The available element types are defined in
`mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h#L243>`_, in the enum type :ref:`mjtObj`.
These enums are mostly used internally. One exception are the functions :ref:`mj_name2id` and :ref:`mj_id2name` in the
MuJoCo API, which map element names to integer ids and vice versa. These functions take an element type as input.
The available element types are defined in `mjmodel.h
<https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h#L243>`_, in the enum type :ref:`mjtObj`. These
enums are mostly used internally. One exception are the functions :ref:`mj_name2id` and :ref:`mj_id2name` in the MuJoCo
API, which map element names to integer ids and vice versa. These functions take an element type as input.
Naming model elements in the XML is optional. Two elements of the same type (e.g. two joints) cannot have the same name.
Naming is required only when a given element needs to be referenced elsewhere in the model; referencing in the XML can
doc/programming.rst
+38 -36
View File
@@ -41,13 +41,13 @@ Getting started
~~~~~~~~~~~~~~~
MuJoCo is an open-source project. Pre-built dynamic libraries are available for x86_64 and arm64 machines running
Windows, Linux, and macOS. These can be downloaded from the `GitHub Releases page <https://github.com/deepmind/mujoco/releases>`_.
Users who do not intend to develop or modify core MuJoCo code are encouraged to use our pre-built libraries, as these
come bundled with the same versions of dependencies that we regularly test against, and benefit from build flags
that have been tuned for performance. Our pre-built libraries are almost entirely self-contained and do not require
any other library to be present, outside the standard C runtime. We also hide all symbols apart from
those that form MuJoCo's public API, thus ensuring that it can coexist with any other libraries that may be loaded into
the process (including other versions of libraries that MuJoCo depends on).
Windows, Linux, and macOS. These can be downloaded from the `GitHub Releases page
<https://github.com/deepmind/mujoco/releases>`_. Users who do not intend to develop or modify core MuJoCo code are
encouraged to use our pre-built libraries, as these come bundled with the same versions of dependencies that we
regularly test against, and benefit from build flags that have been tuned for performance. Our pre-built libraries are
almost entirely self-contained and do not require any other library to be present, outside the standard C runtime. We
also hide all symbols apart from those that form MuJoCo's public API, thus ensuring that it can coexist with any other
libraries that may be loaded into the process (including other versions of libraries that MuJoCo depends on).
The pre-built distribution is a single .zip on Windows, .dmg on macOS, and .tar.gz on Linux. There is no installer.
On Windows and Linux, simply extract the archive in a directory of your choice. From the ``bin`` subdirectory, you can
@@ -71,20 +71,22 @@ directory; it contains error and warning messages, and can be deleted at any tim
sample - code samples and makefile need to build them
After verifying that the simulator works, you may also want to re-compile the code samples to ensure that you have a
working development environment. We provide Makefiles for `Windows <https://github.com/deepmind/mujoco/blob/main/sample/Makefile.windows>`_,
`macOS <https://github.com/deepmind/mujoco/blob/main/sample/Makefile.macos>`_, and
`Linux <https://github.com/deepmind/mujoco/blob/main/sample/Makefile>`_, and also a cross-platform
`CMake <https://github.com/deepmind/mujoco/blob/main/sample/CMakeLists.txt>`_ setup that can be used to build sample
working development environment. We provide Makefiles for `Windows
<https://github.com/deepmind/mujoco/blob/main/sample/Makefile.windows>`_, `macOS
<https://github.com/deepmind/mujoco/blob/main/sample/Makefile.macos>`_, and `Linux
<https://github.com/deepmind/mujoco/blob/main/sample/Makefile>`_, and also a cross-platform `CMake
<https://github.com/deepmind/mujoco/blob/main/sample/CMakeLists.txt>`_ setup that can be used to build sample
applications independently of the MuJoCo library itself. If you are using the vanilla Makefile, we assume that you are
using Visual Studio on Windows and LLVM/Clang on Linux. On Windows, you also need to either open a Visual Studio command
prompt with native x64 tools or call the ``vcvarsall.bat`` script that comes with your MSVC installation to set up the
appropriate environment variables.
On macOS, the DMG disk image contains ``MuJoCo.app``, which you can double-click to launch the ``simulate`` GUI.
You can also drag ``MuJoCo.app`` into the ``/Application`` on your system, as you would to install any other app.
While ``MuJoCo.app`` may look like a file, it is in fact an `Application Bundle <https://developer.apple.com/go/?id=bundle-structure>`_,
which is a directory that contains executable binaries for all of MuJoCo's sample applications, along with an embedded
`framework <https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html>`_,
On macOS, the DMG disk image contains ``MuJoCo.app``, which you can double-click to launch the ``simulate`` GUI. You can
also drag ``MuJoCo.app`` into the ``/Application`` on your system, as you would to install any other app. While
``MuJoCo.app`` may look like a file, it is in fact an `Application Bundle <https://developer.apple.com/go/?id=bundle-
structure>`_, which is a directory that contains executable binaries for all of MuJoCo's sample applications, along with
an embedded `framework
<https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html>`_,
which is a subdirectory containing the MuJoCo dynamic library and all of its public headers. In other words,
``MuJoCo.app`` contains all the same files that are shipped in the archive on Windows and Linux. To see this, right
click (or control-click) on ``MuJoCo.app`` and click "Show Package Contents".
@@ -342,10 +344,10 @@ illustration of how the new UI framework is intended to be used. Below is a scre
.. youtube:: 0ORsj_E17B0
:align: center
Interaction is done with the mouse; built-in help with a summary of available commands is available by pressing the ``F1``
key. Briefly, an object is selected by left-double-click. The user can then apply forces and torques on the selected
object by holding Ctrl and dragging the mouse. Dragging the mouse alone (without Ctrl) moves the camera. There are
keyboard shortcuts for pausing the simulation, resetting, and re-loading the model file. The latter functionality is
Interaction is done with the mouse; built-in help with a summary of available commands is available by pressing the
``F1`` key. Briefly, an object is selected by left-double-click. The user can then apply forces and torques on the
selected object by holding Ctrl and dragging the mouse. Dragging the mouse alone (without Ctrl) moves the camera. There
are keyboard shortcuts for pausing the simulation, resetting, and re-loading the model file. The latter functionality is
very useful while editing the model in an XML editor.
The code is quite long yet reasonably commented, so it is best to just read it. Here we provide a high-level overview.
@@ -377,9 +379,9 @@ This code sample simulates the passive dynamics of a given model, renders it off
values, and saves them into a raw data file that can then be converted into a movie file with tools such as ffmpeg. The
rendering is simplified compared to :ref:`simulate.cc <saSimulate>` because there is no user interaction, visualization
options or timing; instead we simply render with the default settings as fast as possible. The dimensions and number of
multi-samples for the offscreen buffer are specified in the MuJoCo model, while the simulation duration, frames-per-second
to be rendered (usually much less than the physics simulation rate), and output file name are specified as command-line
arguments. For example, a 5 second animation at 60 frames per second is created with:
multi-samples for the offscreen buffer are specified in the MuJoCo model, while the simulation duration, frames-per-
second to be rendered (usually much less than the physics simulation rate), and output file name are specified as
command-line arguments. For example, a 5 second animation at 60 frames per second is created with:
.. code-block:: Shell
@@ -628,11 +630,11 @@ control callback) would become
mj_step(m, d);
}
Why would we not be able to compute the controls before ``mj_step`` is called? After all, isn't this what causality means?
The answer is subtle but important, and has to do with the fact that we are simulating in discrete time. The top-level
simulation function ``mj_step`` basically does two things: compute the :ref:`forward dynamics <siForward>` in continuous
time, and then integrate over a time period specified by ``mjModel.opt.timestep``. Forward dynamics computes the
acceleration ``mjData.qacc`` at time ``mjData.time``, given the :ref:`state and control <siStateControl>` at time
Why would we not be able to compute the controls before ``mj_step`` is called? After all, isn't this what causality
means? The answer is subtle but important, and has to do with the fact that we are simulating in discrete time. The top-
level simulation function ``mj_step`` basically does two things: compute the :ref:`forward dynamics <siForward>` in
continuous time, and then integrate over a time period specified by ``mjModel.opt.timestep``. Forward dynamics computes
the acceleration ``mjData.qacc`` at time ``mjData.time``, given the :ref:`state and control <siStateControl>` at time
``mjData.time``. The numerical integrator then advances the state and time to ``mjData.time + mjModel.opt.timestep``.
Now, the control is required to be a function of the state at time ``mjData.time``. However a general feedback
controller can be a very complex function, depending on various features of the state - in particular all the features
@@ -1025,9 +1027,9 @@ writes to its own mjData. Therefore no further synchronization among threads is
The above template reflects a particular style of parallel processing. Instead of creating a large number of threads,
one for each work item, and letting OpenMP distribute them among processors, we rely on manual scheduling. More
precisely, we create as many threads as there are processors, and then within the ``worker`` function we distribute
the work explicitly among threads (not shown here, but see :ref:`derivative.cc <saDerivative>` for an example). This approach is more
efficient because the thread-specific mjData is large compared to the processor cache.
precisely, we create as many threads as there are processors, and then within the ``worker`` function we distribute the
work explicitly among threads (not shown here, but see :ref:`derivative.cc <saDerivative>` for an example). This
approach is more efficient because the thread-specific mjData is large compared to the processor cache.
We also use a shared mjModel for cache-efficiency. In some situations it may not be possible to use the same mjModel
for all threads. One obvious reason is that mjModel may need to be modified within the thread function. Another reason
@@ -1065,8 +1067,8 @@ Arrays of type mjtByte can be changed safely, since they are binary indicators t
features. The only exception here is ``mjModel.tex_rgb`` which is texture data represented as mjtByte.
When changing mjModel fields that corresponds to resources uploaded to the GPU, the user must also call the
corresponding upload function: ``mjr_uploadTexture``, ``mjr_uploadMesh``, ``mjr_uploadHField``. Otherwise the data used for
simulation and for rendering will no longer be consistent.
corresponding upload function: ``mjr_uploadTexture``, ``mjr_uploadMesh``, ``mjr_uploadHField``. Otherwise the data used
for simulation and for rendering will no longer be consistent.
A related consideration has to do with changing real-valued fields of mjModel that have been used by the compiler to
compute other real-valued fields: if we make a change, we want it to propagate. That is what the function
@@ -1659,9 +1661,9 @@ use the hand-held controller as a "laser pointer" that can select objects.
Perturbations
'''''''''''''
Interactive perturbations have proven very useful in exploring the model dynamics as well as probing closed-loop
control systems. The user is free to implement any perturbation mechanism of their choice by setting
``mjData.qfrc_applied`` or ``mjData.xfrc_applied`` to suitable forces (in generalized and Cartesian coordinates respectively).
Interactive perturbations have proven very useful in exploring the model dynamics as well as probing closed-loop control
systems. The user is free to implement any perturbation mechanism of their choice by setting ``mjData.qfrc_applied`` or
``mjData.xfrc_applied`` to suitable forces (in generalized and Cartesian coordinates respectively).
Prior to MuJoCo version 1.40, user code had to maintain a collection of objects in order to implement perturbations.
All these objects are now grouped into the data structure :ref:`mjvPerturb`. Its use is illustrated in
doc/unity.rst
+4 -3
View File
@@ -5,9 +5,10 @@ Unity Plug-in
Introduction
------------
The MuJoCo `Unity plug-in <https://github.com/deepmind/mujoco/tree/main/unity>`_ allows the Unity Editor and runtime to use the MuJoCo physics engine. Users can import MJCF
files and edit the models in the Editor. The plug-in relies on Unity for most aspects -- assets, game logic, simulation
time -- but uses MuJoCo to determine how objects move, giving the designer access to MuJoCo's full API.
The MuJoCo `Unity plug-in <https://github.com/deepmind/mujoco/tree/main/unity>`_ allows the Unity Editor and runtime to
use the MuJoCo physics engine. Users can import MJCF files and edit the models in the Editor. The plug-in relies on
Unity for most aspects -- assets, game logic, simulation time -- but uses MuJoCo to determine how objects move, giving
the designer access to MuJoCo's full API.
.. _UInstallation: