[isaacsim.core.experimental.utils] Isaac Sim Core (Utils)#

Version: 0.1.1

The Core Utils extension provides a set of utility functions.

Enable Extension#

The extension can be enabled (if not already) in one of the following ways:

Command-line interface

Define the next entry as an application argument from a terminal.

APP_SCRIPT.(sh|bat) --enable isaacsim.core.experimental.utils

Experience/extension configuration

Define the next entry under [dependencies] in an experience (.kit) file or an extension configuration (extension.toml) file.

[dependencies]
"isaacsim.core.experimental.utils" = {}

Extension Manager UI

Open the Window > Extensions menu in a running application instance and search for isaacsim.core.experimental.utils. Then, toggle the enable control button if it is not already active.

API#

Warning

The API featured in this extension is experimental and subject to change without deprecation cycles. Although we will try to maintain backward compatibility in the event of a change, it may not always be possible.

Python API#

Backend Utils#

get_current_backend( supported_backends: list[str], *, raise_on_unsupported: bool | None = None, ) → str#

Get the current backend value if it exists.

Parameters:

supported_backends – The list of supported backends.
raise_on_unsupported – Whether to raise an error if the backend is not supported when requested. If set to a value other than None, this parameter has precedence over the context value.

Returns:

The current backend value or the default value (first supported backend) if no backend is active.

is_backend_set() → bool#

Check if a backend is set in the context.

Returns:: Whether a backend is set in the context.

should_raise_on_fallback() → bool#

Check whether an exception should be raised, depending on the context’s raise on fallback state.

Returns:: Whether an exception should be raised on fallback backend.

should_raise_on_unsupported() → bool#

Check whether an exception should be raised, depending on the context’s raise on unsupported state.

Returns:: Whether an exception should be raised on unsupported backend.

use_backend( backend: Literal['usd', 'usdrt', 'fabric', 'tensor'], *, raise_on_unsupported: bool = False, raise_on_fallback: bool = False, ) → Generator[None, None, None]#

Context manager that sets a thread-local backend value.

Warning

The usdrt and fabric backends require Fabric Scene Delegate (FSD) to be enabled. FSD can be enabled in apps/.kit experience files by setting app.useFabricSceneDelegate = true.

Parameters:

backend – The value to set in the context.
raise_on_unsupported – Whether to raise an exception if the backend is not supported when requested.
raise_on_fallback – Whether to raise an exception if the backend is supported, but a fallback is being used at a particular point in time when requested.

Raises:

RuntimeError – If the usdrt or fabric backend is specified but Fabric Scene Delegate (FSD) is disabled.

Example:

>>> import isaacsim.core.experimental.utils.backend as backend_utils
>>>
>>> with backend_utils.use_backend("usdrt"):
...    # operate on the specified backend
...    pass
>>> # operate on the default backend

Ops Utils#

Broadcast a list, a NumPy array, or a Warp array to a Warp array with a new shape.

Note

Broadcasting follows NumPy’s rules: Two shapes are compatible if by comparing their dimensions element-wise, starting with the trailing dimension (i.e., rightmost) and moving leftward

they are equal, or
one of them is 1.

Parameters:

x – List, NumPy array, or Warp array.
shape – Shape of the desired array.
dtype – Data type of the output array. If None, the data type of the input is used.
device – Device to place the output array on. If None, the default device is used, unless the input is a Warp array (in which case the input device is used).

Returns:

Warp array with the given shape.

Raises:

ValueError – If the input list or array is not compatible with the new shape according to the broadcasting rules.

Example:

>>> import isaacsim.core.experimental.utils.ops as ops_utils
>>> import numpy as np
>>> import warp as wp
>>>
>>> # list
>>> array = ops_utils.broadcast_to([1, 2, 3], shape=(1, 3))  
>>> print(array)
[[1 2 3]]
>>>
>>> # NumPy array (with shape (1, 3))
>>> array = ops_utils.broadcast_to(np.array([[1, 2, 3]]), shape=(2, 3))  
>>> print(array)
[[1 2 3]
 [1 2 3]]
