Principle:ARISE Initiative Robosuite MJCF XML Manipulation
| Knowledge Sources | |
|---|---|
| Domains | Robotics, Simulation, XML Processing |
| Last Updated | 2026-02-15 07:00 GMT |
Overview
A comprehensive library of utility functions for creating, merging, modifying, and querying MuJoCo XML (MJCF) model element trees, enabling programmatic scene construction from composable model fragments.
Description
Physics simulation environments are typically described in XML model files that specify bodies, joints, actuators, sensors, materials, and other elements. Building complex scenes by hand-editing monolithic XML files is impractical when the scene must be composed from reusable components (robots, grippers, objects, arenas) that are each defined in separate files. An MJCF XML manipulation library provides the programmatic tools to load individual model fragments, merge them into a unified scene, resolve naming conflicts, and adjust physical properties at runtime.
The library addresses several core concerns. Element creation functions generate new XML elements (bodies, joints, geoms, actuators, sites, sensors) with properly formatted attributes, converting between Python data types (numpy arrays, lists, scalars) and the string representations required by XML. Element search functions traverse the XML tree to find elements by tag, attribute name, or attribute value, supporting both first-match and all-matches modes. Model merging combines two XML trees by appending the source's child elements (bodies, assets, actuators, sensors, etc.) to the corresponding sections of the target, with optional name prefixing to avoid collisions.
Additional utilities handle common operations such as converting arrays to space-separated strings, finding parent elements in the tree (which ElementTree does not natively support), recoloring collision geometries for visual debugging, scaling entire models by a factor, and resolving file paths relative to the simulation asset directory. Named attribute sets define which XML attributes should be treated as references that need prefixing during merges, ensuring that cross-references between joints, actuators, and sensors remain consistent.
Usage
Apply this principle whenever simulation scenes are built programmatically from reusable model components. It is essential for any framework that supports composable robots (arm + gripper + base), configurable arenas, and dynamically placed objects. Use the element creation functions when generating models from code, the merge functions when combining models, and the search functions when querying or modifying existing models.
Theoretical Basis
The library follows the Builder pattern for XML scene construction:
Scene Construction Pipeline:
1. Load base world XML (ground, lights, global settings)
2. Load arena XML, merge into world
3. Load robot XML, merge into world
4. Load gripper XML, merge into robot body subtree
5. Load object XMLs, merge into world
6. Compile final XML to MjModel
Name prefixing prevents collisions when merging multiple instances:
For robot with idn=0:
"joint1" -> "robot0_joint1"
"grip_site" -> "gripper0_right_grip_site"
MUJOCO_NAMED_ATTRIBUTES = {"name", "joint", "joint1", "joint2",
"mesh", "material", "texture", "geom", "geom1", "geom2", ...}
All attributes in this set are automatically prefixed during merge operations.
Element creation functions enforce consistent formatting:
new_joint(name, type, axis, damping, ...) -> ET.Element("joint")
new_geom(name, type, size, rgba, ...) -> ET.Element("geom")
new_body(name, pos, quat, ...) -> ET.Element("body")
new_actuator(joint, type, name, kp, ...) -> ET.Element("position"|"velocity"|"motor")
Array conversion bridges numpy and XML:
array_to_string(np.array([1.0, 2.0, 3.0])) -> "1.0 2.0 3.0"
string_to_array("1.0 2.0 3.0") -> np.array([1.0, 2.0, 3.0])
Collision color constants provide visual distinction:
ROBOT_COLLISION_COLOR = [0, 0.5, 0, 1] (green)
GRIPPER_COLLISION_COLOR = [0, 0, 0.5, 1] (blue)
MOUNT_COLLISION_COLOR = [0.5, 0.5, 0, 1] (yellow)
OBJECT_COLLISION_COLOR = [0.5, 0, 0, 1] (red)
ENVIRONMENT_COLLISION_COLOR = [0.5, 0.5, 0, 1] (yellow)