Transform Onshape Urdf

Transform ONShape URDF → aligned model

Turns a raw ONShape YAM-family export into the clean form established by yam.urdf (commit 8975c25). This was one script (transform_onshape_urdf.py); it is now two, split around a mandatory visual-inspection checkpoint so the heading rotation -- a human judgment -- is never applied as a default guess:

• scripts/normalize_onshape_urdf.py — stage 1, deterministic cleanup (meshes, joint names, remove root, bake R0). No heading.
• scripts/view_urdf.py — stage 2, the checkpoint: render the normalized model in MuJoCo with world axes and ask the user which heading correction is needed.
• scripts/apply_urdf_heading.py — stage 3, apply the user's rotation to the base (mesh + inertia together) and the arm.

The shared math/XML helpers live in scripts/urdf_align_lib.py.

The downstream URDF→MJCF alignment (regenerate the .xml, then re-sync gripper mounts) is owned by .agents/skills/align-urdf-mjcf/SKILL.md. Treat the URDF as the source of truth; regenerate the .xml (MJCF) from the fixed URDF.

When to use

• A fresh ONShape export needs to become a usable URDF: <robot name="urdf_top_assembly">, package://.../meshes/Name.stl paths, a root link above base, dof_joint0..N joints, and duplicate link*_1 / 分组 / 紧固 structural joints.
• You need to drop a synthetic root and re-home the base heading without disturbing the arm.
• You need to re-run normalization safely (it must be a no-op the second time).

Run it

# Stage 1 — normalize (deterministic; edits in place):
python .agents/skills/transform-onshape-urdf/scripts/normalize_onshape_urdf.py <path/to/model.urdf> \
    [--assets-dir assets] [--name NAME] [--dry-run] [--force]

# Stage 2 — inspect (required checkpoint):
python .agents/skills/transform-onshape-urdf/scripts/view_urdf.py <path/to/model.urdf>   # or --screenshot out.png (headless)

# Stage 3 — apply the user's heading (previews by default; --apply writes):
python .agents/skills/transform-onshape-urdf/scripts/apply_urdf_heading.py <path/to/model.urdf> --axis z --deg <N> [--apply]

• normalize --name defaults to the URDF's parent dir name, skipping a vN version dir (arm/yam/v1/yam.urdf -> yam). Pass it explicitly when the export sits somewhere unrelated.
• normalize --dry-run prints the verification report and the resulting base + joint1, writing nothing. Always dry-run first.
• apply_urdf_heading writes only with --apply; without it, it previews. Different YAM arms need different headings (each export's baked R0 differs) — inspect and confirm visually. Common case is a yaw about world Z; yam_pro needed 0°.

Stage 1 — the transform (what normalize_onshape_urdf.py does)

RPY convention (URDF): R = Rz(yaw) @ Ry(pitch) @ Rx(roll).

1. Keep only the actuated chain. The real kinematic tree is the dof_joint* joints. Drop every other joint (分组/紧固/fastened duplicates) and every link not on that chain. Rename the survivors to canonical names by stripping a trailing _<n> (base_1→base, link2_1→link2, gripper_1→gripper, tip_right_1→tip_right), and rename the base link to base whatever the export called it (ultra_base→base). The base is identified structurally as the parent of dof_joint1, never by name — an export that names it after the product would otherwise slip past step 3's child == "base" guard (reported as "synthetic root already removed") and be rejected by every downstream stage, all of which require the name base.
2. Fix meshes. Rewrite each reference to assets/<file>, preferring an exact case-insensitive match on disk, else the suffix-stripped lowercase name with step 1's link renames applied to the stem (Gripper.stl→gripper.stl, link5_1.stl→link5.stl, ultra_base.stl→base.stl) — a link and its mesh are always renamed together.
3. Remove the synthetic root, baking R0. The synthetic root is the parent of the joint whose child is base (in a raw export that is dof_joint0, root -> base). Capture its rotation R0 = Rz(yaw)Ry(pitch)Rx(roll), delete the root link and that joint, and left-multiply R0 into the base visual origin, the base inertial origin (position + rpy), and the base -> link1 joint origin. The inertia tensor components and every joint's local axis are unchanged; joints 2..N are untouched, so the arm rotates rigidly. Rotating the base mesh and its inertia by the same R0 keeps them consistent. Guard: if no joint has child base, the root is already gone and this step is skipped — it never re-bakes and never mistakes a rootless base for a synthetic root.
4. Rename joints dof_jointN → jointN; set the robot name.
5. Insert an onshape-normalize: marker recording R0 and that a heading is still pending.

No heading is applied here. That is stage 3, gated by the checkpoint.