API Reference

Core Classes

MJControlWrapper

class dexrobot_mujoco.utils.mj_control_utils.MJControlWrapper(model_path, mesh_dir=None, renderer_dimension=None, seed=0)

Bases: object

Wrapper for communicating with Mujoco simulator.

__init__(model_path, mesh_dir=None, renderer_dimension=None, seed=0)

Initialize the Mujoco control wrapper.

Parameters:

• model_path (str) – The path to the Mujoco model XML file.

• mesh_dir (str) – The path to the directory containing the mesh files. Use None for default mesh relative to XML files.

• renderer_dimension (tuple or None) – (width, height) of renderer, if image rendering is needed. When None, rendering is disabled.

reset_safe()

enable_infinite_rotation(act_name_re)

Modify the model to allow infinite rotation for the specified joint actuators.

Parameters:

act_name_re (str) – The regular expression for the actuator names that should allow infinite rotation.

launch_viewer(viewer_type, show_ui=True)

Launch the Mujoco viewer.

Parameters:

• viewer_type (str) – The type of the viewer to launch. Can be “active” or “passive”.

• show_ui (bool) – Whether to show the left and right UI in the viewer.

step(*args, **kwargs)

send_control(*args, **kwargs)

set_control(act_name, value)

Set the control signal to the specified actuator. Used for initialization.

Parameters:

• act_name (str) – The name of the actuator.

• value (float) – The control signal value.

get_joint_id(joint_name)

Get the ID of the specified joint.

Parameters:

joint_name (str) – The name of the joint.

Returns:

The joint ID.

Return type:

int

get_link_id(link_name)

Get the ID of the specified link.

Parameters:

link_name (str) – The name of the link.

Returns:

The link ID.

Return type:

int

get_qpos_addr(joint_name)

Get the address of the specified joint position.

Parameters:

joint_name (str) – The name of the joint.

Returns:

The address of the joint position in the qpos array.

Return type:

int

get_qvel_addr(joint_name)

Get the address of the specified joint velocity.

Parameters:

joint_name (str) – The name of the joint.

Returns:

The address of the joint velocity in the qvel array.

Return type:

int

set_qpos(joint_name, value)

Set the position of the specified joint.

Parameters:

• joint_name (str) – The name of the joint.

• value (float) – The position value.

get_qpos(*args, **kwargs)

get_qvel(*args, **kwargs)

get_qpos_freejoint(joint_name)

Get the position of the specified free joint.

Parameters:

joint_name (str) – The name of the free joint.

get_qvel_freejoint(joint_name)

Get the velocity of the specified free joint.

Parameters:

joint_name (str) – The name of the free joint.

set_qpos_freejoint(joint_name, value)

Set the position of the specified free joint.

Parameters:

• joint_name (str) – The name of the free joint.

• value (np.array) – The position value.

set_qvel_freejoint(joint_name, value)

Set the velocity of the specified free joint.

Parameters:

joint_name (str) – The name of the free joint.

set_site_xpos(site_name, pos)

Set the position of the specified site.

Parameters:

• site_name (str) – The name of the site.

• pos (np.array) – The position value.

get_site_xpos(*args, **kwargs)

get_link_pose(*args, **kwargs)

parse_yaml(yaml_path)

Parse the YAML file containing the configuration.

Parameters:

yaml_path (str) – The path to the YAML file.

set_initial_values()

Set the initial values of the simulation.

set_view_angle(lookat, distance, elevation, azimuth)

Set the view angle of the camera.

Parameters:

• lookat (list) – The lookat point [x, y, z].

• distance (float) – The distance from the camera to the lookat point.

• elevation (float) – The elevation angle in degrees.

• azimuth (float) – The azimuth angle in degrees.

render_frame()

Render a frame using the camera.

key_callback(keycode)

Callback function for handling key presses in the viewer.

Parameters:

keycode (int) – The key code of the pressed key.

reset_simulation()

Reset the simulation.

MJControlVRWrapper

class dexrobot_mujoco.utils.mj_control_vr_utils.MJControlVRWrapper(model_path, enable_vr=True, **kwargs)

Bases: MJControlWrapper

__init__(model_path, enable_vr=True, **kwargs)

Initialize the Mujoco control wrapper.

Parameters:

• model_path (str) – The path to the Mujoco model XML file.

• mesh_dir (str) – The path to the directory containing the mesh files. Use None for default mesh relative to XML files.

