Principle:ARISE Initiative Robosuite MJCF Model Hierarchy
| Knowledge Sources | |
|---|---|
| Domains | Robotics, Simulation, Software Architecture |
| Last Updated | 2026-02-15 07:00 GMT |
Overview
The MJCF model hierarchy provides a two-tier class system for loading, manipulating, and composing MuJoCo XML model files, enabling programmatic scene construction through XML tree merging and prefix-based namespace management.
Description
Physics simulation environments are defined by model description files that specify bodies, joints, actuators, sensors, contacts, and visual assets. The MJCF (MuJoCo Format) model hierarchy provides a principled object-oriented layer over the raw XML representation, enabling programmatic construction and composition of complex simulation scenes from modular components (robots, objects, arenas, grippers).
The first tier, the XML wrapper, loads a MuJoCo XML file and exposes its major sections (worldbody, actuator, asset, sensor, tendon, equality, contact) as ElementTree nodes. It provides a merge operation that combines multiple XML models into a single scene by appending child bodies, actuators, assets, and other elements from one model into another. This merge operation handles asset deduplication (preventing duplicate texture or mesh definitions) and supports targeted body merging (appending bodies to a specific named body rather than the world root). Default class resolution is performed during loading, replacing class-based attribute inheritance with explicit inline attributes for portability.
The second tier, the model abstraction, adds semantic structure on top of the XML wrapper. It defines a standard API for accessing a model's bodies, joints, actuators, sites, sensors, and geoms by name, with automatic namespace prefixing to prevent naming collisions when multiple instances of the same model appear in a scene. The prefix system prepends an instance identifier to all element names, ensuring that two identical robots can coexist without name conflicts. Models also expose geometric properties (bottom offset, top offset, horizontal radius) needed for spatial placement algorithms.
Usage
Apply the MJCF model hierarchy when building simulation environments by composing multiple model files. Use the XML wrapper for loading and merging raw MJCF files. Use the model abstraction when the component needs semantic access to its elements (e.g., a robot needs to know its joint names, a gripper needs its actuator names). The naming prefix system should be used whenever multiple instances of the same model type may appear in a scene.
Theoretical Basis
MJCF Model Hierarchy:
Tier 1 - MujocoXML (XML wrapper):
- __init__(fname):
Parse XML file into ElementTree
Extract: worldbody, actuator, asset, sensor, tendon, equality, contact
Resolve default classes (inline attribute replacement)
Resolve asset file paths to absolute paths
- merge(others, merge_body="default"):
For each other model:
Append other.worldbody children to self.worldbody (or named body)
Merge assets (with deduplication by name)
Append actuators, sensors, tendons, equalities, contacts
- get_model() -> MjModel:
Serialize XML tree to string
Compile via MuJoCo XML parser
- get_xml() -> str:
Serialize XML tree to string
Tier 2 - MujocoModel (semantic model):
- naming_prefix: "{idn}_" for namespace isolation
- correct_naming(names): prepend prefix to names
- Properties: name, root_body, bodies, joints, actuators,
sites, sensors, contact_geoms, visual_geoms,
bottom_offset, top_offset, horizontal_radius
Combined - MujocoXMLModel:
Inherits both MujocoXML and MujocoModel
On init: parse elements, sort into categories,
add naming prefix to all elements,
recolor collision geoms for visualization
Key design decisions:
- Default class inlining: MuJoCo's default class mechanism is resolved at load time, making each element self-contained. This prevents subtle bugs when merging models with different default class definitions.
- Asset path resolution: File paths in asset references are converted to absolute paths at load time, ensuring correctness after merge regardless of working directory.
- Naming prefix system: A per-instance prefix (e.g., "0_", "1_") prevents naming collisions and is automatically applied to all elements during construction.
- Asset deduplication: During merge, assets are checked by name and only added if not already present, preventing duplicate definitions that could cause compilation errors.
- Collision geom recoloring: Collision geoms (group 0) are automatically colored for visual debugging, distinct from visual geoms (group 1).