Skip to content

Commit

Permalink
Add attach tag to MJCF.
Browse files Browse the repository at this point in the history 
PiperOrigin-RevId: 651117953
Change-Id: I57b0e53ed44607d479b3785d908e0837c0804cf3
  • Loading branch information
@quagla
quagla authored and Copybara-Service committed Jul 10, 2024
1 parent 5b080ba commit 27b9ddd
Show file tree
Hide file tree
Showing 19 changed files with 419 additions and 248 deletions.
105 changes: 83 additions & 22 deletions doc/XMLreference.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -110,11 +110,11 @@ Meta elements

These elements are not strictly part of the low-level MJCF format definition, but rather instruct the compiler to
perform some operation on the model. A general property of meta-elements is that they disappear from the model upon
saving the XML. There are currently five meta-elements in MJCF:
saving the XML. There are currently six meta-elements in MJCF:

- :ref:`include<include>`, :ref:`frame<frame>`, and :ref:`replicate<replicate>` which are outside of the schema.
- :ref:`composite<body-composite>` and :ref:`flexcomp<body-flexcomp>` which are part of the schema, but serve to
procedurally generate other MJCF elements.
- :ref:`composite<body-composite>`, :ref:`flexcomp<body-flexcomp>` and :ref:`attach<body-attach>` which are part of the
schema, but serve to procedurally generate other MJCF elements.

.. _frame:

Expand Down Expand Up @@ -1739,6 +1739,24 @@ properties are grouped together.
definition could in fact come from a defaults class. The remaining material properties always apply.


.. _asset-model:

