(!) 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.

Visualizing a URDF

Description: This tutorial shows you how to visualize a URDF using ros3djs.

Keywords: ros3djs, web interface, javascript, URDF, Robot Web Tools

Tutorial Level: BEGINNER

URDF Example

In this tutorial, we show how to load a URDF in the browser. To begin, create a new HTML document and copy the follow code sample into it.

The HTML Code

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4 <meta charset="utf-8" />
   5 
   6 <script src="http://static.robotwebtools.org/threejs/current/three.min.js"></script>
   7 <script src="http://static.robotwebtools.org/threejs/current/ColladaLoader.min.js"></script>
   8 <script src="http://static.robotwebtools.org/ColladaAnimationCompress/current/ColladaLoader2.min.js"></script>
   9 <script src="http://static.robotwebtools.org/threejs/current/STLLoader.min.js"></script>
  10 <script src="http://static.robotwebtools.org/EventEmitter2/current/eventemitter2.min.js"></script>
  11 <script src="http://static.robotwebtools.org/roslibjs/current/roslib.min.js"></script>
  12 <script src="http://static.robotwebtools.org/ros3djs/current/ros3d.min.js"></script>
  13 
  14 <script>
  15   /**
  16    * Setup all visualization elements when the page is loaded.
  17    */
  18   function init() {
  19     // Connect to ROS.
  20     var ros = new ROSLIB.Ros({
  21       url : 'ws://localhost:9090'
  22     });
  23 
  24     // Create the main viewer.
  25     var viewer = new ROS3D.Viewer({
  26       divID : 'urdf',
  27       width : 800,
  28       height : 600,
  29       antialias : true
  30     });
  31 
  32     // Add a grid.
  33     viewer.addObject(new ROS3D.Grid());
  34 
  35     // Setup a client to listen to TFs.
  36     var tfClient = new ROSLIB.TFClient({
  37       ros : ros,
  38       angularThres : 0.01,
  39       transThres : 0.01,
  40       rate : 10.0
  41     });
  42 
  43     // Setup the URDF client.
  44     var urdfClient = new ROS3D.UrdfClient({
  45       ros : ros,
  46       tfClient : tfClient,
  47       path : 'http://resources.robotwebtools.org/',
  48       rootObject : viewer.scene,
  49       loader : ROS3D.COLLADA_LOADER_2
  50     });
  51   }
  52 </script>
  53 </head>
  54 
  55 <body onload="init()">
  56   <h1>Simple URDF Example</h1>
  57   <div id="urdf"></div>
  58 </body>
  59 </html>

Code Explanation

Now that we have an example, let's look at each piece.

   6 <script src="http://static.robotwebtools.org/threejs/current/three.min.js"></script>
   7 <script src="http://static.robotwebtools.org/threejs/current/ColladaLoader.min.js"></script>
   8 <script src="http://static.robotwebtools.org/ColladaAnimationCompress/current/ColladaLoader2.min.js"></script>
   9 <script src="http://static.robotwebtools.org/threejs/current/STLLoader.min.js"></script>
  10 <script src="http://static.robotwebtools.org/EventEmitter2/current/eventemitter2.min.js"></script>
  11 <script src="http://static.robotwebtools.org/roslibjs/current/roslib.min.js"></script>
  12 <script src="http://static.robotwebtools.org/ros3djs/current/ros3d.min.js"></script>

We first need to import all of the required JavaScript files. Note the addition of the two Collada loaders. Technically, we only need one of them, but be aware that there are two, since other robot models might require the THREE.js ColladaLoader. Here, we use the Robot Web Tools CDN.

  20     var ros = new ROSLIB.Ros({
  21       url : 'ws://localhost:9090'
  22     });

Next, we need to create a Ros node object to communicate with a rosbridge v2.0 server. In this example, the script will connect to localhost on the default port of 9090.

  25     var viewer = new ROS3D.Viewer({
  26       divID : 'urdf',
  27       width : 800,
  28       height : 600,
  29       antialias : true
  30     });

