first commit

2026-07-22 13:48:46 +08:00
commit c87751c3dc
2820 changed files with 726976 additions and 0 deletions
@@ -0,0 +1,156 @@
+# 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.