#Measure, reach and collision pairs
These tools are in the Tools tab.
#Measure a distance
- Click Start measuring.
- 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.
- 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. - 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.
- 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.
- Make sure collision geometry is loaded: switch the view to Collision or Both once.
- Set Random poses — more poses means more confidence. 1,000 is a reasonable start; use 10,000 before relying on the result.
- 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.
- 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.