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.
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.
Usage information and examples are provided in this README. The package's full function reference can be found here.
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.
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 .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]"
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)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"})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)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"})Finally, 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.
Mujoco has basic support for URDFs, but natively uses its own MJCF XML format.
If you want to use Mujoco, you probably want to convert any xacro file you have
to MJCF. When handling URDFs, Mujoco automatically converts absolute file paths
for assets like mesh files to relative paths. xacrodoc makes it easy to disable
this behaviour or automatically copy the assets to a local relative directory.
Note that mujoco must be installed and importable for this to work. For
example:
from xacrodoc import XacroDoc
doc = XacroDoc.from_file("input.urdf.xacro")
# keep absolute paths to assets
doc.to_mjcf_file("output.xml", strippath="false")
# copy all the referenced assets to the directory `assets` before conversion
# name collisions between assets with the same filename are automatically
# resolved by appending numbers as needed
doc.localize_assets("assets")
doc.to_mjcf_file("output.xml", strippath="true", meshdir="assets")
# if desired, one can also just produce an MJCF string:
xml = doc.to_mjcf_string()Both to_mjcf_file and to_mjcf_string accept keyword arguments corresponding
to the Mujoco URDF compiler
extension.
MJCF conversion is also available in the command line tool (see below).
In addition to the Python API described above, this packages 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 (-d flag is needed before each one to disambiguate from
# substitution arguments); a common usecase 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 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 or
# convert paths from absolute to relative using -r
xacrodoc input.urdf.xacro -s -r output.urdf
# convert to MJCF (requires Mujoco)
# the -c (short for --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.xmlTests use pytest. Some tests depend on additional submodules, which you can
clone using:
git submodule update --init --recursive
Then do:
cd tests
pytest .
To test the Mujoco MJCF features, you'll also need mujoco installed. To test
against different Python versions, use:
# for example
uv run --locked --isolated --extra mujoco --python=3.9 pytest
Docs are built with sphinx. In the docs directory, run
make html
and the open build/html/index.html.