Rename Python mujoco.simulate to mujoco.viewer.
PiperOrigin-RevId: 492701386 Change-Id: I059c572e2a63bd5529e863a9404720973df8ea46
This commit is contained in:
Saran Tunyasuvunakool
committed by
Copybara-Service
Copybara-Service
parent
dee1d6020a
commit
0846f38c82
+2
-2
@@ -9,8 +9,8 @@ Upcoming version (not yet released)
|
||||
Python bindings
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
- The ``simulate`` GUI is now available through the ``mujoco`` Python package. See :ref:`documentation<PyGUI>` for
|
||||
details. (Contribution by `Levi Burner <https://github.com/aftersomemath>`_.)
|
||||
- The ``simulate`` GUI is now available through the ``mujoco`` Python package as ``mujoco.viewer``.
|
||||
See :ref:`documentation<PyViewer>` for details. (Contribution by `Levi Burner <https://github.com/aftersomemath>`_.)
|
||||
|
||||
General
|
||||
^^^^^^^
|
||||
|
||||
+99
-99
@@ -102,8 +102,41 @@ The Python bindings should now be installed! To check that they've been
|
||||
successfully installed, ``cd`` outside of the ``mujoco`` directory and run
|
||||
``python -c "import mujoco"``.
|
||||
|
||||
.. _PyViewer:
|
||||
|
||||
Interactive viewer
|
||||
==================
|
||||
|
||||
An interactive GUI viewer is available as part of the Python package. (This is the same viewer as the ``simulate``
|
||||
application that ships with the MuJoCo binary releases.)
|
||||
|
||||
Three distinct use cases are supported:
|
||||
|
||||
#. Launching as a standalone application:
|
||||
|
||||
- ``python -m mujoco.viewer`` launches an empty visualization session, where a model can be loaded by drag-and-drop.
|
||||
- ``python -m mujoco.viewer --mjcf=/path/to/some/mjcf.xml`` launches a visualization session for the specified
|
||||
model file.
|
||||
|
||||
#. Launching from a Python program/script -- import the module via ``from mujoco import viewer`` and launch the GUI
|
||||
using one of the following invocations:
|
||||
|
||||
- ``viewer.launch()`` launches an empty visualization session, where a model can be loaded by drag-and-drop.
|
||||
- ``viewer.launch(model)`` launches a visualzation session for the given ``mjModel`` where the visualizer
|
||||
internally creates its own instance of ``mjData``
|
||||
- ``viewer.launch(model, data)`` is the same as above, except that the visualizer operates directly on the given
|
||||
``mjData`` instance -- upon exit the ``data`` object will have been modified.
|
||||
|
||||
#. Launching from an interactive Python session (aka REPL): when working interactively either in a ``python`` or
|
||||
``ipython`` shell, the visualizer can be launched in a "passive" mode via ``viewer.launch_repl(model, data)``, where
|
||||
the user remains in full control of modifying or stepping the physics. In this mode, the user can interact with the
|
||||
visualizer using the mouse and keyboard as usual, however the physics will be frozen unless the user explicitly calls
|
||||
``mj_step`` (or perform any other modification of the ``mjData`` or ``mjModel``) in the REPL terminal. Note that since
|
||||
the visualizer does not modify ``mjData`` in this mode, mouse-drag perturbations will not work unless the user
|
||||
explicitly handles incoming GUI perturbation events in the REPL session.
|
||||
|
||||
Basic usage
|
||||
-----------
|
||||
===========
|
||||
|
||||
Once installed, the package can be imported via ``import mujoco``. Structs, functions, constants, and enums are
|
||||
available directly from the top-level ``mujoco`` module.
|
||||
@@ -111,7 +144,7 @@ available directly from the top-level ``mujoco`` module.
|
||||
.. _PyStructs:
|
||||
|
||||
Structs
|
||||
=======
|
||||
-------
|
||||
|
||||
MuJoCo data structures are exposed as Python classes. In order to conform to
|
||||
`PEP 8 <https://peps.python.org/pep-0008/>`__ naming guidelines, struct names begin with a capital letter, for example
|
||||
@@ -135,7 +168,7 @@ Structs
|
||||
dictionary which is converted into a MuJoCo :ref:`Virtualfilesystem` for use during model compilation.
|
||||
|
||||
Functions
|
||||
=========
|
||||
---------
|
||||
|
||||
MuJoCo functions are exposed as Python functions of the same name. Unlike with structs, we do not attempt to make
|
||||
the function names `PEP 8 <https://peps.python.org/pep-0008/>`__-compliant, as MuJoCo uses both underscores and
|
||||
@@ -171,9 +204,8 @@ Functions
|
||||
for _ in range(20):
|
||||
mj_step(model, data)
|
||||
|
||||
|
||||
Enums and constants
|
||||
===================
|
||||
-------------------
|
||||
|
||||
MuJoCo enums are available as ``mujoco.mjtEnumType.ENUM_VALUE``, for example ``mujoco.mjtObj.mjOBJ_SITE``. MuJoCo
|
||||
constants are available with the same name directly under the ``mujoco`` module, for example ``mujoco.mjVISSTRING``.
|
||||
@@ -209,38 +241,6 @@ Minimal example
|
||||
mujoco.mj_step(model, data)
|
||||
print(data.geom_xpos)
|
||||
|
||||
.. _PyGUI:
|
||||
|
||||
Interactive visualizer
|
||||
----------------------
|
||||
|
||||
MuJoCo's interactive GUI (also known as the ``simulate`` application) is available as part of the Python package.
|
||||
Three distinct use cases are supported:
|
||||
|
||||
- Launching as a standalone application:
|
||||
|
||||
* ``python -m mujoco.simulate`` launches an empty visualization session, where a model can be loaded by drag-and-drop.
|
||||
* ``python -m mujoco.simulate --mjcf=/path/to/some/mjcf.xml`` launches a visualization session for the specified
|
||||
model file.
|
||||
|
||||
- Launching from a Python program/script -- import the module via ``from mujoco import simulate`` and launch the GUI
|
||||
using one of the following invocations:
|
||||
|
||||
* ``simulate.launch()`` launches an empty visualization session, where a model can be loaded by drag-and-drop.
|
||||
* ``simulate.launch(model)`` launches a visualzation session for the given ``mjModel`` where the visualizer
|
||||
internally creates its own instance of ``mjData``
|
||||
* ``simulate.launch(model, data)`` is the same as above, except that the visualizer operates directly on the given
|
||||
``mjData`` instance -- upon exit the ``data`` object will have been modified.
|
||||
|
||||
- Launching from an interactive Python session (aka REPL): when working interactively either in a ``python`` or
|
||||
``ipython`` shell, the visualizer can be launched in a "passive" mode via ``simulate.launch_repl(model, data)``, where
|
||||
the user remains in full control of modifying or stepping the physics. In this mode, the user can interact with the
|
||||
visualizer using the mouse and keyboard as usual, however the physics will be frozen unless the user explicitly calls
|
||||
``mj_step`` (or perform any other modification of the ``mjData`` or ``mjModel``) in the REPL terminal. Note that since
|
||||
the visualizer does not modify ``mjData`` in this mode, mouse-drag perturbations will not work unless the user
|
||||
explicitly handles incoming GUI perturbation events in the REPL session.
|
||||
|
||||
|
||||
.. _PyNamed:
|
||||
|
||||
Named access
|
||||
@@ -356,69 +356,8 @@ Alternatively, if a callback is implemented in a native dynamic library, users c
|
||||
it to ``mujoco.set_mjcb_foo``. The bindings will then retrieve the underlying function pointer and assign it directly to
|
||||
the raw callback pointer, and the GIL will **not** be acquired each time the callback is entered.
|
||||
|
||||
.. _PyMjpy_migration:
|
||||
|
||||
Migration Notes for mujoco-py
|
||||
-----------------------------
|
||||
|
||||
In mujoco-py, the main entry point is the `MjSim <https://github.com/openai/mujoco-py/blob/master/mujoco_py/mjsim.pyx>`_
|
||||
class. Users construct a stateful ``MjSim`` instance from an MJCF model (similar to ``dm_control.Physics``), and this
|
||||
instance holds references to an ``mjModel`` instance and its associated ``mjData``. In contrast, the MuJoCo Python
|
||||
bindings (``mujoco``) take a more low-level approach, as explained above: following the design principle of the C
|
||||
library, the ``mujoco`` module itself is stateless, and merely wraps the underlying native structs and functions.
|
||||
|
||||
While a complete survey of mujoco-py is beyond the scope of this document, we offer below implementation notes for a
|
||||
non-exhaustive list of specific mujoco-py features:
|
||||
|
||||
``mujoco_py.load_model_from_xml(bstring)``
|
||||
===========================================
|
||||
|
||||
This factory function constructs a stateful ``MjSim`` instance. When using ``mujoco``, the user should call the factory
|
||||
function ``mujoco.MjModel.from_xml_*`` as described :ref:`above <PyStructs>`. The user is then responsible for holding
|
||||
the resulting ``MjModel`` struct instance and explicitly generating the corresponding ``MjData`` by calling
|
||||
``mujoco.MjData(model)``.
|
||||
|
||||
``sim.reset()``, ``sim.forward()``, ``sim.step()``
|
||||
==================================================
|
||||
|
||||
Here as above, ``mujoco`` users needs to call the underlying library functions, passing instances of ``MjModel`` and
|
||||
``MjData``: :ref:`mujoco.mj_resetData(model, data) <mj_resetData>`, :ref:`mujoco.mj_forward(model, data) <mj_forward>`,
|
||||
and :ref:`mujoco.mj_step(model, data) <mj_step>`.
|
||||
|
||||
``sim.get_state()``, ``sim.set_state(state)``, ``sim.get_flattened_state()``, ``sim.set_state_from_flattened(state)``
|
||||
=====================================================================================================================
|
||||
|
||||
The MuJoCo library’s computation is deterministic given a specific input, as explained in the :ref:`Programming section
|
||||
<Simulation>`. mujoco-py implements methods for getting and setting some of the relevant fields (and similarly
|
||||
``dm_control.Physics`` offers methods that correspond to the flattened case). ``mujoco`` do not offer such abstraction,
|
||||
and the user is expected to get/set the values of the relevant fields explicitly.
|
||||
|
||||
``sim.model.get_joint_qvel_addr(joint_name)``
|
||||
=============================================
|
||||
|
||||
This is a convenience method in mujoco-py that returns a list of contiguous indices corresponding to this joint. The
|
||||
list starts from ``model.jnt_qposadr[joint_index]``, and its length depends on the joint type. ``mujoco`` doesn't offer
|
||||
this functionality, but this list can be easily constructed using ``model.jnt_qposadr[joint_index]`` and ``xrange``.
|
||||
|
||||
``sim.model.*_name2id(name)``
|
||||
=============================
|
||||
|
||||
mujoco-py creates dicts in ``MjSim`` that allow for efficient lookup of indices for objects of different types:
|
||||
``site_name2id``, ``body_name2id`` etc. These functions replace the function :ref:`mujoco.mj_name2id(model, type_enum,
|
||||
name) <mj_name2id>` whose current implementation is inefficient. ``mujoco`` offers a different
|
||||
approach for using entity names – :ref:`named access <PyNamed>`, as well as access to the native :ref:`mj_name2id`.
|
||||
|
||||
``sim.save(fstream, format_name)``
|
||||
==================================
|
||||
|
||||
This is the one context in which the MuJoCo library (and therefore also ``mujoco``) is stateful: it holds a copy in
|
||||
memory of the last XML that was compiled, which is used in :ref:`mujoco.mj_saveLastXML(fname) <mj_saveLastXML>`. Note
|
||||
that mujoco-py’s implementation has a convenient extra feature, whereby the pose (as determined by ``sim.data``’s
|
||||
state) is transformed to a keyframe that’s added to the model before saving. This extra feature is not currently
|
||||
available in ``mujoco``.
|
||||
|
||||
Code Sample: open-loop rollout
|
||||
------------------------------
|
||||
==============================
|
||||
|
||||
We include a code sample showing how to add additional C/C++ functionality, exposed as a Python module via pybind11. The
|
||||
sample, implemented in ``rollout.cc`` and wrapped in ``rollout.py``, implements a common use case where tight loops
|
||||
@@ -441,3 +380,64 @@ all inputs including ``time`` and ``qacc_warmstart`` are set to default values,
|
||||
|
||||
Since the Global Interpreter Lock can be released, this function can be efficiently threaded using Python threads. See
|
||||
the ``test_threading`` function in ``rollout_test.py`` for an example of threaded operation.
|
||||
|
||||
.. _PyMjpy_migration:
|
||||
|
||||
Migration Notes for mujoco-py
|
||||
=============================
|
||||
|
||||
In mujoco-py, the main entry point is the `MjSim <https://github.com/openai/mujoco-py/blob/master/mujoco_py/mjsim.pyx>`_
|
||||
class. Users construct a stateful ``MjSim`` instance from an MJCF model (similar to ``dm_control.Physics``), and this
|
||||
instance holds references to an ``mjModel`` instance and its associated ``mjData``. In contrast, the MuJoCo Python
|
||||
bindings (``mujoco``) take a more low-level approach, as explained above: following the design principle of the C
|
||||
library, the ``mujoco`` module itself is stateless, and merely wraps the underlying native structs and functions.
|
||||
|
||||
While a complete survey of mujoco-py is beyond the scope of this document, we offer below implementation notes for a
|
||||
non-exhaustive list of specific mujoco-py features:
|
||||
|
||||
``mujoco_py.load_model_from_xml(bstring)``
|
||||
------------------------------------------
|
||||
|
||||
This factory function constructs a stateful ``MjSim`` instance. When using ``mujoco``, the user should call the factory
|
||||
function ``mujoco.MjModel.from_xml_*`` as described :ref:`above <PyStructs>`. The user is then responsible for holding
|
||||
the resulting ``MjModel`` struct instance and explicitly generating the corresponding ``MjData`` by calling
|
||||
``mujoco.MjData(model)``.
|
||||
|
||||
``sim.reset()``, ``sim.forward()``, ``sim.step()``
|
||||
--------------------------------------------------
|
||||
|
||||
Here as above, ``mujoco`` users needs to call the underlying library functions, passing instances of ``MjModel`` and
|
||||
``MjData``: :ref:`mujoco.mj_resetData(model, data) <mj_resetData>`, :ref:`mujoco.mj_forward(model, data) <mj_forward>`,
|
||||
and :ref:`mujoco.mj_step(model, data) <mj_step>`.
|
||||
|
||||
``sim.get_state()``, ``sim.set_state(state)``, ``sim.get_flattened_state()``, ``sim.set_state_from_flattened(state)``
|
||||
---------------------------------------------------------------------------------------------------------------------
|
||||
|
||||
The MuJoCo library’s computation is deterministic given a specific input, as explained in the :ref:`Programming section
|
||||
<Simulation>`. mujoco-py implements methods for getting and setting some of the relevant fields (and similarly
|
||||
``dm_control.Physics`` offers methods that correspond to the flattened case). ``mujoco`` do not offer such abstraction,
|
||||
and the user is expected to get/set the values of the relevant fields explicitly.
|
||||
|
||||
``sim.model.get_joint_qvel_addr(joint_name)``
|
||||
---------------------------------------------
|
||||
|
||||
This is a convenience method in mujoco-py that returns a list of contiguous indices corresponding to this joint. The
|
||||
list starts from ``model.jnt_qposadr[joint_index]``, and its length depends on the joint type. ``mujoco`` doesn't offer
|
||||
this functionality, but this list can be easily constructed using ``model.jnt_qposadr[joint_index]`` and ``xrange``.
|
||||
|
||||
``sim.model.*_name2id(name)``
|
||||
-----------------------------
|
||||
|
||||
mujoco-py creates dicts in ``MjSim`` that allow for efficient lookup of indices for objects of different types:
|
||||
``site_name2id``, ``body_name2id`` etc. These functions replace the function :ref:`mujoco.mj_name2id(model, type_enum,
|
||||
name) <mj_name2id>` whose current implementation is inefficient. ``mujoco`` offers a different
|
||||
approach for using entity names – :ref:`named access <PyNamed>`, as well as access to the native :ref:`mj_name2id`.
|
||||
|
||||
``sim.save(fstream, format_name)``
|
||||
----------------------------------
|
||||
|
||||
This is the one context in which the MuJoCo library (and therefore also ``mujoco``) is stateful: it holds a copy in
|
||||
memory of the last XML that was compiled, which is used in :ref:`mujoco.mj_saveLastXML(fname) <mj_saveLastXML>`. Note
|
||||
that mujoco-py’s implementation has a convenient extra feature, whereby the pose (as determined by ``sim.data``’s
|
||||
state) is transformed to a keyframe that’s added to the model before saving. This extra feature is not currently
|
||||
available in ``mujoco``.
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
# ==============================================================================
|
||||
"""Python bindings for the Simulate GUI."""
|
||||
"""Interactive GUI viewer for MuJoCo."""
|
||||
|
||||
import atexit
|
||||
import code
|
||||
@@ -69,7 +69,7 @@ def _file_loader(path: str) -> _LoaderWithPathType:
|
||||
|
||||
|
||||
def _physics_loop(simulate: Simulate, loader: Optional[_InternalLoaderType]):
|
||||
"""Physics loop for the Simulate GUI, to be run in a separate thread."""
|
||||
"""Physics loop for the GUI, to be run in a separate thread."""
|
||||
m: mujoco.MjModel = None
|
||||
d: mujoco.MjData = None
|
||||
ctrlnoise = np.array([])
|
||||
Reference in New Issue
Block a user