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", "1.2").

Supported Versions

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.

Version 1.2

Version 1.2 extends the URDF specification with extended joint limits:

• All features from version 1.1
• Acceleration limit: The acceleration attribute specifies the maximum joint acceleration
• Deceleration limit: The deceleration attribute specifies the maximum joint deceleration
• Jerk limit: The jerk attribute specifies the maximum joint jerk (rate of change of acceleration)

Version 1.2 also relaxes some requirements on the existing joint limit attributes:

• lower and upper are optional for non-revolute/non-prismatic joints and default to -infinity and infinity when omitted
• for revolute and prismatic joints, both lower and upper must be provided
• effort and velocity become optional and default to infinity when omitted
• effort, velocity, acceleration, deceleration, and jerk must all be non-negative when provided
• when both are specified, upper must be greater than or equal to lower

All three attributes are optional and default to infinity (no limit). If acceleration is specified but deceleration is not, deceleration defaults to the acceleration value. All values must be non-negative.

Extended Joint Limits Example:

<robot name="my_robot" version="1.2">
  <link name="base_link"/>
  <link name="arm_link"/>
  <joint name="arm_joint" type="revolute">
    <parent link="base_link"/>
    <child link="arm_link"/>
    <axis xyz="0 0 1"/>
    <limit lower="-1.57" upper="1.57" effort="100.0" velocity="1.0" acceleration="10.0" deceleration="5.0" jerk="200.0"/>
  </joint>
</robot>

Joint Limit Semantics By Version

The parser keeps legacy behavior for older URDF versions and only applies the relaxed defaults starting in version 1.2.

For all supported versions, invalid numeric values still fail parsing. In version 1.2, negative values for effort, velocity, acceleration, deceleration, and jerk are rejected. In version 1.2, revolute and prismatic joints additionally require both lower and upper, and upper cannot be smaller than lower.

Compatibility and Parsing Behavior

Version Format Requirements:

• Must be in the form major.minor (e.g., "1.0", "1.1", "1.2")
• 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