Jerry
157 lines
6.1 KiB
Markdown
157 lines
6.1 KiB
Markdown
# URDF Generation-Time Validation
|
|
|
|
Use this reference to understand what generated URDFs should satisfy. The `scripts/urdf` generation path validates by default; there is no separate validation-only command in this skill.
|
|
|
|
Validation is a guardrail, not a substitute for a design ledger or visual/consumer smoke test. A URDF can pass structural checks while still having incorrect spatial assumptions.
|
|
|
|
Generated or modified `.urdf` files should be handed to `$cad-viewer` for live viewer links when available.
|
|
|
|
## Structural Checks
|
|
|
|
Validate that:
|
|
|
|
- the root element is `<robot>`;
|
|
- the robot has a non-empty name;
|
|
- every link has a unique non-empty name;
|
|
- every joint has a unique non-empty name;
|
|
- every joint has valid parent and child fields;
|
|
- parent and child links exist;
|
|
- each child link has at most one parent;
|
|
- the graph has exactly one root link;
|
|
- the graph is connected and acyclic;
|
|
- the tree has exactly `links - 1` joints unless the design intentionally uses a different structure and the runtime supports it.
|
|
|
|
## Origin Checks
|
|
|
|
For each joint, visual, collision, and inertial origin, validate or review that:
|
|
|
|
- `xyz` has three finite numeric values when present;
|
|
- `rpy` has three finite numeric values when present;
|
|
- omitted values follow the URDF default only when that is intentional;
|
|
- units are meters for `xyz` and radians for `rpy`;
|
|
- the origin is expressed in the correct frame.
|
|
|
|
Frame correctness must be reviewed from the design ledger. XML validation alone cannot prove that an origin is spatially correct.
|
|
|
|
## Joint Checks
|
|
|
|
The current `scripts/urdf` source reader supports these joint types:
|
|
|
|
- `fixed`
|
|
- `continuous`
|
|
- `revolute`
|
|
- `prismatic`
|
|
|
|
Some URDF consumers also support `floating` and `planar`; use them only when the project runtime and validation path support them. The current `scripts/urdf` reader rejects them.
|
|
|
|
For non-fixed joints, validate or review that:
|
|
|
|
- `<axis>` exists where required;
|
|
- axis has exactly three finite numeric values;
|
|
- axis is nonzero;
|
|
- axis is normalized or intentionally normalized by generator code;
|
|
- axis is expressed in the joint frame;
|
|
- positive motion is documented in the design ledger.
|
|
|
|
For limits:
|
|
|
|
- `revolute` lower/upper limits are radians;
|
|
- `prismatic` lower/upper limits are meters;
|
|
- lower is not greater than upper;
|
|
- effort and velocity are finite when present;
|
|
- `continuous` joints do not use artificial finite lower/upper limits;
|
|
- `fixed` joints do not need motion limits.
|
|
|
|
## Geometry Checks
|
|
|
|
General URDF visual and collision geometry may use:
|
|
|
|
- `<mesh>`
|
|
- `<box>`
|
|
- `<cylinder>`
|
|
- `<sphere>`
|
|
|
|
The current `scripts/urdf` validation path allows these geometry types for both visual and collision geometry.
|
|
|
|
For geometry, validate or review that:
|
|
|
|
- each visual or collision block has a `<geometry>` element;
|
|
- each geometry block has exactly one supported geometry child;
|
|
- primitive dimensions are positive and finite;
|
|
- mesh filenames are non-empty;
|
|
- mesh scale, when present, has three positive finite values;
|
|
- visual and collision origins are relative to the owning link frame;
|
|
- collision geometry is appropriate for the target consumer.
|
|
|
|
## Mesh Reference Checks
|
|
|
|
For mesh references, distinguish syntax, local existence, and runtime package resolution.
|
|
|
|
Validate or review that:
|
|
|
|
- local relative and absolute paths are intentional;
|
|
- local files exist when filesystem validation is available;
|
|
- `package://...` URIs have valid syntax;
|
|
- package URIs are not incorrectly assumed to resolve from the current working directory;
|
|
- the consuming ROS or simulator environment can resolve package URIs;
|
|
- mesh source units and emitted scale convert to meters.
|
|
|
|
The current source reader accepts any non-empty mesh filename or URI. It resolves local mesh paths from the generated URDF file's directory and verifies those files exist. It accepts unresolved `package://...` and remote references with warnings, because final mesh-format support is consumer-specific.
|
|
|
|
If mesh references changed, confirm the corresponding mesh outputs were regenerated separately by the owning CAD or mesh workflow.
|
|
|
|
## Inertial Checks
|
|
|
|
For each physical link with mass or geometry, prefer an explicit `inertial` block:
|
|
|
|
- `origin` is the center of mass in the link frame;
|
|
- `mass` is positive and finite;
|
|
- `inertia` defines `ixx`, `ixy`, `ixz`, `iyy`, `iyz`, and `izz`;
|
|
- all inertia values are finite;
|
|
- diagonal inertia values are positive;
|
|
- the inertia matrix is physically plausible for the intended approximation;
|
|
- approximations are documented.
|
|
|
|
Frame-only links may intentionally omit `inertial`. Physical links with omitted inertials should be called out when the target consumer uses simulation or dynamics.
|
|
|
|
## URDF Validity vs Project Policy
|
|
|
|
Separate general URDF validity from project-specific policy.
|
|
|
|
Examples of general URDF validity or sanity checks:
|
|
|
|
- unique links and joints;
|
|
- valid tree structure;
|
|
- valid joint parent/child references;
|
|
- finite origins;
|
|
- nonzero movable-joint axes;
|
|
- positive primitive dimensions;
|
|
- positive mass for physical inertial blocks.
|
|
|
|
Examples of project policy checks:
|
|
|
|
- visual mesh references must use a specific extension;
|
|
- visual geometry must be mesh-only;
|
|
- collision geometry must be primitive-only;
|
|
- mesh files must live under a specific directory;
|
|
- every physical link must have collision geometry;
|
|
- every physical link must have inertial data;
|
|
- package URIs must use a specific package prefix.
|
|
|
|
When a generated URDF fails because of project policy, report it as policy failure, not as universal URDF invalidity.
|
|
|
|
## Failure Handling
|
|
|
|
When generation-time validation fails:
|
|
|
|
1. fix the generator source, design ledger, or referenced assets;
|
|
2. regenerate the explicit URDF target;
|
|
3. do not hand-edit the generated `.urdf` as a permanent fix;
|
|
4. record any remaining assumptions or unchecked spatial claims.
|
|
|
|
## Tooling
|
|
|
|
Use `scripts/urdf/source.py` through the `urdf.source.read_urdf_source()` helper for compact robot/link/joint checks when writing tests or focused checks.
|
|
|
|
The URDF source reader is a lightweight standard-library validator. It checks the generated subset used by this skill; consumer-specific parser and mesh-loading compatibility should still be smoke-tested in the target runtime when confidence matters.
|