XacroDoc

The main interface for xacrodoc: use to compile xacro files to URDF or MJCF.

class xacrodoc.xacrodoc.XacroDoc(dom, rootdir=None)[source]

Convenience class to build URDF strings and files out of xacro components.

dom

The XML document representing the URDF.

Type:: xml.dom.minidom.Document

rootdir

Root directory to resolve relative asset filenames with respect to.

Type:: str or Path or None

count_assets()[source]

Count the number of unique asset files referenced in the document.

Returns:: The number of unique asset files.
Return type:: int

classmethod from_file(path, walk_up=True, **kwargs)[source]

Load the URDF document from a xacro or plain URDF file.

Parameters:

path (str or Path) – The path to the xacro file.
walk_up (bool) – If True, look for packages by walking up the directory tree from path.
**kwargs (dict) – Additional keyword arguments are passed to the .from_string constructor method.

classmethod from_includes(includes, name='robot', **kwargs)[source]

Build the URDF document from xacro includes.

Parameters:

includes (list) – A list of strings representing files to include in a new, otherwise empty, xacro file. Any string that can be used in a xacro include directive is valid, so look-ups like $(find package) are valid.
name (str) – The name attribute of the top-level robot tag.
**kwargs (dict) – Additional keyword arguments are passed to the .from_string method.

classmethod from_package_file(package_name, relative_path, **kwargs)[source]

Load the URDF document from a xacro file in a ROS package.

Parameters:

package_name (str) – The name of the ROS package.
relative_path (str or Path) – The path of the xacro file relative to the ROS package.
**kwargs (dict) – Additional keyword arguments are passed to the .from_file constructor method.

classmethod from_string(text, subargs=None, max_runs=10, resolve_packages=True, rootdir=None)[source]

Load the URDF document from a xacro or plain URDF string.

Parameters:

text (str) – The xacro text to compile into a URDF document.
subargs (dict or None) – Optional dict of substitution arguments; i.e., the values of <xacro:arg ...> directives. Equivalent to writing value:=foo on the command line.
max_runs (int) – The text is repeated compiled until a fixed point is reached; i.e., compilation of the text just returns the same text. max_runs is the maximum number of times compilation will be performed.
resolve_packages (bool) – If True, resolve package protocol URIs in the compiled URDF. Otherwise, they are left unchanged.
rootdir (str or Path or None) – Root directory to resolve relative asset filenames with respect to.

localize_assets(asset_dir, exist_ok=True)[source]

Copy all assets to a local directory and update all filenames in the document accordingly.

This is particularly useful when converting to MJCF format. The local assets are given unique names in the case of name collisions.

Parameters:

asset_dir (str or Path) – The path to the local directory where all the assets should be copied to.
exist_ok (bool) – If False, an error will be raised if asset_dir already exists. If True and asset_dir already exists, then any files in asset_dir could be overwritten.

temp_urdf_file_path(verbose=False)[source]

Get the context of a temporary URDF file path.

This is useful for temporarily writing the URDF to a file for consumption by other programs.

Parameters:: verbose (bool) – Set to True to print information about xacro compilation, False otherwise.

Examples

Use as a context manager:

with doc.temp_urdf_file_path() as path:
    load_file_from_path(path)

to_mjcf_file(path, **kwargs)[source]

Convert and write to a Mujoco MJCF XML file.

This requires the mujoco module to be installed and available for import.

Parameters:

path (str or Path) – The path to the MJCF XML file to be written.
**kwargs (dict) – All keyword arguments are passed as Mujoco compiler options; see https://mujoco.readthedocs.io/en/stable/modeling.html#curdf

to_mjcf_string(**kwargs)[source]

Convert to a string in Mujoco MJCF XML format.

This requires the mujoco module to be installed and available for import.

All kwargs are used as Mujoco compiler options; see https://mujoco.readthedocs.io/en/stable/modeling.html#curdf

Parameters:: **kwargs (dict) – All keyword arguments are passed as Mujoco compiler options; see https://mujoco.readthedocs.io/en/stable/modeling.html#curdf
Returns:: The string of XML.
Return type:: str

to_temp_urdf_file(verbose=False)[source]

Write the URDF to a temporary file.

Clean-up is left to the user. If you want the tempfile to be automatically deleted, use the context manager temp_urdf_file_path.

Parameters:: verbose (bool) – Set to True to print information about xacro compilation, False otherwise.
Returns:: The path to the temporary URDF file.
Return type:: str

to_urdf_file(path, compare_existing=True, use_protocols=True, relative_paths=False, verbose=False)[source]

Write the URDF to a file.

Parameters:

path (str or Path) – The path to the URDF file to be written.
compare_existing (bool) – If True, then if the file at path already exists, read it and only write back to it if the parsed URDF is different than the file content. This avoids some race conditions if the file is being compiled by multiple processes concurrently.
use_protocols (bool) – If True, all asset filenames that do not currently have a protocol (file:// or package://) will have the file:// protocol prepended. If False, asset filenames will have any protocol removed.
relative_paths (bool) – If True, convert all asset filenames to be relative to the specified output path. Otherwise, absolute paths are used. Note that some applications may not support relative paths.
verbose (bool) – Set to True to print information about xacro compilation, False otherwise.

to_urdf_string(use_protocols=True, paths_relative_to=None, pretty=True)[source]

Get the URDF as a string.

Parameters:

use_protocols (bool) – If True, all asset filenames that do not currently have a protocol (file:// or package://) will have the file:// protocol prepended. If False, asset filenames will have any protocol removed.
paths_relative_to (str or Path or None) – If not None, all asset filenames will be made relative to this path. Otherwise, absolute paths are used. Note that some applications may not support relative paths. Has no effect on filenames with the package:// protocol prefix.
pretty (bool) – Set True to format the string for human readability, False otherwise.

Returns:

The URDF represented as a string.

Return type:

str

Finding ROS Packages

xacro and ROS are built around the concept of ROS packages, but xacrodoc can find these packages without ROS installed.

exception xacrodoc.packages.PackageNotFoundError[source]: Raised when a package could not be found.

xacrodoc.packages.get_file_path(pkg, relative_path)[source]

Get the path to a file within a ROS package.

Parameters:

pkg (str) – The name of the ROS package.
relative_path (str or Path) – The path of the file relative to the package root.

Returns:

The file path.

Return type:

str

xacrodoc.packages.get_path(pkg)[source]

Attempt to get the path of a package.

Parameters:: pkg (str) – The name of the package.
Returns:: The path to the package.
Return type:: str
Raises:: PackageNotFoundError – If the package could not be found.

xacrodoc.packages.look_in(paths, priority=0)[source]

Add additional directories to search for packages.

Parameters:

paths (Iterable) – A list of paths in which to search for packages. Internally, these are passed to rospkg.RosPack.
priority (int) – Priority for the search: lower means the package is looked for using this method earlier.

xacrodoc.packages.reset()[source]: Reset the package finder to the default look-up methods.

xacrodoc.packages.update_package_cache(pkgpaths)[source]

Update the package cache.

This allows the user to manually specify the location of packages on the filesystem. The path does not actually need to be a proper ROS package, meaning that there is no need to have a package.xml file there.

Parameters:: pkgpaths (dict) – Map from package names to package paths. The paths are resolved, made absolute, and converted to strings.

xacrodoc.packages.walk_up_from(path, priority=0)[source]

Look for packages by walking up the directory tree from path.

Parameters:

path (str or pathlib.Path) – The path at which to start looking for packages.
priority (int) – Priority for the search: lower means the package is looked for using this method earlier.