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:
EnumPhysX attribute names and their USD value types.
Access the USD attribute name via
.nameand 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.ValueTypeNamestype.
- class isaacsim.asset.importer.utils.PhysxMimicAttr(
- value,
- names=<not given>,
- *values,
- module=None,
- qualname=None,
- type=None,
- start=1,
- boundary=None,
Bases:
EnumAttribute 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.ValueTypeNamestype.
- class isaacsim.asset.importer.utils.PhysxMimicRel(
- value,
- names=<not given>,
- *values,
- module=None,
- qualname=None,
- type=None,
- start=1,
- boundary=None,
Bases:
EnumRelationship 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,EnumSchema identifiers for
prim.ApplyAPI()andprim.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.MassAPIto 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,
Set joint drive properties (type, target, gains) on USD joints.
Each parameter accepts either a single value (applied to all joints) or a
dictmapping 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.
- isaacsim.asset.importer.utils.apply_link_density(stage: Stage, density: float) None#
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,
Set MJCF actuator gain parameters on all MjcActuator prims.
Finds every
MjcActuatorprim in the stage and writes the givengainType,biasType,gainPrm, andbiasPrmattributes, following the encoding used bycreate_mjc_actuator_from_physicsinurdf_to_mjc_physx_conversion_utilsand read back byconvert_mjc_actuator_to_physicsinmjc_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"), orNoneto skip.bias_type – MuJoCo bias type string (e.g.
"affine"), orNoneto skip.gain_prm – Gain parameter array (10 floats), or
Noneto skip.bias_prm – Bias parameter array (10 floats), or
Noneto 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,
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,
Apply the Isaac robot schema to a prim and populate link/joint relationships.
If the target prim already has the
IsaacRobotAPIapplied, the schema is recalculated (preserving existing ordering). Otherwise a freshRobotAPIis applied and populated from the articulation hierarchy.No-op with a warning if
usd.schema.isaac.robot_schemais 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
IsaacSiteAPIto them.sites_last – When
Trueall sites are appended at the end of the links list; whenFalseeach site follows its parent link.
- Returns:
A
(root_link, root_joint)tuple of the detected articulation root link and root joint. Either may beNone; both areNonewhen the robot schema module is unavailable.- Raises:
ValueError – If robot_type is not in
ROBOT_TYPE_TOKENSor 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,
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,
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
Nonethe 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,
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,
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)