isaaclab.sim.utils

isaaclab.sim.utils#

Utilities built around USD operations.

Submodules

stage

Utilities for operating on the USD stage.

queries

Utilities for querying the USD stage.

prims

Utilities for creating and manipulating USD prims.

semantics

Utilities for applying and removing semantic labels to USD prims.

legacy

Utilities for legacy functionality.

Stage#

Utilities for operating on the USD stage.

Functions:

create_new_stage()

Create a new stage attached to the USD context.

create_new_stage_in_memory()

Creates a new stage in memory, if supported.

is_current_stage_in_memory()

Checks if the current stage is in memory.

open_stage(usd_path)

Open the given usd file and replace currently opened stage.

use_stage(stage)

Context manager that sets a thread-local stage, if supported.

update_stage()

Updates the current stage by triggering an application update cycle.

save_stage(usd_path[, save_and_reload_in_place])

Saves contents of the root layer of the current stage to the specified USD file.

close_stage([callback_fn])

Closes the current USD stage.

clear_stage([predicate])

Deletes all prims in the stage without populating the undo command buffer.

is_stage_loading()

Convenience function to see if any files are being loaded.

get_current_stage([fabric])

Get the current open USD or Fabric stage

get_current_stage_id()

Get the current open stage ID.

attach_stage_to_usd_context([attaching_early])

Attaches the current USD stage in memory to the USD context.
isaaclab.sim.utils.stage.create_new_stage() → pxr.Usd.Stage[source]#

Create a new stage attached to the USD context.

Returns:

The created USD stage.

Return type:

Usd.Stage

Raises:

RuntimeError – When failed to create a new stage.

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> sim_utils.create_new_stage()
Usd.Stage.Open(rootLayer=Sdf.Find('anon:0x7fba6c04f840:World7.usd'),
               sessionLayer=Sdf.Find('anon:0x7fba6c01c5c0:World7-session.usda'),
               pathResolverContext=<invalid repr>)
isaaclab.sim.utils.stage.create_new_stage_in_memory() → pxr.Usd.Stage[source]#

Creates a new stage in memory, if supported.

New in version 2.3.0: This function is available in Isaac Sim 5.0 and later. For backwards compatibility, it falls back to creating a new stage attached to the USD context.

Returns:

The new stage in memory.

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> sim_utils.create_new_stage_in_memory()
Usd.Stage.Open(rootLayer=Sdf.Find('anon:0xf7b00e0:tmp.usda'),
               sessionLayer=Sdf.Find('anon:0xf7cd2e0:tmp-session.usda'),
               pathResolverContext=<invalid repr>)
isaaclab.sim.utils.stage.is_current_stage_in_memory() → bool[source]#

Checks if the current stage is in memory.

This function compares the stage id of the current USD stage with the stage id of the USD context stage.

Returns:

Whether the current stage is in memory.

isaaclab.sim.utils.stage.open_stage(usd_path: str) → bool[source]#

Open the given usd file and replace currently opened stage.

Parameters:

usd_path – The path to the USD file to open.

Returns:

True if operation is successful, otherwise False.

Raises:

ValueError – When input path is not a supported file type by USD.

isaaclab.sim.utils.stage.use_stage(stage: pxr.Usd.Stage) → Generator[None, None, None][source]#

Context manager that sets a thread-local stage, if supported.

This function binds the stage to the thread-local context for the duration of the context manager. During the context manager, any call to get_current_stage() will return the stage specified in the context manager. After the context manager is exited, the stage is restored to the default stage attached to the USD context.

New in version 2.3.0: This function is available in Isaac Sim 5.0 and later. For backwards compatibility, it falls back to a no-op context manager in Isaac Sim < 5.0.

Parameters:

stage – The stage to set in the context.

Returns:

A context manager that sets the stage in the context.

Raises:

AssertionError – If the stage is not a USD stage instance.

Example

>>> from pxr import Usd
>>> import isaaclab.sim as sim_utils
>>>
>>> stage_in_memory = Usd.Stage.CreateInMemory()
>>> with sim_utils.use_stage(stage_in_memory):
...    # operate on the specified stage
...    pass
>>> # operate on the default stage attached to the USD context
isaaclab.sim.utils.stage.update_stage() → None[source]#

Updates the current stage by triggering an application update cycle.

This function triggers a single update cycle of the application interface, which in turn updates the stage and all associated systems (rendering, physics, etc.). This is necessary to ensure that changes made to the stage are properly processed and reflected in the simulation.

Note

This function calls the application update interface rather than directly updating the stage because the stage update is part of the broader application update cycle that includes rendering, physics, and other systems.

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> sim_utils.update_stage()
isaaclab.sim.utils.stage.save_stage(usd_path: str, save_and_reload_in_place: bool = True) → bool[source]#

Saves contents of the root layer of the current stage to the specified USD file.

If the file already exists, it will be overwritten.

Parameters:

  • usd_path – The file path to save the current stage to

  • save_and_reload_in_place – Whether to open the saved USD file in place. Defaults to True.

Returns:

True if operation is successful, otherwise False.

Raises:

  • ValueError – When input path is not a supported file type by USD.

  • RuntimeError – When layer creation or save operation fails.

isaaclab.sim.utils.stage.close_stage(callback_fn: Callable[[bool, str], None] | None = None) → bool[source]#

Closes the current USD stage.

Note

Once the stage is closed, it is necessary to open a new stage or create a new one in order to work on it.

Parameters:

