Format conversion
What a designer must do
- Name one source-of-truth file in the repo [1].
- Validate the source before you convert it. MuJoCo silently ignores mistyped URDF attributes [2].
- Convert angle units and read the unit metadata at each step [3], [4], [5].
- Compare counts and clamps after conversion [6], [7].
- Validate masses, inertias, collisions and joint control on the intended physics backend [8].
- Change a value and watch behaviour change. A value in the file does not prove the engine reads it [9].
- Rerun the description checklist on the output.
Scope: the format-conversion guidelines and the related unit guidelines. A conversion can lose data and say nothing [10], [2], so treat a converted model as unverified until a test shows otherwise.
What each direction can lose
| From, to | Risk | Source | Level | Check |
|---|---|---|---|---|
| URDF to MJCF | One-way workflow: convert once, then edit MJCF, unless URDF stays the maintained source | [1] | guide | review: repo names one source file |
| URDF to MJCF | Mistyped attributes are silently ignored | [2] | must | lint: schema check on URDF and its mujoco extension |
| URDF to MJCF | strippath, angle, fusestatic and discardvisual defaults differ from MJCF | [6] | should | lint: compare compiled body and geom counts with the source |
| URDF to MJCF | fusestatic is true for URDF and merges static bodies, which can remove sensor sites | [11] | should | lint: named frames and sites exist after compile |
| URDF to MJCF | MuJoCo's compiler rejects non-physical dynamics parameters if left unmodified | [12] | guide | sim: compile with balanceinertia off |
| URDF to MJCF | Joint limit effort becomes actuatorfrcrange. Keep it, or move it to the actuators' forcerange | [7] | must | lint: each joint has actuatorfrcrange or a bounded actuator |
| MJCF to URDF | URDF holds only a subset of MuJoCo elements | [10] | guide | review: list MJCF elements with no URDF form |
| PhysX asset to MJWarp | A value in a PhysX asset or Newton model does not prove MJWarp uses it | [9] | must | sim: change the value, confirm behaviour changes |
| PhysX asset to MJWarp | Do not copy friction numbers. Verify shapes and contact, then fit to measured slip | [13] | must | measure: slide test in each backend |
| PhysX asset to MJWarp | ccd_iterations is not a CCD switch | [14] | must | sim: fast thin object under a Newton collision strategy |
| Any asset conversion | Validate masses, inertias, collisions and joint control on the intended physics backend | [8] | must | sim: run the articulation audit on the imported USD |
Structure: pick the format the robot allows
| Level | Case | Action | Check | Source |
|---|---|---|---|---|
| should | Robot with more than one base | MuJoCo and SDF support it; URDF does not. Pick one of those, or split into several URDF files. A dummy base link fixes the bases with no freedom | review | [15] |
| must | Closed kinematic loop | Break it into a tree with closure constraints. Check that the target format keeps them | sim: move it and measure closure error | [16] |
| should | Onshape gear relation | Click the source joint first, then the target joint | sim: drive the source, read the target | [17] |
CAD to model
The guidelines here cover onshape-to-robot, from its docs under the latest alias with no version shown [18].
| Level | Trap | Check | Source |
|---|---|---|---|
| must | A mate without the special prefix is ignored | review: exported joint count against intended degrees of freedom | [18] |
| should | An orphaned link becomes fixed to the base, with only a warning | review: export log holds no such warning | [19] |
| should | Joint direction can differ from the mate. Use the inv suffix | measure: jog each real joint positive, compare with the model | [20] |
| should | ignore_limits drops the CAD joint limits | review: exported limits match the mates | [21] |
Convention table
Check these at every boundary. Blank means the database has no guideline on that cell.
| Item | URDF | MJCF | SDF | USD |
|---|---|---|---|---|
| Angle unit | Radians [22] | Degrees by default. Its check sets compiler/angle [3] | One-dimensional angles in degrees [4] | |
| Length, mass unit | Metres, kilograms [23] | No fixed system; prefer MKS [24] | Per-layer metersPerUnit, kilogramsPerUnit [5] | |
| Pose frame | Joint at child link origin [25] | Local to the parent [26] | Axis in joint frame unless expressed_in says otherwise [27] | |
| Inertia | About center of mass [28] | Valid only if A + B >= C [29] | Products use -m x y [30] | Authored mass overrides density [31] |
| Effort limit | Required field [32] | actuatorfrcrange or forcerange [7] | Negative means not enforced [33] | |
| Multiple bases | No [15] | Yes [15] | Yes [15] |
Post-conversion checklist
- Compiled body and geom counts match the source [6].
- Named frames and sensor sites exist [11].
- Each joint keeps an effort bound [7].
- Limits match after unit conversion [4].
- Total mass and bounding box match the measured robot [34].
- Forward kinematics at zero matches CAD [25].
- No placeholder inertia warning remains [35].
- Articulation audit is recorded [36], [8].
- One value per imported attribute class changes behaviour when edited [9].
On the SO-101
The database holds these descriptions for the SO-ARM101, all Apache-2.0:
| Format | Library | Path |
|---|---|---|
| MJCF | mujoco_menagerie | robotstudio_so101 |
| URDF | robot_descriptions.py | so_arm101_description |
| MJCF | robot_descriptions.py | so_arm101_mj_description |
Pick one as the source of truth and record it [1]. The database does not show whether these files agree with each other, so compare them with your built arm [37]. If your servos are 12 V, check that the force limits match them [38], [39].
Where the database is thin
- The Isaac Sim importer guidelines describe its URDF and MJCF importers. Most rest on notes in the Isaac Sim repo, not on the docs site, which stays held. See Isaac Sim and Isaac Lab.
- The
modelstable has no USD row. Isaac Lab ships a default SO-101 asset [40], but no test here compares it with a built arm. - No guideline gives a tolerance for a kinematics or mass comparison. Set your own, and record it.
- SDF rows are sparse: no guideline states SDF length or angle units.
Sources
Each guideline in this chapter with its source, the date it was read and the exact words of the source. Level: must means breaking it causes failure or harm, should is good practice, guide is a rule of thumb.
- Convert URDF to MJCF once and then edit the MJCF, unless the URDF stays the maintained source. Level: guide. mujoco.readthedocs.io 2026-11-08
- Validate URDF files separately before MuJoCo loads them, because mistyped attributes are silently ignored. Level: must. mujoco.readthedocs.io 2026-11-08
- MJCF angles default to degrees, while URDF input is always parsed as radians. Level: guide. mujoco.readthedocs.io 2026-11-08
- In USD physics, convert radian limits and angular values to degrees, because the schema reads one-dimensional angles in degrees. Level: must. openusd.org 2026-11-08
- Check the unit metadata of every USD file composed into a robot stage, because each referenced file can carry different units. Level: should. openusd.org 2026-11-08
- Check strippath, angle, fusestatic and discardvisual after URDF import, because their defaults differ from MJCF. Level: should. mujoco.readthedocs.io 2026-11-08
- After URDF to MJCF conversion, keep the joint effort clamp or move it to the actuators' forcerange; do not lose it. Level: must. mujoco.readthedocs.io 2026-11-08
- After asset conversion, validate masses, inertias, collisions and joint control on the intended physics backend. Level: must. isaac-sim.github.io 2026-11-08“Validate masses, inertias, collisions and joint control on”
- Confirm by test that MJWarp uses an imported attribute; finding the value in a PhysX asset or in the Newton model does not show this. Level: must. isaac-sim.github.io 2026-11-08“A value present in a PhysX asset or imported Newton model is not proof that MJWarp consumes it.”
- URDF can represent only a subset of the model elements available in MuJoCo. Level: guide. mujoco.readthedocs.io 2026-11-08
- Confirm that sensor sites survive URDF import, because fusestatic defaults to true there and merges static bodies. Level: should. mujoco.readthedocs.io 2026-11-08
- MuJoCo's compiler rejects non-physical URDF dynamics parameters if left unmodified. Level: guide. mujoco.readthedocs.io 2026-11-08
- Do not copy PhysX friction numbers into MJWarp; verify shapes and contact first, then fit friction to measured slip. Level: must. isaac-sim.github.io 2026-11-08“Do not copy PhysX friction settings numerically.”
- Do not read MJWarp ccd_iterations as a CCD switch when porting a PhysX task that used CCD. Level: must. isaac-sim.github.io 2026-11-08“MJWarp’s ccd_iterations is not a CCD switch.”
- URDF has no multiple base links, while MuJoCo and SDF do: pick one of those formats for such a robot, or split it into several URDF files. A dummy base link fixes the bases with no freedom. Level: should. onshape-to-robot.readthedocs.io 2026-11-08
- Break a closed kinematic loop into a tree with closure constraints, and check that the target format keeps them. Level: must. onshape-to-robot.readthedocs.io 2026-11-08
- When exporting Onshape gear relations, click the source joint first, then the target joint. Level: should. onshape-to-robot.readthedocs.io 2026-11-08
- When exporting with onshape-to-robot, name every kinematic mate with its special prefix, because other mates are ignored. Level: must. onshape-to-robot.readthedocs.io 2026-11-08
- Treat an orphaned-link warning from onshape-to-robot as an error to resolve, because that link becomes fixed to the base. Level: should. onshape-to-robot.readthedocs.io 2026-11-08
- Verify each exported joint direction; use the onshape-to-robot inv suffix when a joint must turn opposite to the CAD mate. Level: should. onshape-to-robot.readthedocs.io 2026-11-08
- Set the ignore_limits export option only on purpose, because it drops the CAD joint limits from the model. Level: should. onshape-to-robot.readthedocs.io 2026-11-08
- Read URDF rpy as fixed-axis rotations in radians: roll about x, then pitch about y, then yaw about z. Level: must. wiki.ros.org 2026-11-08“first roll around x, then pitch around y and finally yaw around z. All angles are specified in radians.”
- In a ROS-facing model, state length in metres, mass in kilograms, time in seconds and angle in radians. Level: must. ros.org 2026-11-08“We have chosen to standardize on SI units.”
- MuJoCo fixes no unit system, so choose one consistent system for each MJCF file, and prefer MKS because the engine's defaults assume it. Level: should. mujoco.readthedocs.io 2026-11-08
- Author a URDF joint origin as the parent-to-child transform; the joint sits at the child link origin. Level: must. wiki.ros.org 2026-11-08“The joint is located at the origin of the child link”
- Treat MJCF positions and orientations as local to the parent, not as world values. Level: must. mujoco.readthedocs.io 2026-11-08
- An SDF joint axis uses the joint frame unless expressed_in names another frame. Level: guide. sdformat.org 2026-11-08“The axis is expressed in the joint frame unless a different frame is expressed in the expressed_in attribute.”
- Author URDF inertia about the link's center of mass, not about the link origin. Level: must. wiki.ros.org 2026-11-08“about Co (the link’s center of mass)”
- Each body's principal inertias must satisfy A+B>=C in all permutations, or MuJoCo rejects the model. Level: must. mujoco.readthedocs.io 2026-11-08
- Check the sign of products of inertia when moving data into SDF, because the spec uses the -m x y convention. Level: must. sdformat.org 2026-11-08“the product of inertia convention -m x y (not +m x y) is used”
- In USD, remember that an authored mass overrides density, so a density edit has no effect on a body with explicit mass. Level: should. openusd.org 2026-11-08
- Every URDF limit element needs both effort and velocity values. Level: must. wiki.ros.org 2026-11-08“velocity (required)”
- Do not write a negative SDF effort value unless you want no limit, because SDF then does not enforce it. Level: must. sdformat.org 2026-11-08“Limit is not enforced if value is negative.”
- Before any tuning, check mesh scale and total mass to catch a millimetre-for-metre mistake. Level: must. mujoco.readthedocs.io 2026-11-08
- An importer warning about placeholder inertia means the model is wrong; fix it before any further work. Level: must. isaac-sim.github.io 2026-11-08“Treat a placeholder inertia warning as a modeling failure”
- Before simulating a new USD asset, verify its articulation root, fixed-base form, joint merging, joint types, axes and limits. Level: must. isaac-sim.github.io 2026-11-08“Verify the articulation root, fixed-base representation, fixed-joint merging, nested rigid bodies, joint types, axes, and limits.”
- Compare CAD against the as-built robot as part of gap measurement. Level: should. docs.nvidia.com 2026-11-08
- The STS3215 7.4 V version is rated at 16.5 kg·cm stall torque at 6 V; the 12 V version is rated at 30 kg·cm. Level: guide. github.com 2026-11-08“The 12V version has a stall torque of 30kg.cm.”
- Set each simulated joint's maximum force from the actuator specification when one exists. Level: should. docs.omniverse.nvidia.com 2026-11-08
- The default SO-101 asset in Isaac Lab v3.0.0 takes actuator gains from the USD, with stiffness and damping set to None in the implicit actuator group. Level: guide. raw.githubusercontent.com 2026-11-09“stiffness=None,”