We then need to create a 3D viewer. We provide the dimensions as well as the HTML div where the viewer will be placed.

  33     viewer.addObject(new ROS3D.Grid());

We add a simple grid to the scene to help visualize the X-Y plane.

  36     var tfClient = new ROSLIB.TFClient({
  37       ros : ros,
  38       angularThres : 0.01,
  39       transThres : 0.01,
  40       rate : 10.0
  41     });

We then create a TF client. This client will subscribe to changes in the TF tree and update the scene appropriately. In this case, we will consider the default /base_link to be the fixed frame. We also set change thresholds to throttle the rate at which changes are published.

  44     var urdfClient = new ROS3D.UrdfClient({
  45       ros : ros,
  46       tfClient : tfClient,
  47       path : 'http://resources.robotwebtools.org/',
  48       rootObject : viewer.scene,
  49       loader : ROS3D.COLLADA_LOADER_2
  50     });

This section of code creates the actual UrdfClient object. Here we provide the Ros node object and TF client created above, the viewer's scene to render to, and a link to the base URL where out Collada files are too be loaded from. Note that due to browser security settings, these files must be hosted on a web server of some kind in order to be served properly. The package:// tag in the URDF file, which gives the location to import meshes from, is replaced by the base URL provided in the path parameter. For example, if you referenced a collada file in the URDF file as package:///body/meshes/body.dae, and set the path parameter as localhost:8000/, ros3djs will look for the collada file at localhost:8000/body/meshes/body.dae.

We also note that by default, the loader will use the robot_description parameter from the ROS parameter server as the URDF. Lastly, the loader parameter chooses between the two Collada loaders we've included at the top. The PR2 uses ColladaLoader2, but other robot models (such as CARL) use the ColladaLoader from THREE.js (ROS3D.COLLADA_LOADER). If your robot model does not appear, try changing the loader parameter.

  55 <body onload="init()">

It is important to remember to call the init() function when this page is loaded. This will call the JavaScript code discussed above.

  57   <div id="urdf"></div>

Within the HTML <body> we create a div with a matching ID for the viewer. This is where the interactive markers will be shown.

Converting URDFs to use PNG images

Most browsers require PNG images for the textures when rendering. If the URDF you would like to visualize uses TIFF images, you will need to perform two steps before you can visualize the robot in the browser:

  1. Convert each TIFF image into a PNG. Luckily, the convert command will do this for us:

    convert myimage.tiff myimage.png

    In the case of the PR2, we would convert all the TIFF images from pr2_description using the above command. Robot Web Tools host the converted images of many of the robots on a CDN. Check out Mesh Resource Handling section for available robot descriptions.

  2. Modify the URDF directly to use the PNG images.

Running the Example

At this point we are ready to run the example. To do so, you will need to have pr2_description, robot_state_publisher, joint_state_publisher, rosbridge_server, and tf2_web_republisher installed. Refer to their respective Wiki pages for installation instructions, or simply install their latest builds from the Ubuntu repositories.

Simply launch the necessary nodes with the following:

  •    1 roslaunch pr2_description upload_pr2.launch
       2 rosrun robot_state_publisher robot_state_publisher
       3 rosparam set use_gui true
       4 rosrun joint_state_publisher joint_state_publisher
       5 rosrun tf2_web_republisher tf2_web_republisher
       6 roslaunch rosbridge_server rosbridge_websocket.launch
    

Finally, you are now ready to bring up your HTML page in a web browser. Use the sliders provided by joint_state_publisher to move the PR2's joints. The effect should be mirrored in the browser. The result should be a page that looks similar to the following:

Support

Please send bug reports to the GitHub Issue Tracker. Feel free to contact us at any point with questions and comments.

Wiki: ros3djs/Tutorials/VisualizingAURDF (last edited 2019-08-08 18:42:52 by DavidMillard)