• renderer_dimension (tuple or None) – (width, height) of renderer, if image rendering is needed. When None, rendering is disabled.

update_vr_images()

sync_camera_pose_for_vr(offset=0.1)

Sync the camera pose for VR.

start_simulation()

Starts the simulation in a separate thread.

run_simulation()

Simulation loop.

stop_simulation()

Stops the simulation.

generate_encoded_frames()

Generate encoded frames for streaming.

ROS Integration

MujocoJointController

Utility Functions

MJCF Utilities

dexrobot_mujoco.utils.mjcf_utils.load_meshes(mesh_dir)

Load all mesh files in the given directory and return them as a dictionary.

Parameters:

mesh_dir (str) – The directory containing the mesh files.

Returns:

A dictionary mapping the filenames to the contents of the mesh files.

Return type:

dict[str, bytes]

dexrobot_mujoco.utils.mjcf_utils.urdf2mjcf(urdf_path, mjcf_dir, mesh_dir=None)

Load a URDF file and save it to an MJCF XML file.

Parameters:

• urdf_path (str) – The path to the URDF file.

• mjcf_dir (str) – The directory to save the output MJCF file.

• mesh_dir (str, optional) – The directory containing the mesh files. When not provided, the default search rule of MuJoCo is used.

dexrobot_mujoco.utils.mjcf_utils.get_joint_names(xml_path)

Get the names of all joints in the MJCF XML file.

Parameters:

xml_path (str) – The path to the MJCF XML file.

Returns:

A list of joint names.

Return type:

list[str]

dexrobot_mujoco.utils.mjcf_utils.get_body_names(xml_path)

Get the names of all bodies in the MJCF XML file.

Parameters:

xml_path (str) – The path to the MJCF XML file.

Returns:

A list of body names.

Return type:

list[str]

dexrobot_mujoco.utils.mjcf_utils.add_position_actuators(xml_path, actuator_info)

Add position actuators to the given MJCF XML file.

Parameters:

• xml_path (str) – The path to the MJCF XML file.

• actuator_info (dict) – Dictionary containing the actuator information. key (str): Regular expression for a group of joints. value (dict): A set of properties to add to the <position> element.

dexrobot_mujoco.utils.mjcf_utils.add_touch_sensors(xml_path, sensor_info)

Add touch sensors to the given MJCF XML file.

Parameters:

• xml_path (str) – The path to the MJCF XML file.

• sensor_info (dict) – Dictionary containing the sensor information. key (str): The sensor name. value (dict): A set of properties to add to the <sensor> element.

dexrobot_mujoco.utils.mjcf_utils.add_sites(xml_file_path, site_info)

Add sites to specific bodies in the MJCF XML file.

Parameters:

• xml_file_path (str) – Path to the input/output MJCF XML file.

• site_info (dict) – Dictionary containing the site information. key (str): The body name to add the site to. value (dict): A set of properties to add to the <site> element.

Returns:

None

dexrobot_mujoco.utils.mjcf_utils.apply_defaults(mjcf_xml_path, defaults_xml_path)

Apply default values / options from the given defaults XML file to the given MJCF XML file.

Parameters:

• mjcf_xml_path (str) – The path to the MJCF XML file.

• defaults_xml_path (str) – The path to the defaults XML file.

dexrobot_mujoco.utils.mjcf_utils.merge_xml_files(xml_dict, output_xml_path, model_name)

Merges multiple MuJoCo XML files into a single scene file.

This function combines multiple MuJoCo XML model files into one unified scene file, preserving key elements like assets, bodies, actuators, sensors etc. Each model can be positioned and articulated differently in the combined scene.

Parameters:

• xml_dict (dict) –

  Dictionary mapping XML file paths to positioning attributes. Each entry should have: - ‘pos’: tuple of (x,y,z) coordinates - ‘quat’: tuple of (w,x,y,z) quaternion rotation - ‘articulation_method’: str, either ‘fixed’ or ‘free’

  ’model1.xml’: {‘pos’: (0,0,0), ‘quat’: (1,0,0,0), ‘articulation_method’: ‘fixed’}, ‘model2.xml’: {‘pos’: (1,1,0), ‘quat’: (0,1,0,0), ‘articulation_method’: ‘free’}

• output_xml_path (str) – File path where the combined XML will be saved.

• model_name (str) – Name to be given to the combined model.

Notes

The function merges the following XML elements:

• compiler, option, default (taken from first file only)

• asset (merged from all files)

