Tutorial: Import MJCF#

Learning Objectives#

This tutorial shows how to import a MJCF model and convert it to a USD in NVIDIA Isaac Sim. After this tutorial, you can use MJCF files in your pipeline while using NVIDIA Isaac Sim.

5-10 Minute Tutorial

Getting Started#

Prerequisites

Using the MJCF Importer#

Begin by importing an Ant MJCF from the Built in MJCF files that come with the extension.

  1. Load the MJCF Importer extension, which should be automatically loaded when NVIDIA Isaac Sim opens and can be accessed from the File > Import menu. If not MJCF files are not listed in the import formats, go to Window > Extensions and enable isaacsim.asset.importer.mjcf and isaacsim.asset.importer.mjcf.ui extensions.

  2. In the file selection dialog box, navigate to the desired folder, and select the desired MJCF file. For this example, use the Ant nv_ant.xml file that comes with this extension, included in the extension assets. To find it:

    • Click on the folder icon beside AUTOLOAD to find the isaacsim.asset.importer.mjcf extension.

    • Navigate to /data/mjcf and find nv_ant.xml file.

  3. Change the import options according to the your needs. Check Import Options for more information on the import options.

    Select MJCF to Import

  4. Click the Import button to add the robot to the stage.

    Imported Ant

The robot is now imported into the stage. You can now use it in your simulation. You can perform additional changes to the asset after it’s imported, such as adding sensors, changing materials, and updating the joint drives and configuration to achieve a more stable simulation. Robots are mapped as articulations in the simulation, and for a complete guide in tuning articulations, refer to Articulation Stability Guide.

Importing MJCF Using Python API#

Do the exact same thing with Python scripting instead.

  1. Open the Script Editor. Go to the top Menu Bar and click Window > Script Editor.

  2. The window for the Script Editor is visible in the workspace.

  3. Copy the following code into the Script Editor window.

    import isaacsim.core.experimental.utils.stage as stage_utils
import omni.usd
from isaacsim.asset.importer.mjcf import MJCFImporter, MJCFImporterConfig
from pxr import Gf, PhysicsSchemaTools, Sdf, UsdLux, UsdPhysics

# create new stage
omni.usd.get_context().new_stage()

# Get path to extension data:
ext_manager = omni.kit.app.get_app().get_extension_manager()
ext_id = ext_manager.get_enabled_extension_id("isaacsim.asset.importer.mjcf")
extension_path = ext_manager.get_extension_path(ext_id)

# setting up import configuration:
import_config = MJCFImporterConfig(mjcf_path=extension_path + "/data/mjcf/nv_ant.xml")

# import MJCF
importer = MJCFImporter(import_config)
output_usd_path = importer.import_mjcf()

# open the imported USD file into the current stage
result, stage = stage_utils.open_stage(output_usd_path)

# enable physics
scene = UsdPhysics.Scene.Define(stage, Sdf.Path("/physicsScene"))

# set gravity
scene.CreateGravityDirectionAttr().Set(Gf.Vec3f(0.0, 0.0, -1.0))
scene.CreateGravityMagnitudeAttr().Set(9.81)

# add lighting
distantLight = UsdLux.DistantLight.Define(stage, Sdf.Path("/DistantLight"))
distantLight.CreateIntensityAttr(500)

  4. Click the Run (Ctrl + Enter) button to import the Ant robot.

Importing MJCF Using Python Standalone#

Do the exact same thing with Python standalone instead.

  1. Open a terminal and navigate to the root of the Isaac Sim installation.

  2. Run the following command:

    ./python.sh standalone_examples/api/isaacsim.asset.importer.mjcf/mjcf_import.py
    Args:

    • --mjcf: Path to the MJCF file (.xml) to import.

    • --usd-path: Directory to write converted USD assets.

    • --merge-mesh: Merge meshes after conversion.

    • --debug-mode: Enable debug mode and keep intermediate outputs.

    • --import-scene: Import the MJCF simulation settings along with the model (default True).

    • --collision-from-visuals: Generate collision geometry from visuals.

    • --collision-type: Collision geometry type (e.g. “Convex Hull”, “Convex Decomposition”, “Bounding Sphere”, “Bounding Cube”).

    • --allow-self-collision: Allow self-collision for the imported asset.

    • --test: uses nv_ant.xml test asset into a temp directory

    Example:

    ./python.sh standalone_examples/api/isaacsim.asset.importer.mjcf/mjcf_import.py --mjcf /path/to/nv_ant.xml --usd-path /path/to/output --merge-mesh

Known Issues#

In USD, a joint is defined as a kinematics constraint between two rigid bodies. When a joint is created, the DOF is limited only to the axis of the joint. For example, a revolute joint has only one DOF, and removes the other five DOFs.

In MuJoCo, a joint is defined as a degree of freedom, enabling multiple joints to be combined together to create more degrees of freedoms. For example, an x-axis revolute joint and a y-axis revolute joint can be combined together to create a 2D x-y axis revolute joint. This is not supported in USD, if two revolute joints between two bodies are defined, the system would form a kinematic loop, and become overconstrained.

The current solution is to place a dummy link between the two bodies, and create a joint between the dummy link and the other body in the MJCF file. For example, if two revolute joints are defined between the body and the ground, a dummy link can be placed between the body and the ground, and a joint can be created between the dummy link and the ground and a joint between the dummy link and the body. This will create a 2D x-y axis revolute joint.

Summary#

This tutorial covered the following topics:

  1. Importing MJCF file using GUI

  2. Importing MJCF file using Python API

  3. Importing MJCF file using Python Standalone

Further Learning#

Review MJCF Importer Extension to learn more about the different configuration settings to import a MJCF in NVIDIA Isaac Sim. Learn how to use the Gain Tuner Extension to tune the gains for your robot.