>>>
>>> # Warp array (with different device)
>>> array = ops_utils.broadcast_to(wp.array([1, 2, 3], device="cpu"), shape=(3, 3), device="cuda")  
>>> print(array)
[[1 2 3]
 [1 2 3]
 [1 2 3]]

Create a Warp array from a list, a NumPy array, or a Warp array.

Parameters:

x – List, NumPy array, or Warp array. If the input is a Warp array with the same device and dtype, it is returned as is.
dtype – Data type of the output array. If not provided, the data type of the input is used.
device – Device to place the output array on. If None, the default device is used, unless the input is a Warp array (in which case the input device is used).

Returns:

Warp array instance.

Raises:

TypeError – If the input argument x is not a supported data container.

Example:

>>> import isaacsim.core.experimental.utils.ops as ops_utils
>>> import numpy as np
>>> import warp as wp
>>>
>>> # list
>>> array = ops_utils.place([1, 2, 3], device="cpu")  
>>> print(array, array.dtype, array.device, array.shape)
[1 2 3] <class 'warp.types.int64'> cpu (3,)
>>>
>>> # NumPy array (with shape (3, 1))
>>> array = ops_utils.place(np.array([[1], [2], [3]], dtype=np.uint8), dtype=wp.float32)  
>>> print(array, array.dtype, array.device, array.shape)
[[1.] [2.] [3.]] <class 'warp.types.float32'> cuda:0 (3, 1)
>>>
>>> # Warp array (with different device)
>>> array = ops_utils.place(wp.array([1, 2, 3], device="cpu"), device="cuda")  
>>> print(array, array.dtype, array.device, array.shape)
[1 2 3] <class 'warp.types.int64'> cuda:0 (3,)

Create a flattened (1D) Warp array to be used as indices from a list, a NumPy array, or a Warp array.

Parameters:

x – List, NumPy array, or Warp array.
count – Number of indices to resolve. If input argument x is None, the indices are generated from 0 to count - 1. If the input is not None, this value is ignored.
dtype – Data type of the output array. If None, wp.int32 is used.
device – Device to place the output array on. If None, the default device is used, unless the input is a Warp array (in which case the input device is used).

Returns:

Flattened (1D) Warp array instance.

Raises:

ValueError – If input argument x is None and count is not provided.

Example:

>>> import isaacsim.core.experimental.utils.ops as ops_utils
>>> import numpy as np
>>> import warp as wp
>>>
>>> # list
>>> indices = ops_utils.resolve_indices([1, 2, 3], device="cpu")  
>>> print(indices, indices.dtype, indices.device, indices.shape)
[1 2 3] <class 'warp.types.int32'> cpu (3,)
>>>
>>> # NumPy array (with shape (3, 1))
>>> indices = ops_utils.resolve_indices(np.array([[1], [2], [3]], dtype=np.uint8))  
>>> print(indices, indices.dtype, indices.device, indices.shape)
[1 2 3] <class 'warp.types.int32'> cuda:0 (3,)
>>>
>>> # Warp array (with different device)
>>> indices = ops_utils.resolve_indices(wp.array([1, 2, 3], device="cpu"), device="cuda")  
>>> print(indices, indices.dtype, indices.device, indices.shape)
[1 2 3] <class 'warp.types.int32'> cuda:0 (3,)

Prim Utils#

get_all_matching_child_prims( prim: str | Usd.Prim | usdrt.Usd.Prim, *, predicate: Callable[[str], bool], include_self: bool = False, max_depth: int | None = None, ) → list[Usd.Prim | usdrt.Usd.Prim]#

Get all prim children of the given prim (excluding itself by default) that pass the predicate.

Backends: usd, usdrt, fabric.

Parameters:

prim – Prim path or prim instance.
predicate – Function to test the prims against.
include_self – Whether to include the given prim in the search.
max_depth – Maximum depth to search (current prim is at depth 0). If None, search till the end of the tree.

Returns:

List of matching prim children.

Raises:

ValueError – If max_depth is defined and is less than 0.

Example:

>>> import isaacsim.core.experimental.utils.prim as prim_utils
>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>>
>>> # define some prims
>>> stage_utils.define_prim("/World/Cube_0", "Cube")  
>>> stage_utils.define_prim("/World/Cube_0/Cube_1", "Cube")  
>>>
>>> # get all `/World`'s child prims of type Cube
>>> predicate = lambda path: prim_utils.get_prim_at_path(path).GetTypeName() == "Cube"
>>> prim_utils.get_all_matching_child_prims("/World", predicate=predicate)
[Usd.Prim(</World/Cube_0>), Usd.Prim(</World/Cube_0/Cube_1>)]
>>>
>>> # get all `/World`'s child prims of type Cube with max depth 1
>>> prim_utils.get_all_matching_child_prims("/World", predicate=predicate, max_depth=1)
[Usd.Prim(</World/Cube_0>)]

get_first_matching_child_prim( prim: str | Usd.Prim | usdrt.Usd.Prim, *, predicate: Callable[[str], bool], include_self: bool = False, ) → Usd.Prim | usdrt.Usd.Prim | None#

Get the first prim child of the given prim (excluding itself by default) that passes the predicate.

Backends: usd, usdrt, fabric.

Parameters:

prim – Prim path or prim instance.
predicate – Function to test the prims against.
include_self – Whether to include the given prim in the search.

Returns:

First prim child or None if no prim child passes the predicate.

Example:

>>> import isaacsim.core.experimental.utils.prim as prim_utils
>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>>
>>> # define some prims
>>> stage_utils.define_prim("/World/Cube", "Cube")  
>>> stage_utils.define_prim("/World/Cylinder", "Cylinder")  
>>> stage_utils.define_prim("/World/Sphere", "Sphere")  
>>>
>>> # get the first `/World`'s child prim of type Sphere
>>> predicate = lambda path: prim_utils.get_prim_at_path(path).GetTypeName() == "Sphere"
>>> prim_utils.get_first_matching_child_prim("/World", predicate=predicate)
Usd.Prim(</World/Sphere>)

get_first_matching_parent_prim( prim: str | Usd.Prim | usdrt.Usd.Prim, *, predicate: Callable[[str], bool], include_self: bool = False, ) → Usd.Prim | usdrt.Usd.Prim | None#

Get the first prim parent of the given prim (excluding itself by default) that passes the predicate.

Backends: usd, usdrt, fabric.

Warning

The root prim (/) is not considered a valid parent prim but a pseudo-root prim. Therefore, it is not taken into account by this function, and any match for this prim will return None.

Parameters:

prim – Prim path or prim instance.
predicate – Function to test the prims against.
include_self – Whether to include the given prim in the search.

Returns:

First prim parent or None if no prim parent passes the predicate.

Example:

get_prim_at_path(path: str) → Usd.Prim | usdrt.Usd.Prim#

Get the prim at a given path.

Backends: usd, usdrt, fabric.

Parameters:: path – Prim path.
Returns:: Prim.

Example:

>>> import isaacsim.core.experimental.utils.prim as prim_utils
>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>>
>>> stage_utils.define_prim(f"/World/Cube", "Cube")  
>>>
>>> prim_utils.get_prim_at_path("/World/Cube")
Usd.Prim(</World/Cube>)

get_prim_path(prim: Usd.Prim | usdrt.Usd.Prim) → str#

Get the path of a given prim.

Backends: usd, usdrt, fabric.

Parameters:: prim – Prim instance.
Returns:: Prim path.

Example:

>>> import isaacsim.core.experimental.utils.prim as prim_utils
>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>>
>>> prim = stage_utils.define_prim(f"/World/Cube", "Cube")
>>> prim_utils.get_prim_path(prim)
'/World/Cube'

get_prim_variant_collection( prim: str | Usd.Prim, ) → dict[str, list[str]]#

Get variant collection (all variant sets and selections) for a USD prim.

Backends: usd.

Parameters:: prim – Prim path or prim instance.
Returns:: Variant collection (variant sets and selections).

Example:

>>> import isaacsim.core.experimental.utils.prim as prim_utils
>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>> from isaacsim.storage.native import get_assets_root_path
>>>
>>> stage_utils.open_stage(
...     get_assets_root_path() + "/Isaac/Robots/FrankaRobotics/FrankaPanda/franka.usd"
... )  
>>>
>>> prim_utils.get_prim_variant_collection("/panda")
{'Mesh': ['Performance', 'Quality'], 'Gripper': ['AlternateFinger', 'Default']}

get_prim_variants(prim: str | Usd.Prim) → list[tuple[str, str]]#

Get variants (variant sets and selections) authored on a USD prim.

Backends: usd.

Parameters:: prim – Prim path or prim instance.
Returns:: Authored variants (variant sets and selections).

Example:

>>> import isaacsim.core.experimental.utils.prim as prim_utils
>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>> from isaacsim.storage.native import get_assets_root_path
>>>
>>> stage_utils.open_stage(
...     get_assets_root_path() + "/Isaac/Robots/FrankaRobotics/FrankaPanda/franka.usd"
... )  
>>>
>>> prim_utils.get_prim_variants("/panda")
[('Gripper', 'Default'), ('Mesh', 'Performance')]

set_prim_variants( prim: str | Usd.Prim, *, variants: list[tuple[str, str]], ) → None#

Set/author variants (variant sets and selections) on a USD prim.

Backends: usd.

Parameters:

prim – Prim path or prim instance.
variants – Variants (variant sets and selections) to author on the USD prim.

Raises:

ValueError – If a variant set or selection is invalid.

Example:

>>> import isaacsim.core.experimental.utils.prim as prim_utils
>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>> from isaacsim.storage.native import get_assets_root_path
>>>
>>> stage_utils.open_stage(
...     get_assets_root_path() + "/Isaac/Robots/FrankaRobotics/FrankaPanda/franka.usd"
... )  
>>>
>>> prim_utils.set_prim_variants("/panda", variants=[("Mesh", "Quality"), ("Gripper", "AlternateFinger")])

Stage Utils#

add_reference_to_stage( usd_path: str, path: str, *, prim_type: str = 'Xform', variants: list[tuple[str, str]] = [], ) → pxr.Usd.Prim#

Add a USD file reference to the stage at the specified prim path.

Backends: usd.

Note

This function handles stage units verification to ensure compatibility.

Parameters:

usd_path – USD file path to reference.
path – Prim path where the reference will be attached.
prim_type – Prim type to create if the given path doesn’t exist.
variants – Variants (variant sets and selections) to author on the USD prim.

Returns:

USD prim.

Raises:

Exception – The USD file might not exist or might not be a valid USD file.
ValueError – If a variant set or selection is invalid.

Example:

>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>> from isaacsim.storage.native import get_assets_root_path
>>>
>>> prim = stage_utils.add_reference_to_stage(
...     usd_path=get_assets_root_path() + "/Isaac/Robots/FrankaRobotics/FrankaPanda/franka.usd",
...     path="/panda",
...     variants=[("Gripper", "AlternateFinger"), ("Mesh", "Performance")],
... )

create_new_stage(*, template: str | None = None) → pxr.Usd.Stage#

Create a new USD stage attached to the USD context.

Backends: usd.

Note

At least the following templates should be available. Other templates might be available depending on app customizations.

Template	Description
`"default stage"`	Stage with a gray gridded plane, dome and distant lights, and the `/World` Xform prim.
`"empty"`	Empty stage with the `/World` Xform prim.
`"sunlight"`	Stage with a distant light and the `/World` Xform prim.

Parameters:: template – The template to use to create the stage. If None, a new stage is created with nothing.
Returns:: New USD stage instance.
Raises:: ValueError – When the template is not found.

Example:

>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>>
>>> # create a new stage from the 'sunlight' template
>>> stage_utils.create_new_stage(template="sunlight")
Usd.Stage.Open(rootLayer=Sdf.Find('anon:...usd'), ...)

async create_new_stage_async( *, template: str | None = None, ) → pxr.Usd.Stage#