callback_fn – A callback function to call while closing the stage. The function should take two arguments: a boolean indicating whether the stage is closing and a string indicating the error message if the stage closing fails. Defaults to None, in which case the stage will be closed without a callback.

Returns:

True if operation is successful, otherwise False.

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> sim_utils.close_stage()
True
>>>
Example with callback function:
>>> import isaaclab.sim as sim_utils
>>>
>>> def callback(*args, **kwargs):
...     print("callback:", args, kwargs)
...
>>> sim_utils.close_stage(callback)
True
>>> sim_utils.close_stage(callback)
callback: (False, 'Stage opening or closing already in progress!!') {}
False
isaaclab.sim.utils.stage.clear_stage(predicate: Callable[[pxr.Usd.Prim], bool] | None = None) → None[source]#

Deletes all prims in the stage without populating the undo command buffer.

The function will delete all prims in the stage that satisfy the predicate. If the predicate is None, a default predicate will be used that deletes all prims. The default predicate deletes all prims that are not the root prim, are not under the /Render namespace, have the no_delete metadata, are not ancestral to any other prim, and are not hidden in the stage window.

Parameters:

predicate – A user defined function that takes the USD prim as an argument and returns a boolean indicating if the prim should be deleted. If the predicate is None, a default predicate will be used that deletes all prims.

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> # clear the whole stage
>>> sim_utils.clear_stage()
>>>
>>> # given the stage: /World/Cube, /World/Cube_01, /World/Cube_02.
>>> # Delete only the prims of type Cube
>>> predicate = lambda _prim: _prim.GetTypeName() == "Cube"
>>> sim_utils.clear_stage(predicate)  # after the execution the stage will be /World
isaaclab.sim.utils.stage.is_stage_loading() → bool[source]#

Convenience function to see if any files are being loaded.

Returns:

True if loading, False otherwise

Return type:

bool

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> sim_utils.is_stage_loading()
False
isaaclab.sim.utils.stage.get_current_stage(fabric: bool = False) → pxr.Usd.Stage[source]#

Get the current open USD or Fabric stage

Parameters:

fabric – True to get the fabric stage. False to get the USD stage. Defaults to False.

Returns:

The USD or Fabric stage as specified by the input arg fabric.

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> sim_utils.get_current_stage()
Usd.Stage.Open(rootLayer=Sdf.Find('anon:0x7fba6c04f840:World7.usd'),
               sessionLayer=Sdf.Find('anon:0x7fba6c01c5c0:World7-session.usda'),
               pathResolverContext=<invalid repr>)
isaaclab.sim.utils.stage.get_current_stage_id() → int[source]#

Get the current open stage ID.

Returns:

The current open stage id.

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> sim_utils.get_current_stage_id()
1234567890
isaaclab.sim.utils.stage.attach_stage_to_usd_context(attaching_early: bool = False)[source]#

Attaches the current USD stage in memory to the USD context.

This function should be called during or after scene is created and before stage is simulated or rendered. If the stage is not in memory or rendering is not enabled, this function will return without attaching.

New in version 2.3.0: This function is available in Isaac Sim 5.0 and later. For backwards compatibility, it returns without attaching to the USD context.

Parameters:

attaching_early – Whether to attach the stage to the usd context before stage is created. Defaults to False.

Queries#

Utilities for querying the USD stage.

Functions:

get_next_free_prim_path(path[, stage])

Gets a new prim path that doesn't exist in the stage given a base path.

get_first_matching_ancestor_prim(prim_path, ...)

Gets the first ancestor prim that passes the predicate function.

get_first_matching_child_prim(prim_path, ...)

Recursively get the first USD Prim at the path string that passes the predicate function.

get_all_matching_child_prims(prim_path[, ...])

Performs a search starting from the root and returns all the prims matching the predicate.

find_first_matching_prim(prim_path_regex[, ...])

Find the first matching prim in the stage based on input regex expression.

find_matching_prims(prim_path_regex[, stage])

Find all the matching prims in the stage based on input regex expression.

find_matching_prim_paths(prim_path_regex[, ...])

Find all the matching prim paths in the stage based on input regex expression.

find_global_fixed_joint_prim(prim_path[, ...])

Find the fixed joint prim under the specified prim path that connects the target to the simulation world.
isaaclab.sim.utils.queries.get_next_free_prim_path(path: str, stage: Usd.Stage | None = None) → str[source]#

Gets a new prim path that doesn’t exist in the stage given a base path.

If the given path doesn’t exist in the stage already, it returns the given path. Otherwise, it appends a suffix with an incrementing number to the given path.

Parameters:

  • path – The base prim path to check.

  • stage – The stage to check. Defaults to the current stage.

Returns:

A new path that is guaranteed to not exist on the current stage

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> # given the stage: /World/Cube, /World/Cube_01.
>>> # Get the next available path for /World/Cube
>>> sim_utils.get_next_free_prim_path("/World/Cube")
/World/Cube_02
isaaclab.sim.utils.queries.get_first_matching_ancestor_prim(prim_path: str | Sdf.Path, predicate: Callable[[Usd.Prim], bool], stage: Usd.Stage | None = None) → Usd.Prim | None[source]#

Gets the first ancestor prim that passes the predicate function.

This function walks up the prim hierarchy starting from the target prim and returns the first ancestor prim that passes the predicate function. This includes the prim itself if it passes the predicate.

