chenlin/Mujoco_WASM
1
0
Fork 0
Code Issues Pull Requests Actions 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 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 available for users who know how to use this programming technique. See the header file `mjxmacro.h
`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 <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjxmacro.h>`_ for the actual definitions. They are
for scripting languages, where dynamic structures matching the MuJoCo data structures need to be constructed particularly useful in writing MuJoCo wrappers for scripting languages, where dynamic structures matching the MuJoCo
programmatically. data structures need to be constructed programmatically.
.. _MJOPTION_SCALARS: .. _MJOPTION_SCALARS:
@@ -3238,12 +3238,11 @@ Numeric constants
API functions API functions
------------- -------------
The main header `mujoco.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mujoco.h>`_ exposes a very large number The main header `mujoco.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mujoco.h>`_ exposes a very large
of functions. However the functions that most users are likely to need are a small fraction. For example, 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 :ref:`simulate.cc <saSimulate>` which is as elaborate as a MuJoCo application is likely to get, calls around 40 of these
of these functions, while ``basic.cc`` calls around 20. The rest are explosed just in case someone has a use for functions, while ``basic.cc`` calls around 20. The rest are explosed just in case someone has a use for them. This
them. This includes us as users of MuJoCo -- we do our own work with the public library instead of relying on includes us as users of MuJoCo -- we do our own work with the public library instead of relying on internal builds.
internal builds.
.. _Activation: .. _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 - The order of :ref:`joint <body-joint>` elements within a :ref:`body <body>` matters because joint transformations are
performed in sequence. performed in sequence.
- The order of elements in a :ref:`spatial <tendon-spatial>` tendon matters because it determines the sequence of objects that - The order of elements in a :ref:`spatial <tendon-spatial>` tendon matters because it determines the sequence of
the tendon passes through or wraps around. 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 - 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. 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 - 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 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 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 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. attribute to "radian" internally, regardless of the XML setting.
:at:`fitaabb`: :at-val:`[false, true], "false"` :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. The compiler is able to replace a mesh with a geometric primitive fitted to that mesh; see :ref:`geom <body-geom>`
If this attribute is "true", the fitting procedure uses the axis-aligned bounding box (aabb) of the mesh. Otherwise below. If this attribute is "true", the fitting procedure uses the axis-aligned bounding box (aabb) of the mesh.
it uses the equivalent-inertia box of the mesh. The type of geometric primitive used for fitting is specified Otherwise it uses the equivalent-inertia box of the mesh. The type of geometric primitive used for fitting is
separately for each geom. specified separately for each geom.
:at:`eulerseq`: :at-val:`string, "xyz"` :at:`eulerseq`: :at-val:`string, "xyz"`
This attribute specifies the sequence of Euler rotations for all euler attributes of elements that have spatial 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 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:`implicit` integrator.
:at:`o_margin`: :at-val:`real, "0"` :at:`o_margin`: :at-val:`real, "0"`
This attribute replaces the margin parameter of all active contact pairs when :ref:`Contact override <COverride>` is 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>` enabled. Otherwise MuJoCo uses the element-specific margin attribute of :ref:`geom <body-geom>` or :ref:`pair
depending on how the contact pair was generated. See also :ref:`Collision` in the Computation chapter. The related <contact-pair>` depending on how the contact pair was generated. See also :ref:`Collision` in the Computation
gap parameter does not have a global override. chapter. The related gap parameter does not have a global override.
:at:`o_solref`, :at:`o_solimp` :at:`o_solref`, :at:`o_solimp`
These attributes replace the solref and solimp parameters of all active contact pairs when contact override is These attributes replace the solref and solimp parameters of all active contact pairs when contact override is
enabled. See :ref:`CSolver` for details. enabled. See :ref:`CSolver` for details.
@@ -377,9 +378,9 @@ adjust it properly through the XML.
the Implicit-in-velocity Euler method. the Implicit-in-velocity Euler method.
:at:`collision`: :at-val:`[all, predefined, dynamic], "all"` :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 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 chapter. "predefined" means that only the explicitly-defined contact :ref:`pairs <contact-pair>` are checked.
that only the contact pairs generated dynamically are checked. "all" means that the contact pairs from both sources "dynamic" means that only the contact pairs generated dynamically are checked. "all" means that the contact pairs
are checked. from both sources are checked.
:at:`cone`: :at-val:`[pyramidal, elliptic], "pyramidal"` :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 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. 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 The size of the field mjData.userdata of mjData. This field should be used to store custom dynamic variables. See
also :ref:`CUser`. also :ref:`CUser`.
:at:`nkey`: :at-val:`int, "0"` :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 The number of key frames allocated in mjModel is the larger of this value and the number of :ref:`key <keyframe-key>`
below. Note that the interactive simulator has the ability to take snapshots of the system state and save them as key elements below. Note that the interactive simulator has the ability to take snapshots of the system state and save
frames. them as key frames.
:at:`nuser_body`: :at-val:`int, "-1"` :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 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 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 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 possibly slower speed. Note that :ref:`simulate.cc <saSimulate>` displays the frames per second (FPS). The target FPS is
number shown in the visualizer is substantially lower, this means that the GPU is over-loaded and the visualization 60 Hz; if the number shown in the visualizer is substantially lower, this means that the GPU is over-loaded and the
should somehow be simplified. visualization should somehow be simplified.
:at:`shadowsize`: :at-val:`int, "4096"` :at:`shadowsize`: :at-val:`int, "4096"`
This attribute specifies the size of the square texture used for shadow mapping. Higher values result is smoother 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 shadows. The size of the area over which a :ref:`light <body-light>` can cast shadows also affects smoothness, so
settings should be adjusted jointly. The default here is somewhat conservative. Most modern GPUs are able to handle these settings should be adjusted jointly. The default here is somewhat conservative. Most modern GPUs are able to
significantly larger textures without slowing down. handle significantly larger textures without slowing down.
:at:`offsamples`: :at-val:`int, "4"` :at:`offsamples`: :at-val:`int, "4"`
This attribute specifies the number of multi-samples for offscreen rendering. Larger values produce better 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 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. runtime this value scales the solver cost and gradient used for early termination.
:at:`meansize`: :at-val:`real, optional` :at:`meansize`: :at-val:`real, optional`
If this attribute is specified, it replaces the value of ``mjModel.stat.meansize`` computed by the compiler. At 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 runtime this value multiplies the attributes of the :ref:`scale <visual-scale>` element above, and acts as their
unit. If specific lengths are desired, it can be convenient to set :at:`meansize` to a round number like 1 or 0.01 so length unit. If specific lengths are desired, it can be convenient to set :at:`meansize` to a round number like 1 or
that :ref:`scale <visual-scale>` values are in recognized length units. This is the only semantic of :at:`meansize` and 0.01 so that :ref:`scale <visual-scale>` values are in recognized length units. This is the only semantic of
setting it has no other side-effect. The automatically computed value is heuristic, representing the average body :at:`meansize` and setting it has no other side-effect. The automatically computed value is heuristic, representing
radius. The heuristic is based on geom sizes when present, the distances between joints when present, and the sizes the average body radius. The heuristic is based on geom sizes when present, the distances between joints when
of the body equivalent inertia boxes. present, and the sizes of the body equivalent inertia boxes.
:at:`extent`: :at-val:`real, optional` :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 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 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 multiplied by some of the attributes of the :ref:`map <visual-map>` element above. When the model is first loaded,
camera's initial distance from the :at:`center` (see below) is 1.5 times the :at:`extent`. Must be strictly positive. 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` :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 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 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** (?) :el-prefix:`default/` **motor** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| This and the next three elements set the attributes of the :ref:`general <actuator-general>` element using :ref:`Actuator This and the next three elements set the attributes of the :ref:`general <actuator-general>` element using
shortcuts <CActuator>`. It does not make sense to use more than one such shortcut in the same defaults :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. class, because they set the same underlying attributes, replacing any previous settings. All
| All :ref:`motor <actuator-motor>` attributes are available here except: name, class, joint, jointinparent, site, tendon, :ref:`motor <actuator-motor>` attributes are available here except: name, class, joint, jointinparent, site, tendon,
slidersite, cranksite. slidersite, cranksite.
.. _default-position: .. _default-position:
:el-prefix:`default/` **position** (?) :el-prefix:`default/` **position** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All :ref:`position <actuator-position>` attributes are available here except: name, class, joint, jointinparent, site, tendon, All :ref:`position <actuator-position>` attributes are available here except: name, class, joint, jointinparent, site,
slidersite, cranksite. tendon, slidersite, cranksite.
.. _default-velocity: .. _default-velocity:
:el-prefix:`default/` **velocity** (?) :el-prefix:`default/` **velocity** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All :ref:`velocity <actuator-velocity>` attributes are available here except: name, class, joint, jointinparent, site, tendon, All :ref:`velocity <actuator-velocity>` attributes are available here except: name, class, joint, jointinparent, site,
slidersite, cranksite. tendon, slidersite, cranksite.
.. _default-intvelocity: .. _default-intvelocity:
:el-prefix:`default/` **intvelocity** (?) :el-prefix:`default/` **intvelocity** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All :ref:`intvelocity <actuator-intvelocity>` attributes are available here except: name, class, joint, jointinparent, site, tendon, All :ref:`intvelocity <actuator-intvelocity>` attributes are available here except: name, class, joint, jointinparent,
slidersite, cranksite. site, tendon, slidersite, cranksite.
.. _default-damper: .. _default-damper:
:el-prefix:`default/` **damper** (?) :el-prefix:`default/` **damper** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All :ref:`damper <actuator-damper>` attributes are available here except: name, class, joint, jointinparent, site, tendon, All :ref:`damper <actuator-damper>` attributes are available here except: name, class, joint, jointinparent, site,
slidersite, cranksite. tendon, slidersite, cranksite.
.. _default-cylinder: .. _default-cylinder:
:el-prefix:`default/` **cylinder** (?) :el-prefix:`default/` **cylinder** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All :ref:`cylinder <actuator-cylinder>` attributes are available here except: name, class, joint, jointinparent, site, tendon, All :ref:`cylinder <actuator-cylinder>` attributes are available here except: name, class, joint, jointinparent, site,
slidersite, cranksite. tendon, slidersite, cranksite.
.. _default-muscle: .. _default-muscle:
:el-prefix:`default/` **muscle** (?) :el-prefix:`default/` **muscle** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
All :ref:`muscle <actuator-muscle>` attributes are available here except: name, class, joint, jointinparent, site, tendon, All :ref:`muscle <actuator-muscle>` attributes are available here except: name, class, joint, jointinparent, site,
slidersite, cranksite. tendon, slidersite, cranksite.
:el-prefix:`default/` **adhesion** (?) :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 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 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 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` :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 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. 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 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 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 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 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 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 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 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 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 orientation; see also :at:`mesh` attribute of :ref:`geom <body-geom>` below. Fortunately most meshes used in robot
designed in a coordinate frame centered at the joint. This makes the corresponding MJCF model intuitive: we set the body models are designed in a coordinate frame centered at the joint. This makes the corresponding MJCF model intuitive: we
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 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.
MJCF model fragment of a forearm, containing all the information needed to put the mesh where one would expect it to be. Below is an MJCF model fragment of a forearm, containing all the information needed to put the mesh where one would
The body position is specified relative to the parent body, namely the upper arm (not shown). It is offset by 35 cm expect it to be. The body position is specified relative to the parent body, namely the upper arm (not shown). It is
which is the typical length of the human upper arm. If the mesh vertex data were not designed in the above convention, offset by 35 cm which is the typical length of the human upper arm. If the mesh vertex data were not designed in the
we would have to use the geom position and orientation (or the new refpos, refquat mechanism) to compensate, but in above convention, we would have to use the geom position and orientation (or the new refpos, refquat mechanism) to
practice this is rarely needed. compensate, but in practice this is rarely needed.
.. code-block:: xml .. code-block:: xml
@@ -1404,9 +1408,12 @@ practice this is rarely needed.
<geom type="mesh" mesh="forearm"/> <geom type="mesh" mesh="forearm"/>
</body> </body>
The inertial computation mentioned above is part of an algorithm used not only to center and align the mesh, but also The inertial computation mentioned above is part of an algorithm used not only to center and align the mesh, but also to
to infer the mass and inertia of the body to which it is attached. This is done by computing the centroid of the infer the mass and inertia of the body to which it is attached. This is done by computing the centroid of the triangle
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. 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: 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** (*) :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 This element creates a material asset. It can be referenced from :ref:`skins <asset-skin>`, :ref:`geoms <body-geom>`,
<body-site>` and :ref:`tendons <tendon>` to set their appearance. Note that all these elements also have a local rgba :ref:`sites <body-site>` and :ref:`tendons <tendon>` to set their appearance. Note that all these elements also have a
attribute, which is more convenient when only colors need to be adjusted, because it does not require creating materials local rgba attribute, which is more convenient when only colors need to be adjusted, because it does not require
and referencing them. Materials are useful for adjusting appearance properties beyond color. However once a material is creating materials and referencing them. Materials are useful for adjusting appearance properties beyond color. However
created, it is more natural the specify the color using the material, so that all appearance properties are grouped once a material is created, it is more natural the specify the color using the material, so that all appearance
together. properties are grouped together.
:at:`name`: :at-val:`string, required` :at:`name`: :at-val:`string, required`
Name of the material, used for referencing. 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 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 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 of body: it cannot have child elements :ref:`inertial <body-inertial>` and :ref:`joint <body-joint>`, and also cannot
attributes. It corresponds to the origin of the world frame, within which the rest of the kinematic tree is defined. Its have any attributes. It corresponds to the origin of the world frame, within which the rest of the kinematic tree is
body name is automatically defined as "world". defined. Its body name is automatically defined as "world".
:at:`name`: :at-val:`string, optional` :at:`name`: :at-val:`string, optional`
Name of the body. 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 <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: 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 #. If the inertial frame is not defined via the :ref:`inertial <body-inertial>` element, it is inferred from the
attached to the body. If there are no geoms, the inertial frame remains undefined. This step is applied in both geoms attached to the body. If there are no geoms, the inertial frame remains undefined. This step is applied in
local and global coordinates. both local and global coordinates.
#. If both the body frame and the inertial frame are undefined, a compile error is generated. #. 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 #. 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. 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"/> <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. While this joint can evidently be created with the :ref:`joint <body-joint>` element, default joint settings could
This is usually undesirable as physical free bodies do not have nonzero stiffness, damping, friction or armature. To affect it. This is usually undesirable as physical free bodies do not have nonzero stiffness, damping, friction or
avoid this complication, the :el:`freejoint` element was introduced, ensuring joint defaults are *not inherited*. If armature. To avoid this complication, the :el:`freejoint` element was introduced, ensuring joint defaults are *not
the XML model is saved, it will appear as a regular joint of type :at:`free`. inherited*. If the XML model is saved, it will appear as a regular joint of type :at:`free`.
:at:`name`: :at-val:`string, optional` :at:`name`: :at-val:`string, optional`
Name of the joint. Name of the joint.
@@ -1874,38 +1881,38 @@ helps clarify the role of bodies and geoms in MuJoCo.
:at:`class`: :at-val:`string, optional` :at:`class`: :at-val:`string, optional`
Defaults class for setting unspecified attributes. Defaults class for setting unspecified attributes.
:at:`type`: :at-val:`[plane, hfield, sphere, capsule, ellipsoid, cylinder, box, mesh], "sphere"` :at:`type`: :at-val:`[plane, hfield, sphere, capsule, ellipsoid, cylinder, box, mesh], "sphere"`
Type of geometric shape. The keywords have the following meaning: Type of geometric shape. The keywords have the following meaning: The **plane** type defines a plane which is
The **plane** type defines a plane which is infinite for collision detection purposes. It can only be attached to the infinite for collision detection purposes. It can only be attached to the world body or static children of the world.
world body or static children of the world. The plane passes through a point specified via the pos attribute. It is The plane passes through a point specified via the pos attribute. It is normal to the Z axis of the geom's local
normal to the Z axis of the geom's local frame. The +Z direction corresponds to empty space. Thus the position and frame. The +Z direction corresponds to empty space. Thus the position and orientation defaults of (0,0,0) 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 (1,0,0,0) would create a ground plane at Z=0 elevation, with +Z being the vertical direction in the world (which is
vertical direction in the world (which is MuJoCo's convention). Since the plane is infinite, it could have been MuJoCo's convention). Since the plane is infinite, it could have been defined using any other point in the plane. The
defined using any other point in the plane. The specified position however has additional meaning with regard to specified position however has additional meaning with regard to rendering. If either of the first two size
rendering. If either of the first two size parameters are positive, the plane is rendered as a rectangle of finite parameters are positive, the plane is rendered as a rectangle of finite size (in the positive dimensions). This
size (in the positive dimensions). This rectangle is centered at the specified position. Three size parameters are rectangle is centered at the specified position. Three size parameters are required. The first two specify the half-
required. The first two specify the half-size of the rectangle along the X and Y axes. The third size parameter is size of the rectangle along the X and Y axes. The third size parameter is unusual: it specifies the spacing between
unusual: it specifies the spacing between the grid subdivisions of the plane for rendering purposes. The subdivisions the grid subdivisions of the plane for rendering purposes. The subdivisions are revealed in wireframe rendering mode,
are revealed in wireframe rendering mode, but in general they should not be used to paint a grid over the ground but in general they should not be used to paint a grid over the ground plane (textures should be used for that
plane (textures should be used for that purpose). Instead their role is to improve lighting and shadows, similar to purpose). Instead their role is to improve lighting and shadows, similar to the subdivisions used to render boxes.
the subdivisions used to render boxes. When planes are viewed from the back, the are automatically made When planes are viewed from the back, the are automatically made semi-transparent. Planes and the +Z faces of boxes
semi-transparent. Planes and the +Z faces of boxes are the only surfaces that can show reflections, if the are the only surfaces that can show reflections, if the :ref:`material <asset-material>` applied to the geom has
:ref:`material <asset-material>` applied to the geom has positive reflection. To render an infinite plane, set the first positive reflection. To render an infinite plane, set the first two size parameters to zero.
two size parameters to zero.
The **hfield** type defines a height field geom. The geom must reference the desired height field asset with the 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 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 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 description of the :ref:`hfield <asset-hfield>` element. Similar to planes, height field geoms can only be attached
world body or to static children of the world. 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 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 primitives are treated as analytic surfaces for collision detection purposes, in many cases relying on custom pair-
pair-wise collision routines. Models including only planes, spheres, capsules and boxes are the most efficient in wise collision routines. Models including only planes, spheres, capsules and boxes are the most efficient in terms of
terms of collision detection. Other geom types invoke the general-purpose convex collider. The sphere is centered at collision detection. Other geom types invoke the general-purpose convex collider. The sphere is centered at the
the geom's position. Only one size parameter is used, specifying the radius of the sphere. Rendering of geometric 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>`. primitives is done with automatically generated meshes whose density can be adjusted via
The sphere mesh is triangulated along the lines of latitude and longitude, with the Z axis passing through the north :ref:`quality <visual-quality>`. The sphere mesh is triangulated along the lines of latitude and longitude,
and south pole. This can be useful in wireframe mode for visualizing frame orientation. 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 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 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` :at:`class`: :at-val:`string, optional`
Defaults class for setting unspecified attributes. Defaults class for setting unspecified attributes.
:at:`mode`: :at-val:`[fixed, track, trackcom, targetbody, targetbodycom], "fixed"` :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 This is identical to the mode attribute of :ref:`camera <body-camera>` above. It specifies the how the light position
orientation in world coordinates are computed in forward kinematics (which in turn determine what the light and orientation in world coordinates are computed in forward kinematics (which in turn determine what the light
illuminates). illuminates).
:at:`target`: :at-val:`string, optional` :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 This is identical to the target attribute of :ref:`camera <body-camera>` above. It specifies which body should be
in "targetbody" and "targetbodycom" modes. targeted in "targetbody" and "targetbodycom" modes.
:at:`directional`: :at-val:`[false, true], "false"` :at:`directional`: :at-val:`[false, true], "false"`
The light is directional if this attribute is "true", otherwise it is a spotlight. The light is directional if this attribute is "true", otherwise it is a spotlight.
:at:`castshadow`: :at-val:`[false, true], "true"` :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 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 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 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 achieved by increasing the value of the shadowsize attribute of :ref:`quality <visual-quality>`, as well as
spotlights closer to the surface on which shadows appear, and limiting the volume in which shadows are cast. For positioning spotlights closer to the surface on which shadows appear, and limiting the volume in which shadows are
spotlights this volume is a cone, whose angle is the cutoff attribute below multiplied by the shadowscale attribute cast. For spotlights this volume is a cone, whose angle is the cutoff attribute below multiplied by the shadowscale
of :ref:`map <visual-map>`. For directional lights this volume is a box, whose half-sizes in the directions orthogonal to attribute of :ref:`map <visual-map>`. For directional lights this volume is a box, whose half-sizes in the directions
the light are the model extent multiplied by the shadowclip attribute of :ref:`map <visual-map>`. The model extent is orthogonal to the light are the model extent multiplied by the shadowclip attribute of :ref:`map <visual-map>`. The
computed by the compiler but can also be overridden by specifying the extent attribute of :ref:`statistic model extent is computed by the compiler but can also be overridden by specifying the extent attribute of
<statistic>`. Internally the shadow-mapping mechanism renders the scene from the light viewpoint (as if it were a :ref:`statistic <statistic>`. Internally the shadow-mapping mechanism renders the scene from the light viewpoint (as
camera) into a depth texture, and then renders again from the camera viewpoint, using the depth texture to create if it were a camera) into a depth texture, and then renders again from the camera viewpoint, using the depth texture
shadows. The internal rendering pass uses the same near and far clipping planes as regular rendering, i.e., these to create shadows. The internal rendering pass uses the same near and far clipping planes as regular rendering, i.e.,
clipping planes bound the cone or box shadow volume in the light direction. As a result, some shadows (especially these clipping planes bound the cone or box shadow volume in the light direction. As a result, some shadows
those very close to the light) may be clipped. (especially those very close to the light) may be clipped.
:at:`active`: :at-val:`[false, true], "true"` :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. 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"` :at:`pos`: :at-val:`real(3), "0 0 0"`
doc/changelog.rst
+26 -21
View File
@@ -98,8 +98,9 @@ General
:height: 150px :height: 150px
#. Cartesian 6D end-effector control is now possible by adding a reference site to actuators with :at:`site` #. 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 transmission. See description of new :at:`refsite` attribute in the :ref:`actuator<actuator-general>` documentation
`refsite.xml <https://github.com/deepmind/mujoco/tree/main/test/engine/testdata/refsite.xml>`_ example model. 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 #. 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 :at:`ctrllimited`, :at:`forcelimited` and :at:`actlimited` attributes will automatically be set to ``true`` if the
corresponding range *is defined* and ``false`` otherwise. corresponding range *is defined* and ``false`` otherwise.
@@ -162,7 +163,8 @@ General
#. Added visualisation groups to skins. #. Added visualisation groups to skins.
#. Added actuator visualisation for ``free`` and ``ball`` joints and for actuators with ``site`` transmission. #. Added actuator visualisation for ``free`` and ``ball`` joints and for actuators with ``site`` transmission.
#. Added visualisation for actuator activations. #. 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>`. #. Added ``<actuator-damper>`` actuator shortcut for active-damping actuators, documented :ref:`here <actuator-damper>`.
#. ``mju_rotVecMat`` and ``mju_rotVecMatT`` now support in-place multiplication. #. ``mju_rotVecMat`` and ``mju_rotVecMatT`` now support in-place multiplication.
#. ``mjData.ctrl`` values are no longer clamped in-place, remain untouched by the engine. #. ``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. #. 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 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 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 #. Added :at:`actlimited` and :at:`actrange` attributes to :ref:`general actuators<actuator-general>`, for clamping
internal states (activations). This clamping is useful for integrated-velocity actuators, see the :ref:`Activation actuator internal states (activations). This clamping is useful for integrated-velocity actuators, see the
clamping <CActRange>` section for details. :ref:`Activation clamping <CActRange>` section for details.
#. ``mjData`` fields ``qfrc_unc`` (unconstrained forces) and ``qacc_unc`` (unconstrained accelerations) were renamed #. ``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 ``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 other open source projects. Developers are encouraged to include MuJoCo public headers in their own codebase via
``#include <mujoco/filename.h>``. ``#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. #. 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. #. 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 #. Saved XML files only contain explicit :ref:`inertial <body-inertial>` elements if the original XML included them.
that were automatically inferred by the compiler's :ref:`inertiafromgeom <compiler>` mechanism remain unspecified. 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. #. 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 #. Static geoms now respect their :ref:`geom group<body-geom>` for visualisation. Until this change rendering of static
could only be toggled using the :ref:`mjVIS_STATIC<mjtVisFlag>` visualisation flag . After this change, both the geom geoms could only be toggled using the :ref:`mjVIS_STATIC<mjtVisFlag>` visualisation flag . After this change, both
group and the visualisation flag need to be enabled for the geom to be rendered. 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 #. 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 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. :ref:`weld <equality-weld>` constraints.
.. note:: .. note::
Forces generated by :ref:`spatial tendons <tendon-spatial>` which are outside the kinematic tree (i.e., between bodies Forces generated by :ref:`spatial tendons <tendon-spatial>` which are outside the kinematic tree (i.e., between
which have no ancestral relationship) are still not taken into account by force and torque sensors. This remains a bodies which have no ancestral relationship) are still not taken into account by force and torque sensors. This
future work item. remains a future work item.
Code samples 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. 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 a. MuJoCo library is now packaged as a `Framework Bundle
`Framework Bundle <https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/FrameworkAnatomy.html>`_, <https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/FrameworkAnato
allowing it to be incorporated more easily into Xcode projects (including Swift projects). Developers are my.html>`_, allowing it to be incorporated more easily into Xcode projects (including Swift projects). Developers
encouraged to compile and link against MuJoCo using the ``-framework mujoco`` flag, however all header files and are encouraged to compile and link against MuJoCo using the ``-framework mujoco`` flag, however all header files
the ``libmujoco.2.1.1.dylib`` library can still be directly accessed inside the framework. 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, #. 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 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. (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`. :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 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>` torques to the target object. Ball joints are special, see the :at:`joint` documentation in
reference for more details. :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 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. 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 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 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 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 better to model it as a joint property. Note also the XML :ref:`joint <body-joint>` attribute springdamper which
the creation of mass-spring-dampers with desired time constants and damping ratios; in that case the compiler computes automates the creation of mass-spring-dampers with desired time constants and damping ratios; in that case the compiler
the stiffness and damping coefficients of the joint by taking the joint inertia into account. 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 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 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 Generation
First we generate a list of candidate geom pairs in one of two ways: "pair" or "dynamic". The user can also specify 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" "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 refers to an explicit list of geom pairs defined with the :ref:`pair <contact-pair>` element in MJCF. It gives the
control, however it is a static mechanism (independent of the spatial arrangement of the geoms at runtime) and can be user full control, however it is a static mechanism (independent of the spatial arrangement of the geoms at runtime)
tedious for large models. It is normally used to supplement the output of the "dynamic" mechanism. Dynamic generation and can be tedious for large models. It is normally used to supplement the output of the "dynamic" mechanism. Dynamic
works with bodies rather than geoms; when a body pair is included this means that all geoms attached to one body can generation works with bodies rather than geoms; when a body pair is included this means that all geoms attached to
collide with all geoms attached to the other body. The body pairs are generated via broad-phase collision detection one body can collide with all geoms attached to the other body. The body pairs are generated via broad-phase
based on a modified sweep-and-prune algorithm. The modification is that the axis for sorting is chosen as the collision detection based on a modified sweep-and-prune algorithm. The modification is that the axis for sorting is
principal eigenvector of the covariance matrix of all geom centers - which maximizes the spread. If broad-phase chosen as the principal eigenvector of the covariance matrix of all geom centers - which maximizes the spread. If
collision detection is disabled by the user, all body pairs are included in this step. 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 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 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 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. 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 When a :ref:`joint <body-joint>` is defined inside a body, its function is not to connect the parent and child but
create motion degrees of freedom between them. If no joints are defined within a given body, that body is welded to its rather to create motion degrees of freedom between them. If no joints are defined within a given body, that body is
parent. A body in MJCF can contain multiple joints, thus there is no need to introduce dummy bodies for creating welded to its parent. A body in MJCF can contain multiple joints, thus there is no need to introduce dummy bodies for
composite joints. Instead simply define all the primitive joints that form the desired composite joint within the same creating composite joints. Instead simply define all the primitive joints that form the desired composite joint within
body. For example, two sliders and one hinge can be used to model a body moving in a plane. 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>`, Other MJCF elements can be defined within the tree created by nested body elements, in particular
:ref:`geom <body-geom>`, :ref:`site <body-site>`, :ref:`camera <body-camera>`, :ref:`light <body-light>`. When an element is defined within :ref:`joint <body-joint>`, :ref:`geom <body-geom>`, :ref:`site <body-site>`, :ref:`camera <body-camera>`, :ref:`light
a body, it is fixed to the local frame of that body and always moves with it. Elements that refer to multiple bodies, or <body-light>`. When an element is defined within a body, it is fixed to the local frame of that body and always moves
do not refer to bodies at all, are defined in separate sections outside the kinematic tree. 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: .. _CDefault:
@@ -302,8 +303,8 @@ approximately
.. math:: .. math::
a_1 + d \cdot (b v + k r) = (1 - d)\cdot a_0 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 Again, the parameters that are under the user's control are :math:`d, b, k`. The remaining quantities are functions of
system state and are computed automatically at each time step. 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 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 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 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 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- 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 specific parameters are either defined in the MJCF file via the :at:`user` attribute of :ref:`geom <body-geom>`, or set
by the compiler if this attribute is omitted. The default value of all "nuser_XXX" attributes is -1, which instructs the to 0 by the compiler if this attribute is omitted. The default value of all "nuser_XXX" attributes is -1, which
compiler to automatically set this value to the length of the maximum associated :at:`user` attribute defined in the instructs the compiler to automatically set this value to the length of the maximum associated :at:`user` attribute
model. MuJoCo does not use these parameters in any internal computations; instead they are available for custom defined in the model. MuJoCo does not use these parameters in any internal computations; instead they are available for
computations. The parser allows arrays of arbitrary length in the XML, and the compiler later resizes them to length custom computations. The parser allows arrays of arbitrary length in the XML, and the compiler later resizes them to
nuser_XXX. length nuser_XXX.
Some element-specific parameters that are normally used in internal computations can also be used in custom 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, 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. 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 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 do this is to experiment with the relevant settings and use the visual profiler in :ref:`simulate.cc <saSimulate>`,
shows the timing of different computations as well as solver statistics per iteration. We can offer the following general which shows the timing of different computations as well as solver statistics per iteration. We can offer the following
guidelines and observations: general guidelines and observations:
- The constraint Jacobian should be dense for small models and sparse for large models. The default setting is 'auto'; - 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 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 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 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 independently. The full functionality can be accessed via the XML element :ref:`general <actuator-general>` which allows
to create a variety of custom actuators. In addition, MJCF provides shortcuts for configuring common actuators. This is the user to create a variety of custom actuators. In addition, MJCF provides shortcuts for configuring common actuators.
done via the XML elements :ref:`motor <actuator-motor>`, :ref:`position <actuator-position>`, :ref:`velocity <actuator-velocity>`, This is done via the XML elements :ref:`motor <actuator-motor>`, :ref:`position <actuator-position>`, :ref:`velocity
:ref:`intvelocity <actuator-intvelocity>`, :ref:`damper<actuator-damper>`, :ref:`cylinder<actuator-cylinder>`, :ref:`muscle <actuator-muscle>`, and <actuator-velocity>`, :ref:`intvelocity <actuator-intvelocity>`, :ref:`damper<actuator-damper>`,
:ref:`adhesion <actuator-adhesion>`. These are *not* separate model elements. Internally MuJoCo supports only one actuator type - :ref:`cylinder<actuator-cylinder>`, :ref:`muscle <actuator-muscle>`, and :ref:`adhesion <actuator-adhesion>`. These are
which is why when an MJCF model is saved all actuators are written as :el:`general`. Shortcuts create general actuators *not* separate model elements. Internally MuJoCo supports only one actuator type -which is why when an MJCF model is
implicitly, set their attributes to suitable values, and expose a subset of attributes with possibly different names. saved all actuators are written as :el:`general`. Shortcuts create general actuators implicitly, set their attributes to
For example, :el:`position` creates a position servo with attribute :at:`kp` which is the servo gain. However suitable values, and expose a subset of attributes with possibly different names. For example, :el:`position` creates a
:el:`general` does not have an attribute :at:`kp`. Instead the parser adjusts the gain and bias parameters of the position servo with attribute :at:`kp` which is the servo gain. However :el:`general` does not have an attribute
general actuator in a coordinated way so as to mimic a position servo. The same effect could have been achieved by using :at:`kp`. Instead the parser adjusts the gain and bias parameters of the general actuator in a coordinated way so as to
:el:`general` directly, and setting its attributes to certain values as described below. 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 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 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 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). 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 If known, it can be set with the attribute force of element :ref:`muscle <actuator-muscle>`. If it is not known, we set
:math:`-1` which is the default. In that case we rely on the fact that larger muscles tend to act on joints that move 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
more weight. The attribute scale defines this relationship as: move more weight. The attribute scale defines this relationship as:
.. math:: .. math::
F_0 = \text{scale} / \texttt{actuator\_acc0} 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 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. 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 The :ref:`simulate.cc <saSimulate>` code sample uses the mouse as a motion capture device, allowing the user to move
bodies around: mocap bodies around:
|particle| |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 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 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 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 and collision detection purposes, the grid rectangles are automatically triangulated, thus the height field is
as a union of triangular prisms. Collision detection with such a composite object can in principle generate a large treated as a union of triangular prisms. Collision detection with such a composite object can in principle generate a
number of contact points for a single geom pair. If that happens, only the first 64 contact points are kept. The large number of contact points for a single geom pair. If that happens, only the first 64 contact points are kept.
rationale is that height fields should be used to model terrain maps whose spatial features are large compared to the The rationale is that height fields should be used to model terrain maps whose spatial features are large compared to
other objects in the simulation, so the number of contacts will be small for well-designed models. the other objects in the simulation, so the number of contacts will be small for well-designed models.
Texture Texture
Textures can be loaded from PNG files or synthesized by the compiler based on user-defined procedural parameters. 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 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 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 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 configuration corresponds to 90°, using the ref attribute of :ref:`joint <body-joint>`. The reference values of all
are assembled into the vector ``mjModel.qpos0``. Whenever the simulation is reset, the joint configuration 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 ``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 - 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 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. - 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 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>`__. `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 default value of :ref:`geom density<body-geom>` (used to infer body masses and inertias) is 1000, which
the density of water in MKS. 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 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 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. :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 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: .. _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 first, followed by the limits of the second joint etc. This ordering reflects the fact that all matrices in MuJoCo have
row-major format. row-major format.
The available element types are defined in The available element types are defined in `mjmodel.h
`mjmodel.h <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h#L243>`_, in the enum type :ref:`mjtObj`. <https://github.com/deepmind/mujoco/blob/main/include/mujoco/mjmodel.h#L243>`_, in the enum type :ref:`mjtObj`. These
These enums are mostly used internally. One exception are the functions :ref:`mj_name2id` and :ref:`mj_id2name` in the enums are mostly used internally. One exception are the functions :ref:`mj_name2id` and :ref:`mj_id2name` in the MuJoCo
MuJoCo API, which map element names to integer ids and vice versa. These functions take an element type as input. 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 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 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 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>`_. Windows, Linux, and macOS. These can be downloaded from the `GitHub Releases page
Users who do not intend to develop or modify core MuJoCo code are encouraged to use our pre-built libraries, as these <https://github.com/deepmind/mujoco/releases>`_. Users who do not intend to develop or modify core MuJoCo code are
come bundled with the same versions of dependencies that we regularly test against, and benefit from build flags encouraged to use our pre-built libraries, as these come bundled with the same versions of dependencies that we
that have been tuned for performance. Our pre-built libraries are almost entirely self-contained and do not require regularly test against, and benefit from build flags that have been tuned for performance. Our pre-built libraries are
any other library to be present, outside the standard C runtime. We also hide all symbols apart from almost entirely self-contained and do not require any other library to be present, outside the standard C runtime. We
those that form MuJoCo's public API, thus ensuring that it can coexist with any other libraries that may be loaded into also hide all symbols apart from those that form MuJoCo's public API, thus ensuring that it can coexist with any other
the process (including other versions of libraries that MuJoCo depends on). 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. 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 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 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 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>`_, working development environment. We provide Makefiles for `Windows
`macOS <https://github.com/deepmind/mujoco/blob/main/sample/Makefile.macos>`_, and <https://github.com/deepmind/mujoco/blob/main/sample/Makefile.windows>`_, `macOS
`Linux <https://github.com/deepmind/mujoco/blob/main/sample/Makefile>`_, and also a cross-platform <https://github.com/deepmind/mujoco/blob/main/sample/Makefile.macos>`_, and `Linux
`CMake <https://github.com/deepmind/mujoco/blob/main/sample/CMakeLists.txt>`_ setup that can be used to build sample <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 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 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 prompt with native x64 tools or call the ``vcvarsall.bat`` script that comes with your MSVC installation to set up the
appropriate environment variables. appropriate environment variables.
On macOS, the DMG disk image contains ``MuJoCo.app``, which you can double-click to launch the ``simulate`` GUI. On macOS, the DMG disk image contains ``MuJoCo.app``, which you can double-click to launch the ``simulate`` GUI. You can
You can also drag ``MuJoCo.app`` into the ``/Application`` on your system, as you would to install any other app. also drag ``MuJoCo.app`` into the ``/Application`` on your system, as you would to install any other app. While
While ``MuJoCo.app`` may look like a file, it is in fact an `Application Bundle <https://developer.apple.com/go/?id=bundle-structure>`_, ``MuJoCo.app`` may look like a file, it is in fact an `Application Bundle <https://developer.apple.com/go/?id=bundle-
which is a directory that contains executable binaries for all of MuJoCo's sample applications, along with an embedded structure>`_, which is a directory that contains executable binaries for all of MuJoCo's sample applications, along with
`framework <https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html>`_, 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, 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 ``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". 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 .. youtube:: 0ORsj_E17B0
:align: center :align: center
Interaction is done with the mouse; built-in help with a summary of available commands is available by pressing the ``F1`` Interaction is done with the mouse; built-in help with a summary of available commands is available by pressing the
key. Briefly, an object is selected by left-double-click. The user can then apply forces and torques on the selected ``F1`` key. Briefly, an object is selected by left-double-click. The user can then apply forces and torques on the
object by holding Ctrl and dragging the mouse. Dragging the mouse alone (without Ctrl) moves the camera. There are selected object by holding Ctrl and dragging the mouse. Dragging the mouse alone (without Ctrl) moves the camera. There
keyboard shortcuts for pausing the simulation, resetting, and re-loading the model file. The latter functionality is 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. 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. 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 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 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 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 multi-samples for the offscreen buffer are specified in the MuJoCo model, while the simulation duration, frames-per-
to be rendered (usually much less than the physics simulation rate), and output file name are specified as command-line second to be rendered (usually much less than the physics simulation rate), and output file name are specified as
arguments. For example, a 5 second animation at 60 frames per second is created with: command-line arguments. For example, a 5 second animation at 60 frames per second is created with:
.. code-block:: Shell .. code-block:: Shell
@@ -628,11 +630,11 @@ control callback) would become
mj_step(m, d); 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? Why would we not be able to compute the controls before ``mj_step`` is called? After all, isn't this what causality
The answer is subtle but important, and has to do with the fact that we are simulating in discrete time. The top-level means? The answer is subtle but important, and has to do with the fact that we are simulating in discrete time. The top-
simulation function ``mj_step`` basically does two things: compute the :ref:`forward dynamics <siForward>` in continuous level simulation function ``mj_step`` basically does two things: compute the :ref:`forward dynamics <siForward>` in
time, and then integrate over a time period specified by ``mjModel.opt.timestep``. Forward dynamics computes the continuous time, and then integrate over a time period specified by ``mjModel.opt.timestep``. Forward dynamics computes
acceleration ``mjData.qacc`` at time ``mjData.time``, given the :ref:`state and control <siStateControl>` at time 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``. ``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 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 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, 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 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 precisely, we create as many threads as there are processors, and then within the ``worker`` function we distribute the
the work explicitly among threads (not shown here, but see :ref:`derivative.cc <saDerivative>` for an example). This approach is more work explicitly among threads (not shown here, but see :ref:`derivative.cc <saDerivative>` for an example). This
efficient because the thread-specific mjData is large compared to the processor cache. 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 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 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. 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 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 corresponding upload function: ``mjr_uploadTexture``, ``mjr_uploadMesh``, ``mjr_uploadHField``. Otherwise the data used
simulation and for rendering will no longer be consistent. 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 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 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 Perturbations
''''''''''''' '''''''''''''
Interactive perturbations have proven very useful in exploring the model dynamics as well as probing closed-loop Interactive perturbations have proven very useful in exploring the model dynamics as well as probing closed-loop control
control systems. The user is free to implement any perturbation mechanism of their choice by setting systems. The user is free to implement any perturbation mechanism of their choice by setting ``mjData.qfrc_applied`` or
``mjData.qfrc_applied`` or ``mjData.xfrc_applied`` to suitable forces (in generalized and Cartesian coordinates respectively). ``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. 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 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 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 The MuJoCo `Unity plug-in <https://github.com/deepmind/mujoco/tree/main/unity>`_ allows the Unity Editor and runtime to
files and edit the models in the Editor. The plug-in relies on Unity for most aspects -- assets, game logic, simulation use the MuJoCo physics engine. Users can import MJCF files and edit the models in the Editor. The plug-in relies on
time -- but uses MuJoCo to determine how objects move, giving the designer access to MuJoCo's full API. 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: .. _UInstallation: