Implementation:Google deepmind Dm control MJCF RootElement Parser

Metadata
Knowledge Sources	dm_control
Domains	Physics Simulation, Robotics, Model Authoring
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete tool for creating or parsing MJCF physics model definitions into a mutable in-memory object tree using the RootElement constructor and the from_path / from_xml_string parser functions.

Description

The MJCF RootElement Parser provides three primary entry points for obtaining an MJCF root element:

mjcf.RootElement(model, **kwargs) -- Instantiates an empty root element. The model parameter sets the model name (defaults to 'unnamed_model'). Optional keyword arguments include model_dir (base directory for resolving asset paths) and assets (a dictionary of pre-loaded binary assets). Internally, the constructor creates a NameScope, initialises all non-repeated child elements defined by the MJCF schema, and sets up the attribute storage.

mjcf.from_path(path, escape_separators=False, ...) -- Reads an XML file from disk, extracts the model directory from the file path, parses the XML tree, recursively processes <include> directives, constructs the element tree, and optionally resolves cross-references.

mjcf.from_xml_string(xml_string, escape_separators=False, ...) -- Identical to from_path but accepts an XML byte or unicode string instead of a file path. Useful when models are stored in memory (e.g., fetched from a database or generated dynamically).

All three paths converge on the internal _parse function, which validates the root XML tag, handles <include> merges via include_copy, and calls resolve_references to convert string references into live element pointers.

Usage

Use RootElement when building a model from scratch. Use from_path or from_xml_string when loading existing MJCF assets for inspection, modification, or composition with other models.

Code Reference

Property	Value
Source Location	`dm_control/mjcf/element.py:L1212-1324` (RootElement), `dm_control/mjcf/parser.py:L31-283` (parsers)
Signature (RootElement)	`RootElement(model=None, model_dir=, assets=None)`
Signature (from_path)	`from_path(path, escape_separators=False, resolve_references=True, assets=None)`
Signature (from_xml_string)	`from_xml_string(xml_string, escape_separators=False, model_dir=, resolve_references=True, assets=None)`
Import	`from dm_control import mjcf`

I/O Contract

Inputs (RootElement):

Parameter	Type	Description
`model`	`str` or `None`	Model name; defaults to `'unnamed_model'` if `None`.
`model_dir`	`str`	Base directory for resolving relative asset file paths.
`assets`	`dict` or `None`	Pre-loaded assets as `{filename: bytestring}`.

Inputs (from_path):

Parameter	Type	Description
`path`	`str`	File system path to the XML file.
`escape_separators`	`bool`	Whether to escape `/` characters in identifiers.
`resolve_references`	`bool`	Whether to resolve string references to element objects.
`assets`	`dict` or `None`	Pre-loaded assets dictionary.

Inputs (from_xml_string):

Parameter	Type	Description
`xml_string`	`str` or `bytes`	Raw XML content.
`escape_separators`	`bool`	Whether to escape `/` characters in identifiers.
`model_dir`	`str`	Base directory for resolving relative asset file paths.
`resolve_references`	`bool`	Whether to resolve string references to element objects.
`assets`	`dict` or `None`	Pre-loaded assets dictionary.

Outputs:

Output	Type	Description
return value	`mjcf.RootElement`	The root of the MJCF object model tree; all children are accessible as attributes or via `find`/`find_all`.

Usage Examples

from dm_control import mjcf

# 1. Create an empty model from scratch
model = mjcf.RootElement(model='my_robot')
print(model.model)  # 'my_robot'
print(model.to_xml_string())
# <mujoco model="my_robot"> ... </mujoco>

# 2. Parse a model from a file path
model = mjcf.from_path('/path/to/robot.xml')
print(model.model)
# The worldbody and all children are now accessible:
bodies = model.find_all('body')

# 3. Parse a model from an XML string
xml = b'<mujoco model="box"><worldbody><body name="b1"><geom type="box" size="0.1 0.1 0.1"/></body></worldbody></mujoco>'
model = mjcf.from_xml_string(xml)
geom = model.find('geom', 'b1')  # None, since 'b1' is in the body namespace
body = model.find('body', 'b1')
print(body.to_xml_string())

# 4. Create a model with pre-loaded assets
with open('/path/to/mesh.stl', 'rb') as f:
    mesh_bytes = f.read()
assets = {'mesh.stl': mesh_bytes}
model = mjcf.from_xml_string(xml_with_mesh, assets=assets)

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment