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.

transforms

Utilities for working with USD transform (xform) operations.

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.

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: Any | None = None, translation: Any | None = None, orientation: Any | None = None, scale: Any | 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. The transform can be specified either in world space (using position) or local space (using translation).

The function determines the coordinate system of the transform based on the provided arguments.

  • If position is provided, it is assumed the orientation is provided in the world frame as well.

  • If translation is provided, it is assumed the orientation is provided in the local frame as well.

The scale is always applied in the local frame.

The function handles various sequence types (list, tuple, numpy array, torch tensor) and converts them to properly-typed tuples for operations on the prim.

Note

Transform operations are standardized to the USD convention: translate, orient (quaternion), and scale, in that order. See standardize_xform_ops() for more details.

Parameters:

  • prim_path – The path of the new prim.

  • prim_type – Prim type name. Defaults to “Xform”, in which case a simple Xform prim is created.

  • position – Prim position in world space as (x, y, z). If the prim has a parent, this is automatically converted to local space relative to the parent. Cannot be used with translation. Defaults to None, in which case no position is applied.

  • translation – Prim translation in local space as (x, y, z). This is applied directly without any coordinate transformation. Cannot be used with position. Defaults to None, in which case no translation is applied.

  • orientation – Prim rotation as a quaternion (w, x, y, z). When used with position, the orientation is also converted from world space to local space. When used with translation, it is applied directly as local orientation. Defaults to None.

  • scale – Scaling factor in x, y, z. Applied in local space. Defaults to None, in which case a uniform scale of 1.0 is applied.

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

  • semantic_label – Semantic label to apply to the prim. Defaults to None, in which case no label is added.

  • semantic_type – Semantic type for the label. Defaults to “class”.

  • attributes – Key-value pairs of prim attributes to set. Defaults to None, in which case no attributes are 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.

  • ValueError – If both position and translation are provided.

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> # Create a cube at world position (1.0, 0.5, 0.0)
>>> sim_utils.create_prim(
...     prim_path="/World/Parent/Cube",
...     prim_type="Cube",
...     position=(1.0, 0.5, 0.0),
...     attributes={"size": 2.0}
... )
Usd.Prim(</World/Parent/Cube>)
>>>
>>> # Create a sphere with local translation relative to its parent
>>> sim_utils.create_prim(
...     prim_path="/World/Parent/Sphere",
...     prim_type="Sphere",
...     translation=(0.5, 0.0, 0.0),
...     scale=(2.0, 2.0, 2.0)
... )
Usd.Prim(</World/Parent/Sphere>)
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.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.

Raises:

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

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.

Transforms#

Utilities for working with USD transform (xform) operations.

This module provides utilities for manipulating USD transform operations (xform ops) on prims. Transform operations in USD define how geometry is positioned, oriented, and scaled in 3D space.

The utilities in this module help standardize transform stacks, clear operations, and manipulate transforms in a consistent way across different USD assets.

Functions:

standardize_xform_ops(prim[, translation, ...])

Standardize the transform operation stack on a USD prim to a canonical form.

validate_standard_xform_ops(prim)

Validate if the transform operations on a prim are standardized.

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.

convert_world_pose_to_local(position, ...)

Convert a world-space pose to local-space pose relative to a reference prim.
isaaclab.sim.utils.transforms.standardize_xform_ops(prim: pxr.Usd.Prim, translation: tuple[float, ...] | None = None, orientation: tuple[float, ...] | None = None, scale: tuple[float, ...] | None = None) → bool[source]#

Standardize the transform operation stack on a USD prim to a canonical form.

This function converts a prim’s transform stack to use the standard USD transform operation order: [translate, orient, scale]. The function performs the following operations:

  1. Validates that the prim is Xformable

  2. Captures the current local transform (translation, rotation, scale)

  3. Resolves and bakes unit scale conversions (xformOp:scale:unitsResolve)

  4. Creates or reuses standard transform operations (translate, orient, scale)

  5. Sets the transform operation order to [translate, orient, scale]

  6. Applies the preserved or user-specified transform values

The entire modification is performed within an Sdf.ChangeBlock for optimal performance when processing multiple prims.

Note

Standard Transform Order: The function enforces the USD best practice order: xformOp:translate, xformOp:orient, xformOp:scale. This order is compatible with most USD tools and workflows, and uses quaternions for rotation (avoiding gimbal lock issues).

Note

Pose Preservation: By default, the function preserves the prim’s local transform (relative to its parent). The world-space position of the prim remains unchanged unless explicit translation, orientation, or scale values are provided.

Warning

Animation Data Loss: This function only preserves transform values at the default time code (Usd.TimeCode.Default()). Any animation or time-sampled transform data will be lost. Use this function during asset import or preparation, not on animated prims.

Warning

Unit Scale Resolution: If the prim has a xformOp:scale:unitsResolve attribute (common in imported assets with unit mismatches), it will be baked into the scale and removed. For example, a scale of (1, 1, 1) with unitsResolve of (100, 100, 100) becomes a final scale of (100, 100, 100).