:el-prefix:`asset/` |-| **model** (*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This element specifies other MJCF models which may be used for :ref:`attachment<body-attach>` in the current model.

.. _asset-model-name:

:at:`name`: :at-val:`string, required`
Name of the sub-model, used for referencing in :ref:`attach<body-attach>`. If unspecified, the
:ref:`model name<mujoco-model>` is used.

.. _asset-model-file:

:at:`file`: :at-val:`string, required`
The file from which the sub-model will be loaded. Note that the sub-model must be a valid MJCF model.


.. _body:

**(world)body** (R)
Expand Down Expand Up @@ -2816,24 +2834,6 @@ the direction specified by the dir attribute. It does not have a full spatial fr
The specular color of the light.


.. _body-plugin:

:el-prefix:`body/` |-| **plugin** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Associate this body with an :ref:`engine plugin<exPlugin>`. Either :at:`plugin` or :at:`instance` are required.

.. _body-plugin-plugin:

:at:`plugin`: :at-val:`string, optional`
Plugin identifier, used for implicit plugin instantiation.

.. _body-plugin-instance:

:at:`instance`: :at-val:`string, optional`
Instance name, used for explicit plugin instantiation.


.. _body-composite:

:el-prefix:`body/` |-| **composite** (*)
Expand Down Expand Up @@ -3638,10 +3638,71 @@ Associate this flexcomp with an :ref:`engine plugin<exPlugin>`. Either :at:`plug
Instance name, used for explicit plugin instantiation.


.. _body-plugin:

:el-prefix:`body/` |-| **plugin** (?)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Associate this body with an :ref:`engine plugin<exPlugin>`. Either :at:`plugin` or :at:`instance` are required.

.. _body-plugin-plugin:

:at:`plugin`: :at-val:`string, optional`
Plugin identifier, used for implicit plugin instantiation.

.. _body-plugin-instance:

:at:`instance`: :at-val:`string, optional`
Instance name, used for explicit plugin instantiation.


.. _body-attach:

:el-prefix:`body/` |-| **attach** (*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The :el:`attach` element is used to insert a sub-tree of bodies from another model into this model's kinematic tree.
Unlike :ref:`include<include>`, which is implemented in the parser and is equivalent to copying and pasting XML from
one file into another, :el:`attach` is implemented in the model compiler. In order to use this element, the sub-model
must first be defined as an :ref:`asset<model-asset>`. When creating an attachment, the top body of the attached subtree
is specified, and all referencing elements outside the kinematic tree (e.g., sensors and actuators), are
also copied into the top-level model. Additionally, any elements referenced from within the attached subtree (e.g.
defaults and assets) will be copied in to the top-level model. :el:`attach` is a :ref:`meta-element`, so upon saving
all attachments will appear in the saved XML file.

.. admonition:: Known issues
:class: attention

The :el:`attach` meta-element is new and not well tested. Please report any issues you encounter to the development
team. Additionally, the following known limitations exist, to be addressed in a future release:

- The world body cannot be attached.
- An entire model cannot be attached (i.e. including all elements, referenced or not).
- All assets from the child model will be copied in, whether they are referenced or not.
- Self-attach or circular references are not checked for and will lead to infinite loops.
- :ref:`Keyframes<keyframe>` are not yet supported. When attaching, all keyframes will be deleted.

.. _body-attach-model:

:at:`model`: :at-val:`string, optional`
The sub-model from which to attach a subtree.

.. _body-attach-body:

:at:`body`: :at-val:`string, optional`
Name of the body in the sub-model to attach here. The body and its subtree will be attached.

.. _body-attach-prefix:

:at:`prefix`: :at-val:`string, optional`
Prefix to prepend to names of elements in the sub-model. If empty, the names are unchanged. This attribute is
required to prevent name collisions with the parent or when attaching the same sub-tree multiple times.


.. _body-frame:

:el-prefix:`body/` |-| **frame** (*)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Frames specify a coordinate transformation which is applied to all child elements. They disappear during compilation
and the transformation they encode is accumulated in their direct children. See :ref:`frame<frame>` for examples.
Expand Down
14 changes: 14 additions & 0 deletions doc/XMLschema.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,13 @@
| | | | :ref:`reflectance<asset-material-reflectance>` | :ref:`metallic<asset-material-metallic>` | :ref:`roughness<asset-material-roughness>` | :ref:`rgba<asset-material-rgba>` | |
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |_| asset |br| |_| |L| | | .. table:: |
| :ref:`model | \* | :class: mjcf-attributes |
| <asset-model>` | | |
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
| | | | :ref:`name<asset-model-name>` | :ref:`file<asset-model-file>` | | | |
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| mujoco |br| |L| | | .. table:: |
| :ref:`body | R | :class: mjcf-attributes |
| <body>` | | |
Expand Down Expand Up @@ -261,6 +268,13 @@
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |_| body |br| |_| |L| | | .. table:: |
| :ref:`attach | \* | :class: mjcf-attributes |
| <body-attach>` | | |
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
| | | | :ref:`model<body-attach-model>` | :ref:`body<body-attach-body>` | :ref:`prefix<body-attach-prefix>` | | |
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| |_| body |br| |_| |L| | | .. table:: |
| :ref:`site | \* | :class: mjcf-attributes |
| <body-site>` | | |
| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ |
Expand Down
27 changes: 15 additions & 12 deletions doc/changelog.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,27 +39,30 @@ General
:align: right
:width: 240px

7. Added support for orthographic cameras. This is available for both fixed cameras and the free camera, using the
7. Add :ref:`attach<body-attach>` meta-element to MJCF, which allows attaching a model to a body.
8. Added support for orthographic cameras. This is available for both fixed cameras and the free camera, using the
:ref:`camera/orthographic<body-camera-orthographic>` and :ref:`global/orthographic<visual-global-orthographic>`
attributes, respectively.
8. Added :ref:`maxhullvert<asset-mesh-maxhullvert>`, the maximum number of vertices in a mesh's convex hull.
9. Added :ref:`mj_setKeyframe` for saving the current state into a model keyframe.
10. Added support for ``ball`` joints in the URDF parser ("spherical" in URDF).
11. Replaced ``mjUSEDOUBLE`` which was previously hard-coded in
9. Added :ref:`maxhullvert<asset-mesh-maxhullvert>`, the maximum number of vertices in a mesh's convex hull.
10. Added :ref:`mj_setKeyframe` for saving the current state into a model keyframe.
11. Added support for ``ball`` joints in the URDF parser ("spherical" in URDF).
12. Deprecated :ref:`mju_rotVecMat` and :ref:`mju_rotVecMatT` in favor of :ref:`mju_mulMatVec3` and
:ref:`mju_mulMatTVec3`. These functions names and argument ordering are more consistent with the rest of the API.
13. Replaced ``mjUSEDOUBLE`` which was previously hard-coded in
`mjtnum.h <https://github.com/google-deepmind/mujoco/blob/main/include/mujoco/mjtnum.h>`__
with the build-time flag ``mjUSESINGLE``. If this symbol is not defined, MuJoCo will use double-precision floating
point, as usual. If ``mjUSESINGLE`` is defined, MuJoCo will use single-precision floating point. See :ref:`mjtNum`.

Relatedly, fixed various type errors that prevented building with single-precision.
12. Quaternions in ``mjData->qpos`` and ``mjData->mocap_quat`` are no longer normalized in-place by
14. Quaternions in ``mjData->qpos`` and ``mjData->mocap_quat`` are no longer normalized in-place by
:ref:`mj_kinematics`. Instead they are normalized when they are used. After the first step, quaternions in
``mjData->qpos`` will be normalized.

MJX
~~~
13. Added support for :ref:`elliptic friction cones<option-cone>`.
14. Fixed a bug that resulted in less-optimal linesearch solutions for some difficult constraint settings.
15. Fixed a bug in the Newton solver that sometimes resulted in less-optimal gradients.
15. Added support for :ref:`elliptic friction cones<option-cone>`.
16. Fixed a bug that resulted in less-optimal linesearch solutions for some difficult constraint settings.
17. Fixed a bug in the Newton solver that sometimes resulted in less-optimal gradients.


.. youtube:: P83tKA1iz2Y
Expand All @@ -68,14 +71,14 @@ MJX

Simulate
^^^^^^^^
16. Added improved tutorial video.
17. Improved the Brownian noise generator.
18. Added improved tutorial video.
19. Improved the Brownian noise generator.

|br| |br| |br| |br|

Python bindings
^^^^^^^^^^^^^^^
18. Fixed a memory leak when using ``copy.deepcopy()`` on a ``mujoco.MjData`` instance (:github:issue:`1572`).
20. Fixed a memory leak when using ``copy.deepcopy()`` on a ``mujoco.MjData`` instance (:github:issue:`1572`).

Version 3.1.6 (Jun 3, 2024)
---------------------------
Expand Down
Loading

0 comments on commit 27b9ddd

Please sign in to comment.