OneCAD/docs/urdf.md

# URDF export

A design with components and joints exports as a robot description in URDF (Unified Robot
Description Format), the format ROS, Gazebo, Isaac Sim, PyBullet and MuJoCo read. Each part
becomes a link with its mesh, mass and inertia. Each joint becomes a URDF joint, or a short
chain of them, that moves the parts the way SolidCraft does.

- **Desktop:** **File → Export URDF…**
- **Commands:** `file.export {"path": "robot.urdf"}` (or `"format": "urdf"`)
- **MCP:** the `export` tool with a `.urdf` path or `format: "urdf"`
- **CLI:** `solidcraft-cli run script.json --out robot.urdf`

URDF always exports the whole assembly, so `bodies` is refused.

## Files

Next to `robot.urdf` the export writes one binary STL per component, in metres:

- `robot-<component>.stl` holds all of the component's bodies. The root component's bodies go
  in `robot-base.stl`.
- `robot-<component>-collision.stl` appears only when a component mixes closed solids with
  open surfaces: it holds the closed ones, which are the collision geometry.

Every path is checked before anything is written, including against the folders an agent may
use (`allow_paths`). The meshes are written first and the `.urdf` last. If a write fails part
way, the error names the files already written and the one that failed.

## Parameters

| Parameter | Default | Meaning |
|---|---|---|
| `mesh_prefix` | none | Put before each mesh file name. Leave it empty for loaders that resolve against the URDF's folder (Isaac Sim, PyBullet, MuJoCo, yourdfpy). RViz and other ROS tools need `package://<pkg>/meshes/` or an absolute folder. |
| `effort` | 1000 | Joint effort limit, in N (sliding) or N m (turning). |
| `velocity` | 10 | Joint velocity limit, in m/s or rad/s. |

URDF requires `effort` and `velocity` on every moving joint. When they are not given, the
defaults are written and a warning says so. A value that is not a positive number is refused.

## Links

- **`base_link`** holds the root component's bodies and stays fixed in the world. Every
  grounded occurrence hangs on it by a `fixed` joint at its current place.
- **One link per placement of a component.** A component placed once gives its name to the
  link (`Gripper`). One placed several times gives the occurrence names (`Finger:1` becomes
  `Finger_1`).
- **Names** use only `A-Z a-z 0-9 _` (mesh files also keep `-`). Links, joints and files share
  one set of names, because Gazebo refuses a link and a joint with the same name. A name
  already taken gets `_2`, `_3` and so on. Joint names are taken first, so a joint keeps the
  name you gave it. Mesh file names are compared without case, since Windows and macOS ignore
  it.
- **Mass and inertia** come from each body's mesh and material density: the mass in kg, the
  centre of mass and the inertia tensor about it in the link frame, in kg m². Bodies of the
  same link combine with the parallel-axis theorem.
- **Open surfaces** are drawn but add no mass or collision, with a warning naming them.
- **A link with no mass** (only surfaces, no bodies, or a chain's in-between link) gets a token
  mass of 1e-6 kg and inertia of 1e-12 kg m², because Gazebo drops massless links and breaks
  the chain there.
- **Colour:** the first body's colour, as the visual's material.

## Joints

| SolidCraft joint | URDF |
|---|---|
| Rigid | `fixed` |
| Revolute | `revolute` about z with limits, or `continuous` without |
| Slider | `prismatic` along z |
| Cylindrical | `revolute` z, then `prismatic` z |
| Pin-slot | `prismatic` x, then `revolute` z |
| Planar | `prismatic` x, `prismatic` y, then `revolute` z |
| Ball | `revolute` z, `revolute` y, then `revolute` z |

- **Chains:** a joint with several values becomes one URDF joint per value. Between them sit
  links named `<joint>_link1`, `<joint>_link2`. The steps before the last are named
  `<joint>_dof1`, `<joint>_dof2`, and the last one keeps the joint's name.
- **Values:** each URDF joint value equals the SolidCraft value it comes from: the same angle
  (in radians) or distance (in metres). This holds whichever side of the joint is nearer the
  base. When the tree reaches a joint from its B side, the chain runs backwards with its axes
  reversed, so the values still match.
- **Limits** are written as `lower <= upper` in radians or metres. A sliding step without a
  limit gets ±1000 m, since URDF requires one, with a warning.
- **Motion links** are not written as `<mimic>`. Each joint's own value is free in the URDF.

The URDF is written at the design's current joint values, with every part where it is shown,
including moves not captured yet. The exception is a part the joints place: it exports where its
joints put it, since they put it back as soon as one moves, and a warning says so. Moving a joint in a simulator puts
the parts the joint solver places where SolidCraft's **Drive Joints** would.

## The tree

URDF is a tree hanging from `base_link`. The export builds it the way the joint solver walks
the assembly.

1. From `base_link` and the grounded occurrences, it follows the joints outwards.
2. A group of parts joined to each other but to nothing grounded is fixed where it is by the
   A side of its first joint, as the solver does when nothing is grounded. A warning says the
   part is not grounded.
3. A part no joint reaches is fixed where it is. A nested one hangs on its parent part, so it
   moves with it, as in SolidCraft. A top-level one hangs on `base_link`, with a warning.
4. A joint that would close a loop is left out, with a warning, since a tree cannot hold it.
5. A joint whose snap points no longer resolve (for example, the face it was on is gone) is
   left out, with a warning naming it.

When a component is placed several times, what is nested in it appears in each placement. In
the URDF the first placement is the one its joints move; the others are copies fixed in their
parent at their current pose, with a warning when the copied part has a joint. (In SolidCraft
the copies move together, which a URDF could only express with `<mimic>`.) The export stops copying past
64 levels or 100 000 placements, with a warning.

## Not covered

- `<mimic>` for motion links.
- Simplified collision shapes: the collision mesh is the visual mesh.
- SDF and MJCF export, and URDF import.
- Joint motion inside the copies of a component placed several times.
- Drive dynamics: `effort` and `velocity` are limits you choose.