pathon-ai/pathonroboticsoss/mjcf-to-urdf

mjcf-to-urdf

Wrap convert_mjcf_urdf.py --to-urdf (which uses mjcf-urdf-simple-converter). Lower-priority skill in the bundle — URDF→MJCF is the direction we usually want, since MJCF is more expressive. The reverse is for downstream tools that don't speak MJCF.

The conversion preserves the kinematic tree (links, joints, parent/child, visual/collision meshes, joint limits) but drops several MJCF-only features:

1. `<equality>` constraints disappear. Any joint coupling expressed

as polycoef (the MJCF equivalent of URDF mimic joints) is lost. Joints that should be coupled become independent in the URDF.

1. Actuators are dropped. URDF has no actuator concept — joints

exist, nothing drives them. Downstream consumers must add their own joint controllers.

1. Contact excludes don't survive. URDF has no contact-exclusion

element. Anything that was excluded becomes an active collision pair in the URDF — usually fine for a visualization consumer like RViz, but breaks anything doing physics from the URDF.

1. Keyframes are dropped. Any rest-pose snapshots in the MJCF are

discarded.

1. Position actuators with `kp`/`kv` are dropped. Any tuning is

lost; the URDF has no analog.

The output is for kinematic visualization or planning, not dynamics. If the consumer simulates from the URDF, they'll get wrong results.

When to use this skill

• A downstream consumer (RViz, pinocchio, MoveIt, IK libraries) needs

a URDF and the canonical model is MJCF.

• You only need the kinematic tree: forward kinematics, IK, collision

visualization. You don't need dynamics fidelity.

When NOT to use this skill

• You need to simulate dynamics from the URDF — converting will look

fine but produce wrong physics. Re-export from the MJCF source each time, or use urdf-to-mjcf in reverse only after re-tuning.

• A URDF version of the robot already exists upstream — adopt that

instead. A hand-maintained URDF is almost always more accurate than one auto-converted from MJCF.

• The MJCF uses <equality> constraints that the consumer needs (e.g.

underactuated hand) — the consumer will silently get the wrong kinematics. In this case, regenerate the URDF from the original source (not from the MJCF), or document the lost coupling in the URDF comments.

Workflow

1. Confirm the consumer actually needs URDF. Many tools support

MJCF directly (mink, mujoco-python-viewer, IsaacSim) — skip this skill if so.

1. Check upstream for a hand-maintained URDF. If one exists, use

it. Don't auto-convert.

1. Run the converter (see Commands).
2. Verify mesh paths. The converter may produce

meshdir-relative paths that don't resolve under URDF's normal package:// or relative-to-URDF conventions. Manually inspect.

1. Document what was lost in the URDF's leading comment so future

readers know they're looking at a partial representation.

Commands

Run from the bundle root with the bundle-local venv. Pass an absolute input path so the script doesn't try to resolve it relative to the parent repo:

cd robot-assets-skills/
./.venv/bin/python ../convert_mjcf_urdf.py \
    "$(pwd)/robots/<robot>/<robot>.xml" --to-urdf

By default the output goes to the same directory with .urdf extension. To pick an explicit output path:

./.venv/bin/python ../convert_mjcf_urdf.py \
    "$(pwd)/robots/<robot>/<robot>.xml" \
    "$(pwd)/robots/<robot>/<robot>.urdf"

Verify the URDF parses:

./.venv/bin/python -c "
import mujoco
m = mujoco.MjModel.from_xml_path('robots/<robot>/<robot>.urdf')
print('nq=', m.nq, 'nu=', m.nu, 'nbody=', m.nbody)
"

nu = 0 is expected — URDF has no actuators. Anything in the source MJCF's <actuator> block is gone.

If .venv/ is missing or broken, bootstrap per AGENTS.md's "Python environment" section.

References

• Step-by-step procedure: references/workflow.md
• The losses with concrete examples: references/gotchas.md