Python API reference#

This reference is generated from the installed library package and its public docstrings.

Public API for the asset importer utilities.

Re-exports the contents of the public utility submodules so callers can use short top-level imports (matching the documented top-level API surface):

from isaacsim.asset.importer.utils import collision_from_visuals, parse_robot_name

Those implementation submodules remain accessible via their original names:

from isaacsim.asset.importer.utils import importer_utils
importer_utils.collision_from_visuals(...)
class isaacsim.asset.importer.utils.PhysxAttr(
value,
names=<not given>,
*values,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)#

Bases: Enum

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.ValueTypeName object>)#

Articulation self-collision enabled (Bool).

JOINT_ARMATURE = ('physxJoint:armature', <pxr.Sdf.ValueTypeName object>)#

Joint armature (Float).

JOINT_FRICTION = ('physxJoint:jointFriction', <pxr.Sdf.ValueTypeName object>)#

Joint friction (Float).

JOINT_MAX_VELOCITY = ('physxJoint:maxJointVelocity', <pxr.Sdf.ValueTypeName object>)#

Maximum joint velocity (Float).

property name: str#

USD attribute name.

property type: ValueTypeName#

USD Sdf.ValueTypeNames type.

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

Bases: Enum

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").

Returns:

Formatted PhysxMimicJointAPI attribute name for axis.

GEARING = ('physxMimicJoint:{}:gearing', <pxr.Sdf.ValueTypeName object>)#

Mimic gearing multiplier (Float).

OFFSET = ('physxMimicJoint:{}:offset', <pxr.Sdf.ValueTypeName object>)#

Mimic offset (Float).

REFERENCE_JOINT_AXIS = ('physxMimicJoint:{}:referenceJointAxis', <pxr.Sdf.ValueTypeName object>)#

Reference joint axis token (Token).

property type: ValueTypeName#

USD Sdf.ValueTypeNames type.

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

Bases: Enum

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").

Returns:

Formatted PhysxMimicJointAPI relationship name for axis.

REFERENCE_JOINT = 'physxMimicJoint:{}:referenceJoint'#

Relationship to the reference (source) joint.

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

Bases: str, Enum

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

isaacsim.asset.importer.utils.add_joint_schemas(stage: Stage) → None#

Apply joint-related physics schemas to all joint prims.

Parameters:

stage – USD stage to update with joint schemas.