Parameters:

  • prim_path – The path of the prim in the stage.

  • predicate – The function to test the prims against. It takes a prim as input and returns a boolean.

  • stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Returns:

The first ancestor prim that passes the predicate. If no ancestor prim passes the predicate, it returns None.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

isaaclab.sim.utils.queries.get_first_matching_child_prim(prim_path: str | Sdf.Path, predicate: Callable[[Usd.Prim], bool], stage: Usd.Stage | None = None, traverse_instance_prims: bool = True) → Usd.Prim | None[source]#

Recursively get the first USD Prim at the path string that passes the predicate function.

This function performs a depth-first traversal of the prim hierarchy starting from prim_path, returning the first prim that satisfies the provided predicate. It optionally supports traversal through instance prims, which are normally skipped in standard USD traversals.

USD instance prims are lightweight copies of prototype scene structures and are not included in default traversals unless explicitly handled. This function allows traversing into instances when traverse_instance_prims is set to True.

Changed in version 2.3.0: Added traverse_instance_prims to control whether to traverse instance prims. By default, instance prims are now traversed.

Parameters:

  • prim_path – The path of the prim in the stage.

  • predicate – The function to test the prims against. It takes a prim as input and returns a boolean.

  • stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

  • traverse_instance_prims – Whether to traverse instance prims. Defaults to True.

Returns:

The first prim on the path that passes the predicate. If no prim passes the predicate, it returns None.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

isaaclab.sim.utils.queries.get_all_matching_child_prims(prim_path: str | Sdf.Path, predicate: Callable[[Usd.Prim], bool] = <function <lambda>>, depth: int | None = None, stage: Usd.Stage | None = None, traverse_instance_prims: bool = True) → list[Usd.Prim][source]#

Performs a search starting from the root and returns all the prims matching the predicate.

This function performs a depth-first traversal of the prim hierarchy starting from prim_path, returning all prims that satisfy the provided predicate. It optionally supports traversal through instance prims, which are normally skipped in standard USD traversals.

USD instance prims are lightweight copies of prototype scene structures and are not included in default traversals unless explicitly handled. This function allows traversing into instances when traverse_instance_prims is set to True.

Changed in version 2.3.0: Added traverse_instance_prims to control whether to traverse instance prims. By default, instance prims are now traversed.

Parameters:

  • prim_path – The root prim path to start the search from.

  • predicate – The predicate that checks if the prim matches the desired criteria. It takes a prim as input and returns a boolean. Defaults to a function that always returns True.

  • depth – The maximum depth for traversal, should be bigger than zero if specified. Defaults to None (i.e: traversal happens till the end of the tree).

  • stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

  • traverse_instance_prims – Whether to traverse instance prims. Defaults to True.

Returns:

A list containing all the prims matching the predicate.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

isaaclab.sim.utils.queries.find_first_matching_prim(prim_path_regex: str, stage: Usd.Stage | None = None) → Usd.Prim | None[source]#

Find the first matching prim in the stage based on input regex expression.

Parameters:

  • prim_path_regex – The regex expression for prim path.

  • stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Returns:

The first prim that matches input expression. If no prim matches, returns None.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

isaaclab.sim.utils.queries.find_matching_prims(prim_path_regex: str, stage: Usd.Stage | None = None) → list[Usd.Prim][source]#

Find all the matching prims in the stage based on input regex expression.

Parameters:

  • prim_path_regex – The regex expression for prim path.

  • stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Returns:

A list of prims that match input expression.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

isaaclab.sim.utils.queries.find_matching_prim_paths(prim_path_regex: str, stage: Usd.Stage | None = None) → list[str][source]#

Find all the matching prim paths in the stage based on input regex expression.

Parameters:

  • prim_path_regex – The regex expression for prim path.

  • stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Returns:

A list of prim paths that match input expression.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

isaaclab.sim.utils.queries.find_global_fixed_joint_prim(prim_path: str | Sdf.Path, check_enabled_only: bool = False, stage: Usd.Stage | None = None) → UsdPhysics.Joint | None[source]#

Find the fixed joint prim under the specified prim path that connects the target to the simulation world.

A joint is a connection between two bodies. A fixed joint is a joint that does not allow relative motion between the two bodies. When a fixed joint has only one target body, it is considered to attach the body to the simulation world.

This function finds the fixed joint prim that has only one target under the specified prim path. If no such fixed joint prim exists, it returns None.

Parameters:

  • prim_path – The prim path to search for the fixed joint prim.

  • check_enabled_only – Whether to consider only enabled fixed joints. Defaults to False. If False, then all joints (enabled or disabled) are considered.

  • stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Returns:

The fixed joint prim that has only one target. If no such fixed joint prim exists, it returns None.

Raises:

  • ValueError – If the prim path is not global (i.e: does not start with ‘/’).

  • ValueError – If the prim path does not exist on the stage.

Prims#

Utilities for creating and manipulating USD prims.

Functions:

create_prim(prim_path[, prim_type, ...])

Creates a prim in the provided USD stage.

delete_prim(prim_path[, stage])

Removes the USD Prim and its descendants from the scene if able.

move_prim(path_from, path_to[, ...])

Moves a prim from one path to another within a USD stage.

make_uninstanceable(prim_path[, stage])

Check if a prim and its descendants are instanced and make them uninstanceable.

resolve_prim_pose(prim[, ref_prim])

Resolve the pose of a prim with respect to another prim.

resolve_prim_scale(prim)

Resolve the scale of a prim in the world frame.

