diff --git a/CMakeLists.txt b/CMakeLists.txt index 57b9ddd3..eea180c0 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -28,7 +28,7 @@ set(MSVC_INCREMENTAL_DEFAULT ON) project( mujoco - VERSION 3.1.2 + VERSION 3.1.3 DESCRIPTION "MuJoCo Physics Simulator" HOMEPAGE_URL "https://mujoco.org" ) diff --git a/cmake/MujocoDependencies.cmake b/cmake/MujocoDependencies.cmake index 86c860a2..92341a67 100644 --- a/cmake/MujocoDependencies.cmake +++ b/cmake/MujocoDependencies.cmake @@ -39,12 +39,12 @@ set(MUJOCO_DEP_VERSION_qhull CACHE STRING "Version of `qhull` to be fetched." ) set(MUJOCO_DEP_VERSION_Eigen3 - 454f89af9d6f3525b1df5f9ef9c86df58bf2d4d3 + 7fd7a3f946e5ac152d28dad388cff8bfa1026925 CACHE STRING "Version of `Eigen3` to be fetched." ) set(MUJOCO_DEP_VERSION_abseil - fb3621f4f897824c0dbe0615fa94543df6192f30 # LTS 20230802.1 + 4a2c63365eff8823a5221db86ef490e828306f9d # LTS 20240116.0 CACHE STRING "Version of `abseil` to be fetched." ) diff --git a/dist/mujoco.rc b/dist/mujoco.rc index 2c2d58c6..eb57afca 100644 --- a/dist/mujoco.rc +++ b/dist/mujoco.rc @@ -1,6 +1,6 @@ 1 VERSIONINFO -FILEVERSION 3,1,2,0 -PRODUCTVERSION 3,1,2,0 +FILEVERSION 3,1,3,0 +PRODUCTVERSION 3,1,3,0 FILEOS 0x4 FILETYPE 0x1 { @@ -9,9 +9,9 @@ FILETYPE 0x1 BLOCK "040904b0" { VALUE "ProductName", "MuJoCo" - VALUE "ProductVersion", "3.1.2" + VALUE "ProductVersion", "3.1.3" VALUE "FileDescription", "MuJoCo" - VALUE "FileVersion", "3.1.2" + VALUE "FileVersion", "3.1.3" VALUE "InternalName", "mujoco.dll" VALUE "OriginalFilename", "mujoco.dll" VALUE "CompanyName", "Google DeepMind" diff --git a/dist/simulate.rc b/dist/simulate.rc index 255cb59c..c6eead9f 100644 --- a/dist/simulate.rc +++ b/dist/simulate.rc @@ -1,8 +1,8 @@ MUJOCO ICON "mujoco.ico" 1 VERSIONINFO -FILEVERSION 3,1,2,0 -PRODUCTVERSION 3,1,2,0 +FILEVERSION 3,1,3,0 +PRODUCTVERSION 3,1,3,0 FILEOS 0x4 FILETYPE 0x1 { @@ -11,9 +11,9 @@ FILETYPE 0x1 BLOCK "040904b0" { VALUE "ProductName", "MuJoCo" - VALUE "ProductVersion", "3.1.2" + VALUE "ProductVersion", "3.1.3" VALUE "FileDescription", "MuJoCo" - VALUE "FileVersion", "3.1.2" + VALUE "FileVersion", "3.1.3" VALUE "InternalName", "simulate.exe" VALUE "OriginalFilename", "simulate.exe" VALUE "CompanyName", "Google DeepMind" diff --git a/doc/APIreference/APIglobals.rst b/doc/APIreference/APIglobals.rst index 483383c4..53ea109f 100644 --- a/doc/APIreference/APIglobals.rst +++ b/doc/APIreference/APIglobals.rst @@ -489,7 +489,7 @@ shown in the table below. Their names are in the format ``mjKEY_XXX``. They corr - 1000 - Maximum number of textures allowed. Defined in `mjrender.h `_. - * - ``mjMAXTHREADS`` + * - ``mjMAXTHREAD`` - 128 - Maximum number OS threads that can be used in a thread pool. Defined in `mjthread.h `_. @@ -522,7 +522,7 @@ shown in the table below. Their names are in the format ``mjKEY_XXX``. They corr - Maximum number of UI rectangles. Defined in `mjui.h `_. * - ``mjVERSION_HEADER`` - - 312 + - 313 - The version of the MuJoCo headers; changes with every release. This is an integer equal to 100x the software version, so 210 corresponds to version 2.1. Defined in mujoco.h. The API function :ref:`mj_version` returns a number with the same meaning but for the compiled library. diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst index 6100d9c1..eeb855d2 100644 --- a/doc/XMLreference.rst +++ b/doc/XMLreference.rst @@ -311,15 +311,16 @@ any effect. The settings here are global and apply to the entire model. - All materials are discarded. - All textures are discarded. - - All geoms with :ref:`contype`=:ref:`conaffinity`=0 are discarded, if they - are not referenced in another MJCF element. If a discarded geom was used for inferring body inertia, an explicit - :ref:`inertial` element is added to the body. + - All geoms with :ref:`contype` |-| = |-| :ref:`conaffinity` |-| =0 are + discarded, if they are not referenced in another MJCF element. If a discarded geom was used for inferring body + inertia, an explicit :ref:`inertial` element is added to the body. - All meshes which are not referenced by any geom (in particular those discarded above) are discarded. - The resulting compiled model will have exactly the same dynamics as the original model, with the exception of - raycasting, as used for example by :ref:`rangefinder`, since raycasting reports distances to - visual geoms. When visualizing models compiled with this flag, it is important to remember that colliding geoms are - often placed in a :ref:`group` which is invisible by default. + The resulting compiled model will have exactly the same dynamics as the original model. The only engine-level + computation which might change is the output of :ref:`raycasting` computations, as used for example by + :ref:`rangefinder` sensors, since raycasting reports distances to visual geoms. When visualizing + models compiled with this flag, it is important to remember that collision geoms are often placed in a + :ref:`group` which is invisible by default. .. _compiler-convexhull: @@ -670,14 +671,18 @@ is effectively a miscellaneous subsection. :at:`azimuth`: :at-val:`real, "90"` This attribute specifies the initial azimuth of the free camera around the vertical z-axis, in degrees. A value of 0 corresponds to looking in the positive x direction, while the default value of 90 corresponds to looking in the - positive y direction. + positive y direction. The look-at point itself is specified by the :ref:`statistic/center` + attribute, while the distance from the look-at point is controlled by the :ref:`statistic/extent` + attribute. .. _visual-global-elevation: :at:`elevation`: :at-val:`real, "-45"` This attribute specifies the initial elevation of the free camera with respect to the lookat point. Note that since this is a rotation around a vector parallel to the camera's X-axis (right in pixel space), *negative* numbers - correspond to moving the camera *up* from the horizontal plane, and vice-versa. + correspond to moving the camera *up* from the horizontal plane, and vice-versa. The look-at point itself is specified + by the :ref:`statistic/center` attribute, while the distance from the look-at point is controlled + by the :ref:`statistic/extent` attribute. .. _visual-global-linewidth: @@ -714,6 +719,12 @@ is effectively a miscellaneous subsection. This attribute specifies how the equivalent inertia is visualized. "false": use box, "true": use ellipsoid. +.. _visual-global-bvactive: + +:at:`bvactive`: :at-val:`[false, true], "true"` + This attribute specifies whether collision and raycasting code should mark elements of Bounding Volume Hierarchies + as intersecting, for the purpose of visualization. Setting this attribute to "false" can speed up simulation for + models with high-resolution meshes. .. _visual-quality: @@ -1121,6 +1132,17 @@ disables the rendering of the corresponding object. :at:`frustum`: :at-val:`real(4), "1 1 0 0.2"` Color used to render the camera frustum. +.. _visual-rgba-bv: + +:at:`bv`: :at-val:`real(4), "0 1 0 0.5"` + Color used to render bounding volumes. + +.. _visual-rgba-bvactive: + +:at:`bvactive`: :at-val:`real(4), "1 0 0 0.5"` + Color used to render active bounding volumes, if the :ref:`bvactive` flag is "true". + + .. _asset: @@ -1135,6 +1157,339 @@ extension if no ``content_type`` attribute is specified. The content type is ign file. +.. _asset-mesh: + +:el-prefix:`asset/` |-| **mesh** (*) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This element creates a mesh asset, which can then be referenced from geoms. If the referencing geom type is +:at-val:`mesh` the mesh is instantiated in the model, otherwise a geometric primitive is automatically fitted to it; see +the :ref:`geom ` element below. + +MuJoCo works with triangulated meshes. They can be loaded from binary STL files, OBJ files or MSH files with custom +format described below, or vertex and face data specified directly in the XML. Software such as MeshLab can be used to +convert from other mesh formats to STL or OBJ. While any collection of triangles can be loaded as a mesh and rendered, +collision detection works with the convex hull of the mesh as explained in :ref:`Collision`. See also the convexhull +attribute of the :ref:`compiler ` element which controls the automatic generation of convex hulls. The mesh +appearance (including texture mapping) is controlled by the :at:`material` and :at:`rgba` attributes of the referencing +geom, similarly to height fields. + +Meshes can have explicit texture coordinates instead of relying on the automated texture +mapping mechanism. When provided, these explicit coordinates have priority. Note that texture coordinates can be +specified with OBJ files and MSH files, as well as explicitly in the XML with the :at:`texcoord` attribute, but not via +STL files. These mechanism cannot be mixed. So if you have an STL mesh, the only way to add texture coordinates to it is +to convert to one of the other supported formats. + +MSH file format + The binary MSH file starts with 4 integers specifying the number of vertex positions (nvertex), vertex normals + (nnormal), vertex texture coordinates (ntexcoord), and vertex indices making up the faces (nface), followed by the + numeric data. nvertex must be at least 4. nnormal and ntexcoord can be zero (in which case the corresponding data is + not defined) or equal to nvertex. nface can also be zero, in which case faces are constructed automatically from the + convex hull of the vertex positions. The file size in bytes must be exactly: 16 + 12*(nvertex + nnormal + nface) + + 8*ntexcoord. The contents of the file must be as follows: + + .. code:: Text + + (int32) nvertex + (int32) nnormal + (int32) ntexcoord + (int32) nface + (float) vertex_positions[3*nvertex] + (float) vertex_normals[3*nnormal] + (float) vertex_texcoords[2*ntexcoord] + (int32) face_vertex_indices[3*nface] + +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. + +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 +negative scaling values can be used to flip the mesh; this is a legitimate operation. The size parameters of the +referening geoms are ignored, similarly to height fields. We also provide a mechanism to translate and +rotate the 3D coordinates, using the attributes :ref:`refpos` and :ref:`refquat`. + +A mesh can also be defined without faces (a point cloud essentially). In that case +the convex hull is constructed automatically, even if the compiler attribute convexhull is false. This makes it easy to +construct simple shapes directly in the XML. For example, a pyramid can be created as: + +.. code-block:: xml + + + + + +Positioning and orienting is complicated by the fact that vertex data are often designed relative to coordinate frames +whose origin is not inside the mesh. In contrast, MuJoCo expects the origin of a geom's local frame to coincide with the +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 in :ref:`mjModel.mesh_pos` and +:ref:`mjModel.mesh_quat`. 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. + +.. code-block:: xml + + + + + + + + + + +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: + +#. For STL meshes, remove any repeated vertices and re-index the faces if needed. If the mesh is not STL, we assume that + the desired vertices and faces have already been generated and do not apply removal or re-indexing; +#. If vertex normals are not provided, generate normals automatically, using a weighted average of the surrounding face + normals. If sharp edges are encountered, the renderer uses the face normals to preserve the visual information about + the edge, unless smoothnormal is true. Note that normals cannot be provided with STL meshes; +#. Scale, translate and rotate the vertices and normals, re-normalize the normals in case of scaling; +#. Construct the convex hull if specified; +#. Find the centroid of all triangle faces, and construct the union-of-pyramids representation. Triangles whose area is + too small (below the :ref:`mjMINVAL ` value of 1E-14) result in compile error; +#. Compute the center of mass and inertia matrix of the union-of-pyramids. Use eigenvalue decomposition to find the + principal axes of inertia. Center and align the mesh, saving the translational and rotational offsets for subsequent + geom-related computations. + +.. _asset-mesh-name: + +:at:`name`: :at-val:`string, optional` + Name of the mesh, used for referencing. If omitted, the mesh name equals the file name without the path and + extension. + +.. _asset-mesh-class: + +:at:`class`: :at-val:`string, optional` + Defaults class for setting unspecified attributes (only scale in this case). + +.. _asset-mesh-content_type: + +:at:`content_type`: :at-val:`string, optional` + If the file attribute is specified, then this sets the + `Media Type `_ (formerly known as MIME type) of the + file to be loaded. Any filename extensions will be overloaded. Currently ``model/vnd.mujoco.msh``, ``model/obj``, + and ``model/stl`` are supported. + +.. _asset-mesh-file: + +:at:`file`: :at-val:`string, optional` + The file from which the mesh will be loaded. The path is determined as described in the meshdir attribute of + :ref:`compiler `. The file extension must be "stl", "msh", or "obj" (not case sensitive) specifying the + file type. If the file name is omitted, the vertex attribute becomes required. + +.. _asset-mesh-scale: + +:at:`scale`: :at-val:`real(3), "1 1 1"` + This attribute specifies the scaling that will be applied to the vertex data along each coordinate axis. Negative + values are allowed, resulting in flipping the mesh along the corresponding axis. + +.. _asset-mesh-smoothnormal: + +:at:`smoothnormal`: :at-val:`[false, true], "false"` + Controls the automatic generation of vertex normals when normals are not given explicitly. If true, smooth normals + are generated by averaging the face normals at each vertex, with weight proportional to the face area. If false, + faces at large angles relative to the average normal are excluded from the average. In this way, sharp edges (as in + cube edges) are not smoothed. + +.. _asset-mesh-vertex: + +:at:`vertex`: :at-val:`real(3*nvert), optional` + Vertex 3D position data. You can specify position data in the XML using this attribute, or using a binary file, but + not both. + +.. _asset-mesh-normal: + +:at:`normal`: :at-val:`real(3*nvert), optional` + Vertex 3D normal data. If specified, the number of normals must equal the number of vertices. The model compiler + normalizes the normals automatically. + +.. _asset-mesh-texcoord: + +:at:`texcoord`: :at-val:`real(2*nvert), optional` + Vertex 2D texture coordinates, which are numbers between 0 and 1. If specified, the number of texture coordinate + pairs must equal the number of vertices. + +.. _asset-mesh-face: + +:at:`face`: :at-val:`int(3*nface), optional` + Faces of the mesh. Each face is a sequence of 3 vertex indices, in counter-clockwise order. The indices must be + integers between 0 and nvert-1. + +.. _asset-mesh-refpos: + +:at:`refpos`: :at-val:`real(3), "0 0 0"` + Reference position relative to which the 3D vertex coordinates are defined. This vector is subtracted from the + positions. + +.. _asset-mesh-refquat: + +:at:`refquat`: :at-val:`real(4), "1 0 0 0"` + Reference orientation relative to which the 3D vertex coordinates and normals are defined. The conjugate of this + quaternion is used to rotate the positions and normals. The model compiler normalizes the quaternion automatically. + +.. _mesh-plugin: + +:el-prefix:`mesh/` |-| **plugin** (?) +''''''''''''''''''''''''''''''''''''' + +Associate this mesh with an :ref:`engine plugin`. Either :at:`plugin` or :at:`instance` are required. + +.. _mesh-plugin-plugin: + +:at:`plugin`: :at-val:`string, optional` + Plugin identifier, used for implicit plugin instantiation. + +.. _mesh-plugin-instance: + +:at:`instance`: :at-val:`string, optional` + Instance name, used for explicit plugin instantiation. + + + +.. _asset-hfield: + +:el-prefix:`asset/` |-| **hfield** (*) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This element creates a height field asset, which can then be referenced from geoms with type "hfield". A height field, +also known as terrain map, is a 2D matrix of elevation data. The data can be specified in one of three ways: + +#. The elevation data can be loaded from a PNG file. The image is converted internally to gray scale, and the intensity + of each pixel is used to define elevation; white is high and black is low. + +#. The elevation data can be loaded from a binary file in the custom format described below. As with all other matrices + used in MuJoCo, the data ordering is row-major, like pixels in an image. If the data size is nrow-by-ncol, the file + must have 4*(2+nrow*ncol) bytes: + + :: + + (int32) nrow + (int32) ncol + (float32) data[nrow*ncol] + + +#. The elevation data can be left undefined at compile time. This is done by specifying the attributes nrow and ncol. + The compiler allocates space for the height field data in mjModel and sets it to 0. The user can then generate a + custom height field at runtime, either programmatically or using sensor data. + +| Regardless of which method is used to specify the elevation data, the compiler always normalizes it to the range [0 + 1]. However if the data is left undefined at compile time and generated later at runtime, it is the user's + responsibility to normalize it. +| The position and orientation of the height field is determined by the geom that references it. The spatial extent on + the other hand is specified by the height field asset itself via the size attribute, and cannot be modified by the + referencing geom (the geom size parameters are ignored in this case). The same approach is used for meshes below: + positioning is done by the geom while sizing is done by the asset. This is because height fields and meshes involve + sizing operations that are not common to other geoms. +| For collision detection, a height field is treated as a union of triangular prisms. Collisions between height fields + and other geoms (except for planes and other height fields which are not supported) are computed by first selecting + the sub-grid of prisms that could collide with the geom based on its bounding box, and then using the general convex + collider. The number of possible contacts between a height field and a geom is limited to 50 + (:ref:`mjMAXCONPAIR `); any contacts beyond that are discarded. To avoid penetration due to discarded + contacts, the spatial features of the height field should be large compared to the geoms it collides with. + +.. _asset-hfield-name: + +:at:`name`: :at-val:`string, optional` + Name of the height field, used for referencing. If the name is omitted and a file name is specified, the height field + name equals the file name without the path and extension. + +.. _asset-hfield-content_type: + +:at:`content_type`: :at-val:`string, optional` + If the file attribute is specified, then this sets the + `Media Type `__ (formerly known as MIME types) of the + file to be loaded. Any filename extensions will be overloaded. Currently ``image/png`` and + ``image/vnd.mujoco.hfield`` are supported. + +.. _asset-hfield-file: + +:at:`file`: :at-val:`string, optional` + If this attribute is specified, the elevation data is loaded from the given file. If the file extension is ".png", + not case-sensitive, the file is treated as a PNG file. Otherwise it is treated as a binary file in the above custom + format. The number of rows and columns in the data are determined from the file contents. Loading data from a file + and setting nrow or ncol below to non-zero values results is compile error, even if these settings are consistent + with the file contents. + +.. _asset-hfield-nrow: + +:at:`nrow`: :at-val:`int, "0"` + This attribute and the next are used to allocate a height field in mjModel. If the :at:`elevation` attribute is not + set, the elevation data is set to 0. This attribute specifies the number of rows in the elevation data matrix. The + default value of 0 means that the data will be loaded from a file, which will be used to infer the size of the + matrix. + +.. _asset-hfield-ncol: + +:at:`ncol`: :at-val:`int, "0"` + This attribute specifies the number of columns in the elevation data matrix. + +.. _asset-hfield-elevation: + +:at:`elevation`: :at-val:`real(nrow*ncol), optional` + This attribute specifies the elevation data matrix. Values are automatically normalized to lie between 0 and 1 by + first subtracting the minimum value and then dividing by the (maximum-minimum) difference, if not 0. If not provided, + values are set to 0. + +.. _asset-hfield-size: + +:at:`size`: :at-val:`real(4), required` + .. figure:: images/XMLreference/peaks.png + :width: 350px + :align: right + + The four numbers here are (radius_x, radius_y, elevation_z, base_z). The height field is centered at the referencing + geom's local frame. Elevation is in the +Z direction. The first two numbers specify the X and Y extent (or "radius") + of the rectangle over which the height field is defined. This may seem unnatural for rectangles, but it is natural + for spheres and other geom types, and we prefer to use the same convention throughout the model. The third number is + the maximum elevation; it scales the elevation data which is normalized to [0-1]. Thus the minimum elevation point is + at Z=0 and the maximum elevation point is at Z=elevation_z. The last number is the depth of a box in the -Z direction + serving as a "base" for the height field. Without this automatically generated box, the height field would have zero + thickness at places there the normalized elevation data is zero. Unlike planes which impose global unilateral + constraints, height fields are treated as unions of regular geoms, so there is no notion of being "under" the height + field. Instead a geom is either inside or outside the height field - which is why the inside part must have non-zero + thickness. The example on the right is the MATLAB "peaks" surface saved in our custom height field format, and loaded + as an asset with size = "1 1 1 0.1". The horizontal size of the box is 2, the difference between the maximum and + minimum elevation is 1, and the depth of the base added below the minimum elevation point is 0.1. + + +.. _asset-skin: + +:el-prefix:`asset/` |-| **skin** (*) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _asset-skin-name: +.. _asset-skin-file: +.. _asset-skin-vertex: +.. _asset-skin-texcoord: +.. _asset-skin-face: +.. _asset-skin-inflate: +.. _asset-skin-material: +.. _asset-skin-rgba: +.. _asset-skin-group: + +:ref:`Skins` have been moved under the new grouping element :ref:`deformable`. They can +still be specified here but this functionality is now deprecated and will be removed in the future. + + + .. _asset-texture: :el-prefix:`asset/` |-| **texture** (*) @@ -1347,328 +1702,6 @@ file. If true, images loaded from file are flipped in the vertical direction. Does not affect procedural textures. -.. _asset-hfield: - -:el-prefix:`asset/` |-| **hfield** (*) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This element creates a height field asset, which can then be referenced from geoms with type "hfield". A height field, -also known as terrain map, is a 2D matrix of elevation data. The data can be specified in one of three ways: - -#. The elevation data can be loaded from a PNG file. The image is converted internally to gray scale, and the intensity - of each pixel is used to define elevation; white is high and black is low. - -#. The elevation data can be loaded from a binary file in the custom format described below. As with all other matrices - used in MuJoCo, the data ordering is row-major, like pixels in an image. If the data size is nrow-by-ncol, the file - must have 4*(2+nrow*ncol) bytes: - - :: - - (int32) nrow - (int32) ncol - (float32) data[nrow*ncol] - - -#. The elevation data can be left undefined at compile time. This is done by specifying the attributes nrow and ncol. - The compiler allocates space for the height field data in mjModel and sets it to 0. The user can then generate a - custom height field at runtime, either programmatically or using sensor data. - -| Regardless of which method is used to specify the elevation data, the compiler always normalizes it to the range [0 - 1]. However if the data is left undefined at compile time and generated later at runtime, it is the user's - responsibility to normalize it. -| The position and orientation of the height field is determined by the geom that references it. The spatial extent on - the other hand is specified by the height field asset itself via the size attribute, and cannot be modified by the - referencing geom (the geom size parameters are ignored in this case). The same approach is used for meshes below: - positioning is done by the geom while sizing is done by the asset. This is because height fields and meshes involve - sizing operations that are not common to other geoms. -| For collision detection, a height field is treated as a union of triangular prisms. Collisions between height fields - and other geoms (except for planes and other height fields which are not supported) are computed by first selecting - the sub-grid of prisms that could collide with the geom based on its bounding box, and then using the general convex - collider. The number of possible contacts between a height field and a geom is limited to 50 - (:ref:`mjMAXCONPAIR `); any contacts beyond that are discarded. To avoid penetration due to discarded - contacts, the spatial features of the height field should be large compared to the geoms it collides with. - -.. _asset-hfield-name: - -:at:`name`: :at-val:`string, optional` - Name of the height field, used for referencing. If the name is omitted and a file name is specified, the height field - name equals the file name without the path and extension. - -.. _asset-hfield-content_type: - -:at:`content_type`: :at-val:`string, optional` - If the file attribute is specified, then this sets the - `Media Type `__ (formerly known as MIME types) of the - file to be loaded. Any filename extensions will be overloaded. Currently ``image/png`` and - ``image/vnd.mujoco.hfield`` are supported. - -.. _asset-hfield-file: - -:at:`file`: :at-val:`string, optional` - If this attribute is specified, the elevation data is loaded from the given file. If the file extension is ".png", - not case-sensitive, the file is treated as a PNG file. Otherwise it is treated as a binary file in the above custom - format. The number of rows and columns in the data are determined from the file contents. Loading data from a file - and setting nrow or ncol below to non-zero values results is compile error, even if these settings are consistent - with the file contents. - -.. _asset-hfield-nrow: - -:at:`nrow`: :at-val:`int, "0"` - This attribute and the next are used to allocate a height field in mjModel and leave the elevation data undefined - (i.e., set to 0). This attribute specifies the number of rows in the elevation data matrix. The default value of 0 - means that the data will be loaded from a file, which will be used to infer the size of the matrix. - -.. _asset-hfield-ncol: - -:at:`ncol`: :at-val:`int, "0"` - This attribute specifies the number of columns in the elevation data matrix. - -.. _asset-hfield-size: - -:at:`size`: :at-val:`real(4), required` - .. figure:: images/XMLreference/peaks.png - :width: 350px - :align: right - - The four numbers here are (radius_x, radius_y, elevation_z, base_z). The height field is centered at the referencing - geom's local frame. Elevation is in the +Z direction. The first two numbers specify the X and Y extent (or "radius") - of the rectangle over which the height field is defined. This may seem unnatural for rectangles, but it is natural - for spheres and other geom types, and we prefer to use the same convention throughout the model. The third number is - the maximum elevation; it scales the elevation data which is normalized to [0-1]. Thus the minimum elevation point is - at Z=0 and the maximum elevation point is at Z=elevation_z. The last number is the depth of a box in the -Z direction - serving as a "base" for the height field. Without this automatically generated box, the height field would have zero - thickness at places there the normalized elevation data is zero. Unlike planes which impose global unilateral - constraints, height fields are treated as unions of regular geoms, so there is no notion of being "under" the height - field. Instead a geom is either inside or outside the height field - which is why the inside part must have non-zero - thickness. The example on the right is the MATLAB "peaks" surface saved in our custom height field format, and loaded - as an asset with size = "1 1 1 0.1". The horizontal size of the box is 2, the difference between the maximum and - minimum elevation is 1, and the depth of the base added below the minimum elevation point is 0.1. - - -.. _asset-mesh: - -:el-prefix:`asset/` |-| **mesh** (*) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This element creates a mesh asset, which can then be referenced from geoms. If the referencing geom type is -:at-val:`mesh` the mesh is instantiated in the model, otherwise a geometric primitive is automatically fitted to it; see -the :ref:`geom ` element below. - -MuJoCo works with triangulated meshes. They can be loaded from binary STL files, OBJ files or MSH files with custom -format described below, or vertex and face data specified directly in the XML. Software such as MeshLab can be used to -convert from other mesh formats to STL or OBJ. While any collection of triangles can be loaded as a mesh and rendered, -collision detection works with the convex hull of the mesh as explained in :ref:`Collision`. See also the convexhull -attribute of the :ref:`compiler ` element which controls the automatic generation of convex hulls. The mesh -appearance (including texture mapping) is controlled by the :at:`material` and :at:`rgba` attributes of the referencing -geom, similarly to height fields. - -Meshes can have explicit texture coordinates instead of relying on the automated texture -mapping mechanism. When provided, these explicit coordinates have priority. Note that texture coordinates can be -specified with OBJ files and MSH files, as well as explicitly in the XML with the :at:`texcoord` attribute, but not via -STL files. These mechanism cannot be mixed. So if you have an STL mesh, the only way to add texture coordinates to it is -to convert to one of the other supported formats. - -MSH file format - The binary MSH file starts with 4 integers specifying the number of vertex positions (nvertex), vertex normals - (nnormal), vertex texture coordinates (ntexcoord), and vertex indices making up the faces (nface), followed by the - numeric data. nvertex must be at least 4. nnormal and ntexcoord can be zero (in which case the corresponding data is - not defined) or equal to nvertex. nface can also be zero, in which case faces are constructed automatically from the - convex hull of the vertex positions. The file size in bytes must be exactly: 16 + 12*(nvertex + nnormal + nface) + - 8*ntexcoord. The contents of the file must be as follows: - - .. code:: Text - - (int32) nvertex - (int32) nnormal - (int32) ntexcoord - (int32) nface - (float) vertex_positions[3*nvertex] - (float) vertex_normals[3*nnormal] - (float) vertex_texcoords[2*ntexcoord] - (int32) face_vertex_indices[3*nface] - -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. - -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 -negative scaling values can be used to flip the mesh; this is a legitimate operation. The size parameters of the -referening geoms are ignored, similarly to height fields. We also provide a mechanism to translate and -rotate the 3D coordinates, using the attributes :ref:`refpos` and :ref:`refquat`. - -A mesh can also be defined without faces (a point cloud essentially). In that case -the convex hull is constructed automatically, even if the compiler attribute convexhull is false. This makes it easy to -construct simple shapes directly in the XML. For example, a pyramid can be created as: - -.. code-block:: xml - - - - - -Positioning and orienting is complicated by the fact that vertex data are often designed relative to coordinate frames -whose origin is not inside the mesh. In contrast, MuJoCo expects the origin of a geom's local frame to coincide with the -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 in :ref:`mjModel.mesh_pos` and -:ref:`mjModel.mesh_quat`. 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. - -.. code-block:: xml - - - - - - - - - - -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: - -#. For STL meshes, remove any repeated vertices and re-index the faces if needed. If the mesh is not STL, we assume that - the desired vertices and faces have already been generated and do not apply removal or re-indexing; -#. If vertex normals are not provided, generate normals automatically, using a weighted average of the surrounding face - normals. If sharp edges are encountered, the renderer uses the face normals to preserve the visual information about - the edge, unless smoothnormal is true. Note that normals cannot be provided with STL meshes; -#. Scale, translate and rotate the vertices and normals, re-normalize the normals in case of scaling; -#. Construct the convex hull if specified; -#. Find the centroid of all triangle faces, and construct the union-of-pyramids representation. Triangles whose area is - too small (below the :ref:`mjMINVAL ` value of 1E-14) result in compile error; -#. Compute the center of mass and inertia matrix of the union-of-pyramids. Use eigenvalue decomposition to find the - principal axes of inertia. Center and align the mesh, saving the translational and rotational offsets for subsequent - geom-related computations. - -.. _asset-mesh-name: - -:at:`name`: :at-val:`string, optional` - Name of the mesh, used for referencing. If omitted, the mesh name equals the file name without the path and - extension. - -.. _asset-mesh-class: - -:at:`class`: :at-val:`string, optional` - Defaults class for setting unspecified attributes (only scale in this case). - -.. _asset-mesh-content_type: - -:at:`content_type`: :at-val:`string, optional` - If the file attribute is specified, then this sets the - `Media Type `_ (formerly known as MIME type) of the - file to be loaded. Any filename extensions will be overloaded. Currently ``model/vnd.mujoco.msh``, ``model/obj``, - and ``model/stl`` are supported. - -.. _asset-mesh-file: - -:at:`file`: :at-val:`string, optional` - The file from which the mesh will be loaded. The path is determined as described in the meshdir attribute of - :ref:`compiler `. The file extension must be "stl", "msh", or "obj" (not case sensitive) specifying the - file type. If the file name is omitted, the vertex attribute becomes required. - -.. _asset-mesh-scale: - -:at:`scale`: :at-val:`real(3), "1 1 1"` - This attribute specifies the scaling that will be applied to the vertex data along each coordinate axis. Negative - values are allowed, resulting in flipping the mesh along the corresponding axis. - -.. _asset-mesh-smoothnormal: - -:at:`smoothnormal`: :at-val:`[false, true], "false"` - Controls the automatic generation of vertex normals when normals are not given explicitly. If true, smooth normals - are generated by averaging the face normals at each vertex, with weight proportional to the face area. If false, - faces at large angles relative to the average normal are excluded from the average. In this way, sharp edges (as in - cube edges) are not smoothed. - -.. _asset-mesh-vertex: - -:at:`vertex`: :at-val:`real(3*nvert), optional` - Vertex 3D position data. You can specify position data in the XML using this attribute, or using a binary file, but - not both. - -.. _asset-mesh-normal: - -:at:`normal`: :at-val:`real(3*nvert), optional` - Vertex 3D normal data. If specified, the number of normals must equal the number of vertices. The model compiler - normalizes the normals automatically. - -.. _asset-mesh-texcoord: - -:at:`texcoord`: :at-val:`real(2*nvert), optional` - Vertex 2D texture coordinates, which are numbers between 0 and 1. If specified, the number of texture coordinate - pairs must equal the number of vertices. - -.. _asset-mesh-face: - -:at:`face`: :at-val:`int(3*nface), optional` - Faces of the mesh. Each face is a sequence of 3 vertex indices, in counter-clockwise order. The indices must be - integers between 0 and nvert-1. - -.. _asset-mesh-refpos: - -:at:`refpos`: :at-val:`real(3), "0 0 0"` - Reference position relative to which the 3D vertex coordinates are defined. This vector is subtracted from the - positions. - -.. _asset-mesh-refquat: - -:at:`refquat`: :at-val:`real(4), "1 0 0 0"` - Reference orientation relative to which the 3D vertex coordinates and normals are defined. The conjugate of this - quaternion is used to rotate the positions and normals. The model compiler normalizes the quaternion automatically. - -.. _mesh-plugin: - -:el-prefix:`mesh/` |-| **plugin** (?) -''''''''''''''''''''''''''''''''''''' - -Associate this mesh with an :ref:`engine plugin`. Either :at:`plugin` or :at:`instance` are required. - -.. _mesh-plugin-plugin: - -:at:`plugin`: :at-val:`string, optional` - Plugin identifier, used for implicit plugin instantiation. - -.. _mesh-plugin-instance: - -:at:`instance`: :at-val:`string, optional` - Instance name, used for explicit plugin instantiation. - - -.. _asset-skin: - -:el-prefix:`asset/` |-| **skin** (*) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. _asset-skin-name: -.. _asset-skin-file: -.. _asset-skin-vertex: -.. _asset-skin-texcoord: -.. _asset-skin-face: -.. _asset-skin-inflate: -.. _asset-skin-material: -.. _asset-skin-rgba: -.. _asset-skin-group: - -:ref:`Skins` have been moved under the new grouping element :ref:`deformable`. They can -still be specified here but this functionality is now deprecated and will be removed in the future. - .. _asset-material: @@ -1944,12 +1977,19 @@ adjust it properly through the XML. :at:`sdf_initpoints`: :at-val:`int, "40"` Number of starting points used for finding contacts with Signed Distance Field collisions. +.. youtube:: H9qG9Zf2W44 + :align: right + :width: 240px + .. _option-actuatorgroupdisable: -:at:`actuatorgroupdisable`: :at-val:`int(30), ""` +:at:`actuatorgroupdisable`: :at-val:`int(31), optional` List of actuator groups to disable. Actuators whose :ref:`group` is in this list will produce no force. If they are stateful, their activation states will not be integrated. Internally this list is - implemented as an integer bitfield, so values must be in the range ``0 <= group <= 30``. + implemented as an integer bitfield, so values must be in the range ``0 <= group <= 30``. If not set, all actuator + groups are enabled. See `example model + `__ + and associated screen-capture on the right. .. _option-flag: @@ -2626,7 +2666,7 @@ helps clarify the role of bodies and geoms in MuJoCo. | capsule | 1 or 2 | Radius of the capsule; half-length of the cylinder part when not using the :at:`fromto` | | | | specification. | +---------+--------+------------------------------------------------------------------------------------------------+ - |ellipsoid| 1 | X radius; Y radius; Z radius. | + |ellipsoid| 3 | X radius; Y radius; Z radius. | +---------+--------+------------------------------------------------------------------------------------------------+ |cylinder | 1 or 2 | Radius of the cylinder; half-length of the cylinder when not using the :at:`fromto` | | | | specification. | @@ -4561,7 +4601,7 @@ of the other body, without any joint elements in the child body. :at:`body2`: :at-val:`string, optional` Name of the second body. If this attribute is omitted, the second body is the world body. Welding a body to the world - and changing the corresponding component of mjModel.eq_active at runtime can be used to fix the body temporarily. + and changing the corresponding component of mjData.eq_active at runtime can be used to fix the body temporarily. .. _equality-weld-relpose: @@ -7647,8 +7687,8 @@ if omitted. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | This element sets the attributes of the dummy :ref:`general ` element of the defaults class. -| All general attributes are available here except: name, class, joint, jointinparent, site, tendon, slidersite, - cranksite. +| All general attributes are available here except: name, class, joint, jointinparent, site, refsite, tendon, + slidersite, cranksite. .. _default-motor: @@ -7675,8 +7715,8 @@ if omitted. 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. +:ref:`motor ` attributes are available here except: name, class, joint, jointinparent, site, refsite, +tendon, slidersite, cranksite. .. _default-position: @@ -7705,7 +7745,7 @@ slidersite, cranksite. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ All :ref:`position ` attributes are available here except: name, class, joint, jointinparent, site, -tendon, slidersite, cranksite. +refsite, tendon, slidersite, cranksite. .. _default-velocity: @@ -7732,7 +7772,7 @@ tendon, slidersite, cranksite. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ All :ref:`velocity ` attributes are available here except: name, class, joint, jointinparent, site, -tendon, slidersite, cranksite. +refsite, tendon, slidersite, cranksite. .. _default-intvelocity: @@ -7763,7 +7803,7 @@ tendon, slidersite, cranksite. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ All :ref:`intvelocity ` attributes are available here except: name, class, joint, jointinparent, -site, tendon, slidersite, cranksite. +site, refsite, tendon, slidersite, cranksite. .. _default-damper: @@ -7788,7 +7828,7 @@ site, tendon, slidersite, cranksite. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ All :ref:`damper ` attributes are available here except: name, class, joint, jointinparent, site, -tendon, slidersite, cranksite. +refsite, tendon, slidersite, cranksite. .. _default-cylinder: @@ -7821,7 +7861,7 @@ tendon, slidersite, cranksite. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ All :ref:`cylinder ` attributes are available here except: name, class, joint, jointinparent, site, -tendon, slidersite, cranksite. +refsite, tendon, slidersite, cranksite. .. _default-muscle: @@ -7864,7 +7904,7 @@ tendon, slidersite, cranksite. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ All :ref:`muscle ` attributes are available here except: name, class, joint, jointinparent, site, -tendon, slidersite, cranksite. +refsite, tendon, slidersite, cranksite. .. _default-adhesion: diff --git a/doc/XMLschema.rst b/doc/XMLschema.rst index 702adeb2..143fc733 100644 --- a/doc/XMLschema.rst +++ b/doc/XMLschema.rst @@ -65,7 +65,7 @@ | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | | | | | :ref:`linewidth` | :ref:`glow` | :ref:`offwidth` | :ref:`offheight` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`realtime` | :ref:`ellipsoidinertia` | | | | +| | | | :ref:`realtime` | :ref:`ellipsoidinertia` | :ref:`bvactive` | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |_| visual |br| |_| |L| | | .. table:: | @@ -126,7 +126,9 @@ | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | | | | | :ref:`contacttorque` | :ref:`contactgap` | :ref:`rangefinder` | :ref:`constraint` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`slidercrank` | :ref:`crankbroken` | :ref:`frustum` | | | +| | | | :ref:`slidercrank` | :ref:`crankbroken` | :ref:`frustum` | :ref:`bv` | | +| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +| | | | :ref:`bvactive` | | | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | mujoco |br| |L| | | *no attributes* | @@ -155,7 +157,7 @@ | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | | | | | :ref:`name` | :ref:`content_type` | :ref:`file` | :ref:`nrow` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`ncol` | :ref:`size` | | | | +| | | | :ref:`ncol` | :ref:`size` | :ref:`elevation` | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |_| asset |br| |_| |L| | | .. table:: | diff --git a/doc/changelog.rst b/doc/changelog.rst index fb886273..55cf4d2d 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -5,22 +5,66 @@ Changelog Upcoming version (not yet released) ----------------------------------- +MJX +^^^ + +1. Improved performance of getting and putting device data. + + - Use ``tobytes()`` for numpy array serialization, which is orders of magnitude faster than converting to tuples. + - Avoid reallocating host ``mjData`` arrays when array shapes are unchanged. + - Speed up calculation of ``mjx.ncon`` for models with many geoms. + - Avoid calling ``mjx.ncon`` in ``mjx.get_data_into`` when ``nc`` can be derived from ``mjx.Data``. +2. Fixed a bug in ``mjx-viewer`` that prevented it from running. Updated ``mjx-viewer`` to use newer + ``mjx.get_data_into`` function call. + +Version 3.1.2 (February 05, 2024) +----------------------------------- + General ^^^^^^^ -1. Improved the :ref:discardvisual compiler flag, which now discards all visual-only assets. See - :ref:discardvisual for details. +1. Improved the :ref:`discardvisual` compiler flag, which now discards all visual-only assets. + See :ref:`discardvisual` for details. +2. Removed the :ref:`timer` for midphase colllision detection, it is now folded in with the narrowphase + timer. This is because timing the two phases seperately required fine-grained timers inside the collision + functions; these functions are so small and fast that the timer itself was incurring a measurable cost. +3. Added the flag :ref:`bvactive` to ``visual/global``, allowing users to turn off + visualisation of active bounding volumes (the red/green boxes in this :ref:`this changelog item`). For + models with very high-resolution meshes, the computation required for this visualization can slow down simulation + speed. Fixes :github:issue:`1279`. + + - Added color of :ref:`bounding volumes` and :ref:`active bounding volumes` + to :ref:`visual/rgba`. +4. Height-field elevation data can now be specified directly in XML with the :ref:`elevation` + attribute (and not only with PNG files). + See `example model `__. MJX ^^^ -2. Added :ref:`dyntype` ``filterexact``. -3. Added :at:`site` transmission. -4. Updated MJX colab tutorial with more stable quadruped environment. -5. Added ``mjx.ray`` which mirrors :ref:`mj_ray` for planes, spheres, capsules, and boxes. +5. Added :ref:`dyntype` ``filterexact``. +6. Added :at:`site` transmission. +7. Updated MJX colab tutorial with more stable quadruped environment. +8. Added ``mjx.ray`` which mirrors :ref:`mj_ray` for planes, spheres, capsules, boxes, and meshes. +9. Added ``mjx.is_sparse`` which mirrors :ref:`mj_isSparse` and ``mjx.full_m`` which mirrors :ref:`mj_fullM`. +10. Added support for specifying sparse or dense mass matrices via :ref:`option-jacobian`. +11. Raise a not implemented error when nonzero frictionloss is present. Fixes :github:issue:`1344`. + +Python bindings +^^^^^^^^^^^^^^^ +12. Improved the implementation of the :ref:`rollout` module. Note the changes below are breaking, dependent + code will require modification. + + - Uses :ref:`mjSTATE_FULLPHYSICS` as state spec, enabling divergence detection by inspecting time. + - Allows user-defined control spec for any combination of :ref:`user input` fields as controls. + - Outputs are no longer squeezed and always have dim=3. +13. The ``sync`` function for the :ref:`passive viewer` can now pick up changes to rendering flags in + ``user_scn``, as requested in :github:issue:`1190`. Bug fixes ^^^^^^^^^ -6. Fixed a bug that prevented the use of pins with plugins if flexes are not in the worldbody. Fixes - :github:issue:`1270`. +14. Fixed a bug that prevented the use of pins with plugins if flexes are not in the worldbody. Fixes + :github:issue:`1270`. +15. Fixed a bug in the :ref:`muscle model` that led to non-zero values outside the lower + bound of the length range. Fixes :github:issue:`1342`. Version 3.1.1 (December 18, 2023) @@ -28,7 +72,8 @@ Version 3.1.1 (December 18, 2023) Bug fixes ^^^^^^^^^ -1. Fixed a bug (introduced in 3.1.0) where box-box collisions produced no contacts if one box was deeply embedded in the other. +1. Fixed a bug (introduced in 3.1.0) where box-box collisions produced no contacts if one box was deeply embedded in the + other. 2. Fixed a bug in :ref:`simulate` where the "LOADING..." message was not showing correctly. 3. Fixed a crash in the Python :ref:`passive viewer`, when used with models containing Flex objects. 4. Fixed a bug in MJX where ``site_xmat`` was ignored in ``get_data`` and ``put_data`` @@ -41,8 +86,8 @@ Version 3.1.0 (December 12, 2023) General ^^^^^^^ 1. Improved convergence of Signed Distance Function (SDF) collisions by using line search and a new objective function - for the optimization. This allows to decrease the number of initial points needed for finding the contacts and is more - robust for very small or large geom sizes. + for the optimization. This allows to decrease the number of initial points needed for finding the contacts and is + more robust for very small or large geom sizes. 2. Added :ref:`frame` to MJCF, a :ref:`meta-element` which defines a pure coordinate transformation on its direct children, without requiring a :ref:`body`. 3. Added the :at:`kv` attribute to the :ref:`position` and :ref:`intvelocity` @@ -52,17 +97,14 @@ General Plugins ^^^^^^^ - 4. Allow actuator plugins to use activation variables in ``mjData.act`` as their internal state, rather than ``mjData.plugin_state``. Actuator plugins can now specify :ref:`callbacks` that compute activation variables, and they can be used with built-in :ref:`dyntype` actuator dynamics. - 5. Added the `pid `__ actuator plugin, a configurable PID controller that implements the Integral term, which is not available with native MuJoCo actuators. MJX ^^^ - 6. Added ``site_xpos`` and ``site_xmat`` to MJX. 7. Added ``put_data``, ``put_model``, ``get_data`` to replace ``device_put`` and ``device_get_into``, which will be deprecated. These new functions correctly translate fields that are the result of intermediate calculations such as @@ -74,8 +116,8 @@ Bug fixes Before this fix such actuators could lead to non-conservation of momentum. 9. Fix bug that prevented using flex with :ref:`simulate`. 10. Fix bug that prevented the use of elasticity plugins in combination with pinned flex vertices. -11. Release Python wheels targeting macOS 10.16 to support x86_64 systems where SYSTEM_VERSION_COMPAT is set. The minimum - supported version is still 11.0, but we release these wheels to fix compatibility for those users. See +11. Release Python wheels targeting macOS 10.16 to support x86_64 systems where ``SYSTEM_VERSION_COMPAT`` is set. + The minimum supported version is still 11.0, but we release these wheels to fix compatibility for those users. See :github:issue:`1213`. Version 3.0.1 (November 15, 2023) @@ -272,7 +314,7 @@ General - For models which have ``