scene_pymujoco

Scene utilities for interactive Python MuJoCo simulations.

This module provides the mujoco_scene helper used by RobotBlockSet MuJoCo backends to load models, manage the passive viewer, advance simulation in a worker thread, capture camera images, and reset simulation state.

class robotblockset.mujoco.scene_pymujoco.mujoco_scene(model_xml_file: str | None = None, model: mujoco.MjModel | None = None, show_camera: Sequence[str | int] | None = None, synchronized: bool = True, verbose: int = 0)[source]

Bases: rbs_object

MuJoCo scene manager with a passive viewer and background physics loop.

Attributes:

  • spec (Optional[mujoco.MjSpec]) – MuJoCo specification object when the scene was loaded from XML.

  • model (mujoco.MjModel) – Compiled MuJoCo model used by the scene.

  • data (mujoco.MjData) – Runtime MuJoCo data associated with model.

  • pause (bool) – Flag indicating whether simulation stepping is paused.

  • synchronized (bool) – Whether simulation stepping is synchronized to the model timestep.

  • viewer (Optional[mujoco.viewer.Handle]) – Passive MuJoCo viewer used for the main scene window.

  • show_camera (list[Union[str, int]]) – Requested auxiliary cameras. Auxiliary camera windows are not supported by this threaded backend.

  • visual_thread (Optional[threading.Thread]) – Background thread that advances the simulation.

Create a MuJoCo scene manager.

Parameters:

  • model_xml_file (str, optional) – Path to the MuJoCo XML model file to load.

  • model (mujoco.MjModel, optional) – Existing MuJoCo model to use instead of loading from XML.

  • show_camera (sequence of str or int, optional) – Auxiliary camera names or IDs. Additional GLFW windows are not supported by this threaded backend; use mj_capture_camera() or robotblockset.mujoco.scene_pymujoco_sim instead.

  • synchronized (bool, optional) – If True, synchronize stepping to the MuJoCo model timestep.

  • verbose (int, optional) – Verbosity level used for status messages.

Returns:

This constructor initializes the MuJoCo scene object in place.

Return type:

None

__init__(model_xml_file: str | None = None, model: mujoco.MjModel | None = None, show_camera: Sequence[str | int] | None = None, synchronized: bool = True, verbose: int = 0) → None[source]

Create a MuJoCo scene manager.

Parameters:

  • model_xml_file (str, optional) – Path to the MuJoCo XML model file to load.

  • model (mujoco.MjModel, optional) – Existing MuJoCo model to use instead of loading from XML.

  • show_camera (sequence of str or int, optional) – Auxiliary camera names or IDs. Additional GLFW windows are not supported by this threaded backend; use mj_capture_camera() or robotblockset.mujoco.scene_pymujoco_sim instead.

  • synchronized (bool, optional) – If True, synchronize stepping to the MuJoCo model timestep.

  • verbose (int, optional) – Verbosity level used for status messages.

Returns:

This constructor initializes the MuJoCo scene object in place.

Return type:

None

start_simulation() → None[source]

Start the passive viewer and simulation thread.

Returns:

This method launches the viewer on the caller thread and starts the background physics loop.

Return type:

None

Raises:

RuntimeError – If the viewer or simulation thread cannot be started.

stop_simulation() → None[source]

Stop the visualization thread and close viewer windows.

Returns:

This method stops the background render loop.

Return type:

None

restart_simulation() → None[source]

Restart the viewer thread and recompile the model when possible.

Returns:

This method restarts visualization using the current scene state.

Return type:

None

render() → None[source]

Advance the simulation and synchronize the passive viewer.

Viewer initialization is performed by start_simulation() on the caller thread. This worker owns physics stepping but never calls GLFW directly.

Return type:

None

lock() → ContextManager[object][source]

Return the lock protecting the shared MuJoCo model and data.

Code that directly reads or modifies model or data while the simulation thread is running should hold this lock.

Returns:

Reentrant scene-data lock.

Return type:

ContextManager[object]

mj_pause() → None[source]

Pause simulation stepping.

Returns:

This method sets the internal pause flag.

Return type:

None

mj_run() → None[source]

Resume simulation stepping.

Returns:

This method clears the internal pause flag.

Return type:

None

mj_wait(wait: float = 0) → None[source]

Wait for a specified duration.

Parameters:

wait (float, optional) – Amount of simulated time (in seconds) to advance.

Returns:

This method blocks until the requested amount of simulated time has elapsed.

Return type:

None

mj_reset(keyframe: int | None = None) → None[source]

Resets the simulation state to its initial state, or to a specified keyframe.

Parameters:

keyframe (int, optional) – The index of the keyframe to reset to. If None, the simulation is reset to the initial state.

Return type:

None

mj_capture_camera(camera: int | str = -1, scene_option: mujoco.MjvOption | None = None, **kwargs: object) → ndarray[source]

Captures an image from a specified camera in the simulation.

Parameters:

  • camera (Union[int, str], optional) – The ID or name of the camera to capture. Default is -1, which captures the default camera.

  • scene_option (mujoco.MjvOption, optional) – Rendering options to customize the scene appearance. Default is None.

  • **kwargs (object) – Additional keyword arguments passed to mujoco.Renderer.

Returns:

The rendered image as a NumPy array (RGB format).

Return type:

np.ndarray

Classes

mujoco_scene([model_xml_file, model, ...])

MuJoCo scene manager with a passive viewer and background physics loop.