diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 1f6364d9..1a3288b9 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -96,7 +96,7 @@ jobs: -DCMAKE_CXX_COMPILER:STRING=clang++-10 -DMUJOCO_HARDEN:BOOL=ON tmpdir: "/tmp" - - os: macos-12 + - os: macos-13 cmake_args: >- -G Ninja -DMUJOCO_HARDEN:BOOL=ON @@ -239,7 +239,6 @@ jobs: - name: Test Python bindings if: ${{ runner.os != 'Windows' }} shell: bash - working-directory: python/dist env: MUJOCO_GL: disable run: > diff --git a/CMakeLists.txt b/CMakeLists.txt index 8f5e3df1..62a396ea 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -28,7 +28,7 @@ set(MSVC_INCREMENTAL_DEFAULT ON) project( mujoco - VERSION 3.2.5 + VERSION 3.3.1 DESCRIPTION "MuJoCo Physics Simulator" HOMEPAGE_URL "https://mujoco.org" ) diff --git a/README.md b/README.md index d5f5a27f..935c80b7 100644 --- a/README.md +++ b/README.md @@ -33,8 +33,9 @@ We also provide [Python bindings] and a plug-in for the [Unity] game engine. ## Documentation -MuJoCo's documentation can be found at [mujoco.readthedocs.io]. Upcoming features due for the next -release can be found in the [changelog] in the latest branch. +MuJoCo's documentation can be found at [mujoco.readthedocs.io]. Upcoming +features due for the next release can be found in the [changelog] in the +"latest" branch. ## Getting Started @@ -52,14 +53,19 @@ running on Google Colab: - The **introductory** tutorial teaches MuJoCo basics: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/tutorial.ipynb) - - The **LQR** tutorial synthesizes a linear-quadratic controller, balancing a humanoid on one leg: + - The **rollout** tutorial shows how to use the multithreaded `rollout` module: + [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/rollout.ipynb) + - The **LQR** tutorial synthesizes a linear-quadratic controller, balancing a + humanoid on one leg: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/LQR.ipynb) - - The **least-squares** tutorial explains how to use the Python-based nonlinear least-squares solver: + - The **least-squares** tutorial explains how to use the Python-based nonlinear + least-squares solver: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/least_squares.ipynb) - The **MJX** tutorial provides usage examples of [MuJoCo XLA](https://mujoco.readthedocs.io/en/stable/mjx.html), a branch of MuJoCo written in JAX: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/mjx/tutorial.ipynb) - - The **differentiable physics** tutorial trains locomotion policies with analytical gradients automatically derived from MuJoCo's physics step: + - The **differentiable physics** tutorial trains locomotion policies with + analytical gradients automatically derived from MuJoCo's physics step: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/mjx/training_apg.ipynb) ## Installation @@ -73,7 +79,7 @@ and macOS (universal). This is the recommended way to use the software. ### Building from source Users who wish to build MuJoCo from source should consult the [build from -source] section of the documentation. However, please note that the commit at +source] section of the documentation. However, note that the commit at the tip of the `main` branch may be unstable. ### Python (>= 3.9) @@ -109,7 +115,8 @@ GitHub [Issues](https://github.com/google-deepmind/mujoco/issues) are reserved for bug reports, feature requests and other development-related subjects. ## Related software -MuJoCo is the backbone for numerous environment packages. Below we list several bindings and converters. +MuJoCo is the backbone for numerous environment packages. Below we list several +bindings and converters. ### Bindings @@ -137,7 +144,6 @@ These packages give users of various languages access to MuJoCo functionality: - **Java**: [mujoco-java](https://github.com/CommonWealthRobotics/mujoco-java) - **Julia**: [MuJoCo.jl](https://github.com/JamieMair/MuJoCo.jl) - ### Converters - **OpenSim**: [MyoConverter](https://github.com/MyoHub/myoconverter) converts @@ -146,6 +152,8 @@ These packages give users of various languages access to MuJoCo functionality: two-way SDFormat <-> MJCF conversion tool. - **OBJ**: [obj2mjcf](https://github.com/kevinzakka/obj2mjcf) a script for converting composite OBJ files into a loadable MJCF model. +- **onshape**: [Onshape to Robot](https://github.com/rhoban/onshape-to-robot) + Converts [onshape](https://www.onshape.com/en/) CAD assemblies to MJCF. ## Citation @@ -184,7 +192,6 @@ This is not an officially supported Google product. [Getting Started]: https://mujoco.readthedocs.io/en/latest/programming#getting-started [Unity]: https://unity.com/ [releases page]: https://github.com/google-deepmind/mujoco/releases -[GitHub Issues]: https://github.com/google-deepmind/mujoco/issues [mujoco.readthedocs.io]: https://mujoco.readthedocs.io [changelog]: https://mujoco.readthedocs.io/en/latest/changelog.html [Python bindings]: https://mujoco.readthedocs.io/en/stable/python.html#python-bindings diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index c0f12f52..dfecb4ab 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -6,7 +6,7 @@ possible in your code contributions. ### Scope of this guide -MuJoCo has three main code categories: +Most of this guide involves C/C++ code. For Python, jump to the section [below](#python-code). For MuJoCo C/C++, code has three main categories: 1. **C code:** MuJoCo's core codebase. It consists of public headers under `include/` and C source files and internal headers under `src/`. This style @@ -158,3 +158,7 @@ example above. New code should use the C99 convention. When editing an existing function, please move existing variable declarations into local scope. Pull requests helping us to complete the migration are very welcome. + +### [Python code](#python-code) + +For Python code, run `pyink foo.py` to adhere to Google's [Python style guide](https://google.github.io/styleguide/pyguide.html). For sorting and cleaning imports, run `isort foo.py`. Both `pyink` and `isort` can be pip installed via `pip install pyink isort`. diff --git a/cmake/MujocoDependencies.cmake b/cmake/MujocoDependencies.cmake index 8d09b631..004aedc4 100644 --- a/cmake/MujocoDependencies.cmake +++ b/cmake/MujocoDependencies.cmake @@ -39,22 +39,22 @@ set(MUJOCO_DEP_VERSION_qhull CACHE STRING "Version of `qhull` to be fetched." ) set(MUJOCO_DEP_VERSION_Eigen3 - b396a6fbb2e173f52edb3360485dedf3389ef830 + 66f7f51b7e069d0a03a21157fa60b24aece69aeb CACHE STRING "Version of `Eigen3` to be fetched." ) set(MUJOCO_DEP_VERSION_abseil - 4447c7562e3bc702ade25105912dce503f0c4010 # LTS 20240722.0 + 9ac7062b1860d895fb5a8cbf58c3e9ef8f674b5f # LTS 20250127.0 CACHE STRING "Version of `abseil` to be fetched." ) set(MUJOCO_DEP_VERSION_gtest - b514bdc898e2951020cbdca1304b75f5950d1f59 # v1.15.2 + 6910c9d9165801d8827d628cb72eb7ea9dd538c5 # v1.16.0 CACHE STRING "Version of `gtest` to be fetched." ) set(MUJOCO_DEP_VERSION_benchmark - 7c8ed6b082aa3c7a3402f18e50da4480421d08fd # v1.8.4 + 049f6e79cc3e8636cec21bbd94ed185b4a5f2653 CACHE STRING "Version of `benchmark` to be fetched." ) diff --git a/dist/mujoco.rc b/dist/mujoco.rc index 9fec766a..171b9810 100644 --- a/dist/mujoco.rc +++ b/dist/mujoco.rc @@ -1,6 +1,6 @@ 1 VERSIONINFO -FILEVERSION 3,2,5,0 -PRODUCTVERSION 3,2,5,0 +FILEVERSION 3,3,1,0 +PRODUCTVERSION 3,3,1,0 FILEOS 0x4 FILETYPE 0x1 { @@ -9,9 +9,9 @@ FILETYPE 0x1 BLOCK "040904b0" { VALUE "ProductName", "MuJoCo" - VALUE "ProductVersion", "3.2.5" + VALUE "ProductVersion", "3.3.1" VALUE "FileDescription", "MuJoCo" - VALUE "FileVersion", "3.2.5" + VALUE "FileVersion", "3.3.1" VALUE "InternalName", "mujoco.dll" VALUE "OriginalFilename", "mujoco.dll" VALUE "CompanyName", "Google DeepMind" diff --git a/dist/simulate.rc b/dist/simulate.rc index 2fbbf3aa..7a2492ad 100644 --- a/dist/simulate.rc +++ b/dist/simulate.rc @@ -1,8 +1,8 @@ MUJOCO ICON "mujoco.ico" 1 VERSIONINFO -FILEVERSION 3,2,5,0 -PRODUCTVERSION 3,2,5,0 +FILEVERSION 3,3,1,0 +PRODUCTVERSION 3,3,1,0 FILEOS 0x4 FILETYPE 0x1 { @@ -11,9 +11,9 @@ FILETYPE 0x1 BLOCK "040904b0" { VALUE "ProductName", "MuJoCo" - VALUE "ProductVersion", "3.2.5" + VALUE "ProductVersion", "3.3.1" VALUE "FileDescription", "MuJoCo" - VALUE "FileVersion", "3.2.5" + VALUE "FileVersion", "3.3.1" VALUE "InternalName", "simulate.exe" VALUE "OriginalFilename", "simulate.exe" VALUE "CompanyName", "Google DeepMind" diff --git a/doc/APIreference/APIfunctions.rst b/doc/APIreference/APIfunctions.rst index 824221b6..e64a33ca 100644 --- a/doc/APIreference/APIfunctions.rst +++ b/doc/APIreference/APIfunctions.rst @@ -1,3 +1,8 @@ +.. raw:: html + +
+ + .. _API: ========= diff --git a/doc/APIreference/APIglobals.rst b/doc/APIreference/APIglobals.rst index 91a506b7..c116257a 100644 --- a/doc/APIreference/APIglobals.rst +++ b/doc/APIreference/APIglobals.rst @@ -517,7 +517,7 @@ shown in the table below. Their names are in the format ``mjKEY_XXX``. They corr - Maximum number of UI rectangles. Defined in `mjui.h `_. * - ``mjVERSION_HEADER`` - - 325 + - 331 - The version of the MuJoCo headers; changes with every release. This is an integer equal to 100x the software version, so 210 corresponds to version 2.1. Defined in mujoco.h. The API function :ref:`mj_version` returns a number with the same meaning but for the compiled library. diff --git a/doc/APIreference/APItypes.rst b/doc/APIreference/APItypes.rst index d9ca5fd3..7e2befa0 100644 --- a/doc/APIreference/APItypes.rst +++ b/doc/APIreference/APItypes.rst @@ -28,7 +28,7 @@ MuJoCo defines a large number of types: - :ref:`mjOption` (embedded in :ref:`mjModel`). - :ref:`mjData`. - - :ref:`Auxillary struct types`, also used by the engine. + - :ref:`Auxiliary struct types`, also used by the engine. - Structs for collecting :ref:`simulation statistics`. - Structs for :ref:`abstract visualization`. - Structs used by the :ref:`openGL renderer`. @@ -752,7 +752,7 @@ modifiable inputs and write their outputs. .. _tyAuxStructure: -Auxillary +Auxiliary ^^^^^^^^^ These struct types are used in the engine and their names are prefixed with ``mj``. :ref:`mjVisual` @@ -1140,6 +1140,16 @@ behavior. .. mujoco-include:: mjsElement +.. _mjsCompiler: + +mjsCompiler +~~~~~~~~~~~ + +Compiler options. + +.. mujoco-include:: mjsCompiler + + .. _mjsBody: mjsBody diff --git a/doc/APIreference/functions.rst b/doc/APIreference/functions.rst index 0ce805ce..7ca8f985 100644 --- a/doc/APIreference/functions.rst +++ b/doc/APIreference/functions.rst @@ -13,8 +13,8 @@ The model and all files referenced in it can be loaded from disk or from a VFS w .. _mj_loadXML: -mj_loadXML -~~~~~~~~~~ +`mj_loadXML <#mj_loadXML>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_loadXML @@ -24,8 +24,8 @@ If error is not NULL, it must have size error_sz. .. _mj_parseXML: -mj_parseXML -~~~~~~~~~~~ +`mj_parseXML <#mj_parseXML>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_parseXML @@ -33,8 +33,8 @@ Parse spec from XML file. .. _mj_parseXMLString: -mj_parseXMLString -~~~~~~~~~~~~~~~~~ +`mj_parseXMLString <#mj_parseXMLString>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_parseXMLString @@ -42,8 +42,8 @@ Parse spec from XML string. .. _mj_compile: -mj_compile -~~~~~~~~~~ +`mj_compile <#mj_compile>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_compile @@ -53,8 +53,8 @@ If compilation fails, :ref:`mj_compile` returns ``NULL``; the error can be read .. _mj_recompile: -mj_recompile -~~~~~~~~~~~~ +`mj_recompile <#mj_recompile>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_recompile @@ -70,18 +70,22 @@ instances will be deleted; as in :ref:`mj_compile`, the compilation error can be .. _mj_saveLastXML: -mj_saveLastXML -~~~~~~~~~~~~~~ +`mj_saveLastXML <#mj_saveLastXML>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_saveLastXML -Update XML data structures with info from low-level model, save as MJCF. +Update XML data structures with info from low-level model created with :ref:`mj_loadXML`, save as MJCF. If error is not NULL, it must have size error_sz. +Note that this function only saves models that have been loaded with :ref:`mj_loadXML`, the legacy loading mechanism. +See the :ref:`model editing` chapter to understand the difference between the old and new model loading and +saving mechanisms. + .. _mj_freeLastXML: -mj_freeLastXML -~~~~~~~~~~~~~~ +`mj_freeLastXML <#mj_freeLastXML>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_freeLastXML @@ -89,21 +93,22 @@ Free last XML model if loaded. Called internally at each load. .. _mj_saveXMLString: -mj_saveXMLString -~~~~~~~~~~~~~~~~ +`mj_saveXMLString <#mj_saveXMLString>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_saveXMLString -Save spec to XML string, return 1 on success, 0 otherwise. XML saving requires that the spec first be compiled. +Save spec to XML string, return 0 on success, -1 on failure. If the length of the output buffer is too small, returns +the required size. XML saving automatically compiles the spec before saving. .. _mj_saveXML: -mj_saveXML -~~~~~~~~~~ +`mj_saveXML <#mj_saveXML>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_saveXML -Save spec to XML file, return 1 on success, 0 otherwise. XML saving requires that the spec first be compiled. +Save spec to XML file, return 0 on success, -1 otherwise. XML saving requires that the spec first be compiled. .. _Mainsimulation: @@ -136,8 +141,8 @@ depend on qpos. Calling the dynamics with skipstage = :ref:`mjSTAGE_POS`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_step @@ -145,8 +150,8 @@ Advance simulation, use control callback to obtain external force and control. .. _mj_step1: -mj_step1 -~~~~~~~~ +`mj_step1 <#mj_step1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_step1 @@ -154,8 +159,8 @@ Advance simulation in two steps: before external force and control is set by use .. _mj_step2: -mj_step2 -~~~~~~~~ +`mj_step2 <#mj_step2>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_step2 @@ -163,8 +168,8 @@ Advance simulation in two steps: after external force and control is set by user .. _mj_forward: -mj_forward -~~~~~~~~~~ +`mj_forward <#mj_forward>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_forward @@ -172,8 +177,8 @@ Forward dynamics: same as mj_step but do not integrate in time. .. _mj_inverse: -mj_inverse -~~~~~~~~~~ +`mj_inverse <#mj_inverse>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_inverse @@ -181,8 +186,8 @@ Inverse dynamics: qacc must be set before calling. .. _mj_forwardSkip: -mj_forwardSkip -~~~~~~~~~~~~~~ +`mj_forwardSkip <#mj_forwardSkip>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_forwardSkip @@ -190,8 +195,8 @@ Forward dynamics with skip; skipstage is mjtStage. .. _mj_inverseSkip: -mj_inverseSkip -~~~~~~~~~~~~~~ +`mj_inverseSkip <#mj_inverseSkip>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_inverseSkip @@ -208,8 +213,8 @@ computations, and are documented in more detail below. .. _mj_stateSize: -mj_stateSize -~~~~~~~~~~~~ +`mj_stateSize <#mj_stateSize>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_stateSize @@ -218,8 +223,8 @@ correspond to element fields of :ref:`mjtState`. .. _mj_getState: -mj_getState -~~~~~~~~~~~ +`mj_getState <#mj_getState>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_getState @@ -228,8 +233,8 @@ Copy concatenated state components specified by ``spec`` from ``d`` into ``state .. _mj_setState: -mj_setState -~~~~~~~~~~~ +`mj_setState <#mj_setState>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_setState @@ -238,8 +243,8 @@ Copy concatenated state components specified by ``spec`` from ``state`` into `` .. _mj_setKeyframe: -mj_setKeyframe -~~~~~~~~~~~~~~ +`mj_setKeyframe <#mj_setKeyframe>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_setKeyframe @@ -247,8 +252,8 @@ Copy current state to the k-th model keyframe. .. _mj_addContact: -mj_addContact -~~~~~~~~~~~~~ +`mj_addContact <#mj_addContact>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_addContact @@ -256,8 +261,8 @@ Add contact to d->contact list; return 0 if success; 1 if buffer full. .. _mj_isPyramidal: -mj_isPyramidal -~~~~~~~~~~~~~~ +`mj_isPyramidal <#mj_isPyramidal>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_isPyramidal @@ -265,8 +270,8 @@ Determine type of friction cone. .. _mj_isSparse: -mj_isSparse -~~~~~~~~~~~ +`mj_isSparse <#mj_isSparse>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_isSparse @@ -274,8 +279,8 @@ Determine type of constraint Jacobian. .. _mj_isDual: -mj_isDual -~~~~~~~~~ +`mj_isDual <#mj_isDual>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_isDual @@ -283,8 +288,8 @@ Determine type of solver (PGS is dual, CG and Newton are primal). .. _mj_mulJacVec: -mj_mulJacVec -~~~~~~~~~~~~ +`mj_mulJacVec <#mj_mulJacVec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_mulJacVec @@ -293,8 +298,8 @@ sparse; the function is aware of this setting. Multiplication by J maps velociti .. _mj_mulJacTVec: -mj_mulJacTVec -~~~~~~~~~~~~~ +`mj_mulJacTVec <#mj_mulJacTVec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_mulJacTVec @@ -303,8 +308,8 @@ space. .. _mj_jac: -mj_jac -~~~~~~ +`mj_jac <#mj_jac>`__ +~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_jac @@ -320,8 +325,8 @@ by :ref:`mj_comPos`. .. _mj_jacBody: -mj_jacBody -~~~~~~~~~~ +`mj_jacBody <#mj_jacBody>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_jacBody @@ -330,8 +335,8 @@ site. They are just shortcuts; the same can be achieved by calling mj_jac direct .. _mj_jacBodyCom: -mj_jacBodyCom -~~~~~~~~~~~~~ +`mj_jacBodyCom <#mj_jacBodyCom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_jacBodyCom @@ -339,8 +344,8 @@ Compute body center-of-mass end-effector Jacobian. .. _mj_jacSubtreeCom: -mj_jacSubtreeCom -~~~~~~~~~~~~~~~~ +`mj_jacSubtreeCom <#mj_jacSubtreeCom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_jacSubtreeCom @@ -348,8 +353,8 @@ Compute subtree center-of-mass end-effector Jacobian. .. _mj_jacGeom: -mj_jacGeom -~~~~~~~~~~ +`mj_jacGeom <#mj_jacGeom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_jacGeom @@ -357,8 +362,8 @@ Compute geom end-effector Jacobian. .. _mj_jacSite: -mj_jacSite -~~~~~~~~~~ +`mj_jacSite <#mj_jacSite>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_jacSite @@ -366,8 +371,8 @@ Compute site end-effector Jacobian. .. _mj_jacPointAxis: -mj_jacPointAxis -~~~~~~~~~~~~~~~ +`mj_jacPointAxis <#mj_jacPointAxis>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_jacPointAxis @@ -375,8 +380,8 @@ Compute translation end-effector Jacobian of point, and rotation Jacobian of axi .. _mj_jacDot: -mj_jacDot -~~~~~~~~~ +`mj_jacDot <#mj_jacDot>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_jacDot @@ -387,8 +392,8 @@ consistent with the current generalized positions and velocities ``mjData.{qpos, .. _mj_angmomMat: -mj_angmomMat -~~~~~~~~~~~~ +`mj_angmomMat <#mj_angmomMat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_angmomMat @@ -399,8 +404,8 @@ and :math:`\dot q` is the generalized velocity ``mjData.qvel``, then :math:`h = .. _mj_name2id: -mj_name2id -~~~~~~~~~~ +`mj_name2id <#mj_name2id>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_name2id @@ -408,8 +413,8 @@ Get id of object with the specified mjtObj type and name, returns -1 if id not f .. _mj_id2name: -mj_id2name -~~~~~~~~~~ +`mj_id2name <#mj_id2name>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_id2name @@ -417,17 +422,18 @@ Get name of object with the specified mjtObj type and id, returns NULL if name n .. _mj_fullM: -mj_fullM -~~~~~~~~ +`mj_fullM <#mj_fullM>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_fullM -Convert sparse inertia matrix M into full (i.e. dense) matrix. +Convert sparse inertia matrix ``M`` into full (i.e. dense) matrix. +|br| ``dst`` must be of size ``nv x nv``, ``M`` must be of the same size as ``mjData.qM``. .. _mj_mulM: -mj_mulM -~~~~~~~ +`mj_mulM <#mj_mulM>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_mulM @@ -438,8 +444,8 @@ sparsity. .. _mj_mulM2: -mj_mulM2 -~~~~~~~~ +`mj_mulM2 <#mj_mulM2>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_mulM2 @@ -447,8 +453,8 @@ Multiply vector by (inertia matrix)^(1/2). .. _mj_addM: -mj_addM -~~~~~~~ +`mj_addM <#mj_addM>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_addM @@ -457,8 +463,8 @@ Destination can be sparse uncompressed, or dense when all int* are NULL .. _mj_applyFT: -mj_applyFT -~~~~~~~~~~ +`mj_applyFT <#mj_applyFT>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_applyFT @@ -468,8 +474,8 @@ we want to add the result to a different vector. .. _mj_objectVelocity: -mj_objectVelocity -~~~~~~~~~~~~~~~~~ +`mj_objectVelocity <#mj_objectVelocity>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_objectVelocity @@ -477,8 +483,8 @@ Compute object 6D velocity (rot:lin) in object-centered frame, world/local orien .. _mj_objectAcceleration: -mj_objectAcceleration -~~~~~~~~~~~~~~~~~~~~~ +`mj_objectAcceleration <#mj_objectAcceleration>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_objectAcceleration @@ -488,8 +494,8 @@ mjData.cacc -- the total body acceleration, including contributions from the con .. _mj_geomDistance: -mj_geomDistance -~~~~~~~~~~~~~~~ +`mj_geomDistance <#mj_geomDistance>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_geomDistance @@ -497,21 +503,16 @@ Returns the smallest signed distance between two geoms and optionally the segmen Returned distances are bounded from above by ``distmax``. |br| If no collision of distance smaller than ``distmax`` is found, the function will return ``distmax`` and ``fromto``, if given, will be set to (0, 0, 0, 0, 0, 0). -.. admonition:: Positive ``distmax`` values - :class: note + .. admonition:: different (correct) behavior under `nativeccd` + :class: note - .. TODO: b/339596989 - Improve mjc_Convex. - - For some colliders, a large, positive ``distmax`` will result in an accurate measurement. However, for collision - pairs which use the general ``mjc_Convex`` collider, the result will be approximate and likely innacurate. - This is considered a bug to be fixed in a future release. - In order to determine whether a geom pair uses ``mjc_Convex``, inspect the table at the top of - `engine_collision_driver.c `__. + As explained in :ref:`Collision Detection`, distances are inaccurate when using the + :ref:`legacy CCD pipeline`, and its use is discouraged. .. _mj_contactForce: -mj_contactForce -~~~~~~~~~~~~~~~ +`mj_contactForce <#mj_contactForce>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_contactForce @@ -519,8 +520,8 @@ Extract 6D force:torque given contact id, in the contact frame. .. _mj_differentiatePos: -mj_differentiatePos -~~~~~~~~~~~~~~~~~~~ +`mj_differentiatePos <#mj_differentiatePos>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_differentiatePos @@ -532,8 +533,8 @@ inputs have dimensionality nq. .. _mj_integratePos: -mj_integratePos -~~~~~~~~~~~~~~~ +`mj_integratePos <#mj_integratePos>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_integratePos @@ -542,8 +543,8 @@ format of qpos. .. _mj_normalizeQuat: -mj_normalizeQuat -~~~~~~~~~~~~~~~~ +`mj_normalizeQuat <#mj_normalizeQuat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_normalizeQuat @@ -551,8 +552,8 @@ Normalize all quaternions in qpos-type vector. .. _mj_local2Global: -mj_local2Global -~~~~~~~~~~~~~~~ +`mj_local2Global <#mj_local2Global>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_local2Global @@ -560,8 +561,8 @@ Map from body local to global Cartesian coordinates, sameframe takes values from .. _mj_getTotalmass: -mj_getTotalmass -~~~~~~~~~~~~~~~ +`mj_getTotalmass <#mj_getTotalmass>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_getTotalmass @@ -569,8 +570,8 @@ Sum all body masses. .. _mj_setTotalmass: -mj_setTotalmass -~~~~~~~~~~~~~~~ +`mj_setTotalmass <#mj_setTotalmass>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_setTotalmass @@ -578,8 +579,8 @@ Scale body masses and inertias to achieve specified total mass. .. _mj_getPluginConfig: -mj_getPluginConfig -~~~~~~~~~~~~~~~~~~ +`mj_getPluginConfig <#mj_getPluginConfig>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_getPluginConfig @@ -588,8 +589,8 @@ NULL: invalid plugin instance ID or attribute name .. _mj_loadPluginLibrary: -mj_loadPluginLibrary -~~~~~~~~~~~~~~~~~~~~ +`mj_loadPluginLibrary <#mj_loadPluginLibrary>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_loadPluginLibrary @@ -597,8 +598,8 @@ Load a dynamic library. The dynamic library is assumed to register one or more p .. _mj_loadAllPluginLibraries: -mj_loadAllPluginLibraries -~~~~~~~~~~~~~~~~~~~~~~~~~ +`mj_loadAllPluginLibraries <#mj_loadAllPluginLibraries>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_loadAllPluginLibraries @@ -608,8 +609,8 @@ for each dynamic library encountered that registers plugins. .. _mj_version: -mj_version -~~~~~~~~~~ +`mj_version <#mj_version>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_version @@ -617,8 +618,8 @@ Return version number: 1.0.2 is encoded as 102. .. _mj_versionString: -mj_versionString -~~~~~~~~~~~~~~~~ +`mj_versionString <#mj_versionString>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_versionString @@ -634,8 +635,8 @@ These are components of the simulation pipeline, called internally from :ref:`mj .. _mj_fwdPosition: -mj_fwdPosition -~~~~~~~~~~~~~~ +`mj_fwdPosition <#mj_fwdPosition>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_fwdPosition @@ -643,8 +644,8 @@ Run position-dependent computations. .. _mj_fwdVelocity: -mj_fwdVelocity -~~~~~~~~~~~~~~ +`mj_fwdVelocity <#mj_fwdVelocity>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_fwdVelocity @@ -652,8 +653,8 @@ Run velocity-dependent computations. .. _mj_fwdActuation: -mj_fwdActuation -~~~~~~~~~~~~~~~ +`mj_fwdActuation <#mj_fwdActuation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_fwdActuation @@ -661,8 +662,8 @@ Compute actuator force qfrc_actuator. .. _mj_fwdAcceleration: -mj_fwdAcceleration -~~~~~~~~~~~~~~~~~~ +`mj_fwdAcceleration <#mj_fwdAcceleration>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_fwdAcceleration @@ -670,8 +671,8 @@ Add up all non-constraint forces, compute qacc_smooth. .. _mj_fwdConstraint: -mj_fwdConstraint -~~~~~~~~~~~~~~~~ +`mj_fwdConstraint <#mj_fwdConstraint>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_fwdConstraint @@ -679,8 +680,8 @@ Run selected constraint solver. .. _mj_Euler: -mj_Euler -~~~~~~~~ +`mj_Euler <#mj_Euler>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_Euler @@ -688,8 +689,8 @@ Euler integrator, semi-implicit in velocity. .. _mj_RungeKutta: -mj_RungeKutta -~~~~~~~~~~~~~ +`mj_RungeKutta <#mj_RungeKutta>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_RungeKutta @@ -697,8 +698,8 @@ Runge-Kutta explicit order-N integrator. .. _mj_implicit: -mj_implicit -~~~~~~~~~~~ +`mj_implicit <#mj_implicit>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_implicit @@ -708,8 +709,8 @@ Integrates the simulation state using an implicit-in-velocity integrator (either .. _mj_invPosition: -mj_invPosition -~~~~~~~~~~~~~~ +`mj_invPosition <#mj_invPosition>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_invPosition @@ -717,8 +718,8 @@ Run position-dependent computations in inverse dynamics. .. _mj_invVelocity: -mj_invVelocity -~~~~~~~~~~~~~~ +`mj_invVelocity <#mj_invVelocity>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_invVelocity @@ -726,8 +727,8 @@ Run velocity-dependent computations in inverse dynamics. .. _mj_invConstraint: -mj_invConstraint -~~~~~~~~~~~~~~~~ +`mj_invConstraint <#mj_invConstraint>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_invConstraint @@ -735,8 +736,8 @@ Apply the analytical formula for inverse constraint dynamics. .. _mj_compareFwdInv: -mj_compareFwdInv -~~~~~~~~~~~~~~~~ +`mj_compareFwdInv <#mj_compareFwdInv>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_compareFwdInv @@ -752,8 +753,8 @@ that the user will need to call them. .. _mj_sensorPos: -mj_sensorPos -~~~~~~~~~~~~ +`mj_sensorPos <#mj_sensorPos>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_sensorPos @@ -761,8 +762,8 @@ Evaluate position-dependent sensors. .. _mj_sensorVel: -mj_sensorVel -~~~~~~~~~~~~ +`mj_sensorVel <#mj_sensorVel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_sensorVel @@ -770,8 +771,8 @@ Evaluate velocity-dependent sensors. .. _mj_sensorAcc: -mj_sensorAcc -~~~~~~~~~~~~ +`mj_sensorAcc <#mj_sensorAcc>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_sensorAcc @@ -779,8 +780,8 @@ Evaluate acceleration and force-dependent sensors. .. _mj_energyPos: -mj_energyPos -~~~~~~~~~~~~ +`mj_energyPos <#mj_energyPos>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_energyPos @@ -788,8 +789,8 @@ Evaluate position-dependent energy (potential). .. _mj_energyVel: -mj_energyVel -~~~~~~~~~~~~ +`mj_energyVel <#mj_energyVel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_energyVel @@ -797,8 +798,8 @@ Evaluate velocity-dependent energy (kinetic). .. _mj_checkPos: -mj_checkPos -~~~~~~~~~~~ +`mj_checkPos <#mj_checkPos>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_checkPos @@ -806,8 +807,8 @@ Check qpos, reset if any element is too big or nan. .. _mj_checkVel: -mj_checkVel -~~~~~~~~~~~ +`mj_checkVel <#mj_checkVel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_checkVel @@ -815,8 +816,8 @@ Check qvel, reset if any element is too big or nan. .. _mj_checkAcc: -mj_checkAcc -~~~~~~~~~~~ +`mj_checkAcc <#mj_checkAcc>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_checkAcc @@ -824,8 +825,8 @@ Check qacc, reset if any element is too big or nan. .. _mj_kinematics: -mj_kinematics -~~~~~~~~~~~~~ +`mj_kinematics <#mj_kinematics>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_kinematics @@ -833,8 +834,8 @@ Run forward kinematics. .. _mj_comPos: -mj_comPos -~~~~~~~~~ +`mj_comPos <#mj_comPos>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_comPos @@ -842,8 +843,8 @@ Map inertias and motion dofs to global frame centered at CoM. .. _mj_camlight: -mj_camlight -~~~~~~~~~~~ +`mj_camlight <#mj_camlight>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_camlight @@ -851,8 +852,8 @@ Compute camera and light positions and orientations. .. _mj_flex: -mj_flex -~~~~~~~ +`mj_flex <#mj_flex>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_flex @@ -860,8 +861,8 @@ Compute flex-related quantities. .. _mj_tendon: -mj_tendon -~~~~~~~~~ +`mj_tendon <#mj_tendon>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_tendon @@ -869,8 +870,8 @@ Compute tendon lengths, velocities and moment arms. .. _mj_transmission: -mj_transmission -~~~~~~~~~~~~~~~ +`mj_transmission <#mj_transmission>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_transmission @@ -878,8 +879,8 @@ Compute actuator transmission lengths and moments. .. _mj_crb: -mj_crb -~~~~~~ +`mj_crb <#mj_crb>`__ +~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_crb @@ -887,8 +888,8 @@ Run composite rigid body inertia algorithm (CRB). .. _mj_factorM: -mj_factorM -~~~~~~~~~~ +`mj_factorM <#mj_factorM>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_factorM @@ -896,8 +897,8 @@ Compute sparse :math:`L^T D L` factorizaton of inertia matrix. .. _mj_solveM: -mj_solveM -~~~~~~~~~ +`mj_solveM <#mj_solveM>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_solveM @@ -905,8 +906,8 @@ Solve linear system :math:`M x = y` using factorization: :math:`x = (L^T D L)^{- .. _mj_solveM2: -mj_solveM2 -~~~~~~~~~~ +`mj_solveM2 <#mj_solveM2>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_solveM2 @@ -914,8 +915,8 @@ Half of linear solve: :math:`x = \sqrt{D^{-1}} (L^T)^{-1} y` .. _mj_comVel: -mj_comVel -~~~~~~~~~ +`mj_comVel <#mj_comVel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_comVel @@ -923,8 +924,8 @@ Compute cvel, cdof_dot. .. _mj_passive: -mj_passive -~~~~~~~~~~ +`mj_passive <#mj_passive>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_passive @@ -932,8 +933,8 @@ Compute qfrc_passive from spring-dampers, gravity compensation and fluid forces. .. _mj_subtreeVel: -mj_subtreeVel -~~~~~~~~~~~~~ +`mj_subtreeVel <#mj_subtreeVel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_subtreeVel @@ -944,8 +945,8 @@ It is also triggered for :ref:`user sensors` of :ref:`stage`__ +~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_rne @@ -954,8 +955,8 @@ assumes :math:`\ddot q = 0`). .. _mj_rnePostConstraint: -mj_rnePostConstraint -~~~~~~~~~~~~~~~~~~~~ +`mj_rnePostConstraint <#mj_rnePostConstraint>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_rnePostConstraint @@ -977,8 +978,8 @@ the effect of spatial tendons, see :github:issue:`832`. .. _mj_collision: -mj_collision -~~~~~~~~~~~~ +`mj_collision <#mj_collision>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_collision @@ -986,8 +987,8 @@ Run collision detection. .. _mj_makeConstraint: -mj_makeConstraint -~~~~~~~~~~~~~~~~~ +`mj_makeConstraint <#mj_makeConstraint>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_makeConstraint @@ -995,8 +996,8 @@ Construct constraints. .. _mj_island: -mj_island -~~~~~~~~~ +`mj_island <#mj_island>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_island @@ -1004,8 +1005,8 @@ Find constraint islands. .. _mj_projectConstraint: -mj_projectConstraint -~~~~~~~~~~~~~~~~~~~~ +`mj_projectConstraint <#mj_projectConstraint>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_projectConstraint @@ -1013,8 +1014,8 @@ Compute inverse constraint inertia efc_AR. .. _mj_referenceConstraint: -mj_referenceConstraint -~~~~~~~~~~~~~~~~~~~~~~ +`mj_referenceConstraint <#mj_referenceConstraint>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_referenceConstraint @@ -1022,8 +1023,8 @@ Compute efc_vel, efc_aref. .. _mj_constraintUpdate: -mj_constraintUpdate -~~~~~~~~~~~~~~~~~~~ +`mj_constraintUpdate <#mj_constraintUpdate>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_constraintUpdate @@ -1047,8 +1048,8 @@ rays from a single point. .. _mj_multiRay: -mj_multiRay -~~~~~~~~~~~ +`mj_multiRay <#mj_multiRay>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_multiRay @@ -1057,8 +1058,8 @@ Similar semantics to mj_ray, but vec is an array of (nray x 3) directions. .. _mj_ray: -mj_ray -~~~~~~ +`mj_ray <#mj_ray>`__ +~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_ray @@ -1075,8 +1076,8 @@ bodyexclude=-1 can be used to indicate that all bodies are included. .. _mj_rayHfield: -mj_rayHfield -~~~~~~~~~~~~ +`mj_rayHfield <#mj_rayHfield>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_rayHfield @@ -1084,8 +1085,8 @@ Intersect ray with hfield, return nearest distance or -1 if no intersection. .. _mj_rayMesh: -mj_rayMesh -~~~~~~~~~~ +`mj_rayMesh <#mj_rayMesh>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_rayMesh @@ -1093,8 +1094,8 @@ Intersect ray with mesh, return nearest distance or -1 if no intersection. .. _mju_rayGeom: -mju_rayGeom -~~~~~~~~~~~ +`mju_rayGeom <#mju_rayGeom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_rayGeom @@ -1102,8 +1103,8 @@ Intersect ray with pure geom, return nearest distance or -1 if no intersection. .. _mju_rayFlex: -mju_rayFlex -~~~~~~~~~~~ +`mju_rayFlex <#mju_rayFlex>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_rayFlex @@ -1112,8 +1113,8 @@ and also output nearest vertex id. .. _mju_raySkin: -mju_raySkin -~~~~~~~~~~~ +`mju_raySkin <#mju_raySkin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_raySkin @@ -1129,8 +1130,8 @@ These functions can be used to print various quantities to the screen for debugg .. _mj_printFormattedModel: -mj_printFormattedModel -~~~~~~~~~~~~~~~~~~~~~~ +`mj_printFormattedModel <#mj_printFormattedModel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_printFormattedModel @@ -1139,8 +1140,8 @@ float_format must be a valid printf-style format string for a single float value .. _mj_printModel: -mj_printModel -~~~~~~~~~~~~~ +`mj_printModel <#mj_printModel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_printModel @@ -1148,8 +1149,8 @@ Print model to text file. .. _mj_printFormattedData: -mj_printFormattedData -~~~~~~~~~~~~~~~~~~~~~ +`mj_printFormattedData <#mj_printFormattedData>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_printFormattedData @@ -1158,8 +1159,8 @@ float_format must be a valid printf-style format string for a single float value .. _mj_printData: -mj_printData -~~~~~~~~~~~~ +`mj_printData <#mj_printData>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_printData @@ -1167,8 +1168,8 @@ Print data to text file. .. _mju_printMat: -mju_printMat -~~~~~~~~~~~~ +`mju_printMat <#mju_printMat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_printMat @@ -1176,8 +1177,8 @@ Print matrix to screen. .. _mju_printMatSparse: -mju_printMatSparse -~~~~~~~~~~~~~~~~~~ +`mju_printMatSparse <#mju_printMatSparse>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_printMatSparse @@ -1185,8 +1186,8 @@ Print sparse matrix to screen. .. _mj_printSchema: -mj_printSchema -~~~~~~~~~~~~~~ +`mj_printSchema <#mj_printSchema>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_printSchema @@ -1209,8 +1210,8 @@ The VFS must first be allocated using :ref:`mj_defaultVFS` and must be freed wit .. _mj_defaultVFS: -mj_defaultVFS -~~~~~~~~~~~~~ +`mj_defaultVFS <#mj_defaultVFS>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_defaultVFS @@ -1218,8 +1219,8 @@ Initialize an empty VFS, :ref:`mj_deleteVFS` must be called to deallocate the VF .. _mj_addFileVFS: -mj_addFileVFS -~~~~~~~~~~~~~ +`mj_addFileVFS <#mj_addFileVFS>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_addFileVFS @@ -1228,8 +1229,8 @@ Add file to VFS. The directory argument is optional and can be NULL or empty. Re .. _mj_addBufferVFS: -mj_addBufferVFS -~~~~~~~~~~~~~~~ +`mj_addBufferVFS <#mj_addBufferVFS>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_addBufferVFS @@ -1237,8 +1238,8 @@ Add file to VFS from buffer, return 0: success, 2: repeated name, -1: failed to .. _mj_deleteFileVFS: -mj_deleteFileVFS -~~~~~~~~~~~~~~~~ +`mj_deleteFileVFS <#mj_deleteFileVFS>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_deleteFileVFS @@ -1246,8 +1247,8 @@ Delete file from VFS, return 0: success, -1: not found in VFS. .. _mj_deleteVFS: -mj_deleteVFS -~~~~~~~~~~~~ +`mj_deleteVFS <#mj_deleteVFS>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_deleteVFS @@ -1263,8 +1264,8 @@ in the code samples. .. _mj_defaultLROpt: -mj_defaultLROpt -~~~~~~~~~~~~~~~ +`mj_defaultLROpt <#mj_defaultLROpt>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_defaultLROpt @@ -1272,8 +1273,8 @@ Set default options for length range computation. .. _mj_defaultSolRefImp: -mj_defaultSolRefImp -~~~~~~~~~~~~~~~~~~~ +`mj_defaultSolRefImp <#mj_defaultSolRefImp>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_defaultSolRefImp @@ -1281,8 +1282,8 @@ Set solver parameters to default values. .. _mj_defaultOption: -mj_defaultOption -~~~~~~~~~~~~~~~~ +`mj_defaultOption <#mj_defaultOption>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_defaultOption @@ -1290,8 +1291,8 @@ Set physics options to default values. .. _mj_defaultVisual: -mj_defaultVisual -~~~~~~~~~~~~~~~~ +`mj_defaultVisual <#mj_defaultVisual>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_defaultVisual @@ -1299,8 +1300,8 @@ Set visual options to default values. .. _mj_copyModel: -mj_copyModel -~~~~~~~~~~~~ +`mj_copyModel <#mj_copyModel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_copyModel @@ -1308,8 +1309,8 @@ Copy mjModel, allocate new if dest is NULL. .. _mj_saveModel: -mj_saveModel -~~~~~~~~~~~~ +`mj_saveModel <#mj_saveModel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_saveModel @@ -1317,8 +1318,8 @@ Save model to binary MJB file or memory buffer; buffer has precedence when given .. _mj_loadModel: -mj_loadModel -~~~~~~~~~~~~ +`mj_loadModel <#mj_loadModel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_loadModel @@ -1327,8 +1328,8 @@ If vfs is not NULL, look up file in vfs before reading from disk. .. _mj_deleteModel: -mj_deleteModel -~~~~~~~~~~~~~~ +`mj_deleteModel <#mj_deleteModel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_deleteModel @@ -1336,8 +1337,8 @@ Free memory allocation in model. .. _mj_sizeModel: -mj_sizeModel -~~~~~~~~~~~~ +`mj_sizeModel <#mj_sizeModel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_sizeModel @@ -1345,8 +1346,8 @@ Return size of buffer needed to hold model. .. _mj_makeData: -mj_makeData -~~~~~~~~~~~ +`mj_makeData <#mj_makeData>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_makeData @@ -1355,8 +1356,8 @@ If the model buffer is unallocated the initial configuration will not be set. .. _mj_copyData: -mj_copyData -~~~~~~~~~~~ +`mj_copyData <#mj_copyData>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_copyData @@ -1365,8 +1366,8 @@ m is only required to contain the size fields from MJMODEL_INTS. .. _mj_resetData: -mj_resetData -~~~~~~~~~~~~ +`mj_resetData <#mj_resetData>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_resetData @@ -1374,8 +1375,8 @@ Reset data to defaults. .. _mj_resetDataDebug: -mj_resetDataDebug -~~~~~~~~~~~~~~~~~ +`mj_resetDataDebug <#mj_resetDataDebug>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_resetDataDebug @@ -1383,8 +1384,8 @@ Reset data to defaults, fill everything else with debug_value. .. _mj_resetDataKeyframe: -mj_resetDataKeyframe -~~~~~~~~~~~~~~~~~~~~ +`mj_resetDataKeyframe <#mj_resetDataKeyframe>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_resetDataKeyframe @@ -1392,8 +1393,8 @@ Reset data. If 0 <= key < nkey, set fields from specified keyframe. .. _mj_markStack: -mj_markStack -~~~~~~~~~~~~ +`mj_markStack <#mj_markStack>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_markStack @@ -1401,8 +1402,8 @@ Mark a new frame on the mjData stack. .. _mj_freeStack: -mj_freeStack -~~~~~~~~~~~~ +`mj_freeStack <#mj_freeStack>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_freeStack @@ -1411,8 +1412,8 @@ to mj_markStack must no longer be used afterwards. .. _mj_stackAllocByte: -mj_stackAllocByte -~~~~~~~~~~~~~~~~~ +`mj_stackAllocByte <#mj_stackAllocByte>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_stackAllocByte @@ -1421,8 +1422,8 @@ Call mju_error on stack overflow. .. _mj_stackAllocNum: -mj_stackAllocNum -~~~~~~~~~~~~~~~~ +`mj_stackAllocNum <#mj_stackAllocNum>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_stackAllocNum @@ -1430,8 +1431,8 @@ Allocate array of mjtNums on mjData stack. Call mju_error on stack overflow. .. _mj_stackAllocInt: -mj_stackAllocInt -~~~~~~~~~~~~~~~~ +`mj_stackAllocInt <#mj_stackAllocInt>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_stackAllocInt @@ -1439,8 +1440,8 @@ Allocate array of ints on mjData stack. Call mju_error on stack overflow. .. _mj_deleteData: -mj_deleteData -~~~~~~~~~~~~~ +`mj_deleteData <#mj_deleteData>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_deleteData @@ -1448,8 +1449,8 @@ Free memory allocation in mjData. .. _mj_resetCallbacks: -mj_resetCallbacks -~~~~~~~~~~~~~~~~~ +`mj_resetCallbacks <#mj_resetCallbacks>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_resetCallbacks @@ -1457,8 +1458,8 @@ Reset all callbacks to NULL pointers (NULL is the default). .. _mj_setConst: -mj_setConst -~~~~~~~~~~~ +`mj_setConst <#mj_setConst>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_setConst @@ -1466,8 +1467,8 @@ Set constant fields of mjModel, corresponding to qpos0 configuration. .. _mj_setLengthRange: -mj_setLengthRange -~~~~~~~~~~~~~~~~~ +`mj_setLengthRange <#mj_setLengthRange>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_setLengthRange @@ -1475,8 +1476,8 @@ Set actuator_lengthrange for specified actuator; return 1 if ok, 0 if error. .. _mj_makeSpec: -mj_makeSpec -~~~~~~~~~~~ +`mj_makeSpec <#mj_makeSpec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_makeSpec @@ -1484,8 +1485,8 @@ Create empty spec. .. _mj_copySpec: -mj_copySpec -~~~~~~~~~~~ +`mj_copySpec <#mj_copySpec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_copySpec @@ -1493,8 +1494,8 @@ Copy spec. .. _mj_deleteSpec: -mj_deleteSpec -~~~~~~~~~~~~~ +`mj_deleteSpec <#mj_deleteSpec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_deleteSpec @@ -1502,13 +1503,22 @@ Free memory allocation in mjSpec. .. _mjs_activatePlugin: -mjs_activatePlugin -~~~~~~~~~~~~~~~~~~ +`mjs_activatePlugin <#mjs_activatePlugin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_activatePlugin Activate plugin. Returns 0 on success. +.. _mjs_setDeepCopy: + +`mjs_setDeepCopy <#mjs_setDeepCopy>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjs_setDeepCopy + +Turn deep copy on or off attach. Returns 0 on success. + .. _Errorandmemory: Error and memory @@ -1516,8 +1526,8 @@ Error and memory .. _mju_error: -mju_error -~~~~~~~~~ +`mju_error <#mju_error>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_error @@ -1525,8 +1535,8 @@ Main error function; does not return to caller. .. _mju_error_i: -mju_error_i -~~~~~~~~~~~ +`mju_error_i <#mju_error_i>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_error_i @@ -1534,8 +1544,8 @@ Deprecated: use mju_error. .. _mju_error_s: -mju_error_s -~~~~~~~~~~~ +`mju_error_s <#mju_error_s>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_error_s @@ -1543,8 +1553,8 @@ Deprecated: use mju_error. .. _mju_warning: -mju_warning -~~~~~~~~~~~ +`mju_warning <#mju_warning>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_warning @@ -1552,8 +1562,8 @@ Main warning function; returns to caller. .. _mju_warning_i: -mju_warning_i -~~~~~~~~~~~~~ +`mju_warning_i <#mju_warning_i>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_warning_i @@ -1561,8 +1571,8 @@ Deprecated: use mju_warning. .. _mju_warning_s: -mju_warning_s -~~~~~~~~~~~~~ +`mju_warning_s <#mju_warning_s>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_warning_s @@ -1570,8 +1580,8 @@ Deprecated: use mju_warning. .. _mju_clearHandlers: -mju_clearHandlers -~~~~~~~~~~~~~~~~~ +`mju_clearHandlers <#mju_clearHandlers>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_clearHandlers @@ -1579,8 +1589,8 @@ Clear user error and memory handlers. .. _mju_malloc: -mju_malloc -~~~~~~~~~~ +`mju_malloc <#mju_malloc>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_malloc @@ -1588,8 +1598,8 @@ Allocate memory; byte-align on 64; pad size to multiple of 64. .. _mju_free: -mju_free -~~~~~~~~ +`mju_free <#mju_free>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_free @@ -1597,8 +1607,8 @@ Free memory, using free() by default. .. _mj_warning: -mj_warning -~~~~~~~~~~ +`mj_warning <#mj_warning>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mj_warning @@ -1606,8 +1616,8 @@ High-level warning function: count warnings in mjData, print only the first. .. _mju_writeLog: -mju_writeLog -~~~~~~~~~~~~ +`mju_writeLog <#mju_writeLog>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_writeLog @@ -1615,8 +1625,8 @@ Write [datetime, type: message] to MUJOCO_LOG.TXT. .. _mjs_getError: -mjs_getError -~~~~~~~~~~~~ +`mjs_getError <#mjs_getError>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_getError @@ -1624,8 +1634,8 @@ Get compiler error message from spec. .. _mjs_isWarning: -mjs_isWarning -~~~~~~~~~~~~~ +`mjs_isWarning <#mjs_isWarning>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_isWarning @@ -1638,8 +1648,8 @@ Miscellaneous .. _mju_muscleGain: -mju_muscleGain -~~~~~~~~~~~~~~ +`mju_muscleGain <#mju_muscleGain>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_muscleGain @@ -1647,8 +1657,8 @@ Muscle active force, prm = (range[2], force, scale, lmin, lmax, vmax, fpmax, fvm .. _mju_muscleBias: -mju_muscleBias -~~~~~~~~~~~~~~ +`mju_muscleBias <#mju_muscleBias>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_muscleBias @@ -1656,8 +1666,8 @@ Muscle passive force, prm = (range[2], force, scale, lmin, lmax, vmax, fpmax, fv .. _mju_muscleDynamics: -mju_muscleDynamics -~~~~~~~~~~~~~~~~~~ +`mju_muscleDynamics <#mju_muscleDynamics>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_muscleDynamics @@ -1665,8 +1675,8 @@ Muscle activation dynamics, prm = (tau_act, tau_deact, smoothing_width). .. _mju_encodePyramid: -mju_encodePyramid -~~~~~~~~~~~~~~~~~ +`mju_encodePyramid <#mju_encodePyramid>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_encodePyramid @@ -1674,8 +1684,8 @@ Convert contact force to pyramid representation. .. _mju_decodePyramid: -mju_decodePyramid -~~~~~~~~~~~~~~~~~ +`mju_decodePyramid <#mju_decodePyramid>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_decodePyramid @@ -1683,8 +1693,8 @@ Convert pyramid representation to contact force. .. _mju_springDamper: -mju_springDamper -~~~~~~~~~~~~~~~~ +`mju_springDamper <#mju_springDamper>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_springDamper @@ -1692,8 +1702,8 @@ Integrate spring-damper analytically, return pos(dt). .. _mju_min: -mju_min -~~~~~~~ +`mju_min <#mju_min>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_min @@ -1701,8 +1711,8 @@ Return min(a,b) with single evaluation of a and b. .. _mju_max: -mju_max -~~~~~~~ +`mju_max <#mju_max>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_max @@ -1710,8 +1720,8 @@ Return max(a,b) with single evaluation of a and b. .. _mju_clip: -mju_clip -~~~~~~~~ +`mju_clip <#mju_clip>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_clip @@ -1719,8 +1729,8 @@ Clip x to the range [min, max]. .. _mju_sign: -mju_sign -~~~~~~~~ +`mju_sign <#mju_sign>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_sign @@ -1728,8 +1738,8 @@ Return sign of x: +1, -1 or 0. .. _mju_round: -mju_round -~~~~~~~~~ +`mju_round <#mju_round>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_round @@ -1737,8 +1747,8 @@ Round x to nearest integer. .. _mju_type2Str: -mju_type2Str -~~~~~~~~~~~~ +`mju_type2Str <#mju_type2Str>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_type2Str @@ -1746,8 +1756,8 @@ Convert type id (mjtObj) to type name. .. _mju_str2Type: -mju_str2Type -~~~~~~~~~~~~ +`mju_str2Type <#mju_str2Type>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_str2Type @@ -1755,8 +1765,8 @@ Convert type name to type id (mjtObj). .. _mju_writeNumBytes: -mju_writeNumBytes -~~~~~~~~~~~~~~~~~ +`mju_writeNumBytes <#mju_writeNumBytes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_writeNumBytes @@ -1764,8 +1774,8 @@ Return human readable number of bytes using standard letter suffix. .. _mju_warningText: -mju_warningText -~~~~~~~~~~~~~~~ +`mju_warningText <#mju_warningText>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_warningText @@ -1773,8 +1783,8 @@ Construct a warning message given the warning type and info. .. _mju_isBad: -mju_isBad -~~~~~~~~~ +`mju_isBad <#mju_isBad>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_isBad @@ -1782,8 +1792,8 @@ Return 1 if nan or abs(x)>mjMAXVAL, 0 otherwise. Used by check functions. .. _mju_isZero: -mju_isZero -~~~~~~~~~~ +`mju_isZero <#mju_isZero>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_isZero @@ -1791,8 +1801,8 @@ Return 1 if all elements are 0. .. _mju_standardNormal: -mju_standardNormal -~~~~~~~~~~~~~~~~~~ +`mju_standardNormal <#mju_standardNormal>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_standardNormal @@ -1800,8 +1810,8 @@ Standard normal random number generator (optional second number). .. _mju_f2n: -mju_f2n -~~~~~~~ +`mju_f2n <#mju_f2n>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_f2n @@ -1809,8 +1819,8 @@ Convert from float to mjtNum. .. _mju_n2f: -mju_n2f -~~~~~~~ +`mju_n2f <#mju_n2f>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_n2f @@ -1818,8 +1828,8 @@ Convert from mjtNum to float. .. _mju_d2n: -mju_d2n -~~~~~~~ +`mju_d2n <#mju_d2n>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_d2n @@ -1827,8 +1837,8 @@ Convert from double to mjtNum. .. _mju_n2d: -mju_n2d -~~~~~~~ +`mju_n2d <#mju_n2d>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_n2d @@ -1836,8 +1846,8 @@ Convert from mjtNum to double. .. _mju_insertionSort: -mju_insertionSort -~~~~~~~~~~~~~~~~~ +`mju_insertionSort <#mju_insertionSort>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_insertionSort @@ -1845,8 +1855,8 @@ Insertion sort, resulting list is in increasing order. .. _mju_insertionSortInt: -mju_insertionSortInt -~~~~~~~~~~~~~~~~~~~~ +`mju_insertionSortInt <#mju_insertionSortInt>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_insertionSortInt @@ -1854,8 +1864,8 @@ Integer insertion sort, resulting list is in increasing order. .. _mju_Halton: -mju_Halton -~~~~~~~~~~ +`mju_Halton <#mju_Halton>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_Halton @@ -1863,8 +1873,8 @@ Generate Halton sequence. .. _mju_strncpy: -mju_strncpy -~~~~~~~~~~~ +`mju_strncpy <#mju_strncpy>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_strncpy @@ -1872,8 +1882,8 @@ Call strncpy, then set dst[n-1] = 0. .. _mju_sigmoid: -mju_sigmoid -~~~~~~~~~~~ +`mju_sigmoid <#mju_sigmoid>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_sigmoid @@ -1897,8 +1907,8 @@ illustrated in :ref:`simulate`. .. _mjv_defaultCamera: -mjv_defaultCamera -~~~~~~~~~~~~~~~~~ +`mjv_defaultCamera <#mjv_defaultCamera>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_defaultCamera @@ -1906,8 +1916,8 @@ Set default camera. .. _mjv_defaultFreeCamera: -mjv_defaultFreeCamera -~~~~~~~~~~~~~~~~~~~~~ +`mjv_defaultFreeCamera <#mjv_defaultFreeCamera>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_defaultFreeCamera @@ -1915,8 +1925,8 @@ Set default free camera. .. _mjv_defaultPerturb: -mjv_defaultPerturb -~~~~~~~~~~~~~~~~~~ +`mjv_defaultPerturb <#mjv_defaultPerturb>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_defaultPerturb @@ -1924,8 +1934,8 @@ Set default perturbation. .. _mjv_room2model: -mjv_room2model -~~~~~~~~~~~~~~ +`mjv_room2model <#mjv_room2model>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_room2model @@ -1933,8 +1943,8 @@ Transform pose from room to model space. .. _mjv_model2room: -mjv_model2room -~~~~~~~~~~~~~~ +`mjv_model2room <#mjv_model2room>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_model2room @@ -1942,8 +1952,8 @@ Transform pose from model to room space. .. _mjv_cameraInModel: -mjv_cameraInModel -~~~~~~~~~~~~~~~~~ +`mjv_cameraInModel <#mjv_cameraInModel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_cameraInModel @@ -1951,8 +1961,8 @@ Get camera info in model space; average left and right OpenGL cameras. .. _mjv_cameraInRoom: -mjv_cameraInRoom -~~~~~~~~~~~~~~~~ +`mjv_cameraInRoom <#mjv_cameraInRoom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_cameraInRoom @@ -1960,8 +1970,8 @@ Get camera info in room space; average left and right OpenGL cameras. .. _mjv_frustumHeight: -mjv_frustumHeight -~~~~~~~~~~~~~~~~~ +`mjv_frustumHeight <#mjv_frustumHeight>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_frustumHeight @@ -1969,8 +1979,8 @@ Get frustum height at unit distance from camera; average left and right OpenGL c .. _mjv_alignToCamera: -mjv_alignToCamera -~~~~~~~~~~~~~~~~~ +`mjv_alignToCamera <#mjv_alignToCamera>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_alignToCamera @@ -1978,8 +1988,8 @@ Rotate 3D vec in horizontal plane by angle between (0,1) and (forward_x,forward_ .. _mjv_moveCamera: -mjv_moveCamera -~~~~~~~~~~~~~~ +`mjv_moveCamera <#mjv_moveCamera>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_moveCamera @@ -1987,8 +1997,8 @@ Move camera with mouse; action is mjtMouse. .. _mjv_moveCameraFromState: -mjv_moveCameraFromState -~~~~~~~~~~~~~~~~~~~~~~~ +`mjv_moveCameraFromState <#mjv_moveCameraFromState>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_moveCameraFromState @@ -1996,8 +2006,8 @@ Move camera with mouse given a scene state; action is mjtMouse. .. _mjv_movePerturb: -mjv_movePerturb -~~~~~~~~~~~~~~~ +`mjv_movePerturb <#mjv_movePerturb>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_movePerturb @@ -2005,8 +2015,8 @@ Move perturb object with mouse; action is mjtMouse. .. _mjv_movePerturbFromState: -mjv_movePerturbFromState -~~~~~~~~~~~~~~~~~~~~~~~~ +`mjv_movePerturbFromState <#mjv_movePerturbFromState>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_movePerturbFromState @@ -2014,8 +2024,8 @@ Move perturb object with mouse given a scene state; action is mjtMouse. .. _mjv_moveModel: -mjv_moveModel -~~~~~~~~~~~~~ +`mjv_moveModel <#mjv_moveModel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_moveModel @@ -2023,8 +2033,8 @@ Move model with mouse; action is mjtMouse. .. _mjv_initPerturb: -mjv_initPerturb -~~~~~~~~~~~~~~~ +`mjv_initPerturb <#mjv_initPerturb>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_initPerturb @@ -2032,8 +2042,8 @@ Copy perturb pos,quat from selected body; set scale for perturbation. .. _mjv_applyPerturbPose: -mjv_applyPerturbPose -~~~~~~~~~~~~~~~~~~~~ +`mjv_applyPerturbPose <#mjv_applyPerturbPose>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_applyPerturbPose @@ -2042,8 +2052,8 @@ Write d->qpos only if flg_paused and subtree root for selected body has free joi .. _mjv_applyPerturbForce: -mjv_applyPerturbForce -~~~~~~~~~~~~~~~~~~~~~ +`mjv_applyPerturbForce <#mjv_applyPerturbForce>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_applyPerturbForce @@ -2051,8 +2061,8 @@ Set perturb force,torque in d->xfrc_applied, if selected body is dynamic. .. _mjv_averageCamera: -mjv_averageCamera -~~~~~~~~~~~~~~~~~ +`mjv_averageCamera <#mjv_averageCamera>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_averageCamera @@ -2060,8 +2070,8 @@ Return the average of two OpenGL cameras. .. _mjv_select: -mjv_select -~~~~~~~~~~ +`mjv_select <#mjv_select>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_select @@ -2082,8 +2092,8 @@ Unity or Unreal Engine. See :ref:`simulate` for illustration of how .. _mjv_defaultOption: -mjv_defaultOption -~~~~~~~~~~~~~~~~~ +`mjv_defaultOption <#mjv_defaultOption>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_defaultOption @@ -2091,8 +2101,8 @@ Set default visualization options. .. _mjv_defaultFigure: -mjv_defaultFigure -~~~~~~~~~~~~~~~~~ +`mjv_defaultFigure <#mjv_defaultFigure>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_defaultFigure @@ -2100,29 +2110,17 @@ Set default figure. .. _mjv_initGeom: -mjv_initGeom -~~~~~~~~~~~~ +`mjv_initGeom <#mjv_initGeom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_initGeom Initialize given geom fields when not NULL, set the rest to their default values. -.. _mjv_makeConnector: - -mjv_makeConnector -~~~~~~~~~~~~~~~~~ - -.. mujoco-include:: mjv_makeConnector - -Set (type, size, pos, mat) for connector-type geom between given points. -Assume that mjv_initGeom was already called to set all other properties. -Width of mjGEOM_LINE is denominated in pixels. -Deprecated: use mjv_connector. - .. _mjv_connector: -mjv_connector -~~~~~~~~~~~~~ +`mjv_connector <#mjv_connector>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_connector @@ -2132,8 +2130,8 @@ Width of mjGEOM_LINE is denominated in pixels. .. _mjv_defaultScene: -mjv_defaultScene -~~~~~~~~~~~~~~~~ +`mjv_defaultScene <#mjv_defaultScene>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_defaultScene @@ -2141,8 +2139,8 @@ Set default abstract scene. .. _mjv_makeScene: -mjv_makeScene -~~~~~~~~~~~~~ +`mjv_makeScene <#mjv_makeScene>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_makeScene @@ -2150,8 +2148,8 @@ Allocate resources in abstract scene. .. _mjv_freeScene: -mjv_freeScene -~~~~~~~~~~~~~ +`mjv_freeScene <#mjv_freeScene>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_freeScene @@ -2159,8 +2157,8 @@ Free abstract scene. .. _mjv_updateScene: -mjv_updateScene -~~~~~~~~~~~~~~~ +`mjv_updateScene <#mjv_updateScene>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_updateScene @@ -2168,17 +2166,26 @@ Update entire scene given model state. .. _mjv_updateSceneFromState: -mjv_updateSceneFromState -~~~~~~~~~~~~~~~~~~~~~~~~ +`mjv_updateSceneFromState <#mjv_updateSceneFromState>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_updateSceneFromState Update entire scene from a scene state, return the number of new mjWARN_VGEOMFULL warnings. +.. _mjv_copyModel: + +`mjv_copyModel <#mjv_copyModel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjv_copyModel + +Copy mjModel, skip large arrays not required for abstract visualization. + .. _mjv_defaultSceneState: -mjv_defaultSceneState -~~~~~~~~~~~~~~~~~~~~~ +`mjv_defaultSceneState <#mjv_defaultSceneState>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_defaultSceneState @@ -2186,8 +2193,8 @@ Set default scene state. .. _mjv_makeSceneState: -mjv_makeSceneState -~~~~~~~~~~~~~~~~~~ +`mjv_makeSceneState <#mjv_makeSceneState>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_makeSceneState @@ -2195,8 +2202,8 @@ Allocate resources and initialize a scene state object. .. _mjv_freeSceneState: -mjv_freeSceneState -~~~~~~~~~~~~~~~~~~ +`mjv_freeSceneState <#mjv_freeSceneState>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_freeSceneState @@ -2204,8 +2211,8 @@ Free scene state. .. _mjv_updateSceneState: -mjv_updateSceneState -~~~~~~~~~~~~~~~~~~~~ +`mjv_updateSceneState <#mjv_updateSceneState>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_updateSceneState @@ -2213,8 +2220,8 @@ Update a scene state from model and data. .. _mjv_addGeoms: -mjv_addGeoms -~~~~~~~~~~~~ +`mjv_addGeoms <#mjv_addGeoms>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_addGeoms @@ -2222,8 +2229,8 @@ Add geoms from selected categories. .. _mjv_makeLights: -mjv_makeLights -~~~~~~~~~~~~~~ +`mjv_makeLights <#mjv_makeLights>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_makeLights @@ -2231,8 +2238,8 @@ Make list of lights. .. _mjv_updateCamera: -mjv_updateCamera -~~~~~~~~~~~~~~~~ +`mjv_updateCamera <#mjv_updateCamera>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_updateCamera @@ -2240,8 +2247,8 @@ Update camera. .. _mjv_updateSkin: -mjv_updateSkin -~~~~~~~~~~~~~~ +`mjv_updateSkin <#mjv_updateSkin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjv_updateSkin @@ -2257,8 +2264,8 @@ of how to use these functions. .. _mjr_defaultContext: -mjr_defaultContext -~~~~~~~~~~~~~~~~~~ +`mjr_defaultContext <#mjr_defaultContext>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_defaultContext @@ -2266,8 +2273,8 @@ Set default mjrContext. .. _mjr_makeContext: -mjr_makeContext -~~~~~~~~~~~~~~~ +`mjr_makeContext <#mjr_makeContext>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_makeContext @@ -2275,8 +2282,8 @@ Allocate resources in custom OpenGL context; fontscale is mjtFontScale. .. _mjr_changeFont: -mjr_changeFont -~~~~~~~~~~~~~~ +`mjr_changeFont <#mjr_changeFont>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_changeFont @@ -2284,8 +2291,8 @@ Change font of existing context. .. _mjr_addAux: -mjr_addAux -~~~~~~~~~~ +`mjr_addAux <#mjr_addAux>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_addAux @@ -2293,8 +2300,8 @@ Add Aux buffer with given index to context; free previous Aux buffer. .. _mjr_freeContext: -mjr_freeContext -~~~~~~~~~~~~~~~ +`mjr_freeContext <#mjr_freeContext>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_freeContext @@ -2302,8 +2309,8 @@ Free resources in custom OpenGL context, set to default. .. _mjr_resizeOffscreen: -mjr_resizeOffscreen -~~~~~~~~~~~~~~~~~~~ +`mjr_resizeOffscreen <#mjr_resizeOffscreen>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_resizeOffscreen @@ -2311,8 +2318,8 @@ Resize offscreen buffers. .. _mjr_uploadTexture: -mjr_uploadTexture -~~~~~~~~~~~~~~~~~ +`mjr_uploadTexture <#mjr_uploadTexture>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_uploadTexture @@ -2320,8 +2327,8 @@ Upload texture to GPU, overwriting previous upload if any. .. _mjr_uploadMesh: -mjr_uploadMesh -~~~~~~~~~~~~~~ +`mjr_uploadMesh <#mjr_uploadMesh>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_uploadMesh @@ -2329,8 +2336,8 @@ Upload mesh to GPU, overwriting previous upload if any. .. _mjr_uploadHField: -mjr_uploadHField -~~~~~~~~~~~~~~~~ +`mjr_uploadHField <#mjr_uploadHField>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_uploadHField @@ -2338,8 +2345,8 @@ Upload height field to GPU, overwriting previous upload if any. .. _mjr_restoreBuffer: -mjr_restoreBuffer -~~~~~~~~~~~~~~~~~ +`mjr_restoreBuffer <#mjr_restoreBuffer>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_restoreBuffer @@ -2347,8 +2354,8 @@ Make con->currentBuffer current again. .. _mjr_setBuffer: -mjr_setBuffer -~~~~~~~~~~~~~ +`mjr_setBuffer <#mjr_setBuffer>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_setBuffer @@ -2357,8 +2364,8 @@ If only one buffer is available, set that buffer and ignore framebuffer argument .. _mjr_readPixels: -mjr_readPixels -~~~~~~~~~~~~~~ +`mjr_readPixels <#mjr_readPixels>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_readPixels @@ -2367,8 +2374,8 @@ Viewport is in OpenGL framebuffer; client buffer starts at (0,0). .. _mjr_drawPixels: -mjr_drawPixels -~~~~~~~~~~~~~~ +`mjr_drawPixels <#mjr_drawPixels>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_drawPixels @@ -2377,8 +2384,8 @@ Viewport is in OpenGL framebuffer; client buffer starts at (0,0). .. _mjr_blitBuffer: -mjr_blitBuffer -~~~~~~~~~~~~~~ +`mjr_blitBuffer <#mjr_blitBuffer>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_blitBuffer @@ -2387,8 +2394,8 @@ If src, dst have different size and flg_depth==0, color is interpolated with GL_ .. _mjr_setAux: -mjr_setAux -~~~~~~~~~~ +`mjr_setAux <#mjr_setAux>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_setAux @@ -2396,8 +2403,8 @@ Set Aux buffer for custom OpenGL rendering (call restoreBuffer when done). .. _mjr_blitAux: -mjr_blitAux -~~~~~~~~~~~ +`mjr_blitAux <#mjr_blitAux>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_blitAux @@ -2405,8 +2412,8 @@ Blit from Aux buffer to con->currentBuffer. .. _mjr_text: -mjr_text -~~~~~~~~ +`mjr_text <#mjr_text>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_text @@ -2414,8 +2421,8 @@ Draw text at (x,y) in relative coordinates; font is mjtFont. .. _mjr_overlay: -mjr_overlay -~~~~~~~~~~~ +`mjr_overlay <#mjr_overlay>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_overlay @@ -2423,8 +2430,8 @@ Draw text overlay; font is mjtFont; gridpos is mjtGridPos. .. _mjr_maxViewport: -mjr_maxViewport -~~~~~~~~~~~~~~~ +`mjr_maxViewport <#mjr_maxViewport>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_maxViewport @@ -2432,8 +2439,8 @@ Get maximum viewport for active buffer. .. _mjr_rectangle: -mjr_rectangle -~~~~~~~~~~~~~ +`mjr_rectangle <#mjr_rectangle>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_rectangle @@ -2441,8 +2448,8 @@ Draw rectangle. .. _mjr_label: -mjr_label -~~~~~~~~~ +`mjr_label <#mjr_label>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_label @@ -2450,8 +2457,8 @@ Draw rectangle with centered text. .. _mjr_figure: -mjr_figure -~~~~~~~~~~ +`mjr_figure <#mjr_figure>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_figure @@ -2459,8 +2466,8 @@ Draw 2D figure. .. _mjr_render: -mjr_render -~~~~~~~~~~ +`mjr_render <#mjr_render>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_render @@ -2468,8 +2475,8 @@ Render 3D scene. .. _mjr_finish: -mjr_finish -~~~~~~~~~~ +`mjr_finish <#mjr_finish>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_finish @@ -2477,8 +2484,8 @@ Call glFinish. .. _mjr_getError: -mjr_getError -~~~~~~~~~~~~ +`mjr_getError <#mjr_getError>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_getError @@ -2486,8 +2493,8 @@ Call glGetError and return result. .. _mjr_findRect: -mjr_findRect -~~~~~~~~~~~~ +`mjr_findRect <#mjr_findRect>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjr_findRect @@ -2502,8 +2509,8 @@ For a high-level description of the UI framework, see :ref:`UI`. .. _mjui_themeSpacing: -mjui_themeSpacing -~~~~~~~~~~~~~~~~~ +`mjui_themeSpacing <#mjui_themeSpacing>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjui_themeSpacing @@ -2511,8 +2518,8 @@ Get builtin UI theme spacing (ind: 0-1). .. _mjui_themeColor: -mjui_themeColor -~~~~~~~~~~~~~~~ +`mjui_themeColor <#mjui_themeColor>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjui_themeColor @@ -2520,8 +2527,8 @@ Get builtin UI theme color (ind: 0-3). .. _mjui_add: -mjui_add -~~~~~~~~ +`mjui_add <#mjui_add>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjui_add @@ -2534,8 +2541,8 @@ of the UI. Keep in mind that there is a maximum preallocated number of sections .. _mjui_addToSection: -mjui_addToSection -~~~~~~~~~~~~~~~~~ +`mjui_addToSection <#mjui_addToSection>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjui_addToSection @@ -2543,8 +2550,8 @@ Add definitions to UI section. .. _mjui_resize: -mjui_resize -~~~~~~~~~~~ +`mjui_resize <#mjui_resize>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjui_resize @@ -2552,8 +2559,8 @@ Compute UI sizes. .. _mjui_update: -mjui_update -~~~~~~~~~~~ +`mjui_update <#mjui_update>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjui_update @@ -2566,8 +2573,8 @@ specifies the section and the item that was modified. A value of -1 means all it .. _mjui_event: -mjui_event -~~~~~~~~~~ +`mjui_event <#mjui_event>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjui_event @@ -2578,8 +2585,8 @@ depending on which UI item was modified and what the state of that item is after .. _mjui_render: -mjui_render -~~~~~~~~~~~ +`mjui_render <#mjui_render>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjui_render @@ -2598,8 +2605,8 @@ outputs of derivative functions are the trailing rather than leading arguments. .. _mjd_transitionFD: -mjd_transitionFD -~~~~~~~~~~~~~~~~ +`mjd_transitionFD <#mjd_transitionFD>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjd_transitionFD @@ -2647,8 +2654,8 @@ These matrices and their dimensions are: .. _mjd_inverseFD: -mjd_inverseFD -~~~~~~~~~~~~~ +`mjd_inverseFD <#mjd_inverseFD>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjd_inverseFD @@ -2690,8 +2697,8 @@ using finite-differencing. These matrices and their dimensions are: .. _mjd_subQuat: -mjd_subQuat -~~~~~~~~~~~ +`mjd_subQuat <#mjd_subQuat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjd_subQuat @@ -2699,8 +2706,8 @@ Derivatives of :ref:`mju_subQuat` (quaternion difference). .. _mjd_quatIntegrate: -mjd_quatIntegrate -~~~~~~~~~~~~~~~~~ +`mjd_quatIntegrate <#mjd_quatIntegrate>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjd_quatIntegrate @@ -2730,8 +2737,8 @@ Plugins ^^^^^^^ .. _mjp_defaultPlugin: -mjp_defaultPlugin -~~~~~~~~~~~~~~~~~ +`mjp_defaultPlugin <#mjp_defaultPlugin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjp_defaultPlugin @@ -2739,8 +2746,8 @@ Set default plugin definition. .. _mjp_registerPlugin: -mjp_registerPlugin -~~~~~~~~~~~~~~~~~~ +`mjp_registerPlugin <#mjp_registerPlugin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjp_registerPlugin @@ -2753,8 +2760,8 @@ need not be the same. .. _mjp_pluginCount: -mjp_pluginCount -~~~~~~~~~~~~~~~ +`mjp_pluginCount <#mjp_pluginCount>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjp_pluginCount @@ -2762,8 +2769,8 @@ Return the number of globally registered plugins. .. _mjp_getPlugin: -mjp_getPlugin -~~~~~~~~~~~~~ +`mjp_getPlugin <#mjp_getPlugin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjp_getPlugin @@ -2771,8 +2778,8 @@ Look up a plugin by name. If slot is not NULL, also write its registered slot nu .. _mjp_getPluginAtSlot: -mjp_getPluginAtSlot -~~~~~~~~~~~~~~~~~~~ +`mjp_getPluginAtSlot <#mjp_getPluginAtSlot>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjp_getPluginAtSlot @@ -2780,8 +2787,8 @@ Look up a plugin by the registered slot number that was returned by mjp_register .. _mjp_defaultResourceProvider: -mjp_defaultResourceProvider -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +`mjp_defaultResourceProvider <#mjp_defaultResourceProvider>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjp_defaultResourceProvider @@ -2789,8 +2796,8 @@ Set default resource provider definition. .. _mjp_registerResourceProvider: -mjp_registerResourceProvider -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +`mjp_registerResourceProvider <#mjp_registerResourceProvider>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjp_registerResourceProvider @@ -2800,8 +2807,8 @@ returns a slot number > 0 on success. .. _mjp_resourceProviderCount: -mjp_resourceProviderCount -~~~~~~~~~~~~~~~~~~~~~~~~~ +`mjp_resourceProviderCount <#mjp_resourceProviderCount>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjp_resourceProviderCount @@ -2809,8 +2816,8 @@ Return the number of globally registered resource providers. .. _mjp_getResourceProvider: -mjp_getResourceProvider -~~~~~~~~~~~~~~~~~~~~~~~ +`mjp_getResourceProvider <#mjp_getResourceProvider>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjp_getResourceProvider @@ -2819,8 +2826,8 @@ If no match, return NULL. .. _mjp_getResourceProviderAtSlot: -mjp_getResourceProviderAtSlot -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +`mjp_getResourceProviderAtSlot <#mjp_getResourceProviderAtSlot>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjp_getResourceProviderAtSlot @@ -2833,8 +2840,8 @@ Threads ^^^^^^^ .. _mju_threadPoolCreate: -mju_threadPoolCreate -~~~~~~~~~~~~~~~~~~~~ +`mju_threadPoolCreate <#mju_threadPoolCreate>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_threadPoolCreate @@ -2842,8 +2849,8 @@ Create a thread pool with the specified number of threads running. .. _mju_bindThreadPool: -mju_bindThreadPool -~~~~~~~~~~~~~~~~~~ +`mju_bindThreadPool <#mju_bindThreadPool>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_bindThreadPool @@ -2851,8 +2858,8 @@ Adds a thread pool to mjData and configures it for multi-threaded use. .. _mju_threadPoolEnqueue: -mju_threadPoolEnqueue -~~~~~~~~~~~~~~~~~~~~~ +`mju_threadPoolEnqueue <#mju_threadPoolEnqueue>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_threadPoolEnqueue @@ -2860,8 +2867,8 @@ Enqueue a task in a thread pool. .. _mju_threadPoolDestroy: -mju_threadPoolDestroy -~~~~~~~~~~~~~~~~~~~~~ +`mju_threadPoolDestroy <#mju_threadPoolDestroy>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_threadPoolDestroy @@ -2869,8 +2876,8 @@ Destroy a thread pool. .. _mju_defaultTask: -mju_defaultTask -~~~~~~~~~~~~~~~ +`mju_defaultTask <#mju_defaultTask>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_defaultTask @@ -2878,8 +2885,8 @@ Initialize an mjTask. .. _mju_taskJoin: -mju_taskJoin -~~~~~~~~~~~~ +`mju_taskJoin <#mju_taskJoin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_taskJoin @@ -3009,8 +3016,8 @@ Vector math .. _mju_zero3: -mju_zero3 -~~~~~~~~~ +`mju_zero3 <#mju_zero3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_zero3 @@ -3018,8 +3025,8 @@ Set res = 0. .. _mju_copy3: -mju_copy3 -~~~~~~~~~ +`mju_copy3 <#mju_copy3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_copy3 @@ -3027,8 +3034,8 @@ Set res = vec. .. _mju_scl3: -mju_scl3 -~~~~~~~~ +`mju_scl3 <#mju_scl3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_scl3 @@ -3036,8 +3043,8 @@ Set res = vec*scl. .. _mju_add3: -mju_add3 -~~~~~~~~ +`mju_add3 <#mju_add3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_add3 @@ -3045,8 +3052,8 @@ Set res = vec1 + vec2. .. _mju_sub3: -mju_sub3 -~~~~~~~~ +`mju_sub3 <#mju_sub3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_sub3 @@ -3054,8 +3061,8 @@ Set res = vec1 - vec2. .. _mju_addTo3: -mju_addTo3 -~~~~~~~~~~ +`mju_addTo3 <#mju_addTo3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_addTo3 @@ -3063,8 +3070,8 @@ Set res = res + vec. .. _mju_subFrom3: -mju_subFrom3 -~~~~~~~~~~~~ +`mju_subFrom3 <#mju_subFrom3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_subFrom3 @@ -3072,8 +3079,8 @@ Set res = res - vec. .. _mju_addToScl3: -mju_addToScl3 -~~~~~~~~~~~~~ +`mju_addToScl3 <#mju_addToScl3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_addToScl3 @@ -3081,8 +3088,8 @@ Set res = res + vec*scl. .. _mju_addScl3: -mju_addScl3 -~~~~~~~~~~~ +`mju_addScl3 <#mju_addScl3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_addScl3 @@ -3090,8 +3097,8 @@ Set res = vec1 + vec2*scl. .. _mju_normalize3: -mju_normalize3 -~~~~~~~~~~~~~~ +`mju_normalize3 <#mju_normalize3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_normalize3 @@ -3099,8 +3106,8 @@ Normalize vector, return length before normalization. .. _mju_norm3: -mju_norm3 -~~~~~~~~~ +`mju_norm3 <#mju_norm3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_norm3 @@ -3108,8 +3115,8 @@ Return vector length (without normalizing the vector). .. _mju_dot3: -mju_dot3 -~~~~~~~~ +`mju_dot3 <#mju_dot3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_dot3 @@ -3117,8 +3124,8 @@ Return dot-product of vec1 and vec2. .. _mju_dist3: -mju_dist3 -~~~~~~~~~ +`mju_dist3 <#mju_dist3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_dist3 @@ -3126,8 +3133,8 @@ Return Cartesian distance between 3D vectors pos1 and pos2. .. _mju_mulMatVec3: -mju_mulMatVec3 -~~~~~~~~~~~~~~ +`mju_mulMatVec3 <#mju_mulMatVec3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_mulMatVec3 @@ -3135,35 +3142,17 @@ Multiply 3-by-3 matrix by vector: res = mat * vec. .. _mju_mulMatTVec3: -mju_mulMatTVec3 -~~~~~~~~~~~~~~~ +`mju_mulMatTVec3 <#mju_mulMatTVec3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_mulMatTVec3 Multiply transposed 3-by-3 matrix by vector: res = mat' * vec. -.. _mju_rotVecMat: - -mju_rotVecMat -~~~~~~~~~~~~~ - -.. mujoco-include:: mju_rotVecMat - -Deprecated, use mju_mulMatVec3(res, mat, vec). - -.. _mju_rotVecMatT: - -mju_rotVecMatT -~~~~~~~~~~~~~~ - -.. mujoco-include:: mju_rotVecMatT - -Deprecated, use mju_mulMatTVec3(res, mat, vec). - .. _mju_cross: -mju_cross -~~~~~~~~~ +`mju_cross <#mju_cross>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_cross @@ -3171,8 +3160,8 @@ Compute cross-product: res = cross(a, b). .. _mju_zero4: -mju_zero4 -~~~~~~~~~ +`mju_zero4 <#mju_zero4>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_zero4 @@ -3180,8 +3169,8 @@ Set res = 0. .. _mju_unit4: -mju_unit4 -~~~~~~~~~ +`mju_unit4 <#mju_unit4>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_unit4 @@ -3189,8 +3178,8 @@ Set res = (1,0,0,0). .. _mju_copy4: -mju_copy4 -~~~~~~~~~ +`mju_copy4 <#mju_copy4>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_copy4 @@ -3198,8 +3187,8 @@ Set res = vec. .. _mju_normalize4: -mju_normalize4 -~~~~~~~~~~~~~~ +`mju_normalize4 <#mju_normalize4>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_normalize4 @@ -3207,8 +3196,8 @@ Normalize vector, return length before normalization. .. _mju_zero: -mju_zero -~~~~~~~~ +`mju_zero <#mju_zero>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_zero @@ -3216,8 +3205,8 @@ Set res = 0. .. _mju_fill: -mju_fill -~~~~~~~~ +`mju_fill <#mju_fill>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_fill @@ -3225,8 +3214,8 @@ Set res = val. .. _mju_copy: -mju_copy -~~~~~~~~ +`mju_copy <#mju_copy>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_copy @@ -3234,8 +3223,8 @@ Set res = vec. .. _mju_sum: -mju_sum -~~~~~~~ +`mju_sum <#mju_sum>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_sum @@ -3243,8 +3232,8 @@ Return sum(vec). .. _mju_L1: -mju_L1 -~~~~~~ +`mju_L1 <#mju_L1>`__ +~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_L1 @@ -3252,8 +3241,8 @@ Return L1 norm: sum(abs(vec)). .. _mju_scl: -mju_scl -~~~~~~~ +`mju_scl <#mju_scl>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_scl @@ -3261,8 +3250,8 @@ Set res = vec*scl. .. _mju_add: -mju_add -~~~~~~~ +`mju_add <#mju_add>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_add @@ -3270,8 +3259,8 @@ Set res = vec1 + vec2. .. _mju_sub: -mju_sub -~~~~~~~ +`mju_sub <#mju_sub>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_sub @@ -3279,8 +3268,8 @@ Set res = vec1 - vec2. .. _mju_addTo: -mju_addTo -~~~~~~~~~ +`mju_addTo <#mju_addTo>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_addTo @@ -3288,8 +3277,8 @@ Set res = res + vec. .. _mju_subFrom: -mju_subFrom -~~~~~~~~~~~ +`mju_subFrom <#mju_subFrom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_subFrom @@ -3297,8 +3286,8 @@ Set res = res - vec. .. _mju_addToScl: -mju_addToScl -~~~~~~~~~~~~ +`mju_addToScl <#mju_addToScl>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_addToScl @@ -3306,8 +3295,8 @@ Set res = res + vec*scl. .. _mju_addScl: -mju_addScl -~~~~~~~~~~ +`mju_addScl <#mju_addScl>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_addScl @@ -3315,8 +3304,8 @@ Set res = vec1 + vec2*scl. .. _mju_normalize: -mju_normalize -~~~~~~~~~~~~~ +`mju_normalize <#mju_normalize>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_normalize @@ -3324,8 +3313,8 @@ Normalize vector, return length before normalization. .. _mju_norm: -mju_norm -~~~~~~~~ +`mju_norm <#mju_norm>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_norm @@ -3333,8 +3322,8 @@ Return vector length (without normalizing vector). .. _mju_dot: -mju_dot -~~~~~~~ +`mju_dot <#mju_dot>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_dot @@ -3342,8 +3331,8 @@ Return dot-product of vec1 and vec2. .. _mju_mulMatVec: -mju_mulMatVec -~~~~~~~~~~~~~ +`mju_mulMatVec <#mju_mulMatVec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_mulMatVec @@ -3351,8 +3340,8 @@ Multiply matrix and vector: res = mat * vec. .. _mju_mulMatTVec: -mju_mulMatTVec -~~~~~~~~~~~~~~ +`mju_mulMatTVec <#mju_mulMatTVec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_mulMatTVec @@ -3360,8 +3349,8 @@ Multiply transposed matrix and vector: res = mat' * vec. .. _mju_mulVecMatVec: -mju_mulVecMatVec -~~~~~~~~~~~~~~~~ +`mju_mulVecMatVec <#mju_mulVecMatVec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_mulVecMatVec @@ -3369,8 +3358,8 @@ Multiply square matrix with vectors on both sides: returns vec1' * mat * vec2. .. _mju_transpose: -mju_transpose -~~~~~~~~~~~~~ +`mju_transpose <#mju_transpose>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_transpose @@ -3378,8 +3367,8 @@ Transpose matrix: res = mat'. .. _mju_symmetrize: -mju_symmetrize -~~~~~~~~~~~~~~ +`mju_symmetrize <#mju_symmetrize>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_symmetrize @@ -3387,8 +3376,8 @@ Symmetrize square matrix :math:`R = \frac{1}{2}(M + M^T)`. .. _mju_eye: -mju_eye -~~~~~~~ +`mju_eye <#mju_eye>`__ +~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_eye @@ -3396,8 +3385,8 @@ Set mat to the identity matrix. .. _mju_mulMatMat: -mju_mulMatMat -~~~~~~~~~~~~~ +`mju_mulMatMat <#mju_mulMatMat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_mulMatMat @@ -3405,8 +3394,8 @@ Multiply matrices: res = mat1 * mat2. .. _mju_mulMatMatT: -mju_mulMatMatT -~~~~~~~~~~~~~~ +`mju_mulMatMatT <#mju_mulMatMatT>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_mulMatMatT @@ -3414,8 +3403,8 @@ Multiply matrices, second argument transposed: res = mat1 * mat2'. .. _mju_mulMatTMat: -mju_mulMatTMat -~~~~~~~~~~~~~~ +`mju_mulMatTMat <#mju_mulMatTMat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_mulMatTMat @@ -3423,8 +3412,8 @@ Multiply matrices, first argument transposed: res = mat1' * mat2. .. _mju_sqrMatTD: -mju_sqrMatTD -~~~~~~~~~~~~ +`mju_sqrMatTD <#mju_sqrMatTD>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_sqrMatTD @@ -3432,8 +3421,8 @@ Set res = mat' * diag * mat if diag is not NULL, and res = mat' * mat otherwise. .. _mju_transformSpatial: -mju_transformSpatial -~~~~~~~~~~~~~~~~~~~~ +`mju_transformSpatial <#mju_transformSpatial>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_transformSpatial @@ -3444,10 +3433,20 @@ rotnew2old is 3-by-3, NULL means no rotation; flg_force specifies force or motio Sparse math ^^^^^^^^^^^ +.. _mju_dense2sparse: + +`mju_dense2sparse <#mju_dense2sparse>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_dense2sparse + +Convert matrix from dense to sparse. + nnz is size of res and colind, return 1 if too small, 0 otherwise. + .. _mju_sparse2dense: -mju_sparse2dense -~~~~~~~~~~~~~~~~ +`mju_sparse2dense <#mju_sparse2dense>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_sparse2dense @@ -3460,8 +3459,8 @@ Quaternions .. _mju_rotVecQuat: -mju_rotVecQuat -~~~~~~~~~~~~~~ +`mju_rotVecQuat <#mju_rotVecQuat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_rotVecQuat @@ -3469,8 +3468,8 @@ Rotate vector by quaternion. .. _mju_negQuat: -mju_negQuat -~~~~~~~~~~~ +`mju_negQuat <#mju_negQuat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_negQuat @@ -3478,8 +3477,8 @@ Conjugate quaternion, corresponding to opposite rotation. .. _mju_mulQuat: -mju_mulQuat -~~~~~~~~~~~ +`mju_mulQuat <#mju_mulQuat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_mulQuat @@ -3487,8 +3486,8 @@ Multiply quaternions. .. _mju_mulQuatAxis: -mju_mulQuatAxis -~~~~~~~~~~~~~~~ +`mju_mulQuatAxis <#mju_mulQuatAxis>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_mulQuatAxis @@ -3496,8 +3495,8 @@ Multiply quaternion and axis. .. _mju_axisAngle2Quat: -mju_axisAngle2Quat -~~~~~~~~~~~~~~~~~~ +`mju_axisAngle2Quat <#mju_axisAngle2Quat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_axisAngle2Quat @@ -3505,8 +3504,8 @@ Convert axisAngle to quaternion. .. _mju_quat2Vel: -mju_quat2Vel -~~~~~~~~~~~~ +`mju_quat2Vel <#mju_quat2Vel>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_quat2Vel @@ -3514,8 +3513,8 @@ Convert quaternion (corresponding to orientation difference) to 3D velocity. .. _mju_subQuat: -mju_subQuat -~~~~~~~~~~~ +`mju_subQuat <#mju_subQuat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_subQuat @@ -3523,8 +3522,8 @@ Subtract quaternions, express as 3D velocity: qb*quat(res) = qa. .. _mju_quat2Mat: -mju_quat2Mat -~~~~~~~~~~~~ +`mju_quat2Mat <#mju_quat2Mat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_quat2Mat @@ -3532,8 +3531,8 @@ Convert quaternion to 3D rotation matrix. .. _mju_mat2Quat: -mju_mat2Quat -~~~~~~~~~~~~ +`mju_mat2Quat <#mju_mat2Quat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_mat2Quat @@ -3541,8 +3540,8 @@ Convert 3D rotation matrix to quaternion. .. _mju_derivQuat: -mju_derivQuat -~~~~~~~~~~~~~ +`mju_derivQuat <#mju_derivQuat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_derivQuat @@ -3550,8 +3549,8 @@ Compute time-derivative of quaternion, given 3D rotational velocity. .. _mju_quatIntegrate: -mju_quatIntegrate -~~~~~~~~~~~~~~~~~ +`mju_quatIntegrate <#mju_quatIntegrate>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_quatIntegrate @@ -3559,17 +3558,27 @@ Integrate quaternion given 3D angular velocity. .. _mju_quatZ2Vec: -mju_quatZ2Vec -~~~~~~~~~~~~~ +`mju_quatZ2Vec <#mju_quatZ2Vec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_quatZ2Vec Construct quaternion performing rotation from z-axis to given vector. +.. _mju_mat2Rot: + +`mju_mat2Rot <#mju_mat2Rot>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mju_mat2Rot + +Extract 3D rotation from an arbitrary 3x3 matrix by refining the input quaternion. +Returns the number of iterations required to converge + .. _mju_euler2Quat: -mju_euler2Quat -~~~~~~~~~~~~~~ +`mju_euler2Quat <#mju_euler2Quat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_euler2Quat @@ -3583,8 +3592,8 @@ Poses .. _mju_mulPose: -mju_mulPose -~~~~~~~~~~~ +`mju_mulPose <#mju_mulPose>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_mulPose @@ -3592,8 +3601,8 @@ Multiply two poses. .. _mju_negPose: -mju_negPose -~~~~~~~~~~~ +`mju_negPose <#mju_negPose>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_negPose @@ -3601,8 +3610,8 @@ Conjugate pose, corresponding to the opposite spatial transformation. .. _mju_trnVecPose: -mju_trnVecPose -~~~~~~~~~~~~~~ +`mju_trnVecPose <#mju_trnVecPose>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_trnVecPose @@ -3615,8 +3624,8 @@ Decompositions / Solvers .. _mju_cholFactor: -mju_cholFactor -~~~~~~~~~~~~~~ +`mju_cholFactor <#mju_cholFactor>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_cholFactor @@ -3624,8 +3633,8 @@ Cholesky decomposition: mat = L*L'; return rank, decomposition performed in-plac .. _mju_cholSolve: -mju_cholSolve -~~~~~~~~~~~~~ +`mju_cholSolve <#mju_cholSolve>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_cholSolve @@ -3633,8 +3642,8 @@ Solve (mat*mat') * res = vec, where mat is a Cholesky factor. .. _mju_cholUpdate: -mju_cholUpdate -~~~~~~~~~~~~~~ +`mju_cholUpdate <#mju_cholUpdate>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_cholUpdate @@ -3642,8 +3651,8 @@ Cholesky rank-one update: L*L' +/- x*x'; return rank. .. _mju_cholFactorBand: -mju_cholFactorBand -~~~~~~~~~~~~~~~~~~ +`mju_cholFactorBand <#mju_cholFactorBand>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_cholFactorBand @@ -3692,8 +3701,8 @@ Band-dense Cholesky decomposition. .. _mju_cholSolveBand: -mju_cholSolveBand -~~~~~~~~~~~~~~~~~ +`mju_cholSolveBand <#mju_cholSolveBand>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_cholSolveBand @@ -3701,8 +3710,8 @@ Solve (mat*mat')*res = vec where mat is a band-dense Cholesky factor. .. _mju_band2Dense: -mju_band2Dense -~~~~~~~~~~~~~~ +`mju_band2Dense <#mju_band2Dense>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_band2Dense @@ -3710,8 +3719,8 @@ Convert banded matrix to dense matrix, fill upper triangle if flg_sym>0. .. _mju_dense2Band: -mju_dense2Band -~~~~~~~~~~~~~~ +`mju_dense2Band <#mju_dense2Band>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_dense2Band @@ -3719,8 +3728,8 @@ Convert dense matrix to banded matrix. .. _mju_bandMulMatVec: -mju_bandMulMatVec -~~~~~~~~~~~~~~~~~ +`mju_bandMulMatVec <#mju_bandMulMatVec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_bandMulMatVec @@ -3728,8 +3737,8 @@ Multiply band-diagonal matrix with nvec vectors, include upper triangle if flg_s .. _mju_bandDiag: -mju_bandDiag -~~~~~~~~~~~~ +`mju_bandDiag <#mju_bandDiag>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_bandDiag @@ -3737,8 +3746,8 @@ Address of diagonal element i in band-dense matrix representation. .. _mju_eig3: -mju_eig3 -~~~~~~~~ +`mju_eig3 <#mju_eig3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_eig3 @@ -3746,8 +3755,8 @@ Eigenvalue decomposition of symmetric 3x3 matrix, mat = eigvec * diag(eigval) * .. _mju_boxQP: -mju_boxQP -~~~~~~~~~ +`mju_boxQP <#mju_boxQP>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_boxQP @@ -3786,8 +3795,8 @@ notes: .. _mju_boxQPmalloc: -mju_boxQPmalloc -~~~~~~~~~~~~~~~ +`mju_boxQPmalloc <#mju_boxQPmalloc>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mju_boxQPmalloc @@ -3801,8 +3810,8 @@ Attachment ^^^^^^^^^^ .. _mjs_attachBody: -mjs_attachBody -~~~~~~~~~~~~~~ +`mjs_attachBody <#mjs_attachBody>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_attachBody @@ -3810,8 +3819,8 @@ Attach child body to a parent frame, return the attached body if success or NULL .. _mjs_attachFrame: -mjs_attachFrame -~~~~~~~~~~~~~~~ +`mjs_attachFrame <#mjs_attachFrame>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_attachFrame @@ -3819,21 +3828,39 @@ Attach child frame to a parent body, return the attached frame if success or NUL .. _mjs_attachToSite: -mjs_attachToSite -~~~~~~~~~~~~~~~~ +`mjs_attachToSite <#mjs_attachToSite>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_attachToSite Attach child body to a parent site, return the attached body if success or NULL otherwise. +.. _mjs_attachFrameToSite: + +`mjs_attachFrameToSite <#mjs_attachFrameToSite>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjs_attachFrameToSite + +Attach child frame to a parent site, return the attached frame if success or NULL otherwise. + .. _mjs_detachBody: -mjs_detachBody -~~~~~~~~~~~~~~ +`mjs_detachBody <#mjs_detachBody>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_detachBody -Detach body from mjSpec, remove all references and delete the body, return 0 on success. +Delete body and descendants from mjSpec, remove all references, return 0 on success. + +.. _mjs_detachDefault: + +`mjs_detachDefault <#mjs_detachDefault>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjs_detachDefault + +Delete default class and descendants from mjSpec, remove all references, return 0 on success. .. _AddTreeElements: @@ -3841,8 +3868,8 @@ Tree elements ^^^^^^^^^^^^^ .. _mjs_addBody: -mjs_addBody -~~~~~~~~~~~ +`mjs_addBody <#mjs_addBody>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addBody @@ -3850,8 +3877,8 @@ Add child body to body, return child. .. _mjs_addSite: -mjs_addSite -~~~~~~~~~~~ +`mjs_addSite <#mjs_addSite>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addSite @@ -3859,8 +3886,8 @@ Add site to body, return site spec. .. _mjs_addJoint: -mjs_addJoint -~~~~~~~~~~~~ +`mjs_addJoint <#mjs_addJoint>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addJoint @@ -3868,8 +3895,8 @@ Add joint to body. .. _mjs_addFreeJoint: -mjs_addFreeJoint -~~~~~~~~~~~~~~~~ +`mjs_addFreeJoint <#mjs_addFreeJoint>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addFreeJoint @@ -3877,8 +3904,8 @@ Add freejoint to body. .. _mjs_addGeom: -mjs_addGeom -~~~~~~~~~~~ +`mjs_addGeom <#mjs_addGeom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addGeom @@ -3886,8 +3913,8 @@ Add geom to body. .. _mjs_addCamera: -mjs_addCamera -~~~~~~~~~~~~~ +`mjs_addCamera <#mjs_addCamera>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addCamera @@ -3895,8 +3922,8 @@ Add camera to body. .. _mjs_addLight: -mjs_addLight -~~~~~~~~~~~~ +`mjs_addLight <#mjs_addLight>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addLight @@ -3904,8 +3931,8 @@ Add light to body. .. _mjs_addFrame: -mjs_addFrame -~~~~~~~~~~~~ +`mjs_addFrame <#mjs_addFrame>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addFrame @@ -3913,12 +3940,13 @@ Add frame to body. .. _mjs_delete: -mjs_delete -~~~~~~~~~~ +`mjs_delete <#mjs_delete>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_delete -Delete object corresponding to the given element. +Delete object corresponding to the given element, return 0 on success. This function should only be used for element +types that cannot have children, i.e. excluding bodies and default classes. .. _AddNonTreeElements: @@ -3926,8 +3954,8 @@ Non-tree elements ^^^^^^^^^^^^^^^^^ .. _mjs_addActuator: -mjs_addActuator -~~~~~~~~~~~~~~~ +`mjs_addActuator <#mjs_addActuator>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addActuator @@ -3935,8 +3963,8 @@ Add actuator. .. _mjs_addSensor: -mjs_addSensor -~~~~~~~~~~~~~ +`mjs_addSensor <#mjs_addSensor>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addSensor @@ -3944,8 +3972,8 @@ Add sensor. .. _mjs_addFlex: -mjs_addFlex -~~~~~~~~~~~ +`mjs_addFlex <#mjs_addFlex>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addFlex @@ -3953,8 +3981,8 @@ Add flex. .. _mjs_addPair: -mjs_addPair -~~~~~~~~~~~ +`mjs_addPair <#mjs_addPair>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addPair @@ -3962,8 +3990,8 @@ Add contact pair. .. _mjs_addExclude: -mjs_addExclude -~~~~~~~~~~~~~~ +`mjs_addExclude <#mjs_addExclude>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addExclude @@ -3971,8 +3999,8 @@ Add excluded body pair. .. _mjs_addEquality: -mjs_addEquality -~~~~~~~~~~~~~~~ +`mjs_addEquality <#mjs_addEquality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addEquality @@ -3980,8 +4008,8 @@ Add equality. .. _mjs_addTendon: -mjs_addTendon -~~~~~~~~~~~~~ +`mjs_addTendon <#mjs_addTendon>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addTendon @@ -3989,8 +4017,8 @@ Add tendon. .. _mjs_wrapSite: -mjs_wrapSite -~~~~~~~~~~~~ +`mjs_wrapSite <#mjs_wrapSite>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_wrapSite @@ -3998,8 +4026,8 @@ Wrap site using tendon. .. _mjs_wrapGeom: -mjs_wrapGeom -~~~~~~~~~~~~ +`mjs_wrapGeom <#mjs_wrapGeom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_wrapGeom @@ -4007,8 +4035,8 @@ Wrap geom using tendon. .. _mjs_wrapJoint: -mjs_wrapJoint -~~~~~~~~~~~~~ +`mjs_wrapJoint <#mjs_wrapJoint>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_wrapJoint @@ -4016,8 +4044,8 @@ Wrap joint using tendon. .. _mjs_wrapPulley: -mjs_wrapPulley -~~~~~~~~~~~~~~ +`mjs_wrapPulley <#mjs_wrapPulley>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_wrapPulley @@ -4025,8 +4053,8 @@ Wrap pulley using tendon. .. _mjs_addNumeric: -mjs_addNumeric -~~~~~~~~~~~~~~ +`mjs_addNumeric <#mjs_addNumeric>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addNumeric @@ -4034,8 +4062,8 @@ Add numeric. .. _mjs_addText: -mjs_addText -~~~~~~~~~~~ +`mjs_addText <#mjs_addText>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addText @@ -4043,8 +4071,8 @@ Add text. .. _mjs_addTuple: -mjs_addTuple -~~~~~~~~~~~~ +`mjs_addTuple <#mjs_addTuple>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addTuple @@ -4052,8 +4080,8 @@ Add tuple. .. _mjs_addKey: -mjs_addKey -~~~~~~~~~~ +`mjs_addKey <#mjs_addKey>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addKey @@ -4061,8 +4089,8 @@ Add keyframe. .. _mjs_addPlugin: -mjs_addPlugin -~~~~~~~~~~~~~ +`mjs_addPlugin <#mjs_addPlugin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addPlugin @@ -4070,8 +4098,8 @@ Add plugin. .. _mjs_addDefault: -mjs_addDefault -~~~~~~~~~~~~~~ +`mjs_addDefault <#mjs_addDefault>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addDefault @@ -4083,8 +4111,8 @@ Assets ^^^^^^ .. _mjs_addMesh: -mjs_addMesh -~~~~~~~~~~~ +`mjs_addMesh <#mjs_addMesh>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addMesh @@ -4092,8 +4120,8 @@ Add mesh. .. _mjs_addHField: -mjs_addHField -~~~~~~~~~~~~~ +`mjs_addHField <#mjs_addHField>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addHField @@ -4101,8 +4129,8 @@ Add height field. .. _mjs_addSkin: -mjs_addSkin -~~~~~~~~~~~ +`mjs_addSkin <#mjs_addSkin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addSkin @@ -4110,8 +4138,8 @@ Add skin. .. _mjs_addTexture: -mjs_addTexture -~~~~~~~~~~~~~~ +`mjs_addTexture <#mjs_addTexture>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addTexture @@ -4119,8 +4147,8 @@ Add texture. .. _mjs_addMaterial: -mjs_addMaterial -~~~~~~~~~~~~~~~ +`mjs_addMaterial <#mjs_addMaterial>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_addMaterial @@ -4132,8 +4160,8 @@ Find and get utilities ^^^^^^^^^^^^^^^^^^^^^^ .. _mjs_getSpec: -mjs_getSpec -~~~~~~~~~~~ +`mjs_getSpec <#mjs_getSpec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_getSpec @@ -4141,8 +4169,8 @@ Get spec from body. .. _mjs_findSpec: -mjs_findSpec -~~~~~~~~~~~~ +`mjs_findSpec <#mjs_findSpec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_findSpec @@ -4150,8 +4178,8 @@ Find spec (model asset) by name. .. _mjs_findBody: -mjs_findBody -~~~~~~~~~~~~ +`mjs_findBody <#mjs_findBody>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_findBody @@ -4159,8 +4187,8 @@ Find body in spec by name. .. _mjs_findElement: -mjs_findElement -~~~~~~~~~~~~~~~ +`mjs_findElement <#mjs_findElement>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_findElement @@ -4168,17 +4196,35 @@ Find element in spec by name. .. _mjs_findChild: -mjs_findChild -~~~~~~~~~~~~~ +`mjs_findChild <#mjs_findChild>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_findChild Find child body by name. +.. _mjs_getParent: + +`mjs_getParent <#mjs_getParent>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjs_getParent + +Get parent body. + +.. _mjs_getFrame: + +`mjs_getFrame <#mjs_getFrame>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjs_getFrame + +Get parent frame. + .. _mjs_findFrame: -mjs_findFrame -~~~~~~~~~~~~~ +`mjs_findFrame <#mjs_findFrame>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_findFrame @@ -4186,8 +4232,8 @@ Find frame by name. .. _mjs_getDefault: -mjs_getDefault -~~~~~~~~~~~~~~ +`mjs_getDefault <#mjs_getDefault>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_getDefault @@ -4195,8 +4241,8 @@ Get default corresponding to an element. .. _mjs_findDefault: -mjs_findDefault -~~~~~~~~~~~~~~~ +`mjs_findDefault <#mjs_findDefault>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_findDefault @@ -4204,8 +4250,8 @@ Find default in model by class name. .. _mjs_getSpecDefault: -mjs_getSpecDefault -~~~~~~~~~~~~~~~~~~ +`mjs_getSpecDefault <#mjs_getSpecDefault>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_getSpecDefault @@ -4213,8 +4259,8 @@ Get global default from model. .. _mjs_getId: -mjs_getId -~~~~~~~~~ +`mjs_getId <#mjs_getId>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_getId @@ -4222,8 +4268,8 @@ Get element id. .. _mjs_firstChild: -mjs_firstChild -~~~~~~~~~~~~~~ +`mjs_firstChild <#mjs_firstChild>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_firstChild @@ -4231,8 +4277,8 @@ Return body's first child of given type. If recurse is nonzero, also search the .. _mjs_nextChild: -mjs_nextChild -~~~~~~~~~~~~~ +`mjs_nextChild <#mjs_nextChild>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_nextChild @@ -4241,8 +4287,8 @@ If recurse is nonzero, also search the body's subtree. .. _mjs_firstElement: -mjs_firstElement -~~~~~~~~~~~~~~~~ +`mjs_firstElement <#mjs_firstElement>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_firstElement @@ -4250,8 +4296,8 @@ Return spec's first element of selected type. .. _mjs_nextElement: -mjs_nextElement -~~~~~~~~~~~~~~~ +`mjs_nextElement <#mjs_nextElement>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_nextElement @@ -4263,8 +4309,8 @@ Attribute setters ^^^^^^^^^^^^^^^^^ .. _mjs_setBuffer: -mjs_setBuffer -~~~~~~~~~~~~~ +`mjs_setBuffer <#mjs_setBuffer>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_setBuffer @@ -4272,8 +4318,8 @@ Copy buffer. .. _mjs_setString: -mjs_setString -~~~~~~~~~~~~~ +`mjs_setString <#mjs_setString>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_setString @@ -4281,8 +4327,8 @@ Copy text to string. .. _mjs_setStringVec: -mjs_setStringVec -~~~~~~~~~~~~~~~~ +`mjs_setStringVec <#mjs_setStringVec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_setStringVec @@ -4290,8 +4336,8 @@ Split text to entries and copy to string vector. .. _mjs_setInStringVec: -mjs_setInStringVec -~~~~~~~~~~~~~~~~~~ +`mjs_setInStringVec <#mjs_setInStringVec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_setInStringVec @@ -4299,8 +4345,8 @@ Set entry in string vector. .. _mjs_appendString: -mjs_appendString -~~~~~~~~~~~~~~~~ +`mjs_appendString <#mjs_appendString>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_appendString @@ -4308,8 +4354,8 @@ Append text entry to string vector. .. _mjs_setInt: -mjs_setInt -~~~~~~~~~~ +`mjs_setInt <#mjs_setInt>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_setInt @@ -4317,8 +4363,8 @@ Copy int array to vector. .. _mjs_appendIntVec: -mjs_appendIntVec -~~~~~~~~~~~~~~~~ +`mjs_appendIntVec <#mjs_appendIntVec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_appendIntVec @@ -4326,8 +4372,8 @@ Append int array to vector of arrays. .. _mjs_setFloat: -mjs_setFloat -~~~~~~~~~~~~ +`mjs_setFloat <#mjs_setFloat>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_setFloat @@ -4335,8 +4381,8 @@ Copy float array to vector. .. _mjs_appendFloatVec: -mjs_appendFloatVec -~~~~~~~~~~~~~~~~~~ +`mjs_appendFloatVec <#mjs_appendFloatVec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_appendFloatVec @@ -4344,8 +4390,8 @@ Append float array to vector of arrays. .. _mjs_setDouble: -mjs_setDouble -~~~~~~~~~~~~~ +`mjs_setDouble <#mjs_setDouble>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_setDouble @@ -4353,8 +4399,8 @@ Copy double array to vector. .. _mjs_setPluginAttributes: -mjs_setPluginAttributes -~~~~~~~~~~~~~~~~~~~~~~~ +`mjs_setPluginAttributes <#mjs_setPluginAttributes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_setPluginAttributes @@ -4366,8 +4412,8 @@ Attribute getters ^^^^^^^^^^^^^^^^^ .. _mjs_getString: -mjs_getString -~~~~~~~~~~~~~ +`mjs_getString <#mjs_getString>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_getString @@ -4375,8 +4421,8 @@ Get string contents. .. _mjs_getDouble: -mjs_getDouble -~~~~~~~~~~~~~ +`mjs_getDouble <#mjs_getDouble>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_getDouble @@ -4388,8 +4434,8 @@ Spec utilities ^^^^^^^^^^^^^^ .. _mjs_setDefault: -mjs_setDefault -~~~~~~~~~~~~~~ +`mjs_setDefault <#mjs_setDefault>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_setDefault @@ -4397,17 +4443,17 @@ Set element's default. .. _mjs_setFrame: -mjs_setFrame -~~~~~~~~~~~~ +`mjs_setFrame <#mjs_setFrame>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_setFrame -Set element's enlcosing frame. +Set element's enclosing frame. .. _mjs_resolveOrientation: -mjs_resolveOrientation -~~~~~~~~~~~~~~~~~~~~~~ +`mjs_resolveOrientation <#mjs_resolveOrientation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_resolveOrientation @@ -4415,21 +4461,48 @@ Resolve alternative orientations to quat, return error if any. .. _mjs_bodyToFrame: -mjs_bodyToFrame -~~~~~~~~~~~~~~~ +`mjs_bodyToFrame <#mjs_bodyToFrame>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_bodyToFrame Transform body into a frame. +.. _mjs_setUserValue: + +`mjs_setUserValue <#mjs_setUserValue>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjs_setUserValue + +Set user payload, overriding the existing value for the specified key if present. + +.. _mjs_getUserValue: + +`mjs_getUserValue <#mjs_getUserValue>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjs_getUserValue + +Return user payload or NULL if none found. + +.. _mjs_deleteUserValue: + +`mjs_deleteUserValue <#mjs_deleteUserValue>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. mujoco-include:: mjs_deleteUserValue + +Delete user payload. + .. _ElementInitialization: Element initialization ^^^^^^^^^^^^^^^^^^^^^^ .. _mjs_defaultSpec: -mjs_defaultSpec -~~~~~~~~~~~~~~~ +`mjs_defaultSpec <#mjs_defaultSpec>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultSpec @@ -4437,8 +4510,8 @@ Default spec attributes. .. _mjs_defaultOrientation: -mjs_defaultOrientation -~~~~~~~~~~~~~~~~~~~~~~ +`mjs_defaultOrientation <#mjs_defaultOrientation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultOrientation @@ -4446,8 +4519,8 @@ Default orientation attributes. .. _mjs_defaultBody: -mjs_defaultBody -~~~~~~~~~~~~~~~ +`mjs_defaultBody <#mjs_defaultBody>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultBody @@ -4455,8 +4528,8 @@ Default body attributes. .. _mjs_defaultFrame: -mjs_defaultFrame -~~~~~~~~~~~~~~~~ +`mjs_defaultFrame <#mjs_defaultFrame>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultFrame @@ -4464,8 +4537,8 @@ Default frame attributes. .. _mjs_defaultJoint: -mjs_defaultJoint -~~~~~~~~~~~~~~~~ +`mjs_defaultJoint <#mjs_defaultJoint>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultJoint @@ -4473,8 +4546,8 @@ Default joint attributes. .. _mjs_defaultGeom: -mjs_defaultGeom -~~~~~~~~~~~~~~~ +`mjs_defaultGeom <#mjs_defaultGeom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultGeom @@ -4482,8 +4555,8 @@ Default geom attributes. .. _mjs_defaultSite: -mjs_defaultSite -~~~~~~~~~~~~~~~ +`mjs_defaultSite <#mjs_defaultSite>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultSite @@ -4491,8 +4564,8 @@ Default site attributes. .. _mjs_defaultCamera: -mjs_defaultCamera -~~~~~~~~~~~~~~~~~ +`mjs_defaultCamera <#mjs_defaultCamera>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultCamera @@ -4500,8 +4573,8 @@ Default camera attributes. .. _mjs_defaultLight: -mjs_defaultLight -~~~~~~~~~~~~~~~~ +`mjs_defaultLight <#mjs_defaultLight>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultLight @@ -4509,8 +4582,8 @@ Default light attributes. .. _mjs_defaultFlex: -mjs_defaultFlex -~~~~~~~~~~~~~~~ +`mjs_defaultFlex <#mjs_defaultFlex>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultFlex @@ -4518,8 +4591,8 @@ Default flex attributes. .. _mjs_defaultMesh: -mjs_defaultMesh -~~~~~~~~~~~~~~~ +`mjs_defaultMesh <#mjs_defaultMesh>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultMesh @@ -4527,8 +4600,8 @@ Default mesh attributes. .. _mjs_defaultHField: -mjs_defaultHField -~~~~~~~~~~~~~~~~~ +`mjs_defaultHField <#mjs_defaultHField>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultHField @@ -4536,8 +4609,8 @@ Default height field attributes. .. _mjs_defaultSkin: -mjs_defaultSkin -~~~~~~~~~~~~~~~ +`mjs_defaultSkin <#mjs_defaultSkin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultSkin @@ -4545,8 +4618,8 @@ Default skin attributes. .. _mjs_defaultTexture: -mjs_defaultTexture -~~~~~~~~~~~~~~~~~~ +`mjs_defaultTexture <#mjs_defaultTexture>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultTexture @@ -4554,8 +4627,8 @@ Default texture attributes. .. _mjs_defaultMaterial: -mjs_defaultMaterial -~~~~~~~~~~~~~~~~~~~ +`mjs_defaultMaterial <#mjs_defaultMaterial>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultMaterial @@ -4563,8 +4636,8 @@ Default material attributes. .. _mjs_defaultPair: -mjs_defaultPair -~~~~~~~~~~~~~~~ +`mjs_defaultPair <#mjs_defaultPair>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultPair @@ -4572,8 +4645,8 @@ Default pair attributes. .. _mjs_defaultEquality: -mjs_defaultEquality -~~~~~~~~~~~~~~~~~~~ +`mjs_defaultEquality <#mjs_defaultEquality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultEquality @@ -4581,8 +4654,8 @@ Default equality attributes. .. _mjs_defaultTendon: -mjs_defaultTendon -~~~~~~~~~~~~~~~~~ +`mjs_defaultTendon <#mjs_defaultTendon>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultTendon @@ -4590,8 +4663,8 @@ Default tendon attributes. .. _mjs_defaultActuator: -mjs_defaultActuator -~~~~~~~~~~~~~~~~~~~ +`mjs_defaultActuator <#mjs_defaultActuator>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultActuator @@ -4599,8 +4672,8 @@ Default actuator attributes. .. _mjs_defaultSensor: -mjs_defaultSensor -~~~~~~~~~~~~~~~~~ +`mjs_defaultSensor <#mjs_defaultSensor>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultSensor @@ -4608,8 +4681,8 @@ Default sensor attributes. .. _mjs_defaultNumeric: -mjs_defaultNumeric -~~~~~~~~~~~~~~~~~~ +`mjs_defaultNumeric <#mjs_defaultNumeric>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultNumeric @@ -4617,8 +4690,8 @@ Default numeric attributes. .. _mjs_defaultText: -mjs_defaultText -~~~~~~~~~~~~~~~ +`mjs_defaultText <#mjs_defaultText>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultText @@ -4626,8 +4699,8 @@ Default text attributes. .. _mjs_defaultTuple: -mjs_defaultTuple -~~~~~~~~~~~~~~~~ +`mjs_defaultTuple <#mjs_defaultTuple>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultTuple @@ -4635,8 +4708,8 @@ Default tuple attributes. .. _mjs_defaultKey: -mjs_defaultKey -~~~~~~~~~~~~~~ +`mjs_defaultKey <#mjs_defaultKey>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultKey @@ -4644,8 +4717,8 @@ Default keyframe attributes. .. _mjs_defaultPlugin: -mjs_defaultPlugin -~~~~~~~~~~~~~~~~~ +`mjs_defaultPlugin <#mjs_defaultPlugin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_defaultPlugin @@ -4657,8 +4730,8 @@ Element casting ^^^^^^^^^^^^^^^ .. _mjs_asBody: -mjs_asBody -~~~~~~~~~~ +`mjs_asBody <#mjs_asBody>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asBody @@ -4666,8 +4739,8 @@ Safely cast an element as mjsBody, or return NULL if the element is not an mjsBo .. _mjs_asGeom: -mjs_asGeom -~~~~~~~~~~ +`mjs_asGeom <#mjs_asGeom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asGeom @@ -4675,8 +4748,8 @@ Safely cast an element as mjsGeom, or return NULL if the element is not an mjsGe .. _mjs_asJoint: -mjs_asJoint -~~~~~~~~~~~ +`mjs_asJoint <#mjs_asJoint>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asJoint @@ -4684,8 +4757,8 @@ Safely cast an element as mjsJoint, or return NULL if the element is not an mjsJ .. _mjs_asSite: -mjs_asSite -~~~~~~~~~~ +`mjs_asSite <#mjs_asSite>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asSite @@ -4693,8 +4766,8 @@ Safely cast an element as mjsSite, or return NULL if the element is not an mjsSi .. _mjs_asCamera: -mjs_asCamera -~~~~~~~~~~~~ +`mjs_asCamera <#mjs_asCamera>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asCamera @@ -4702,8 +4775,8 @@ Safely cast an element as mjsCamera, or return NULL if the element is not an mjs .. _mjs_asLight: -mjs_asLight -~~~~~~~~~~~ +`mjs_asLight <#mjs_asLight>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asLight @@ -4711,8 +4784,8 @@ Safely cast an element as mjsLight, or return NULL if the element is not an mjsL .. _mjs_asFrame: -mjs_asFrame -~~~~~~~~~~~ +`mjs_asFrame <#mjs_asFrame>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asFrame @@ -4720,8 +4793,8 @@ Safely cast an element as mjsFrame, or return NULL if the element is not an mjsF .. _mjs_asActuator: -mjs_asActuator -~~~~~~~~~~~~~~ +`mjs_asActuator <#mjs_asActuator>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asActuator @@ -4729,8 +4802,8 @@ Safely cast an element as mjsActuator, or return NULL if the element is not an m .. _mjs_asSensor: -mjs_asSensor -~~~~~~~~~~~~ +`mjs_asSensor <#mjs_asSensor>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asSensor @@ -4738,8 +4811,8 @@ Safely cast an element as mjsSensor, or return NULL if the element is not an mjs .. _mjs_asFlex: -mjs_asFlex -~~~~~~~~~~ +`mjs_asFlex <#mjs_asFlex>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asFlex @@ -4747,8 +4820,8 @@ Safely cast an element as mjsFlex, or return NULL if the element is not an mjsFl .. _mjs_asPair: -mjs_asPair -~~~~~~~~~~ +`mjs_asPair <#mjs_asPair>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asPair @@ -4756,8 +4829,8 @@ Safely cast an element as mjsPair, or return NULL if the element is not an mjsPa .. _mjs_asEquality: -mjs_asEquality -~~~~~~~~~~~~~~ +`mjs_asEquality <#mjs_asEquality>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asEquality @@ -4765,8 +4838,8 @@ Safely cast an element as mjsEquality, or return NULL if the element is not an m .. _mjs_asExclude: -mjs_asExclude -~~~~~~~~~~~~~ +`mjs_asExclude <#mjs_asExclude>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asExclude @@ -4774,8 +4847,8 @@ Safely cast an element as mjsExclude, or return NULL if the element is not an mj .. _mjs_asTendon: -mjs_asTendon -~~~~~~~~~~~~ +`mjs_asTendon <#mjs_asTendon>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asTendon @@ -4783,8 +4856,8 @@ Safely cast an element as mjsTendon, or return NULL if the element is not an mjs .. _mjs_asNumeric: -mjs_asNumeric -~~~~~~~~~~~~~ +`mjs_asNumeric <#mjs_asNumeric>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asNumeric @@ -4792,8 +4865,8 @@ Safely cast an element as mjsNumeric, or return NULL if the element is not an mj .. _mjs_asText: -mjs_asText -~~~~~~~~~~ +`mjs_asText <#mjs_asText>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asText @@ -4801,8 +4874,8 @@ Safely cast an element as mjsText, or return NULL if the element is not an mjsTe .. _mjs_asTuple: -mjs_asTuple -~~~~~~~~~~~ +`mjs_asTuple <#mjs_asTuple>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asTuple @@ -4810,8 +4883,8 @@ Safely cast an element as mjsTuple, or return NULL if the element is not an mjsT .. _mjs_asKey: -mjs_asKey -~~~~~~~~~ +`mjs_asKey <#mjs_asKey>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asKey @@ -4819,8 +4892,8 @@ Safely cast an element as mjsKey, or return NULL if the element is not an mjsKey .. _mjs_asMesh: -mjs_asMesh -~~~~~~~~~~ +`mjs_asMesh <#mjs_asMesh>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asMesh @@ -4828,8 +4901,8 @@ Safely cast an element as mjsMesh, or return NULL if the element is not an mjsMe .. _mjs_asHField: -mjs_asHField -~~~~~~~~~~~~ +`mjs_asHField <#mjs_asHField>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asHField @@ -4837,8 +4910,8 @@ Safely cast an element as mjsHField, or return NULL if the element is not an mjs .. _mjs_asSkin: -mjs_asSkin -~~~~~~~~~~ +`mjs_asSkin <#mjs_asSkin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asSkin @@ -4846,8 +4919,8 @@ Safely cast an element as mjsSkin, or return NULL if the element is not an mjsSk .. _mjs_asTexture: -mjs_asTexture -~~~~~~~~~~~~~ +`mjs_asTexture <#mjs_asTexture>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asTexture @@ -4855,8 +4928,8 @@ Safely cast an element as mjsTexture, or return NULL if the element is not an mj .. _mjs_asMaterial: -mjs_asMaterial -~~~~~~~~~~~~~~ +`mjs_asMaterial <#mjs_asMaterial>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asMaterial @@ -4864,8 +4937,8 @@ Safely cast an element as mjsMaterial, or return NULL if the element is not an m .. _mjs_asPlugin: -mjs_asPlugin -~~~~~~~~~~~~ +`mjs_asPlugin <#mjs_asPlugin>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. mujoco-include:: mjs_asPlugin diff --git a/doc/APIreference/functions_override.rst b/doc/APIreference/functions_override.rst index 447a0a05..ec72a183 100644 --- a/doc/APIreference/functions_override.rst +++ b/doc/APIreference/functions_override.rst @@ -47,13 +47,23 @@ struct pointers while editing the model programmatically. :ref:`mj_recompile` returns 0 if compilation succeed. In the case of failure, the given :ref:`mjModel` and :ref:`mjData` instances will be deleted; as in :ref:`mj_compile`, the compilation error can be read with :ref:`mjs_getError`. +.. _mj_saveLastXML: + +Update XML data structures with info from low-level model created with :ref:`mj_loadXML`, save as MJCF. +If error is not NULL, it must have size error_sz. + +Note that this function only saves models that have been loaded with :ref:`mj_loadXML`, the legacy loading mechanism. +See the :ref:`model editing` chapter to understand the difference between the old and new model loading and +saving mechanisms. + .. _mj_saveXMLString: -Save spec to XML string, return 1 on success, 0 otherwise. XML saving requires that the spec first be compiled. +Save spec to XML string, return 0 on success, -1 on failure. If the length of the output buffer is too small, returns +the required size. XML saving automatically compiles the spec before saving. .. _mj_saveXML: -Save spec to XML file, return 1 on success, 0 otherwise. XML saving requires that the spec first be compiled. +Save spec to XML file, return 0 on success, -1 otherwise. XML saving requires that the spec first be compiled. .. _Mainsimulation: @@ -221,16 +231,16 @@ Returns the smallest signed distance between two geoms and optionally the segmen Returned distances are bounded from above by ``distmax``. |br| If no collision of distance smaller than ``distmax`` is found, the function will return ``distmax`` and ``fromto``, if given, will be set to (0, 0, 0, 0, 0, 0). -.. admonition:: Positive ``distmax`` values - :class: note + .. admonition:: different (correct) behavior under `nativeccd` + :class: note - .. TODO: b/339596989 - Improve mjc_Convex. + As explained in :ref:`Collision Detection`, distances are inaccurate when using the + :ref:`legacy CCD pipeline`, and its use is discouraged. - For some colliders, a large, positive ``distmax`` will result in an accurate measurement. However, for collision - pairs which use the general ``mjc_Convex`` collider, the result will be approximate and likely innacurate. - This is considered a bug to be fixed in a future release. - In order to determine whether a geom pair uses ``mjc_Convex``, inspect the table at the top of - `engine_collision_driver.c `__. +.. _mj_fullM: + +Convert sparse inertia matrix ``M`` into full (i.e. dense) matrix. +|br| ``dst`` must be of size ``nv x nv``, ``M`` must be of the same size as ``mjData.qM``. .. _mj_mulM: @@ -694,3 +704,8 @@ to the inputs. Below, :math:`\bar q` denotes the pre-modified quaternion: Note that derivatives depend only on :math:`h` and :math:`v` (in fact, on :math:`s = h v`). All outputs are optional. + +.. _mjs_delete: + +Delete object corresponding to the given element, return 0 on success. This function should only be used for element +types that cannot have children, i.e. excluding bodies and default classes. diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst index 8c3e72de..ca7258f8 100644 --- a/doc/XMLreference.rst +++ b/doc/XMLreference.rst @@ -264,6 +264,11 @@ how to use includes and how to modularize large files if desired. The name of the XML file to be included. The file location is relative to the directory of the main MJCF file. If the file is not in the same directory, it should be prefixed with a relative path. +.. admonition:: Prefer attach to include + :class: note + + While some use cases for :ref:`include` remain valid, it is recommended to use the + :ref:`attach` element instead, where applicable. .. _mujoco: @@ -577,6 +582,12 @@ from its default. This flag disables the mid-phase collision filtering using a static AABB bounding volume hierarchy (a BVH binary tree). If disabled, all geoms pairs that are allowed to collide are checked for collisions. +.. _option-flag-nativeccd: + +:at:`nativeccd`: :at-val:`[disable, enable], "enable"` + This flag enables the native convex collision detection pipeline instead of using the + `libccd library `__, see :ref:`convex collisions` for more details. + .. _option-flag-eulerdamp: :at:`eulerdamp`: :at-val:`[disable, enable], "enable"` @@ -586,7 +597,7 @@ from its default. .. _option-flag-autoreset: :at:`autoreset`: :at-val:`[disable, enable], "enable"` - This flag disables the automatic reseting of the simulation state when numerical issues are detected. + This flag disables the automatic resetting of the simulation state when numerical issues are detected. .. _option-flag-override: @@ -596,9 +607,17 @@ from its default. .. _option-flag-energy: :at:`energy`: :at-val:`[disable, enable], "disable"` - This flag enables the computation of kinetic and potential energy, stored in mjData.energy and displayed in the GUI. - This feature adds some CPU time but it is usually negligible. Monitoring energy for a system that is supposed to be - energy-conserving is one of the best ways to assess the accuracy of a complex simulation. + This flag enables the computation of potential and kinetic energy in ``mjData.energy[0, 1]`` respectively, + and displayed in the simulate GUI info overlay. Potential energy includes the gravitational component summed over + all bodies :math:`\sum_b m_b g h` and energy stored in passive springs in joints, tendons and flexes + :math:`\tfrac{1}{2} k x^2`, where :math:`x` is the displacement and :math:`k` is the spring constant. Kinetic + energy is given by :math:`\tfrac{1}{2} v^T M v`, where :math:`v` is the velocity and :math:`M` is the + mass matrix. Note that potential and kinetic energy in constraints is not accounted for. + + The extra computation (also triggered by :ref:`potential` and + :ref:`kinetic` energy sensors) adds some CPU time but it is usually negligible. Monitoring energy + for a system that is supposed to be energy-conserving is one of the best ways to assess the accuracy of a complex + simulation. .. _option-flag-fwdinv: @@ -622,14 +641,12 @@ from its default. .. _option-flag-multiccd: -:at:`multiccd`: :at-val:`[disable, enable], "disable"` |nbsp| |nbsp| |nbsp| (experimental feature) +:at:`multiccd`: :at-val:`[disable, enable], "disable"` This flag enables multiple-contact collision detection for geom pairs that use a general-purpose convex-convex - collider e.g., mesh-mesh collisions. This can be useful when the contacting geoms have a flat surface, and the + collider e.g., mesh-mesh collisions. This can be useful when the contacting geoms have a flat surface and the single contact point generated by the convex-convex collider cannot accurately capture the surface contact, leading - to instabilities that typically manifest as sliding or wobbling. Multiple contact points are found by rotating the - two geoms by ±1e-3 radians around the tangential axes and re-running the collision function. If a new contact is - detected it is added, allowing for up to 4 additional contact points. This feature is currently considered - experimental, and both the behavior and the way it is activated may change in the future. + to instabilities that typically manifest as sliding or wobbling. The implementation of this feature depends on the + selected convex collision pipeline, see :ref:`convex collisions` for more details. .. _option-flag-island: @@ -639,12 +656,6 @@ from its default. allows for `island visualization `__. In a future release, the constraint solver will exploit the disjoint nature of constraint islands. -.. _option-flag-nativeccd: - -:at:`nativeccd`: :at-val:`[disable, enable], "disable"` - This flag enables the native convex collision detection pipeline instead of using the - `libccd library `__. - .. _compiler: **compiler** (*) @@ -772,23 +783,11 @@ has any effect. The settings here are global and apply to the entire model. models compiled with this flag, it is important to remember that collision geoms are often placed in a :ref:`group` which is invisible by default. -.. _compiler-convexhull: - -:at:`convexhull`: :at-val:`[false, true], "true"` - If this attribute is "true", the compiler will automatically generate a convex hull for every mesh that is used in at - least one non-visual geom (in the sense of the discardvisual attribute above). This is done to speed up collision - detection; recall :ref:`Collision` section in the Computation chapter. Even if the mesh is already convex, the hull - contains edge information that is not present in the mesh file, so it needs to be constructed. The only reason to - disable this feature is to speed up re-loading of a model with large meshes during model editing (since the convex - hull computation is the slowest operation performed by the compiler). However once model design is finished, this - feature should be enabled, because the availability of convex hulls substantially speeds up collision detection with - large meshes. - .. _compiler-usethread: :at:`usethread`: :at-val:`[false, true], "true"` If this attribute is "true", the model compiler will run in multi-threaded mode. Currently multi-threading is used - for computing the length ranges of actuators and for loading meshes. + for computing the length ranges of actuators and for parallel loading of meshes. .. _compiler-fusestatic: @@ -1245,21 +1244,21 @@ The full list of processing steps applied by the compiler to each mesh is as fol .. _asset-mesh-inertia: -:at:`inertia`: :at-val:`[convex, exact, legacy], "legacy"` +:at:`inertia`: :at-val:`[convex, exact, legacy, shell], "legacy"` This attribute controls how the mesh is used when mass and inertia are - :ref:`inferred from geometry<_compiler-inertiafromgeom>`. The current default value :at-val:`legacy` will be changed + :ref:`inferred from geometry`. The current default value :at-val:`legacy` will be changed to :at-val:`convex` in a future release. - :at-val:`convex` - Use the mesh's convex hull to compute volume and inertia. + :at-val:`convex`: Use the mesh's convex hull to compute volume and inertia, assuming uniform density. - :at-val:`exact` - Use an exact algorithm to compute volume and inertia. This algorithm requires a well-oriented, watertight mesh and - will error otherwise. + :at-val:`exact`: Compute volume and inertia exactly, even for non-convex meshes. This algorithm requires a + well-oriented, watertight mesh and will error otherwise. - :at-val:`legacy` - Use the legacy algorithm, which is similar to :at-val:`convex`, but leads to volume overcounting for non-convex - meshes. + :at-val:`legacy`: Use the legacy algorithm, leads to volume overcounting for non-convex meshes. Though currently the + default to avoid breakages, it is not recommended. + + :at-val:`shell`: Assume mass is concentrated on the surface of the mesh. Use the mesh's surface to compute + the inertia, assuming uniform surface density. .. _asset-mesh-smoothnormal: @@ -1273,7 +1272,7 @@ The full list of processing steps applied by the compiler to each mesh is as fol :at:`maxhullvert`: :at-val:`int, "-1"` Maximum number of vertices in a mesh's convex hull. Currently this is implemented by asking qhull - `to teminate `__ after :at:`maxhullvert` vertices. The default + `to terminate `__ after :at:`maxhullvert` vertices. The default value of -1 means "unlimited". Positive values must be larger than 3. .. _asset-mesh-vertex: @@ -1710,9 +1709,9 @@ properties are grouped together. loaded explicitly via the :ref:`texture ` element and then referenced here. The texture referenced here is used for specifying the RGB values. For advanced rendering (e.g., Physics-Based Rendering), more texture types need to be specified (e.g., roughness, metallic). In this case, this texture attribute should be omitted, and - the texture types should be specified explicitly via the specific role child elements, e.g., - :ref:`texture `. Note however that the built-in renderer does not support PBR properties, so these - advanced rendering features are only available when using an external renderer. + the texture types should be specified using :ref:`layer ` child elements. Note however that the + built-in renderer does not support PBR properties, so these advanced rendering features are only available when using + an external renderer. .. _asset-material-texrepeat: @@ -1784,116 +1783,59 @@ properties are grouped together. model element which defines its own local rgba attribute, the local definition has precedence. Note that this "local" definition could in fact come from a defaults class. The remaining material properties always apply. -.. _material-rgb: +.. _material-layer: -:el-prefix:`material/` |-| **rgb** (?) -'''''''''''''''''''''''''''''''''''''' +:el-prefix:`material/` |-| **layer** (?) +'''''''''''''''''''''''''''''''''''''''' -This element references a texture asset used to specify base color / albedo values. +If multiple textures are needed to specify the appearance of a material, the :ref:`texture ` +attribute cannot be used, and :el:`layer` child elements must be used instead. Specifying both the :at:`texture` +attribute and :el:`layer` child elements is an error. -.. _material-rgb-texture: +.. _material-layer-texture: :at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly 3 channels. + Name of the texture, like the :ref:`texture ` attribute. -.. _material-normal: +.. _material-layer-role: -:el-prefix:`material/` |-| **normal** (?) -''''''''''''''''''''''''''''''''''''''''' +:at:`role`: :at-val:`string, required` + Role of the texture. The valid values, expected number of channels, and the role semantics are: -This element references a texture asset used to specify the bump map (surface normals). - -.. _material-normal-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly 3 channels. - -.. _material-occlusion: - -:el-prefix:`material/` |-| **occlusion** (?) -'''''''''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify ambient occlusion. - -.. _material-occlusion-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly one channel. - -.. _material-roughness: - -:el-prefix:`material/` |-| **roughness** (?) -'''''''''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify the roughness map. - -.. _material-roughness-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly one channel. - -.. _material-metallic: - -:el-prefix:`material/` |-| **metallic** (?) -''''''''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify the metallic map. - -.. _material-metallic-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly one channel. - -.. _material-opacity: - -:el-prefix:`material/` |-| **opacity** (?) -'''''''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify the opacity map (alpha channel, transparency). - -.. _material-opacity-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly one channel. - -.. _material-emissive: - -:el-prefix:`material/` |-| **emissive** (?) -''''''''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify light emission. - -.. _material-emissive-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly 4 channels. - -.. _material-orm: - -:el-prefix:`material/` |-| **orm** (?) -'''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify a packed ORM map, where occlusion, roughness, and metallic -are joined into the corresponding RGB values of a single texture. - -.. _material-orm-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly 3 channels. - -.. _material-rgba: - -:el-prefix:`material/` |-| **rgba** (?) -''''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify a packed map where albedo and opacity are joined into the same -4-channel texture. - -.. _material-rgba-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly 4 channels. + .. list-table:: + :widths: 1 1 8 + :header-rows: 1 + * - value + - channels + - description + * - :at:`rgb` + - 3 + - base color / albedo [red, green, blue] + * - :at:`normal` + - 3 + - bump map (surface normals) + * - :at:`occlusion` + - 1 + - ambient occlusion + * - :at:`roughness` + - 1 + - roughness + * - :at:`metallic` + - 1 + - metallicity + * - :at:`opacity` + - 1 + - opacity (alpha channel) + * - :at:`emissive` + - 4 + - RGB light emmision intensity, exposure weight in 4th channel + * - :at:`orm` + - 3 + - packed 3 channel [occlusion, roughness, metallic] + * - :at:`rgba` + - 4 + - packed 4 channel [red, green, blue, alpha] .. _asset-model: @@ -1946,11 +1888,11 @@ defined. Its body name is automatically defined as "world". :at:`mocap`: :at-val:`[false, true], "false"` If this attribute is "true", the body is labeled as a mocap body. This is allowed only for bodies that are children of the world body and have no joints. Such bodies are fixed from the viewpoint of the dynamics, but nevertheless the - forward kinematics set their position and orientation from the fields mjData.mocap_pos and mjData.mocap_quat at each + forward kinematics set their position and orientation from the fields ``mjData.mocap_{pos,quat}`` at each time step. The size of these arrays is adjusted by the compiler so as to match the number of mocap bodies in the model. This mechanism can be used to stream motion capture data into the simulation. Mocap bodies can also be moved via mouse perturbations in the interactive visualizer, even in dynamic simulation mode. This can be useful for - creating props with adjustable position and orientation. See also the mocap attribute of :ref:`flag `. + creating props with adjustable position and orientation. .. _body-pos: @@ -2181,7 +2123,7 @@ rotations as unit quaternions. (``mjData.qfrc_actuator``) rather than passive forces (``mjData.qfrc_passive``). Notionally, this means that gravity compensation is the result of a control system rather than natural buoyancy. In practice, enabling this flag is useful when joint-level actuator force clamping is used. In this case, the total actuation force applied on a joint, - including gravity compensation, is guaranteed to not exceeed the specified limits. See :ref:`CForceRange` and + including gravity compensation, is guaranteed to not exceed the specified limits. See :ref:`CForceRange` and :ref:`actuatorfrcrange` for more details on this type of force limit. .. _body-joint-margin: @@ -2426,7 +2368,8 @@ helps clarify the role of bodies and geoms in MuJoCo. This attribute specifies an integer group to which the geom belongs. The only effect on the physics is at compile time, when body masses and inertias are inferred from geoms selected based on their group; see inertiagrouprange attribute of :ref:`compiler `. At runtime this attribute is used by the visualizer to enable and disable - the rendering of entire geom groups. It can also be used as a tag for custom computations. + the rendering of entire geom groups. By default, groups 0, 1 and 2 are visible, while all other groups are invisible. + The group attribute can also be used as a tag for custom computations. .. _body-geom-priority: @@ -2515,8 +2458,10 @@ helps clarify the role of bodies and geoms in MuJoCo. .. _body-geom-shellinertia: :at:`shellinertia` :at-val:`[false, true], "false"` - If true, the geom's inertia is computed assuming that all the mass is concentrated on the boundary. In this case - :at:`density` is interpreted as surface density rather than volumetric density. + If true, the geom's inertia is computed assuming that all the mass is concentrated on the surface. In this case + :at:`density` is interpreted as surface rather than volumetric density. This attribute only applies to primitive + geoms and is ignored for meshes. Surface inertia for meshes can be specified by setting the + :ref:`asset/mesh/inertia` attribute to :at-val:`"shell"`. .. _body-geom-solmix: @@ -2563,7 +2508,7 @@ helps clarify the role of bodies and geoms in MuJoCo. `. The frame position is in the middle between the end points. If this attribute is specified, the remaining position and orientation-related attributes are ignored. The image on the right demonstrates use of :at:`fromto` with the four supported geoms, using identical Z values. The model is `here <_static/fromto.xml>`__. - Note that the :at:`fromto` semantics of *capsule* are unique: the two end points specify the segement around which + Note that the :at:`fromto` semantics of *capsule* are unique: the two end points specify the segment around which the radius defines the capsule surface. .. _body-geom-pos: @@ -2794,7 +2739,7 @@ and the +Y axis points up. Thus the frame position and orientation are the key a :at:`mode`: :at-val:`[fixed, track, trackcom, targetbody, targetbodycom], "fixed"` This attribute specifies how the camera position and orientation in world coordinates are computed in forward kinematics (which in turn determine what the camera sees). "fixed" means that the position and orientation specified - below are fixed relative to the the body where the camera is defined. "track" means that the camera position is at a + below are fixed relative to the body where the camera is defined. "track" means that the camera position is at a constant offset from the body in world coordinates, while the camera orientation is constant in world coordinates. These constants are determined by applying forward kinematics in qpos0 and treating the camera as fixed. Tracking can be used for example to position a camera above a body, point it down so it sees the body, and have it always remain @@ -3017,14 +2962,14 @@ the direction specified by the dir attribute. It does not have a full spatial fr ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This is not a model element, but rather a macro which expands into multiple model elements representing a composite -object. These elements are bodies (with their own joints, geoms and sites) that become children of the parent body -containing the macro, as well as tendons and equality constraints added to the corresponding model sections. The -automatically-generated bodies are laid out in a regular grid in 1D, 2D or 3D depending on the object type and count -attributes. The macro expansion is done by the model compiler. If the resulting model is then saved, the macro will be +object. These elements are bodies (with their own joints and geoms) that become children of the parent body containing +the macro. The macro expansion is done by the model compiler. If the resulting model is then saved, the macro will be replaced with the actual model elements. The defaults mechanism used in the rest of MJCF does not apply here, even if the parent body has a childclass attribute defined. Instead there are internal defaults adjusted automatically for each -composite object type. Composite objects can only be defined if the model is in local coordinates. Using them in global -coordinates results in compiler error. See :ref:`CComposite` in the modeling guide for more detailed explanation. +composite object type. See :ref:`CComposite` in the modeling guide for more detailed explanation. Note that there used +to be several composite types, but they have incrementally replaced by :ref:`replicate` (for repeated +objects) and :ref:`flexcomp` (for soft objects). Therefore, the only supported composite type is now +cable, which produces an inextensible chain of bodies connected with ball joints. .. _body-composite-prefix: @@ -3035,37 +2980,8 @@ coordinates results in compiler error. See :ref:`CComposite` in the modeling gui .. _body-composite-type: -:at:`type`: :at-val:`[particle, grid, cable, rope, loop, cloth, box, cylinder, ellipsoid], required` - This attribute determines the type of composite object. The remaining attributes and sub-elements are then - interpreted according to the type. Default settings are also adjusted depending on the type. - - The **particle** type creates a 1D, 2D or 3D grid of equally-spaced bodies. By default, each body has a single sphere - geom and 3 orthogonal sliding joints, allowing translation but not rotation. The geom condim and priority attributes - are set to 1 by default. This makes the spheres have frictionless contacts with all other geoms (unless the priority - of some frictional geom is higher). The user can replace the default sliders with multiple joints of kind="particle" - and replace the default sphere with a custom geom. Note that the particle composite type is deprecated and might be - removed in a future version. Instead of particle, it is recommended to use :ref:`replicate`. - - The **grid** type creates a 1D or 2D grid of bodies, each having a sphere geom, a sphere site, and 3 orthogonal - sliding joints by default. The :el:`pin` sub-element can be used to specify that some bodies should not have joints, - and instead should be pinned to the parent body. Unlike the particle type, here each two neighboring bodies are - connected with a spatial tendon whose length is equality-constrained to its initial value (the sites are needed to - define the tendons). The "main" tendons are parallel to the axes of the grid. In addition one can create diagonal - "shear" tendons, using the :el:`tendon` sub-element. This type is suitable for simulating strings as well as cloth. - - The **rope** type creates a 1D grid of bodies, each having a geom with user-defined type (sphere, capsule or - ellipsoid) and 2 hinge joints with axes orthogonal to the grid, creating a universal joint with the previous body. - This corresponds to a kinematic chain which can bend but cannot stretch or twist. In addition, one can specify - stretch and twist joints (slide and hinge respectively) with the :el:`joint` sub-element. When specified, these extra - joints are equality-constrained, but the constraint is soft by default so that some stretch and twist are possible. - The rope can extend in one or both directions from the parent body. To specify the origin of the rope, the parent - body *must* be named so that it fits the automatic naming convention. For example, to make the parent be the first - body in the chain, and assuming we have prefix="C", the parent body should be named "CB0". When the parent is not at - the end, the rope consists of two kinematic chains starting at the parent and extending in opposite directions. - - The **loop** type is the same as the rope type except the elements are arranged in a circle, and the first and last - elements are equality-constrained to remain connected (using the "connect" constraint type). The softness of this - equality constraint is adjusted with the attributes solrefsmooth and solimpsmooth. +:at:`type`: :at-val:`[cable], required` + This attribute determines the type of composite object. The only supported type is cable. The **cable** type creates a 1D chain of bodies connected with ball joints, each having a geom with user-defined type (cylinder, capsule or box). The geometry can either be defined with an array of 3D vertex coordinates :at:`vertex` @@ -3074,34 +2990,6 @@ coordinates results in compiler error. See :ref:`CComposite` in the modeling gui :at:`size`, resulting in :math:`f(s)=\{\text{size}[1]\cdot\cos(2\pi\cdot\text{size}[2]),\; \text{size}[1]\cdot\sin(2\pi\cdot\text{size}[2]),\; \text{size}[0]\cdot s\}`. - The **cloth** type is a different way to model cloth, beyond type="grid". Here the elements are connected with - universal joints and form a kinematic spanning tree. The root of the tree is the parent body, and its coordinates in - the grid are inferred from its name - similar to rope but here the naming format is "CB2_0". Neighboring bodies that - are not connected with joints are then connected with equality-constrained spatial tendons. The resulting cloth is - non-homogeneous, because the kinematic constraints cannot be violated while the tendon equality constraints are soft. - One can make it more homogeneous by adding stretch and twist joints (similar to rope) and adjusting the strength of - their equality constraints. Shear tendons can also be added. In addition to the different physics, cloth can do - things that a 2D grid cannot do. This is because the elements of cloth have both position and orientation, while the - elements of grid can only translate. The geoms used in cloth can be ellipsoids and capsules in addition to spheres. - When elongated geoms are used, they are rotated and interleaved in a pattern that fills the holes, preventing objects - from penetrating the cloth. Furthermore the inertia of the cloth elements can be modified with the flatinertia - attribute, and can then be used with lift and drag forces to simulate ripple effects. - - The **box** type creates a 3D arrangement of bodies forming the outer shell of a (soft) box. The parent body is at - the center of the box. Each element body has a geom (sphere, ellipsoid or capsule) and a single sliding joint - pointing away from the center of the box. The sliding joints are equality-constrained to their initial value. - Furthermore, to achieve smooth deformations of the sides of the box, each joint is equality-constrained to remain - equal to its neighbor joints. To preserve the volume of the soft box approximately, a fixed tendon is used to - constrain the sum of all joints to remain constant. When the user specifies elongated geoms (capsules or ellipsoids) - their long axis is aligned with the sliding joint axis. This makes the shell thicker for collision detection - purposes, preventing objects from penetrating the box. It is important to disable contacts between the elements of - the box. This is done by setting the default geom contype to 0. The user can change it of course, but if the geoms - comprising the soft box are allowed to contact each other the model will not work as intended. - - The **cylinder** and **ellipsoid** types are the same as box, except the elements are projected on the surface of an - ellipsoid or a cylinder respectively. Thus the composite soft body shape is different, while everything else is the - same as in the box type. - .. _body-composite-count: :at:`count`: :at-val:`int(3), required` @@ -3112,61 +3000,33 @@ coordinates results in compiler error. See :ref:`CComposite` in the modeling gui parent body. Note that some types imply a grid of certain dimensionality, so the requirements for this attribute depend on the specified type. -.. _body-composite-spacing: - -:at:`spacing`: :at-val:`real, required` - The spacing between the centers of the grid elements. This spacing is the same in all dimensions. It should normally - be set to a value larger than the geom size, otherwise there will be a lot of contacts in the reference model - configuration (which is allowed but rarely desirable). - .. _body-composite-offset: :at:`offset`: :at-val:`real(3), "0 0 0"` - This attribute affects particle and grid types, and is ignored for all other types. It specifies a 3D offset from the - center of the parent body to the center of the grid of elements. The offset is expressed in the local coordinate - frame of the parent body. - -.. _body-composite-flatinertia: - -:at:`flatinertia`: :at-val:`real, "0"` - This attribute affects the cloth type and is ignored for all other types. The default value 0 disables this - mechanism. When the value is positive, it specifies the ratio of the small-to-large axes of the modified diagonal - inertia. The idea is to set it to a small value, say 0.01, in which case the inertias of the body elements will - corresponds to flat boxes aligned with the cloth (which can then be used for lift forces). This will not change the - geom shapes, but instead will set the body inertias directly and disable the automatic computation of inertia from - geom shape for the composite body only. - -.. _body-composite-solrefsmooth: - -.. _body-composite-solimpsmooth: - -:at:`solrefsmooth`, :at:`solimpsmooth` - These are the solref and solimp attributes of the loop-closure equality constraint for loop types, and the - smoothness-preserving equality constraint for box, cylinder and ellipsoid types. For all other types they have no - effect. They obey the same rules as all other solref and solimp attributes in MJCF, except their defaults here are - adjusted depending on the composite type. See :ref:`CSolver`. + It specifies a 3D offset from the center of the parent body to the center of the grid of elements. The offset is + expressed in the local coordinate frame of the parent body. .. _body-composite-vertex: :at:`vertex`: :at-val:`real(3*nvert), optional` - Vertex 3D positions in global coordinates (cable only). + Vertex 3D positions in global coordinates. .. _body-composite-initial: :at:`initial`: :at-val:`[free, ball, none], "0"` - Behavior of the first point (cable only). Free: free joint. Ball: ball joint. None: no dof. + Behavior of the first point. Free: free joint. Ball: ball joint. None: no dof. .. _body-composite-curve: :at:`curve`: :at-val:`string(3), optional` - Functions specifying the vertex positions (cable only). Available functions are `s`, `cos(s)`, and `sin(s)`, where - `s` is the arc length parameter. + Functions specifying the vertex positions. Available functions are `s`, `cos(s)`, and `sin(s)`, where `s` is the arc + length parameter. .. _body-composite-size: :at:`size`: :at-val:`int(3), optional` - Scaling of the curve functions (cable only). `size[0]` is the scaling of `s`, `size[1]` is the radius of `\cos(s)` - and `\sin(s)`, and `size[2]` is the speed of the argument (i.e. `\cos(2*\pi*size[2]*s)`). + Scaling of the curve functions. `size[0]` is the scaling of `s`, `size[1]` is the radius of `\cos(s)` and `\sin(s)`, + and `size[2]` is the speed of the argument (i.e. `\cos(2*\pi*size[2]*s)`). .. _composite-joint: @@ -3180,7 +3040,7 @@ joints should be created, as well as to adjust the attributes of both automatic .. _composite-joint-kind: -:at:`kind`: :at-val:`[main, twist, stretch, particle], required` +:at:`kind`: :at-val:`[main], required` The joint kind here is orthogonal to the joint type in the rest of MJCF. The joint kind refers to the function of the joint within the mechanism comprising the composite body, while the joint type (hinge or slide) is implied by the joint kind and composite body type. @@ -3190,18 +3050,6 @@ joints should be created, as well as to adjust the attributes of both automatic sliders for box, cylinder and rope; universal joints for cloth, rope and loop. Even though the main joints are included automatically, this sub-element is still useful for adjusting their attributes. - The **twist** kind corresponds to hinge joints enabling rope, loop and cloth objects to twist. These are optional - joints and are only created if this sub-element is present. This sub-element is also used to adjust the attributes of - the optional twist joints. For other composite object types this sub-element has no effect. - - The **stretch** kind corresponds to slide joints enabling rope, loop and cloth objects to stretch. These are optional - joints and are only created if this sub-element is present. This sub-element is also used to adjust the attributes of - the optional stretch joints. For other composite object types this sub-element has no effect. - - The **particle** kind can only be used with the particle composite type. As opposed to all previous kinds, this kind - *replaces* the default 3 sliders with user-defined joints. User-defined joints can be repeated, for example - to create planar particles with two sliders and a hinge. - .. _composite-joint-solreffix: .. _composite-joint-solimpfix: @@ -3249,73 +3097,6 @@ joints should be created, as well as to adjust the attributes of both automatic Same meaning as regular :ref:`joint ` attributes. -.. _composite-tendon: - -:el-prefix:`composite/` |-| **tendon** (*) -'''''''''''''''''''''''''''''''''''''''''' - -Tendons are treated similarly to joints in composite objects. The tendon kind specified here together with the composite -body type imply the tendon type as used in the rest of MJCF. This sub-element is used to both create optional tendons, -and adjust the attributes of automatic and optional tendons. One difference from joints is that all tendons used in -composite objects are equality-constrained. - -.. _composite-tendon-kind: - -:at:`kind`: :at-val:`[main, shear], required` - The **main** kind corresponds to tendons holding the composite body together. These are the spatial tendons that - connect neighboring bodies in grid and cloth, and the fixed tendon used to preserve the volume of box, cylinder and - ellipsoid. For other composite types this sub-element has no effect. - - The **shear** kind corresponds to diagonal tendons that prevent shear (as opposed to enabling - which is the function - of optional joints). Such tendons can be created in 2D grid objects and cloth objects. For all other composite object - types this sub-element has no effect. - -.. _composite-tendon-solreffix: - -.. _composite-tendon-solimpfix: - -:at:`solreffix`, :at:`solimpfix` - These are the solref and solimp attributes used to equality-constrain the tendon. The defaults are adjusted depending - on the composite type. Otherwise these attributes obey the same rules as all other solref and solimp attributes in - MJCF. See :ref:`CSolver`. - -.. _composite-tendon-group: - -.. _composite-tendon-stiffness: - -.. _composite-tendon-damping: - -.. _composite-tendon-limited: - -.. _composite-tendon-range: - -.. _composite-tendon-margin: - -.. _composite-tendon-solreflimit: - -.. _composite-tendon-solimplimit: - -.. _composite-tendon-frictionloss: - -.. _composite-tendon-solreffriction: - -.. _composite-tendon-solimpfriction: - -.. _composite-tendon-material: - -.. _composite-tendon-rgba: - -.. _composite-tendon-width: - -.. |body/composite/tendon attrib list| replace:: - :at:`group`, :at:`stiffness`, :at:`damping`, :at:`limited`, :at:`range`, :at:`margin`, :at:`solreflimit`, - :at:`solimplimit`, :at:`frictionloss`, :at:`solreffriction`, :at:`solimpfriction`, :at:`material`, :at:`rgba`, - :at:`width` - -|body/composite/tendon attrib list| - Same meaning as regular :ref:`tendon ` attributes. - - .. _composite-geom: :el-prefix:`composite/` |-| **geom** (?) @@ -3437,22 +3218,6 @@ automatically-generated skin. bi-cubic interpolation. This increases the quality of the rendering (especially in the absence of textures) but also slows down the renderer, so use it with caution. Values above 3 are unlikely to be needed. -.. _composite-pin: - -:el-prefix:`composite/` |-| **pin** (*) -''''''''''''''''''''''''''''''''''''''' - -This sub-element can be used to pin some of the element bodies in grid objects (both 1D and 2D). Pinning means that the -corresponding body has no joints, and therefore it is rigidly fixed to the parent body. When the parent is the world, -this has the effect of hanging a string or a cloth in space. If the parent body is moving, this can be used to model a -handle where the composite object is attached. For other composite types this sub-element has no effect. - -.. _composite-pin-coord: - -:at:`coord`: :at-val:`int(2), required` - The grid coordinates of the element body which should be pinned. The coordinates are zero-based. For 1D grids this - attribute can have only one number, in which case the second number is automatically set to 0. - .. _composite-plugin: @@ -3559,9 +3324,48 @@ saving the XML: radius in 2D, and tetrahedra with radius in 3D. Certain flexcomp types imply a dimensionality, in which case the value specified here is ignored. +.. youtube:: uNt3i8hrJu4 + :align: right + :width: 240px + +.. _body-flexcomp-dof: + +:at:`dof`: :at-val:`[full, radial, trilinear], "full"` + The parametrization of the flex's degrees of freedom (dofs). See the video on the right illustrating the + different parametrizations with deformable spheres. The three models in the video are respectively + `sphere_full `__, + `sphere_radial `__ + and `sphere_trilinear `__. + + **full** + Three translational dofs per vertex. This is the most expressive but also the most expensive option. + + **radial** + A single radial translational dof per vertex. Note that unlike in the "full" case, the radial parametrization + requires a free joint at the flex's parent in order for free body motion to be possible. This type of + parametrization is appropriate for shapes that are relatively spherical. + + **trilinear** + Three translational dofs at each corner of the bounding box of the flex, for a total of 24 dofs for the entire + flex, independent of the number of vertices. The positions of the vertices are updated using trilinear + interpolation over the bounding box. + + .. youtube:: qJFbx-FR7Bc + :align: right + :width: 240px + + Trilinear flexes are much faster than the previous two options, and are the preferred choice if the expected + deformations can be captured by the reduced parametriation. For example, see the video on the right comparing `full + `__ and `trilinear + `__ flexes for modeling + deformable gripper pads. + + Note that the choice of dof parametrization affects the deformation modes of the flex but has no effect on the + accuracy of the collision geometry, which always takes into account the high-resolution mesh of the flex. + .. _body-flexcomp-type: -:at:`type`: :at-val:`[grid, box, cylinder, ellipsoid, mesh, gmsh, direct], "grid"` +:at:`type`: :at-val:`[grid, box, cylinder, ellipsoid, disc, circle, mesh, gmsh, direct], "grid"` This attribute determines the type of :el:`flexcomp` object. The remaining attributes and sub-elements are then interpreted according to the type. Default settings are also adjusted depending on the type. Different types correspond to different methods for specifying the flexcomp points and the stretchable elements that connect them. @@ -3585,11 +3389,19 @@ saving the XML: **ellipsoid** is the same as **box**, except the points are projected on the surface of an ellipsoid. + **disc** is the same as **box**, except the points are projected on the surface of a disc. It is only compatible + with :at:`dim=2`. + + **circle** is the same as **grid**, except the points are sampled along a circle so that the first and last points + are the same. The radius of the circle is computed such that each segment has the requested spacing. It is only + compatible with :at:`dim=1`. + **mesh** loads the flexcomp points and elements (i.e. triangles) from a mesh file, in the same file formats as mesh - assets. A mesh asset is not actually added to the model. Instead the vertex and face data from the mesh file are used - to populate the point and element data of the flexcomp. :at:`dim` is automatically set to 2. Recall that a mesh asset - in MuJoCo can be used as a rigid geom attached to a single body. In contrast, the flex generated here corresponds to - a soft mesh with the same initial shape, where each vertex is a separate moving body (unless pinned). + assets, excluding the legacy .msh format. A mesh asset is not actually added to the model. Instead the vertex and + face data from the mesh file are used to populate the point and element data of the flexcomp. :at:`dim` is + automatically set to 2. Recall that a mesh asset in MuJoCo can be used as a rigid geom attached to a single body. In + contrast, the flex generated here corresponds to a soft mesh with the same initial shape, where each vertex is a + separate moving body (unless pinned). .. _gmsh-file-docs: @@ -3638,9 +3450,10 @@ saving the XML: :at:`texcoord`: :at-val:`real(2*npoint), optional` Texture coordinates of each point, passed through to the automatically-generated flex. Note that flexcomp does not - generate texture coordinates automatically, except for 2D grids. For all other types, the user can specify explicit - texture coordinates here, even if the points themselves were generated automatically. This requires understanding of - the layout of the automatically-generated points and how they correspond to the texture referenced by the material. + generate texture coordinates automatically, except for 2D grids, box, cylinder and ellipsoid. For all other types, + the user can specify explicit texture coordinates here, even if the points themselves were generated automatically. + This requires understanding of the layout of the automatically-generated points and how they correspond to the + texture referenced by the material. .. _body-flexcomp-mass: @@ -3659,9 +3472,9 @@ saving the XML: :at:`file`: :at-val:`string, optional` The name of the file from which a **surface** (triangular) or **volumetric** (tetrahedral) mesh is loaded. For - surface meshes, the file extension is used to determine the file format. Supported formats are the same as in - :ref:`mesh assets` and also including GMSH. Volumetric meshes are supported only in GMSH format. - See :ref:`here` for more information on GMSH files. + surface meshes, the file extension is used to determine the file format. Supported formats are GMSH and the formats + specified in :ref:`mesh assets`, excluding the legacy .msh format. Volumetric meshes are supported only + in GMSH format. See :ref:`here` for more information on GMSH files. .. _body-flexcomp-rigid: @@ -3705,6 +3518,13 @@ saving the XML: These attributes are directly passed through to the automatically-generated :ref:`flex` object and have the same meaning. +.. _body-flexcomp-origin: + +:at:`origin`: :at-val:`real(3), "0 0 0"` + The origin of the flexcomp. Used for generating a volumetric mesh from an OBJ surface mesh. Each surface triangle is + connected to the origin to create a tetrahedron, so the resulting volumetric mesh is guaranteed to be well-formed + only for convex shapes. + .. _flexcomp-contact: :el-prefix:`flexcomp/` |-| **contact** (*) @@ -4097,9 +3917,14 @@ cases, the user will specify a :el:`flexcomp` which will then automatically cons .. _deformable-flex-texcoord: -:at:`texcoord`: :at-val:`real(2*nvert), optional` - Texture coordinates for each vertex. If omitted, texture mapping for this flex is disabled, even if a texture is - specified in the material. +:at:`texcoord`: :at-val:`real(2*vert or ntexcoord), optional` + Texture coordinates. If omitted, texture mapping for this flex is disabled, even if a texture is specified in the + material. + +.. _deformable-flex-elemtexcoord: + +:at:`elemtexcoord`: :at-val:`int((dim+1)*nelem), optional` + Texture indices for each face. If omitted, texture are assumed to be vertex-based. .. _deformable-flex-element: @@ -4109,7 +3934,7 @@ cases, the user will specify a :el:`flexcomp` which will then automatically cons which is why the number of indices equals (dim+1) times the number of elements. In 2D, the vertices should be listed in counter-clockwise order. In 1D and 3D the order is irrelevant; in 3D the model compiler will rearrange the vertices as needed. Repeated vertex indices within a flex element are not allowed. The topology of the flex is not - enforced; it could corespond to a continuous soft body, or a collection of disconnected stretchable elements, or + enforced; it could correspond to a continuous soft body, or a collection of disconnected stretchable elements, or anything in-between. .. _deformable-flex-flatskin: @@ -4138,6 +3963,12 @@ cases, the user will specify a :el:`flexcomp` which will then automatically cons Integer group to which the flex belongs. This attribute can be used for custom tags. It is also used by the visualizer to enable and disable the rendering of entire groups of flexes. +.. _deformable-flex-node: + +:at:`node`: :at-val:`string(nnode), optional` + The degrees-of-freedom of the flex. + An array of MuJoCo body names (separated by white space) to which each node belongs. The number of body names + should equal the number of nodes (nnode). See the flexcomp :ref:`dof` attribute for more details. .. _flex-edge: @@ -4197,7 +4028,7 @@ stress-strain relationship.. See also :ref:`deformable ` objects. :at:`thickness`: :at-val:`real(1), "-1"` Shell thickness, units of length; only for used 2D flexes. Used to scale the stretching stiffness. This thickness can be set equal to 2 times the :ref:`radius ` in order to match the geometry, - but is exposed seperately since the radius might be constrained by considerations related to collision detection. + but is exposed separately since the radius might be constrained by considerations related to collision detection. .. _flex-contact: @@ -4210,7 +4041,7 @@ extensions specific to flexes. .. _flex-contact-internal: -:at:`internal`: :at-val:`[true, false], "true"` +:at:`internal`: :at-val:`[true, false], "false"` Enables or disables internal collisions which prevent flex self-penetration and element inversion. Note that flex elements that have shared vertices cannot collide (or else there will be permanent contacts). In 1D and 2D, internal collision checks rely on predefined vertex-element pairs, where the vertex is treated as a sphere with the same @@ -4218,7 +4049,9 @@ extensions specific to flexes. flex. The pre-defined vertex-element pairs are generated by the model compiler automatically. In 3D, internal collision checks are performed within each tetraheron: each vertex is collided with the plane corresponding to the opposing triangle face (again using the flex radius). The resulting contacts are always created with condim 1, gap 0, - margin 0. + margin 0. Note that internal contacts modify the behavior implied by the :ref:`elasticity + parameters` and is recommended only for flexes where element inversion cannot be prevented. The + default value of this attribute was changed from "true" to "false" in version 3.3.1. .. _flex-contact-selfcollide: @@ -4438,7 +4271,7 @@ ball joint outside the kinematic tree. Connect constraints can be specified in o - Using :ref:`body1` and :ref:`anchor` (both required) and optionally :ref:`body2`. When using this specification, the constraint is assumed to be - satisfied in the configuration in which the model is defined. + satisfied at the configuration in which the model is defined (``mjData.qpos0``). - :ref:`site1` and :ref:`site2` (both required). When using this specification, the two sites will be pulled together by the constraint, regardless of their position in the default configuration. An example of this specification is shown in @@ -4484,8 +4317,8 @@ ball joint outside the kinematic tree. Connect constraints can be specified in o :at:`anchor`: :at-val:`real(3), optional` Coordinates of the 3D anchor point where the two bodies are connected, in the local coordinate frame of :at:`body1`. - The constraint is assumed to be satisfied in the configuration in which the model is defined, which lets the compiler - compute the associated anchor point for :at:`body2`. + The constraint is assumed to be satisfied in the configuration at which the model is defined (``mjData.qpos0``), + which lets the compiler compute the associated anchor point for :at:`body2`. .. _equality-connect-site1: @@ -4739,6 +4572,18 @@ A second form of wrapping is where the tendon is constrained to pass *through* a wrap around it. This is enabled automatically when a sidesite is specified and its position is inside the volume of the obstacle geom. +.. youtube:: I2q7D0Vda-A + :width: 300px + :align: right + +**Visualization:** Tendon paths are visualized as in the image above, respecting the :ref:`width`, +:ref:`material` and :ref:`rgba` attributes below. A special kind of +visualization is used for unactuated 2-point tendons with :ref:`range` or +:ref:`springlength` of the form :at-val:`[0 X]`, with positive X. Such tendons act like a +cable, applying force only when stretched. Therefore when not stretched, they are drawn as a catenary of +length X, as in the clip on the right of `this example model +`__. + .. _tendon-spatial-name: :at:`name`: :at-val:`string, optional` @@ -6255,13 +6100,12 @@ excluded; this is because sensor calculations are independent of the visualizer. :el-prefix:`sensor/` |-| **camprojection** (*) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This element creates a camprojection sensor, which returns the location of a target site, projected onto a camera image -in pixel coordinates. The origin of this system is located at the top-left corner of the first pixel, so a target -which projects exactly onto the corner of the image, will have value (0, 0). Values are not clipped, so targets which -fall outside the camera image will take values above or below the pixel limits. Moreover, points behind the camera -are also projected onto the image, so it is up to the user to filter out such points, if desired. This can be done using -a `framepos` sensor with the camera as reference frame, then a negative/positive value in the -z-coordinate indicates (respectively) a location in the front/back of the camera. +This element creates a camera projection sensor: the location of a target site, projected onto a camera image in pixel +coordinates. The pixel origin (0, 0) is located at the top-left corner. Values are not clipped, so targets which fall +outside the camera image will take values above or below the pixel range limits. Moreover, points behind the camera are +also projected onto the image, so it is up to the user to filter out such points, if desired. This can be done using a +:ref:`framepos` sensor with the camera as a reference frame: a negative/positive value in the +z-coordinate indicates a location in front of/behind the camera plane, respectively. .. _sensor-camprojection-site: @@ -6471,7 +6315,7 @@ contributed by all actuators to a single scalar joint (hinge or slider). If the :ref:`actuatorgravcomp` attribute is "true", this sensor will also measure contributions by gravity compensation forces (which are added directly to the joint and would *not* register in the :ref:`actuatorfrc`) sensor. This type of sensor is important when multiple actuators act on a single -joint or when a single actuator act on multiple joints. See :ref:`CForceRange` for details. +joint or when a single actuator acts on multiple joints. See :ref:`CForceRange` for details. .. _sensor-jointactuatorfrc-name: @@ -7139,16 +6983,11 @@ pipeline. These 3 sensors share some common properties: to geom-geom penetration) will be reported by :ref:`sensor/distance`. In order to determine collision properties of non-penetrating geom pairs, a positive :at:`cutoff` is required. - .. admonition:: Positive cutoff values + .. admonition:: different (correct) behavior under `nativeccd` :class: note - .. TODO: b/339596989 - Improve mjc_Convex. - - For some colliders, a positive :at:`cutoff` will result in an accurate measurement. However, for collision - pairs which use the general ``mjc_Convex`` collider, the result will be approximate and likely innacurate. - This is considered a bug to be fixed in a future release. - In order to determine whether a geom pair uses ``mjc_Convex``, inspect the table at the top of - `engine_collision_driver.c `__. + As explained in :ref:`Collision Detection`, distances are inaccurate when using the + :ref:`legacy CCD pipeline`, and its use is discouraged. :at:`geom1`, :at:`geom2`, :at:`body1`, :at:`body2` For all 3 collision sensor types, the two colliding geoms can be specified explicitly using the :at:`geom1` and @@ -7300,6 +7139,45 @@ See :ref:`collision-sensors` for more details about sensors of this type. :at:`name`, :at:`noise`, :at:`user` See :ref:`CSensor`. + +.. _sensor-e_potential: + +:el-prefix:`sensor/` |-| **e_potential** (*) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This element creates sensor that returns the potential energy. + +.. _sensor-e_potential-name: + +.. _sensor-e_potential-noise: + +.. _sensor-e_potential-cutoff: + +.. _sensor-e_potential-user: + +:at:`name`, :at:`noise`, :at:`cutoff`, :at:`user` + See :ref:`CSensor`. + + +.. _sensor-e_kinetic: + +:el-prefix:`sensor/` |-| **e_kinetic** (*) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This element creates sensor that returns the kinetic energy. + +.. _sensor-e_kinetic-name: + +.. _sensor-e_kinetic-noise: + +.. _sensor-e_kinetic-cutoff: + +.. _sensor-e_kinetic-user: + +:at:`name`, :at:`noise`, :at:`cutoff`, :at:`user` + See :ref:`CSensor`. + + .. _sensor-clock: :el-prefix:`sensor/` |-| **clock** (*) diff --git a/doc/XMLschema.rst b/doc/XMLschema.rst index 4b45b68b..0f71f6a3 100644 --- a/doc/XMLschema.rst +++ b/doc/XMLschema.rst @@ -52,9 +52,9 @@ | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | | | | | :ref:`fitaabb` | :ref:`eulerseq` | :ref:`meshdir` | :ref:`texturedir` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`discardvisual` | :ref:`convexhull` | :ref:`usethread` | :ref:`fusestatic` | | +| | | | :ref:`discardvisual` | :ref:`usethread` | :ref:`fusestatic` | :ref:`inertiafromgeom` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`inertiafromgeom` | :ref:`inertiagrouprange` | :ref:`assetdir` | :ref:`alignfree` | | +| | | | :ref:`inertiagrouprange` | :ref:`assetdir` | :ref:`alignfree` | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |_| compiler |br| |_| |L| | | .. table:: | @@ -178,66 +178,10 @@ | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`rgb | ? | :class: mjcf-attributes | -| ` | | | +| :ref:`layer | \* | :class: mjcf-attributes | +| ` | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`occlusion | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`roughness | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`metallic | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`normal | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`opacity | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`emissive | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`rgba | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`orm | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | +| | | | :ref:`texture` | :ref:`role` | | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |_| asset |br| |_| |L| | | .. table:: | @@ -396,9 +340,7 @@ | :ref:`composite | \* | :class: mjcf-attributes | | ` | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`prefix` | :ref:`type` | :ref:`count` | :ref:`spacing` | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`offset` | :ref:`flatinertia` | :ref:`solrefsmooth` | :ref:`solimpsmooth` | | +| | | | :ref:`prefix` | :ref:`type` | :ref:`count` | :ref:`offset` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | | | | | :ref:`vertex` | :ref:`initial` | :ref:`curve` | :ref:`size` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | @@ -419,21 +361,6 @@ | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |_2| composite |br| |_2| |L| | | .. table:: | -| :ref:`tendon | \* | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`kind` | :ref:`group` | :ref:`stiffness` | :ref:`damping` | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`solreffix` | :ref:`solimpfix` | :ref:`limited` | :ref:`range` | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`margin` | :ref:`solreflimit` | :ref:`solimplimit` | :ref:`frictionloss` | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`solreffriction` | :ref:`solimpfriction` | :ref:`material` | :ref:`rgba` | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`width` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| composite |br| |_2| |L| | | .. table:: | | :ref:`skin | ? | :class: mjcf-attributes | | ` | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | @@ -465,13 +392,6 @@ | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |_2| composite |br| |_2| |L| | | .. table:: | -| :ref:`pin | \* | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`coord` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| composite |br| |_2| |L| | | .. table:: | | :ref:`plugin | \* | :class: mjcf-attributes | | ` | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | @@ -491,15 +411,17 @@ | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | | | | | :ref:`name` | :ref:`type` | :ref:`group` | :ref:`dim` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`count` | :ref:`spacing` | :ref:`radius` | :ref:`rigid` | | +| | | | :ref:`dof` | :ref:`count` | :ref:`spacing` | :ref:`radius` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`mass` | :ref:`inertiabox` | :ref:`scale` | :ref:`file` | | +| | | | :ref:`rigid` | :ref:`mass` | :ref:`inertiabox` | :ref:`scale` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`point` | :ref:`element` | :ref:`texcoord` | :ref:`material` | | +| | | | :ref:`file` | :ref:`point` | :ref:`element` | :ref:`texcoord` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`rgba` | :ref:`flatskin` | :ref:`pos` | :ref:`quat` | | +| | | | :ref:`material` | :ref:`rgba` | :ref:`flatskin` | :ref:`pos` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`axisangle` | :ref:`xyaxes` | :ref:`zaxis` | :ref:`euler` | | +| | | | :ref:`quat` | :ref:`axisangle` | :ref:`xyaxes` | :ref:`zaxis` | | +| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +| | | | :ref:`euler` | :ref:`origin` | | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |_2| flexcomp |br| |_2| |L| | | .. table:: | @@ -563,7 +485,9 @@ | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | | | | | :ref:`material` | :ref:`rgba` | :ref:`flatskin` | :ref:`body` | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`vertex` | :ref:`element` | :ref:`texcoord` | | | +| | | | :ref:`vertex` | :ref:`element` | :ref:`texcoord` | :ref:`elemtexcoord` | | +| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +| | | | :ref:`node` | | | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |_2| flex |br| |_2| |L| | | .. table:: | @@ -1285,6 +1209,20 @@ | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |_| sensor |br| |_| |L| | | .. table:: | +| :ref:`e_potential | \* | :class: mjcf-attributes | +| ` | | | +| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +| | | | :ref:`name` | :ref:`cutoff` | :ref:`noise` | :ref:`user` | | +| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | ++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| |_| sensor |br| |_| |L| | | .. table:: | +| :ref:`e_kinetic | \* | :class: mjcf-attributes | +| ` | | | +| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +| | | | :ref:`name` | :ref:`cutoff` | :ref:`noise` | :ref:`user` | | +| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | ++------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| |_| sensor |br| |_| |L| | | .. table:: | | :ref:`clock | \* | :class: mjcf-attributes | | ` | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | diff --git a/doc/changelog.rst b/doc/changelog.rst index d3ec0db6..05d68306 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -5,19 +5,206 @@ Changelog Upcoming version (not yet released) ----------------------------------- -General -^^^^^^^ -- The global compiler flag ``exactmeshinertia`` has been removed and replaced with the mesh-specific - :ref:`inertia` attribute. +.. admonition:: Breaking API changes + :class: attention -MJX -^^^ -- Added ``apply_ft``, ``jac``, and ``xfrc_accumulate`` as public functions. -- Added ``TOUCH`` sensor. + - The default value of the flag for toggling :ref:`internal flex contacts` was changed from + "true" to "false". This feature has proven to be counterintuitive for users. Bug fixes ^^^^^^^^^ -- Fixed a bug in slider-crank ref:`transmission`. The bug was introduced in 3.0.0. +- :ref:`mj_jacDot` was missing a term that accounts for the motion of the point with respect to + which the Jacobian is computed, now fixed. +- Fixed a bug that caused the parent frame of elements in the child worldbody to be incorrectly set when attaching an + mjSpec to a frame or a site. + +Version 3.3.0 (Feb 26, 2025) +---------------------------- + + +Feature promotion +^^^^^^^^^^^^^^^^^ +.. youtube:: qJFbx-FR7Bc + :aspect: 16:7 + :align: right + :width: 240px + +1. Introduced a new kind of **fast deformable body**, activated by setting :ref:`flexcomp/dof` to + "trilinear". This type of :ref:`deformable` flex object has the same collision geometry as a regular + flex, but has far fewer degrees of freedom. Instead of 3 dofs per vertex, only the corners of the bounding box are + free to move, with the positions of the interior vertices computed with trilinear interpolation of the 8 corners, for + a total of 24 dofs for the entire flex object (or less, if some of the corners are pinned). This limits the types of + deformation achievable by the flex, but allows for much faster simulation. For example, see the video on the right + comparing `full `__ and `trilinear + `__ flexes for modeling + deformable gripper pads. + + +.. image:: images/computation/ccd_light.gif + :width: 20% + :align: right + :class: only-light + +.. image:: images/computation/ccd_dark.gif + :width: 20% + :align: right + :class: only-dark + +2. The native convex collision detection pipeline introduced in 3.2.3 and enabled by the + :ref:`nativeccd` flag, is now the default. See the section on + :ref:`Convex Collision Detection` for more details. + + **Migration:** If the new pipeline breaks your workflow, set :ref:`nativeccd` to "disable". + +General +^^^^^^^ +3. Add support for custom plots in the MuJoCo viewer by exposing a ``viewport`` property, a ``set_figures`` method, + and a ``clear_figures`` method. +4. Separate collision and deformation meshes for :ref:`flex`. This enables a fixed cost for the soft + body computations, while preserving the fidelity of high-resolution collisions. +5. Added :ref:`potential` and :ref:`kinetic` energy sensors. +6. Improved shadow rendering in the native renderer. +7. Moved ``introspect`` to ``python/introspect``. + +.. admonition:: Breaking API changes + :class: attention + + 8. As mentioned above, the native convex collision detection pipeline is now the default, which may break some + workflows. In this case, set :ref:`nativeccd` to "disable" to restore the old behavior. + 9. Added :ref:`mjs_setDeepCopy` API function. When the deep copy flag is 0, attaching a model will not copy it to the + parent, so the original references to the child can be used to modify the parent after attachment. The default + behavior is to perform such a shallow copy. The old behavior of creating a deep copy of the child model while + attaching can be restored by setting the deep copy flag to 1. + 10. Changes to inertia inference from meshes: + + Previously, in order to specify that the mass lies on the surface, :ref:`geom/shellinertia` + could be used for any geom type. Now this attribute is ignored if the geom is a mesh; instead, inertia inference + for meshes is specified in the asset, using the :ref:`asset/mesh/inertia` attribute. + + Previously, if the volumetric inertia computation failed (for example due to a very flat mesh), the compiler + would silently fall back to surface inertia computation. Now, the compiler will throw an informative error. + 11. Removed the composite type ``grid``. Users should instead use :ref:`flexcomp`. + 12. Removed the ``particle`` composite type. It is recommended to use the more generic :ref:`replicate` + instead, see for example `this model + `__. + +MJX +^^^ +13. Added support for spatial tendons with internal sphere and cylinder wrapping. +14. Fix a bug with box-box collisions :github:issue:`2356`. + +Python bindings +^^^^^^^^^^^^^^^ + +15. Added a pedagogical colab notebook for ``mujoco.rollout``, a Python module for multithreaded simulation rollouts. + It is available here |rollout_colab|. + |br| Contribution by :github:user:`aftersomemath`. + +.. |rollout_colab| image:: https://colab.research.google.com/assets/colab-badge.svg + :target: https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/rollout.ipynb + +Version 3.2.7 (Jan 14, 2025) +---------------------------- + +Python bindings +^^^^^^^^^^^^^^^ +1. :ref:`rollout` now features native multi-threading. If a sequence of ``MjData`` instances + of length ``nthread`` is passed in, ``rollout`` will automatically create a thread pool and parallelize + the computation. The thread pool can be reused across calls, but then the function cannot be called simultaneously + from multiple threads. To run multiple threaded rollouts simultaneously, use the new class ``Rollout`` which + encapsulates the thread pool. Contribution by :github:user:`aftersomemath`. +2. Fix global namespace pollution when using ``mjpython`` (:github:issue:`2265`). + +General +^^^^^^^ + +.. admonition:: Breaking API changes (minor) + :class: attention + + 3. The field ``mjData.qLDiagSqrtInv`` has been removed. This field is only required for the dual solvers. It is now + computed as-needed rather than unconditionally. Relatedly, added the corresponding argument to :ref:`mj_solveM2`. + +4. Reduced the memory footprint of the PGS solver's :ref:`A matrix`. This was the last remaining dense-memory + allocation in MuJoCo, allowing for a significant reduction of the :ref:`dynamic memory allocation heuristic`. + +Bug fixes +^^^^^^^^^ +5. Fixed a bug in the box-sphere collider, depth was incorrect for deep penetrations (:github:issue:`2206`). +6. Fixed a bug in :ref:`mj_mulM2` and added a test. + +Version 3.2.6 (Dec 2, 2024) +--------------------------- + +General +^^^^^^^ +1. Removed rope and loop from :ref:`composite`. The user is encouraged to instead use the :at:`cable` + plugin or :ref:`flexcomp`, respectively. + +MJX +^^^ +2. Added muscle actuators. + +Python bindings +^^^^^^^^^^^^^^^ +3. Provide prebuilt wheels for Python 3.13. +4. Added ``bind`` method and removed id attribute from :ref:`mjSpec` objects. Using ids is error prone in scenarios of + repeated attachment and detachment. Python users are encouraged to use names for unique identification of model + elements. +5. :ref:`rollout` can now accept sequences of MjModel of length ``nroll``. Also removed the ``nroll`` + argument because its value can always be inferred. + +Bug fixes +^^^^^^^^^ +6. Fixed :github:issue:`2212`, type error in ``mjx.get_data``. +7. Fixed bug introduced in 3.2.0 in handling of :ref:`texrepeat` attribute, was mistakenly + cast from ``float`` to ``int``, (fixed :github:issue:`2223`). + +Version 3.2.5 (Nov 4, 2024) +--------------------------- + +Feature promotion +^^^^^^^^^^^^^^^^^ +1. The :doc:`Model Editing` framework afforded by :ref:`mjSpec`, introduced in 3.2.0 as an + in-development feature, is now stable and recommended for general use. +2. The native convex collision detection pipeline introduced in 3.2.3 and enabled by the + :ref:`nativeccd` flag, is not yet the default but is already recommended for general use. + Please try it when encountering collision-related problems and report any issues you encounter. + +General +^^^^^^^ + +3. The global compiler flag ``exactmeshinertia`` has been removed and replaced with the mesh-specific + :ref:`inertia` attribute. +4. The not-useful ``convexhull`` compiler option (to disable computation of mesh convex hulls) has been removed. +5. Removed the deprecated ``mju_rotVecMat``, ``mju_rotVecMatT`` and ``mjv_makeConnector`` functions. +6. Sorting now uses a faster, native sort function (fixes :github:issue:`1638`). +7. The PBR texture layers introduced in 3.2.1 were refactored from separate sub-elements to a single + :ref:`layer` sub-element. +8. The composite types box, cylinder, and sphere have been removed. Users should instead use the equivalent types + available in :ref:`flexcomp`. + +MJX +^^^ +9. Added ``apply_ft``, ``jac``, and ``xfrc_accumulate`` as public functions. +10. Added ``TOUCH`` sensor. +11. Added support for ``eq_active``. Fixes :github:issue:`2173`. +12. Added ray intersection with ellipsoid. + +Bug fixes +^^^^^^^^^ +13. Fixed several bugs related to connect and weld constraints with site semantics (fixes :github:issue:`2179`, reported + by :github:user:`yinfanyi`). The introduction of site specification to connects and welds in 3.2.3 conditionally + changed the semantics of `mjData.eq_obj1id` and `mjData.eq_obj2id`, but these changes were not properly propagated + in several places leading to incorrect computations of constraint inertia, readings of affected force/torque sensors + and runtime enabling/disabling of such constraints. +14. Fixed a bug in slider-crank :ref:`transmission`. The bug was introduced in 3.0.0. +15. Fixed a bug in flex texture coordinates that prevented the correct allocation of textures in mjModel. + + +Documentation +^^^^^^^^^^^^^ +16. Function headers in the :doc:`API reference <../APIreference/APIfunctions>` now link to their source definitions + in GitHub. Version 3.2.4 (Oct 15, 2024) ---------------------------- @@ -26,13 +213,14 @@ General ^^^^^^^ .. youtube:: e8lUuykQPGs + :aspect: 16:7 :align: right :width: 240px 1. The Newton solver no longer requires ``nv*nv`` memory allocation, allowing for much larger models. See e.g., `100_humanoids.xml `__. - Two quadratic-memory allocations still remain to be fully sparsified: ``mjData.actuator_moment`` and the matrices used - by the PGS solver. + Two quadratic-memory allocations still remain to be fully sparsified: ``mjData.actuator_moment`` and the matrices + used by the PGS solver. 2. Removed the :at:`solid` and :at:`membrane` plugins and moved the associated computations into the engine. See `3D example model `__ and `2D example model `__ for examples of flex objects @@ -81,10 +269,11 @@ General 4. Added the :ref:`nativeccd` flag. When this flag is enabled, general convex collision detection is handled with a new native code path, rather than `libccd `__. - This feature is in early stages of testing, but users who've experienced issues related to collsion detection are + This feature is in early stages of testing, but users who've experienced issues related to collision detection are welcome to experiment with it and report any issues. .. youtube:: kcM_oauk3ZA + :aspect: 16:7 :align: right :width: 240px @@ -167,7 +356,7 @@ General 2. Added a new :ref:`autoreset` flag to disable automatic reset when NaNs or infinities are detected. 3. Added sub-elements to the MJCF :ref:`material` element, to allow specification of multiple textures - for rendering (e.g., :ref:`occlusion-roughness-metallic`). Note that the MuJoCo renderer doesn't + for rendering (e.g., ``occlusion, roughness, metallic``). Note that the MuJoCo renderer doesn't support these new features, and they are made available for use with external renderers. 4. Sorting (``mjQUICKSORT``) now calls ``std::sort`` when building with C++ (:github:issue:`1638`). @@ -214,12 +403,12 @@ General 3. Calls to :ref:`mj_defaultVFS` may allocate memory inside VFS, and the corresponding :ref:`mj_deleteVFS` must be called to deallocate any internal allocated memory. - 4. Deprecated :ref:`mju_rotVecMat` and :ref:`mju_rotVecMatT` in favor of :ref:`mju_mulMatVec3` and + 4. Deprecated ``mju_rotVecMat`` and ``mju_rotVecMatT`` in favor of :ref:`mju_mulMatVec3` and :ref:`mju_mulMatTVec3`. These function names and argument order are more consistent with the rest of the API. The older functions have been removed from the Python bindings and will be removed from the C API in the next release. 5. Removed the ``actuator_actdim`` callback from actuator plugins. They now have the ``actdim`` attribute, which - must be used with actuators that write state to the ``act`` array. This fixed a crash which happend when + must be used with actuators that write state to the ``act`` array. This fixed a crash which happened when keyframes were used in a model with stateful actuator plugins. The PID plugin will give an error when the wrong value of actdim is provided. @@ -229,6 +418,7 @@ General speed and memory footprint. .. youtube:: ZXBTEIDWHhs + :aspect: 16:7 :align: right :width: 240px @@ -317,6 +507,7 @@ General ^^^^^^^ .. youtube:: 5k0_wsIRAFc + :aspect: 16:7 :align: right :width: 240px @@ -421,6 +612,7 @@ Python bindings ^^^^^^^^^^^^^^^ .. youtube:: xHDS0n5DpqM + :aspect: 16:7 :align: right :width: 240px @@ -480,7 +672,7 @@ General 1. Improved the :ref:`discardvisual` compiler flag, which now discards all visual-only assets. See :ref:`discardvisual` for details. 2. Removed the :ref:`timer` for midphase colllision detection, it is now folded in with the narrowphase - timer. This is because timing the two phases seperately required fine-grained timers inside the collision + timer. This is because timing the two phases separately required fine-grained timers inside the collision functions; these functions are so small and fast that the timer itself was incurring a measurable cost. 3. Added the flag :ref:`bvactive` to ``visual/global``, allowing users to turn off visualisation of active bounding volumes (the red/green boxes in this :ref:`this changelog item`). For @@ -585,6 +777,7 @@ General ``qfrc_{spring, damper, gravcomp, fluid}``. The sum of these vectors equals ``qfrc_passive``. .. youtube:: H9qG9Zf2W44 + :aspect: 16:7 :align: right :width: 240px @@ -648,6 +841,7 @@ Documentation ^^^^^^^^^^^^^ .. youtube:: cE3s_IfO4g4 + :aspect: 16:7 :align: right :width: 240px @@ -679,6 +873,7 @@ New features :target: https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/mjx/tutorial.ipynb .. youtube:: QewlEqIZi1o + :aspect: 16:7 :align: right :width: 240px @@ -689,6 +884,7 @@ New features gradient at query points. See the :ref:`documentation` for more details. .. youtube:: ra2bTiZHGlw + :aspect: 16:7 :align: right :width: 240px @@ -709,6 +905,7 @@ New features this functionality to be unified in the future. .. youtube:: Vc1tq0fFvQA + :aspect: 16:7 :align: right :width: 240px @@ -837,6 +1034,7 @@ Simulate ^^^^^^^^ .. youtube:: YSvWn_poqWs + :aspect: 16:7 :align: right :width: 240px @@ -851,6 +1049,7 @@ Documentation ^^^^^^^^^^^^^ .. youtube:: nljr0X79vI0 + :aspect: 16:7 :align: right :width: 240px @@ -884,8 +1083,8 @@ General used to determine the type of the asset file without resorting to pulling the type from the file extension. #. Added analytic derivatives for quaternion :ref:`subtraction` and :ref:`integration` (rotation with an angular velocity). Derivatives are in the 3D tangent space. -#. Added :ref:`mjv_connector` which has identical functionality to :ref:`mjv_makeConnector`, but with more convenient - "from-to" argument parametrization. :ref:`mjv_makeConnector` is now deprecated. +#. Added :ref:`mjv_connector` which has identical functionality to ``mjv_makeConnector``, but with more convenient + "from-to" argument parametrization. ``mjv_makeConnector`` is now deprecated. #. Bumped oldest supported MacOS from version 10.12 to 11. MacOS 11 is the oldest version still maintained by Apple. Python bindings @@ -949,11 +1148,12 @@ Simulate ^^^^^^^^ .. youtube:: mXVPbppGk5I + :aspect: 16:7 :align: right :width: 240px 6. Added Visualization tab to simulate UI, corresponding to elements of the :ref:`visual` MJCF element. After - modifying values in the GUI, a saved XML will contain the new values. The modifyable members of + modifying values in the GUI, a saved XML will contain the new values. The modifiable members of :ref:`mjStatistic` (:ref:`extent`, :ref:`meansize` and :ref:`center`) are computed by the compiler and therefore do not have defaults. In order for these attributes to appear in the saved XML, a value must be specified in the loaded XML. @@ -1072,7 +1272,7 @@ Python bindings passive viewer now also requires an explicit call to ``sync`` on its handle to pick up any update to the physics state. This is to avoid race conditions that can result in visual artifacts. See :ref:`documentation` for details. -#. The ``viewer.launch_repl`` function has been removed since its functionality is superceded by ``launch_passive``. +#. The ``viewer.launch_repl`` function has been removed since its functionality is superseded by ``launch_passive``. #. Added a small number of missing struct fields discovered through the new ``introspect`` metadata. Bug fixes @@ -1322,6 +1522,7 @@ General See the :ref:`Memory allocation ` section for details. .. youtube:: RHnXD6uO3Mg + :aspect: 16:7 :align: right :height: 150px @@ -1409,6 +1610,7 @@ General ^^^^^^^ .. youtube:: BcHZ5BFeTmU + :aspect: 16:7 :align: right :height: 150px @@ -1425,6 +1627,7 @@ General different uses of new weld attributes. .. youtube:: s-0JHanqV1A + :aspect: 16:7 :align: right :height: 150px diff --git a/doc/computation/fluid.rst b/doc/computation/fluid.rst index a066a263..24c259c2 100644 --- a/doc/computation/fluid.rst +++ b/doc/computation/fluid.rst @@ -135,7 +135,7 @@ also disables the inertia-based model for the parent body. The Elements of the model are a generalization of :cite:t:`andersen2005b` to 3 dimensions. The force :math:`\mathbf{f}_{\text{ellipsoid}}` and torque :math:`\mathbf{g}_{\text{ellipsoid}}` exerted by the fluid onto the solid are -the sum of of the terms +the sum of the terms .. math:: \begin{align*} @@ -308,7 +308,7 @@ We present the following result. :math:`\mathcal{E}` with :math:`\Pi_{\mathbf{u}}` (denoted :math:`\mathcal{E}^{\cap}_{\mathbf{u}}`). An important property of :math:`\mathcal{E}^{\mathrm{proj}}_{\mathbf{u}}` is that :math:`\mathbf{u}` is tangent - tangent to the ellipsoid :math:`\mathcal{E}` at every point on :math:`\mathcal{E}^{\mathrm{proj}}_{\mathbf{u}}`. + to the ellipsoid :math:`\mathcal{E}` at every point on :math:`\mathcal{E}^{\mathrm{proj}}_{\mathbf{u}}`. We can regard :math:`\mathcal{E}` as the image of the unit sphere :math:`\mathcal{S}` under a stretching transformation :math:`T = \mathrm{diag}(r_x, r_y, r_z)`. Furthermore, if :math:`\mathbf{\tilde{u}}` is a vector diff --git a/doc/computation/index.rst b/doc/computation/index.rst index 048ac199..1021067a 100644 --- a/doc/computation/index.rst +++ b/doc/computation/index.rst @@ -241,7 +241,7 @@ The computation of the constraint force is the hard part and will be described l description of the general framework by summarizing how the above quantities up to the constraint Jacobian are computed. - The applied force :math:`\tau` includes :ref:`passive ` forces from spring-dampers and fluid dynamics, - :ref:`actuation ` forces, and additonal forces specified by the user. + :ref:`actuation ` forces, and additional forces specified by the user. - The bias force :math:`c` includes Coriolis, centrifugal and gravitational forces. Their sum is computed using the Recursive Newton-Euler (RNE) algorithm with acceleration set to 0. - The joint-space inertia matrix :math:`M` is computed using the Composite Rigid-Body (CRB) algorithm. This matrix is @@ -414,7 +414,7 @@ with MuJoCo's operation as long as such user forces depend only on position and MuJoCo can compute three types of passive forces: -- Spring-dampers in joints and tendons. See the following attribues for details. +- Spring-dampers in joints and tendons. See the following attributes for details. |br| **Joints:** :ref:`stiffness`, :ref:`springref`, :ref:`damping`, :ref:`springdamper`. @@ -484,24 +484,27 @@ acceleration as a function of velocity: :math:`a_t = a(v_t)`, the velocity updat This is a non-linear equation in the unknown vector :math:`v_{t+h}` and can be solved numerically at each time step using a first-order expansion of :math:`a(v_{t+h})` around :math:`v_t`. Recall that the forward dynamics are -.. math:: a(v) = M^{-1} \big(\tau(v) - c(v) + J^T f(v)\big) +.. math:: + :label: eq_forward + + a(v) = M^{-1} \big(\tau(v) - c(v) + J^T f(v)\big) Thus we define the derivative .. math:: - \begin{aligned} - {\partial a(v) \over \partial v} &= M^{-1} D \\ - D &\equiv {\partial \over \partial v} \Big(\tau(v) - c (v) + J^T f(v)\Big) - \end{aligned} + \begin{aligned} + {\partial a(v) \over \partial v} &= M^{-1} D \\ + D &\equiv {\partial \over \partial v} \Big(\tau(v) - c (v) + J^T f(v)\Big) + \end{aligned} The velocity update corresponding to Newton's method is as follows. First, we expand the right hand side to first order .. math:: - \begin{aligned} - v_{t+h} &= v_t + h a(v_{t+h}) \\ - &\approx v_t + h \big( a(v_t) + {\partial a(v) \over \partial v} \cdot (v_{t+h}-v_t) \big) \\ - &= v_t + h a(v_t) + h M^{-1} D \cdot (v_{t+h}-v_t) - \end{aligned} + \begin{aligned} + v_{t+h} &= v_t + h a(v_{t+h}) \\ + &\approx v_t + h \big( a(v_t) + {\partial a(v) \over \partial v} \cdot (v_{t+h}-v_t) \big) \\ + &= v_t + h a(v_t) + h M^{-1} D \cdot (v_{t+h}-v_t) + \end{aligned} Premultiplying by :math:`M` and rearranging yields @@ -512,16 +515,27 @@ Solving for :math:`v_{t+h}`, we obtain the implicit-in-velocity update .. math:: :label: eq_implicit_update - v_{t+h} = v_t + h (M-h D)^{-1} M a(v_t) + \begin{aligned} + v_{t+h} &= v_t + h \widehat{M}^{-1} M a(v_t) \\ + \widehat{M} &\equiv M-h D + \end{aligned} +.. _geIntegrators: + +Integrators +^^^^^^^^^^^ +MuJoCo supports four integrators: three single-step integrators and the multi-step 4th order Runge-Kutta integrator. All three single-step integrators in MuJoCo use the update :eq:`eq_implicit_update`, with different definitions of the :math:`D` matrix, which is always computed analytically. Semi-implicit with implicit joint damping (``Euler``) For this method, :math:`D` only includes derivatives of joint damping. Note that in this case :math:`D` is diagonal - and :math:`M-h D` is symmetric, so Cholesky decomposition can be used. If the model has no joint damping or the + and :math:`\widehat{M}` is symmetric, so :math:`L^TL` decomposition (a variant of Cholesky) can be used. This + factorization is stored ``mjData.qLD``. If the model has no joint damping or the :ref:`eulerdamp` disable-flag is set, implicit damping is disabled and the semi-implicit - update :eq:`eq_semimplicit` is used, rather than :eq:`eq_implicit_update`. + update :eq:`eq_semimplicit` is used, rather than :eq:`eq_implicit_update`, avoiding the additional factorization of + :math:`\widehat{M}` (*additional* because :math:`M` is already factorized for the acceleration update + :eq:`eq_forward`). Implicit-in-velocity (``implicit``) For this method, :math:`D` includes derivatives of all forces except the constraint forces :math:`J^T f(v)`. These @@ -530,8 +544,8 @@ Implicit-in-velocity (``implicit``) future version. Additionally, we restrict :math:`D` to have the same sparsity pattern as :math:`M`, for computational efficiency. This restriction will exclude damping in tendons which connect bodies that are on different branches of the kinematic tree. Since :math:`D` is not symmetric, we cannot use Cholesky factorization, but because :math:`D` and - :math:`M` have the same sparsity pattern corresponding to the topology of the kinematic tree, reverse-order LU - factorization of :math:`M-h D` is `guaranteed to have no fill-in + :math:`M` have the same sparsity pattern corresponding to the topology of the kinematic tree, reverse-order + :math:`LU` factorization of :math:`\widehat{M}` is guaranteed to have `no fill-in `_. This factorization is stored ``mjData.qLU``. Fast implicit-in-velocity (``implicitfast``) @@ -541,7 +555,7 @@ Fast implicit-in-velocity (``implicitfast``) Second, these forces change rapidly only at high rotational velocities of complex pendula and spinning bodies, scenarios which are not common and already well-handled by the Runge-Kutta integrator (see below). Because the RNE derivatives are also the main source of asymmetry of :math:`D`, by dropping them and symmetrizing, we can use the - faster Cholesky rather than LU decomposition. + faster :math:`L^TL` rather than :math:`LU` decomposition. 4th-order Runge-Kutta (``RK4``) One advantage of our continuous-time formulation is that we can use higher order integrators such as Runge-Kutta or @@ -576,8 +590,8 @@ Fast implicit-in-velocity (``implicitfast``) increased stability, and is therefore a strict improvement. It is the recommended integrator for most models. **implicit**: The benefit over ``implicitfast`` is the implicit integration of Coriolis and centripetal forces, including - gyroscopic forces. The most common case where integrating such forces implicitly leads to noticable improvement is - when free objects with assymetric inertia are spinning quickly. `gyroscopic.xml <../_static/gyroscopic.xml>`__ + gyroscopic forces. The most common case where integrating such forces implicitly leads to noticeable improvement is + when free objects with asymmetric inertia are spinning quickly. `gyroscopic.xml <../_static/gyroscopic.xml>`__ shows an ellipsoid rolling on an inclined plane which quickly diverges with ``implicitfast`` but is stable with ``implicit``. **RK4**: @@ -646,7 +660,7 @@ Control: ``ctrl`` generalized forces directly (stateless actuators), or affect the actuator activations in ``mjData.act``, which then produce forces. -Auxillary Controls: ``qfrc_applied`` and ``xfrc_applied`` +Auxiliary Controls: ``qfrc_applied`` and ``xfrc_applied`` | ``mjData.qfrc_applied`` are directly applied generalized forces. | ``mjData.xfrc_applied`` are Cartesian wrenches applied to the CoM of individual bodies. This field is used for example, by the :ref:`native viewer` to apply mouse perturbations. @@ -1525,27 +1539,106 @@ Filtering Checking ~~~~~~~~ +Detailed collision checking, also known as *near-phase* or narrow-phase_ collision detection, is performed by functions +that depend on the geom types in the pair. The table of narrow-phase collision functions can be inspected at the top of +`engine_collision_driver.c `__ +and exposed to users who wish to install their own colliders as :ref:`mjCOLLISIONFUNC`. MuJoCo supports several +primitive geometric shapes: plane, sphere, capsule, cylinder, ellipsoid, and box. It also supports triangulated meshes and +height-fields. -Detailed collision checking is performed by functions that depend on the geom types in the pair. MuJoCo supports several -primitive geometric shapes: plane, sphere, capsule, cylinder, ellipsoid, box. It also supports triangulated meshes and -height fields. +.. _narrow-phase: https://en.wikipedia.org/wiki/Collision_detection#Narrow_phase -We have chosen to limit collision detection to *convex* geoms. All primitive types are convex. Height fields are not -convex but internally they are treated as unions of triangular prisms (using custom collision pruning beyond the filters -described above). Meshes specified by the user can be non-convex, and are rendered as such. For collision purposes -however they are replaced with their convex hulls. Mesh collisions are based on the Minkowski Portal Refinement (MPR) -algorithm as implemented in `libccd `__. It has tolerance and maximum iteration -parameters exposed as ``mjModel.opt.ccd_tolerance`` and ``mjModel.opt.ccd_iterations`` respectively. MPR operates on the -convex hull implicitly, however pre-computing that hull can substantially improve performance for large meshes. The -model compiler does that by default, using the `qhull `__ library. +With the notable exception of :ref:`SDF plugins` (see documentation therein), collision detection is limited to +*convex* geoms. All primitive types are convex. Height-fields are not convex but internally they are treated as a +collection of triangular prisms (using custom collision pruning beyond the filters described above). Meshes specified by +the user can be non-convex, and are rendered as such. For collision purposes however they are replaced with their convex +hulls (visualized with the 'H' key in :ref:`simulate `), computed by the `qhull `__ +library. + +.. _coCCD: + +Convex collisions +^^^^^^^^^^^^^^^^^ +All collisions involving pairs of geoms that do not have an analytic collider (e.g., meshes), are handled by one of two +general-purpose convex collision detection (CCD) pipelines: + +native pipeline (default) + The native CCD pipeline ("nativeccd") is implemented natively in MuJoCo, based on the Gilbert-Johnson-Keerthi and + Expanding Polytope algorithms (GJK_ / EPA_). The native pipeline is both faster and more robust than the MPR-based + pipeline. + +libccd pipeline (legacy) + This legacy pipeline is based on the libccd_ library, and uses Minkowski Portal Refinement (MPR_). It is activated by + disabling the :ref:`nativeccd` flag. + +.. _libccd: https://github.com/danfis/libccd +.. _MPR: https://en.wikipedia.org/wiki/Minkowski_Portal_Refinement +.. _GJK: https://en.wikipedia.org/wiki/Gilbert%E2%80%93Johnson%E2%80%93Keerthi_distance_algorithm +.. _EPA: http://scroll.stanford.edu/courses/cs468-01-fall/Papers/van-den-bergen.pdf + +Both pipelines are controlled by a tolerance (in units of distance) and maximum iteration parameters exposed as +``mjOption.ccd_tolerance`` (:ref:`ccd_tolerance`) and ``mjOption.ccd_iterations`` +(:ref:`ccd_iterations`), respectively. + +.. _coMultiCCD: + +Multiple contacts +^^^^^^^^^^^^^^^^^ +Some colliders can return more than one contact per colliding pair to model line or surface contacts, as when two flat +objects touch. For example the capsule-plane and box-plane colliders can return up to two or four contacts, +respectively. Standard general-purpose convex collision algorithms like MPR and GJK always return a single contact +point, which is problematic for surface contact scenarios (e.g., box-stacking). Both of MuJoCo's CCD pipelines can +return multiple points per contacting pair ("multiccd"). This behavior is controlled by the +:ref:`multiccd` flag, but is implemented in different ways with different trade-offs: + +libccd pipeline (legacy) + Multiple contact points are found by rotating the two geoms by ±1e-3 radians around the tangential axes and + re-running the collision routine. If a new contact is detected it is added, allowing for up to 4 additional contact + points. This method is effective, but increases the cost of each collision call by a factor of 5. + +native pipeline + Native multiccd discovers multiple contacts using a novel analysis of the contacting surfaces at the solution, + avoiding full re-runs of the collision routine, and is thus effectively "free". Note that native multiccd currently + does not support positive contact margins. If one of the two geoms has a positive margin, native multiccd will fall + back to legacy algorithm. + +.. _coDistance: + +Geom distance +^^^^^^^^^^^^^ + +.. image:: ../images/computation/ccd_light.gif + :width: 25% + :align: right + :class: only-light + +.. image:: ../images/computation/ccd_dark.gif + :width: 25% + :align: right + :class: only-dark + +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. + +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. Open 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. +(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 + +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. .. _Pipeline: @@ -1597,14 +1690,14 @@ The stages below compute quantities that depend on the generalized positions ``m 3. Compute the body inertias and joint axes, in global frames centered at the centers of mass of the corresponding kinematic subtrees: :ref:`mj_comPos` 4. Compute quantities related to :ref:`flex` objects: :ref:`mj_flex` -5. Compute the actuator lengths and moment arms: :ref:`mj_tendon` +5. Compute the tendon lengths and moment arms. This includes the computation of minimal-length paths for spatial + tendons: :ref:`mj_tendon` 6. Compute the composite rigid body inertias and joint-space inertia matrix: :ref:`mj_crb` 7. Compute the sparse factorization of the joint-space inertia matrix: :ref:`mj_factorM` 8. Construct the list of active contacts. This includes both broad-phase and near-phase collision detection: :ref:`mj_collision` 9. Construct the constraint Jacobian and compute the constraint residuals: :ref:`mj_makeConstraint` -10. Compute the tendon lengths and moment arms. This includes the computation of minimal-length paths for spatial - tendons: :ref:`mj_transmission` +10. Compute the actuator lengths and moment arms: :ref:`mj_transmission` 11. Compute the matrices and vectors needed by the constraint solvers: :ref:`mj_projectConstraint` 12. Compute sensor data that only depends on position, and the potential energy if enabled: :ref:`mj_sensorPos`, :ref:`mj_energyPos` @@ -1722,7 +1815,7 @@ The top-level function :ref:`mj_inverse` invokes the following sequence of compu Derivatives ----------- -MuJoCo's entire computational pipline including its constraint solver are analytically differentiable in principle. +MuJoCo's entire computational pipeline including its constraint solver are analytically differentiable in principle. Writing efficient implementations of these derivatives is a long term goal of the development team. Analytic derivatives of the smooth dynamics (excluding constraints) with respect to velocity are already computed and enable the two :ref:`implicit integrators`. diff --git a/doc/conf.py b/doc/conf.py index e41542fa..cecc6c96 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -159,10 +159,14 @@ pygments_dark_style = 'monokai' html_static_path = [ '_static', 'css', + 'js', ] html_css_files = [ 'theme_overrides.css', ] +html_js_files = [ + 'linenumbers.js', +] favicons = [ { diff --git a/doc/css/theme_overrides.css b/doc/css/theme_overrides.css index e51e4eb0..00b8042d 100644 --- a/doc/css/theme_overrides.css +++ b/doc/css/theme_overrides.css @@ -72,7 +72,7 @@ h4 { /* Paragraph margins don't apply to table cell contents. */ .rst-content table.docutils td>p { - margin-top: 0px; + margin-top: 0; } /* Set padding of in-line highlighted text. */ @@ -200,8 +200,8 @@ table.docutils:not(.mjcf-attributes) > tbody > tr.row-odd { /* MJCF attributes table. */ table.mjcf-attributes { border-style: none; - margin-left: 0px; - margin-right: 0px; + margin-left: 0; + margin-right: 0; width: 100%; box-shadow: none; } @@ -209,7 +209,7 @@ table.mjcf-attributes { table.mjcf-attributes tbody tr td, table.mjcf-attributes tbody tr:nth-child(2n-1) td { border-style: none; - padding: 0px 0px 0px 0px; + padding: 0 0 0 0; width: 25%; } @@ -217,13 +217,13 @@ table.mjcf-attributes tbody tr td p { margin: 0; } -div.table-wrapper.mjcf-attributes { +.table-wrapper.mjcf-attributes { margin: 0.5em; padding: 0; } table td > div.wy-table-responsive { - margin-bottom: 0px; + margin-bottom: 0; } /* Remove vertical spacing before/after code blocks. */ diff --git a/doc/ext/header_reader.py b/doc/ext/header_reader.py index 42a93a14..e81f98a8 100644 --- a/doc/ext/header_reader.py +++ b/doc/ext/header_reader.py @@ -98,7 +98,7 @@ def read(lines: List[str]) -> Dict[str, ApiDefinition]: if section is not None: if 'MJAPI FUNCTIONS' in section: # Stripped functions do not begin with MJAPI, and must be under the - # predefiend section 'MJAPI FUNCTIONS'. This is because the docs don't + # predefined section 'MJAPI FUNCTIONS'. This is because the docs don't # include this prefix, and so we need to read such functions from the # reference header. stripped_functions = True diff --git a/doc/images/computation/ccd_dark.gif b/doc/images/computation/ccd_dark.gif new file mode 100644 index 00000000..61a47d49 Binary files /dev/null and b/doc/images/computation/ccd_dark.gif differ diff --git a/doc/images/computation/ccd_light.gif b/doc/images/computation/ccd_light.gif new file mode 100644 index 00000000..c12354be Binary files /dev/null and b/doc/images/computation/ccd_light.gif differ diff --git a/doc/images/python/rollout.png b/doc/images/python/rollout.png new file mode 100644 index 00000000..9901e687 Binary files /dev/null and b/doc/images/python/rollout.png differ diff --git a/doc/includes/references.h b/doc/includes/references.h index 9f348881..39eece88 100644 --- a/doc/includes/references.h +++ b/doc/includes/references.h @@ -169,7 +169,8 @@ struct mjData_ { int nf; // number of friction constraints int nl; // number of limit constraints int nefc; // number of constraints - int nnzJ; // number of non-zeros in constraint Jacobian + int nJ; // number of non-zeros in constraint Jacobian + int nA; // number of non-zeros in constraint inverse inertia matrix int nisland; // number of detected constraint islands // global properties @@ -263,8 +264,8 @@ struct mjData_ { mjtNum* actuator_length; // actuator lengths (nu x 1) int* moment_rownnz; // number of non-zeros in actuator_moment row (nu x 1) int* moment_rowadr; // row start address in colind array (nu x 1) - int* moment_colind; // column indices in sparse Jacobian (nu x nv) - mjtNum* actuator_moment; // actuator moments (nu x nv) + int* moment_colind; // column indices in sparse Jacobian (nJmom x 1) + mjtNum* actuator_moment; // actuator moments (nJmom x 1) // computed by mj_fwdPosition/mj_crb mjtNum* crb; // com-based composite inertia and mass (nbody x 10) @@ -273,7 +274,6 @@ struct mjData_ { // computed by mj_fwdPosition/mj_factorM mjtNum* qLD; // L'*D*L factorization of M (sparse) (nM x 1) mjtNum* qLDiagInv; // 1/diag(D) (nv x 1) - mjtNum* qLDiagSqrtInv; // 1/sqrt(diag(D)) (nv x 1) // computed by mj_collisionTree mjtNum* bvh_aabb_dyn; // global bounding box (center, size) (nbvhdynamic x 6) @@ -312,12 +312,17 @@ struct mjData_ { int* B_rownnz; // body-dof: non-zeros in each row (nbody x 1) int* B_rowadr; // body-dof: address of each row in B_colind (nbody x 1) int* B_colind; // body-dof: column indices of non-zeros (nB x 1) + int* M_rownnz; // inertia: non-zeros in each row (nv x 1) + int* M_rowadr; // inertia: address of each row in M_colind (nv x 1) + int* M_colind; // inertia: column indices of non-zeros (nM x 1) + int* mapM2M; // index mapping from M (legacy) to M (CSR) (nM x 1) int* C_rownnz; // reduced dof-dof: non-zeros in each row (nv x 1) int* C_rowadr; // reduced dof-dof: address of each row in C_colind (nv x 1) int* C_colind; // reduced dof-dof: column indices of non-zeros (nC x 1) int* mapM2C; // index mapping from M to C (nC x 1) int* D_rownnz; // dof-dof: non-zeros in each row (nv x 1) int* D_rowadr; // dof-dof: address of each row in D_colind (nv x 1) + int* D_diag; // dof-dof: index of diagonal element (nv x 1) int* D_colind; // dof-dof: column indices of non-zeros (nD x 1) int* mapM2D; // index mapping from M to D (nD x 1) int* mapD2M; // index mapping from D to M (nM x 1) @@ -361,13 +366,13 @@ struct mjData_ { int* efc_J_rownnz; // number of non-zeros in constraint Jacobian row (nefc x 1) int* efc_J_rowadr; // row start address in colind array (nefc x 1) int* efc_J_rowsuper; // number of subsequent rows in supernode (nefc x 1) - int* efc_J_colind; // column indices in constraint Jacobian (nnzJ x 1) + int* efc_J_colind; // column indices in constraint Jacobian (nJ x 1) int* efc_JT_rownnz; // number of non-zeros in constraint Jacobian row T (nv x 1) int* efc_JT_rowadr; // row start address in colind array T (nv x 1) int* efc_JT_rowsuper; // number of subsequent rows in supernode T (nv x 1) - int* efc_JT_colind; // column indices in constraint Jacobian T (nnzJ x 1) - mjtNum* efc_J; // constraint Jacobian (nnzJ x 1) - mjtNum* efc_JT; // constraint Jacobian transposed (nnzJ x 1) + int* efc_JT_colind; // column indices in constraint Jacobian T (nJ x 1) + mjtNum* efc_J; // constraint Jacobian (nJ x 1) + mjtNum* efc_JT; // constraint Jacobian transposed (nJ x 1) mjtNum* efc_pos; // constraint position (equality, contact) (nefc x 1) mjtNum* efc_margin; // inclusion margin (contact) (nefc x 1) mjtNum* efc_frictionloss; // frictionloss (friction) (nefc x 1) @@ -391,8 +396,8 @@ struct mjData_ { // computed by mj_projectConstraint (PGS solver) int* efc_AR_rownnz; // number of non-zeros in AR (nefc x 1) int* efc_AR_rowadr; // row start address in colind array (nefc x 1) - int* efc_AR_colind; // column indices in sparse AR (nefc x nefc) - mjtNum* efc_AR; // J*inv(M)*J' + R (nefc x nefc) + int* efc_AR_colind; // column indices in sparse AR (nA x 1) + mjtNum* efc_AR; // J*inv(M)*J' + R (nA x 1) //-------------------- arena-allocated: POSITION, VELOCITY dependent @@ -428,8 +433,9 @@ typedef enum mjtDisableBit_ { // disable default feature bitflags mjDSBL_MIDPHASE = 1<<13, // mid-phase collision filtering mjDSBL_EULERDAMP = 1<<14, // implicit integration of joint damping in Euler integrator mjDSBL_AUTORESET = 1<<15, // automatic reset when numerical issues are detected + mjDSBL_NATIVECCD = 1<<16, // native convex collision detection - mjNDISABLE = 16 // number of disable flags + mjNDISABLE = 17 // number of disable flags } mjtDisableBit; typedef enum mjtEnableBit_ { // enable optional feature bitflags mjENBL_OVERRIDE = 1<<0, // override contact parameters @@ -439,9 +445,8 @@ typedef enum mjtEnableBit_ { // enable optional feature bitflags // experimental features: mjENBL_MULTICCD = 1<<4, // multi-point convex collision detection mjENBL_ISLAND = 1<<5, // constraint island discovery - mjENBL_NATIVECCD = 1<<6, // native convex collision detection - mjNENABLE = 7 // number of enable flags + mjNENABLE = 6 // number of enable flags } mjtEnableBit; typedef enum mjtJoint_ { // type of degree of freedom mjJNT_FREE = 0, // global position and orientation (quat) (7) @@ -598,7 +603,9 @@ typedef enum mjtObj_ { // type of MujoCo object mjNOBJECT, // number of object types // meta elements, do not appear in mjModel - mjOBJ_FRAME = 100 // frame + mjOBJ_FRAME = 100, // frame + mjOBJ_DEFAULT // default + } mjtObj; typedef enum mjtConstraint_ { // type of constraint mjCNSTR_EQUALITY = 0, // equality constraint @@ -673,6 +680,8 @@ typedef enum mjtSensor_ { // type of sensor mjSENS_GEOMFROMTO, // segment between two geoms // global sensors + mjSENS_E_POTENTIAL, // potential energy + mjSENS_E_KINETIC, // kinetic energy mjSENS_CLOCK, // simulation time // plugin-controlled sensors @@ -898,6 +907,7 @@ struct mjModel_ { int ncam; // number of cameras int nlight; // number of lights int nflex; // number of flexes + int nflexnode; // number of dofs in all flexes int nflexvert; // number of vertices in all flexes int nflexedge; // number of edges in all flexes int nflexelem; // number of elements in all flexes @@ -912,6 +922,9 @@ struct mjModel_ { int nmeshtexcoord; // number of texcoords in all meshes int nmeshface; // number of triangular faces in all meshes int nmeshgraph; // number of ints in mesh auxiliary data + int nmeshpoly; // number of polygons in all meshes + int nmeshpolyvert; // number of vertices in all polygons + int nmeshpolymap; // number of polygons in vertex map int nskin; // number of skins int nskinvert; // number of vertices in all skins int nskintexvert; // number of vertiex with texcoords in all skins @@ -948,19 +961,20 @@ struct mjModel_ { int nuser_actuator; // number of mjtNums in actuator_user int nuser_sensor; // number of mjtNums in sensor_user int nnames; // number of chars in all names - int nnames_map; // number of slots in the names hash map int npaths; // number of chars in all paths - // sizes set after mjModel construction (only affect mjData) + // sizes set after mjModel construction + int nnames_map; // number of slots in the names hash map int nM; // number of non-zeros in sparse inertia matrix int nB; // number of non-zeros in sparse body-dof matrix int nC; // number of non-zeros in sparse reduced dof-dof matrix int nD; // number of non-zeros in sparse dof-dof matrix + int nJmom; // number of non-zeros in sparse actuator_moment matrix int ntree; // number of kinematic trees under world body int ngravcomp; // number of bodies with nonzero gravcomp int nemax; // number of potential equality-constraint rows - int njmax; // number of available rows in constraint Jacobian - int nconmax; // number of potential contacts in contact list + int njmax; // number of available rows in constraint Jacobian (legacy) + int nconmax; // number of potential contacts in contact list (legacy) int nuserdata; // number of mjtNums reserved for the user int nsensordata; // number of mjtNums in sensor data vector int npluginstate; // number of mjtNums in plugin state vector @@ -1149,6 +1163,9 @@ struct mjModel_ { int* flex_dim; // 1: lines, 2: triangles, 3: tetrahedra (nflex x 1) int* flex_matid; // material id for rendering (nflex x 1) int* flex_group; // group for visibility (nflex x 1) + int* flex_interp; // interpolation (0: vertex, 1: nodes) (nflex x 1) + int* flex_nodeadr; // first node address (nflex x 1) + int* flex_nodenum; // number of nodes (nflex x 1) int* flex_vertadr; // first vertex address (nflex x 1) int* flex_vertnum; // number of vertices (nflex x 1) int* flex_edgeadr; // first edge address (nflex x 1) @@ -1162,15 +1179,19 @@ struct mjModel_ { int* flex_evpairadr; // first evpair address (nflex x 1) int* flex_evpairnum; // number of evpairs (nflex x 1) int* flex_texcoordadr; // address in flex_texcoord; -1: none (nflex x 1) + int* flex_nodebodyid; // node body ids (nflexnode x 1) int* flex_vertbodyid; // vertex body ids (nflexvert x 1) int* flex_edge; // edge vertex ids (2 per edge) (nflexedge x 2) int* flex_elem; // element vertex ids (dim+1 per elem) (nflexelemdata x 1) + int* flex_elemtexcoord; // element texture coordinates (dim+1) (nflexelemdata x 1) int* flex_elemedge; // element edge ids (nflexelemedge x 1) int* flex_elemlayer; // element distance from surface, 3D only (nflexelem x 1) int* flex_shell; // shell fragment vertex ids (dim per frag) (nflexshelldata x 1) int* flex_evpair; // (element, vertex) collision pairs (nflexevpair x 2) mjtNum* flex_vert; // vertex positions in local body frames (nflexvert x 3) - mjtNum* flex_xvert0; // Cartesian vertex positions in qpos0 (nflexvert x 3) + mjtNum* flex_vert0; // vertex positions in qpos0 on [0, 1]^d (nflexvert x 3) + mjtNum* flex_node; // node positions in local body frames (nflexnode x 3) + mjtNum* flex_node0; // Cartesian node positions in qpos0 (nflexnode x 3) mjtNum* flexedge_length0; // edge lengths in qpos0 (nflexedge x 1) mjtNum* flexedge_invweight0; // edge inv. weight in qpos0 (nflexedge x 1) mjtNum* flex_radius; // radius around primitive element (nflex x 1) @@ -1211,6 +1232,15 @@ struct mjModel_ { mjtNum* mesh_pos; // translation applied to asset vertices (nmesh x 3) mjtNum* mesh_quat; // rotation applied to asset vertices (nmesh x 4) int* mesh_pathadr; // address of asset path for mesh; -1: none (nmesh x 1) + int* mesh_polynum; // number of polygons per mesh (nmesh x 1) + int* mesh_polyadr; // first polygon address per mesh (nmesh x 1) + mjtNum* mesh_polynormal; // all polygon normals (nmeshpoly x 3) + int* mesh_polyvertadr; // polygon vertex start address (nmeshpoly x 1) + int* mesh_polyvertnum; // number of vertices per polygon (nmeshpoly x 1) + int* mesh_polyvert; // all polygon vertices (nmeshpolyvert x 1) + int* mesh_polymapadr; // first polygon address per vertex (nmeshvert x 1) + int* mesh_polymapnum; // number of polygons per vertex (nmeshvert x 1) + int* mesh_polymap; // vertex to polygon map (nmeshpolymap x 1) // skins int* skin_matid; // skin material id; -1: none (nskin x 1) @@ -1582,14 +1612,14 @@ struct mjrContext_ { // custom OpenGL context unsigned int auxColor_r[mjNAUX]; // auxiliary color buffer for resolving // materials with textures - int mat_texid[mjMAXMATERIAL*mjNTEXROLE]; // material texture ids (-1: no texture) - int mat_texuniform[mjMAXMATERIAL]; // texture repetition for 2d mapping - int mat_texrepeat[mjMAXMATERIAL*2]; // texture repetition for 2d mapping + int mat_texid[mjMAXMATERIAL*mjNTEXROLE]; // material texture ids (-1: no texture) + int mat_texuniform[mjMAXMATERIAL]; // uniform cube mapping + float mat_texrepeat[mjMAXMATERIAL*2]; // texture repetition for 2d mapping // texture objects and info - int ntexture; // number of allocated textures - int textureType[mjMAXTEXTURE]; // type of texture (mjtTexture) (ntexture) - unsigned int texture[mjMAXTEXTURE]; // texture names + int ntexture; // number of allocated textures + int textureType[mjMAXTEXTURE]; // type of texture (mjtTexture) (ntexture) + unsigned int texture[mjMAXTEXTURE]; // texture names // displaylist starting positions unsigned int basePlane; // all planes from model @@ -1628,23 +1658,24 @@ struct mjrContext_ { // custom OpenGL context int windowDoublebuffer; // is default/window framebuffer double buffered // framebuffer - int currentBuffer; // currently active framebuffer: mjFB_WINDOW or mjFB_OFFSCREEN + int currentBuffer; // currently active framebuffer: mjFB_WINDOW or mjFB_OFFSCREEN // pixel output format - int readPixelFormat; // default color pixel format for mjr_readPixels + int readPixelFormat; // default color pixel format for mjr_readPixels // depth output format - int readDepthMap; // depth mapping: mjDEPTH_ZERONEAR or mjDEPTH_ZEROFAR + int readDepthMap; // depth mapping: mjDEPTH_ZERONEAR or mjDEPTH_ZEROFAR }; typedef struct mjrContext_ mjrContext; typedef enum mjtGeomInertia_ { // type of inertia inference mjINERTIA_VOLUME = 0, // mass distributed in the volume mjINERTIA_SHELL, // mass distributed on the surface } mjtGeomInertia; -typedef enum mjtMeshInertia_ { // type of mesh inertia - mjINERTIA_CONVEX = 0, // convex mesh inertia - mjINERTIA_EXACT, // exact mesh inertia - mjINERTIA_LEGACY, // legacy mesh inertia +typedef enum mjtMeshInertia_ { // type of mesh inertia + mjMESH_INERTIA_CONVEX = 0, // convex mesh inertia + mjMESH_INERTIA_EXACT, // exact mesh inertia + mjMESH_INERTIA_LEGACY, // legacy mesh inertia + mjMESH_INERTIA_SHELL // shell mesh inertia } mjtMeshInertia; typedef enum mjtBuiltin_ { // type of built-in procedural texture mjBUILTIN_NONE = 0, // no built-in texture @@ -1683,30 +1714,32 @@ typedef enum mjtOrientation_ { // type of orientation specifier typedef struct mjsElement_ { // element type, do not modify mjtObj elemtype; // element type } mjsElement; -typedef struct mjSpec_ { // model specification - mjsElement* element; // element type - mjString* modelname; // model name - - // compiler settings +typedef struct mjsCompiler_ { // compiler options mjtByte autolimits; // infer "limited" attribute based on range double boundmass; // enforce minimum body mass double boundinertia; // enforce minimum body diagonal inertia double settotalmass; // rescale masses and inertias; <=0: ignore mjtByte balanceinertia; // automatically impose A + B >= C rule - mjtByte strippath; // automatically strip paths from mesh files mjtByte fitaabb; // meshfit to aabb instead of inertia box mjtByte degree; // angles in radians or degrees char eulerseq[3]; // sequence for euler rotations - mjString* meshdir; // mesh and hfield directory - mjString* texturedir; // texture directory mjtByte discardvisual; // discard visual geoms in parser - mjtByte convexhull; // compute mesh convex hulls mjtByte usethread; // use multiple threads to speed up compiler mjtByte fusestatic; // fuse static bodies with parent int inertiafromgeom; // use geom inertias (mjtInertiaFromGeom) int inertiagrouprange[2]; // range of geom groups used to compute inertia int alignfree; // align free joints with inertial frame mjLROpt LRopt; // options for lengthrange computation +} mjsCompiler; +typedef struct mjSpec_ { // model specification + mjsElement* element; // element type + mjString* modelname; // model name + + // compiler data + mjsCompiler compiler; // compiler options + mjtByte strippath; // automatically strip paths from mesh files + mjString* meshdir; // mesh and hfield directory + mjString* texturedir; // texture directory // engine data mjOption option; // physics options @@ -1977,10 +2010,13 @@ typedef struct mjsFlex_ { // flex specification double thickness; // thickness (2D only) // mesh properties + mjStringVec* nodebody; // node body names mjStringVec* vertbody; // vertex body names + mjDoubleVec* node; // node positions mjDoubleVec* vert; // vertex positions mjIntVec* elem; // element vertex ids mjFloatVec* texcoord; // vertex texture coordinates + mjIntVec* elemtexcoord; // element texture coordinates // other mjString* info; // message appended to compiler errors @@ -1993,14 +2029,13 @@ typedef struct mjsMesh_ { // mesh specification double refpos[3]; // reference position double refquat[4]; // reference orientation double scale[3]; // rescale mesh - mjtMeshInertia inertia; // inertia type (convex, legacy, exact) + mjtMeshInertia inertia; // inertia type (convex, legacy, exact, shell) mjtByte smoothnormal; // do not exclude large-angle faces from normals int maxhullvert; // maximum vertex count for the convex hull mjFloatVec* uservert; // user vertex data mjFloatVec* usernormal; // user normal data mjFloatVec* usertexcoord; // user texcoord data mjIntVec* userface; // user vertex indices - mjIntVec* userfacenormal; // user normal indices mjIntVec* userfacetexcoord; // user texcoord indices mjsPlugin plugin; // sdf plugin mjString* info; // message appended to compiler errors @@ -2496,7 +2531,7 @@ struct mjUI_ { // entire UI // UI sizes (framebuffer units) int width; // width - int height; // current heigth + int height; // current height int maxheight; // height when all sections open int scroll; // scroll from top of UI @@ -2963,9 +2998,14 @@ struct mjvSceneState_ { int* flex_dim; int* flex_matid; int* flex_group; + int* flex_interp; + int* flex_nodeadr; + int* flex_nodenum; + int* flex_nodebodyid; int* flex_vertadr; int* flex_vertnum; int* flex_elem; + int* flex_elemtexcoord; int* flex_elemlayer; int* flex_elemadr; int* flex_elemnum; @@ -2976,8 +3016,11 @@ struct mjvSceneState_ { int* flex_texcoordadr; int* flex_bvhadr; int* flex_bvhnum; + mjtByte* flex_centered; + mjtNum* flex_node; mjtNum* flex_radius; float* flex_rgba; + float* flex_texcoord; int* hfield_pathadr; @@ -3178,11 +3221,12 @@ mjSpec* mj_makeSpec(void); mjSpec* mj_copySpec(const mjSpec* s); void mj_deleteSpec(mjSpec* s); int mjs_activatePlugin(mjSpec* s, const char* name); +int mjs_setDeepCopy(mjSpec* s, int deepcopy); void mj_printFormattedModel(const mjModel* m, const char* filename, const char* float_format); void mj_printModel(const mjModel* m, const char* filename); -void mj_printFormattedData(const mjModel* m, mjData* d, const char* filename, +void mj_printFormattedData(const mjModel* m, const mjData* d, const char* filename, const char* float_format); -void mj_printData(const mjModel* m, mjData* d, const char* filename); +void mj_printData(const mjModel* m, const mjData* d, const char* filename); void mju_printMat(const mjtNum* mat, int nr, int nc); void mju_printMatSparse(const mjtNum* mat, int nr, const int* rownnz, const int* rowadr, const int* colind); @@ -3217,7 +3261,8 @@ void mj_transmission(const mjModel* m, mjData* d); void mj_crb(const mjModel* m, mjData* d); void mj_factorM(const mjModel* m, mjData* d); void mj_solveM(const mjModel* m, mjData* d, mjtNum* x, const mjtNum* y, int n); -void mj_solveM2(const mjModel* m, mjData* d, mjtNum* x, const mjtNum* y, int n); +void mj_solveM2(const mjModel* m, mjData* d, mjtNum* x, const mjtNum* y, + const mjtNum* sqrtInvD, int n); void mj_comVel(const mjModel* m, mjData* d); void mj_passive(const mjModel* m, mjData* d); void mj_subtreeVel(const mjModel* m, mjData* d); @@ -3335,9 +3380,6 @@ void mjv_defaultOption(mjvOption* opt); void mjv_defaultFigure(mjvFigure* fig); void mjv_initGeom(mjvGeom* geom, int type, const mjtNum size[3], const mjtNum pos[3], const mjtNum mat[9], const float rgba[4]); -void mjv_makeConnector(mjvGeom* geom, int type, mjtNum width, - mjtNum a0, mjtNum a1, mjtNum a2, - mjtNum b0, mjtNum b1, mjtNum b2); void mjv_connector(mjvGeom* geom, int type, mjtNum width, const mjtNum from[3], const mjtNum to[3]); void mjv_defaultScene(mjvScene* scn); @@ -3348,6 +3390,7 @@ void mjv_updateScene(const mjModel* m, mjData* d, const mjvOption* opt, int mjv_updateSceneFromState(const mjvSceneState* scnstate, const mjvOption* opt, const mjvPerturb* pert, mjvCamera* cam, int catmask, mjvScene* scn); +void mjv_copyModel(mjModel* dest, const mjModel* src); void mjv_defaultSceneState(mjvSceneState* scnstate); void mjv_makeSceneState(const mjModel* m, const mjData* d, mjvSceneState* scnstate, int maxgeom); @@ -3429,8 +3472,6 @@ mjtNum mju_dot3(const mjtNum vec1[3], const mjtNum vec2[3]); mjtNum mju_dist3(const mjtNum pos1[3], const mjtNum pos2[3]); void mju_mulMatVec3(mjtNum res[3], const mjtNum mat[9], const mjtNum vec[3]); void mju_mulMatTVec3(mjtNum res[3], const mjtNum mat[9], const mjtNum vec[3]); -void mju_rotVecMat(mjtNum res[3], const mjtNum vec[3], const mjtNum mat[9]); -void mju_rotVecMatT(mjtNum res[3], const mjtNum vec[3], const mjtNum mat[9]); void mju_cross(mjtNum res[3], const mjtNum a[3], const mjtNum b[3]); void mju_zero4(mjtNum res[4]); void mju_unit4(mjtNum res[4]); @@ -3467,6 +3508,8 @@ void mju_sqrMatTD(mjtNum* res, const mjtNum* mat, const mjtNum* diag, int nr, in void mju_transformSpatial(mjtNum res[6], const mjtNum vec[6], int flg_force, const mjtNum newpos[3], const mjtNum oldpos[3], const mjtNum rotnew2old[9]); +int mju_dense2sparse(mjtNum* res, const mjtNum* mat, int nr, int nc, + int* rownnz, int* rowadr, int* colind, int nnz); void mju_sparse2dense(mjtNum* res, const mjtNum* mat, int nr, int nc, const int* rownnz, const int* rowadr, const int* colind); void mju_rotVecQuat(mjtNum res[3], const mjtNum vec[3], const mjtNum quat[4]); @@ -3481,6 +3524,7 @@ void mju_mat2Quat(mjtNum quat[4], const mjtNum mat[9]); void mju_derivQuat(mjtNum res[4], const mjtNum quat[4], const mjtNum vel[3]); void mju_quatIntegrate(mjtNum quat[4], const mjtNum vel[3], mjtNum scale); void mju_quatZ2Vec(mjtNum quat[4], const mjtNum vec[3]); +int mju_mat2Rot(mjtNum quat[4], const mjtNum mat[9]); void mju_euler2Quat(mjtNum quat[4], const mjtNum euler[3], const char* seq); void mju_mulPose(mjtNum posres[3], mjtNum quatres[4], const mjtNum pos1[3], const mjtNum quat1[4], @@ -3567,23 +3611,26 @@ mjsFrame* mjs_attachFrame(mjsBody* parent, const mjsFrame* child, const char* prefix, const char* suffix); mjsBody* mjs_attachToSite(mjsSite* parent, const mjsBody* child, const char* prefix, const char* suffix); +mjsFrame* mjs_attachFrameToSite(mjsSite* parent, const mjsFrame* child, + const char* prefix, const char* suffix); int mjs_detachBody(mjSpec* s, mjsBody* b); -mjsBody* mjs_addBody(mjsBody* body, mjsDefault* def); -mjsSite* mjs_addSite(mjsBody* body, mjsDefault* def); -mjsJoint* mjs_addJoint(mjsBody* body, mjsDefault* def); +int mjs_detachDefault(mjSpec* s, mjsDefault* d); +mjsBody* mjs_addBody(mjsBody* body, const mjsDefault* def); +mjsSite* mjs_addSite(mjsBody* body, const mjsDefault* def); +mjsJoint* mjs_addJoint(mjsBody* body, const mjsDefault* def); mjsJoint* mjs_addFreeJoint(mjsBody* body); -mjsGeom* mjs_addGeom(mjsBody* body, mjsDefault* def); -mjsCamera* mjs_addCamera(mjsBody* body, mjsDefault* def); -mjsLight* mjs_addLight(mjsBody* body, mjsDefault* def); +mjsGeom* mjs_addGeom(mjsBody* body, const mjsDefault* def); +mjsCamera* mjs_addCamera(mjsBody* body, const mjsDefault* def); +mjsLight* mjs_addLight(mjsBody* body, const mjsDefault* def); mjsFrame* mjs_addFrame(mjsBody* body, mjsFrame* parentframe); -void mjs_delete(mjsElement* element); -mjsActuator* mjs_addActuator(mjSpec* s, mjsDefault* def); +int mjs_delete(mjsElement* element); +mjsActuator* mjs_addActuator(mjSpec* s, const mjsDefault* def); mjsSensor* mjs_addSensor(mjSpec* s); mjsFlex* mjs_addFlex(mjSpec* s); -mjsPair* mjs_addPair(mjSpec* s, mjsDefault* def); +mjsPair* mjs_addPair(mjSpec* s, const mjsDefault* def); mjsExclude* mjs_addExclude(mjSpec* s); -mjsEquality* mjs_addEquality(mjSpec* s, mjsDefault* def); -mjsTendon* mjs_addTendon(mjSpec* s, mjsDefault* def); +mjsEquality* mjs_addEquality(mjSpec* s, const mjsDefault* def); +mjsTendon* mjs_addTendon(mjSpec* s, const mjsDefault* def); mjsWrap* mjs_wrapSite(mjsTendon* tendon, const char* name); mjsWrap* mjs_wrapGeom(mjsTendon* tendon, const char* name, const char* sidesite); mjsWrap* mjs_wrapJoint(mjsTendon* tendon, const char* name, double coef); @@ -3594,16 +3641,18 @@ mjsTuple* mjs_addTuple(mjSpec* s); mjsKey* mjs_addKey(mjSpec* s); mjsPlugin* mjs_addPlugin(mjSpec* s); mjsDefault* mjs_addDefault(mjSpec* s, const char* classname, const mjsDefault* parent); -mjsMesh* mjs_addMesh(mjSpec* s, mjsDefault* def); +mjsMesh* mjs_addMesh(mjSpec* s, const mjsDefault* def); mjsHField* mjs_addHField(mjSpec* s); mjsSkin* mjs_addSkin(mjSpec* s); mjsTexture* mjs_addTexture(mjSpec* s); -mjsMaterial* mjs_addMaterial(mjSpec* s, mjsDefault* def); +mjsMaterial* mjs_addMaterial(mjSpec* s, const mjsDefault* def); mjSpec* mjs_getSpec(mjsElement* element); mjSpec* mjs_findSpec(mjSpec* spec, const char* name); mjsBody* mjs_findBody(mjSpec* s, const char* name); mjsElement* mjs_findElement(mjSpec* s, mjtObj type, const char* name); mjsBody* mjs_findChild(mjsBody* body, const char* name); +mjsBody* mjs_getParent(mjsElement* element); +mjsFrame* mjs_getFrame(mjsElement* element); mjsFrame* mjs_findFrame(mjSpec* s, const char* name); mjsDefault* mjs_getDefault(mjsElement* element); mjsDefault* mjs_findDefault(mjSpec* s, const char* classname); @@ -3626,11 +3675,14 @@ void mjs_setDouble(mjDoubleVec* dest, const double* array, int size); void mjs_setPluginAttributes(mjsPlugin* plugin, void* attributes); const char* mjs_getString(const mjString* source); const double* mjs_getDouble(const mjDoubleVec* source, int* size); -void mjs_setDefault(mjsElement* element, mjsDefault* def); +void mjs_setDefault(mjsElement* element, const mjsDefault* def); void mjs_setFrame(mjsElement* dest, mjsFrame* frame); const char* mjs_resolveOrientation(double quat[4], mjtByte degree, const char* sequence, const mjsOrientation* orientation); mjsFrame* mjs_bodyToFrame(mjsBody** body); +void mjs_setUserValue(mjsElement* element, const char* key, const void* data); +const void* mjs_getUserValue(mjsElement* element, const char* key); +void mjs_deleteUserValue(mjsElement* element, const char* key); void mjs_defaultSpec(mjSpec* spec); void mjs_defaultOrientation(mjsOrientation* orient); void mjs_defaultBody(mjsBody* body); diff --git a/doc/js/linenumbers.js b/doc/js/linenumbers.js new file mode 100644 index 00000000..818728e1 --- /dev/null +++ b/doc/js/linenumbers.js @@ -0,0 +1,128 @@ +const SRCS = [ + 'xml/xml_api.cc', + 'user/user_api.cc', + 'user/user_init.c', + 'user/user_vfs.cc', + 'thread/thread_task.cc', + 'thread/thread_pool.cc', + 'render/render_context.c', + 'render/render_gl2.c', + 'render/render_gl3.c', + 'render/render_util.c', + 'engine/engine_derivative.c', + 'engine/engine_io.c', + 'engine/engine_sensor.c', + 'engine/engine_callback.c', + 'engine/engine_collision_driver.c', + 'engine/engine_core_constraint.c', + 'engine/engine_core_smooth.c', + 'engine/engine_derivative_fd.c', + 'engine/engine_forward.c', + 'engine/engine_inverse.c', + 'engine/engine_island.c', + 'engine/engine_name.c', + 'engine/engine_passive.c', + 'engine/engine_plugin.cc', + 'engine/engine_print.c', + 'engine/engine_ray.c', + 'engine/engine_setconst.c', + 'engine/engine_solver.c', + 'engine/engine_support.c', + 'engine/engine_util_blas.c', + 'engine/engine_util_container.c', + 'engine/engine_util_errmem.c', + 'engine/engine_util_misc.c', + 'engine/engine_util_solve.c', + 'engine/engine_util_spatial.c', + 'engine/engine_util_sparse.c', + 'engine/engine_vis_init.c', + 'engine/engine_vis_interact.c', + 'engine/engine_vis_state.c', + 'engine/engine_vis_visualize.c', + 'ui/ui_main.c', +]; + +class LineNumbers { + constructor() { + this.map = new Map(); + } + + static fetch(src) { + const url = `https://raw.githubusercontent.com/google-deepmind/mujoco/refs/heads/main/src/${src}`; + const request = new XMLHttpRequest(); + return new Promise((resolve, reject) => { + request.onreadystatechange = () => { + if (request.readyState === 4) { + if (request.status === 200) { + resolve(request.responseText); + } else { + reject(request.status); + } + } + }; + request.open('GET', url, true); + request.send(); + }); + } + + fetchAll() { + let requests = []; + for (const src of SRCS) { + requests.push(LineNumbers.fetch(src).then(contents => { + this.processSrc(src, contents); + }, reason => {/* swallow error */})); + } + Promise.all(requests).then(() => { + const anchors = document.querySelectorAll('h3 a.reference.external'); + for (const anchor of anchors) { + const url = anchor.getAttribute('href'); + if (url.startsWith('#')) { + const key = url.substring(1); + if (this.map.has(key)) { + anchor.href = this.map.get(key); + } else { + console.log(`No line number found for ${key}`); + } + } + } + }); + } + + processSrc(src, contents) { + const lines = contents.split('\n'); + const re = /^(const )?[a-zA-Z0-9_*]+\s(.+)\(.+[{,]$/; + for (let i = 0; i < lines.length; i++) { + if (lines[i].match(re)) { + const key = lines[i].match(re)[2]; + this.map.set(key, `https://github.com/google-deepmind/mujoco/blob/main/src/${src}#L${i+1}`); + } + } + + // edge cases + if (src == 'user/user_api.cc') { + for (let i = 0; i < lines.length; i++) { + if (lines[i].startsWith('[[nodiscard]] int mj_recompile(')) { + const key = 'mj_recompile'; + this.map.set(key, `https://github.com/google-deepmind/mujoco/blob/main/src/${src}#L${i+1}`); + } + } + } else if (src == 'engine/engine_io.c') { + for (let i = 0; i < lines.length; i++) { + if (lines[i].startsWith('void mj_freeStack(')) { + const key = 'mj_freeStack'; + this.map.set(key, `https://github.com/google-deepmind/mujoco/blob/main/src/${src}#L${i+1}`); + } else if (lines[i].startsWith('void mj_markStack(')) { + const key = 'mj_markStack'; + this.map.set(key, `https://github.com/google-deepmind/mujoco/blob/main/src/${src}#L${i+1}`); + } + } + } + } +} + +window.onload = () => { + if (document.getElementById('fetchlines')) { + let lines = new LineNumbers(); + lines.fetchAll(); + } +}; diff --git a/doc/mjx.rst b/doc/mjx.rst index c1e0fc16..98fb36b3 100644 --- a/doc/mjx.rst +++ b/doc/mjx.rst @@ -7,7 +7,7 @@ MuJoCo XLA (MJX) Starting with version 3.0.0, MuJoCo includes MuJoCo XLA (MJX) under the `mjx `__ directory. MJX allows MuJoCo to run on compute hardware supported by the `XLA `__ compiler via the -`JAX `__ framework. MJX runs on a +`JAX `__ framework. MJX runs on a `all platforms supported by JAX `__: Nvidia and AMD GPUs, Apple Silicon, and `Google Cloud TPUs `__. @@ -50,7 +50,7 @@ The recommended way to install this package is via `PyPI `__-compliant names. Most of the :ref:`main simulation ` and -some of the :ref:`sub-components ` for forward simulation are available from the top-level ``mjx`` module. +MuJoCo functions are exposed as MJX functions of the same name, but following `PEP 8 +`__-compliant names. Most of the :ref:`main simulation ` and some of +the :ref:`sub-components ` for forward simulation are available from the top-level ``mjx`` module. MJX functions are not `JIT compiled `__ by default -- we leave it to the user to JIT MJX functions, or JIT their own functions that reference MJX functions. See the @@ -165,6 +163,30 @@ Minimal example pos = jax.jit(batched_step)(vel) print(pos) +.. _MjxCli: + +Helpful Command Line Scripts +---------------------------- + +We provide two command line scripts with the ``mujoco-mjx`` package: + +.. code-block:: shell + + mjx-testspeed --mjcf=/PATH/TO/MJCF/ --base_path=. + +This command takes in a path to an MJCF file along with optional arguments (use ``--help`` for more information) +and computes helpful metrics for performance tuning. The command will output, among other things, the total +simulation time, the total steps per second and the total realtime factor (here total is across all available +devices). + +.. code-block:: shell + + mjx-viewer --help + +This command launches the MJX model in the simulate viewer, allowing you to visualize and interact with the model. +Note this steps the simulation using MJX physics (not C MuJoCo) so it can be helpful for example for debugging +solver parameters. + .. _MjxFeatureParity: Feature Parity @@ -190,18 +212,19 @@ The following features are **fully supported** in MJX: * - :ref:`Transmission ` - ``JOINT``, ``JOINTINPARENT``, ``SITE``, ``TENDON`` * - :ref:`Actuator Dynamics ` - - ``NONE``, ``INTEGRATOR``, ``FILTER``, ``FILTEREXACT`` + - ``NONE``, ``INTEGRATOR``, ``FILTER``, ``FILTEREXACT``, ``MUSCLE`` * - :ref:`Actuator Gain ` - - ``FIXED``, ``AFFINE`` + - ``FIXED``, ``AFFINE``, ``MUSCLE`` * - :ref:`Actuator Bias ` - - ``NONE``, ``AFFINE`` + - ``NONE``, ``AFFINE``, ``MUSCLE`` * - :ref:`Tendon Wrapping ` - - ``JOINT``, ``SITE``, ``PULLEY`` + - ``JOINT``, ``SITE``, ``PULLEY``, ``SPHERE``, ``CYLINDER`` * - :ref:`Geom ` - ``PLANE``, ``HFIELD``, ``SPHERE``, ``CAPSULE``, ``BOX``, ``MESH`` are fully implemented. ``ELLIPSOID`` and ``CYLINDER`` are implemented but only collide with other primitives, note that ``BOX`` is implemented as a mesh. * - :ref:`Constraint ` - - ``EQUALITY``, ``LIMIT_JOINT``, ``CONTACT_FRICTIONLESS``, ``CONTACT_PYRAMIDAL``, ``CONTACT_ELLIPTIC``, ``FRICTION_DOF``, ``FRICTION_TENDON`` + - ``EQUALITY``, ``LIMIT_JOINT``, ``CONTACT_FRICTIONLESS``, ``CONTACT_PYRAMIDAL``, ``CONTACT_ELLIPTIC``, + ``FRICTION_DOF``, ``FRICTION_TENDON`` * - :ref:`Equality ` - ``CONNECT``, ``WELD``, ``JOINT``, ``TENDON`` * - :ref:`Integrator ` @@ -209,19 +232,20 @@ The following features are **fully supported** in MJX: * - :ref:`Cone ` - ``PYRAMIDAL``, ``ELLIPTIC`` * - :ref:`Condim ` - - 1, 3, 4, 6 + - 1, 3, 4, 6 (1 is not supported with ``ELLIPTIC``) * - :ref:`Solver ` - ``CG``, ``NEWTON`` * - Fluid Model - :ref:`flInertia` * - :ref:`Tendons ` - - :ref:`Fixed ` + - :ref:`Fixed `, :ref:`Spatial ` * - :ref:`Sensors ` - ``MAGNETOMETER``, ``CAMPROJECTION``, ``RANGEFINDER``, ``JOINTPOS``, ``TENDONPOS``, ``ACTUATORPOS``, ``BALLQUAT``, ``FRAMEPOS``, ``FRAMEXAXIS``, ``FRAMEYAXIS``, ``FRAMEZAXIS``, ``FRAMEQUAT``, ``SUBTREECOM``, ``CLOCK``, ``VELOCIMETER``, ``GYRO``, ``JOINTVEL``, ``TENDONVEL``, ``ACTUATORVEL``, ``BALLANGVEL``, ``FRAMELINVEL``, ``FRAMEANGVEL``, ``SUBTREELINVEL``, ``SUBTREEANGMOM``, ``TOUCH``, ``ACCELEROMETER``, ``FORCE``, ``TORQUE``, - ``ACTUATORFRC``, ``JOINTACTFRC``, ``FRAMELINACC``, ``FRAMEANGACC``. + ``ACTUATORFRC``, ``JOINTACTFRC``, ``FRAMELINACC``, ``FRAMEANGACC`` + (``ACCELEROMETER``, ``FORCE``, ``TORQUE`` not supported with connect or weld equality constraints) The following features are **in development** and coming soon: @@ -240,18 +264,8 @@ The following features are **in development** and coming soon: - ``IMPLICIT`` * - Dynamics - :ref:`Inverse ` - * - :ref:`Actuator Dynamics ` - - ``MUSCLE`` - * - :ref:`Actuator Gain ` - - ``MUSCLE`` - * - :ref:`Actuator Bias ` - - ``MUSCLE`` - * - :ref:`Tendon Wrapping ` - - ``SPHERE``, ``CYLINDER`` * - Fluid Model - :ref:`flEllipsoid` - * - :ref:`Tendons ` - - :ref:`Spatial ` * - :ref:`Sensors ` - All except ``PLUGIN``, ``USER`` * - Lights @@ -300,22 +314,19 @@ Single scene simulation carefully optimized for CPU. MJX works best when simulating thousands or tens of thousands of scenes in parallel. Collisions between large meshes - MJX supports collisions between convex mesh geometries. However the convex collision algorithms - in MJX are implemented differently than in MuJoCo. MJX uses a branchless version of the - `Separating Axis Test `__ - (SAT) to determine if geometries are colliding with convex meshes, while MuJoCo uses the Minkowski Portal Refinement (MPR) - algorithm as implemented in `libccd `__. - SAT works well for smaller meshes but suffers in both runtime and memory for larger meshes. + MJX supports collisions between convex mesh geometries. However the convex collision algorithms in MJX are implemented + differently than in MuJoCo. MJX uses a branchless version of the `Separating Axis Test + `__ + (SAT) to determine if geometries are colliding with convex meshes, while MuJoCo uses either MPR or GJK/EPA, see + :ref:`Collision Detection` for more details. SAT works well for smaller meshes but suffers in both runtime + and memory for larger meshes. - For - collisions with convex meshes and primitives, the convex decompositon of the mesh should have - roughly **200 vertices or less** for reasonable performance. For convex-convex collisions, - the convex mesh should have roughly **fewer than 32 vertices**. We recommend using - :ref:`maxhullvert` in the MuJoCo compiler to achieve desired convex mesh properties. - With careful - tuning, MJX can simulate scenes with mesh collisions -- see the MJX - `shadow hand `__ - config for an example. Speeding up mesh collision detection is an active area of development for MJX. + For collisions with convex meshes and primitives, the convex decompositon of the mesh should have roughly **200 + vertices or less** for reasonable performance. For convex-convex collisions, the convex mesh should have roughly + **fewer than 32 vertices**. We recommend using :ref:`maxhullvert` in the MuJoCo compiler to + achieve desired convex mesh properties. With careful tuning, MJX can simulate scenes with mesh collisions -- see the + MJX `shadow hand `__ config + for an example. Speeding up mesh collision detection is an active area of development for MJX. Large, complex scenes with many contacts Accelerators exhibit poor performance for @@ -377,13 +388,12 @@ For MJX to perform well, some configuration parameters should be adjusted from t of 10% to 20%, as long as the dense matrices can fit on the device. Broadphase - While MuJoCo handles broadphase culling out of the box, MJX requires additional parameters. For an approximate version of - broadphase, use the experimental custom numeric parameters - ``max_contact_points`` and ``max_geom_pairs``. ``max_contact_points`` caps the number of contact points - sent to the solver for each condim type. ``max_geom_pairs`` caps the total number of geom-pairs sent to - respective collision functions for each geom-type pair. As an example, the - `shadow hand `__ - environment makes use of these parameters. + While MuJoCo handles broadphase culling out of the box, MJX requires additional parameters. For an approximate version + of broadphase, use the experimental custom numeric parameters ``max_contact_points`` and ``max_geom_pairs``. + ``max_contact_points`` caps the number of contact points sent to the solver for each condim type. ``max_geom_pairs`` + caps the total number of geom-pairs sent to respective collision functions for each geom-type pair. As an example, the + `shadow hand `__ environment + makes use of these parameters. GPU performance --------------- @@ -393,4 +403,4 @@ The following environment variables should be set: ``XLA_FLAGS=--xla_gpu_triton_gemm_any=true`` This enables the Triton-based GEMM (matmul) emitter for any GEMM that it supports. This can yield a 30% speedup on NVIDIA GPUs. If you have multiple GPUs, you may also benefit from enabling flags related to - `communciation between GPUs `__. + `communication between GPUs `__. diff --git a/doc/modeling.rst b/doc/modeling.rst index f0d3a0e6..4ef331a4 100644 --- a/doc/modeling.rst +++ b/doc/modeling.rst @@ -136,21 +136,21 @@ the model. We start with an example. .. code-block:: xml - - - - - + + + + + - - - - - - - - + + + + + + + + This example will not actually compile because some required information is missing, but here we are only interested @@ -629,11 +629,12 @@ Group disable The :ref:`actuatorgroupdisable` attribute, which can be changed at runtime by setting the :ref:`mjOption.disableactuator` integer bitfield, allows the user to disable sets of actuators according to their :ref:`group`. This feature is convenient when one would like to use multiple types of -actuators for the same kinematic tree. For example consider a robot with firmware that supports mutiple control modes +actuators for the same kinematic tree. For example consider a robot with firmware that supports multiple control modes e.g., torque-control and position-control. In this case, one can define both types of actuators in the same MJCF model, assigning one type of actuator to group 0 and the other to group 1. .. youtube:: H9qG9Zf2W44 + :aspect: 2:1 :align: right :width: 40% @@ -1120,122 +1121,40 @@ Intrinsics Composite objects ~~~~~~~~~~~~~~~~~ -Composite objects are not new model elements. Instead, they are (large) collections of existing elements designed to -simulate particle systems, ropes, cloth, and soft bodies. These collections are generated by the model compiler -automatically. The user configures the automatic generator on a high level, using the new XML element -:ref:`composite ` and its attributes and sub-elements, as described in the XML reference -chapter. If the compiled model is then saved, :el:`composite` is no longer present and is replaced with the collection -of regular model elements that were automatically generated. So think of it as a macro that gets expanded by the model -compiler. +Composite objects are not new model elements. Instead, they are collections of existing element originally designed to +simulate particle systems, ropes, cloth, and soft bodies. Over time, most of these types have been replaced by +:ref:`replicate` (for repeated objects) and :ref:`flexcomp` (for soft objects). Therefore, the +only supported composite type is now ``cable``, which produces an inextensible chain of bodies connected with ball +joints. -Composite objects are made up of regular MuJoCo bodies, which we call "element bodies" in this context. The element -bodies are created as children of the body within which :el:`composite` appears; thus a composite object appears in the -same place in the XML where a regular child body may have been defined. Each automatically-generated element body has a -single geom attached to it, usually a sphere but could also be a capsule or an ellipsoid. Thus the composite object is -essentially a particle system, however the particles can be constrained to move together in ways that simulate various -flexible objects. The initial positions of the element bodies form a regular grid in 1D, 2D or 3D. They could all be -children of the parent body (which can be the world or another regular body; composite objects cannot be nested) and -have joints allowing motion relative to the parent, or they could form a kinematic tree with joints between the element -bodies. They can also be connected with tendons with soft equality constraints on the tendon length, creating the -necessary coupling. Joint equality constraints are also used in some cases. The :at:`solref` and :at:`solimp` attributes -of these equality constraints can be adjusted by the user, thereby adjusting the softness and flexibility of the -composite objects. +Composite objects are made up of regular MuJoCo bodies, which we call "element bodies" in this context. The collection +of element bodies is generated by the model compiler automatically. The user configures the automatic generator on a +high level, using the new XML element :ref:`composite ` and its attributes and sub-elements, as +described in the XML reference chapter. If the compiled model is then saved, :el:`composite` is no longer present and is +replaced with the collection of regular model elements that were automatically generated. So think of it as a macro that +gets expanded by the model compiler. The element bodies are created as children of the body within which :el:`composite` +appears; thus a composite object appears in the same place in the XML where a regular child body may have been defined. +Each automatically-generated element body has a single geom attached to it. We have designed the composite object +generator to have intuitive high-level controls as much as possible, but at the same time it exposes a large number of +options that interact with each other and can profoundly affect the resulting physics. So at some point users should +read the :ref:`reference documentation ` carefully. -In addition to setting up the physics, the composite object generator creates suitable rendering. 2D and 3D objects -can be rendered as :ref:`skins `. The skin is generated -automatically, and can be textured as well as subdivided using bi-cubic interpolation. The actual physics and in -particular the collision detection are based on the element bodies and their geoms, while the skin is purely a -visualization object. Yet in most situations we prefer to look at the skin representation. To facilitate this, the -generator places all geoms, sites and tendons in group 3 whose visualization is disabled by default. So when you load -a 2D grid for example, you will see a continuous flexible surface and not a collection of spheres connected with -tendons. However when fine-tuning the model and trying to understand the physics behind it, it is useful to be able to -render the spheres and tendons. To switch the rendering style, disable the rendering of skins and enable group 3 for -geoms and tendons. - -We have designed the composite object generator to have intuitive high-level controls as much as possible, but at the -same time it exposes a large number of options that interact with each other and can profoundly affect the resulting -physics. So at some point users should read the :ref:`reference documentation ` carefully. -As a quick start though, MuJoCo comes with an example of each composite object type. Below we go over these -examples and explain the less obvious aspects. In all examples we have a static scene which is included in the model, -followed by a single composite object. The static scene has a mocap body (large capsule) that can be moved around with -the mouse to probe the behavior of the system. The XML snippets below are just the definition of the composite object; -see the XML model files in the distribution for the complete examples. - -**Particle**. - -|image4| |image5| - -.. code-block:: xml - - - - - - - -The above XML is all it takes to create a system with 1000 particles with initial positions on a 10-10-10 grid, and -set the size, color, spacing and offset of the particles. The resulting element bodies become children of the world -body. One could adjust many other properties including the softness of the contacts and the joint attributes. The plot -on the right shows the joints. Each element body has 3 orthogonal slider joints, allowing it to translate but not -rotate. The idea is that particles should have position but no orientation. MuJoCo bodies always have orientation, -however by using only slider joints we do not allow the orientation to change. The geom defaults are adjusted -automatically so that they make frictionless contacts with each other and with the rest of the model. So this system -has 1000 bodies (each with a geom), 3000 degrees of freedom and around 1000 active contacts. Evaluating the dynamics -takes around 1 ms on a single core of a modern processor. As with most other MuJoCo models, the soft constraints allow -simulation at much larger timesteps (this model is stable at 30 ms timestep and even higher). - -Particles are also compatible with the passive forces 2D and 3D plugins, discussed in the :ref:`deformable -` section. However, collisions are limited to the particle themselves and not to the whole boundary of the -skin that encloses them. This makes contacts very fast but does not guarantee that all penetrations can be avoided. For -a more complete treatment, see again the :ref:`deformable ` section, which outlines how to use -:ref:`flexcomp` to create such an object. It is easy to port models create with composite particles to -flex, see the folder `elasticity/ `__ for -several examples. - -**1D grid**. - -|image6| |image7| - -.. code-block:: xml - - - - - - - - - -The grid type can create 1D or 2D grids, depending on the :at:`count` attribute. Here we illustrate 1D grids. These -are strings of spheres connected with tendons whose length is soft-equality-constrained. The softness can be adjusted. -Similar to particles, the element bodies here have slider joints but no rotational joints. The plot on the right -illustrates pinning. The :el:`pin` sub-element is used to specify the grid coordinates of the pinned bodies, and the -model compiler does not generate joints for these bodies, thereby fixing them rigidly to the parent body (in this case -the world). This makes the string in the right plot hang in space. The same mechanism can be used to model a whip for -example; in that case the parent body would be moving, and the first element body would be pinned to the parent. - -**2D grid**. - -|image8| |image9| - -.. code-block:: xml - - - - - - - - -A 2D grid can be used to simulate cloth. What it really simulates is a 2D grid of spheres connected with -equality-constrained tendons (not shown). The model compiler can also generate skin, enabled with the :el:`skin` -sub-element in the above XML. Some of the element bodies can also be pinned, similar to 1D grids but using two grid -coordinates. The plot on the right shows a cloth pinned to the world body at the two corners, and draping over our -capsule probe. The skin on the right is subdivided using bi-cubic interpolation, which increases visual quality in the -absence of textures. When textures are present (left) the benefits of subdivision are less visible. +In addition to setting up the physics, the composite object generator creates suitable rendering. Objects can be +rendered as :ref:`skins `. The skin is generated automatically, and can be textured as well as subdivided +using bi-cubic interpolation. The actual physics and in particular the collision detection are based on the element +bodies and their geoms, while the skin is purely a visualization object. Yet in some situations we prefer to look at the +skin representation, as in `this model +`__, whose skin is a continuous +flexible surface and not a collection of discontinuous thin boxes. However when fine-tuning the model and trying to +understand the physics behind it, it is useful to be able to render the geoms. To switch the rendering style, disable +the rendering of skins and enable group 3 for geoms and tendons. **Cable**. +As a quick start, MuJoCo comes with an example of composite cables. In all examples we have a static scene which is +included in the model, followed by a single composite object. The XML snippets below are just the definition of the +composite object; see the XML model files in the distribution for the complete examples. + |coil| .. code-block:: xml @@ -1269,6 +1188,16 @@ stiffnesses can be set independently. Moreover, it is possible to specify if the curve, such as in the case of coil springs. The cable requires using a first-party :ref:`engine plugin`, which may be integrated directly into the engine in the future. +**Particle**. + +The particle type is deprecated. It is recommended to use the more generic :ref:`replicate` instead, for +example `this model `__. + +**Grid**. + +The grid composite type has been removed. It is recommended to use 2D flex :ref:`deformable objects ` for +simulating thin elastic structures. + **Rope and loop**. The rope and loop are deprecated. It is recommended to use the cable for simulating inextensible elastic rods that are @@ -1280,62 +1209,11 @@ scenario (e.g. a stretched rubber band). The cloth is deprecated. It is recommended to use 2D flex :ref:`deformable objects ` for simulating thin elastic structures. -**Box**. +**Box, cylinder and ellipsoid**. -|image14| |image15| -.. code-block:: xml - - - - - - - - - -The box type, as well as the cylinder and ellipsoid types below, are used to model soft 3D objects. The element bodies -form a grid along the outer shell, thus the number of element bodies scales with the square of the linear dimension. -This is much more efficient than simulating a 3D grid. The parent body within which :el:`composite` appears is at the -center of the soft object. All element bodies are children of the parent. Each element body has a single sliding joint -pointing away from the parent. These joints allow the surface of the soft object to compress and expand at any point. -The joints are equality-constrained to their initial position, so as to maintain the shape. In addition each joint is -equality-constrained to its neighbor joints, so that when the soft objects deforms, the deformation is smooth. -Finally, there is a tendon equality constraint specifying that the sum of all joints should remain constant. This -attempts to preserve the volume of the soft object approximately. If the object is squeezed from all sides it will -compress and the volume will decrease, but otherwise some element bodies will stick out to compensate for squeezing -elsewhere. The plot on the left shows this effect; we are using the capsule probe to compress one corner, and the -opposite sides of the cube expand a bit, while the deformations remain smooth. The :at:`count` attribute determines -the number of element bodies in each dimension, so if the counts are different the resulting object will be a -rectangular box and not a cube. The geoms attached to the element bodies can be spheres, capsules or ellipsoids. -Spheres are faster for collision detection, but they result in a thin shell, allowing other bodies to "get under the -skin" of the soft object. When capsules or ellipsoids are used, they are automatically oriented so that the long axis -points to the outside, thus creating a thicker shell which is harder to penetrate. - -**Cylinder and ellipsoid**. - -|image16| |image17| - -.. code-block:: xml - - - - - - - - - -Cylinders and ellipsoids are created in the same way as boxes. The only difference is that the reference positions of -the element bodies (relative to the parent) are projected on a cylinder or ellipsoid, with size implied by the -:at:`count` attribute. The automatic skin generator is aware of the smooth surfaces, and adjusts the skin normals -accordingly. In the plots we have used the capsule probe to press on each body, then paused the simulation and moved the -probe away (which is possible because the probe is a mocap body which can move independent of the physics). In this way -we can see the indentation made by the probe, and the resulting deformation in the rest of the body. By changing the -solref and solimp attributes of the equality constraints that hold the soft object together, one can adjust the behavior -of the system making it softer or harder, damped or springy, etc. Note that box, cylinder and ellipsoid objects do not -involve long kinematic chains, and can be simulated at large timesteps -- similar to particle and grid, and unlike rope -and cloth. +The box type, as well as the cylinder and ellipsoid types, are now deprecated in favor of 3D flex :ref:`deformable +objects `. element. .. _CDeformable: @@ -1386,9 +1264,7 @@ improved realism and accuracy. The edge-based model could be seen as a "lumped" coupling of deformation modes (e.g. shear and volumetric) is averaged in a single quantity. The continuum model enables instead to specify shear and volumetic stiffnesses separately using the `Poisson's ratio `__ of the material. For more details, see the `Saint Venant-Kirchhoff -`__ hyperelastic model. This -functionality is currently based on first-party :ref:`engine plugins` as of MuJoCo 3.0 but may be integrated -into the engine in future releases. +`__ hyperelastic model. **Creation and visualization**. @@ -1396,20 +1272,12 @@ into the engine in future releases.