MJCF Importer Extension

About

Starting from the Isaac Sim 2023.1.0 release, the MJCF importer has been open-sourced. Source code and information for contributing can be found at our github repo.

The MJCF Importer Extension Extension is used to import MuJoCo representations of robots. MuJoCo Modeling XML File (MJCF), is an XML format for representing a robot model in the MuJoCo simulator.

To access this Extension, go to the top menu bar and click File > Import.

This extension is enabled by default. If it is ever disabled, it can be re-enabled from the Extension Manager by searching for isaacsim.asset.importer.mjcf.

Conventions

Warning

Special characters in link or joint names are not supported and will be replaced with an underscore. In the event that the name starts with an underscore due to the replacement, an a is pre-pended. It is recommended to make these name changes in the mjcf directly.

See the Isaac Sim Conventions documentation for a complete list of NVIDIA Isaac Sim conventions.

User Interface

Import Options

Model

Provides the Options to Import in Stage, or add as a referenced model. If Create in Stage is selected. Choose the options to Set as the default prim, and Clear Stage on Import. By default both are left unchecked.

Links

Choose between a Moveable base (for example, a wheeled robot) or a Static base (for example, a 6-dof robotic arm). If the robot is a Moveable base, the base link will be set to moveable. If the robot is a Static base, the base link will be fixed in place with a root_joint.

The Default Density is used for links that do not have a mass specified in the URDF. If the density is set to 0, the physics engine will automatically compute the density with its default value.

Colliders

• Visualize Collision Geometry: When selected, the collision geometry will be visible in the viewport.

• Allow self-collision: Enables self collision between adjacent links. It may cause instability if the collision meshes are intersecting at the joint.

Note

It is recommended that you set Self Collision to false unless you are certain that links on the robot are not self colliding

Note

You must have write access to the output directory used for import, it will default to the current open stage, change this as necessary.

Robot Properties

There might be many properties you want to tune on your robot. These properties can be spread across many different Schemas and APIs.

The general steps of getting and setting a parameter are:

1. Find which API is the parameter under. Most common ones can be found in the Pixar USD API.

2. Get the prim handle that the API is applied to. For example, Articulation and Drive APIs are applied to joints, and MassAPIs are applied to the rigid bodies.

3. Get the handle to the API. From there on, you can Get or Set the attributes associated with that API.

For example, if we want to set the wheel’s drive velocity and the actuators’ stiffness, we need to find the DriveAPI:

# get handle to the Drive API for both wheels
left_wheel_drive = UsdPhysics.DriveAPI.Get(stage.GetPrimAtPath("/carter/chassis_link/left_wheel"), "angular")
right_wheel_drive = UsdPhysics.DriveAPI.Get(stage.GetPrimAtPath("/carter/chassis_link/right_wheel"), "angular")

# Set the velocity drive target in degrees/second
left_wheel_drive.GetTargetVelocityAttr().Set(150)
right_wheel_drive.GetTargetVelocityAttr().Set(150)

# Set the drive damping, which controls the strength of the velocity drive
left_wheel_drive.GetDampingAttr().Set(15000)
right_wheel_drive.GetDampingAttr().Set(15000)

# Set the drive stiffness, which controls the strength of the position drive
# In this case because we want to do velocity control this should be set to zero
left_wheel_drive.GetStiffnessAttr().Set(0)
right_wheel_drive.GetStiffnessAttr().Set(0)

Alternatively you can use the Omniverse Commands Tool Extension to change a value in the UI and get the associated Omniverse command that changes the property.

Note

• The drive stiffness parameter should be set when using position control on a joint drive.

• The drive damping parameter should be set when using velocity control on a joint drive.

• A combination of setting stiffness and damping on a drive will result in both targets being applied, this can be useful in position control to reduce vibrations.

Asset Structure

The Isaac Sim Imported assets are organized in a specific structure to make it easier to manage, reuse, and simulate them. Each asset is broken down into multiple components, which can be categorized as follows:

For an example of an asset following these guidelines check Nova carter at Robots/NVIDIA/Carter/nova_carter/ in Isaac Sim assets.

