Tutorial: Export URDF#

Learning Objectives#

This tutorial explores exporting a URDF file from USD in NVIDIA Isaac Sim. After this tutorial, you will be able to convert robot USD files to URDF files using NVIDIA Isaac Sim.

10-20 Minute Tutorial

Getting Started#

Prerequisites

Exporting A Robot#

To convert a robot USD file to a URDF file and cover some advanced options:

Enable the Exporter Extension#

To enable the exporter extension:

  1. Navigate to Windows > Extensions and type urdf in the search bar, then enable the USD to URDF exporter extension.

    This will add the File > Export to URDF menu option.

  2. Select it to open the extension, verify that the user interface is similar to:

    The USD to URDF Exporter UI

  3. Open the USD for the Franka robot, which is found in the Isaac asset root path at /Isaac/Robots/FrankaRobotics/FrankaPanda/franka.usd.

    After the USD finishes loading:

  4. Open the File > Export to URDF menu option. A select file dialog will appear.

  5. Select the destination file and folder.

  6. Click Export.

    The USD to URDF Exporter UI

  7. Open the output folder to view the resulting files.

  8. Verify that a franka.urdf file and a meshes directory is present. The meshes directory contains the mesh files for the robot.

To check the results:

  • The URDF can be imported back to USD and opened in Isaac Sim. Refer to the Import URDF tutorial for the steps to do that.

  • Review the results with this URDF Viewer Example website. Drag the output directory directly into the site to view the URDF file, and examine the joints.

The Franka URDF viewed with the URDF Viewer Example website

Import Options#

Mesh Directory Path#

The directory for where the mesh .obj files are saved defaults to the name meshes, and is placed in the same directory as where the URDF file is saved. You can specify an explicit directory by defining the directory path in the Mesh Directory Path field.

Mesh directory path field

By default the paths to the mesh files are relative paths, which you can observe by opening up the exported franka.urdf file in a text editor.

The Franka URDF with relative mesh file paths

Mesh Path Prefix#

Often it is necessary to use absolute paths or a URI, which is necessary when using the URDF with ROS. Any prefix can be prepended to the mesh file paths by specifying the prefix in the Mesh Path Prefix field.

