Implementation:ARISE Initiative Robosuite BindingUtils

Knowledge Sources	ARISE_Initiative_Robosuite
Domains	Robotics, Physics Simulation
Last Updated	2026-02-15 07:00 GMT

Overview

The binding_utils module provides wrapper classes (MjSim, MjModel, MjData, MjRenderContext, MjSimState) that adapt the DeepMind MuJoCo Python bindings to replicate the legacy mujoco-py API used throughout robosuite.

Description

This module bridges the gap between the modern DeepMind mujoco Python bindings and the older mujoco-py API that robosuite was originally built upon. It provides wrapper classes that expose a mujoco-py-compatible interface while internally delegating to the native MuJoCo bindings.

The MjModel class wraps mujoco.MjModel using a metaclass (_MjModelMeta) that dynamically creates property delegates for all non-private attributes. It additionally provides name-to-id and id-to-name mapping methods for bodies, joints, geoms, sites, cameras, lights, actuators, sensors, tendons, and meshes. It also implements get_joint_qpos_addr and get_joint_qvel_addr methods that return joint addresses compatible with the mujoco-py convention (returning either an integer for 1-DOF joints or a (start, end) tuple for multi-DOF joints).

The MjData class similarly wraps mujoco.MjData with a metaclass and provides query methods for body positions, rotations, Jacobians, velocities, geom/site/camera/light/sensor data, and mocap body manipulation. The MjSim class composes MjModel and MjData and provides high-level simulation methods: reset, forward, step, step1, step2, render, and state get/set operations. The MjRenderContext class manages OpenGL rendering contexts with support for offscreen rendering, segmentation, and texture uploading.

Usage

These classes are used internally by robosuite to interface with MuJoCo. They are instantiated by the environment during simulation setup. Use MjSim when you need to create a standalone simulation from an XML string or file, and access sim.model and sim.data for model queries and state manipulation.

Code Reference

Source Location

Repository: ARISE_Initiative_Robosuite
File: robosuite/utils/binding_utils.py

Signature

class MjSim:
    def __init__(self, model): ...
    @classmethod
    def from_xml_string(cls, xml) -> "MjSim": ...
    @classmethod
    def from_xml_file(cls, xml_file) -> "MjSim": ...
    def reset(self): ...
    def forward(self): ...
    def step(self, with_udd=True): ...
    def render(self, width=None, height=None, *, camera_name=None, depth=False,
               mode="offscreen", device_id=-1, segmentation=False): ...
    def get_state(self) -> MjSimState: ...
    def set_state(self, value: MjSimState): ...
    def free(self): ...

class MjModel(metaclass=_MjModelMeta):
    def __init__(self, model_ptr): ...
    def joint_name2id(self, name) -> int: ...
    def body_name2id(self, name) -> int: ...
    def site_name2id(self, name) -> int: ...
    def camera_name2id(self, name) -> int: ...
    def get_joint_qpos_addr(self, name): ...
    def get_joint_qvel_addr(self, name): ...
    def get_xml(self) -> str: ...

class MjData(metaclass=_MjDataMeta):
    def __init__(self, model): ...
    def get_body_xpos(self, name) -> np.ndarray: ...
    def get_body_xquat(self, name) -> np.ndarray: ...
    def get_body_jacp(self, name) -> np.ndarray: ...
    def get_site_xpos(self, name) -> np.ndarray: ...
    def get_joint_qpos(self, name) -> np.ndarray: ...
    def set_joint_qpos(self, name, value): ...

class MjRenderContext:
    def __init__(self, sim, offscreen=True, device_id=-1, max_width=640, max_height=480): ...
    def render(self, width, height, camera_id=None, segmentation=False): ...
    def read_pixels(self, width, height, depth=False, segmentation=False): ...

class MjSimState:
    def __init__(self, time, qpos, qvel): ...
    @classmethod
    def from_flattened(cls, array, sim) -> "MjSimState": ...
    def flatten(self) -> np.ndarray: ...

Import

from robosuite.utils.binding_utils import MjSim, MjModel, MjData, MjRenderContext, MjSimState

I/O Contract

Inputs

Name	Type	Required	Description
model (MjSim)	mujoco.MjModel	Yes	A native MuJoCo model instance to wrap
xml (from_xml_string)	str	Yes	MuJoCo XML model definition as a string
xml_file (from_xml_file)	str	Yes	Path to a MuJoCo XML model file
camera_name (render)	str or None	No	Camera name for rendering. None uses free camera
width, height (render)	int	Yes	Dimensions of the rendered image in pixels
depth (render)	bool	No	Whether to return a depth buffer (default: False)
segmentation (render)	bool	No	Whether to return segmentation map (default: False)

Outputs

Name	Type	Description
sim.model	MjModel	Wrapped MuJoCo model with name-to-id mappings
sim.data	MjData	Wrapped MuJoCo data with query methods
render output	np.ndarray	RGB image array (H, W, 3) uint8, optionally with depth (float32)
MjSimState	MjSimState	Simulation state snapshot (time, qpos, qvel)

Usage Examples

from robosuite.utils.binding_utils import MjSim

# Create simulation from XML string
xml = open("path/to/model.xml").read()
sim = MjSim.from_xml_string(xml)

# Run simulation steps
sim.forward()
sim.step()

# Query body position by name
body_pos = sim.data.get_body_xpos("robot0_link7")

# Query joint position by name
joint_qpos = sim.data.get_joint_qpos("robot0_joint1")

# Get and set simulation state
state = sim.get_state()
sim.set_state(state)
sim.forward()

# Render an image (requires render context)
from robosuite.utils.binding_utils import MjRenderContextOffscreen
ctx = MjRenderContextOffscreen(sim, device_id=0)
img = sim.render(width=640, height=480, camera_name="frontview")

# Clean up
sim.free()

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment