[Documentation] [TitleIndex] [WordIndex

Note: This tutorial assumes you know how to write well-formatted XML code.
(!) Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Building a Visual Robot Model with URDF from Scratch

Description: Learn how to build a visual model of a robot that you can view in Rviz

Keywords: URDF

Tutorial Level: BEGINNER

Next Tutorial: Making the Model Move

In this tutorial, we’re going to build a visual model of a robot that vaguely looks like R2D2. In later tutorials, you’ll learn how to articulate the model, add in some physical properties, generate neater code with xacro and make it move in Gazebo. But for now, we’re going to focus on getting the visual geometry correct.

Before continuing, make sure you have the joint_state_publisher package installed. If you installed urdf_tutorial using apt-get, this should already be the case. If not, please update your installation to include that package (use rosdep to check).

All of the robot models mentioned in this tutorial (and the source files) can be found in the urdf_tutorial package.

One Shape

First, we’re just going to explore one simple shape. Here’s about as simple as a urdf as you can make. Source

   1 <?xml version="1.0"?>
   2 <robot name="myfirst">
   3   <link name="base_link">
   4     <visual>
   5       <geometry>
   6         <cylinder length="0.6" radius="0.2"/>
   7       </geometry>
   8     </visual>
   9   </link>
  10 </robot>

To translate the XML into English, this is a robot with the name myfirst, that contains only one link (a.k.a. part), whose visual component is just a cylinder 0.6 meters long with a 0.2 meter radius. This may seem like a lot of enclosing tags for a simple “hello world” type example, but it will get more complicated, trust me.

To examine the model, launch the display.launch file:

$ roslaunch urdf_tutorial display.launch model:=urdf/01-myfirst.urdf

This does three things. It

Note that the roslaunch line above assumes that you are executing it from the urdf_tutorial package directory (ie: the urdf directory is a direct child of the current working directory). If that is not the case, the relative path to 01-myfirst.urdf will not be valid, and you'll receive an error as soon as roslaunch tries to load the urdf to the parameter server.

A slightly modified argument allows this to work regardless of the current working directory:

$ roslaunch urdf_tutorial display.launch model:='$(find urdf_tutorial)/urdf/01-myfirst.urdf'

note the single quotes around the argument value.

You'll have to change all example roslaunch lines given in these tutorials if you are not running them from the urdf_tutorial package location.

After launching display.launch, you should end up with RViz showing you the following:

my first image

Things to note:

Multiple Shapes

Now let’s look at how to add multiple shapes/links. If we just add more link elements to the urdf, the parser won’t know where to put them. So, we have to add joints. Joint elements can refer to both flexible and inflexible joints. We’ll start with inflexible, or fixed joints. Source

   1 <?xml version="1.0"?>
   2 <robot name="multipleshapes">
   3   <link name="base_link">
   4     <visual>
   5       <geometry>
   6         <cylinder length="0.6" radius="0.2"/>
   7       </geometry>
   8     </visual>
   9   </link>
  10 
  11   <link name="right_leg">
  12     <visual>
  13       <geometry>
  14         <box size="0.6 0.1 0.2"/>
  15       </geometry>
  16     </visual>
  17   </link>
  18 
  19   <joint name="base_to_right_leg" type="fixed">
  20     <parent link="base_link"/>
  21     <child link="right_leg"/>
  22   </joint>
  23 
  24 </robot>

roslaunch urdf_tutorial display.launch model:=urdf/02-multipleshapes.urdf Multiple Shapes

Both of the shapes overlap with each other, because they share the same origin. If we want them not to overlap we must define more origins.

Origins

So R2D2’s leg attaches to the top half of his torso, on the side. So that’s where we specify the origin of the JOINT to be. Also, it doesn’t attach to the middle of the leg, it attaches to the upper part, so we must offset the origin for the leg as well. We also rotate the leg so it is upright. Source

   1 <?xml version="1.0"?>
   2 <robot name="origins">
   3   <link name="base_link">
   4     <visual>
   5       <geometry>
   6         <cylinder length="0.6" radius="0.2"/>
   7       </geometry>
   8     </visual>
   9   </link>
  10 
  11   <link name="right_leg">
  12     <visual>
  13       <geometry>
  14         <box size="0.6 0.1 0.2"/>
  15       </geometry>
  16       <origin rpy="0 1.57075 0" xyz="0 0 -0.3"/>
  17     </visual>
  18   </link>
  19 
  20   <joint name="base_to_right_leg" type="fixed">
  21     <parent link="base_link"/>
  22     <child link="right_leg"/>
  23     <origin xyz="0 -0.22 0.25"/>
  24   </joint>
  25 
  26 </robot>

roslaunch urdf_tutorial display.launch model:=urdf/03-origins.urdf Origins Screenshot

Material Girl

“Alright,” I hear you say. “That’s very cute, but not everyone owns a B21. My robot and R2D2 are not red!” That’s a good point. Let’s take a look at the material tag. Source

   1 <?xml version="1.0"?>
   2 <robot name="materials">
   3 
   4   <material name="blue">
   5     <color rgba="0 0 0.8 1"/>
   6   </material>
   7 
   8   <material name="white">
   9     <color rgba="1 1 1 1"/>
  10   </material>
  11 
  12 
  13   <link name="base_link">
  14     <visual>
  15       <geometry>
  16         <cylinder length="0.6" radius="0.2"/>
  17       </geometry>
  18       <material name="blue"/>
  19     </visual>
  20   </link>
  21 
  22   <link name="right_leg">
  23     <visual>
  24       <geometry>
  25         <box size="0.6 0.1 0.2"/>
  26       </geometry>
  27       <origin rpy="0 1.57075 0" xyz="0 0 -0.3"/>
  28       <material name="white"/>
  29     </visual>
  30   </link>
  31 
  32   <joint name="base_to_right_leg" type="fixed">
  33     <parent link="base_link"/>
  34     <child link="right_leg"/>
  35     <origin xyz="0 -0.22 0.25"/>
  36   </joint>
  37 
  38   <link name="left_leg">
  39     <visual>
  40       <geometry>
  41         <box size="0.6 0.1 0.2"/>
  42       </geometry>
  43       <origin rpy="0 1.57075 0" xyz="0 0 -0.3"/>
  44       <material name="white"/>
  45     </visual>
  46   </link>
  47 
  48   <joint name="base_to_left_leg" type="fixed">
  49     <parent link="base_link"/>
  50     <child link="left_leg"/>
  51     <origin xyz="0 0.22 0.25"/>
  52   </joint>
  53 
  54 </robot>

roslaunch urdf_tutorial display.launch model:=urdf/04-materials.urdf Materials Screenshot

Finishing the Model

Now we finish the model off with a few more shapes: feet, wheels, and head. Most notably, we add a sphere and a some meshes. We’ll also add few other pieces that we’ll use later. Source

   1 <?xml version="1.0"?>
   2 <robot name="visual">
   3 
   4 <material name="blue">
   5     <color rgba="0 0 0.8 1"/>
   6   </material>
   7   <material name="black">
   8     <color rgba="0 0 0 1"/>
   9   </material>
  10   <material name="white">
  11     <color rgba="1 1 1 1"/>
  12   </material>
  13 
  14   <link name="base_link">
  15     <visual>
  16       <geometry>
  17         <cylinder length="0.6" radius="0.2"/>
  18       </geometry>
  19       <material name="blue"/>
  20     </visual>
  21   </link>
  22 
  23   <link name="right_leg">
  24     <visual>
  25       <geometry>
  26         <box size="0.6 0.1 0.2"/>
  27       </geometry>
  28       <origin rpy="0 1.57075 0" xyz="0 0 -0.3"/>
  29       <material name="white"/>
  30     </visual>
  31   </link>
  32 
  33   <joint name="base_to_right_leg" type="fixed">
  34     <parent link="base_link"/>
  35     <child link="right_leg"/>
  36     <origin xyz="0 -0.22 0.25"/>
  37   </joint>
  38 
  39   <link name="right_base">
  40     <visual>
  41       <geometry>
  42         <box size="0.4 0.1 0.1"/>
  43       </geometry>
  44       <material name="white"/>
  45     </visual>
  46   </link>
  47 
  48   <joint name="right_base_joint" type="fixed">
  49     <parent link="right_leg"/>
  50     <child link="right_base"/>
  51     <origin xyz="0 0 -0.6"/>
  52   </joint>
  53 
  54   <link name="right_front_wheel">
  55     <visual>
  56       <origin rpy="1.57075 0 0" xyz="0 0 0"/>
  57       <geometry>
  58         <cylinder length="0.1" radius="0.035"/>
  59       </geometry>
  60       <material name="black"/>
  61       <origin rpy="0 0 0" xyz="0 0 0"/>
  62     </visual>
  63   </link>
  64   <joint name="right_front_wheel_joint" type="fixed">
  65     <parent link="right_base"/>
  66     <child link="right_front_wheel"/>
  67     <origin rpy="0 0 0" xyz="0.133333333333 0 -0.085"/>
  68   </joint>
  69 
  70   <link name="right_back_wheel">
  71     <visual>
  72       <origin rpy="1.57075 0 0" xyz="0 0 0"/>
  73       <geometry>
  74         <cylinder length="0.1" radius="0.035"/>
  75       </geometry>
  76       <material name="black"/>
  77     </visual>
  78   </link>
  79   <joint name="right_back_wheel_joint" type="fixed">
  80     <parent link="right_base"/>
  81     <child link="right_back_wheel"/>
  82     <origin rpy="0 0 0" xyz="-0.133333333333 0 -0.085"/>
  83   </joint>
  84 
  85   <link name="left_leg">
  86     <visual>
  87       <geometry>
  88         <box size="0.6 0.1 0.2"/>
  89       </geometry>
  90       <origin rpy="0 1.57075 0" xyz="0 0 -0.3"/>
  91       <material name="white"/>
  92     </visual>
  93   </link>
  94 
  95   <joint name="base_to_left_leg" type="fixed">
  96     <parent link="base_link"/>
  97     <child link="left_leg"/>
  98     <origin xyz="0 0.22 0.25"/>
  99   </joint>
 100 
 101   <link name="left_base">
 102     <visual>
 103       <geometry>
 104         <box size="0.4 0.1 0.1"/>
 105       </geometry>
 106       <material name="white"/>
 107     </visual>
 108   </link>
 109 
 110   <joint name="left_base_joint" type="fixed">
 111     <parent link="left_leg"/>
 112     <child link="left_base"/>
 113     <origin xyz="0 0 -0.6"/>
 114   </joint>
 115 
 116   <link name="left_front_wheel">
 117     <visual>
 118       <origin rpy="1.57075 0 0" xyz="0 0 0"/>
 119       <geometry>
 120         <cylinder length="0.1" radius="0.035"/>
 121       </geometry>
 122       <material name="black"/>
 123     </visual>
 124   </link>
 125   <joint name="left_front_wheel_joint" type="fixed">
 126     <parent link="left_base"/>
 127     <child link="left_front_wheel"/>
 128     <origin rpy="0 0 0" xyz="0.133333333333 0 -0.085"/>
 129   </joint>
 130 
 131   <link name="left_back_wheel">
 132     <visual>
 133       <origin rpy="1.57075 0 0" xyz="0 0 0"/>
 134       <geometry>
 135         <cylinder length="0.1" radius="0.035"/>
 136       </geometry>
 137       <material name="black"/>
 138     </visual>
 139   </link>
 140   <joint name="left_back_wheel_joint" type="fixed">
 141     <parent link="left_base"/>
 142     <child link="left_back_wheel"/>
 143     <origin rpy="0 0 0" xyz="-0.133333333333 0 -0.085"/>
 144   </joint>
 145 
 146   <joint name="gripper_extension" type="fixed">
 147     <parent link="base_link"/>
 148     <child link="gripper_pole"/>
 149     <origin rpy="0 0 0" xyz="0.19 0 0.2"/>
 150   </joint>
 151 
 152   <link name="gripper_pole">
 153     <visual>
 154       <geometry>
 155         <cylinder length="0.2" radius="0.01"/>
 156       </geometry>
 157       <origin rpy="0 1.57075 0 " xyz="0.1 0 0"/>
 158     </visual>
 159   </link>
 160 
 161   <joint name="left_gripper_joint" type="fixed">
 162     <origin rpy="0 0 0" xyz="0.2 0.01 0"/>
 163     <parent link="gripper_pole"/>
 164     <child link="left_gripper"/>
 165   </joint>
 166 
 167   <link name="left_gripper">
 168     <visual>
 169       <origin rpy="0.0 0 0" xyz="0 0 0"/>
 170       <geometry>
 171         <mesh filename="package://urdf_tutorial/meshes/l_finger.dae"/>
 172       </geometry>
 173     </visual>
 174   </link>
 175 
 176   <joint name="left_tip_joint" type="fixed">
 177     <parent link="left_gripper"/>
 178     <child link="left_tip"/>
 179   </joint>
 180 
 181   <link name="left_tip">
 182     <visual>
 183       <origin rpy="0.0 0 0" xyz="0.09137 0.00495 0"/>
 184       <geometry>
 185         <mesh filename="package://urdf_tutorial/meshes/l_finger_tip.dae"/>
 186       </geometry>
 187     </visual>
 188   </link>
 189   <joint name="right_gripper_joint" type="fixed">
 190     <origin rpy="0 0 0" xyz="0.2 -0.01 0"/>
 191     <parent link="gripper_pole"/>
 192     <child link="right_gripper"/>
 193   </joint>
 194 
 195   <link name="right_gripper">
 196     <visual>
 197       <origin rpy="-3.1415 0 0" xyz="0 0 0"/>
 198       <geometry>
 199         <mesh filename="package://urdf_tutorial/meshes/l_finger.dae"/>
 200       </geometry>
 201     </visual>
 202   </link>
 203 
 204   <joint name="right_tip_joint" type="fixed">
 205     <parent link="right_gripper"/>
 206     <child link="right_tip"/>
 207   </joint>
 208 
 209   <link name="right_tip">
 210     <visual>
 211       <origin rpy="-3.1415 0 0" xyz="0.09137 0.00495 0"/>
 212       <geometry>
 213         <mesh filename="package://urdf_tutorial/meshes/l_finger_tip.dae"/>
 214       </geometry>
 215     </visual>
 216   </link>
 217 
 218   <link name="head">
 219     <visual>
 220       <geometry>
 221         <sphere radius="0.2"/>
 222       </geometry>
 223       <material name="white"/>
 224     </visual>
 225   </link>
 226   <joint name="head_swivel" type="fixed">
 227     <parent link="base_link"/>
 228     <child link="head"/>
 229     <origin xyz="0 0 0.3"/>
 230   </joint>
 231 
 232   <link name="box">
 233     <visual>
 234       <geometry>
 235         <box size="0.08 0.08 0.08"/>
 236       </geometry>
 237       <material name="blue"/>
 238     </visual>
 239   </link>
 240 
 241   <joint name="tobox" type="fixed">
 242     <parent link="head"/>
 243     <child link="box"/>
 244     <origin xyz="0.1814 0 0.1414"/>
 245   </joint>
 246 </robot>

roslaunch urdf_tutorial display.launch model:=urdf/05-visual.urdf Visual Screenshot

How to add the sphere should be fairly self explanatory

   1   <link name="head">
   2     <visual>
   3       <geometry>
   4         <sphere radius="0.2"/>
   5       </geometry>
   6       <material name="white"/>
   7     </visual>
   8   </link>

The meshes here were borrowed from the PR2. They are separate files which you have to specify the path for. You should use the package://NAME_OF_PACKAGE/path notation. The meshes for this tutorial are located within the urdf_tutorial package, in a folder called meshes.

   1   <link name="left_gripper">
   2     <visual>
   3       <origin rpy="0.0 0 0" xyz="0 0 0"/>
   4       <geometry>
   5         <mesh filename="package://urdf_tutorial/meshes/l_finger.dae"/>
   6       </geometry>
   7     </visual>
   8   </link>

There you have it. A R2D2-like URDF model. Now you can continue on to the next step, making it move.


2018-11-10 13:33