[isaacsim.asset.importer.utils] Isaac Sim Asset Importer Utils#

Version: 1.1.1

Shared utility functions for asset importers.

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.utils

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.utils" = {}

Extension Manager UI

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

Asset Importer Utils Extension [isaacsim.asset.importer.utils]#

This extension provides shared utility functions for asset importers, including collision handling, mesh merging, and stage management operations.

Importer Utils#

Utility helpers for asset importer preprocessing steps.

add_joint_schemas(stage: pxr.Usd.Stage) → None#

Apply joint-related physics schemas to all joint prims.

Parameters:: stage – USD stage to update with joint schemas.

add_rigid_body_schemas(stage: pxr.Usd.Stage) → None#

Apply rigid body-related physics schemas to all rigid body prims.

Parameters:: stage – USD stage to update with rigid body schemas.

collision_from_visuals( stage: pxr.Usd.Stage, collision_type: str, ) → int#

Apply collisions from visual geometry and remove guide colliders.

Parameters:

stage – USD stage for authoring collision APIs.
collision_type – Collision approximation label. Defaults to convex hull when unknown.

Returns:

Number of visual geometry prims processed.

Example:

>>> from pxr import Usd
>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>> from isaacsim.asset.importer.utils import collision_from_visuals
>>>
>>> stage = Usd.Stage.CreateInMemory()
>>> stage_utils.use_stage(stage)
>>> collision_from_visuals(stage, "Convex Hull")  

create_physx_mimic_joint(prim: pxr.Usd.Prim) → None#

Create a mimic joint for a joint.

Parameters:: prim – prim to create the mimic joint for.

delete_scope(stage: pxr.Usd.Stage, prim_path: str) → None#

Delete a scope prim from the stage, reparenting its children to the parent prim.

Parameters:

stage – USD stage containing the prim.
prim_path – Path to the prim to delete.

enable_self_collision( usd_stage: pxr.Usd.Stage, enabled: bool = True, ) → int#

Enable self-collisions on articulation roots.

Parameters:

usd_stage – USD stage for authoring PhysX articulation attributes.
enabled – Whether to enable self collisions on articulation roots.

Returns:

Number of articulation roots updated.

remove_custom_scopes(stage: pxr.Usd.Stage) → None#

Remove custom scopes from the stage.

Parameters:: stage – USD stage to update with custom scopes.

run_asset_transformer_profile( input_stage_path: str, output_package_root: str, profile_json_path: str, *, log_path: str | None = None, ) → None#

Run an asset structure profile against an input stage.

Parameters:

input_stage_path – Path to the input USD stage.
output_package_root – Destination folder for output assets.
profile_json_path – Path to the profile JSON file.
log_path – Optional JSON report output path.

Example:

>>> from isaacsim.asset.importer.utils import run_asset_transformer_profile
>>>
>>> run_asset_transformer_profile(
...     input_stage_path="/tmp/input.usda",
...     output_package_root="/tmp/output",
...     profile_json_path="/tmp/profile.json",
... )  

Merge Mesh Utils#

Mesh cleanup and merge operations for asset importers.

clean_mesh_operation(stage: pxr.Usd.Stage) → None#

Clean mesh prims.

Parameters:: stage – USD stage for executing clean operations.

generate_mesh_uv_normals_operation(stage: pxr.Usd.Stage) → None#

Generate mesh UV normals.

Parameters:: stage – USD stage for executing generate operations.

merge_mesh(stage: pxr.Usd.Stage, meshes: list[str]) → None#

Merge a list of mesh prim paths using Scene Optimizer.

Parameters:

stage – USD stage containing the mesh prims.
meshes – List of mesh prim paths to merge.

Example:

>>> from pxr import Usd
>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>> from isaacsim.asset.importer.utils import merge_mesh
>>>
>>> stage = Usd.Stage.CreateInMemory()
>>> stage_utils.use_stage(stage)
>>> merge_mesh(stage, ["/World/meshA", "/World/meshB"])  

merge_meshes_operation(stage: pxr.Usd.Stage) → int#

Merge mesh prims grouped under rigid bodies.

Parameters:: stage – USD stage for executing merge operations.
Returns:: Number of mesh groups merged.

Example:

>>> from pxr import Usd
>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>> from isaacsim.asset.importer.utils import merge_meshes_operation
>>>
>>> stage = Usd.Stage.CreateInMemory()
>>> stage_utils.use_stage(stage)
>>> merge_meshes_operation(stage)  

MJCF to PhysX Conversion Utils#

Utilities for converting MJCF actuator/joint data to PhysX schemas.

convert_mjc_actuator_to_physics( mjc_actuator: pxr.Usd.Prim, stage: pxr.Usd.Stage, ) → None#

Convert a MJCF actuator to a PhysX actuator.

Parameters:

mjc_actuator – MJCF actuator prim.
stage – USD stage containing the target joint prim.

Raises:

ValueError – If the actuator or its target joint prim is invalid.

convert_mjc_joint_to_physx( joint: pxr.Usd.Prim, stage: pxr.Usd.Stage, ) → None#

Convert a MJCF joint to a PhysX joint.

Parameters:

joint – MJCF joint prim.
stage – USD stage containing the joint prim.

convert_mjc_to_physx(stage: pxr.Usd.Stage) → None#

Convert all MJCF actuators to PhysX actuators.

Parameters:: stage – USD stage to update with PhysX actuators.

Stage Utils#

Stage helpers for asset importer utilities.

get_stage_id(stage: pxr.Usd.Stage) → int#

Get the stage ID of a USD stage.

Backends: usd.

Parameters:: stage – The stage to get the ID of.
Returns:: The stage ID.

Example:

>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>>
>>> stage = stage_utils.get_current_stage()
>>> stage_utils.get_stage_id(stage)  
9223006

open_stage(usd_path: str) → pxr.Usd.Stage#

Open a USD file as a standalone USD stage.

Backends: usd.

Parameters:: usd_path – USD file path to open.
Returns:: Opened USD stage instance.
Raises:: ValueError – If the USD file does not exist or is not a valid (shallow check).

Example:

>>> import isaacsim.asset.importer.utils.stage_utils as stage_utils
>>> from isaacsim.storage.native import get_assets_root_path
>>>
>>> # open a USD file
>>> stage = stage_utils.open_stage(
...     get_assets_root_path() + "/Isaac/Robots/FrankaRobotics/FrankaPanda/franka.usd"
... )
>>> stage
Usd.Stage.Open(rootLayer=Sdf.Find('...'), ...)

save_stage(stage: pxr.Usd.Stage, usd_path: str) → bool#

Save a stage to a USD file.

Backends: usd.

Parameters:

stage – USD stage to save.
usd_path – USD file path to save the stage to.

Returns:

Whether the stage was saved successfully.

Raises:

ValueError – If the target path is not a supported USD file or the stage is invalid.

Example:

>>> import os
>>> import tempfile
>>> import isaacsim.asset.importer.utils.stage_utils as stage_utils
>>>
>>> # save the stage to a USD file
>>> stage = Usd.Stage.CreateInMemory()
>>> usd_path = os.path.join(tempfile.gettempdir(), "test.usd")
>>> stage_utils.save_stage(stage, usd_path)
True

URDF to MJCF/PhysX Conversion Utils#

Utilities for converting URDF/PhysX joint data into MJCF-compatible data.

convert_joints_attributes(stage: pxr.Usd.Stage) → None#

Convert all joints attributes to MJCF attributes.

Parameters:: stage – USD stage to update with MJCF attributes.

convert_physx_to_mjc(joint: pxr.Usd.Prim) → None#

Convert a PhysX joint to a MJCF joint.

Parameters:: joint – PhysX joint prim.
Raises:: ValueError – If the input joint prim is invalid.

convert_urdf_to_physx(joint: pxr.Usd.Prim) → None#

Convert a URDF attributes to PhysX attributes.

Parameters:: joint – joint prim.
Raises:: ValueError – If the input joint prim is invalid.

create_mjc_actuator_from_physics( joint: Usd.Prim, stage: Usd.Stage, path: str, ) → Usd.Prim | None#

Create a MJCF actuator for a joint.

Parameters:

joint – URDF joint prim.
stage – USD stage to update with MJCF attributes.
path – Path to the MJCF actuator scope.

Returns:

The created MJCF actuator prim.

Raises:

ValueError – If the input joint prim is invalid.