For example, to make the Franka URDF loadable in RViz let’s turn the paths into a valid URI with the file scheme (that is, file://). To do this:

  1. Set the Mesh Path Prefix to file://<absolute path to output directory>/.

  2. You can get the absolute path to the output directory by copying the text that is in the Output File/Directory field.#. Verify that your Mesh Path Prefix field is something like this:

    file:///home/<username>/franka/.

    Note

    There are three forward slashes at the beginning and the trailing forward slash at the end.

  3. After exporting, verify that the mesh file paths in the URDF are all beginning with the prefix.

The Franka URDF with URI file paths

This allows for the URDF to be viewed in RViz.

The Franka URDF viewed in RViz

Root Prim Path#

If you are exporting a robot directly from its asset file, the default prim would be the root prim for it, but if exporting from a scene that contains a robot and multiple other objects, you can elect to export only the robot by specifying which prim represents it.

Collision Objects#

In a URDF file, a link often has two separate meshes associated with it:

  • a visual mesh

  • a collision mesh

In USD there is no distinction between a visual mesh and a collision mesh. USD prims can have the PhysicsCollisionAPI attached to them, which tells the physics engine to resolve the motion of the body as it touches other bodies. Additionally, prims can be set to be visible or invisible. The USD to URDF exporter creates visual meshes and collision meshes for each link based on if it has the PhysicsCollisionAPI applied to it and if it is visible.

To explore how geometry prims map to visual and collision meshes in the URDF, add a geometry prim to the Franka robot and export it in different ways to verify what is created with each of the resulting URDF files.

  1. Open the USD for the Franka robot (found at /Isaac/Robots/FrankaRobotics/FrankaPanda/franka.usd).

  2. Right click the panda_hand Xform prim, and from the contextual menu select Create > Mesh > Sphere.

  3. Select the new Sphere Mesh prim, and change the scaling for the x, y, and z components to all be 0.3.

  4. Verify that the Franka is similar to:

    The Franka USD with a mesh sphere that does not have collision API and is visible

  5. Export your current stage by following the steps discussed above and outlined below (there is no need to save your changes).

    • Open the USD to URDF Exporter menu.

    • Select an output directory.

    • Press the EXPORT button.

  6. Drag your output directory into the URDF Viewer Example website to view the results.

  7. Verify that your results are similar to:

    The Franka URDF with a mesh sphere that does not have the collision API and is visible

  8. Enable the Show Collision option, which visualizes all the collisions meshes and highlights them with a gold color.

  9. Observe how the sphere is not highlighted with the gold color, that is because in the URDF it is not a collision mesh it is a visual mesh.

  10. Back in the Franka USD, add the collision API to the sphere.

    This can be done by selecting the Sphere prim and clicking the +Add button in the prim’s property menu.

  11. Select Physics > Colliders Preset.

  12. After adding the collision API to the sphere, re-export the USD stage to URDF and drag the output directory into the URDF viewer again. You might need to refresh the viewer’s webpage before dragging in the new URDF.

  13. Verify that your Franka is similar to:

    The Franka URDF with a mesh sphere that does have the collision API and is visible

  14. Enable the Show Collision option.

  15. Observe that this time the sphere is highlighted with the gold color.

    That is because the sphere is both a collision mesh and a visual mesh in the URDF file.

  16. Back in the Franka USD, make the sphere invisible by disabling the “eye” icon next to the Sphere prim.

    The Franka USD with the sphere set to be invisible

  17. After making the sphere invisible, re-export the USD stage to URDF and drag the output directory into the URDF viewer again.

    Initially the sphere is not there, but after enabling Show Collision, the sphere is highlighted with the gold color. This is because the sphere is a collision mesh, but not a visual mesh in the URDF file.

  18. Verify that you have something similar to:

The Franka URDF with a mesh sphere that does have the collision API and is invisible

To export link collision meshes correctly to URDF, they must have the collision API and must be set to invisible. To make all collision API prims into visual meshes, regardless of the visibility state of the prim, enable the Visualize Collisions option under the advanced options of the USD to URDF Exporter.

Limitations#

The USD format offers much greater expressiveness and provides more capabilities compared to URDF. The set of all scenes and robots that can be described using USD is a superset to those that can be described with URDF. Meaning all scenes and robots that can be described by a URDF file can also be described by a USD file, but not vice versa. Therefore, there is no direct one-to-one mapping between USDs and URDFs. Consequently, when converting a USD file to a URDF file, several assumptions are made and constraints are imposed.

Here is list of constraints for the USD in order for the USD to URDF exporter to succeed.

  • The kinematic structure of the robot must be a tree structure

  • Scaling on sphere shapes must be the same for every axis

  • Scaling on cylinder shapes must be the same for radius axes (that is, the non-height axes)

  • The coordinates for each body frame of a joint must be co-located and aligned

  • Parent link prims should be Body 0, and child link prims should be Body 1 of the joint

  • Joint prims must be either prismatic, revolute, or fixed

  • Link prims must be Xform.

  • Sensor prims must be either Camera or IsaacImuSensor

  • Geometry prims must be either Cube, Sphere, Cylinder, or Mesh

  • Geometry prims must be “leafs” in the kinematic tree

If your USD violates one of these constraints an error is thrown.

Note

Depending on the robot structure, some body names might be overridden because of the merging of different frames. Review the output and verify that it is accurate.

Summary#

This tutorial covered the following topics:

  1. Exporting URDF files using the exporter GUI

  2. Validating the URDF result by viewing in a viewer

  3. Understanding how collision and visual meshes in the URDF are controlled from the USD

  4. Outline the limitation of the USD to URDF exporter

Further Learning#

Review USD to URDF Exporter Extension to learn more about other configuration options.