Updates MJCF Importer to Isaac Sim MJCF Importer 3.0

[kellyguo11]

Description

Isaac Sim recently updated the MJCF importer to use https://github.com/newton-physics/mujoco-usd-converter, which resulted in major changes to APIs and functionality.

To accommodate for these changes, the IsaacLab wrapper for the MJCF importer also requires breaking changes to the configuration and parameters.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (existing functionality will not work without user modification)
• Documentation update

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh --format
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• I have updated the changelog and the corresponding version in the extension's config/extension.toml file
• I have added my name to the CONTRIBUTORS.md or my name already exists there

[greptile-apps]

Greptile Summary

This PR updates the MJCF converter to use Isaac Sim 5.0's new MJCFImporter API backed by the mujoco-usd-converter library, replacing the deprecated command-based approach.

Major Changes:

• Refactored MjcfConverter to use MJCFImporter and MJCFImporterConfig classes instead of Kit commands
• Removed deprecated settings: fix_base, link_density, import_inertia_tensor, import_sites, make_instanceable (handled automatically by new converter)
• Added new settings: merge_mesh, collision_from_visuals, collision_type
• Updated output structure: converter now outputs to {usd_dir}/{robot_name}/{robot_name}.usda instead of flat structure
• Fixed variable naming typo in tests (urdf_converter → mjcf_converter)

Documentation:

• Comprehensive migration guide with before/after examples for CLI and Python API
• Updated how-to guide with new command-line flags
• CHANGELOG entry for 4.0.0 release with breaking changes clearly noted
• Version bump to 4.0.0 reflecting breaking changes

Key Implementation Details:

• __init__ pre-adjusts usd_file_name to match new nested output structure for lazy conversion compatibility
• _convert_asset cleans up existing output subdirectory before conversion to ensure fresh files
• Parameter mapping correctly translates IsaacLab's self_collision to Isaac Sim's allow_self_collision

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• Well-structured refactoring with comprehensive documentation, migration guide, and test updates. Breaking changes are clearly documented and handled appropriately through version bump to 4.0.0.
• No files require special attention

Important Files Changed

Filename	Overview
source/isaaclab/isaaclab/sim/converters/mjcf_converter.py	Refactored to use new Isaac Sim 5.0 MJCFImporter API, removed deprecated command-based approach, handles new output directory structure correctly
source/isaaclab/isaaclab/sim/converters/mjcf_converter_cfg.py	Updated configuration to match new MJCF importer API, removed deprecated settings, added new collision and mesh optimization options
scripts/tools/convert_mjcf.py	Updated CLI arguments to match new MJCF converter configuration, removed deprecated flags, added new mesh and collision options
docs/source/migration/migrating_to_isaaclab_3-0.rst	Comprehensive migration guide covering API changes, removed/renamed/new settings, and code examples for updating from 2.x to 3.0

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[MjcfConverter.__init__] -->|Pre-adjust usd_file_name| B[robot/robot.usda]
    B --> C[AssetConverterBase.__init__]
    C -->|Check if conversion needed| D{USD exists & hash matches?}
    D -->|No| E[_convert_asset]
    D -->|Yes| F[Skip conversion]
    E -->|Clean existing subdir| G[shutil.rmtree output_subdir]
    G --> H[Create MJCFImporterConfig]
    H -->|Parameters| I[mjcf_path, usd_path, merge_mesh,<br/>collision_from_visuals, collision_type,<br/>allow_self_collision]
    I --> J[MJCFImporter.import_mjcf]
    J --> K[Output: usd_dir/robot_name/robot_name.usda]
    
    style A fill:#e1f5ff
    style E fill:#fff4e1
    style J fill:#e7f9e7
    style K fill:#e7f9e7

Loading

_{Last reviewed commit: 30d6c57}

[greptile-apps]

_{8 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}