Why URDF is not enough
URDF gives you the kinematic tree, joint limits, visual meshes, and collision meshes. cuRobo needs two extra layers for fast GPU planning: collision spheres fitted to each link and a self-collision ignore matrix. The official RobotBuilder pipeline generates both and exports a YAML or XRDF config consumed by FK, IK, motion planning, and MPC.
Prepare the URDF
Before running the builder, inspect three things:
- Joint axes point in the expected direction.
- Mesh paths do not depend on a local ROS 2 workspace.
- Collision meshes are simple enough, or visual meshes can be approximated with spheres.
A clean layout:
my_arm_description/
urdf/my_arm.urdf
meshes/base.stl
meshes/link1.stl
meshes/link2.stl
If the URDF uses package://my_arm_description/meshes/link1.stl, point --asset-path to the parent directory that contains my_arm_description.
Run the builder
python -m curobo.examples.getting_started.build_robot_model \
--urdf /workspace/my_arm_description/urdf/my_arm.urdf \
--asset-path /workspace \
--output /workspace/curobo_configs/my_arm.yml \
--compute-metrics \
--visualize
The Viser viewer runs at http://localhost:8080 by default. On a headless Jetson:
ssh -L 8080:localhost:8080 robot@jetson
Read sphere-fitting metrics
Do not stop at "created successfully". Inspect per-link metrics:
| Metric | Meaning | Action |
|---|---|---|
cover% |
How much of the mesh is covered | Increase sphere density if low |
protr% |
Sphere volume outside the mesh | Increase protrusion weight if high |
gap_mm |
Largest uncovered gap | Dangerous around grippers and fingers |
vol_ratio |
Sphere volume versus mesh volume | Too high causes false collisions |
False collision near the base and wrist is common. Clip base spheres if they intersect the table:
python -m curobo.examples.getting_started.build_robot_model \
--urdf /workspace/my_arm_description/urdf/my_arm.urdf \
--asset-path /workspace \
--output /workspace/curobo_configs/my_arm.yml \
--clip-link base_link z 0.0 \
--sphere-density 1.5 \
--compute-metrics
The self-collision matrix is not a safety waiver
The ignore matrix skips link pairs that are adjacent or unreachable under valid joint limits. If the URDF limits are wrong, the matrix is wrong. Before trusting it, random-sample joint positions and visualize extreme postures: folded elbow, rotated wrist, and gripper near forearm.
Pass/fail criteria
A robot arm config should pass:
- cuRobo FK matches TF/URDF visualization within a small tolerance.
- IK succeeds for home, pre-grasp, and five boundary workspace poses.
- Self-collision detects truly folded postures.
- Base/table contact does not create false positives at home.
- The YAML config is versioned with the URDF revision or artifact hash.
Conclusion
Robot modeling is the foundation. Bad sphere fitting makes every downstream planner either too conservative or unsafe. Next we will validate FK, IK, quaternion convention, frame names, and joint order.