set_prim_visibility(prim, visible)

Sets the visibility of the prim in the opened stage.

safe_set_attribute_on_usd_schema(schema_api, ...)

Set the value of an attribute on its USD schema if it exists.

safe_set_attribute_on_usd_prim(prim, ...)

Set the value of a attribute on its USD prim.

export_prim_to_file(path, source_prim_path)

Exports a prim from a given stage to a USD file.

apply_nested(func)

Decorator to apply a function to all prims under a specified prim-path.

clone(func)

Decorator for cloning a prim based on matching prim paths of the prim's parent.

bind_visual_material(prim_path, material_path)

Bind a visual material to a prim.

bind_physics_material(prim_path, material_path)

Bind a physics material to a prim.

add_usd_reference(prim_path, usd_path[, ...])

Adds a USD reference at the specified prim path on the provided stage.

get_usd_references(prim_path[, stage])

Gets the USD references at the specified prim path on the provided stage.

select_usd_variants(prim_path, variants[, stage])

Sets the variant selections from the specified variant sets on a USD prim.
isaaclab.sim.utils.prims.logger = <Logger isaaclab.sim.utils.prims (WARNING)>#

General Utils

isaaclab.sim.utils.prims.create_prim(prim_path: str, prim_type: str = 'Xform', position: Sequence[float] | None = None, translation: Sequence[float] | None = None, orientation: Sequence[float] | None = None, scale: Sequence[float] | None = None, usd_path: str | None = None, semantic_label: str | None = None, semantic_type: str = 'class', attributes: dict | None = None, stage: Usd.Stage | None = None) → Usd.Prim[source]#

Creates a prim in the provided USD stage.

The method applies the specified transforms, the semantic label and sets the specified attributes.

Parameters:

  • prim_path – The path of the new prim.

  • prim_type – Prim type name

  • position – prim position (applied last)

  • translation – prim translation (applied last)

  • orientation – prim rotation as quaternion

  • scale – scaling factor in x, y, z.

  • usd_path – Path to the USD that this prim will reference.

  • semantic_label – Semantic label.

  • semantic_type – set to “class” unless otherwise specified.

  • attributes – Key-value pairs of prim attributes to set.

  • stage – The stage to create the prim in. Defaults to None, in which case the current stage is used.

Returns:

The created USD prim.

Raises:

ValueError – If there is already a prim at the provided prim_path.

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> # create a cube (/World/Cube) of size 2 centered at (1.0, 0.5, 0.0)
>>> sim_utils.create_prim(
...     prim_path="/World/Cube",
...     prim_type="Cube",
...     position=(1.0, 0.5, 0.0),
...     attributes={"size": 2.0}
... )
Usd.Prim(</World/Cube>)
isaaclab.sim.utils.prims.delete_prim(prim_path: str | Sequence[str], stage: Usd.Stage | None = None) → None[source]#

Removes the USD Prim and its descendants from the scene if able.

Parameters:

  • prim_path – The path of the prim to delete. If a list of paths is provided, the function will delete all the prims in the list.

  • stage – The stage to delete the prim in. Defaults to None, in which case the current stage is used.

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> sim_utils.delete_prim("/World/Cube")
isaaclab.sim.utils.prims.move_prim(path_from: str, path_to: str, keep_world_transform: bool = True, stage: Usd.Stage | None = None) → None[source]#

Moves a prim from one path to another within a USD stage.

This function moves the prim from the source path to the destination path. If the keep_world_transform is set to True, the world transform of the prim is kept. This implies that the prim’s local transform is reset such that the prim’s world transform is the same as the source path’s world transform. If it is set to False, the prim’s local transform is preserved.

Warning

Reparenting or moving prims in USD is an expensive operation that may trigger significant recomposition costs, especially in large or deeply layered stages.

Parameters:

  • path_from – Path of the USD Prim you wish to move

  • path_to – Final destination of the prim

  • keep_world_transform – Whether to keep the world transform of the prim. Defaults to True.

  • stage – The stage to move the prim in. Defaults to None, in which case the current stage is used.

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> # given the stage: /World/Cube. Move the prim Cube outside the prim World
>>> sim_utils.move_prim("/World/Cube", "/Cube")
isaaclab.sim.utils.prims.make_uninstanceable(prim_path: str | Sdf.Path, stage: Usd.Stage | None = None)[source]#

Check if a prim and its descendants are instanced and make them uninstanceable.

This function checks if the prim at the specified prim path and its descendants are instanced. If so, it makes the respective prim uninstanceable by disabling instancing on the prim.

This is useful when we want to modify the properties of a prim that is instanced. For example, if we want to apply a different material on an instanced prim, we need to make the prim uninstanceable first.

Parameters:

  • prim_path – The prim path to check.

  • stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Raises:

ValueError – If the prim path is not global (i.e: does not start with ‘/’).

isaaclab.sim.utils.prims.resolve_prim_pose(prim: Usd.Prim, ref_prim: Usd.Prim | None = None) → tuple[tuple[float, float, float], tuple[float, float, float, float]][source]#

Resolve the pose of a prim with respect to another prim.

Note

This function ignores scale and skew by orthonormalizing the transformation matrix at the final step. However, if any ancestor prim in the hierarchy has non-uniform scale, that scale will still affect the resulting position and orientation of the prim (because it’s baked into the transform before scale removal).

In other words: scale is not removed hierarchically. If you need completely scale-free poses, you must walk the transform chain and strip scale at each level. Please open an issue if you need this functionality.

Parameters:

  • prim – The USD prim to resolve the pose for.

  • ref_prim – The USD prim to compute the pose with respect to. Defaults to None, in which case the world frame is used.

Returns:

A tuple containing the position (as a 3D vector) and the quaternion orientation in the (w, x, y, z) format.

Raises:

ValueError – If the prim or ref prim is not valid.

isaaclab.sim.utils.prims.resolve_prim_scale(prim: pxr.Usd.Prim) → tuple[float, float, float][source]#

Resolve the scale of a prim in the world frame.

At an attribute level, a USD prim’s scale is a scaling transformation applied to the prim with respect to its parent prim. This function resolves the scale of the prim in the world frame, by computing the local to world transform of the prim. This is equivalent to traversing up the prim hierarchy and accounting for the rotations and scales of the prims.

For instance, if a prim has a scale of (1, 2, 3) and it is a child of a prim with a scale of (4, 5, 6), then the scale of the prim in the world frame is (4, 10, 18).

Parameters:

prim – The USD prim to resolve the scale for.

Returns:

The scale of the prim in the x, y, and z directions in the world frame.

Raises:

ValueError – If the prim is not valid.

isaaclab.sim.utils.prims.set_prim_visibility(prim: pxr.Usd.Prim, visible: bool) → None[source]#

Sets the visibility of the prim in the opened stage.

Note

The method does this through the USD API.

Parameters:

  • prim – the USD prim

  • visible – flag to set the visibility of the usd prim in stage.

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> # given the stage: /World/Cube. Make the Cube not visible
>>> prim = sim_utils.get_prim_at_path("/World/Cube")
>>> sim_utils.set_prim_visibility(prim, False)
isaaclab.sim.utils.prims.safe_set_attribute_on_usd_schema(schema_api: pxr.Usd.APISchemaBase, name: str, value: Any, camel_case: bool)[source]#

Set the value of an attribute on its USD schema if it exists.

A USD API schema serves as an interface or API for authoring and extracting a set of attributes. They typically derive from the pxr.Usd.SchemaBase class. This function checks if the attribute exists on the schema and sets the value of the attribute if it exists.

Parameters:

  • schema_api – The USD schema to set the attribute on.

  • name – The name of the attribute.

  • value – The value to set the attribute to.

  • camel_case – Whether to convert the attribute name to camel case.

Raises:

TypeError – When the input attribute name does not exist on the provided schema API.

isaaclab.sim.utils.prims.safe_set_attribute_on_usd_prim(prim: pxr.Usd.Prim, attr_name: str, value: Any, camel_case: bool)[source]#

Set the value of a attribute on its USD prim.

The function creates a new attribute if it does not exist on the prim. This is because in some cases (such as with shaders), their attributes are not exposed as USD prim properties that can be altered. This function allows us to set the value of the attributes in these cases.

Parameters:

  • prim – The USD prim to set the attribute on.

  • attr_name – The name of the attribute.

  • value – The value to set the attribute to.

  • camel_case – Whether to convert the attribute name to camel case.

isaaclab.sim.utils.prims.export_prim_to_file(path: str | Sdf.Path, source_prim_path: str | Sdf.Path, target_prim_path: str | Sdf.Path | None = None, stage: Usd.Stage | None = None)[source]#

Exports a prim from a given stage to a USD file.

The function creates a new layer at the provided path and copies the prim to the layer. It sets the copied prim as the default prim in the target layer. Additionally, it updates the stage up-axis and meters-per-unit to match the current stage.

Parameters:

  • path – The filepath path to export the prim to.

  • source_prim_path – The prim path to export.

  • target_prim_path – The prim path to set as the default prim in the target layer. Defaults to None, in which case the source prim path is used.

  • stage – The stage where the prim exists. Defaults to None, in which case the current stage is used.

Raises:

ValueError – If the prim paths are not global (i.e: do not start with ‘/’).

isaaclab.sim.utils.prims.apply_nested(func: Callable) → Callable[source]#

Decorator to apply a function to all prims under a specified prim-path.

The function iterates over the provided prim path and all its children to apply input function to all prims under the specified prim path.

If the function succeeds to apply to a prim, it will not look at the children of that prim. This is based on the physics behavior that nested schemas are not allowed. For example, a parent prim and its child prim cannot both have a rigid-body schema applied on them, or it is not possible to have nested articulations.

While traversing the prims under the specified prim path, the function will throw a warning if it does not succeed to apply the function to any prim. This is because the user may have intended to apply the function to a prim that does not have valid attributes, or the prim may be an instanced prim.

Parameters:

func – The function to apply to all prims under a specified prim-path. The function must take the prim-path and other arguments. It should return a boolean indicating whether the function succeeded or not.

Returns:

The wrapped function that applies the function to all prims under a specified prim-path.

Raises:

ValueError – If the prim-path does not exist on the stage.

isaaclab.sim.utils.prims.clone(func: Callable) → Callable[source]#

Decorator for cloning a prim based on matching prim paths of the prim’s parent.

The decorator checks if the parent prim path matches any prim paths in the stage. If so, it clones the spawned prim at each matching prim path. For example, if the input prim path is: /World/Table_[0-9]/Bottle, the decorator will clone the prim at each matching prim path of the parent prim: /World/Table_0/Bottle, /World/Table_1/Bottle, etc.

Note

For matching prim paths, the decorator assumes that valid prims exist for all matching prim paths. In case no matching prim paths are found, the decorator raises a RuntimeError.

