Implementation:ARISE Initiative Robosuite MujocoModel Base

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

Overview

The base module defines the foundational classes MujocoXML, MujocoModel, and MujocoXMLModel that form the core of robosuite's model abstraction hierarchy for loading, merging, and managing MuJoCo MJCF XML simulation models.

Description

This module provides three key classes that form the base of the robosuite model system. MujocoXML wraps Python's xml.etree.ElementTree to provide specialized XML handling for MuJoCo MJCF files. When initialized from a file path, it parses the XML tree and extracts references to critical sections such as worldbody, actuator, sensor, asset, tendon, equality, and contact. It also resolves file dependencies to absolute paths and replaces default classes inline, eliminating the need for a separate <default> section during model merging.

MujocoModel is an abstract base class that defines a standardized API for accessing model properties such as bodies, joints, actuators, sites, sensors, contact geoms, visual geoms, and spatial offsets (bottom_offset, top_offset, horizontal_radius). It also provides a naming prefix system via correct_naming() to prevent naming collisions when multiple model instances are loaded into the same simulation.

MujocoXMLModel inherits from both MujocoXML and MujocoModel, combining XML parsing with the standardized model API. It automatically parses the element tree to extract bodies, joints, actuators, geoms (separated into contact and visual groups), and sites. It applies naming prefixes to all elements and recolors collision geoms for visual clarity. This class serves as the direct parent for robot models and other XML-based simulation models.

Usage

Use MujocoXML when you need to load and merge raw MJCF XML files (e.g., arenas, world bases). Use MujocoModel as an interface contract when writing code that should work with any simulation model. Use MujocoXMLModel as the base class for XML-backed models that need automatic element parsing, prefix management, and collision geom recoloring -- this is the primary parent class for RobotModel and related model classes.

Code Reference

Source Location

Repository: ARISE_Initiative_Robosuite
File: robosuite/models/base.py

Signature

class MujocoXML(object):
    def __init__(self, fname)

class MujocoModel(object):
    # Abstract base -- no __init__ args

class MujocoXMLModel(MujocoXML, MujocoModel):
    def __init__(self, fname, idn=0)

Import

from robosuite.models.base import MujocoXML, MujocoModel, MujocoXMLModel

I/O Contract

Inputs

Name	Type	Required	Description
fname	str	Yes	Path to the MJCF XML file to load
idn	int or str	No	Unique identification number or string for this model instance (default: 0). Used for naming prefix generation.

Outputs

Name	Type	Description
name	str	Unique name for the model (class name + idn for MujocoXMLModel)
naming_prefix	str	Prefix string used to prevent naming collisions (e.g., "0_")
root_body	str	Name of the top-level body element in the XML tree
bodies	list of str	All body names in the model
joints	list of str	All joint names in the model
actuators	list of str	All actuator names in the model
sites	list of str	All site names in the model
sensors	list of str	All sensor names in the model
contact_geoms	list of str	Names of geoms used for collision detection (group 0)
visual_geoms	list of str	Names of geoms used for visual rendering (group 1)
bottom_offset	np.array	(dx, dy, dz) vector from root body to model bottom
top_offset	np.array	(dx, dy, dz) vector from root body to model top
horizontal_radius	float	Maximum radial distance from root body to any point

Usage Examples

# Load and merge two XML models
from robosuite.models.base import MujocoXML

world = MujocoXML("path/to/world.xml")
arena = MujocoXML("path/to/arena.xml")
world.merge(arena)

# Get the combined XML string
xml_string = world.get_xml()

# Generate a MuJoCo model from the combined XML
model = world.get_model(mode="mujoco")

# Using MujocoXMLModel for a named model with prefix support
from robosuite.models.base import MujocoXMLModel

class MyModel(MujocoXMLModel):
    def __init__(self, idn=0):
        super().__init__("path/to/model.xml", idn=idn)

    @property
    def _important_geoms(self):
        return {"body": ["main_geom"]}

    @property
    def _important_sites(self):
        return {}

    @property
    def _important_sensors(self):
        return {}

    @property
    def contact_geom_rgba(self):
        return [0, 1, 0, 0.3]

    @property
    def top_offset(self):
        return np.array([0, 0, 0.1])

    @property
    def horizontal_radius(self):
        return 0.2

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment