[isaacsim.asset.importer.urdf] Omniverse URDF Importer Core

Version: 3.11.10

Overview

To enable this extension, go to the Extension Manager menu and enable isaacsim.asset.importer.urdf extension.

High Level Code Overview

Python

The URDF Importer extension provides a Python API for importing URDF files into USD format. The main classes are:

• URDFImporterConfig: A dataclass that stores configuration settings for the import operation, including:

  • urdf_path: Path to the URDF file to import

  • usd_path: Directory where the USD file will be saved

  • merge_mesh: Whether to merge meshes for optimization

  • debug_mode: Whether to enable debug mode with intermediate outputs

  • collision_from_visuals: Whether to generate collision geometry from visual geometries

  • collision_type: Type of collision geometry to use

  • allow_self_collision: Whether to allow self-collision

  • ros_package_paths: List of ROS package name/path mappings for resolving package:// URLs

• URDFImporter: The main importer class that converts URDF files to USD format.

The import workflow is as follows:

1. Create a URDFImporterConfig instance with the desired settings

2. Create a URDFImporter instance with the config

3. Call import_urdf() which:

   • Uses urdf-usd-converter to convert the URDF file to an intermediate USD format

   • Applies post-processing operations (rigid body schemas, joint schemas, mesh merging, collision geometry generation, etc.)

   • Runs the asset transformer profile to structure the output according to Isaac Sim conventions

   • Returns the path to the final USD file

When the import button is pressed in the UI, the extension creates a URDFImporter instance and calls import_urdf() with the user’s configuration settings.

Enable Extension

The extension can be enabled (if not already) in one of the following ways:

Command-line interface

Define the next entry as an application argument from a terminal.

APP_SCRIPT.(sh|bat) --enable isaacsim.asset.importer.urdf

Experience/extension configuration

Define the next entry under [dependencies] in an experience (.kit) file or an extension configuration (extension.toml) file.

[dependencies]
"isaacsim.asset.importer.urdf" = {}

Extension Manager UI

Open the Window > Extensions menu in a running application instance and search for isaacsim.asset.importer.urdf. Then, toggle the enable control button if it is not already active.

URDF Import Extension [isaacsim.asset.importer.urdf]

URDF Importer API

The URDF importer provides a Python API for configuring and converting URDF files into USD assets. Below is a sample demonstrating how to import the Carter URDF included with this extension.

import os

import omni.usd
from isaacsim.asset.importer.urdf import URDFImporter, URDFImporterConfig

# 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.urdf")
extension_path = ext_manager.get_extension_path(ext_id)

urdf_path = os.path.join(extension_path, "data", "urdf", "robots", "carter", "urdf", "carter.urdf")
output_dir = os.path.dirname(urdf_path)

# Configure and import.
import_config = URDFImporterConfig(
    urdf_path=urdf_path,
    usd_path=output_dir,
    collision_from_visuals=False,
    merge_mesh=False
)

importer = URDFImporter(import_config)
output_path = importer.import_urdf()

# Open the resulting USD stage.
omni.usd.get_context().open_stage(output_path)

class URDFImporter(

config: URDFImporterConfig | None = None,

)

URDF to USD importer.

Uses urdf-usd-converter to convert URDF files to USD format.

Parameters:

config – Optional configuration for the import operation.

Example:

>>> from isaacsim.asset.importer.urdf import URDFImporter
>>> URDFImporter()
<...>

import_urdf(

config: URDFImporterConfig | None = None,

) → str

Import a URDF file and convert it to USD.

Parameters:

config – Optional configuration for the import operation. If not provided, the stored importer configuration will be used.

Returns:

Path to the generated USD file.

Raises:

ValueError – If the URDF path is not configured or if the file does not have a .urdf extension.

Example:

>>> from isaacsim.asset.importer.urdf import URDFImporter, URDFImporterConfig

>>> importer = URDFImporter()
>>> config = URDFImporterConfig(urdf_path="/tmp/robot.urdf")
>>> importer.config = config
>>> # output_path = importer.import_urdf()

property config: URDFImporterConfig

Get the importer configuration.

Returns:

Current importer configuration.

Example:

>>> from isaacsim.asset.importer.urdf import URDFImporter, URDFImporterConfig

