Skip to content
WE BUILDHUMANOIDS

GUIDE · 6 MIN READ

URDF and MJCF models of humanoid robots

How URDF and MJCF humanoid models are published and loaded, what they contain, and what to check before trusting one in simulation.

CHECKED AUTOMATICALLY AGAINST ITS SOURCES · · DRAFTED WITH AI ASSISTANCE FROM THE CITED SOURCES

For: People who build, program or evaluate humanoid robots and need a simulation-ready model of a robot.

What a robot description contains

URDF, the Unified Robot Description Format, is the ROS robot description file. In the Open-X-Humanoid repository for the Tien Kung humanoid, the URDF files define the mechanical structure, the joint limits, the mass distribution and the inertial parameters, and the repository says they suit ROS and Gazebo simulation and research on motion planning and control. [6]

In MuJoCo Menagerie, each model directory holds the MJCF definition in a `<model>.xml` file, next to an `assets` folder with the 3D meshes used for visual and collision purposes. [1]

Menagerie keeps the model file separate from the world it sits in. The model file describes only the robot, with no other entity in the kinematic tree, while a `scene.xml` file includes it together with a plane, a light source and possibly other objects. [1]

Not every description is a static URDF file. In the robot_descriptions Python package, a description can define `XACRO_PATH`, with optional `XACRO_ARGS`, instead of a static `URDF_PATH`. When such a description is loaded, the package renders the Xacro to a cached URDF. [2]

Where humanoid models come from

  • **A repository for one robot family.** The A3-A3U-robot-model repository provides URDF, MJCF and RViz files for the A3 series of humanoid robots, and SRDF files for the A3 Ultra versions, for use in ROS, ROS 2, MuJoCo and MoveIt. Its content is mainly static model resources, and the README says it does not include controllers, drivers or launch scripts. [5] PNDbotics publishes URDF and MJCF descriptions with mesh assets for its models, among them the Adam variants. [4]
  • **A research group's release.** The Berkeley Humanoid Lite documentation lists a separate repository of robot description assets in URDF, MJCF and USD, alongside its CAD models and control code. [7] The robotology project maintains URDF and SDF models of the iCub humanoid robots. [3]
  • **A curated or aggregated collection.** Google DeepMind curates MuJoCo Menagerie, which includes humanoids such as Unitree H1 and Booster T1. [1] The robot_descriptions package imports open source robot descriptions as Python modules and lists humanoids from several makers. [2]

Menagerie states the reason for curation plainly: a physics simulator is only as good as the model it simulates, and in MuJoCo it is easy to create bad models that do not behave as expected. [1]

Loading models without hand-copying files

The robot_descriptions package downloads a description on first import and caches it for later use. [2] Its `load_robot_description` functions return an object ready for the target software, with loaders for iDynTree, MuJoCo, Pinocchio, PyBullet, RoboMeshCat and yourdfpy. [2]

A description imported as a submodule exposes `URDF_PATH` or `MJCF_PATH` for the main file, `PACKAGE_PATH` for the root of the description package, and `REPOSITORY_PATH` for the working directory of the hosting git repository. [2] The package says that its descriptions load successfully in MuJoCo for MJCF, or in Pinocchio, iDynTree, PyBullet and yourdfpy for URDF. [2]

Menagerie has its own Python package, which downloads each model on first load into a per-user cache and compiles its scene. Menagerie models are also reachable through robot_descriptions. [1]

The icub-models repository documents three ways to install its models: conda-forge, the robotology-superbuild, or a build from source. [3] The README addresses the installed models by `package://` URIs of the form `package://iCub/robots/<name>/model.urdf`, and describes their use with ROS. [3] It also provides a Python library, `icub_models`, whose functions report where the models are installed and which robots are available. [3]

Simulation variants are not the real robot

The iCub repository ships models whose names start with `iCubGazebo`. Its table notes for iCubGazeboV2_5, iCubGazeboV2_5_KIT_007, iCubGazeboV2_6 and iCubGazeboV2_7 that joint damping and the inertias of some links were increased in a non realistic way so that they run smoothly in Gazebo Classic with the ODE physics engine. [3] The iCubGazeboV2_5_visuomanip entry is described as a model with hands and eyes, with base_link fixed to the ground and the legs disabled. [3] The repository installs only the models known to work with the default physics settings of Classic Gazebo unless you enable a CMake option to install them all. [3]

Menagerie introduces a grading system to help users set expectations about the quality of each model. A+ means the values are the product of proper system identification, A means they are realistic but not identified, B means stable with some unrealistic values, and C means conditionally stable and open to significant improvement. [1] The README says the grading will be applied once a system identification toolbox exists, and that the current state of many models is not necessarily as good as it could be. [1]

Menagerie notes that a `<model>_mjx.xml` file holds an MJX-compatible version and that not every model has one. [1] The Tien Kung repository separates a body-only URDF from one with dexterous hands, and the A3 repository offers a planning URDF with an SRDF for the Ultra versions. [6] [5]

Pitfalls recorded by the maintainers

PNDbotics warns about a toe link flip. If you use its reinforcement learning examples, the collision element of the `toe_left` and `toe_right` links needs a specific origin rotation, and the Isaac Gym configuration needs `flip_visual_attachments = True`, because the default value of `False` may misalign the toe components visually in some models. [4]

The iCub README says the root frame of the robot is defined x-backward, meaning that the x-axis points behind the robot, while the root frame of a robot in the robotics community is sometimes x-forward. [3] For software developed for the x-forward configuration, it says the root frame orientation may need updating, by substituting the `origin` of the `base_fixed_joint` in the URDF model as follows: [3]

- <origin xyz="0 0 0" rpy="0 -0 0"/>
+ <origin xyz="0 0 0" rpy="0 -0 3.14159265358979323846"/>

The Berkeley Humanoid Lite release log records a fix of incorrect joint limit values in its documentation, which is a reminder that limits copied from documentation deserve a second look. [7]

The torobo_mujoco repository notes that the timing of the ball release in its pitching example differs depending on the computer environment. [8]

Licences and reuse

Check the licence before you copy a model into a product or a public repository. Menagerie says the XML and asset files in each model directory are subject to different licence terms, so you must read the `LICENSE` file under each model directory. [1] The licences in the Menagerie humanoid table include BSD-3-Clause, Apache-2.0 and MIT. [1]

The robot_descriptions tables list a licence for each description. Among the humanoids, GR-1 from Fourier is listed under GPL-3.0 and GENE.01 from Generative Bionics under CC-BY-NC-4.0. [2] The iCub models are licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. [3]

A checklist before you trust a model

The steps below are a suggested order for adopting a humanoid description for simulation or control work.

  1. Prefer the maker's repository for the geometry, and record which directory and version you took. The A3 repository, for example, holds several directories, each with its own URDF and MJCF files. [5]
  2. Read the notes about known issues, such as the toe link flip in the PNDbotics models. [4]
  3. Find out whether the model is a faithful description or a variant tuned for a simulator, as with the iCub Gazebo models. [3]
  4. Look for a quality grade or an identification record, and treat an ungraded model as unverified. [1]
  5. Check the root frame convention, the joint limits and the licence before wiring the model into a controller. [3] [7] [1]
  6. Load the model in more than one library. The robot_descriptions package lists loaders for MuJoCo (MJCF) and for Pinocchio, iDynTree, PyBullet and yourdfpy (URDF). [2]

Compare joint ranges, masses and inertias with the maker's documentation, and run a simple motion before you train a policy on the model.