Parameters:

  • prim – The USD prim to standardize. Must be a valid prim that supports the UsdGeom.Xformable schema (e.g., Xform, Mesh, Cube, etc.). Material and Shader prims are not Xformable and will return False.

  • translation – Optional translation vector (x, y, z) in local space. If provided, overrides the prim’s current translation. If None, preserves the current local translation. Defaults to None.

  • orientation – Optional orientation quaternion (w, x, y, z) in local space. If provided, overrides the prim’s current orientation. If None, preserves the current local orientation. Defaults to None.

  • scale – Optional scale vector (x, y, z). If provided, overrides the prim’s current scale. If None, preserves the current scale (after unit resolution) or uses (1, 1, 1) if no scale exists. Defaults to None.

Returns:

True if the transform operations were successfully standardized. False if the

prim is not Xformable (e.g., Material, Shader prims). The function will log an error message when returning False.

Return type:

bool

Raises:

ValueError – If the prim is not valid (i.e., does not exist or is an invalid prim).

Example

>>> import isaaclab.sim as sim_utils
>>>
>>> # Standardize a prim with non-standard transform operations
>>> prim = stage.GetPrimAtPath("/World/ImportedAsset")
>>> result = sim_utils.standardize_xform_ops(prim)
>>> if result:
...     print("Transform stack standardized successfully")
>>> # The prim now uses: [translate, orient, scale] in that order
>>>
>>> # Standardize and set new transform values
>>> sim_utils.standardize_xform_ops(
...     prim,
...     translation=(1.0, 2.0, 3.0),
...     orientation=(1.0, 0.0, 0.0, 0.0),  # identity rotation (w, x, y, z)
...     scale=(2.0, 2.0, 2.0)
... )
>>>
>>> # Batch processing for performance
>>> prims_to_standardize = [stage.GetPrimAtPath(p) for p in prim_paths]
>>> for prim in prims_to_standardize:
...     sim_utils.standardize_xform_ops(prim)  # Each call uses Sdf.ChangeBlock
isaaclab.sim.utils.transforms.validate_standard_xform_ops(prim: pxr.Usd.Prim) → bool[source]#

Validate if the transform operations on a prim are standardized.

This function checks if the transform operations on a prim are standardized to the canonical form: [translate, orient, scale].

Parameters:

prim – The USD prim to validate.

isaaclab.sim.utils.transforms.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.

Example

>>> import isaaclab.sim as sim_utils
>>> from pxr import Usd, UsdGeom
>>>
>>> # Get prim
>>> stage = sim_utils.get_current_stage()
>>> prim = stage.GetPrimAtPath("/World/ImportedAsset")
>>>
>>> # Resolve pose
>>> pos, quat = sim_utils.resolve_prim_pose(prim)
>>> print(f"Position: {pos}")
>>> print(f"Orientation: {quat}")
>>>
>>> # Resolve pose with respect to another prim
>>> ref_prim = stage.GetPrimAtPath("/World/Reference")
>>> pos, quat = sim_utils.resolve_prim_pose(prim, ref_prim)
>>> print(f"Position: {pos}")
>>> print(f"Orientation: {quat}")
isaaclab.sim.utils.transforms.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.

Example

>>> import isaaclab.sim as sim_utils
>>> from pxr import Usd, UsdGeom
>>>
>>> # Get prim
>>> stage = sim_utils.get_current_stage()
>>> prim = stage.GetPrimAtPath("/World/ImportedAsset")
>>>
>>> # Resolve scale
>>> scale = sim_utils.resolve_prim_scale(prim)
>>> print(f"Scale: {scale}")
isaaclab.sim.utils.transforms.convert_world_pose_to_local(position: tuple[float, ...], orientation: tuple[float, ...] | None, ref_prim: pxr.Usd.Prim) → tuple[tuple[float, float, float], tuple[float, float, float, float] | None][source]#

Convert a world-space pose to local-space pose relative to a reference prim.

This function takes a position and orientation in world space and converts them to local space relative to the given reference prim. This is useful when creating or positioning prims where you know the desired world position but need to set local transform attributes relative to another prim.

The conversion uses the standard USD transformation math: local_transform = world_transform * inverse(ref_world_transform)

Note

If the reference prim is the root prim (“/”), the position and orientation are returned unchanged, as they are already effectively in local/world space.

Parameters:

  • position – The world-space position as (x, y, z).

  • orientation – The world-space orientation as quaternion (w, x, y, z). If None, only position is converted and None is returned for orientation.

  • ref_prim – The reference USD prim to compute the local transform relative to. If this is the root prim (“/”), the world pose is returned unchanged.

Returns:

  • local_translation is a tuple of (x, y, z) in local space relative to ref_prim

  • local_orientation is a tuple of (w, x, y, z) in local space relative to ref_prim, or None if no orientation was provided

Return type:

A tuple of (local_translation, local_orientation) where

Raises:

ValueError – If the reference prim is not a valid USD prim.

Example

>>> import isaaclab.sim as sim_utils
>>> from pxr import Usd, UsdGeom
>>>
>>> # Get reference prim
>>> stage = sim_utils.get_current_stage()
>>> ref_prim = stage.GetPrimAtPath("/World/Reference")
>>>
>>> # Convert world pose to local (relative to ref_prim)
>>> world_pos = (10.0, 5.0, 0.0)
>>> world_quat = (1.0, 0.0, 0.0, 0.0)  # identity rotation
>>> local_pos, local_quat = sim_utils.convert_world_pose_to_local(
...     world_pos, world_quat, ref_prim
... )
>>> print(f"Local position: {local_pos}")
>>> print(f"Local orientation: {local_quat}")

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