Documentation

Contents:

Overview

Mujoco Toolbox

A toolbox for working with MuJoCo simulations.

This package provides various utilities and controllers to facilitate a faster simulation process.

Modules

  • wrapper: Contains the Wrapper class for interfacing with MuJoCo.

  • controllers: Includes pre-built functions for controlling simulations.

  • assets: Contains pre-defined assets for building MuJoCo models.

Constants

  • CAPTURE_PARAMETERS: List of MjData fields to capture during simulation.

  • MAX_GEOM_SCALAR: Scalar value for mujoco.Renderer.max_geom.

This project is licensed under the MIT License. See the LICENSE file for details.

Notes

This package is still under development. Report any issues to: https://github.com/MGross21/mujoco-toolbox/issues.

class mujoco_toolbox.Builder(*args: str)[source]

Bases: object

Builder class for loading, merging, and saving MuJoCo models from XML strings or file paths.

save(file_path: str) → str[source]

Save the merged model to a file.

Parameters:

file_path – Path to save the model.

Returns:

Absolute path to the saved file.

Return type:

str

Raises:

ValueError – If no model is loaded.

class mujoco_toolbox.Wrapper(*args: Any, **kwargs: Any)[source]

Bases: object

Wrapper class for managing MuJoCo simulations.

body_data(body_name: str, data_name: str | None = None) → dict[str, ndarray] | ndarray[source]

Get the data for a specific body in the simulation.

Parameters:

  • body_name (str) – The name of the body to retrieve data for.

  • data_name (str) – The name of the data to retrieve.

Returns:

The data for the specified body.

Return type:

dict[str, np.ndarray] | np.ndarray

property captured_data: dict[str, ndarray]

Read-only property to access the entire captured simulation data.

property controller: Callable[[MjModel, MjData, Any], None] | None

Controller Function.

property data: MjData

Read-only property to access the MjData single-step object.

Use captured_data to access the entire simulation data.

property data_rate: int

Data rate of the simulation in frames per second.

property duration: float

Duration of the simulation in seconds.

f2t(frame: int) → float[source]

Convert frame index to time.

property fps: float

Frames per second.

property frames: list[ndarray]

Read-only property to access the captured frames.

property gravity: ndarray

Gravity vector of the simulation.

id2name(id: int) → str[source]

Get the name of a body given its ID.

Parameters:

id (int) – The ID of the body.

Returns:

The name of the body.

Return type:

str

property initial_conditions: dict[str, list]

Initial conditions for the simulation.

property keyframe: int | None

Keyframe index for the simulation.

launch(show_menu: bool = True) → None[source]

Open a window to display the simulation in real time.

property model: MjModel

Read-only property to access the MjModel object.

name2id(name: str) → int[source]

Get the name of a body given its index.

Parameters:

name (str) – The name of the body.

Returns:

The index of the body.

Return type:

int

reload() → Wrapper[source]

Reload the model and data objects.

Returns:

Self for method chaining.

Return type:

Wrapper

property resolution: tuple[int, int]

Resolution of the simulation in pixels (w,h).

run(*, render: bool = False, camera: str | None = None, interactive: bool = False, show_menu: bool = True, multi_thread: bool = False) → Wrapper[source]

Run the simulation with optional rendering.

Parameters:

  • render (bool) – If True, renders the simulation.

  • camera (str) – The camera view to render from, defaults to None.

  • data_rate (int) – How often to capture data, expressed as frames

  • second. (per)

  • interactive (bool) – If True, opens an interactive viewer window.

  • show_menu (bool) – Shows the menu in the interactive viewer.

  • True. (Interactive must be)

  • multi_thread (bool) – If True, runs the simulation in multi-threaded

  • mode.

Returns:

The current Wrapper object for method chaining.

Return type:

self

save(title: str = 'render', codec: str = 'gif', frame_idx: int | tuple[int, int] | None = None, time_idx: float | tuple[float, float] | None = None) → str[source]

Save specific frame(s) as a video or GIF to a file.

Parameters:

  • title (str, optional) – Filename for the saved media.

  • codec (str, optional) – Video codec/format. Defaults to “gif”.

  • frame_idx (int or tuple, optional) – Single frame index or (start, stop) frame indices.

  • time_idx (float or tuple, optional) – Single time or (start, end) times in seconds.

Returns:

Absolute path to the saved file.

Return type:

str

Raises:

ValueError – If no frames are captured or invalid input parameters.

save_yaml(name: str = 'Model') → None[source]

Save simulation data to a YAML file.

Parameters:

name (str) – The filename for the YAML file.

Returns:

None

show(title: str | None = None, codec: str = 'gif', frame_idx: int | tuple[int, int] | None = None, time_idx: float | tuple[float, float] | None = None) → None[source]

Render specific frame(s) as a video or GIF in a window.

Parameters:

  • title (str, optional) – Title for the rendered media.

  • codec (str, optional) – Video codec/format. Defaults to “gif”.

  • frame_idx (int or tuple, optional) – Single frame index or (start, stop) frame indices.

  • time_idx (float or tuple, optional) – Single time or (start, end) times in seconds.

Raises:

ValueError – If no frames are captured or invalid input parameters.

t2f(t: float) → int[source]

Convert time to frame index.

property ts: float

Timestep of the simulation in seconds.

mujoco_toolbox.cos(model, data, **kwargs) → None[source]

A simple cosine wave controller for the simulation.

Parameters:

  • amplitude (float) – The amplitude of the cosine wave (default=1).

  • frequency (float) – The frequency of the cosine wave (default=1).

  • phase (float) – The phase shift of the cosine wave (default=0).

  • joint (list[int]) – The joint to apply the cosine wave to (default=all).

  • delay (float) – The delay before applying the cosine wave (default=0).

Returns:

None

mujoco_toolbox.glovebox(*, width: float = 1.25, depth: float = 0.75, height: float = 1.0, glass_thickness: float = 0.05, pos_x: float = 0, pos_y: float = 0) → str[source]

Create a glovebox with the given dimensions.

mujoco_toolbox.random(model, data, **kwargs) → None[source]

A random controller for the simulation.

Parameters:

  • amplitude (float) – The maximum amplitude of the random signal (default=1).

  • joint (list[int]) – The joints to apply the random signal to (default=all).

  • axis (int) – The axis to apply the random signal to (default=None).

  • delay (float) – The delay before applying the random signal (default=0).

Returns:

None

mujoco_toolbox.real_time(model, data, *args, **kwargs) → None[source]

A real-time controller for the simulation.

Parameters:

controller_params (dict) – Dictionary of parameters to pass to the controller.

Returns:

None

mujoco_toolbox.sin(model, data, **kwargs) → None[source]

A simple sine wave controller for the simulation.

Parameters:

  • amplitude (float) – The amplitude of the sine wave (default=1).

  • frequency (float) – The frequency of the sine wave (default=1).

  • phase (float) – The phase shift of the sine wave (default=0).

  • joint (list[int]) – The joint to apply the sine wave to (default=all).

  • delay (float) – The delay before applying the sine wave (default=0).

Returns:

None

mujoco_toolbox.step(model, data, **kwargs) → None[source]

A step controller for the simulation.

Parameters:

  • amplitude (float) – The amplitude of the step signal (default=1).

  • joint (list[int]) – The joints to apply the step signal to (default=all).

  • axis (int) – The axis to apply the step signal to (default=None).

  • delay (float) – The delay before applying the step signal (default=0).

Returns:

None