From 880304abba3498ad9bc00c182cd0ab1ccf1190bb Mon Sep 17 00:00:00 2001 From: Yuval Tassa Date: Mon, 6 Jun 2022 05:02:04 -0700 Subject: [PATCH] Update the asset/mesh section of the XML reference to mention OBJ files. Also clean up some formatting. PiperOrigin-RevId: 453173729 Change-Id: I069b9433542dda0e3effe71d162cb51a46ce2f4e --- doc/XMLreference.rst | 110 +++++++++++++++++++++++-------------------- 1 file changed, 58 insertions(+), 52 deletions(-) diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst index f48d5a90..45d9f54f 100644 --- a/doc/XMLreference.rst +++ b/doc/XMLreference.rst @@ -2603,52 +2603,57 @@ also known as terrain map, is a 2D matrix of elevation data. The data can be spe :el-prefix:`asset/` **mesh** (*) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -| This element creates a mesh asset, which can then be referenced from geoms. If the referencing geom type is "mesh" the - mesh is instantiated in the model, otherwise a geometric primitive is automatically fitted to it; see the - :ref:`geom ` element below. +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, binary 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. 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` in the Computation - chapter. 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 material and rgba - attributes of the referencing geom, similarly to height fields. -| Starting with MuJoCo 2.0, 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 custom binary files, as well as explicitly in the XML with the 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. -| 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: +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. -.. code:: Text +Starting with MuJoCo 2.0, 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. - (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] +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: -| 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. -| 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 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. As of MuJoCo 2.0 we also provide a mechanism to translate and rotate - the 3D coordinates, using the attributes refpos and refquat. -| Another new feature in MuJoCo 2.0 is that a mesh can 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 is - easy to construct simple shapes directly in the XML. For example, a pyramid can be created as: + .. 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. + +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. As of MuJoCo 2.0 we also provide a mechanism to translate and +rotate the 3D coordinates, using the attributes refpos and refquat. + +Another new feature in MuJoCo 2.0 is that a mesh can 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 @@ -2661,7 +2666,7 @@ 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 mesh attribute of :ref:`geom ` below. Fortunately most meshes used in robot models are +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. @@ -2681,15 +2686,16 @@ 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 inertia of - all pyramids and accumulating them. This algorithm comes from Astronomy where it is used to estimate inertial - properties of asteroids. It is exact for convex meshes but is not always exact for non-convex meshes; indeed no - algorithm can be exact when the notion of interior is ill-defined. Thus for non-convex models designed in CAD software - (which usually knows what the interior is) it is better to ask that software to compute the inertial properties of the - body and enter them in the MJCF file explicitly via the :ref:`inertial ` element. -| The full list of processing steps applied by the compiler to each mesh is as follows: +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 inertia of +all pyramids and accumulating them. This algorithm comes from Astronomy where it is used to estimate inertial +properties of asteroids. It is exact for convex meshes but is not always exact for non-convex meshes; indeed no +algorithm can be exact when the notion of interior is ill-defined. Thus for non-convex models designed in CAD software +(which usually knows what the interior is) it is better to ask that software to compute the inertial properties of the +body and enter them in the MJCF file explicitly via the :ref:`inertial ` element. + +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;