urdfdom

The URDF (U-Robot Description Format) library provides core data structures and a simple XML parsers for populating the class data structures from an URDF file.

For now, the details of the URDF specifications reside on http://ros.org/wiki/urdf

Using with ROS

If you choose to check this repository out for use with ROS, be aware that the necessary package.xml is not included in this repo but instead is added in during the ROS release process. To emulate this, pull the appropriate file into this repository using the following format. Be sure to replace the ALLCAPS words with the appropriate terms:

wget https://raw.github.com/ros-gbp/urdfdom-release/debian/ROS_DISTRO/UBUNTU_DISTRO/urdfdom/package.xml

For example:

wget https://raw.github.com/ros-gbp/urdfdom-release/debian/hydro/precise/urdfdom/package.xml

URDF Versioning

The URDF format supports versioning to allow for format evolution while maintaining compatibility. The version is specified in the <robot> tag using the version attribute in the format x.y (e.g., "1.0", "1.1").

Supported Versions

Version	Status	Description
1.0	Default	The original URDF specification. If no version attribute is specified, version 1.0 is assumed.
1.1	Supported	Adds quaternion orientation support via the quat_xyzw attribute and capsule geometry.

Version 1.0 (Default)

Version 1.0 is the default URDF version. When the version attribute is omitted from the <robot> tag, the parser assumes version 1.0.

Features supported in version 1.0:

• Robot model definition (links, joints, materials)
• Visual and collision geometry (box, cylinder, sphere, mesh)
• Joint types: revolute, continuous, prismatic, fixed, floating, planar
• Pose specification using xyz and rpy (roll-pitch-yaw) attributes
• Transmission elements
• Gazebo extensions and many more

Example:

<robot name="my_robot">
  <!-- No version attribute means version 1.0 -->
  <link name="base_link"/>
</robot>

Or explicitly:

<robot name="my_robot" version="1.0">
  <link name="base_link"/>
</robot>

Version 1.1

Version 1.1 extends the URDF specification with the following new features:

• All features from version 1.0
• Quaternion orientation: The quat_xyzw attribute can be used in <origin> elements as an alternative to rpy for specifying orientation
• Capsule geometry: A new geometry primitive defined by radius and length attributes

Quaternion Example:

<robot name="my_robot" version="1.1">
  <link name="base_link">
    <visual>
      <origin xyz="0 0 0" quat_xyzw="0 0 0 1"/>
      <geometry>
        <box size="1 1 1"/>
      </geometry>
    </visual>
  </link>
</robot>

Note: You cannot use both rpy and quat_xyzw in the same <origin> element.

Capsule Geometry Example:

<robot name="my_robot" version="1.1">
  <link name="arm_link">
    <visual>
      <geometry>
        <capsule radius="0.05" length="0.5"/>
      </geometry>
    </visual>
    <collision>
      <geometry>
        <capsule radius="0.05" length="0.5"/>
      </geometry>
    </collision>
  </link>
</robot>

The capsule is a cylinder capped with hemispheres at both ends. The length attribute specifies the length of the cylindrical portion (not including the hemispherical caps), and radius specifies the radius of both the cylinder and the hemispheres. Both attributes must be non-negative finite values.

Compatibility and Parsing Behavior

Scenario	Behavior
Newer URDF parsed by older library	Parsing will fail. The library validates the version and rejects URDF files with unsupported versions (e.g., a 1.1 URDF parsed by a library that only supports 1.0). Version-specific features like quat_xyzw and capsule geometry will be ignored with a warning if the declared version doesn't support them.
Older URDF parsed by newer library	Fully supported. The newer library is backward compatible and will parse older URDF files correctly. If no version attribute is specified, the parser defaults to version 1.0.
Unsupported version (e.g., 2.0)	Parsing will fail with an error. Only versions 1.0 and 1.1 are currently supported.
Invalid version format	Parsing will fail. The version must be in the format x.y (e.g., "1.0"). Single integers like "1" or malformed versions like "1.0.0" are rejected.

Version Format Requirements:

• Must be in the form major.minor (e.g., "1.0", "1.1")
• Both major and minor must be non-negative integers
• Single integers (e.g., "1") are not valid
• Trailing characters (e.g., "1.0~pre6") are not allowed

Installing from Source with ROS Debians

Warning: this will break ABI compatibility with future /opt/ros updates through the debian package manager. This is a hack, use at your own risk.

If you want to install urdfdom from source, but not install all of ROS from source, you can follow these loose guidelines. This is not best practice for installing, but works. This version is for ROS Hydro but should be easily customized for future version of ROS:

sudo mv /opt/ros/hydro/include/urdf_parser/ /opt/ros/hydro/include/_urdf_parser/
sudo mv /opt/ros/hydro/lib/liburdfdom_model.so /opt/ros/hydro/lib/_liburdfdom_model.so
sudo mv /opt/ros/hydro/lib/liburdfdom_model_state.so /opt/ros/hydro/lib/_liburdfdom_model_state.so
sudo mv /opt/ros/hydro/lib/liburdfdom_sensor.so /opt/ros/hydro/lib/_liburdfdom_sensor.so
sudo mv /opt/ros/hydro/lib/liburdfdom_world.so /opt/ros/hydro/lib/_liburdfdom_world.so
sudo mv /opt/ros/hydro/lib/pkgconfig/urdfdom.pc /opt/ros/hydro/lib/pkgconfig/_urdfdom.pc
sudo mv /opt/ros/hydro/share/urdfdom/cmake/urdfdom-config.cmake /opt/ros/hydro/share/urdfdom/cmake/_urdfdom-config.cmake

cd ~/ros/urdfdom # where the git repo was checked out
mkdir -p build
cd build
cmake ../ -DCMAKE_INSTALL_PREFIX=/opt/ros/hydro
make -j8
sudo make install

# now rebuild your catkin workspace
cd ~/ros/ws_catkin
catkin_make