[Documentation] [TitleIndex] [WordIndex


This tool was developed to convert CAD models to URDF models semi-automatically. It makes use of the XML files exported by the SimMechanics Link . Mathworks, makers of SimMechanics, have developed plugins for a couple of leading CAD programs, including SolidWorks, ProEngineer and Inventor.

For more information on using this package, please see the tutorial on converting SimMechanics to URDF


This package has only been tested using SimMechanics Link Version 3.2 with ProEngineer 4.0 and 5.0.

How it Works

The SimMechanics Link creates an XML file (PhysicalModelingXMLFile) and a collection of STL files. The XML describes all of the bodies, reference frames, inertial frames and joints for the model. The script convert.py takes this information and converts it to a URDF. However, there are some tricks and caveats, which can maneuvered using a parameter file. Not using a parameter file will result in a model that looks correct when not moving, but possibly does not move correctly.

General Usage

The parameter file is optional. The keyword xml tells the script to output urdf/xml, as opposed to the other options described below.

Tree vs. Graph

URDF allows robot descriptions to only follow a tree structure, meaning that each link/body can have only one parent, and its position is dependent on the position of its parent and the position of the joint connecting it to its parent. This forces URDF descriptions to be in a tree structure.

CAD files do not generally follow this restriction; one body can be dependent on multiple bodies, or at the very least, aligned to multiple bodies.

This creates two problems.

1. The graph must be converted into a tree structure. This is done by means of a breadth first traversal of the graph, starting from the root link. However, this sometimes leads to improper dependencies, which can be corrected with the parameter file, as described below.

2. Fixed joints in CAD are not always fixed in the exported XML. To best understand this, consider the example where you have bodies A, B and C, all connected to each other. If C is connected to A in such a way that it is constrained in the X and Z dimensions, and C is connected to B so that it is constrained in the Y dimension, then effectively, C is fixed/welded to both of those bodies. Thus removing the joint between B and C (which is needed to make the tree structure) frees up the joint. This also can be fixed with the parameter file.

Naming Conventions

Each Body element in the XML has a possibly non-unique name tag. These are converted to ("%s%d", name tag, lowest unused natural number)

Reference Frames

The exported XML includes three types of reference frames for each body. "CG" refers to the center of gravity, "CS1" refers to the root coordinate system for the STL, and all of the rest refer to joints attaching points. The first two use TF frames named ("%s%s", body's unique name, CG or CS1). All of the rest use the reference attribute of the Frame.

The script also defines one extra reference frame for each body, named ("X%s", body's unique name). This is the origin for the Link element in the URDF. It is defined to have the offset equal to the reference frame of the joint connecting it to its parent, and the orientation equal to that of CS1. In the URDF, the visual origin, collision origin and all other relative offsets are calculated from this point.


Joints follow a similar naming scheme to Links, ("%s%d", name tag, lowest unused natural number). However, often they are referred to by a their base connection frame. In the following snippet, the joint number would be 11.

   1 <SimpleJoint>
   2         <name>"ENTERPRISEHULL--PHASERARRAY"</name>
   3         <nodeID>"44/5516/10606:-:44/5516"</nodeID>
   4         <status>""</status>
   5         <base>
   6           <JointSide>
   7             <name>""</name>
   8             <connection>
   9               <Frame ref="11"></Frame>
  10             </connection>
  11           </JointSide>
  12         </base>
  13         <follower>
  14           <JointSide>
  15             <name>""</name>
  16             <connection>
  17               <Frame ref="12"></Frame>
  18             </connection>
  19           </JointSide>
  20         </follower>
  21         ...
  22 </SimpleJoint>

This was done out of convenience, but is probably not the best way to refer to joints. However, in the parameter file below, this will be referred to as the joint number.

The Parameter File

All of the parameters are loaded in via a text file/yaml file. They are NOT loaded into the parameter server.

Root Parameters

STL Parameters

Redefining Joints

   12: {name: ARM_TRANSLATE, axis: "1 0 0", type: prismatic, limits: {effort: 30, velocity: 1.0, lower: -.18, upper: .18}}
   15: {name: ARM_ROTATE, axis: "0 0 1"}

Adding Joints

2024-07-13 14:38