Create a new USD stage attached to the USD context.

Backends: usd.

This function is the asynchronous version of create_new_stage().

Parameters:: template – The template to use to create the stage. If None, a new stage is created with nothing.
Returns:: New USD stage instance.
Raises:: ValueError – When the template is not found.

define_prim( path: str, type_name: str = 'Xform', ) → Usd.Prim | usdrt.Usd.Prim#

Attempt to define a prim of the specified type at the given path.

Backends: usd, usdrt, fabric.

Common token values for type_name are:

"Camera", "Mesh", "PhysicsScene", "Xform"
Shapes ("Capsule", "Cone", "Cube", "Cylinder", "Plane", "Sphere")
Lights ("CylinderLight", "DiskLight", "DistantLight", "DomeLight", "RectLight", "SphereLight")

Parameters:

path – Absolute prim path.
type_name – Token identifying the prim type.

Raises:

ValueError – If the path is not a valid or absolute path string.
RuntimeError – If there is already a prim at the given path with a different type.

Returns:

Defined prim.

Example:

>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>>
>>> stage_utils.define_prim("/World/Sphere", type_name="Sphere")
Usd.Prim(</World/Sphere>)

get_current_stage( *, backend: str | None = None, ) → Usd.Stage | usdrt.Usd.Stage#

Get the stage set in the context manager or the default stage attached to the USD context.

Backends: usd, usdrt, fabric.

Parameters:

backend – Backend to use to get the stage. If not None, it has precedence over the current backend set via the use_backend() context manager.

Returns:

The current stage instance or the default stage attached to the USD context if no stage is set.

Raises:

ValueError – If the backend is not supported.
ValueError – If there is no stage (set via context manager or attached to the USD context).

Example:

>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>>
>>> stage_utils.get_current_stage()
Usd.Stage.Open(rootLayer=Sdf.Find('anon:...usd'), ...)

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

Get the stage ID of a USD stage.

Backends: usd.

Parameters:: stage – The stage to get the ID of.
Returns:: The stage ID.

Example:

>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>>
>>> stage = stage_utils.get_current_stage()
>>> stage_utils.get_stage_id(stage)  
9223006

is_stage_set() → bool#

Check if a stage is set in the context manager.

Returns:: Whether a stage is set in the context manager.

open_stage(usd_path: str) → tuple[bool, Usd.Stage | None]#

Open a USD file attached to the USD context.

Backends: usd.

Parameters:: usd_path – USD file path to open.
Returns:: Two-elements tuple. 1) Whether the USD file was opened successfully. 2) Opened USD stage instance or None if the USD file was not opened.
Raises:: ValueError – If the USD file does not exist or is not a valid (shallow check).

Example:

>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>> from isaacsim.storage.native import get_assets_root_path
>>>
>>> # open a USD file
>>> result, stage = stage_utils.open_stage(
...     get_assets_root_path() + "/Isaac/Robots/FrankaRobotics/FrankaPanda/franka.usd"
... )
>>> result
True
>>> stage
Usd.Stage.Open(rootLayer=Sdf.Find('...'), ...)

async open_stage_async(usd_path: str) → tuple[bool, Usd.Stage | None]#

Open a USD file attached to the USD context.

Backends: usd.

This function is the asynchronous version of open_stage().

Parameters:: usd_path – USD file path to open.
Returns:: Two-elements tuple. 1) Whether the USD file was opened successfully. 2) Opened USD stage instance or None if the USD file was not opened.
Raises:: ValueError – If the USD file does not exist or is not a valid (shallow check).

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

Context manager that sets a thread-local stage instance.

Parameters:: stage – The stage to set in the context.
Raises:: AssertionError – If the stage is not a USD stage instance.

Example:

>>> from pxr import Usd
>>> import isaacsim.core.experimental.utils.stage as stage_utils
>>>
>>> stage_in_memory = Usd.Stage.CreateInMemory()
>>> with stage_utils.use_stage(stage_in_memory):
...    # operate on the specified stage
...    pass
>>> # operate on the default stage attached to the USD context