diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst index 7e3e1afd..6c988d0d 100644 --- a/doc/XMLreference.rst +++ b/doc/XMLreference.rst @@ -1327,57 +1327,92 @@ The full list of processing steps applied by the compiler to each mesh is as fol :at:`builtin`: :at-val:`string, optional` The mesh is generated by the compiler from a set of parameters specified in :ref:`params`. - When saved to XML, meshes produced this way are converted to explicit vertices. + When saved to XML, meshes produced this way are converted to explicit vertices. The Python bindings include + :ref:`convenience methods ` for generating these meshes. The available built-in types, their parameters and semantics are: + .. image:: images/XMLreference/s.png + :width: 23% + :align: right + :target: https://github.com/google-deepmind/mujoco/blob/main/test/user/testdata/makemesh.xml + :at-val:`sphere` (subdivision) - Repeated subdivisions :math:`s` of a unit icosahedron. Has :math:`2 + 10 \cdot 4^s` vertices. + Repeated subdivisions of a unit icosahedron ("icosphere"). For :math:`s` subdivisions, this mesh + has :math:`V = 2 + 10 \cdot 4^s` vertices and :math:`F = 20 \cdot 4^s` faces. **subdivision**: integer in [0-4]: The number of subdivisions to apply to icosahedron faces. + .. image:: images/XMLreference/h.png + :width: 23% + :align: right + :target: https://github.com/google-deepmind/mujoco/blob/main/test/user/testdata/makemesh.xml + :at-val:`hemisphere` (subdivision) - Repeated subdivisions :math:`s` of a square-based pyramid. Has :math:`2+2(s+1)(s+2)` vertices. + Repeated subdivisions of a square-based pyramid. For :math:`s` subdivisions, this mesh + has :math:`V = 2 + 2(s+1)(s+2)` vertices and :math:`F = 4(s+1)(s+2)` faces. **subdivision**: integer in [0-10]: The number of subdivisions to apply to the pyramid. + .. image:: images/XMLreference/c.png + :width: 23% + :align: right + :target: https://github.com/google-deepmind/mujoco/blob/main/test/user/testdata/makemesh.xml + :at-val:`cone` (nvert, radius) - The convex hull of a regular unit polygon at z = -1 and a unit polygon with the given radiusat z = 1. - If radius is 1, the mesh a prism. If radius is 0, only a single vertex is place at (0, 0, 1) and the mesh is a + The convex hull of a regular unit polygon at z = -1 and a unit polygon with the given radius at z = 1. + If radius is 1, the mesh a prism. If radius is 0, only a single vertex is placed at (0, 0, 1) and the mesh is a discrete cone. If radius is positive, the mesh is a truncated discrete cone. **nvert**: integer >= 3: The number vertices in the polygon. |br| **radius**: real in [0, 1]: The radius of the top face. - :at-val:`supersphere` (resolution, e, n) - A generalization of a sphere, also known as a superellipsoid (we use "supersphere" since semiaxis rescaling is - performed by the :ref:`scale` attribute). If the **n** and **e** parameters are both 1, the - shape is a sphere. See `here `__ for the definition of superspheres. + .. image:: images/XMLreference/ss.png + :width: 23% + :align: right + :target: https://github.com/google-deepmind/mujoco/blob/main/test/user/testdata/makemesh.xml - **resolution** integer >= 4: The discretization of both major and minor radii. + :at-val:`supersphere` (resolution, e, n) + A generalization of a sphere, also known as a superellipsoid (we use 'supersphere' since semiaxis rescaling is + performed by the :ref:`scale` attribute). If the **n** and **e** parameters are both 1, the + shape is a sphere. See `here `__ for more details. + + **resolution** integer >= 3: Longitude and latitude discretization. |br| **e**: real >= 0: The "east-west" exponent. |br| **n**: real >= 0: The "north-south" exponent. + .. image:: images/XMLreference/st.png + :width: 23% + :align: right + :target: https://github.com/google-deepmind/mujoco/blob/main/test/user/testdata/makemesh.xml + :at-val:`supertorus` (resolution, radius, s, t) A generalization of a torus with major radius of 1 and given minor radius. If the **s** and **t** parameters are - both 1, the shape is a torus. See `here `__ for details regarding - the definition of supertori. + both 1, the shape is a torus. See `here `__ for more details. Note that + this shape is inherently non-convex, and the :ref:`standard caveats` about mesh collisions apply. - **resolution** integer >= 4: The discretization of both major and minor radii. + **resolution** integer >= 3: Discretization of both circumfrences. |br| **radius**: real in (0, 1]: The minor radius of the torus. - |br| **s**: real > 0: The "squareness" of major sections. - |br| **t**: real > 0: The "squareness" of minor sections. + |br| **s**: real > 0: The "squareness" of minor sections. + |br| **t**: real > 0: The "squareness" of major sections. + + .. image:: images/XMLreference/w.png + :width: 23% + :align: right + :target: https://github.com/google-deepmind/mujoco/blob/main/test/user/testdata/makemesh.xml :at-val:`wedge` (res_phi, res_theta, fov_phi, fov_theta, gamma) - A slice of a unit spherical shell in spherical coordinates. + A slice of a unit spherical shell in spherical coordinates. This mesh is designed to be used by the :ref:`tactile + sensor`, which reports data at the vertices. **res_phi**: integer >= 0: The vertical resolution of the slice. |br| **res_theta**: integer >= 0: The horizontal resolution of the slice. - |br| **fov_phi**: real in (0, 180]: The horizontal field of view (longitude) in degrees. - |br| **fov_phi**: real in (0, 90): The vertical field of view (latitude) in degrees. + |br| **fov_phi**: real in (0, 180]: The horizontal field of view (degrees). + |br| **fov_phi**: real in (0, 90): The vertical field of view (degrees). |br| **gamma**: real in [0, 1]: Foveal deformation of the discretization. :at-val:`plate` (res_x, res_y) - A rectangular plate with resolution in each dimension. + A rectangular plate with given resolution in each dimension. This mesh is designed to be used by the :ref:`tactile + sensor`, which reports data at the vertices. **res_x**: integer > 0: The horizontal resolution of the plate. |br| **res_y**: integer > 0: The vertical resolution of the plate. diff --git a/doc/changelog.rst b/doc/changelog.rst index be0dc814..dbd0384b 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -55,8 +55,8 @@ Version 3.3.4 (July 8, 2025) function :ref:`mjs_setName` which allows checking for naming collisions at set-time rather than compile-time, for earlier catching of errors. Relatedly, the ``name`` attribute has been removed from all mjs elements. 4. For MJX, the ``mjx.Option`` dataclass now has private and public fields similar to ``mjx.Model`` and - ``mjx.Data``. Some fields are no longer publicly available due to differences in the - underlying implementations of this data structure. + ``mjx.Data``. Some fields are no longer publicly available due to differences in the + underlying implementations of this data structure. General ^^^^^^^ diff --git a/doc/computation/index.rst b/doc/computation/index.rst index aca4c663..7b78225b 100644 --- a/doc/computation/index.rst +++ b/doc/computation/index.rst @@ -1603,9 +1603,6 @@ native pipeline .. _coDistance: -Geom distance -^^^^^^^^^^^^^ - .. image:: ../images/computation/ccd_light.gif :width: 25% :align: right @@ -1616,28 +1613,30 @@ Geom distance :align: right :class: only-dark +Geom distance +^^^^^^^^^^^^^ + The narrow-phase collision functions described :ref:`above` drive the :ref:`mj_geomDistance` function and associated :ref:`collision-sensors`. Due to the limitations of MPR, the legacy pipeline will return incorrect values (top) except at very small distances relative to the geom sizes, and is discouraged for this use case. In contrast, the GJK-based native pipeline (bottom), computes the correct values at all distances. +.. _coDecomposition: + Convex decomposition ^^^^^^^^^^^^^^^^^^^^ In order to model a non-convex object other than a height field, the user must decompose it into a union of convex geoms -(which can be primitive shapes or meshes) and attach them to the same body. A height-field is essentially a shape that -is automatically-decomposed into prisms +(which can be primitive shapes or meshes) and attach them to the same body. The other exception to this rule (besides +height fields) are :ref:`Signed Distance Functions` (see documentation therein), which in certain cases (e.g., +`analytic SDFs `__) can be efficient, but +have other requirements and limitations. -Open mesh-decomposition tools like the -`CoACD library `__ can be used outside MuJoCo to automate this process. Finally, -all built-in collision functions can be replaced with custom callbacks. This can be used to incorporate a -general-purpose "triangle soup" collision detector for example. However we do not recommend such an approach. -Pre-processing the geometry and representing it as a union of convex geoms takes some work, but it pays off at runtime -and yields both faster and more stable simulation. - -The exception to this rule are :ref:`SDF plugins` (see documentation therein), which in -`certain cases `__ can be efficient, -but have other requirements and limitations. +Open source mesh-decomposition tools like the `CoACD library `__ can be used +outside MuJoCo to automate this process. Finally, all built-in collision functions can be replaced with custom +callbacks. This can be used to incorporate a general-purpose "triangle soup" collision detector for example. However we +do not recommend such an approach. Pre-processing the geometry and representing it as a union of convex geoms takes some +work, but it pays off at runtime and yields both faster and more stable simulation. .. _Pipeline: diff --git a/doc/images/XMLreference/c.png b/doc/images/XMLreference/c.png new file mode 100644 index 00000000..c9046097 Binary files /dev/null and b/doc/images/XMLreference/c.png differ diff --git a/doc/images/XMLreference/h.png b/doc/images/XMLreference/h.png new file mode 100644 index 00000000..3dd561b0 Binary files /dev/null and b/doc/images/XMLreference/h.png differ diff --git a/doc/images/XMLreference/s.png b/doc/images/XMLreference/s.png new file mode 100644 index 00000000..06e02b06 Binary files /dev/null and b/doc/images/XMLreference/s.png differ diff --git a/doc/images/XMLreference/ss.png b/doc/images/XMLreference/ss.png new file mode 100644 index 00000000..e9a6b327 Binary files /dev/null and b/doc/images/XMLreference/ss.png differ diff --git a/doc/images/XMLreference/st.png b/doc/images/XMLreference/st.png new file mode 100644 index 00000000..2a523d68 Binary files /dev/null and b/doc/images/XMLreference/st.png differ diff --git a/doc/images/XMLreference/w.png b/doc/images/XMLreference/w.png new file mode 100644 index 00000000..6da17dca Binary files /dev/null and b/doc/images/XMLreference/w.png differ diff --git a/doc/python.rst b/doc/python.rst index cf4c3dd2..abade998 100644 --- a/doc/python.rst +++ b/doc/python.rst @@ -590,6 +590,8 @@ attaching. However, it is possible to override the default behavior by setting ` worldframe_in_site = parent.attach(child, site=site, prefix='child-') worldframe_in_frame = parent.attach(child, frame=frame, prefix='child-') +.. _PyEditConvenience: + Convenience methods ------------------- @@ -641,6 +643,17 @@ The ``MjSpec`` object can be serialized with all of its assets using the functio can be either a path to a file or a file object. In order to load the spec from a zip file, use ``spec = MjSpec.from_zip(file)``, where ``file`` is a path to a zip file or a zip file object. +Mesh creation +^^^^^^^^^^^^^ +The :ref:`mjsMesh` object includes convenience methods for model creation with named attributes, corresponding to the +:ref:`mesh/builtin` semantics. See `specs_test.py +`__. + +.. code-block:: python + + mesh = spec.add_mesh(name='prism') + mesh.make_cone(nedge=5, radius=1) + .. _PyMJCF: Relationship to ``PyMJCF`` and ``bind`` diff --git a/test/user/testdata/makemesh.xml b/test/user/testdata/makemesh.xml index 9394c58e..77a46270 100644 --- a/test/user/testdata/makemesh.xml +++ b/test/user/testdata/makemesh.xml @@ -1,26 +1,207 @@ + + + + + + - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +