xacrodoc

xacrodoc is a tool for compiling xacro files to plain URDF files or Mujoco MJCF files from within Python code or via the command line. It is fully functional whether ROS is installed on the system or not.

Why?

Compared to the regular xacro package, xacrodoc allows you to:

• Conveniently convert xacro files to URDF or Mujoco MJCF files without a ROS installation (this includes converting plain URDF to MJCF).
• Programmatically compose multiple xacro files and apply substitution arguments to build a flexible URDF model directly in your code. This allows you to avoid the clutter of redundant compiled raw URDFs and only keep the xacro source files.
• Seamlessly obtain URDF strings and (temporary) URDF file paths as needed. For example, many libraries (such as Pinocchio) accept a URDF string to build a model, but others (like PyBullet) only load URDFs directly from file paths.
• Easily copy assets like meshes to a single directory and have fine-grained control over file protocols and absolute vs. relative paths, if desired.

Documentation

Usage information and examples are provided in this README. The package's full API reference can be found here.

Installation

xacrodoc requires at least Python 3.8. Note that ROS does not need to be installed on the system, but xacrodoc will also use its infrastructure to look for packages if it is available.

Command Line Tool

It is recommended to install the command line tool into an isolated environment using uv:

uv tool install xacrodoc

# for conversion to MJCF files, use:
uv tool install "xacrodoc[mujoco]"

or pipx:

pipx install xacrodoc
# or
pipx install "xacrodoc[mujoco]"

Python Library

The library can be installed from pip:

pip install xacrodoc

# or to also include conversion to MJCF files:
pip install "xacrodoc[mujoco]"

or from source:

git clone --recurse-submodules https://github.com/adamheins/xacrodoc
cd xacrodoc
pip install .

Command Line Usage

In addition to the Python API described below, this package also includes a xacrodoc command line tool. It is similar to xacro but provides additional options; notably, directories in which to search for packages can be provided manually. Examples:

# compile and print to stdout
xacrodoc input.urdf.xacro

# compile and output to provided output file
xacrodoc input.urdf.xacro -o output.urdf

# provide directories in which to look for packages referenced in
# input.urdf.xacro (the -d (--pkg-dir) flag is needed before each one to
# disambiguate from substitution arguments); a common use-case would be
# providing the path to catkin workspaces
xacrodoc input.urdf.xacro -d ~/my_pkg_dir -d ~/my_other_pkg_dir

# alternatively, package name/path mappings can be directly supplied using the
# -p (--pkg-path) flag; := is used to separate the name and path:
xacrodoc input.urdf.xacro -p my_pkg:=~/path/to/my_pkg -p other_pkg:=/home/foo/packages/other_pkg

# substitution arguments also use := notation, like xacro
xacrodoc input.urdf.xacro mass:=1

# you can also remove file:// protocols prefixed to asset paths with
# -s (--strip-protocols) or convert paths from absolute to relative using
# -r (--relative-paths)
xacrodoc input.urdf.xacro -s -r output.urdf

# alternatively, convert to MJCF (requires Mujoco)
# the -c (--copy-assets-to) option with a directory name is required when 
# converting to MJCF; it copies all assets to that directory and updates their
# file paths (-c is optional when converting to URDF)
# relative file paths are always used when converting to MJCF
xacrodoc input.urdf.xacro --mjcf -c assets -o output.xml

Python Library Usage

Basic

A basic use-case of compiling a URDF from a xacro file:

import os
from xacrodoc import XacroDoc

doc = XacroDoc.from_file("robot.urdf.xacro")

# or relative to a ROS package
# e.g., for a file located at some_ros_package/urdf/robot.urdf.xacro:
doc = XacroDoc.from_package_file("some_ros_package", "urdf/robot.urdf.xacro")

# convert to a string of URDF
urdf_str = doc.to_urdf_string()

# or write to a file
doc.to_urdf_file("robot.urdf")

# or just work with a temp file
# this is useful for working with libraries that expect a URDF *file* (rather
# than a string)
with doc.temp_urdf_file_path() as path:
  # do stuff with URDF file located at `path`...
  # file is cleaned up once context manager is exited

# you can also manage the temp file yourself if you don't want to clean it up
# right away
path = doc.to_temp_urdf_file()
# ...do stuff with path...

# manually delete the temp file
os.remove(path)

Finding ROS packages

xacro files often make use of $(find <pkg>) directives to resolve paths relative to a given ROS package. If ROS is installed on the system, xacrodoc automatically looks for ROS packages using the usual ROS infrastructure. If not, or if you are working with packages outside of a ROS workspace, you'll need to tell xacrodoc where to find packages. There are a few ways to do this:

import xacrodoc as xd

# `from_file` automatically resolves packages by looking in each parent
# directory of the given path to check for required ROS packages (as marked by
# a package.xml file)
doc = xd.XacroDoc.from_file("robot.urdf.xacro")

# if you want to disable this, pass `walk_up=False`:
doc = xd.XacroDoc.from_file("robot.urdf.xacro", walk_up=False)

# we can also tell xacrodoc to walk up a directory tree manually
xd.packages.walk_up_from("some/other/path")

# or we can give paths to directories to search for packages
# packages can be located multiple levels deep from the specified directories,
# just like in a ROS workspace - the same package search logic is used (since
# we actually use rospkg under the hood)
xd.packages.look_in(["somewhere/I/keep/packages", "another/directory/with/packages"])

# you can bypass ROS conventions entirely by directly providing a dict of
# package names and paths; no package.xml is required to identify packages in
# this case
xd.packages.update_package_cache({"my_package": "path/to/my_package"})

Multiple URDFs

We can also build a URDF programmatically from multiple xacro files:

import xacrodoc as xd

# setup where to look for packages, if needed; for example:
xd.packages.look_in(["somewhere/I/keep/packages"])

# specify files to compose (using xacro include directives)
includes = ["robot_base.urdf.xacro", "robot_arm.urdf.xacro", "tool.urdf.xacro"]
doc = xd.XacroDoc.from_includes(includes)

# includes can also use $(find ...) directives:
includes = [
    "$(find my_ros_package)/urdf/robot_base.urdf.xacro",
    "$(find another_ros_package)/urdf/robot_arm.urdf.xacro",
    "tool.urdf.xacro"
]
doc = xd.XacroDoc.from_includes(includes)

Substitution arguments

We can also pass in substitution arguments to xacro files. For example, suppose our file robot.urdf.xacro contains the directive <xacro:arg name="mass" default="1"/>. On the command line, we could write

xacro robot_base.urdf.xacro -o robot_base.urdf mass:=2

to set the mass value. Programmatically, we do

from xacrodoc import XacroDoc

doc = XacroDoc.from_file("robot.urdf.xacro", subargs={"mass": "2"})

Resolving file names with respect to packages

One feature of URDF (not just xacro files) is that file names (e.g., for meshes) can be specified relative to a package by using

package://<pkg>/relative/path/to/mesh

syntax, which depends on ROS and is not supported by other non-ROS tools. xacrodoc automatically expands these paths out to full absolute paths, e.g.,

file:///abs/path/to/mesh

but this can be disabled by passing resolve_packages=False to the XacroDoc constructor methods.

Additional file name manipulation

As just described, URDFs typically prefix asset file names with a protocol, either file:// or package://, and the resolution of the latter to the former can be controlled using the resolve_packages parameter.

For some applications, one may wish to eliminate the protocol prefixes entirely. This can be done by passing use_protocols=False to the XacroDoc.to_urdf_string or XacroDoc.to_urdf_file methods, which will strip away any file:// protocols (it doesn't make sense to strip an unresolved package:// prefix, an error is raised if one is found when use_protocols=False). Conversely, if use_protocols=True (the default), then a file:// protocol prefix is added to any file names without a prefix and package:// prefixes are left unchanged. Note that protocols are always stripped when converted to MJCF.

In addition, one can control whether resolved file paths are absolute or relative. By default, URDF works with absolute paths, but many applications support relative paths, which are also more portable. When converting to a file using the XacroDoc.to_urdf_file method, passing relative_paths=True will make all file names relative to the output file location. When converting to a string using XacroDoc.to_urdf_string, you can pass a path to paths_relative_to to make all file names relative to that path in the resulting URDF string.

When loading a document that has relative file names, they are resolved relative to the XacroDoc.rootdir attribute if it is not None. When the document is loaded from a file using XacroDoc.from_file or XacroDoc.from_package_file, rootdir is automatically set to be that file's parent directory. When the document is loaded using XacroDoc.from_string or XacroDoc.from_includes, rootdir can be specified as an argument.

Conversion to MJCF format

Mujoco has basic support for URDFs, but natively uses its own MJCF XML format. If you want to use Mujoco, you probably