>>> importer = URDFImporter()
>>> importer.config  
URDFImporterConfig(...)

class URDFImporterConfig(

urdf_path: str | None = None,

usd_path: str | None = None,

merge_fixed_joints: bool = False,

merge_mesh: bool = False,

debug_mode: bool = False,

collision_from_visuals: bool = False,

collision_type: str = 'Convex Hull',

allow_self_collision: bool = False,

ros_package_paths: list[dict[str,

str]] = <factory>,

robot_type: str = 'Default',

fix_base: bool | None = None,

link_density: float | None = None,

joint_drive_type: str | dict[str,

str] | None = None,

joint_target_type: str | dict[str,

str] | None = None,

override_joint_stiffness: float | dict[str,

float] | None = None,

override_joint_damping: float | dict[str,

float] | None = None,

run_asset_transformer: bool = True,

run_multi_physics_conversion: bool = True,

)

Configuration for URDF import operations.

Stores settings that control how URDF files are converted to USD.

Parameters:

• urdf_path – Path to the URDF (.urdf) file to import.

• usd_path – Directory path where the USD file will be saved. When left at its default of None, URDFImporter.import_urdf() will mutate this field in-place to os.path.dirname(urdf_path) (the directory containing the source URDF) and write all USD output there. Pass an explicit value to keep import outputs out of the source tree.

• merge_fixed_joints – If True, merges fixed joints where possible to optimize the model.

• merge_mesh – If True, merges meshes where possible to optimize the model.

• debug_mode – If True, enables debug mode with additional logging and visualization.

• collision_from_visuals – If True, collision geometry is generated from visual geometries.

• collision_type – Type of collision geometry to use. Options: “Convex Hull”, “Convex Decomposition”, “Bounding Sphere”, “Bounding Cube”.

• allow_self_collision – If True, allows the model to collide with itself.

• ros_package_paths – List of ROS package name/path mappings for resolving package:// URLs.

• fix_base –

  Tri-state base-type toggle. - True: adds a fixed joint from the world to the root rigid-body link and

  relocates ArticulationRootAPI to the correct ancestor prim.

  • False: removes any existing world-to-root fixed joint so the robot becomes floating-base.

  • None (default): leaves the source asset’s base authoring untouched.

• link_density – Default density (kg/m^3) applied to rigid body links that have no explicit mass. None means no density override.

• joint_drive_type – Joint drive type ("force" or "acceleration"), or a dict mapping joint-name regex patterns to per-joint values. None leaves drives unchanged.

• joint_target_type – Joint target type ("none", "position", or "velocity"), or a dict of patterns. None leaves targets unchanged.

• override_joint_stiffness – Joint stiffness in Nm/rad (revolute) or N/m (prismatic), or a dict of patterns. None leaves stiffness unchanged.

• override_joint_damping – Joint damping in Nm*s/rad (revolute) or N*s/m (prismatic), or a dict of patterns. None leaves damping unchanged.

• run_asset_transformer – If True, runs the asset transformer profile after conversion to restructure the USD output.

• run_multi_physics_conversion – If True, runs URDF-to-PhysX joint attribute conversion on the imported stage.

Example:

>>> from isaacsim.asset.importer.urdf import URDFImporterConfig

>>> config = URDFImporterConfig(
...     urdf_path="/tmp/robot.urdf",
...     usd_path="/tmp/output",
...     merge_mesh=True
... )
>>> config.urdf_path
'/tmp/robot.urdf'

allow_self_collision: bool = False

collision_from_visuals: bool = False

collision_type: str = 'Convex Hull'

debug_mode: bool = False

fix_base: bool | None = None

joint_drive_type: str | dict[str, str] | None = None

joint_target_type: str | dict[str, str] | None = None

link_density: float | None = None

merge_fixed_joints: bool = False

merge_mesh: bool = False

override_joint_damping: float | dict[str, float] | None = None

override_joint_stiffness: float | dict[str, float] | None = None

robot_type: str = 'Default'

ros_package_paths: list[dict[str, str]]

run_asset_transformer: bool = True

run_multi_physics_conversion: bool = True

urdf_path: str | None = None

usd_path: str | None = None

• Python API