Jerry
106 lines
3.5 KiB
Markdown
106 lines
3.5 KiB
Markdown
# URDF Frame Semantics
|
|
|
|
Use this reference whenever editing origins, axes, visual placement, collision placement, or inertials. Most URDF generation errors are frame errors.
|
|
|
|
## Core Semantics
|
|
|
|
URDF represents a robot as a tree of links connected by joints.
|
|
|
|
For a joint:
|
|
|
|
- `<parent link="...">` names the parent link.
|
|
- `<child link="...">` names the child link.
|
|
- `<origin xyz="..." rpy="...">` is the transform from the parent link frame to the joint frame.
|
|
- The child link frame is coincident with the joint frame.
|
|
- `<axis xyz="...">` for a movable joint is expressed in the joint frame, not automatically in the world frame and not in the visual mesh frame.
|
|
|
|
For link subelements:
|
|
|
|
- `<visual><origin ...>` is expressed in the link frame.
|
|
- `<collision><origin ...>` is expressed in the link frame.
|
|
- `<inertial><origin ...>` is the center-of-mass/inertial frame expressed in the link frame.
|
|
|
|
These origins are independent. A mesh can be offset from its link frame, and the center of mass can be offset differently.
|
|
|
|
## Units and Angles
|
|
|
|
Use:
|
|
|
|
- meters for length;
|
|
- kilograms for mass;
|
|
- radians for angles;
|
|
- seconds for time;
|
|
- right-handed coordinate frames unless the project documents an exception.
|
|
|
|
Do not store revolute limits in degrees in generated URDF. Convert degrees to radians before emission.
|
|
|
|
Do not use finite lower/upper limits for a `continuous` joint unless the project is intentionally not using URDF continuous-joint semantics.
|
|
|
|
## Joint Axis Checklist
|
|
|
|
For every non-fixed joint, confirm:
|
|
|
|
1. the axis is present;
|
|
2. the axis vector has three finite numbers;
|
|
3. the vector is nonzero;
|
|
4. the vector is normalized or intentionally normalized by helper code;
|
|
5. the vector is expressed in the joint frame;
|
|
6. positive motion is documented.
|
|
|
|
Examples:
|
|
|
|
```xml
|
|
<joint name="shoulder_pan_joint" type="revolute">
|
|
<parent link="base_link" />
|
|
<child link="shoulder_link" />
|
|
<origin xyz="0 0 0.24" rpy="0 0 0" />
|
|
<axis xyz="0 0 1" />
|
|
<limit lower="-3.14159" upper="3.14159" effort="40" velocity="2" />
|
|
</joint>
|
|
```
|
|
|
|
This means the child link frame is at `z = 0.24` in `base_link`, and positive joint motion rotates about +Z of the joint/child frame.
|
|
|
|
## Visual and Collision Placement Checklist
|
|
|
|
For every visual or collision block, confirm:
|
|
|
|
1. the origin is relative to the owning link frame;
|
|
2. mesh scale converts the mesh source units into meters;
|
|
3. visual and collision geometry are intentionally the same or intentionally different;
|
|
4. collision geometry is simple enough for the intended physics/planning consumer;
|
|
5. mesh paths are stable from the generated URDF's location or use an intended package URI.
|
|
|
|
Example:
|
|
|
|
```xml
|
|
<link name="forearm_link">
|
|
<visual>
|
|
<origin xyz="0 0 0" rpy="0 0 0" />
|
|
<geometry>
|
|
<mesh filename="package://robot_description/meshes/forearm.stl" scale="0.001 0.001 0.001" />
|
|
</geometry>
|
|
</visual>
|
|
<collision>
|
|
<origin xyz="0.12 0 0" rpy="0 1.57079632679 0" />
|
|
<geometry>
|
|
<cylinder radius="0.035" length="0.24" />
|
|
</geometry>
|
|
</collision>
|
|
</link>
|
|
```
|
|
|
|
This places the visual mesh at the link frame and uses a simplified collision cylinder offset in the same link frame.
|
|
|
|
## Inertial Placement Checklist
|
|
|
|
For every physical link with inertial data, confirm:
|
|
|
|
1. mass is positive and finite;
|
|
2. inertial origin is the center of mass in the link frame;
|
|
3. inertia tensor values are in SI units;
|
|
4. tensor values correspond to the inertial frame being declared;
|
|
5. approximations are documented.
|
|
|
|
Do not infer inertial origin from visual or collision origin unless the source data proves they coincide.
|