chenlin/Mujoco_WASM
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update the asset/mesh section of the XML reference to mention OBJ files.

Browse Source 
Also clean up some formatting.

PiperOrigin-RevId: 453173729
Change-Id: I069b9433542dda0e3effe71d162cb51a46ce2f4e
This commit is contained in:
Yuval Tassa
2022-06-06 05:02:04 -07:00
committed by Copybara-Service
parent d7ae7f5433
commit 880304abba
1 changed files with 58 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/XMLreference.rst
+58 -52
View File
@@ -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 <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 <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 <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 <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 <geom>` below. Fortunately most meshes used in robot models are
orientation; see also :at:`mesh` attribute of :ref:`geom <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.
<geom type="mesh" mesh="forearm"/>
</body>
| 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 <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 <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;