Robot Modeling

The urdf XML specification contains nine sub-specifications. Many of the specifications are not used or only used with specific packages. The important specifications are described below.

• model - This specification provides a general guide to the .urdf format.
• robot - The <robot> element is the top-level element in all urdf files. It contains links and joints.
• link - Describes properties of a rigid-body in your robot
  • Has a name attribute to name the link.
  • <inertial> Optionally specify mass and rotational inertia properties of the link.
  • <visual> Optionally describes how to draw the link. There are basic primitives or you can use a 3D model from CAD.
    • <geometry> specifies the shape of the object. Can be <box>, <cylinder>, <sphere> or <mesh>.
    • <material> specifies the color of the object
  • <collision> Optionally describe geometry used for collision detection. Used by motion planning and simulation tools.
• joint - Connects links together with various types of joint freedoms.
  • Has a name attribute to name the joint.
  • Has a type attribute which determines what freedoms and constraints are imposed on the joint.
    • revolute: a 1-degree of freedom (DOF) rotational joint with upper and lower joint limits (specified by a <limit> element)
    • continuous: a 1-DOF rotational joint without limits
    • prismatic: a 1-DOF translational joint with limits (specified by a <limit> element)
    • fixed: A transformation that does not change between two links
    • floating: A joint where all 6 DOF can move
    • planar: A 2-DOF joint allowing translation in the plane
  • Joints have a <parent> link and a <child> link and determine where the <child> link is relative to the parent.
  • <origin> specifies the location of the child in the parent link frame
    • The child frame is translated by xyz
    • The child frame is rotated by rpy, roll ,pitch, yaw (which are rotations about the fixed x, y, and z axes).
  • Other joints can be created by locating multiple joints at the same location. For example: a universal joint is two co-located continuous joints. Creating such joints may require using "dummy" links that lack inertial, visualization, or collision properties.
  • There are many optional tags. The <safety_controller> tag is only used by the pr2_controller_manager and the ros_control packages.
• gazebo Gazebo extensions to URDF files, which it uses when converting to its SDF file format. For more information see Gazebo Tutorial for Using URDF.
• Go through the ROS URDF Tutorials to learn more.

There are other formats used in robotics (not just ROS) that relate to URDF files.

• Kinematics and Dynamics Library (KDL)
  • The kdl_parser converts urdf to a format used by KDL
• Gazebo (the primary ROS simulation tool) uses SDF files, but can convert URDF files to SDF automatically
  • Many tags in a URDF file are mainly used when Gazebo converts to SDF.
• Collada is a generic 3D file format.
  • The collada_urdf package converts between .urdf and collada (.dae) files
• SolidWorks is a 3D computer aided design (CAD) program
  • sw_urdf_exporter an convert SolidWorks models to URDF.

• Use the <xacro:property name = "name" value = "value"> to define a constant in xacro
  • Basic constants (like pi) are already defined.
  • You can use any python expression anywhere using the ${} syntax

  • It often makes sense to load non-changeable robot parameters directly from a yaml file

    <!-- Get the path to the yaml file relative to the package -->
    <xacro:property name="yaml_file"    value="$(find package)/config/config.yaml" />
    <!-- load the values in the yaml file. They are stored in a dictionary called properties -->
    <xacro:property name="properties"   value="${load_yaml(yaml_file)}" />
    <!-- access an individual variable -->
    <xacro:property name="property"  value="${properties['property']}" />
    

• Macro's are the most useful tools when creating urdf files for eventual use with gazebo

• A common case: you want the visual, inertial, and collision elements of a link to correspond to each other:

   <!-- Create a link with
        visual, inertial, and collision for a z-axis aligned cylinder.
        Also enables specifying a material block.
        Assumes the default cylinder orientation
   -->
  <xacro:macro name="cylinder_link" params="name length radius mass *material">
    <link name="${name}">
      <visual>
        <geometry>
          <cylinder length="${length}" radius="${radius}" />
        </geometry>
        <xacro:insert_block name="material" />
      </visual>
      <collision>
        <geometry>
          <cylinder length="${length}" radius="${radius}" />
        </geometry>
      </collision>
      <inertial>
        <mass value="${mass}"/>
        <inertia ixx="${(1.0/12.0)*mass*(3*radius**2 + length**2)}"
                 ixy="0"
                 ixz="0"
                 iyy="${(1.0/12.0)*mass*(3*radius**2 + length**2)}"
                 iyz="0"
                 izz="${0.5*mass*radius**2}" />
      </inertial>
    </link>
  </xacro:macro>
  

• You can include xacro files in other xacro files using <xacro:include filename = "$(find package)/urdf/myfile.xacro">
• Build your own library of useful xacro macros.
• Keep the gazebo tags for your urdf in a separate file and include it. Thus you can maintain a clean separation between the gazebo and non-gazebo parts of your file.

• Conditionally include a block using <xacro:if value = "expression">

• Pass arguments to xacro using xacro model variable:=value syntax..
• Access arguments within xacro using $(arg name)