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

Improve plugin documentation.

Browse Source 
PiperOrigin-RevId: 690974299
Change-Id: Iadaabafb7434ada9579d6e2f64aae435cdfedbd8
This commit is contained in:
Yuval Tassa
2024-10-29 05:06:19 -07:00
committed by Copybara-Service
parent ce5f8b4728
commit 6703a40fcf
1 changed files with 54 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/programming/extension.rst
+54 -40
View File
@@ -201,22 +201,22 @@ the ``copy`` callback from :ref:`mjpPlugin` for each plugin instance present.
.. _exActuatorAct: .. _exActuatorAct:
Actuator activations Actuator states
"""""""""""""""""""" """""""""""""""
When writing stateful actuator plugins, there are two choices for where to save the actuator state. One option is using When writing stateful actuator plugins, there are two choices for where to save the actuator state. One option is using
``plugin_state`` as described above, and the other is to use ``mjData.act`` by implementing the ``actuator_actdim`` and ``plugin_state`` as described above, and the other is to use ``mjData.act`` by implementing the callback on
``actuator_act_dot`` callbacks on :ref:`mjpPlugin`. :ref:`mjpPlugin`.
When using the latter option, the actuator plugin's state will be added to ``mjData.act``, and MuJoCo will When using the latter option, the actuator plugin's state will be added to ``mjData.act``, and MuJoCo will
automatically integrate ``mjData.act_dot`` values between timesteps. One advantage of this approach is that automatically integrate ``mjData.act_dot`` values between timesteps. One advantage of this approach is that
finite-differencing functions like :ref:`mjd_transitionFD` will work as they do for native actuators. The finite-differencing functions like :ref:`mjd_transitionFD` will work as they do for native actuators. The
``mjpPlugin.advance`` callback will be called after ``act_dot`` is integrated, and actuator plugins may overwrite ``mjpPlugin.advance`` callback will be called after ``act_dot`` is integrated, and actuator plugins may overwrite
the ``act`` values at that point, if Euler integration isn't appropriate. the ``act`` values at that point, if the built-in integrator is not appropriate.
Users may specify the :ref:`dyntype<actuator-plugin-dyntype>` attribute on actuator plugins, to introduce a filter or Users may specify the :ref:`dyntype<actuator-plugin-dyntype>` attribute on actuator plugins, to introduce a filter or
an integrator between user inputs and actuator activations. When they do, the activation variable introduced by an integrator between user inputs and actuator states. When they do, the state variable introduced by
``dyntype`` will be placed *after* the plugin's activation variables in the ``act`` array. ``dyntype`` will be placed *after* the plugin's state variables in the ``act`` array.
.. _exRegistration: .. _exRegistration:
@@ -269,43 +269,57 @@ A future version of this section will include:
There are several first-party plugin directories: There are several first-party plugin directories:
* **actuator:** The plugins in the `actuator/ <https://github.com/google-deepmind/mujoco/tree/main/plugin/actuator>`__ actuator
directory implement custom actuators, so far only a PID controller. See the """"""""
`README <https://github.com/google-deepmind/mujoco/blob/main/plugin/actuator/README.md>`__ for details. The plugins in the `actuator/ <https://github.com/google-deepmind/mujoco/tree/main/plugin/actuator>`__ directory
* **elasticity:** The plugins in the `elasticity/ implement custom actuators, so far only a PID controller. See the `README
<https://github.com/google-deepmind/mujoco/tree/main/plugin/elasticity>`__ directory are passive forces based on <https://github.com/google-deepmind/mujoco/blob/main/plugin/actuator/README.md>`__ for details.
continuum mechanics for 1-dimensional and 2-dimensional bodies. The 1D model is invariant under rotations and captures
the large deformation of elastic cables, decoupling twisting and bending strains. The 2D model is a suitable for
computing the bending stiffness of thin elastic plates (i.e. shells having a flat stress-free configuration). In this
case, the elastic energy is quadratic and therefore the stiffness matrix is constant. For more information, please see
the `README <https://github.com/google-deepmind/mujoco/blob/main/plugin/elasticity/README.md>`__.
* **sensor:** The plugins in the `sensor/ <https://github.com/google-deepmind/mujoco/tree/main/plugin/sensor>`__
directory implement custom sensors. Currently the sole sensor plugin is the touch grid sensor, see the
`README <https://github.com/google-deepmind/mujoco/blob/main/plugin/sensor/README.md>`__ for details.
* **sdf:** The plugins in the `sdf/ <https://github.com/google-deepmind/mujoco/tree/main/plugin/sdf>`__ directory
specify custom shapes in a mesh-free manner, by defining methods computing a signed distance field and its gradient at
query points. This shape then acts as a new geom type in the collision table at the top of `engine_collision_driver.c
<https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_collision_driver.c>`__. For more information
concerning the available SDFs and how to write your own implicit geometry, please see the `README
<https://github.com/google-deepmind/mujoco/blob/main/plugin/sdf/README.md>`__. The rest of this section will give more
detail concerning the collision algorithm and the plugin engine interface.
Collision points are found by minimizing the function A + B + abs(max(A, B)), where A and B are the two colliding
SDFs, via gradient descent. Because SDFs are non-convex, multiple starting points are required in order to converge to
multiple local minima. The number of starting points is set using :ref:`sdf_initpoints<option-sdf_initpoints>`, and
are initialized using the Halton sequence inside the intersection of the axis-aligned bounding boxes. The number of
gradient descent iterations is set using :ref:`sdf_iterations<option-sdf_iterations>`.
While *exact* SDFs---encoding the precise signed distance to the surface---are preferred, collisions are possible with elasticity
any function whose value vanishes at the surface and grows monotonically away from it, with a negative sign in the """"""""""
interior. For such functions, it is still possible to find collisons, albeit with a possibly The plugins in the `elasticity/ <https://github.com/google-deepmind/mujoco/tree/main/plugin/elasticity>`__ directory are
increased number of starting points. passive forces based on continuum mechanics for 1-dimensional and 2-dimensional bodies. The 1D model is invariant under
rotations and captures the large deformation of elastic cables, decoupling twisting and bending strains. The 2D model is
a suitable for computing the bending stiffness of thin elastic plates (i.e. shells having a flat stress-free
configuration). In this case, the elastic energy is quadratic and therefore the stiffness matrix is constant. For more
information, please see the `README
<https://github.com/google-deepmind/mujoco/blob/main/plugin/elasticity/README.md>`__.
The ``sdf_distance`` method is called by the compiler to produce a visual mesh for rendering using the marching cubes
algorithm implemented by `MarchingCubeCpp <https://github.com/aparis69/MarchingCubeCpp>`__.
Future improvement to the gradient descent algorithm, such as a line search which takes advantage of the properties of sensor
SDFs, might reduce the number of iterations and/or starting points. """"""
The plugins in the `sensor/ <https://github.com/google-deepmind/mujoco/tree/main/plugin/sensor>`__ directory implement
custom sensors. Currently the sole sensor plugin is the touch grid sensor, see the `README
<https://github.com/google-deepmind/mujoco/blob/main/plugin/sensor/README.md>`__ for details.
sdf
"""
The plugins in the `sdf/ <https://github.com/google-deepmind/mujoco/tree/main/plugin/sdf>`__ directory
specify custom shapes in a mesh-free manner, by defining methods computing a signed distance field and its gradient at
query points. This shape then acts as a new geom type in the collision table at the top of `engine_collision_driver.c
<https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_collision_driver.c>`__. For more information
concerning the available SDFs and how to write your own implicit geometry, please see the `README
<https://github.com/google-deepmind/mujoco/blob/main/plugin/sdf/README.md>`__. The rest of this section will give more
detail concerning the collision algorithm and the plugin engine interface.
Collision points are found by minimizing the function A + B + abs(max(A, B)), where A and B are the two colliding
SDFs, via gradient descent. Because SDFs are non-convex, multiple starting points are required in order to converge to
multiple local minima. The number of starting points is set using :ref:`sdf_initpoints<option-sdf_initpoints>`, and
are initialized using the Halton sequence inside the intersection of the axis-aligned bounding boxes. The number of
gradient descent iterations is set using :ref:`sdf_iterations<option-sdf_iterations>`.
While *exact* SDFs---encoding the precise signed distance to the surface---are preferred, collisions are possible with
any function whose value vanishes at the surface and grows monotonically away from it, with a negative sign in the
interior. For such functions, it is still possible to find collisons, albeit with a possibly
increased number of starting points.
The ``sdf_distance`` method is called by the compiler to produce a visual mesh for rendering using the marching cubes
algorithm implemented by `MarchingCubeCpp <https://github.com/aparis69/MarchingCubeCpp>`__.
Future improvement to the gradient descent algorithm, such as a line search which takes advantage of the properties of
SDFs, might reduce the number of iterations and/or starting points.
For the sdf plugin, the following methods need to be specified For the sdf plugin, the following methods need to be specified