Parameters:

func – The function to decorate.

Returns:

The decorated function that spawns the prim and clones it at each matching prim path. It returns the spawned source prim, i.e., the first prim in the list of matching prim paths.

isaaclab.sim.utils.prims.bind_visual_material(prim_path: str | Sdf.Path, material_path: str | Sdf.Path, stage: Usd.Stage | None = None, stronger_than_descendants: bool = True)[source]#

Bind a visual material to a prim.

This function is a wrapper around the USD command BindMaterialCommand.

Note

The function is decorated with apply_nested() to allow applying the function to a prim path and all its descendants.

Parameters:

  • prim_path – The prim path where to apply the material.

  • material_path – The prim path of the material to apply.

  • stage – The stage where the prim and material exist. Defaults to None, in which case the current stage is used.

  • stronger_than_descendants – Whether the material should override the material of its descendants. Defaults to True.

Raises:

ValueError – If the provided prim paths do not exist on stage.

isaaclab.sim.utils.prims.bind_physics_material(prim_path: str | Sdf.Path, material_path: str | Sdf.Path, stage: Usd.Stage | None = None, stronger_than_descendants: bool = True)[source]#

Bind a physics material to a prim.

Physics material can be applied only to a prim with physics-enabled on them. This includes having collision APIs, or deformable body APIs, or being a particle system. In case the prim does not have any of these APIs, the function will not apply the material and return False.

Note

The function is decorated with apply_nested() to allow applying the function to a prim path and all its descendants.

Parameters:

  • prim_path – The prim path where to apply the material.

  • material_path – The prim path of the material to apply.

  • stage – The stage where the prim and material exist. Defaults to None, in which case the current stage is used.

  • stronger_than_descendants – Whether the material should override the material of its descendants. Defaults to True.

Raises:

ValueError – If the provided prim paths do not exist on stage.

isaaclab.sim.utils.prims.add_usd_reference(prim_path: str, usd_path: str, prim_type: str = 'Xform', stage: Usd.Stage | None = None) → Usd.Prim[source]#

Adds a USD reference at the specified prim path on the provided stage.

This function adds a reference to an external USD file at the specified prim path on the provided stage. If the prim does not exist, it will be created with the specified type.

The function also handles stage units verification to ensure compatibility. For instance, if the current stage is in meters and the referenced USD file is in centimeters, the function will convert the units to match. This is done using the omni.metrics.assembler functionality.

Parameters:

  • prim_path – The prim path where the reference will be attached.

  • usd_path – The path to USD file to reference.

  • prim_type – The type of prim to create if it doesn’t exist. Defaults to “Xform”.

  • stage – The stage to add the reference to. Defaults to None, in which case the current stage is used.

Returns:

The USD prim at the specified prim path.

Raises:

FileNotFoundError – When the input USD file is not found at the specified path.

isaaclab.sim.utils.prims.get_usd_references(prim_path: str, stage: Usd.Stage | None = None) → list[str][source]#

Gets the USD references at the specified prim path on the provided stage.

Parameters:

  • prim_path – The prim path to get the USD references from.

  • stage – The stage to get the USD references from. Defaults to None, in which case the current stage is used.

Returns:

A list of USD reference paths.

isaaclab.sim.utils.prims.select_usd_variants(prim_path: str, variants: object | dict[str, str], stage: Usd.Stage | None = None)[source]#

Sets the variant selections from the specified variant sets on a USD prim.

USD Variants are a very powerful tool in USD composition that allows prims to have different options on a single asset. This can be done by modifying variations of the same prim parameters per variant option in a set. This function acts as a script-based utility to set the variant selections for the specified variant sets on a USD prim.

The function takes a dictionary or a config class mapping variant set names to variant selections. For instance, if we have a prim at "/World/Table" with two variant sets: “color” and “size”, we can set the variant selections as follows:

select_usd_variants(
    prim_path="/World/Table",
    variants={
        "color": "red",
        "size": "large",
    },
)

Alternatively, we can use a config class to define the variant selections:

@configclass
class TableVariants:
    color: Literal["blue", "red"] = "red"
    size: Literal["small", "large"] = "large"

select_usd_variants(
    prim_path="/World/Table",
    variants=TableVariants(),
)
Parameters:

  • prim_path – The path of the USD prim.

  • variants – A dictionary or config class mapping variant set names to variant selections.

  • stage – The USD stage. Defaults to None, in which case, the current stage is used.

Raises:

ValueError – If the prim at the specified path is not valid.

Semantics#

Utilities for applying and removing semantic labels to USD prims.

Functions:

add_labels(prim, labels[, instance_name, ...])

Apply semantic labels to a prim using the UsdSemantics.LabelsAPI.

get_labels(prim)

Get all semantic labels (UsdSemantics.LabelsAPI) applied to a prim.

remove_labels(prim[, instance_name, ...])

Removes semantic labels (UsdSemantics.LabelsAPI) from a prim and optionally its descendants.

check_missing_labels([prim_path, stage])

Checks whether the prim and its descendants at the provided path have missing semantic labels (UsdSemantics.LabelsAPI).

count_total_labels([prim_path, stage])

Counts the number of semantic labels (UsdSemantics.LabelsAPI) applied to the prims at the provided path.
isaaclab.sim.utils.semantics.add_labels(prim: pxr.Usd.Prim, labels: list[str], instance_name: str = 'class', overwrite: bool = True) → None[source]#