• worldbody (merged with specified positions and articulations)

• actuator (merged from all files)

• sensor (merged from all files if present)

• tendon (merged from all files if present)

• contact (merged from all files if present)

dexrobot_mujoco.utils.mjcf_utils.articulate(parent_xml_path, child_xml_path, link_name, output_xml_path, pos='0 0 0', quat='1 0 0 0')

Articulates a child model to a parent model at the specified link. Uses visual, option, default and size settings from the child model. Handles mesh paths considering both explicit paths and meshdir compiler settings.

Parameters:

• parent_xml_path (str) – Path to the parent MJCF XML file.

• child_xml_path (str) – Path to the child MJCF XML file.

• link_name (str) – Name of the link in the parent model to which the child model should be articulated.

• output_xml_path (str) – Path to the output articulated MJCF XML file.

• pos (str) – Position of the child model.

• quat (str) – Quaternion orientation of the child model.

dexrobot_mujoco.utils.mjcf_utils.add_trunk_body(xml_file_path, name=None, pos='0 0 0', quat='1 0 0 0')

Adds a top-level “trunk” element below the “worldbody” element.

Makes every original child of “worldbody” a child of “trunk” instead.

Parameters:

• xml_file_path – Path to the input/output MJCF XML file.

• name – Name of the “trunk” body. Defaults to f”{model_name}_trunk”.

• pos – Position of the “trunk” body. Defaults to “0 0 0”.

• quat – Quaternion orientation of the “trunk” body. Defaults to “1 0 0 0”.

dexrobot_mujoco.utils.mjcf_utils.exclude_self_collisions(xml_file_path, top_level_body_1=None, top_level_body_2=None, allowed_collision_pairs=[], additional_xml_file_path=None)

Excludes self-collisions pairwise between bodies under specified top-level bodies.

When one of the top-level bodies is None, excludes self-collisions within that top- level body. When both are None, excludes self-collisions within the first body directly under “worldbody”.

Parameters:

• xml_file_path – Path to the input/output MJCF XML file.

• top_level_body_1 – Name of the first top-level body.

• top_level_body_2 – Name of the second top-level body.

• allowed_collision_pairs – List of tuples of body names that should not be excluded from collisions. Each body name can be specified as a regular expression.

• additional_xml_file_path – Path to an additional XML file. Useful for dealing with bodies included by mujocoinclude. When specified, the second top- level body will be read from this additional XML file.

dexrobot_mujoco.utils.mjcf_utils.add_ground(xml_file_path, ground_name='ground', pos='0 0 0', size='1 1 0.1', rgba='0.8 0.8 1 1')

Adds a ground plane to the MJCF XML file.

Parameters:

• xml_file_path – Path to the input/output MJCF XML file.

• ground_name – Name of the ground plane geom. Defaults to ‘ground’.

• pos – Position of the ground plane. Defaults to “0 0 0”.

• size – Size of the ground plane. Defaults to “1 1 0.1”.

• rgba – RGBA color of the ground plane. Defaults to “0.8 0.8 1 1”.

dexrobot_mujoco.utils.mjcf_utils.extract_part(xml_file_path, output_path, part_name, body_name=None)

Extract a part from the MJCF XML file into a <mujocoinclude> file.

Parameters:

• xml_file_path (str) – Path to the input MJCF XML file.

• output_path (str) – Path to the output <mujocoinclude> file.

• part_name (str) – Name of the part to extract. Can be “asset”, “body”, “actuator”, “sensor”, “tendon”, or “contact”. When “body” is specified, the body_name argument must be provided.

• body_name (str or None) – Name of the body to extract when part_name is “body”.

Returns:

None

dexrobot_mujoco.utils.mjcf_utils.add_mesh_prefix(xml_file_path, prefix)

Add a prefix to all mesh filenames in the MJCF XML file.

Parameters:

• xml_file_path (str) – Path to the input/output MJCF XML file.

• prefix (str) – Prefix to add to all mesh filenames.

Returns:

None

dexrobot_mujoco.utils.mjcf_utils.update_geom_collisions(xml_file_path, collision_yaml_path)

Update collision properties of an MJCF XML file based on a YAML configuration.

This function: 1. Sets all existing geoms to non-collidable if they don’t have collision properties already set 2. Adds collidable geoms specified in the YAML file

Parameters:

• xml_file_path (str) – Path to the MJCF XML file

• collision_yaml_path (str) – Path to YAML file containing collidable geom specifications