diff --git a/doc/APIreference.rst b/doc/APIreference.rst index 9cad1c67..0dac539f 100644 --- a/doc/APIreference.rst +++ b/doc/APIreference.rst @@ -2736,10 +2736,10 @@ X Macros ^^^^^^^^ The X Macros are not needed in most user projects. They are used internally to allocate the model, and are also -available for users who know how to use this programming technique. See the header file -`mjxmacro.h `_ for the actual definitions. They are particularly useful in writing MuJoCo wrappers -for scripting languages, where dynamic structures matching the MuJoCo data structures need to be constructed -programmatically. +available for users who know how to use this programming technique. See the header file `mjxmacro.h +`_ for the actual definitions. They are +particularly useful in writing MuJoCo wrappers for scripting languages, where dynamic structures matching the MuJoCo +data structures need to be constructed programmatically. .. _MJOPTION_SCALARS: @@ -3238,12 +3238,11 @@ Numeric constants API functions ------------- -The main header `mujoco.h `_ exposes a very large number -of functions. However the functions that most users are likely to need are a small fraction. For example, -:ref:`simulate.cc ` which is as elaborate as a MuJoCo application is likely to get, calls around 40 -of these functions, while ``basic.cc`` calls around 20. The rest are explosed just in case someone has a use for -them. This includes us as users of MuJoCo -- we do our own work with the public library instead of relying on -internal builds. +The main header `mujoco.h `_ exposes a very large +number of functions. However the functions that most users are likely to need are a small fraction. For example, +:ref:`simulate.cc ` which is as elaborate as a MuJoCo application is likely to get, calls around 40 of these +functions, while ``basic.cc`` calls around 20. The rest are explosed just in case someone has a use for them. This +includes us as users of MuJoCo -- we do our own work with the public library instead of relying on internal builds. .. _Activation: diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst index 9136c239..52424030 100644 --- a/doc/XMLreference.rst +++ b/doc/XMLreference.rst @@ -79,12 +79,13 @@ MJCF Reference - The order of :ref:`joint ` elements within a :ref:`body ` matters because joint transformations are performed in sequence. -- The order of elements in a :ref:`spatial ` tendon matters because it determines the sequence of objects that - the tendon passes through or wraps around. +- The order of elements in a :ref:`spatial ` tendon matters because it determines the sequence of + objects that the tendon passes through or wraps around. - The order of repeated sections matters when the same attribute is set multiple times to different values. In that case the last setting takes effect for the entire model. - The order of multiple actuator shortcuts in the same defaults class matters, because each shortcut sets the - attributes of the single :ref:`general ` element in that defaults class, overriding the previous settings. + attributes of the single :ref:`general ` element in that defaults class, overriding the previous + settings. In the remainder of this chapter we describe all valid MJCF elements and their attributes. Some elements can be used in multiple contexts, in which case their meaning depends on the parent element. This is why we always show the parent as a @@ -165,10 +166,10 @@ any effect. The settings here are global and apply to the entire model. compiler converts degrees into radians, and mjModel always uses radians. For URDF models the parser sets this attribute to "radian" internally, regardless of the XML setting. :at:`fitaabb`: :at-val:`[false, true], "false"` - The compiler is able to replace a mesh with a geometric primitive fitted to that mesh; see :ref:`geom ` below. - If this attribute is "true", the fitting procedure uses the axis-aligned bounding box (aabb) of the mesh. Otherwise - it uses the equivalent-inertia box of the mesh. The type of geometric primitive used for fitting is specified - separately for each geom. + The compiler is able to replace a mesh with a geometric primitive fitted to that mesh; see :ref:`geom ` + below. If this attribute is "true", the fitting procedure uses the axis-aligned bounding box (aabb) of the mesh. + Otherwise it uses the equivalent-inertia box of the mesh. The type of geometric primitive used for fitting is + specified separately for each geom. :at:`eulerseq`: :at-val:`string, "xyz"` This attribute specifies the sequence of Euler rotations for all euler attributes of elements that have spatial frames, as explained in :ref:`COrientation`. This must be a string with exactly 3 @@ -365,9 +366,9 @@ adjust it properly through the XML. :at:`implicit` integrator. :at:`o_margin`: :at-val:`real, "0"` This attribute replaces the margin parameter of all active contact pairs when :ref:`Contact override ` is - enabled. Otherwise MuJoCo uses the element-specific margin attribute of :ref:`geom ` or :ref:`pair ` - depending on how the contact pair was generated. See also :ref:`Collision` in the Computation chapter. The related - gap parameter does not have a global override. + enabled. Otherwise MuJoCo uses the element-specific margin attribute of :ref:`geom ` or :ref:`pair + ` depending on how the contact pair was generated. See also :ref:`Collision` in the Computation + chapter. The related gap parameter does not have a global override. :at:`o_solref`, :at:`o_solimp` These attributes replace the solref and solimp parameters of all active contact pairs when contact override is enabled. See :ref:`CSolver` for details. @@ -377,9 +378,9 @@ adjust it properly through the XML. the Implicit-in-velocity Euler method. :at:`collision`: :at-val:`[all, predefined, dynamic], "all"` This attribute specifies which geom pairs should be checked for collision; recall :ref:`Collision` in the Computation - chapter. "predefined" means that only the explicitly-defined contact :ref:`pairs ` are checked. "dynamic" means - that only the contact pairs generated dynamically are checked. "all" means that the contact pairs from both sources - are checked. + chapter. "predefined" means that only the explicitly-defined contact :ref:`pairs ` are checked. + "dynamic" means that only the contact pairs generated dynamically are checked. "all" means that the contact pairs + from both sources are checked. :at:`cone`: :at-val:`[pyramidal, elliptic], "pyramidal"` The type of contact friction cone. Elliptic cones are a better model of the physical reality, but pyramidal cones sometimes make the solver faster and more robust. @@ -521,9 +522,9 @@ compilation. The size of the field mjData.userdata of mjData. This field should be used to store custom dynamic variables. See also :ref:`CUser`. :at:`nkey`: :at-val:`int, "0"` - The number of key frames allocated in mjModel is the larger of this value and the number of :ref:`key ` elements - below. Note that the interactive simulator has the ability to take snapshots of the system state and save them as key - frames. + The number of key frames allocated in mjModel is the larger of this value and the number of :ref:`key ` + elements below. Note that the interactive simulator has the ability to take snapshots of the system state and save + them as key frames. :at:`nuser_body`: :at-val:`int, "-1"` The number of custom user parameters added to the definition of each body. See also :ref:`User parameters `. The parameter values are set via the user attribute of the :ref:`body ` element. These values are not accessed @@ -605,15 +606,15 @@ is effectively a miscellaneous subsection. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This element specifies settings that affect the quality of the rendering. Larger values result in higher quality but -possibly slower speed. Note that :ref:`simulate.cc ` displays the frames per second (FPS). The target FPS is 60 Hz; if the -number shown in the visualizer is substantially lower, this means that the GPU is over-loaded and the visualization -should somehow be simplified. +possibly slower speed. Note that :ref:`simulate.cc ` displays the frames per second (FPS). The target FPS is +60 Hz; if the number shown in the visualizer is substantially lower, this means that the GPU is over-loaded and the +visualization should somehow be simplified. :at:`shadowsize`: :at-val:`int, "4096"` This attribute specifies the size of the square texture used for shadow mapping. Higher values result is smoother - shadows. The size of the area over which a :ref:`light ` can cast shadows also affects smoothness, so these - settings should be adjusted jointly. The default here is somewhat conservative. Most modern GPUs are able to handle - significantly larger textures without slowing down. + shadows. The size of the area over which a :ref:`light ` can cast shadows also affects smoothness, so + these settings should be adjusted jointly. The default here is somewhat conservative. Most modern GPUs are able to + handle significantly larger textures without slowing down. :at:`offsamples`: :at-val:`int, "4"` This attribute specifies the number of multi-samples for offscreen rendering. Larger values produce better anti-aliasing but can slow down the GPU. Set this to 0 to disable multi-sampling. Note that this attribute only @@ -836,17 +837,18 @@ parameters. runtime this value scales the solver cost and gradient used for early termination. :at:`meansize`: :at-val:`real, optional` If this attribute is specified, it replaces the value of ``mjModel.stat.meansize`` computed by the compiler. At - runtime this value multiplies the attributes of the :ref:`scale ` element above, and acts as their length - unit. If specific lengths are desired, it can be convenient to set :at:`meansize` to a round number like 1 or 0.01 so - that :ref:`scale ` values are in recognized length units. This is the only semantic of :at:`meansize` and - setting it has no other side-effect. The automatically computed value is heuristic, representing the average body - radius. The heuristic is based on geom sizes when present, the distances between joints when present, and the sizes - of the body equivalent inertia boxes. + runtime this value multiplies the attributes of the :ref:`scale ` element above, and acts as their + length unit. If specific lengths are desired, it can be convenient to set :at:`meansize` to a round number like 1 or + 0.01 so that :ref:`scale ` values are in recognized length units. This is the only semantic of + :at:`meansize` and setting it has no other side-effect. The automatically computed value is heuristic, representing + the average body radius. The heuristic is based on geom sizes when present, the distances between joints when + present, and the sizes of the body equivalent inertia boxes. :at:`extent`: :at-val:`real, optional` If this attribute is specified, it replaces the value of mjModel.stat.extent computed by the compiler. The computed value is half the side of the bounding box of the model in the initial configuration. At runtime this value is - multiplied by some of the attributes of the :ref:`map ` element above. When the model is first loaded, the free - camera's initial distance from the :at:`center` (see below) is 1.5 times the :at:`extent`. Must be strictly positive. + multiplied by some of the attributes of the :ref:`map ` element above. When the model is first loaded, + the free camera's initial distance from the :at:`center` (see below) is 1.5 times the :at:`extent`. Must be strictly + positive. :at:`center`: :at-val:`real(3), optional` If this attribute is specified, it replaces the value of mjModel.stat.center computed by the compiler. The computed value is the center of the bounding box of the entire model in the initial configuration. This 3D vector is used to @@ -962,59 +964,59 @@ if omitted. :el-prefix:`default/` **motor** (?) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -| This and the next three elements set the attributes of the :ref:`general ` element using :ref:`Actuator - shortcuts `. It does not make sense to use more than one such shortcut in the same defaults - class, because they set the same underlying attributes, replacing any previous settings. -| All :ref:`motor ` attributes are available here except: name, class, joint, jointinparent, site, tendon, - slidersite, cranksite. +This and the next three elements set the attributes of the :ref:`general ` element using +:ref:`Actuator shortcuts `. It does not make sense to use more than one such shortcut in the same defaults +class, because they set the same underlying attributes, replacing any previous settings. All +:ref:`motor ` attributes are available here except: name, class, joint, jointinparent, site, tendon, +slidersite, cranksite. .. _default-position: :el-prefix:`default/` **position** (?) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All :ref:`position ` attributes are available here except: name, class, joint, jointinparent, site, tendon, -slidersite, cranksite. +All :ref:`position ` attributes are available here except: name, class, joint, jointinparent, site, +tendon, slidersite, cranksite. .. _default-velocity: :el-prefix:`default/` **velocity** (?) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All :ref:`velocity ` attributes are available here except: name, class, joint, jointinparent, site, tendon, -slidersite, cranksite. +All :ref:`velocity ` attributes are available here except: name, class, joint, jointinparent, site, +tendon, slidersite, cranksite. .. _default-intvelocity: :el-prefix:`default/` **intvelocity** (?) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All :ref:`intvelocity ` attributes are available here except: name, class, joint, jointinparent, site, tendon, -slidersite, cranksite. +All :ref:`intvelocity ` attributes are available here except: name, class, joint, jointinparent, +site, tendon, slidersite, cranksite. .. _default-damper: :el-prefix:`default/` **damper** (?) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All :ref:`damper ` attributes are available here except: name, class, joint, jointinparent, site, tendon, -slidersite, cranksite. +All :ref:`damper ` attributes are available here except: name, class, joint, jointinparent, site, +tendon, slidersite, cranksite. .. _default-cylinder: :el-prefix:`default/` **cylinder** (?) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All :ref:`cylinder ` attributes are available here except: name, class, joint, jointinparent, site, tendon, -slidersite, cranksite. +All :ref:`cylinder ` attributes are available here except: name, class, joint, jointinparent, site, +tendon, slidersite, cranksite. .. _default-muscle: :el-prefix:`default/` **muscle** (?) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All :ref:`muscle ` attributes are available here except: name, class, joint, jointinparent, site, tendon, -slidersite, cranksite. +All :ref:`muscle ` attributes are available here except: name, class, joint, jointinparent, site, +tendon, slidersite, cranksite. :el-prefix:`default/` **adhesion** (?) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1156,7 +1158,8 @@ chapter. stretched. For planes this is not an issue because the plane is always normal to the local Z axis. For height fields the sides enclosing the terrain map appear stretched, but in that case the effect is actually desirable. 2d textures can be rectangular, unlike the sides of cube textures which must be square. The scaling can be controlled with the - texrepeat attribute of :ref:`material `. The data can be loaded from a singlefile or created procedurally. + texrepeat attribute of :ref:`material `. The data can be loaded from a singlefile or created + procedurally. :at:`file`: :at-val:`string, optional` If this attribute is specified, and the builtin attribute below is set to "none", the texture data is loaded from a single file. See the texturedir attribute of :ref:`compiler ` regarding the file path. @@ -1361,7 +1364,8 @@ MSH file format Poorly designed meshes can display rendering artifacts. In particular, the shadow mapping mechanism relies on having some distance between front and back-facing triangle faces. If the faces are repeated, with opposite normals as determined by the vertex order in each triangle, this causes shadow aliasing. The solution is to remove the repeated -faces (which can be done in MeshLab) or use a better designed mesh. Flipped faces are checked by MuJoCo for meshes specified as OBJ or XML and an error message is returned. +faces (which can be done in MeshLab) or use a better designed mesh. Flipped faces are checked by MuJoCo for meshes +specified as OBJ or XML and an error message is returned. The size of the mesh is determined by the 3D coordinates of the vertex data in the mesh file, multiplied by the components of the :at:`scale` attribute below. Scaling is applied separately for each coordinate axis. Note that @@ -1384,14 +1388,14 @@ whose origin is not inside the mesh. In contrast, MuJoCo expects the origin of a geometric center of the shape. We resolve this discrepancy by pre-processing the mesh in the compiler, so that it is centered around (0,0,0) and its principal axes of inertia are the coordinate axes. We also save the translation and rotation offsets needed to achieve such alignment. These offsets are then applied to the referencing geom's position and -orientation; see also :at:`mesh` attribute of :ref:`geom ` below. Fortunately most meshes used in robot models are -designed in a coordinate frame centered at the joint. This makes the corresponding MJCF model intuitive: we set the body -frame at the joint, so that the joint position is (0,0,0) in the body frame, and simply reference the mesh. Below is an -MJCF model fragment of a forearm, containing all the information needed to put the mesh where one would expect it to be. -The body position is specified relative to the parent body, namely the upper arm (not shown). It is offset by 35 cm -which is the typical length of the human upper arm. If the mesh vertex data were not designed in the above convention, -we would have to use the geom position and orientation (or the new refpos, refquat mechanism) to compensate, but in -practice this is rarely needed. +orientation; see also :at:`mesh` attribute of :ref:`geom ` below. Fortunately most meshes used in robot +models are designed in a coordinate frame centered at the joint. This makes the corresponding MJCF model intuitive: we +set the body frame at the joint, so that the joint position is (0,0,0) in the body frame, and simply reference the mesh. +Below is an MJCF model fragment of a forearm, containing all the information needed to put the mesh where one would +expect it to be. The body position is specified relative to the parent body, namely the upper arm (not shown). It is +offset by 35 cm which is the typical length of the human upper arm. If the mesh vertex data were not designed in the +above convention, we would have to use the geom position and orientation (or the new refpos, refquat mechanism) to +compensate, but in practice this is rarely needed. .. code-block:: xml @@ -1404,9 +1408,12 @@ practice this is rarely needed. -The inertial computation mentioned above is part of an algorithm used not only to center and align the mesh, but also -to infer the mass and inertia of the body to which it is attached. This is done by computing the centroid of the -triangle faces, connecting each face with the centroid to form a triangular pyramid, computing the mass and signed inertia of all pyramids (considered solid or hollow if :at:`shellinertia` is true) and accumulating them. The sign ensures that pyramids on the outside of the surfaces are subtracted, as it can occur with concave geometries. This algorithm can be found in section 1.3.8 of Computational Geometry in C (Second Edition) by Joseph O'Rourke. +The inertial computation mentioned above is part of an algorithm used not only to center and align the mesh, but also to +infer the mass and inertia of the body to which it is attached. This is done by computing the centroid of the triangle +faces, connecting each face with the centroid to form a triangular pyramid, computing the mass and signed inertia of all +pyramids (considered solid or hollow if :at:`shellinertia` is true) and accumulating them. The sign ensures that +pyramids on the outside of the surfaces are subtracted, as it can occur with concave geometries. This algorithm can be +found in section 1.3.8 of Computational Geometry in C (Second Edition) by Joseph O'Rourke. The full list of processing steps applied by the compiler to each mesh is as follows: @@ -1576,12 +1583,12 @@ This element defines a bone of the skin. The bone is a regular MuJoCo body which :el-prefix:`asset/` **material** (*) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This element creates a material asset. It can be referenced from :ref:`skins `, :ref:`geoms `, :ref:`sites -` and :ref:`tendons ` to set their appearance. Note that all these elements also have a local rgba -attribute, which is more convenient when only colors need to be adjusted, because it does not require creating materials -and referencing them. Materials are useful for adjusting appearance properties beyond color. However once a material is -created, it is more natural the specify the color using the material, so that all appearance properties are grouped -together. +This element creates a material asset. It can be referenced from :ref:`skins `, :ref:`geoms `, +:ref:`sites ` and :ref:`tendons ` to set their appearance. Note that all these elements also have a +local rgba attribute, which is more convenient when only colors need to be adjusted, because it does not require +creating materials and referencing them. Materials are useful for adjusting appearance properties beyond color. However +once a material is created, it is more natural the specify the color using the material, so that all appearance +properties are grouped together. :at:`name`: :at-val:`string, required` Name of the material, used for referencing. @@ -1637,9 +1644,9 @@ together. This element is used to construct the :ref:`kinematic tree ` via nesting. The element :el:`worldbody` is used for the top-level body, while the element :el:`body` is used for all other bodies. The top-level body is a restricted type -of body: it cannot have child elements :ref:`inertial ` and :ref:`joint `, and also cannot have any -attributes. It corresponds to the origin of the world frame, within which the rest of the kinematic tree is defined. Its -body name is automatically defined as "world". +of body: it cannot have child elements :ref:`inertial ` and :ref:`joint `, and also cannot +have any attributes. It corresponds to the origin of the world frame, within which the rest of the kinematic tree is +defined. Its body name is automatically defined as "world". :at:`name`: :at-val:`string, optional` Name of the body. @@ -1661,9 +1668,9 @@ body name is automatically defined as "world". `. In local coordinates, if the body position is left undefined it defaults to (0,0,0). In global coordinates, an undefined body position is inferred by the compiler through the following steps: - #. If the inertial frame is not defined via the :ref:`inertial ` element, it is inferred from the geoms - attached to the body. If there are no geoms, the inertial frame remains undefined. This step is applied in both - local and global coordinates. + #. If the inertial frame is not defined via the :ref:`inertial ` element, it is inferred from the + geoms attached to the body. If there are no geoms, the inertial frame remains undefined. This step is applied in + both local and global coordinates. #. If both the body frame and the inertial frame are undefined, a compile error is generated. #. If one of these two frames is defined and the other is not, the defined one is copied into the undefined one. At this point both frames are defined, in global coordinates. @@ -1839,10 +1846,10 @@ an XML shortcut for -While this joint can evidently be created with the :ref:`joint ` element, default joint settings could affect it. -This is usually undesirable as physical free bodies do not have nonzero stiffness, damping, friction or armature. To -avoid this complication, the :el:`freejoint` element was introduced, ensuring joint defaults are *not inherited*. If -the XML model is saved, it will appear as a regular joint of type :at:`free`. +While this joint can evidently be created with the :ref:`joint ` element, default joint settings could +affect it. This is usually undesirable as physical free bodies do not have nonzero stiffness, damping, friction or +armature. To avoid this complication, the :el:`freejoint` element was introduced, ensuring joint defaults are *not +inherited*. If the XML model is saved, it will appear as a regular joint of type :at:`free`. :at:`name`: :at-val:`string, optional` Name of the joint. @@ -1874,38 +1881,38 @@ helps clarify the role of bodies and geoms in MuJoCo. :at:`class`: :at-val:`string, optional` Defaults class for setting unspecified attributes. :at:`type`: :at-val:`[plane, hfield, sphere, capsule, ellipsoid, cylinder, box, mesh], "sphere"` - Type of geometric shape. The keywords have the following meaning: - The **plane** type defines a plane which is infinite for collision detection purposes. It can only be attached to the - world body or static children of the world. The plane passes through a point specified via the pos attribute. It is - normal to the Z axis of the geom's local frame. The +Z direction corresponds to empty space. Thus the position and - orientation defaults of (0,0,0) and (1,0,0,0) would create a ground plane at Z=0 elevation, with +Z being the - vertical direction in the world (which is MuJoCo's convention). Since the plane is infinite, it could have been - defined using any other point in the plane. The specified position however has additional meaning with regard to - rendering. If either of the first two size parameters are positive, the plane is rendered as a rectangle of finite - size (in the positive dimensions). This rectangle is centered at the specified position. Three size parameters are - required. The first two specify the half-size of the rectangle along the X and Y axes. The third size parameter is - unusual: it specifies the spacing between the grid subdivisions of the plane for rendering purposes. The subdivisions - are revealed in wireframe rendering mode, but in general they should not be used to paint a grid over the ground - plane (textures should be used for that purpose). Instead their role is to improve lighting and shadows, similar to - the subdivisions used to render boxes. When planes are viewed from the back, the are automatically made - semi-transparent. Planes and the +Z faces of boxes are the only surfaces that can show reflections, if the - :ref:`material ` applied to the geom has positive reflection. To render an infinite plane, set the first - two size parameters to zero. + Type of geometric shape. The keywords have the following meaning: The **plane** type defines a plane which is + infinite for collision detection purposes. It can only be attached to the world body or static children of the world. + The plane passes through a point specified via the pos attribute. It is normal to the Z axis of the geom's local + frame. The +Z direction corresponds to empty space. Thus the position and orientation defaults of (0,0,0) and + (1,0,0,0) would create a ground plane at Z=0 elevation, with +Z being the vertical direction in the world (which is + MuJoCo's convention). Since the plane is infinite, it could have been defined using any other point in the plane. The + specified position however has additional meaning with regard to rendering. If either of the first two size + parameters are positive, the plane is rendered as a rectangle of finite size (in the positive dimensions). This + rectangle is centered at the specified position. Three size parameters are required. The first two specify the half- + size of the rectangle along the X and Y axes. The third size parameter is unusual: it specifies the spacing between + the grid subdivisions of the plane for rendering purposes. The subdivisions are revealed in wireframe rendering mode, + but in general they should not be used to paint a grid over the ground plane (textures should be used for that + purpose). Instead their role is to improve lighting and shadows, similar to the subdivisions used to render boxes. + When planes are viewed from the back, the are automatically made semi-transparent. Planes and the +Z faces of boxes + are the only surfaces that can show reflections, if the :ref:`material ` applied to the geom has + positive reflection. To render an infinite plane, set the first two size parameters to zero. The **hfield** type defines a height field geom. The geom must reference the desired height field asset with the hfield attribute below. The position and orientation of the geom set the position and orientation of the height field. The size of the geom is ignored, and the size parameters of the height field asset are used instead. See the - description of the :ref:`hfield ` element. Similar to planes, height field geoms can only be attached to the - world body or to static children of the world. + description of the :ref:`hfield ` element. Similar to planes, height field geoms can only be attached + to the world body or to static children of the world. The **sphere** type defines a sphere. This and the next four types correspond to built-in geometric primitives. These - primitives are treated as analytic surfaces for collision detection purposes, in many cases relying on custom - pair-wise collision routines. Models including only planes, spheres, capsules and boxes are the most efficient in - terms of collision detection. Other geom types invoke the general-purpose convex collider. The sphere is centered at - the geom's position. Only one size parameter is used, specifying the radius of the sphere. Rendering of geometric - primitives is done with automatically generated meshes whose density can be adjusted via :ref:`quality `. - The sphere mesh is triangulated along the lines of latitude and longitude, with the Z axis passing through the north - and south pole. This can be useful in wireframe mode for visualizing frame orientation. + primitives are treated as analytic surfaces for collision detection purposes, in many cases relying on custom pair- + wise collision routines. Models including only planes, spheres, capsules and boxes are the most efficient in terms of + collision detection. Other geom types invoke the general-purpose convex collider. The sphere is centered at the + geom's position. Only one size parameter is used, specifying the radius of the sphere. Rendering of geometric + primitives is done with automatically generated meshes whose density can be adjusted via + :ref:`quality `. The sphere mesh is triangulated along the lines of latitude and longitude, + with the Z axis passing through the north and south pole. This can be useful in wireframe mode for visualizing frame + orientation. The **capsule** type defines a capsule, which is a cylinder capped with two half-spheres. It is oriented along the Z axis of the geom's frame. When the geom frame is specified in the usual way, two size parameters are required: the @@ -2214,29 +2221,29 @@ the direction specified by the dir attribute. It does not have a full spatial fr :at:`class`: :at-val:`string, optional` Defaults class for setting unspecified attributes. :at:`mode`: :at-val:`[fixed, track, trackcom, targetbody, targetbodycom], "fixed"` - This is identical to the mode attribute of :ref:`camera ` above. It specifies the how the light position and - orientation in world coordinates are computed in forward kinematics (which in turn determine what the light + This is identical to the mode attribute of :ref:`camera ` above. It specifies the how the light position + and orientation in world coordinates are computed in forward kinematics (which in turn determine what the light illuminates). :at:`target`: :at-val:`string, optional` - This is identical to the target attribute of :ref:`camera ` above. It specifies which body should be targeted - in "targetbody" and "targetbodycom" modes. + This is identical to the target attribute of :ref:`camera ` above. It specifies which body should be + targeted in "targetbody" and "targetbodycom" modes. :at:`directional`: :at-val:`[false, true], "false"` The light is directional if this attribute is "true", otherwise it is a spotlight. :at:`castshadow`: :at-val:`[false, true], "true"` If this attribute is "true" the light will cast shadows. More precisely, the geoms illuminated by the light will cast shadows, however this is a property of lights rather than geoms. Since each shadow-casting light causes one extra rendering pass through all geoms, this attribute should be used with caution. Higher quality of the shadows is - achieved by increasing the value of the shadowsize attribute of :ref:`quality `, as well as positioning - spotlights closer to the surface on which shadows appear, and limiting the volume in which shadows are cast. For - spotlights this volume is a cone, whose angle is the cutoff attribute below multiplied by the shadowscale attribute - of :ref:`map `. For directional lights this volume is a box, whose half-sizes in the directions orthogonal to - the light are the model extent multiplied by the shadowclip attribute of :ref:`map `. The model extent is - computed by the compiler but can also be overridden by specifying the extent attribute of :ref:`statistic - `. Internally the shadow-mapping mechanism renders the scene from the light viewpoint (as if it were a - camera) into a depth texture, and then renders again from the camera viewpoint, using the depth texture to create - shadows. The internal rendering pass uses the same near and far clipping planes as regular rendering, i.e., these - clipping planes bound the cone or box shadow volume in the light direction. As a result, some shadows (especially - those very close to the light) may be clipped. + achieved by increasing the value of the shadowsize attribute of :ref:`quality `, as well as + positioning spotlights closer to the surface on which shadows appear, and limiting the volume in which shadows are + cast. For spotlights this volume is a cone, whose angle is the cutoff attribute below multiplied by the shadowscale + attribute of :ref:`map `. For directional lights this volume is a box, whose half-sizes in the directions + orthogonal to the light are the model extent multiplied by the shadowclip attribute of :ref:`map `. The + model extent is computed by the compiler but can also be overridden by specifying the extent attribute of + :ref:`statistic `. Internally the shadow-mapping mechanism renders the scene from the light viewpoint (as + if it were a camera) into a depth texture, and then renders again from the camera viewpoint, using the depth texture + to create shadows. The internal rendering pass uses the same near and far clipping planes as regular rendering, i.e., + these clipping planes bound the cone or box shadow volume in the light direction. As a result, some shadows + (especially those very close to the light) may be clipped. :at:`active`: :at-val:`[false, true], "true"` The light is active if this attribute is "true". This can be used at runtime to turn lights on and off. :at:`pos`: :at-val:`real(3), "0 0 0"` diff --git a/doc/changelog.rst b/doc/changelog.rst index 83d212ab..370e4748 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -98,8 +98,9 @@ General :height: 150px #. Cartesian 6D end-effector control is now possible by adding a reference site to actuators with :at:`site` - transmission. See description of new :at:`refsite` attribute in the :ref:`actuator` documentation and - `refsite.xml `_ example model. + transmission. See description of new :at:`refsite` attribute in the :ref:`actuator` documentation + and `refsite.xml `_ example model. + #. Added :at:`autolimits` compiler option. If ``true``, joint and tendon :at:`limited` attributes and actuator :at:`ctrllimited`, :at:`forcelimited` and :at:`actlimited` attributes will automatically be set to ``true`` if the corresponding range *is defined* and ``false`` otherwise. @@ -162,7 +163,8 @@ General #. Added visualisation groups to skins. #. Added actuator visualisation for ``free`` and ``ball`` joints and for actuators with ``site`` transmission. #. Added visualisation for actuator activations. -#. Added ```` actuator shortcut for "integrated velocity" actuators, documented :ref:`here `. +#. Added ```` actuator shortcut for "integrated velocity" actuators, documented + :ref:`here `. #. Added ```` actuator shortcut for active-damping actuators, documented :ref:`here `. #. ``mju_rotVecMat`` and ``mju_rotVecMatT`` now support in-place multiplication. #. ``mjData.ctrl`` values are no longer clamped in-place, remain untouched by the engine. @@ -231,11 +233,12 @@ General #. Added ``implicit`` integrator. Using the analytic derivatives above, a new implicit-in-velocity integrator was added. This integrator lies between the Euler and Runge Kutta integrators in terms of both stability and computational cost. It is most useful for models which use fluid drag (e.g. for flying or swimming) and for models which use - :ref:`velocity actuators`. For more details, see the :ref:`Numerical Integration` section. + :ref:`velocity actuators`. For more details, see the :ref:`Numerical Integration` + section. -#. Added :at:`actlimited` and :at:`actrange` attributes to :ref:`general actuators`, for clamping actuator - internal states (activations). This clamping is useful for integrated-velocity actuators, see the :ref:`Activation - clamping ` section for details. +#. Added :at:`actlimited` and :at:`actrange` attributes to :ref:`general actuators`, for clamping + actuator internal states (activations). This clamping is useful for integrated-velocity actuators, see the + :ref:`Activation clamping ` section for details. #. ``mjData`` fields ``qfrc_unc`` (unconstrained forces) and ``qacc_unc`` (unconstrained accelerations) were renamed ``qfrc_smooth`` and ``qacc_smooth``, respectively. While "unconstrained" is precise, "smooth" is more intelligible @@ -245,7 +248,8 @@ General other open source projects. Developers are encouraged to include MuJoCo public headers in their own codebase via ``#include ``. -#. The default shadow resolution specified by the :ref:`shadowsize` attribute was increased from 1024 to 4096. +#. The default shadow resolution specified by the :ref:`shadowsize` attribute was increased from 1024 to + 4096. #. Saved XMLs now use 2-space indents. @@ -403,14 +407,15 @@ General #. Increased the maximum number of lights in an :ref:`mjvScene` from 8 to 100. -#. Saved XML files only contain explicit :ref:`inertial ` elements if the original XML included them. Inertias - that were automatically inferred by the compiler's :ref:`inertiafromgeom ` mechanism remain unspecified. +#. Saved XML files only contain explicit :ref:`inertial ` elements if the original XML included them. + Inertias that were automatically inferred by the compiler's :ref:`inertiafromgeom ` mechanism remain + unspecified. #. User-selected geoms are always rendered as opaque. This is useful in interactive visualizers. -#. Static geoms now respect their :ref:`geom group` for visualisation. Until this change rendering of static geoms - could only be toggled using the :ref:`mjVIS_STATIC` visualisation flag . After this change, both the geom - group and the visualisation flag need to be enabled for the geom to be rendered. +#. Static geoms now respect their :ref:`geom group` for visualisation. Until this change rendering of static + geoms could only be toggled using the :ref:`mjVIS_STATIC` visualisation flag . After this change, both + the geom group and the visualisation flag need to be enabled for the geom to be rendered. #. Pointer parameters in function declarations in :ref:`mujoco.h` that are supposed to represent fixed-length arrays are now spelled as arrays with extents, e.g. ``mjtNum quat[4]`` rather than ``mjtNum* quat``. From the @@ -481,9 +486,9 @@ Bug Fixes :ref:`weld ` constraints. .. note:: - Forces generated by :ref:`spatial tendons ` which are outside the kinematic tree (i.e., between bodies - which have no ancestral relationship) are still not taken into account by force and torque sensors. This remains a - future work item. + Forces generated by :ref:`spatial tendons ` which are outside the kinematic tree (i.e., between + bodies which have no ancestral relationship) are still not taken into account by force and torque sensors. This + remains a future work item. Code samples ^^^^^^^^^^^^ @@ -510,11 +515,11 @@ Binary build 15. MacOS packaging. We now ship Universal binaries that natively support both Apple Silicon and Intel CPUs. - a. MuJoCo library is now packaged as a - `Framework Bundle `_, - allowing it to be incorporated more easily into Xcode projects (including Swift projects). Developers are - encouraged to compile and link against MuJoCo using the ``-framework mujoco`` flag, however all header files and - the ``libmujoco.2.1.1.dylib`` library can still be directly accessed inside the framework. + a. MuJoCo library is now packaged as a `Framework Bundle + `_, allowing it to be incorporated more easily into Xcode projects (including Swift projects). Developers + are encouraged to compile and link against MuJoCo using the ``-framework mujoco`` flag, however all header files + and the ``libmujoco.2.1.1.dylib`` library can still be directly accessed inside the framework. #. Sample applications are now packaged into an Application Bundle called ``MuJoCo.app``. When launched via GUI, the bundle launches the ``simulate`` executable. Other precompiled sample programs are shipped inside that bundle (in ``MuJoCo.app/Contents/MacOS``) and can be launched via command line. diff --git a/doc/computation.rst b/doc/computation.rst index 25de8267..a2d6b6bf 100644 --- a/doc/computation.rst +++ b/doc/computation.rst @@ -267,8 +267,8 @@ is attached; the possible attachment object types are :at:`joint`, :at:`tendon`, :at:`slider-crank`, :at:`site`, and :at:`body`. The :at:`joint` and :at:`tendon` transmission types act as expected and correspond to the actuator applying forces or - torques to the target object. Ball joints are special, see the :at:`joint` documentation in :ref:`actuator` - reference for more details. + torques to the target object. Ball joints are special, see the :at:`joint` documentation in + :ref:`actuator` reference for more details. The :at:`jointinparent` transmission is unique to ball and free joint and asserts that rotation should be measured in the parent rather than child frame. @@ -362,9 +362,9 @@ with MuJoCo's operation as long as such user forces depend only on position and MuJoCo can compute two types of passive forces: spring-dampers in joints and tendons, and fluid dynamics. When Euler integration is used, joint damping is integrated implicitly (by modifying the inertia matrix internally) which significantly increases stability. Thus, even though damping can be alternatively modeled as an actuator property, it is -better to model it as a joint property. Note also the XML :ref:`joint ` attribute springdamper which automates -the creation of mass-spring-dampers with desired time constants and damping ratios; in that case the compiler computes -the stiffness and damping coefficients of the joint by taking the joint inertia into account. +better to model it as a joint property. Note also the XML :ref:`joint ` attribute springdamper which +automates the creation of mass-spring-dampers with desired time constants and damping ratios; in that case the compiler +computes the stiffness and damping coefficients of the joint by taking the joint inertia into account. Proper simulation of fluid dynamics is beyond the scope of MuJoCo, and would be too slow for the applications we aim to facilitate. Nevertheless we provide a phenomenological model which is sufficient for simulating behaviors such as flying @@ -1395,14 +1395,14 @@ checked in detail. The decision process involves two stages: generation and filt Generation First we generate a list of candidate geom pairs in one of two ways: "pair" or "dynamic". The user can also specify "all" which merges both sources (and is the default). This is done via the setting ``mjModel.opt.collision``. "Pair" - refers to an explicit list of geom pairs defined with the :ref:`pair ` element in MJCF. It gives the user full - control, however it is a static mechanism (independent of the spatial arrangement of the geoms at runtime) and can be - tedious for large models. It is normally used to supplement the output of the "dynamic" mechanism. Dynamic generation - works with bodies rather than geoms; when a body pair is included this means that all geoms attached to one body can - collide with all geoms attached to the other body. The body pairs are generated via broad-phase collision detection - based on a modified sweep-and-prune algorithm. The modification is that the axis for sorting is chosen as the - principal eigenvector of the covariance matrix of all geom centers - which maximizes the spread. If broad-phase - collision detection is disabled by the user, all body pairs are included in this step. + refers to an explicit list of geom pairs defined with the :ref:`pair ` element in MJCF. It gives the + user full control, however it is a static mechanism (independent of the spatial arrangement of the geoms at runtime) + and can be tedious for large models. It is normally used to supplement the output of the "dynamic" mechanism. Dynamic + generation works with bodies rather than geoms; when a body pair is included this means that all geoms attached to + one body can collide with all geoms attached to the other body. The body pairs are generated via broad-phase + collision detection based on a modified sweep-and-prune algorithm. The modification is that the axis for sorting is + chosen as the principal eigenvector of the covariance matrix of all geom centers - which maximizes the spread. If + broad-phase collision detection is disabled by the user, all body pairs are included in this step. Finally, the user can explicitly exclude certain body pairs using the :ref:`exclude ` element in MJCF. Exclusion is applied when "dynamic" or "all" are selected, but not when "pair" is selected. At the end of diff --git a/doc/modeling.rst b/doc/modeling.rst index dcfa3423..a283cd53 100644 --- a/doc/modeling.rst +++ b/doc/modeling.rst @@ -103,16 +103,17 @@ special and is called :el:`worldbody`. This tree organization is in contrast wit links and then connects them with joints that specify a child and a parent link. In MJCF the child body is literally a child of the parent body, in the sense of XML. -When a :ref:`joint ` is defined inside a body, its function is not to connect the parent and child but rather to -create motion degrees of freedom between them. If no joints are defined within a given body, that body is welded to its -parent. A body in MJCF can contain multiple joints, thus there is no need to introduce dummy bodies for creating -composite joints. Instead simply define all the primitive joints that form the desired composite joint within the same -body. For example, two sliders and one hinge can be used to model a body moving in a plane. +When a :ref:`joint ` is defined inside a body, its function is not to connect the parent and child but +rather to create motion degrees of freedom between them. If no joints are defined within a given body, that body is +welded to its parent. A body in MJCF can contain multiple joints, thus there is no need to introduce dummy bodies for +creating composite joints. Instead simply define all the primitive joints that form the desired composite joint within +the same body. For example, two sliders and one hinge can be used to model a body moving in a plane. -Other MJCF elements can be defined within the tree created by nested body elements, in particular :ref:`joint `, -:ref:`geom `, :ref:`site `, :ref:`camera `, :ref:`light `. When an element is defined within -a body, it is fixed to the local frame of that body and always moves with it. Elements that refer to multiple bodies, or -do not refer to bodies at all, are defined in separate sections outside the kinematic tree. +Other MJCF elements can be defined within the tree created by nested body elements, in particular +:ref:`joint `, :ref:`geom `, :ref:`site `, :ref:`camera `, :ref:`light +`. When an element is defined within a body, it is fixed to the local frame of that body and always moves +with it. Elements that refer to multiple bodies, or do not refer to bodies at all, are defined in separate sections +outside the kinematic tree. .. _CDefault: @@ -302,8 +303,8 @@ approximately .. math:: a_1 + d \cdot (b v + k r) = (1 - d)\cdot a_0 -Again, the parameters that are under the user's control are :math:`d, b, k`. The remaining quantities are functions of the -system state and are computed automatically at each time step. +Again, the parameters that are under the user's control are :math:`d, b, k`. The remaining quantities are functions of +the system state and are computed automatically at each time step. First we explain the setting of the impedance :math:`d`. Recall that :math:`d` must lie between 0 and 1; internally MuJoCo clamps it to the range [:ref:`mjMINIMP mjMAXIMP `] which is currently set to [0.0001 0.9999]. It @@ -459,12 +460,12 @@ User parameters A number of MJCF elements have the optional attribute :at:`user`, which defines a custom element-specific parameter array. This interacts with the corresponding "nuser_XXX" attribute of the :ref:`size ` element. If for example we set :at:`nuser_geom` to 5, then every geom in mjModel will have a custom array of 5 real-valued parameters. These geom- -specific parameters are either defined in the MJCF file via the :at:`user` attribute of :ref:`geom `, or set to 0 -by the compiler if this attribute is omitted. The default value of all "nuser_XXX" attributes is -1, which instructs the -compiler to automatically set this value to the length of the maximum associated :at:`user` attribute defined in the -model. MuJoCo does not use these parameters in any internal computations; instead they are available for custom -computations. The parser allows arrays of arbitrary length in the XML, and the compiler later resizes them to length -nuser_XXX. +specific parameters are either defined in the MJCF file via the :at:`user` attribute of :ref:`geom `, or set +to 0 by the compiler if this attribute is omitted. The default value of all "nuser_XXX" attributes is -1, which +instructs the compiler to automatically set this value to the length of the maximum associated :at:`user` attribute +defined in the model. MuJoCo does not use these parameters in any internal computations; instead they are available for +custom computations. The parser allows arrays of arbitrary length in the XML, and the compiler later resizes them to +length nuser_XXX. Some element-specific parameters that are normally used in internal computations can also be used in custom computations. This is done by installing user callbacks which override parts of the simulation pipeline. For example, @@ -493,9 +494,9 @@ There is also a second Noslip solver, which is a post-processing step enabled by noslip iterations. All these algorithm settings can be specified in the :ref:`option