FreeCAD  →  .urdf

FreeCAD to URDF

FreeCAD's own Robot workbench simulates arms but writes no URDF. The route out is a ROS workbench — CROSS, or RobotCAD built on it — which turns parts and placements into links and joints and writes the description package for you.

The export itself happens in FreeCAD

This site does not read FreeCAD files. The conversion is done by freecad.cross — LGPL 2.1, with RobotCAD as a fork that adds mass from materials, ros2_control and Gazebo sensors, at github.com/galou/freecad.cross. What follows is what the export needs from you, and then the half that is ours: what these exports get wrong, and how to find out which of it happened to yours.

Getting a description out

Install a ROS workbench

CROSS needs FreeCAD 0.21.2 or later and targets ROS 2. RobotCAD is a fork of it with more automation — mass and inertia computed from a material, collisions generated from the part, controllers for ros2_control and sensors for Gazebo. Either installs as a FreeCAD workbench; neither replaces FreeCAD's own Robot workbench, which has no URDF export.

Make a robot of links and joints

The workbench adds a robot object that holds links and joints. Each link points at FreeCAD parts in three roles — what is seen, what collides and the real part the mass comes from — and each joint has a placement relative to its parent link. Placing joints by selecting faces is where most of the time goes, and where a frame turned the wrong way is made.

Give the parts real mass

Mass and inertia come from the parts' volumes and the material you assign. A part with no material gets a default density or none, and the description states the result as precisely as any other number in the file.

Export the package and open it here

The output is a ROS description package — URDF or xacro, the meshes, the package files. Drop the folder into the viewer: xacro is expanded on the way in, and the check runs as the robot appears.

Or skip the exporter

For a few parts the workbench is more than the job needs. Export each body from FreeCAD as STL — in millimetres, as FreeCAD writes it — and put them together in the URDF editor, which offers the 0.001 scale the moment a mesh arrives a thousand times too big, and computes each link's inertia from its mesh.

What comes out wrong, and how you find out

A CAD export produces a file that opens, renders and looks like your robot. The failures below are the ones that survive that impression and show up later as a simulation behaving strangely for no visible reason. Each is a check this site runs on a model you open — not a warning to keep in mind, a line naming the link or the joint.

A robot a thousand times too big

Millimetres where metres were meant is the commonest CAD failure there is, and FreeCAD makes it easy: anything written outside the workbench keeps FreeCAD's unit. The check states the model's size in metres and says when it is probably in millimetres.

Mass from a material nobody chose

A link given no material, or a mass with no geometry behind it, still arrives with confident numbers. Each link's implied density is compared against what robot parts are made of, in kg/m³, and the ones outside it are named.

Mesh paths that only resolve in your workspace

The package refers to its meshes by package:// paths, correct inside the ROS workspace it was written in and unresolvable anywhere else. The check lists them and says which files it could not find, so a colleague does not get an empty scene.

Collision geometry that is the whole part

A collision element that reuses the real part puts its full mesh into every contact test. The check names links whose collision shape is identical to their visual one, which is where a simulation that runs at a tenth of real time usually starts.

Check the export

The units. FreeCAD measures in millimetres and URDF in metres; the workbench converts what it writes, but a mesh exported by hand from FreeCAD keeps its millimetres, and a robot assembled from both is the classic mixed-unit file.

Drop the URDF and its mesh folder into the viewer. Nothing is installed and nothing is published; the file is read to draw it and deleted after a day. For a model out of FreeCAD, in this order:

  1. The size. Stated in metres the moment the model opens. A FreeCAD robot that reads as 400 m tall was measured in millimetres somewhere on its way out.
  2. Mass and density. Mass computed from a material is only as right as the material; a link left on a default, or given a mass with no shape behind it, shows up as a density nothing is made of.
  3. Mesh paths. The package points at its meshes through package:// paths, which resolve inside a ROS workspace and nowhere else — the panel names the ones it could not find.
  4. Collision against visual. Generated collision boxes are cheap; a collision element that reuses the full part is not.

Then send it further: convert to MJCF and run it in the physics lab, where a robot that cannot hold itself up says so in the first second — or author a movement in motion and find out whether the motors your CAD material implies can actually perform it.

Other CAD packages