Apply semantic labels to a prim using the UsdSemantics.LabelsAPI.

This function is a wrapper around the omni.replicator.core.functional.modify.semantics() function. It applies the labels to the prim using the UsdSemantics.LabelsAPI.

New in version 2.3.0: This function is available in Isaac Sim 5.0 and later, which introduces the UsdSemantics.LabelsAPI. For previous versions, the function falls back to use the deprecated UsdSemantics.SemanticsAPI instead.

Example

>>> prim = sim_utils.create_prim("/World/Test/Sphere", "Sphere", stage=stage, attributes={"radius": 10.0})
>>> sim_utils.add_labels(prim, labels=["sphere"], instance_name="class")
Parameters:

  • prim – The USD prim to add or update labels on.

  • labels – The list of labels to apply.

  • instance_name – The name of the semantic instance. Defaults to “class”.

  • overwrite – Whether to overwrite existing labels for this instance. If False, the new labels are appended to existing ones (if any). Defaults to True.

isaaclab.sim.utils.semantics.get_labels(prim: pxr.Usd.Prim) → dict[str, list[str]][source]#

Get all semantic labels (UsdSemantics.LabelsAPI) applied to a prim.

New in version 2.3.0: This function is available in Isaac Sim 5.0 and later. For previous versions, please use isaacsim.core.utils.semantics module instead.

Parameters:

prim – The USD prim to return labels for.

Returns:

A dictionary mapping instance names to a list of labels. If no labels are found, it returns an empty dictionary.

isaaclab.sim.utils.semantics.remove_labels(prim: pxr.Usd.Prim, instance_name: str | None = None, include_descendants: bool = False)[source]#

Removes semantic labels (UsdSemantics.LabelsAPI) from a prim and optionally its descendants.

New in version 2.3.0: This function is available in Isaac Sim 5.0 and later. For previous versions, please use isaacsim.core.utils.semantics module instead.

Parameters:

  • prim – The USD prim to remove labels from.

  • instance_name – The specific instance name to remove. Defaults to None, in which case all labels are removed.

  • include_descendants – Whether to also traverse children and remove labels recursively. Defaults to False.

isaaclab.sim.utils.semantics.check_missing_labels(prim_path: str | None = None, stage: Usd.Stage | None = None) → list[str][source]#

Checks whether the prim and its descendants at the provided path have missing semantic labels (UsdSemantics.LabelsAPI).

Note

The function checks only prims that are UsdGeom.Gprim type.

New in version 2.3.0: This function is available in Isaac Sim 5.0 and later. For previous versions, please use isaacsim.core.utils.semantics module instead.

Parameters:

  • prim_path – The prim path to search from. If None, the entire stage is inspected.

  • stage – The stage to search from. If None, the current stage is used.

Returns:

A list containing prim paths to prims with no labels applied.

isaaclab.sim.utils.semantics.count_total_labels(prim_path: str | None = None, stage: Usd.Stage | None = None) → dict[str, int][source]#

Counts the number of semantic labels (UsdSemantics.LabelsAPI) applied to the prims at the provided path.

This function iterates over all the prims from the provided path and counts the number of times each label is applied to the prims. It returns a dictionary of labels and their corresponding count.

New in version 2.3.0: This function is available in Isaac Sim 5.0 and later. For previous versions, please use isaacsim.core.utils.semantics module instead.

Parameters:

  • prim_path – The prim path to search from. If None, the entire stage is inspected.

  • stage – The stage to search from. If None, the current stage is used.

Returns:

A dictionary mapping individual labels to their total count across all instances. The dictionary includes a ‘missing_labels’ count for prims with no labels.

Legacy#

Utilities for legacy functionality.

This sub-module contains legacy functions from Isaac Sim that are no longer required for Isaac Lab. Most functions are simple wrappers around USD APIs and are provided mainly for convenience.

It is recommended to use the USD APIs directly whenever possible.

Functions:

add_reference_to_stage(usd_path, path[, ...])

Adds a USD reference to the stage at the specified prim path.

get_stage_up_axis()

Gets the up axis of the stage.

traverse_stage([fabric])

Traverses the stage and returns all the prims.

get_prim_at_path(prim_path[, fabric])

Gets the USD prim at the specified path.

get_prim_path(prim)

Gets the path of the specified USD prim.

is_prim_path_valid(prim_path[, fabric])

Check if a path has a valid USD Prim on the specified stage.

define_prim(prim_path[, prim_type, fabric])

Create a USD Prim at the given prim_path of type prim type unless one already exists.

get_prim_type_name(prim_path[, fabric])

Get the type name of the USD Prim at the provided path.

get_next_free_path(path)

Gets a new prim path that doesn't exist in the stage given a base path.
isaaclab.sim.utils.legacy.logger = <Logger isaaclab.sim.utils.legacy (WARNING)>#

Stage utilities.

isaaclab.sim.utils.legacy.add_reference_to_stage(usd_path: str, path: str, prim_type: str = 'Xform') → pxr.Usd.Prim[source]#

Adds a USD reference to the stage at the specified prim path.

Deprecated since version 2.3.0: This function is deprecated. Please use the isaaclab.sim.utils.prims.add_usd_reference() function instead.

Parameters:

  • usd_path – The path to the USD file to reference.

  • path – The prim path to add the reference to.

  • prim_type – The type of prim to create if it doesn’t exist. Defaults to “Xform”.

Returns:

The USD prim at the specified prim path.