isaacsim.asset.importer.utils.add_rigid_body_schemas(stage: 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.

isaacsim.asset.importer.utils.apply_fix_base(stage: Stage) → None#

Add a world-to-root fixed joint when the robot is not already world-anchored.

When a fixed joint is created, move articulation-root authoring from the root rigid body to that joint. Existing world-anchoring joints of any type are preserved unchanged.

Parameters:

stage – The USD stage to modify.

isaacsim.asset.importer.utils.apply_floating_base(stage: Stage) → None#

Remove any joint anchoring the articulation to the world.

Inverse of apply_fix_base(). Removes world-anchoring joints found by _find_fixed_base_joints; internal and body1-empty joints are kept.

Parameters:

stage – The USD stage to modify.

isaacsim.asset.importer.utils.apply_joint_drives(
stage: Stage,
drive_type: str | dict[str, str] | None = None,
target_type: str | dict[str, str] | None = None,
stiffness: float | dict[str, float] | None = None,
damping: float | dict[str, float] | None = None,
) → None#

Set joint drive properties (type, target, gains) on USD joints.

Each parameter accepts either a single value (applied to all joints) or a dict mapping regex patterns to per-joint values.

Parameters:
  • stage – The USD stage to modify.

  • drive_type – Drive type string ("force" or "acceleration"), or a dict mapping joint-name regex patterns to drive type strings.

  • target_type – Target type string ("none", "position", or "velocity"), or a dict of patterns.

  • stiffness – Stiffness in Nm/rad (revolute) or N/m (prismatic), or a dict of patterns. Revolute values are converted to the USD Nm/deg convention internally.

  • damping – Damping in Nm*s/rad (revolute) or N*s/m (prismatic), or a dict of patterns. Same unit conversion as stiffness.

Set default density on rigid body links that have no explicit mass.

Parameters:
  • stage – The USD stage to modify.

  • density – The density value in kg/m^3.

isaacsim.asset.importer.utils.apply_mjc_actuator_gains(
stage: Stage,
gain_type: str | None,
bias_type: str | None,
gain_prm: list[float] | None,
bias_prm: list[float] | None,
) → int#

Set MJCF actuator gain parameters on all MjcActuator prims.

Finds every MjcActuator prim in the stage and writes the given gainType, biasType, gainPrm, and biasPrm attributes, following the encoding used by create_mjc_actuator_from_physics in urdf_to_mjc_physx_conversion_utils and read back by convert_mjc_actuator_to_physics in mjc_to_physx_conversion_utils.

Common configurations:

  • Position control (kp + kd): gain_type="fixed", bias_type="affine", gain_prm=[kp, 0, ...], bias_prm=[0, -kp, -kd, 0, ...]

  • Velocity control (kd only): gain_type="fixed", bias_type="affine", gain_prm=[kd, 0, ...], bias_prm=[0, 0, -kd, 0, ...]

Parameters:
  • stage – The USD stage containing MjcActuator prims.

  • gain_type – MuJoCo gain type string (e.g. "fixed"), or None to skip.

  • bias_type – MuJoCo bias type string (e.g. "affine"), or None to skip.

  • gain_prm – Gain parameter array (10 floats), or None to skip.

  • bias_prm – Bias parameter array (10 floats), or None to skip.

Returns:

Number of MjcActuator prims updated.

isaacsim.asset.importer.utils.clean_mesh_operation(stage: Stage) → None#

Clean mesh prims.

Parameters:

stage – USD stage for executing clean operations.

isaacsim.asset.importer.utils.collision_from_visuals(
stage: 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")  
isaacsim.asset.importer.utils.create_robot_schema(
stage: Stage,
robot_type: str = 'Default',
*,
prim_path: str | None = None,
add_sites: bool = True,
sites_last: bool = False,
) → tuple[Prim | None, 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.

isaacsim.asset.importer.utils.delete_scope(stage: 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.

isaacsim.asset.importer.utils.enable_self_collision(
usd_stage: 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.

isaacsim.asset.importer.utils.fix_articulation_root_for_fixed_base(stage: Stage) → int#

Move articulation-root authoring from fixed-base links to their world joints.

A fixed-base articulation is rooted at the world-to-root joint. Moving authoring to the joint avoids applying the schema to a geometric hierarchy parent that may carry scale or other non-physics transforms.

Parameters:

stage – The USD stage to modify.

Returns:

Number of articulation roots that were relocated.

isaacsim.asset.importer.utils.generate_mesh_uv_normals_operation(stage: Stage) → None#

Generate mesh UV normals.

Parameters:

stage – USD stage for executing generate operations.

isaacsim.asset.importer.utils.get_stage_id(stage: 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
isaacsim.asset.importer.utils.get_stage_time_code(
stage: Stage,
) → tuple[float, float, float]#

Get a stage’s time-code range and rate.

Parameters:

stage – USD stage to query.

Returns:

Start time code, end time code, and time codes per second.

Example:

>>> from isaacsim.asset.importer.utils import stage_utils
>>> from pxr import Usd
>>>
>>> stage = Usd.Stage.CreateInMemory()
>>> stage_utils.get_stage_time_code(stage)
(0.0, 0.0, 24.0)
isaacsim.asset.importer.utils.merge_mesh(stage: Stage, meshes: list[str]) → None#

Merge a list of mesh prim paths using USD Optimize.

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"])  
isaacsim.asset.importer.utils.merge_meshes_operation(stage: 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)  
isaacsim.asset.importer.utils.open_stage(usd_path: str) → 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_Multiphysics/FrankaRobotics/FrankaPanda/franka/franka.usda"
... )
>>> stage
Usd.Stage.Open(rootLayer=Sdf.Find('...'), ...)
isaacsim.asset.importer.utils.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'
isaacsim.asset.importer.utils.remove_custom_scopes(stage: Stage) → None#

Remove custom scopes from the stage.

Parameters:

stage – USD stage to update with custom scopes.

isaacsim.asset.importer.utils.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.

isaacsim.asset.importer.utils.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",
... )  
isaacsim.asset.importer.utils.save_stage(stage: 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
isaacsim.asset.importer.utils.set_stage_time_code(
stage: Stage,
*,
start_time_code: float | None = None,
end_time_code: float | None = None,
time_codes_per_second: float | None = None,
) → None#

Set a stage’s time-code range and rate.

Parameters:
  • stage – USD stage to modify.

  • start_time_code – Start time code to author.

  • end_time_code – End time code to author.

  • time_codes_per_second – Time codes per second to author.

Example:

>>> from isaacsim.asset.importer.utils import stage_utils
>>> from pxr import Usd
>>>
>>> stage = Usd.Stage.CreateInMemory()
>>> stage_utils.set_stage_time_code(stage, start_time_code=0.0, end_time_code=100.0)