URDF Studio

Search documentation

#Measure, reach and collision pairs

These tools are in the Tools tab.

#Measure a distance

  1. Click Start measuring.
  2. Click two points on the robot.

The Tools tab shows the straight-line distance in metres, the X, Y and Z differences, and both points' world coordinates. A line is drawn between the points in the 3D view. Click Clear to remove it, or Start measuring again for a new measurement.

Points snap to mesh surfaces, so you can only measure between parts of the robot, not to empty space.

#See how far the robot reaches

Reachability samples many random joint positions and records where one link ends up each time, and which way it points. The result is a map of the robot's workspace that also shows how freely the tip can be oriented at each spot.

  1. Choose the Tip link. The list shows links at the end of a chain that the joints actually move, with tool points (tcp, tool, ee, flange…) and the end of the longest moving chain first — so the default is normally right.
  2. Set the number of Samples. The default of 1,000,000 takes about a second on a typical arm. More samples give smaller cubes and steadier colours; up to 5,000,000 are allowed.
  3. Click Sample. The robot does not move while sampling.

#Reading the map

Space is divided into small cubes, and each dot is one cube the tip reached. The colour shows from how many directions it got there: the tip link's Z axis (the approach direction of a ROS tool frame) is sorted into 24 directions spread evenly around a sphere.

Colour Meaning
Purple Reached from only one or a few directions — usually the edge of the workspace
Green Reached from many directions
Yellow The best spots for this robot

The legend gives the best count, for example 17 of 24. Places with high dexterity are where the robot can approach a part from above, from the side, or at an angle — a good place for a fixture or a workpiece.

The low-dexterity shell hides the interior. Drag Hide below to show only cubes reaching at least that share of the best one, and the core appears.

The status line gives the sample time, cube size and the X, Y and Z extent of the map. Clear removes it. Samples stay within joint limits; mimic joints follow the joint they copy. Rotation around the tip's Z axis is not counted, which suits grippers and most tools.

If your tool frame's approach axis is not Z, pick a link whose Z axis points along the tool, or add a fixed tool-point link to the model.

#Save a report

Once a map is drawn, two buttons appear under it:

  • Save report (PDF) — a two-page A4 report to share or print:
    • Summary: tip link, sample count, reached volume, reach from the base axis and from the base origin, height range, best dexterity, how the volume splits by dexterity, and the 3D view.
    • Drawing: the map in front, side and top view, laid out like an engineering drawing — the views share one scale and line up with each other, with a scale bar, overall dimensions, centre lines through the robot base, the horizontal reach as a circle in the top view and the robot's outline in its current pose.
  • Save data (CSV) — every reached cube with its centre (x_m, y_m, z_m) and dexterity, for your own analysis or plots.

All coordinates are in the robot's base frame, in metres. In the drawing, each square shows the best cube along the line of sight — so the top view answers "is there a height above this spot where the tool has this much freedom?". The views follow the Up axis setting.

Where What the buttons do
Browser Download <robot>-reachability.pdf / .csv
VS Code Ask where to save, next to the robot file by default

#Collision pairs

MoveIt and other planners skip checking link pairs listed under <disable_collisions> in the SRDF. Listing pairs that can never touch makes planning much faster. This tool finds candidates for you.

  1. Make sure collision geometry is loaded: switch the view to Collision or Both once.
  2. Set Random poses — more poses means more confidence. 1,000 is a reasonable start; use 10,000 before relying on the result.
  3. Click Analyze. The tool reports how many of the possible link pairs never touched in any sampled pose, and lists them. Links attached directly to each other are left out, and so are links with no collision geometry (sensor frames, tool points), which can't collide at all.
  4. Click Write to SRDF to add them.
Where What Write to SRDF does
Browser Downloads an updated copy of your SRDF (or a new <robot>.srdf)
VS Code Adds the pairs to your SRDF in place, or asks where to create one

Pairs already in the SRDF are not added twice.

"Never touched in N random poses" is strong evidence, not proof. Review the list for pairs you know can meet — for example a gripper and the base of a folding arm.

#Screenshot and export

The Screenshot and Export sections here do the same as the toolbar's Export menu. See Save poses and export.