Is this page helpful?

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.

class PhysxAttr( value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None, )#

PhysX attribute names and their USD value types.

Access the USD attribute name via .name and the type via .type.

ARTICULATION_SELF_COLLISION = ('physxArticulation:enabledSelfCollisions', pxr.Sdf.ValueTypeNames.Bool)#: Articulation self-collision enabled (Bool).

JOINT_ARMATURE = ('physxJoint:armature', pxr.Sdf.ValueTypeNames.Float)#: Joint armature (Float).

JOINT_FRICTION = ('physxJoint:jointFriction', pxr.Sdf.ValueTypeNames.Float)#: Joint friction (Float).

JOINT_MAX_VELOCITY = ('physxJoint:maxJointVelocity', pxr.Sdf.ValueTypeNames.Float)#: Maximum joint velocity (Float).

property name: str#: USD attribute name.

property type: pxr.Sdf.ValueTypeName#: USD Sdf.ValueTypeNames type.

class PhysxMimicAttr( value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None, )#

Attribute name templates for PhysxMimicJointAPI (multi-apply).

Use attr.format(axis) to get the full attribute name for a given axis token. Access the USD type via .type.

Example:

attr_name = PhysxMimicAttr.GEARING.format("rotZ")
# -> "physxMimicJoint:rotZ:gearing"

format(axis: str) → str#

Return the full attribute name for a given axis token.

Parameters:: axis – Axis instance token (e.g. "rotX", "rotZ").

GEARING = ('physxMimicJoint:{}:gearing', pxr.Sdf.ValueTypeNames.Float)#: Mimic gearing multiplier (Float).

OFFSET = ('physxMimicJoint:{}:offset', pxr.Sdf.ValueTypeNames.Float)#: Mimic offset (Float).

REFERENCE_JOINT_AXIS = ('physxMimicJoint:{}:referenceJointAxis', pxr.Sdf.ValueTypeNames.Token)#: Reference joint axis token (Token).

property type: pxr.Sdf.ValueTypeName#: USD Sdf.ValueTypeNames type.

class PhysxMimicRel( value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None, )#

Relationship name templates for PhysxMimicJointAPI (multi-apply).

Use rel.format(axis) to get the full relationship name for a given axis token.

Example:

rel_name = PhysxMimicRel.REFERENCE_JOINT.format("rotZ")
# -> "physxMimicJoint:rotZ:referenceJoint"

format(axis: str) → str#

Return the full relationship name for a given axis token.

Parameters:: axis – Axis instance token (e.g. "rotX", "rotZ").

REFERENCE_JOINT = 'physxMimicJoint:{}:referenceJoint'#: Relationship to the reference (source) joint.

class PhysxSchema( value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None, )#

Schema identifiers for prim.ApplyAPI() and prim.HasAPI().

ARTICULATION_API = 'PhysxArticulationAPI'#: PhysX articulation API (single-apply).

JOINT_API = 'PhysxJointAPI'#: PhysX joint API (single-apply).

JOINT_STATE_API = 'PhysicsJointStateAPI'#: PhysX joint state API (multi-apply with drive instance).

MIMIC_JOINT_API = 'PhysxMimicJointAPI'#: PhysX mimic joint API (multi-apply with axis instance).

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 UsdPhysics.MassAPI to every rigid body that lacks it.

This function is deprecated, and will be removed in a future version. Use asset_utils.apply_link_density() instead.

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_robot_schema( stage: Usd.Stage, robot_type: str = 'Default', *, prim_path: str | None = None, add_sites: bool = True, sites_last: bool = False, ) → tuple[Usd.Prim | None, Usd.Prim | None]#

Apply the Isaac robot schema to a prim and populate link/joint relationships.

If the target prim already has the IsaacRobotAPI applied, the schema is recalculated (preserving existing ordering). Otherwise a fresh RobotAPI is applied and populated from the articulation hierarchy.

No-op with a warning if usd.schema.isaac.robot_schema is unavailable.

Parameters:

stage – The USD stage containing the robot.
robot_type – Robot category token. Must be one of ROBOT_TYPE_TOKENS (e.g. "Manipulator", "Humanoid").
prim_path – Prim path to apply the schema to. Defaults to the stage default prim when None.
add_sites – Detect child Xforms with no children under each link and apply IsaacSiteAPI to them.
sites_last – When True all sites are appended at the end of the links list; when False each site follows its parent link.

Returns:

A (root_link, root_joint) tuple of the detected articulation root link and root joint. Either may be None; both are None when the robot schema module is unavailable.

Raises:

ValueError – If robot_type is not in ROBOT_TYPE_TOKENS or the resolved prim is invalid.

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 articulation attributes.
enabled – Whether to enable self collisions on articulation roots.

Returns:

Number of articulation roots updated.

parse_robot_name(path: str, *, expected_extension: str) → str#

Derive a robot name from a URDF/MJCF file path and validate its extension.

The robot name is the file’s basename with its trailing extension removed. Hidden-file style names (e.g. .franka.urdf) are handled by stripping leading dots so the result is non-empty. When the stem still contains . characters (e.g. franka.v2.urdf) a warning is emitted because the stem is used verbatim as a USD prim / file name and dots there can cause downstream issues.

Parameters:

path – Path to the URDF or MJCF source file.
expected_extension – Required extension including the leading dot (e.g. ".urdf" or ".xml"). Matched case-insensitively.

Returns:

The derived robot name (never empty).

Raises:

ValueError – If the file does not end with expected_extension.

Example:

>>> from isaacsim.asset.importer.utils import parse_robot_name
>>> parse_robot_name("/tmp/franka.urdf", expected_extension=".urdf")
'franka'
>>> parse_robot_name("/tmp/.franka.urdf", expected_extension=".urdf")
'franka'

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

Remove custom scopes from the stage.

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

resolve_unique_path(path: str, *, is_file: bool | None = None) → str#

Return path or a numerically suffixed variant that does not collide on disk.

A path is considered colliding if it is an existing file or a non-empty directory. For files the counter is inserted before the extension (robot_1.usda); for directories it is appended (usdex_robot_1).

Parameters:

path – File or directory path to resolve.
is_file – Explicit file/directory hint. When None the type is inferred from the filesystem or from a conventional extension to avoid mangling directories with dots in their name.

Returns:

A path that does not cause a conflict on disk.

Raises:

RuntimeError – If no unique path could be resolved after 1000 attempts.

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.

combine_overconstrained_joints_in_physx_layer( physx_layer_path: str, ) → int#

Run combine_overconstrained_joints_to_d6() against a standalone PhysX overlay layer.

Assumes the PhysX layer sublayers the base physics layer (the asset transformer’s physx.usda -> physics.usda layout). All edits are authored back into the PhysX layer only.

Parameters:: physx_layer_path – Path to the PhysX overlay layer file (typically payloads/Physics/physx.usda).
Returns:: Number of joint groups combined, or 0 if the layer can’t be opened.

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

Combine joints sharing the same body pair into a single PhysX D6 joint.

For each (body0, body1) group with more than one joint the first joint is retyped to PhysicsJoint with per-axis LimitAPI and DriveAPI instances; the rest are deactivated, and any NewtonMimicAPI newton:mimicJoint reference targeting them is redirected to the new D6 host. All authoring goes to the stage’s current edit target, so the caller should set that to the PhysX overlay layer (e.g. payloads/Physics/physx.usda) to keep MuJoCo/Newton variants untouched.

Parameters:: stage – USD stage to inspect for over-constrained joint groups.
Returns:: Number of joint groups that were combined into D6 joints.

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

Convert an 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 an 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 joint 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 an 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 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 an 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.