Formatting improvements to docs Overview chapter.
PiperOrigin-RevId: 561586361 Change-Id: Ib529cbd49cebf26d802d023d12d973491e41d3ad
This commit is contained in:
Yuval Tassa
committed by
Copybara-Service
Copybara-Service
parent
ac150f751d
commit
43a0bd3646
+4
-4
@@ -38,11 +38,11 @@ General
|
||||
Euler integrator. See the :ref:`Numerical Integration<geIntegration>` section for more details.
|
||||
#. Added the flag :ref:`invdiscrete<option-flag-invdiscrete>`, which enables discrete-time inverse dynamics for all
|
||||
:ref:`integrators<option-integrator>` other than ``RK4``. See the flag documentation for more details.
|
||||
#. Changed the function ``mj_stackAlloc`` to allocate an arbitrary number of bytes, rather than in multiples of
|
||||
#. Changed the function :ref:`mj_stackAlloc` to allocate an arbitrary number of bytes, rather than in multiples of
|
||||
``sizeof(mjtNum)``, and add an additional argument for specifying the alignment of the returned pointer. The existing
|
||||
functionality of allocating ``mjtNum`` arrays is still available through the new function ``mj_stackAllocNum``.
|
||||
#. Renamed the ``nstack`` field in ``mjModel`` and ``mjData`` to ``narena``. Changed ``narena``, ``pstack``, and
|
||||
``maxuse_stack`` to count number of bytes rather than number of ``mjtNum``s.
|
||||
functionality of allocating ``mjtNum`` arrays is still available through the new function :ref:`mj_stackAllocNum`.
|
||||
#. Renamed the ``nstack`` field in :ref:`mjModel` and :ref:`mjData` to ``narena``. Changed ``narena``, ``pstack``, and
|
||||
``maxuse_stack`` to count number of bytes rather than number of :ref:`mjtNum` |-| s.
|
||||
|
||||
Python bindings
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
+105
-52
@@ -239,8 +239,7 @@ The function :ref:`mj_step` is the top-level function which advances the simulat
|
||||
of course is just a passive dynamical system. Things get more interesting when the user specifies controls or applies
|
||||
forces and starts interacting with the system.
|
||||
|
||||
Next we provide a more elaborate example illustrating several features of MJCF.
|
||||
|
||||
Next we provide a more elaborate example illustrating several features of MJCF. Consider the following
|
||||
`example.xml <_static/example.xml>`__:
|
||||
|
||||
.. code:: xml
|
||||
@@ -332,15 +331,21 @@ XML file, default values are used. The options are designed such that the user c
|
||||
simulation time step. Within a time step however none of the options should be changed.
|
||||
|
||||
``mjOption``
|
||||
^^^^^^^^^^^^
|
||||
|
||||
This structure contains all options that affect the physics simulation. It is used to select algorithms and set their
|
||||
parameters, enable and disable different portions of the simulation pipeline, and adjust system-level physical
|
||||
properties such as gravity.
|
||||
|
||||
``mjVisual``
|
||||
^^^^^^^^^^^^
|
||||
|
||||
This structure contains all visualization options. There are additional OpenGL rendering options, but these are
|
||||
session-dependent and are not part of the model.
|
||||
|
||||
``mjStatistic``
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
This structure contains statistics about the model which are computed by the compiler: average body mass, spatial
|
||||
extent of the model etc. It is included for information purposes, and also because the visualizer uses it for
|
||||
automatic scaling.
|
||||
@@ -357,6 +362,8 @@ purpose of including an asset is to reference it, and referencing can only be do
|
||||
undefined.
|
||||
|
||||
Mesh
|
||||
^^^^
|
||||
|
||||
MuJoCo can load triangulated meshes from OBJ files and binary STL. Software such as `MeshLab
|
||||
<https://www.meshlab.net/>`__ can be used to convert from other formats. While any collection of triangles can be
|
||||
loaded and visualized as a mesh, the collision detector works with the convex hull. There are compile-time options
|
||||
@@ -367,6 +374,8 @@ Mesh
|
||||
custom binary file format for normals and texture coordinates. Meshes can also be embedded directly in the XML.
|
||||
|
||||
Skin
|
||||
^^^^
|
||||
|
||||
Skinned meshes (or skins) are meshes whose shape can deform at runtime. Their vertices are attached to rigid bodies
|
||||
(called bones in this context) and each vertex can belong to multiple bones, resulting in smooth deformations of the
|
||||
skin. Skins are purely visualization objects and do not affect the physics, but nevertheless they can enhance visual
|
||||
@@ -375,6 +384,8 @@ Skin
|
||||
objects.
|
||||
|
||||
Height field
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Height fields can be loaded from PNG files (converted to gray-scale internally) or from files in a custom binary
|
||||
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
|
||||
@@ -386,6 +397,8 @@ Height field
|
||||
the other objects in the simulation, so the number of contacts will be small for well-designed models.
|
||||
|
||||
Texture
|
||||
^^^^^^^
|
||||
|
||||
Textures can be loaded from PNG files or synthesized by the compiler based on user-defined procedural parameters.
|
||||
There is also the option to leave the texture empty at model creation time and change it later at runtime -- so as to
|
||||
render video in a MuJoCo simulation, or create other dynamic effects. The visualizer supports two types of texture
|
||||
@@ -396,6 +409,8 @@ Texture
|
||||
only be referenced from another asset (namely material) which is then referenced from model elements.
|
||||
|
||||
Material
|
||||
^^^^^^^^
|
||||
|
||||
Materials are used to control the appearance of geoms, sites and tendons. This is done by referencing the material
|
||||
from the corresponding model element. Appearance includes texture mapping as well as other properties that interact
|
||||
with OpenGL lights below: RGBA, specularity, shininess, emission. Materials can also be used to make objects
|
||||
@@ -417,6 +432,8 @@ within a body and belong to that body. This is in contrast with the stand-alone
|
||||
associated with a single body.
|
||||
|
||||
Body
|
||||
^^^^
|
||||
|
||||
Bodies have mass and inertial properties but do not have any geometric properties. Instead geometric shapes (or
|
||||
geoms) are attached to the bodies. Each body has two coordinate frames: the frame used to define it as well as to
|
||||
position other elements relative to it, and an inertial frame centered at the body's center of mass and aligned with
|
||||
@@ -425,6 +442,8 @@ Body
|
||||
coordinates. This provides the basis for all subsequent computations.
|
||||
|
||||
Joint
|
||||
^^^^^
|
||||
|
||||
Joints are defined within bodies. They create motion degrees of freedom (DOFs) between the body and its parent. In
|
||||
the absence of joints the body is welded to its parent. This is the opposite of gaming engines which use
|
||||
over-complete Cartesian coordinates, where joints remove DOFs instead of adding them. There are four types of joints:
|
||||
@@ -433,56 +452,9 @@ Joint
|
||||
ball and free joints are represented as unit quaternions, and all computations in MuJoCo respect the properties of
|
||||
quaternions.
|
||||
|
||||
DOF
|
||||
Degrees of freedom are closely related to joints, but are not in one-to-one correspondence because ball and free
|
||||
joints have multiple DOFs. Think of joints as specifying positional information, and of DOFs as specifying velocity
|
||||
and force information. More formally, the joint positions are coordinates over the configuration manifold of the
|
||||
system, while the joint velocities are coordinates over the tangent space to this manifold at the current position.
|
||||
DOFs have velocity-related properties such as friction loss, damping, armature inertia. All generalized forces acting
|
||||
on the system are expressed in the space of DOFs. In contrast, joints have position-related properties such as limits
|
||||
and spring stiffness. DOFs are not specified directly by the user. Instead they are created by the compiler given the
|
||||
joints.
|
||||
Joint reference
|
||||
'''''''''''''''
|
||||
|
||||
Geom
|
||||
Geoms are 3D shapes rigidly attached to the bodies. Multiple geoms can be attached to the same body. This is
|
||||
particularly useful in light of the fact that MuJoCo only supports convex geom-geom collisions, and the only way to
|
||||
create non-convex objects is to represent them as a union of convex geoms. Apart from collision detection and
|
||||
subsequent computation of contact forces, geoms are used for rendering, as well as automatic inference of body masses
|
||||
and inertias when the latter are omitted. MuJoCo supports several primitive geometric shapes: plane, sphere, capsule,
|
||||
ellipsoid, cylinder, box. A geom can also be a mesh or a height field; this is done by referencing the corresponding
|
||||
asset. Geoms have a number of material properties that affect the simulation and visualization.
|
||||
|
||||
Site
|
||||
Sites are essentially light geoms. They represent locations of interest within the body frame. Sites do not
|
||||
participate in collision detection or automated computation of inertial properties, however they can be used to
|
||||
specify the spatial properties of other objects like sensors, tendon routing, and slider-crank endpoints.
|
||||
|
||||
Camera
|
||||
Multiple cameras can be defined in a model. There is always a default camera which the user can freely move with the
|
||||
mouse in the interactive visualizer. However it is often convenient to define additional cameras that are either
|
||||
fixed to the world, or are attached to one of the bodies and move with it. In addition to the camera position and
|
||||
orientation, the user can adjust the field of view and the inter-pupilary distance for stereoscopic rendering, as
|
||||
well as create oblique projections needed for stereoscopic virtual environments.
|
||||
|
||||
Light
|
||||
Lights can be fixed to the world body or attached to moving bodies. The visualizer provides access to the full
|
||||
lighting model in OpenGL (fixed function) including ambient, diffuse and specular components, attenuation and cutoff,
|
||||
positional and directional lighting, fog. Lights, or rather the objects illuminated by them, can also cast shadows.
|
||||
However, similar to material reflections, each shadow-casting light adds one rendering pass so this feature should be
|
||||
used with caution. Documenting the lighting model in detail is beyond the scope of this chapter; see `OpenGL
|
||||
documentation <http://www.glprogramming.com/red/chapter05.html>`__ instead. Note that in addition to lights defined
|
||||
by the user in the kinematic tree, there is a default headlight that moves with the camera. Its properties are
|
||||
adjusted through the mjVisual options.
|
||||
|
||||
.. _Standalone:
|
||||
|
||||
Stand-alone elements
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Here we describe the model elements which do not belong to an individual body, and therefore are described outside the
|
||||
kinematic tree.
|
||||
|
||||
Reference pose
|
||||
The reference pose is a vector of joint positions stored in ``mjModel.qpos0``. It corresponds to the numeric values
|
||||
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
|
||||
@@ -496,14 +468,77 @@ Reference pose
|
||||
the quaternion saved in ``mjModel.qpos0`` is always (1,0,0,0) which corresponds to the null rotation. For free
|
||||
joints, the global 3D position and quaternion of the floating body are saved in ``mjModel.qpos0``.
|
||||
|
||||
Spring reference pose
|
||||
Spring reference
|
||||
''''''''''''''''
|
||||
|
||||
This is the pose in which all joint and tendon springs achieve their resting length. Spring forces are generated
|
||||
when the joint configuration deviates from the spring reference pose, and are linear in the amount of deviation. The
|
||||
spring reference pose is saved in ``mjModel.qpos_spring``. For slide and hinge joints, the spring reference is
|
||||
specified with the attribute springref. For ball and free joints, the spring reference corresponds to the initial
|
||||
model configuration.
|
||||
|
||||
DOF
|
||||
^^^
|
||||
|
||||
Degrees of freedom are closely related to joints, but are not in one-to-one correspondence because ball and free
|
||||
joints have multiple DOFs. Think of joints as specifying positional information, and of DOFs as specifying velocity
|
||||
and force information. More formally, the joint positions are coordinates over the configuration manifold of the
|
||||
system, while the joint velocities are coordinates over the tangent space to this manifold at the current position.
|
||||
DOFs have velocity-related properties such as friction loss, damping, armature inertia. All generalized forces acting
|
||||
on the system are expressed in the space of DOFs. In contrast, joints have position-related properties such as limits
|
||||
and spring stiffness. DOFs are not specified directly by the user. Instead they are created by the compiler given the
|
||||
joints.
|
||||
|
||||
Geom
|
||||
^^^^
|
||||
|
||||
Geoms are 3D shapes rigidly attached to the bodies. Multiple geoms can be attached to the same body. This is
|
||||
particularly useful in light of the fact that MuJoCo only supports convex geom-geom collisions, and the only way to
|
||||
create non-convex objects is to represent them as a union of convex geoms. Apart from collision detection and
|
||||
subsequent computation of contact forces, geoms are used for rendering, as well as automatic inference of body masses
|
||||
and inertias when the latter are omitted. MuJoCo supports several primitive geometric shapes: plane, sphere, capsule,
|
||||
ellipsoid, cylinder, box. A geom can also be a mesh or a height field; this is done by referencing the corresponding
|
||||
asset. Geoms have a number of material properties that affect the simulation and visualization.
|
||||
|
||||
Site
|
||||
^^^^
|
||||
|
||||
Sites are essentially light geoms. They represent locations of interest within the body frame. Sites do not
|
||||
participate in collision detection or automated computation of inertial properties, however they can be used to
|
||||
specify the spatial properties of other objects like sensors, tendon routing, and slider-crank endpoints.
|
||||
|
||||
Camera
|
||||
^^^^^^
|
||||
|
||||
Multiple cameras can be defined in a model. There is always a default camera which the user can freely move with the
|
||||
mouse in the interactive visualizer. However it is often convenient to define additional cameras that are either
|
||||
fixed to the world, or are attached to one of the bodies and move with it. In addition to the camera position and
|
||||
orientation, the user can adjust the field of view and the inter-pupilary distance for stereoscopic rendering, as
|
||||
well as create oblique projections needed for stereoscopic virtual environments.
|
||||
|
||||
Light
|
||||
^^^^^
|
||||
|
||||
Lights can be fixed to the world body or attached to moving bodies. The visualizer provides access to the full
|
||||
lighting model in OpenGL (fixed function) including ambient, diffuse and specular components, attenuation and cutoff,
|
||||
positional and directional lighting, fog. Lights, or rather the objects illuminated by them, can also cast shadows.
|
||||
However, similar to material reflections, each shadow-casting light adds one rendering pass so this feature should be
|
||||
used with caution. Documenting the lighting model in detail is beyond the scope of this chapter; see `OpenGL
|
||||
documentation <http://www.glprogramming.com/red/chapter05.html>`__ instead. Note that in addition to lights defined
|
||||
by the user in the kinematic tree, there is a default headlight that moves with the camera. Its properties are
|
||||
adjusted through the mjVisual options.
|
||||
|
||||
.. _Standalone:
|
||||
|
||||
Stand-alone
|
||||
~~~~~~~~~~~
|
||||
|
||||
Here we describe the model elements which do not belong to an individual body, and therefore are described outside the
|
||||
kinematic tree.
|
||||
|
||||
Tendon
|
||||
^^^^^^
|
||||
|
||||
Tendons are scalar length elements that can be used for actuation, imposing limits and equality constraints, or
|
||||
creating spring-dampers and friction loss. There are two types of tendons: fixed and spatial. Fixed tendons are
|
||||
linear combinations of (scalar) joint positions. They are useful for modeling mechanical coupling. Spatial tendons
|
||||
@@ -515,6 +550,8 @@ Tendon
|
||||
multiple branches using pulleys.
|
||||
|
||||
Actuator
|
||||
^^^^^^^^
|
||||
|
||||
MuJoCo provides a flexible actuator model, with three components that can be specified independently. Together they
|
||||
determine how the actuator works. Common actuator types are obtained by specifying these components in a coordinated
|
||||
way. The three components are transmission, activation dynamics, and force generation. The transmission specifies how
|
||||
@@ -525,6 +562,8 @@ Actuator
|
||||
turn mapped into a generalized force by the moment arms inferred from the transmission.
|
||||
|
||||
Sensor
|
||||
^^^^^^
|
||||
|
||||
MuJoCo can generate simulated sensor data which is saved in the global array ``mjData.sensordata``. The result is not
|
||||
used in any internal computations; instead it is provided because the user presumably needs it for custom computation
|
||||
or data analysis. Available sensor types include touch sensors, inertial measurement units (IMUs), force-torque
|
||||
@@ -536,6 +575,8 @@ Sensor
|
||||
and instead has to be done programmatically, as illustrated in the code sample :ref:`simulate.cc <saSimulate>`.
|
||||
|
||||
Equality
|
||||
^^^^^^^^
|
||||
|
||||
Equality constraints can impose additional constraints beyond those already imposed by the kinematic tree structure
|
||||
and the joints/DOFs defined in it. They can be used to create loop joints, or in general model mechanical coupling.
|
||||
The internal forces that enforce these constraints are computed together with all other constraint forces. The
|
||||
@@ -544,6 +585,8 @@ Equality
|
||||
the positions of two joints or two tendons via a cubic polynomial.
|
||||
|
||||
Contact pair
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Contact generation in MuJoCo is an elaborate process. Geom pairs that are checked for contact can come from two
|
||||
sources: automated proximity tests and other filters collectively called "dynamic", as well as an explicit list of
|
||||
geom pairs provided in the model. The latter is a separate type of model element. Because a contact involves a
|
||||
@@ -552,6 +595,8 @@ Contact pair
|
||||
pairs that were removed by an aggressive filtering scheme.
|
||||
|
||||
Contact exclude
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
This is the opposite of contact pairs: it specifies pairs of bodies (rather than geoms) which should be excluded from
|
||||
the generation of candidate contact pairs. It is useful for disabling contacts between bodies whose geometry causes
|
||||
an undesirable permanent contact. Note that MuJoCo has other mechanisms for dealing with this situation (in
|
||||
@@ -559,6 +604,8 @@ Contact exclude
|
||||
automated mechanisms are not sufficient and explicit exclusion becomes necessary.
|
||||
|
||||
Custom numeric
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
There are three ways to enter custom numbers in a MuJoCo simulation. First, global numeric fields can be defined in
|
||||
the XML. They have a name and an array of real values. Second, the definition of certain model elements can be
|
||||
extended with element-specific custom arrays. This is done by setting the attributes ``nuser_XXX`` in the XML element
|
||||
@@ -567,17 +614,23 @@ Custom numeric
|
||||
``mjData`` and not in ``mjModel``.
|
||||
|
||||
Custom text
|
||||
^^^^^^^^^^^
|
||||
|
||||
Custom text fields can be saved in the model. They can be used in custom computations - either to specify keyword
|
||||
commands, or to provide some other textual information. Do not use them for comments though; there is no benefit to
|
||||
saving comments in a compiled model. XML has its own commenting mechanism (ignored by MuJoCo's parser and compiler)
|
||||
which is more suitable.
|
||||
|
||||
Custom tuple
|
||||
^^^^^^^^^^^^
|
||||
|
||||
Custom tuples are lists of MuJoCo model elements, possibly including other tuples. They are not used by the
|
||||
simulator, but are available for specifying groups of elements that are needed for user code. For example, one can
|
||||
use tuples to define pairs of bodies for custom contact processing.
|
||||
|
||||
Keyframe
|
||||
^^^^^^^^
|
||||
|
||||
A keyframe is a snapshot of the simulation state variables. It contains the vectors of joint positions, joint
|
||||
velocities, actuator activations when present, and the simulation time. The model can contain a library of keyframes.
|
||||
They are useful for resetting the state of the system to a point of interest. Note that keyframes are not intended
|
||||
|
||||
Reference in New Issue
Block a user