Design Book › Format conversion

Format conversion

What a designer must do

  1. Name one source-of-truth file in the repo [1].
  2. Validate the source before you convert it. MuJoCo silently ignores mistyped URDF attributes [2].
  3. Convert angle units and read the unit metadata at each step [3], [4], [5].
  4. Compare counts and clamps after conversion [6], [7].
  5. Validate masses, inertias, collisions and joint control on the intended physics backend [8].
  6. Change a value and watch behaviour change. A value in the file does not prove the engine reads it [9].
  7. 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

What each direction can lose
From, toRiskSourceLevelCheck
URDF to MJCFOne-way workflow: convert once, then edit MJCF, unless URDF stays the maintained source[1]guidereview: repo names one source file
URDF to MJCFMistyped attributes are silently ignored[2]mustlint: schema check on URDF and its mujoco extension
URDF to MJCFstrippath, angle, fusestatic and discardvisual defaults differ from MJCF[6]shouldlint: compare compiled body and geom counts with the source
URDF to MJCFfusestatic is true for URDF and merges static bodies, which can remove sensor sites[11]shouldlint: named frames and sites exist after compile
URDF to MJCFMuJoCo's compiler rejects non-physical dynamics parameters if left unmodified[12]guidesim: compile with balanceinertia off
URDF to MJCFJoint limit effort becomes actuatorfrcrange. Keep it, or move it to the actuators' forcerange[7]mustlint: each joint has actuatorfrcrange or a bounded actuator
MJCF to URDFURDF holds only a subset of MuJoCo elements[10]guidereview: list MJCF elements with no URDF form
PhysX asset to MJWarpA value in a PhysX asset or Newton model does not prove MJWarp uses it[9]mustsim: change the value, confirm behaviour changes
PhysX asset to MJWarpDo not copy friction numbers. Verify shapes and contact, then fit to measured slip[13]mustmeasure: slide test in each backend
PhysX asset to MJWarpccd_iterations is not a CCD switch[14]mustsim: fast thin object under a Newton collision strategy
Any asset conversionValidate masses, inertias, collisions and joint control on the intended physics backend[8]mustsim: run the articulation audit on the imported USD

Structure: pick the format the robot allows

Structure: pick the format the robot allows
LevelCaseActionCheckSource
shouldRobot with more than one baseMuJoCo 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 freedomreview[15]
mustClosed kinematic loopBreak it into a tree with closure constraints. Check that the target format keeps themsim: move it and measure closure error[16]
shouldOnshape gear relationClick the source joint first, then the target jointsim: 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].

CAD to model
LevelTrapCheckSource
mustA mate without the special prefix is ignoredreview: exported joint count against intended degrees of freedom[18]
shouldAn orphaned link becomes fixed to the base, with only a warningreview: export log holds no such warning[19]
shouldJoint direction can differ from the mate. Use the inv suffixmeasure: jog each real joint positive, compare with the model[20]
shouldignore_limits drops the CAD joint limitsreview: exported limits match the mates[21]

Convention table

Check these at every boundary. Blank means the database has no guideline on that cell.

Convention table
ItemURDFMJCFSDFUSD
Angle unitRadians [22]Degrees by default. Its check sets compiler/angle [3]One-dimensional angles in degrees [4]
Length, mass unitMetres, kilograms [23]No fixed system; prefer MKS [24]Per-layer metersPerUnit, kilogramsPerUnit [5]
Pose frameJoint at child link origin [25]Local to the parent [26]Axis in joint frame unless expressed_in says otherwise [27]
InertiaAbout center of mass [28]Valid only if A + B >= C [29]Products use -m x y [30]Authored mass overrides density [31]
Effort limitRequired field [32]actuatorfrcrange or forcerange [7]Negative means not enforced [33]
Multiple basesNo [15]Yes [15]Yes [15]

Post-conversion checklist

  1. Compiled body and geom counts match the source [6].
  2. Named frames and sensor sites exist [11].
  3. Each joint keeps an effort bound [7].
  4. Limits match after unit conversion [4].
  5. Total mass and bounding box match the measured robot [34].
  6. Forward kinematics at zero matches CAD [25].
  7. No placeholder inertia warning remains [35].
  8. Articulation audit is recorded [36], [8].
  9. 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:

On the SO-101
FormatLibraryPath
MJCFmujoco_menagerierobotstudio_so101
URDFrobot_descriptions.pyso_arm101_description
MJCFrobot_descriptions.pyso_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

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.

  1. 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
  2. Validate URDF files separately before MuJoCo loads them, because mistyped attributes are silently ignored. Level: must. mujoco.readthedocs.io 2026-11-08
  3. MJCF angles default to degrees, while URDF input is always parsed as radians. Level: guide. mujoco.readthedocs.io 2026-11-08
  4. 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
  5. 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
  6. Check strippath, angle, fusestatic and discardvisual after URDF import, because their defaults differ from MJCF. Level: should. mujoco.readthedocs.io 2026-11-08
  7. 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
  8. 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”
  9. 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.”
  10. URDF can represent only a subset of the model elements available in MuJoCo. Level: guide. mujoco.readthedocs.io 2026-11-08
  11. 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
  12. MuJoCo's compiler rejects non-physical URDF dynamics parameters if left unmodified. Level: guide. mujoco.readthedocs.io 2026-11-08
  13. 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.”
  14. 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.”
  15. 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
  16. 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
  17. When exporting Onshape gear relations, click the source joint first, then the target joint. Level: should. onshape-to-robot.readthedocs.io 2026-11-08
  18. 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
  19. 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
  20. 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
  21. 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
  22. 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.”
  23. 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.”
  24. 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
  25. 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”
  26. Treat MJCF positions and orientations as local to the parent, not as world values. Level: must. mujoco.readthedocs.io 2026-11-08
  27. 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.”
  28. 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)”
  29. 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
  30. 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”
  31. 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
  32. Every URDF limit element needs both effort and velocity values. Level: must. wiki.ros.org 2026-11-08“velocity (required)”
  33. 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.”
  34. Before any tuning, check mesh scale and total mass to catch a millimetre-for-metre mistake. Level: must. mujoco.readthedocs.io 2026-11-08
  35. 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”
  36. 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.”
  37. Compare CAD against the as-built robot as part of gap measurement. Level: should. docs.nvidia.com 2026-11-08
  38. 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.”
  39. Set each simulated joint's maximum force from the actuator specification when one exists. Level: should. docs.omniverse.nvidia.com 2026-11-08
  40. 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,”