isaaclab.sim.utils.legacy.get_stage_up_axis() → str[source]#

Gets the up axis of the stage.

Deprecated since version 2.3.0: This function is deprecated. Please use the USD APIs directly instead.

>>> import isaaclab.sim as sim_utils
>>> from pxr import UsdGeom
>>>
>>> UsdGeom.GetStageUpAxis(sim_utils.get_current_stage())
'Z'
isaaclab.sim.utils.legacy.traverse_stage(fabric: bool = False) → Iterable[pxr.Usd.Prim][source]#

Traverses the stage and returns all the prims.

Deprecated since version 2.3.0: This function is deprecated. Please use the USD APIs directly instead.

>>> import isaaclab.sim as sim_utils
>>>
>>> stage = sim_utils.get_current_stage()
>>> for prim in stage.Traverse():
>>>     print(prim)
Usd.Prim(</World>)
Usd.Prim(</World/Cube>)
Usd.Prim(</World/Cube_01>)
Usd.Prim(</World/Cube_02>)
Parameters:

fabric – True for fabric stage and False for USD stage. Defaults to False.

Returns:

An iterable of all the prims in the stage.

isaaclab.sim.utils.legacy.get_prim_at_path(prim_path: str, fabric: bool = False) → Usd.Prim | None[source]#

Gets the USD prim at the specified path.

Deprecated since version 2.3.0: This function is deprecated. Please use the USD APIs directly instead.

>>> import isaaclab.sim as sim_utils
>>>
>>> stage = sim_utils.get_current_stage()
>>> stage.GetPrimAtPath("/World/Cube")
Usd.Prim(</World/Cube>)
Parameters:

  • prim_path – The path of the prim to get.

  • fabric – Whether to get the prim from the fabric stage. Defaults to False.

Returns:

The USD prim at the specified path. If stage is not found, returns None.

isaaclab.sim.utils.legacy.get_prim_path(prim: pxr.Usd.Prim) → str[source]#

Gets the path of the specified USD prim.

Deprecated since version 2.3.0: This function is deprecated. Please use the USD APIs directly instead.

>>> import isaaclab.sim as sim_utils
>>>
>>> stage = sim_utils.get_current_stage()
>>> prim = stage.GetPrimAtPath("/World/Cube")
>>> prim.GetPath().pathString
"/World/Cube"
Parameters:

prim – The USD prim to get the path of.

Returns:

The path of the specified USD prim.

isaaclab.sim.utils.legacy.is_prim_path_valid(prim_path: str, fabric: bool = False) → bool[source]#

Check if a path has a valid USD Prim on the specified stage.

Deprecated since version 2.3.0: This function is deprecated. Please use the USD APIs directly instead.

>>> import isaaclab.sim as sim_utils
>>>
>>> stage = sim_utils.get_current_stage()
>>> prim = stage.GetPrimAtPath("/World/Cube")
>>> prim.IsValid()
True
Parameters:

  • prim_path – path of the prim in the stage

  • fabric – True for fabric stage and False for USD stage. Defaults to False.

Returns:

True if the path points to a valid prim. False otherwise.

isaaclab.sim.utils.legacy.define_prim(prim_path: str, prim_type: str = 'Xform', fabric: bool = False) → pxr.Usd.Prim[source]#

Create a USD Prim at the given prim_path of type prim type unless one already exists.

This function creates a prim of the specified type in the specified path. To apply a transformation (position, orientation, scale), set attributes or load an USD file while creating the prim use the isaaclab.sim.utils.prims.create_prim() function.

Deprecated since version 2.3.0: This function is deprecated. Please use the USD APIs directly instead. In case, a new prim is needed, use the isaaclab.sim.utils.prims.create_prim() function instead.

>>> import isaaclab.sim as sim_utils
>>>
>>> stage = sim_utils.get_current_stage()
>>> stage.DefinePrim("/World/Shapes", "Xform")
Usd.Prim(</World/Shapes>)
Parameters:

  • prim_path – path of the prim in the stage

  • prim_type – The type of the prim to create. Defaults to “Xform”.

  • fabric – True for fabric stage and False for USD stage. Defaults to False.

Returns:

The created USD prim.

Raises:

ValueError – If there is already a prim at the prim_path

isaaclab.sim.utils.legacy.get_prim_type_name(prim_path: str | Usd.Prim, fabric: bool = False) → str[source]#

Get the type name of the USD Prim at the provided path.

Deprecated since version 2.3.0: This function is deprecated. Please use the USD APIs directly instead.

>>> import isaaclab.sim as sim_utils
>>>
>>> stage = sim_utils.get_current_stage()
>>> prim = stage.GetPrimAtPath("/World/Cube")
>>> prim.GetTypeName()
"Cube"
Parameters:

  • prim_path – path of the prim in the stage or the prim itself

  • fabric – True for fabric stage and False for USD stage. Defaults to False.

Returns:

The type name of the USD Prim at the provided path.

Raises:

ValueError – If there is not a valid prim at the provided path

isaaclab.sim.utils.legacy.get_next_free_path(path: str) → str[source]#

Gets a new prim path that doesn’t exist in the stage given a base path.

Deprecated since version 2.3.0: This function is deprecated. Please use the isaaclab.sim.utils.queries.get_next_free_prim_path() function instead.

Parameters:

  • path – The base prim path to check.

  • stage – The stage to check. Defaults to the current stage.

Returns:

A new path that is guaranteed to not exist on the current stage