Asset Source

Assets in this stage represent their raw form as imported from their original file format. They are typically organized into:

1. Base Asset ( asset_base.usd ): Contains the full structural hierarchy of the asset, such as robot assemblies.

2. Parts ( parts.usd ): Includes individual components, with one USD file per mesh. This modular breakdown ensures easy access and management.

3. Materials ( materials.usd ): A collection of Physically Based Rendering (PBR) materials used by the asset.

Guidelines:

• The source assets should remain unchanged to ensure that they can be re-imported seamlessly without losing downstream modifications.

• Consistency is critical: the structural hierarchy, naming conventions, and part assemblies must remain intact.

Transformation

This stage prepares the asset for simulation by reorganizing and optimizing it. This transformation is necessary when the source asset contains nested rigid bodies or a complex structure that doesn’t meet the requirements of simulation. The structure must be flattened with rigid bodies organized into a simple list, and meshes should be simplified to minimize their total count. The transformation process includes:

1. Reorganizing Structure: - Create the simulation structure (e.g., separating visuals and colliders as needed). - Adjust the hierarchy to fit simulation requirements.

2. Optimizing Meshes: - Merge meshes that will function as a single rigid body. - Simplify the material count into a single visual material list. - Clean and format meshes as instanceable references to enhance performance.

Note

If the asset source is already in a format suitable for simulation, this step or parts of it can be skipped.

Features

Simulation features are added in this stage, and each feature is defined as a separate lightweight layer that builds on top of the transformed asset. These features include, but are not limited to, physics setups, sensor configurations, and control graphs.

Workflow for Adding/Modifying Features:

1. Create a new empty stage or open the existing feature stage.

2. Add the optimized asset (asset_sim_optimized.usd) as a sub-layer.

3. Modify the root layer to add/modify the feature.

4. Remove or disable the sub-layer (optimized asset) from the stage composition before saving.

5. Add the feature to the final asset as a payload. Optionally, a Variant set can be configured to enable quick switching between different feature sets by selecting them on a list.

Example Features:

• Physics ( asset_physics.usd ): Adds rigid bodies, colliders, joints, and articulations.

• Sensors ( asset_sensors.usd ): Defines sensor specifications.

• Control Graphs ( asset_control.usd ): Adds control features for simulations.

• ROS Integration ( asset_ros.usd ): Configures ROS Omnigraph functionalities.

Note

The Physics feature is an exception and is added as a reference to the default prim, while other features are added as payloads. and it maintains the layer connection to the optimized asset.

Composition of Final Asset

The final composed asset is represented in the asset.usd file, which integrates all the necessary components for simulation. This is achieved through the following composition process:

1. Sublayers: - The base or optimized asset (asset_sim_optimized.usd) is included as a sublayer to provide the core structural and visual elements.

2. Payloads: - Features such as sensors (asset_sensors.usd) and control graphs (asset_control.usd) are dynamically added as payloads. This allows for flexible and efficient loading of components.

3. References: - The physics setup (asset_physics.usd) is added as a reference to the default prim, ensuring a consistent simulation-ready configuration.

4. Variants: - Variants can be configured in the asset.usd file to enable different feature sets, such as alternative sensor configurations or control setups, without duplicating the asset.

This modular approach ensures that the final asset file is both lightweight and highly flexible, making it easy to adapt to different simulation scenarios.

To keep assets organized and maintainable, it is recommended to follow the structure and guidelines outlined above. This will help streamline the asset creation process and improve overall simulation performance.

It is also suggested to keep the assets organized in folders, with the source assets in their own folder, and all features in a features folder, while the final asset is saved in the root folder. By default Isaac Sim importers for robots follow this structure.

Key Definitions and Notes

• Add-ons: - Features that have the simulation asset as a temporary sublayer used during feature creation - We call this the Add-on. The sublayer connection is broken before saving the feature asset.

• Payloads: Dynamically loadable components that reduce memory overhead and improve modularity.

Tutorial

Please check out Tutorial: Import MJCF.