Implementation:ARISE Initiative Robosuite MjcfUtils
| Knowledge Sources | |
|---|---|
| Domains | Robotics, MJCF Modeling |
| Last Updated | 2026-02-15 07:00 GMT |
Overview
The mjcf_utils module provides utility functions and classes for constructing, modifying, and querying MuJoCo MJCF XML models, including element creation, prefix management, material handling, model scaling, and XML tree traversal.
Description
This module is the primary toolkit for programmatic MJCF XML manipulation in robosuite. It defines the CustomMaterial class for procedurally generating texture/material combinations (supporting both named textures from a built-in library and RGBA-specified default textures), and a comprehensive set of functions for creating and manipulating XML elements.
The element creation functions -- new_element, new_joint, new_actuator, new_site, new_geom, new_body, and new_inertial -- produce ET.Element instances with properly formatted MuJoCo-compatible attributes, automatically converting arrays and numerics to space-separated strings. Helper functions array_to_string, string_to_array, and convert_to_string handle format conversion between Python types and MJCF attribute strings.
The prefix management function add_prefix recursively traverses an XML tree and prepends a naming prefix to all specified MuJoCo named attributes (joints, bodies, geoms, sites, etc.), which is essential for avoiding naming conflicts when composing multiple robot or object models. The add_material function assigns materials to visual geoms, and recolor_collision_geoms sets RGBA values on collision geometry groups.
The XML traversal functions -- find_elements, find_elements_by_substring, find_parent, sort_elements -- provide flexible searching and categorization of elements within the XML tree. The scaling functions (scale_mjcf_model and its component functions scale_geom_element, scale_mesh_element, scale_body_element, scale_joint_element, scale_site_element) apply uniform or per-axis scaling to all geometric and positional attributes in a model.
Usage
Use these utilities when building custom MJCF models programmatically, when composing multi-robot or multi-object scenes (via add_prefix), when assigning materials to visual elements, or when scaling object models. These functions are used extensively by robosuite's model assembly pipeline.
Code Reference
Source Location
- Repository: ARISE_Initiative_Robosuite
- File: robosuite/utils/mjcf_utils.py
Signature
class CustomMaterial(object):
def __init__(self, texture, tex_name, mat_name,
tex_attrib=None, mat_attrib=None, shared=False): ...
def xml_path_completion(xml_path, root=None) -> str: ...
def array_to_string(array) -> str: ...
def string_to_array(string) -> np.array: ...
def new_element(tag, name, **kwargs) -> ET.Element: ...
def new_joint(name, **kwargs) -> ET.Element: ...
def new_site(name, rgba=RED, pos=(0,0,0), size=(0.005,), **kwargs) -> ET.Element: ...
def new_geom(name, type, size, pos=(0,0,0), group=0, **kwargs) -> ET.Element: ...
def new_body(name, pos=(0,0,0), **kwargs) -> ET.Element: ...
def add_prefix(root, prefix, tags="default", attribs="default", exclude=None): ...
def find_elements(root, tags, attribs=None, return_first=True): ...
def sort_elements(root, parent=None, element_filter=None, _elements_dict=None) -> dict: ...
def scale_mjcf_model(obj, asset_root, scale, get_elements_func,
worldbody=None, scale_slide_joints=True) -> np.array: ...
Import
from robosuite.utils.mjcf_utils import (
CustomMaterial,
xml_path_completion,
array_to_string,
string_to_array,
new_element,
new_joint,
new_site,
new_geom,
new_body,
add_prefix,
find_elements,
sort_elements,
scale_mjcf_model,
)
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| texture (CustomMaterial) | str or 4-array or None | Yes | Texture name from ALL_TEXTURES, RGBA tuple, or None |
| tex_name | str | Yes | Name for the texture reference |
| mat_name | str | Yes | Name for the material reference |
| root (add_prefix) | ET.Element | Yes | Root XML element tree to modify |
| prefix | str | Yes | Prefix string to prepend to named attributes |
| root (find_elements) | ET.Element | Yes | Root XML element tree to search |
| tags | str or list | Yes | Tag name(s) to search for |
| attribs | dict or None | No | Attribute key-value pairs to match |
| scale (scale_mjcf_model) | float or 3-array | Yes | Scale factor (uniform scalar or per-axis [sx, sy, sz]) |
Outputs
| Name | Type | Description |
|---|---|---|
| CustomMaterial instance | CustomMaterial | Material object with tex_attrib and mat_attrib dicts |
| new_* functions | ET.Element | New XML element with formatted attributes |
| find_elements | ET.Element or list or None | Matching element(s), or None if no match |
| sort_elements | dict | Dictionary mapping filter keys to lists of elements |
| scale_mjcf_model | np.array | Normalized 3-element scale array that was applied |
Usage Examples
import xml.etree.ElementTree as ET
from robosuite.utils.mjcf_utils import (
CustomMaterial, new_body, new_geom, new_joint, new_site,
add_prefix, find_elements, array_to_string, string_to_array,
)
# Create a custom material with a named texture
wood_material = CustomMaterial(
texture="WoodDark",
tex_name="dark_wood_tex",
mat_name="dark_wood_mat",
tex_attrib={"type": "cube"},
mat_attrib={"shininess": "0.1"},
)
# Create XML elements
body = new_body("my_body", pos=(0.5, 0.0, 1.0))
geom = new_geom("my_geom", type="box", size=(0.1, 0.1, 0.1), rgba=(1, 0, 0, 1))
joint = new_joint("my_joint", type="hinge", axis=(0, 0, 1))
site = new_site("my_site", pos=(0, 0, 0.1))
body.append(geom)
body.append(joint)
body.append(site)
# Add a naming prefix to avoid collisions
add_prefix(body, prefix="robot0_")
# Find all geoms in the tree
geoms = find_elements(body, tags="geom", return_first=False)
# Convert between arrays and strings
pos_str = array_to_string([0.5, 0.0, 1.0]) # "0.5 0.0 1.0"
pos_array = string_to_array("0.5 0.0 1.0") # np.array([0.5, 0.0, 1.0])