[isaacsim.core.utils] Isaac Sim Utilities#

Warning

Deprecation: Extension deprecated since Isaac Sim 6.0.0 in favor of the Core Experimental extension: isaacsim.core.experimental.utils

Version: 4.1.9

Overview#

Deprecated since version 6.0.0: This extension is deprecated in favor of isaacsim.core.experimental.utils.

The isaacsim.core.utils extension provides shared utility functions used across Isaac Sim workflows. It collects helpers for common USD, stage, prim, physics, math, transform, rotation, mesh, bounds, semantics, rendering, and carb tasks so that extension authors and tools can rely on consistent behavior across the simulation stack.

The extension is a utility layer rather than a standalone tool or UI. Its modules are typically imported directly, for example from isaacsim.core.utils.stage import add_reference_to_stage.

Key Components#

Utility submodules#

Utilities are grouped by domain and accessed as isaacsim.core.utils.<name>:

USD and stage: stage, prims, semantics, xforms, fabric, render_product
Math and transforms: math, rotations, transformations, distance_metrics, and backend-specific helpers under numpy, torch, and warp
Physics and geometry: physics, articulations, bounds, collisions, mesh, deformable_mesh_utils
Application and data helpers: carb, extensions, string, constants, types, viewports, camera_utils, interops, random

from isaacsim.core.utils.stage import add_reference_to_stage, get_current_stage
from isaacsim.core.utils.prims import get_prim_at_path

add_reference_to_stage(usd_path="/path/to/asset.usd", prim_path="/World/Asset")
stage = get_current_stage()
prim = get_prim_at_path("/World/Asset")

Commands#

The commands submodule registers omni.kit commands for common prim operations, including IsaacSimSpawnPrim, IsaacSimTeleportPrim, IsaacSimScalePrim, and IsaacSimDestroyPrim.

C++ interface#

The extension includes a Carbonite plugin and pybind11 bindings exposed as isaacsim.core.utils.bindings._isaac_utils. The bindings provide a math submodule with vector and quaternion operations (such as dot, cross, normalize, lerp, and slerp) and a transforms submodule (set_transform, set_scale), and back the prim-path matching helper used by the Python utilities.

Relationships#

isaacsim.core.utils is a shared utility dependency for simulation-oriented extensions. It declares dependencies on USD and physics systems, including PhysX, USD physics schemas, semantic schema support, and USD metrics assembly, which align with the USD and physics utilities it provides.

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.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.utils" = {}

Extension Manager UI

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

Commands#

Public command API for module isaacsim.core.utils:

IsaacSimDestroyPrim
IsaacSimScalePrim
IsaacSimSpawnPrim
IsaacSimTeleportPrim

IsaacSimDestroyPrim#

Command to delete a prim. This variant has less overhead than other commands as it doesn’t store an undo operation.

Typical usage example:

.. code-block:: python

omni.kit.commands.execute( “IsaacSimDestroyPrim”, prim_path=”/World/Prim”, )

Arguments#

prim_path: Path to the prim to delete.

Usage#

import omni.kit.commands
import omni.usd
from pxr import UsdGeom

# Get the current USD stage
stage = omni.usd.get_context().get_stage()

# Create a prim to delete
prim_path = "/World/PrimToDelete"
UsdGeom.Xform.Define(stage, prim_path)

# Delete the prim using the IsaacSimDestroyPrim command
omni.kit.commands.execute(
    "IsaacSimDestroyPrim",
    prim_path=prim_path,
)

IsaacSimScalePrim#

Command to set a scale of a prim.

Typical usage example:

.. code-block:: python

omni.kit.commands.execute( “IsaacSimScalePrim”, prim_path=”/World/Prim”, scale=(1.5, 1.5, 1.5), )

Arguments#

prim_path: Path to the prim to scale.
scale: Scale values for x, y, and z axes.

Usage#

import omni.kit.commands

# Scale an existing prim at this path.
prim_path = "/World/Prim"

# Set the prim scale along the X, Y, and Z axes.
scale = (1.5, 1.5, 1.5)

omni.kit.commands.execute(
    "IsaacSimScalePrim",
    prim_path=prim_path,
    scale=scale,
)

IsaacSimSpawnPrim#

Command to spawn a new prim in the stage and set its transform. This uses dynamic_control to properly handle physics objects and articulation.

Typical usage example:

.. code-block:: python

omni.kit.commands.execute( “IsaacSimSpawnPrim”, usd_path=”/path/to/file.usd”, prim_path=”/World/Prim”, translation=(0, 0, 0), rotation=(0, 0, 0, 1), )

Arguments#

usd_path: Path to the USD file to reference.
prim_path: Path where the prim will be created in the stage.
translation: Translation vector for the prim’s position.
rotation: Rotation quaternion for the prim’s orientation.

Usage#

import omni.kit.commands

# Path to the USD file to spawn.
# Replace this with a valid local path or Omniverse/Nucleus USD path.
usd_path = "/path/to/asset.usd"

# Spawn the USD asset at /World/SpawnedPrim and set its transform.
omni.kit.commands.execute(
    "IsaacSimSpawnPrim",
    usd_path=usd_path,
    prim_path="/World/SpawnedPrim",
    translation=(0.0, 0.0, 0.5),  # position: (x, y, z)
    rotation=(0.0, 0.0, 0.0, 1.0),  # quaternion: (x, y, z, w)
)

IsaacSimTeleportPrim#

Command to set a transform of a prim. This uses dynamic_control to properly handle physics objects and articulation.

Typical usage example:

.. code-block:: python

omni.kit.commands.execute( “IsaacSimTeleportPrim”, prim_path=”/World/Prim”, translation=(0, 0, 0), rotation=(0, 0, 0, 1), )

Arguments#

prim_path: Path to the prim to teleport.
translation: Translation vector as (x, y, z).
rotation: Rotation quaternion as (x, y, z, w).

Usage#

import omni.kit.commands

# Teleport an existing prim to a new world transform.
# translation is (x, y, z)
# rotation is a quaternion (x, y, z, w)
omni.kit.commands.execute(
    "IsaacSimTeleportPrim",
    prim_path="/World/Prim",
    translation=(1.0, 0.0, 0.5),
    rotation=(0.0, 0.0, 0.0, 1.0),
)

Python API#

Articulation Utils#

Utils for programmatically interacting with Articulations on the Stage.

The utils can be used to:

Modify Articulation Roots.
Determine the base paths of every Articulation on the Stage.

Deprecated articulation utility functions.

add_articulation_root(prim: pxr.Usd.Prim) → None#

Add an Articulation Root to prim.

Parameters:: prim – A prim to which an Articulation Root will be added.

find_all_articulation_base_paths() → list#

Find all base Articulation paths on the stage.

A base path is defined as the maximal path that contains every part of a robot. For example, the articulation root in the UR10 robot may be at “/World/ur10/base_link”, but the path returned by this function would be “/World/ur10”.

An Articulation base path:

Contains exactly one Articulation Root in the subtree of prim paths that stem from a base path.
Is a parent of every link in an Articulation.

On a stage with nested articulation roots, only the inner-most root will be listed.

Returns:: A list of every Articulation base path on the stage.

move_articulation_root( src_prim: pxr.Usd.Prim, dst_prim: pxr.Usd.Prim, ) → None#

Move the Articulation Root from src_prim to dst_prim.

If src_prim is not an Articulation Root, nothing will happen.

Parameters:

src_prim – A prim from which an Articulation Root will be removed.
dst_prim – A prim to which an Articulation Root will be added.

remove_articulation_root(prim: pxr.Usd.Prim) → None#

Remove the Articulation Root from prim if one exists.

Parameters:: prim – A prim whose Articulation Root will be removed.

Bounds Utils#

Utils for computing the Axis-Aligned Bounding Box (AABB) and the Oriented Bounding Box (OBB) of a prim.

The AABB is the smallest cuboid that can completely contain the prim it represents. It is defined by the following 3D coordinates: \((x_{min}, y_{min}, z_{min}, x_{max}, y_{max}, z_{max})\).
Unlike the AABB, which is aligned with the coordinate axes, the OBB can be oriented at any angle in 3D space.

Deprecated bounds computation utilities.

compute_aabb( bbox_cache: pxr.UsdGeom.BBoxCache, prim_path: str, include_children: bool = False, ) → array#

Compute an Axis-Aligned Bounding Box (AABB) for a given prim_path.

A combined AABB is computed if include_children is True.

Parameters:

bbox_cache – Existing bounding box cache to use for computation.
prim_path – Prim path to compute AABB for.
include_children – Whether to include children of the specified prim in the calculation.

Returns:

Bounding box for this prim as [min x, min y, min z, max x, max y, max z].

Raises:

ValueError – If no valid prim exists at prim_path.

Example:

>>> import isaacsim.core.utils.bounds as bounds_utils
>>>
>>> # 1 stage unit length cube centered at (0.0, 0.0, 0.0)
>>> cache = bounds_utils.create_bbox_cache()
>>> bounds_utils.compute_aabb(cache, prim_path="/World/Cube")
[-0.5 -0.5 -0.5  0.5  0.5  0.5]
>>>
>>> # the same cube rotated 45 degrees around the z-axis
>>> cache = bounds_utils.create_bbox_cache()
>>> bounds_utils.compute_aabb(cache, prim_path="/World/Cube")
[-0.70710678  -0.70710678  -0.5  0.70710678  0.70710678  0.5]

compute_combined_aabb( bbox_cache: pxr.UsdGeom.BBoxCache, prim_paths: list[str], ) → array#

Computes a combined Axis-Aligned Bounding Box (AABB) given a list of prim paths.

Parameters:

bbox_cache – Existing bounding box cache to use for computation.
prim_paths – List of prim paths to compute combined AABB for.

Returns:

Bounding box for input prims as [min x, min y, min z, max x, max y, max z].

Raises:

ValueError – If prim_paths is empty.

Example:

>>> import isaacsim.core.utils.bounds as bounds_utils
>>>
>>> # 1 stage unit length cube centered at (0.0, 0.0, 0.0)
>>> # with a 1 stage unit diameter sphere centered at (-0.5, 0.5, 0.5)
>>> cache = bounds_utils.create_bbox_cache()
>>> bounds_utils.compute_combined_aabb(cache, prim_paths=["/World/Cube", "/World/Sphere"])
[-1.  -0.5 -0.5  0.5  1.   1. ]

compute_obb( bbox_cache: pxr.UsdGeom.BBoxCache, prim_path: str, ) → tuple[ndarray, ndarray, ndarray]#

Computes the Oriented Bounding Box (OBB) of a prim.

Note

The OBB does not guarantee the smallest possible bounding box, it rotates and scales the default AABB.
The rotation matrix incorporates any scale factors applied to the object.
The half_extent values do not include these scaling effects.

Parameters:

bbox_cache – USD bounding box cache object to use for computation.
prim_path – Prim path to compute OBB for.

Returns:

A tuple containing the OBB centroid, axes, and half extent.

Example:

>>> import isaacsim.core.utils.bounds as bounds_utils
>>>
>>> # 1 stage unit length cube centered at (0.0, 0.0, 0.0)
>>> cache = bounds_utils.create_bbox_cache()
>>> centroid, axes, half_extent = bounds_utils.compute_obb(cache, prim_path="/World/Cube")
>>> centroid
[0. 0. 0.]
>>> axes
[[1. 0. 0.]
 [0. 1. 0.]
 [0. 0. 1.]]
>>> half_extent
[0.5 0.5 0.5]
>>>
>>> # the same cube rotated 45 degrees around the z-axis
>>> cache = bounds_utils.create_bbox_cache()
>>> centroid, axes, half_extent = bounds_utils.compute_obb(cache, prim_path="/World/Cube")
>>> centroid
[0. 0. 0.]
>>> axes
[[ 0.70710678  0.70710678  0.        ]
 [-0.70710678  0.70710678  0.        ]
 [ 0.          0.          1.        ]]
>>> half_extent
[0.5 0.5 0.5]

compute_obb_corners( bbox_cache: pxr.UsdGeom.BBoxCache, prim_path: str, ) → ndarray#

Computes the corners of the Oriented Bounding Box (OBB) of a prim.

Parameters:

bbox_cache – Bounding box cache object to use for computation.
prim_path – Prim path to compute OBB for.

Returns:

Array of shape (8, 3) containing each corner location of the OBB.

\(c_0 = (x_{min}, y_{min}, z_{min})\)
\(c_1 = (x_{min}, y_{min}, z_{max})\)
\(c_2 = (x_{min}, y_{max}, z_{min})\)
\(c_3 = (x_{min}, y_{max}, z_{max})\)
\(c_4 = (x_{max}, y_{min}, z_{min})\)
\(c_5 = (x_{max}, y_{min}, z_{max})\)
\(c_6 = (x_{max}, y_{max}, z_{min})\)
\(c_7 = (x_{max}, y_{max}, z_{max})\)

Example:

>>> import isaacsim.core.utils.bounds as bounds_utils
>>>
>>> cache = bounds_utils.create_bbox_cache()
>>> bounds_utils.compute_obb_corners(cache, prim_path="/World/Cube")
[[-0.5 -0.5 -0.5]
 [-0.5 -0.5  0.5]
 [-0.5  0.5 -0.5]
 [-0.5  0.5  0.5]
 [ 0.5 -0.5 -0.5]
 [ 0.5 -0.5  0.5]
 [ 0.5  0.5 -0.5]
 [ 0.5  0.5  0.5]]

create_bbox_cache( time: pxr.Usd.TimeCode = pxr.Usd.TimeCode.Default, use_extents_hint: bool = True, ) → pxr.UsdGeom.BBoxCache#

Helper function to create a bounding box cache object that can be used for computations.

Parameters:

time – Time at which the cache should be initialized.
use_extents_hint – Whether to use existing extents attributes on prims to compute bounding boxes.

Returns:

Initialized bounding box cache.

Example:

>>> import isaacsim.core.utils.bounds as bounds_utils
>>>
>>> bounds_utils.create_bbox_cache()
<pxr.UsdGeom.BBoxCache object at 0x7f6720b8bc90>

get_obb_corners( centroid: ndarray, axes: ndarray, half_extent: ndarray, ) → ndarray#

Computes the corners of the Oriented Bounding Box (OBB) from the given OBB information.

Parameters:

centroid – Centroid of the OBB.
axes – Axes of the OBB, where each row represents a different axis.
half_extent – Half extent of the OBB.

Returns:

Array of shape (8, 3) containing each corner location of the OBB.

\(c_0 = (x_{min}, y_{min}, z_{min})\)
\(c_1 = (x_{min}, y_{min}, z_{max})\)
\(c_2 = (x_{min}, y_{max}, z_{min})\)
\(c_3 = (x_{min}, y_{max}, z_{max})\)
\(c_4 = (x_{max}, y_{min}, z_{min})\)
\(c_5 = (x_{max}, y_{min}, z_{max})\)
\(c_6 = (x_{max}, y_{max}, z_{min})\)
\(c_7 = (x_{max}, y_{max}, z_{max})\)

Example:

>>> import isaacsim.core.utils.bounds as bounds_utils
>>>
>>> cache = bounds_utils.create_bbox_cache()
>>> centroid, axes, half_extent = bounds_utils.compute_obb(cache, prim_path="/World/Cube")
>>> bounds_utils.get_obb_corners(centroid, axes, half_extent)
[[-0.5 -0.5 -0.5]
 [-0.5 -0.5  0.5]
 [-0.5  0.5 -0.5]
 [-0.5  0.5  0.5]
 [ 0.5 -0.5 -0.5]
 [ 0.5 -0.5  0.5]
 [ 0.5  0.5 -0.5]
 [ 0.5  0.5  0.5]]

recompute_extents( prim: pxr.UsdGeom.Boundable, time: pxr.Usd.TimeCode = pxr.Usd.TimeCode.Default, include_children: bool = False, ) → None#

Recomputes and overwrites the extents attribute for a UsdGeom.Boundable prim.

Parameters:

prim – Input prim to recompute extents for.
time – Timecode to use for computing extents.
include_children – Whether to include children of the specified prim in the calculation.

Raises:

ValueError – If prim is not of UsdGeom.Boundable type.

Example:

>>> import isaacsim.core.utils.bounds as bounds_utils
>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> prim = stage_utils.get_current_stage().GetPrimAtPath("/World/Cube")
>>> bounds_utils.recompute_extents(prim)

Carb Utils#

Carb settings is a generalized subsystem designed to provide a simple to use interface to Kit’s various subsystems, which can be automated, enumerated, serialized and so on.

The most common types of settings are:

Persistent (saved between sessions): "/persistent/<setting>"
(e.g., "/persistent/physics/numThreads")
Application: "/app/<setting>" (e.g., "/app/viewport/grid/enabled")
Extension: "/exts/<extension>/<setting>" (e.g., "/exts/omni.kit.debug.python/host")

Deprecated Carbonite utility functions.

get_carb_setting( carb_settings: carb.settings.ISettings, setting: str, ) → Any#

Convenience function to get settings.

Parameters:

carb_settings – The interface to carb settings.
setting – Name of setting to read.

Returns:

Value for the setting.

Example:

>>> import carb
>>> import isaacsim.core.utils.carb as carb_utils
>>>
>>> settings = carb.settings.get_settings()
>>> carb_utils.get_carb_setting(settings, "/physics/updateToUsd")
False

set_carb_setting( carb_settings: carb.settings.ISettings, setting: str, value: Any, ) → None#

Convenience function to set carb settings.

Parameters:

carb_settings – The interface to carb settings.
setting – Name of setting to change.
value – New value for the setting.

Raises:

TypeError – If the type of value does not match a supported setting type.

Example:

>>> import carb
>>> import isaacsim.core.utils.carb as carb_utils
>>>
>>> settings = carb.settings.get_settings()
>>> carb_utils.set_carb_setting(settings, "/physics/updateToUsd", True)

Collisions Utils#

Deprecated collision utility functions.

ray_cast( position: array, orientation: array, offset: array, max_dist: float = 100.0, ) → tuple[None | str, float]#

Projects a raycast forward along x axis with specified offset.

If a hit is found within the maximum distance, then the object’s prim path and distance to it is returned. Otherwise, None and 10000 is returned.

Parameters:

position – Origin’s position for ray cast.
orientation – Origin’s orientation for ray cast.
offset – Offset for ray cast.
max_dist – Maximum distance to test for collisions in stage units.

Returns:

Path to geometry that was hit and hit distance, or None and 10000 if no hit occurred.

Commands#

Deprecated simulation command utilities.

class IsaacSimDestroyPrim(*args: Any, **kwargs: Any)#

Bases: Command

Command to delete a prim. This variant has less overhead than other commands because it does not store an undo operation.

Typical usage example:

omni.kit.commands.execute(
    "IsaacSimDestroyPrim",
    prim_path="/World/Prim",
)

Parameters:: prim_path – Path to the prim to delete.

class IsaacSimScalePrim(*args: Any, **kwargs: Any)#

Bases: Command

Command to set the scale of a prim.

Typical usage example:

omni.kit.commands.execute(
    "IsaacSimScalePrim",
    prim_path="/World/Prim",
    scale=(1.5, 1.5, 1.5),
)

Parameters:

prim_path – Path to the prim to scale.
scale – Scale values for x, y, and z axes.

class IsaacSimSpawnPrim(*args: Any, **kwargs: Any)#

Bases: Command

Command to spawn a new prim in the stage and set its transform.

This uses dynamic_control to properly handle physics objects and articulation.

Typical usage example:

omni.kit.commands.execute(
    "IsaacSimSpawnPrim",
    usd_path="/path/to/file.usd",
    prim_path="/World/Prim",
    translation=(0, 0, 0),
    rotation=(0, 0, 0, 1),
)

Parameters:

usd_path – Path to the USD file to reference.
prim_path – Path where the prim will be created in the stage.
translation – Translation vector for the prim’s position.
rotation – Rotation quaternion for the prim’s orientation.

class IsaacSimTeleportPrim(*args: Any, **kwargs: Any)#

Bases: Command

Command to set the transform of a prim. This uses dynamic_control to properly handle physics objects and articulation.

Typical usage example:

omni.kit.commands.execute(
    "IsaacSimTeleportPrim",
    prim_path="/World/Prim",
    translation=(0, 0, 0),
    rotation=(0, 0, 0, 1),
)

Parameters:

prim_path – Path to the prim to teleport.
translation – Translation vector as (x, y, z).
rotation – Rotation quaternion as (x, y, z, w).

get_current_stage( fabric: bool = False, ) → Usd.Stage | usdrt.Usd._Usd.Stage#

Get the current open USD or Fabric stage.

Parameters:: fabric – True to get the Fabric stage. False to get the USD stage.
Returns:: The USD or Fabric stage as specified by the fabric argument.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_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>)

get_current_stage_id() → int#

Get the current open stage id.

Returns:: The stage id.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_utils.get_current_stage_id()
1234567890

Constants Utils#

Deprecated constant definitions.

AXES_INDICES = {'X': 0, 'Y': 1, 'Z': 2, 'x': 0, 'y': 1, 'z': 2}#

Mapping from axis name to axis ID

Example:

>>> import isaacsim.core.utils.constants as constants_utils
>>>
>>> # get the x-axis index
>>> constants_utils.AXES_INDICES['x']
0
>>> constants_utils.AXES_INDICES['X']
0

AXES_TOKEN = {'X': pxr.UsdGeom.Tokens.x, 'Y': pxr.UsdGeom.Tokens.y, 'Z': pxr.UsdGeom.Tokens.z, 'x': pxr.UsdGeom.Tokens.x, 'y': pxr.UsdGeom.Tokens.y, 'z': pxr.UsdGeom.Tokens.z}#

Mapping from axis name to axis USD token

>>> import isaacsim.core.utils.constants as constants_utils
>>>
>>> # get the x-axis USD token
>>> constants_utils.AXES_TOKEN['x']
X
>>> constants_utils.AXES_TOKEN['X']
X

Distance Metrics Utils#

Deprecated distance metric functions.

rotational_distance_angle( r1: np.ndarray | Gf.Matrix3d | Gf.Matrix4d, r2: np.ndarray | Gf.Matrix3d | Gf.Matrix4d, ) → np.ndarray#

Computes the weighted distance between two rotations using inner product.

Note

If r1 and r2 are Gf.Matrix3d() or Gf.Matrix4d() objects, the transformation matrices will be transposed in the distance calculations.

Parameters:

r1 – Rotation matrices or 4x4 transformation matrices.
r2 – Rotation matrices or 4x4 transformation matrices.

Returns:

The magnitude of the angle of rotation from r1 to r2.

Raises:

ValueError – If either rotation input is not 3x3 or 4x4.

rotational_distance_identity_matrix_deviation( r1: np.ndarray | Gf.Matrix4d | Gf.Matrix3d, r2: np.ndarray | Gf.Matrix4d | Gf.Matrix3d, ) → np.ndarray#

Computes the distance between two rotations using deviation from identity matrix.

Note

If r1 and r2 are Gf.Matrix3d() or Gf.Matrix4d() objects, the transformation matrices will be transposed in the distance calculations.

Parameters:

r1 – Rotation matrices or 4x4 transformation matrices.
r2 – Rotation matrices or 4x4 transformation matrices.

Returns:

The Frobenius norm ||I-r1*r2^T||, where I is the identity matrix.

Raises:

ValueError – If either rotation input is not 3x3 or 4x4.

rotational_distance_single_axis( r1: np.ndarray | Gf.Matrix4d | Gf.Matrix3d, r2: np.ndarray | Gf.Matrix4d | Gf.Matrix3d, axis: np.ndarray, ) → np.ndarray#

Computes the distance between two rotations w.r.t. input axis.

Note

If r1 and r2 are Gf.Matrix3d() or Gf.Matrix4d() objects, the transformation matrices will be transposed in the distance calculations.

Usage:: If the robot were holding a cup aligned with its z-axis, it would be important to align the z-axis of the robot with the z-axis of the world frame. This could be accomplished by letting

-r1 be the rotation of the robot end effector

-r2 be any rotation matrix for a rotation about the z axis

-axis = [0,0,1]

Parameters:

r1 – Rotation matrices or 4x4 transformation matrices.
r2 – Rotation matrices or 4x4 transformation matrices.
axis – A 3d vector that will be rotated by r1 and r2.

Returns:

The angle between (r1 @ axis) and (r2 @ axis).

Raises:

ValueError – If either rotation input is not 3x3 or 4x4, if axis does not have length 3, or if axis has zero magnitude.

weighted_translational_distance( t1: np.ndarray | Gf.Matrix4d, t2: np.ndarray | Gf.Matrix4d, weight_matrix: np.ndarray = array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]), ) → np.ndarray#

Computes the weighted distance between two translation vectors.

The distance calculation has the form sqrt(x.T W x), where

- x is the vector difference between t1 and t2.

- W is a weight matrix.

Given the identity weight matrix, this is equivalent to the ||t1-t2||.

Usage:

This formulation can be used to weight an arbitrary axis of the translation difference. Letting x = t1-t2 = a1*b1 + a2*b2 + a3*b3 (where b1,b2,b3 are column basis vectors, and a1,a2,a3 are constants), When W = I: x.T W x = sqrt(a1^2 + a2^2 + a3^2). To weight the b1 axis by 2, let W take the form (R.T @ ([4,1,1]@I) @ R) where:

- I is the identity matrix.

- R is a rotation matrix of the form [b1,b2,b3].T

This is effectively equivalent to ||[2*e1,e2,e3] @ [b1,b2,b3].T @ x|| = sqrt(4*a1^2 + a2^2 + a3^2).

- e1,e2,e3 are the elementary basis vectors.

Parameters:

t1 – 3d translation vectors or 4x4 transformation matrices.
t2 – 3d translation vectors or 4x4 transformation matrices.
weight_matrix – A 3x3 positive semidefinite matrix of weights.

Returns:

The weighted norm of the difference (t1-t2).

Raises:

ValueError – If either translation input is not a 3d vector or 4x4 transformation matrix, or if weight_matrix has an incompatible shape.

Extensions Utils#

Utilities for enabling and disabling extensions from the Extension Manager and knowing their locations

Deprecated extension utility functions.

disable_extension(extension_name: str) → bool#

Unload an extension.

Parameters:: extension_name – Name of the extension.
Returns:: True if the extension could be unloaded, False otherwise.

Example:

>>> import isaacsim.core.utils.extensions as extensions_utils
>>>
>>> extensions_utils.disable_extension("omni.kit.window.stage")
True

enable_extension(extension_name: str) → bool#

Load an extension from the extension manager.

Parameters:: extension_name – Name of the extension.
Returns:: True if the extension could be loaded, False otherwise.

Example:

>>> import isaacsim.core.utils.extensions as extensions_utils
>>>
>>> extensions_utils.enable_extension("omni.kit.window.stage")
True

get_extension_id(extension_name: str) → str#

Get the extension id for a loaded extension.

Parameters:: extension_name – Name of the extension.
Returns:: Full extension id.

Example:

>>> import isaacsim.core.utils.extensions as extensions_utils
>>>
>>> extensions_utils.get_extension_id("omni.kit.window.stage")
omni.kit.window.stage-2.4.3

get_extension_path(ext_id: str) → str#

Get the extension path for a loaded extension by its full id.

Parameters:: ext_id – Full id of the extension.
Returns:: Path to the loaded extension root directory.

Example:

>>> import isaacsim.core.utils.extensions as extensions_utils
>>>
>>> ext_id = extensions_utils.get_extension_id("omni.kit.window.stage")
>>> extensions_utils.get_extension_path(ext_id)
/home/user/.local/share/ov/pkg/isaac_sim-<version>/kit/exts/omni.kit.window.stage

get_extension_path_from_name(extension_name: str) → str#

Get the extension path for a loaded extension by its name.

Parameters:: extension_name – Name of the extension.
Returns:: Path to the loaded extension root directory.
Raises:: RuntimeError – If the extension is not enabled or could not be found.

Example:

>>> import isaacsim.core.utils.extensions as extensions_utils
>>>
>>> extensions_utils.get_extension_path_from_name("omni.kit.window.stage")
/home/user/.local/share/ov/pkg/isaac_sim-<version>/kit/exts/omni.kit.window.stage

Interoperability Utils#

Utilities for interoperability between different (ML) frameworks.
Supported frameworks are:

Deprecated interoperability utility functions.

jax2numpy(array: jax.Array) → numpy.ndarray#

Convert JAX array to NumPy array.

Parameters:: array – JAX array.
Returns:: NumPy array.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import jax
>>> import jax.numpy as jnp
>>>
>>> with jax.default_device(jax.devices("cuda")[0]):
...     jax_array = jnp.zeros((100, 10), dtype=jnp.float32)
...
>>> numpy_array = interops_utils.jax2numpy(jax_array)
>>> type(numpy_array)
<class 'numpy.ndarray'>

jax2tensorflow(array: jax.Array) → tensorflow.Tensor#

Convert JAX array to TensorFlow tensor.

Parameters:: array – JAX array.
Returns:: TensorFlow tensor.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import jax
>>> import jax.numpy as jnp
>>>
>>> with jax.default_device(jax.devices("cuda")[0]):
...     jax_array = jnp.zeros((100, 10), dtype=jnp.float32)
...
>>> tensorflow_tensor = interops_utils.jax2tensorflow(jax_array)
>>> type(tensorflow_tensor)
<class 'tensorflow.python...Tensor'>

jax2torch(array: jax.Array) → torch.Tensor#

Convert JAX array to PyTorch tensor.

Parameters:: array – JAX array.
Returns:: PyTorch tensor.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import jax
>>> import jax.numpy as jnp
>>>
>>> with jax.default_device(jax.devices("cuda")[0]):
...     jax_array = jnp.zeros((100, 10), dtype=jnp.float32)
...
>>> torch_tensor = interops_utils.jax2torch(jax_array)
>>> type(torch_tensor)
<class 'torch.Tensor'>

jax2warp(array: jax.Array) → warp.array#

Convert JAX array to Warp array.

Parameters:: array – JAX array.
Returns:: Warp array.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import jax
>>> import jax.numpy as jnp
>>>
>>> with jax.default_device(jax.devices("cuda")[0]):
...     jax_array = jnp.zeros((100, 10), dtype=jnp.float32)
...
>>> warp_array = interops_utils.jax2warp(jax_array)
>>> type(warp_array)
<class 'warp._src.types.array'>

numpy2jax(array: numpy.ndarray) → jax.Array#

Convert NumPy array to JAX array.

Parameters:: array – NumPy array.
Returns:: JAX array.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import numpy as np
>>>
>>> numpy_array = np.zeros((100, 10), dtype=np.float32)
>>> jax_array = interops_utils.numpy2jax(numpy_array)
>>> type(jax_array)
<class 'jaxlib.xla_extension.ArrayImpl'>

numpy2tensorflow(array: numpy.ndarray) → tensorflow.Tensor#

Convert NumPy array to TensorFlow tensor.

Parameters:: array – NumPy array.
Returns:: TensorFlow tensor.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import numpy as np
>>>
>>> numpy_array = np.zeros((100, 10), dtype=np.float32)
>>> tensorflow_tensor = interops_utils.numpy2tensorflow(numpy_array)
>>> type(tensorflow_tensor)
<class 'tensorflow.python...Tensor'>

numpy2torch(array: numpy.ndarray) → torch.Tensor#

Convert NumPy array to PyTorch tensor.

Parameters:: array – NumPy array.
Returns:: PyTorch tensor.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import numpy as np
>>>
>>> numpy_array = np.zeros((100, 10), dtype=np.float32)
>>> torch_tensor = interops_utils.numpy2torch(numpy_array)
>>> type(torch_tensor)
<class 'torch.Tensor'>

numpy2warp(array: numpy.ndarray) → warp.array#

Convert NumPy array to Warp array.

Parameters:: array – NumPy array.
Returns:: Warp array.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import numpy as np
>>>
>>> numpy_array = np.zeros((100, 10), dtype=np.float32)
>>> warp_array = interops_utils.numpy2warp(numpy_array)
>>> type(warp_array)
<class 'warp._src.types.array'>

tensorflow2jax(tensor: tensorflow.Tensor) → jax.Array#

Convert TensorFlow tensor to JAX array.

Parameters:: tensor – TensorFlow tensor.
Returns:: JAX array.

Warning

It is expected that the conversion of int32 TensorFlow tensors to other backends will be on the CPU, regardless of which context device is specified (see TensorFlow issues #34071, #41307, #46833)

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import tensorflow as tf  
>>>
>>> with tf.device("/GPU:0"):
...     tensorflow_tensor = tf.zeros((100, 10), dtype=tf.float32)
...
>>> jax_array = interops_utils.tensorflow2jax(tensorflow_tensor)
>>> type(jax_array)
<class 'jaxlib.xla_extension.Array...'>

tensorflow2numpy(tensor: tensorflow.Tensor) → numpy.ndarray#

Convert TensorFlow tensor to NumPy array.

Parameters:: tensor – TensorFlow tensor.
Returns:: NumPy array.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import tensorflow as tf  
>>>
>>> with tf.device("/GPU:0"):
...     tensorflow_tensor = tf.zeros((100, 10), dtype=tf.float32)
...
>>> numpy_array = interops_utils.tensorflow2numpy(tensorflow_tensor)
>>> type(numpy_array)
<class 'numpy.ndarray'>

tensorflow2torch(tensor: tensorflow.Tensor) → torch.Tensor#

Convert TensorFlow tensor to PyTorch tensor.

Parameters:: tensor – TensorFlow tensor.
Returns:: PyTorch tensor.

Warning

It is expected that the conversion of int32 TensorFlow tensors to other backends will be on the CPU, regardless of which context device is specified (see TensorFlow issues #34071, #41307, #46833)

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import tensorflow as tf  
>>>
>>> with tf.device("/GPU:0"):
...     tensorflow_tensor = tf.zeros((100, 10), dtype=tf.float32)
...
>>> torch_tensor = interops_utils.tensorflow2torch(tensorflow_tensor)
>>> type(torch_tensor)
<class 'torch.Tensor'>

tensorflow2warp(tensor: tensorflow.Tensor) → warp.array#

Convert TensorFlow tensor to Warp array.

Parameters:: tensor – TensorFlow tensor.
Returns:: Warp array.

Warning

It is expected that the conversion of int32 TensorFlow tensors to other backends will be on the CPU, regardless of which context device is specified (see TensorFlow issues #34071, #41307, #46833)

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import tensorflow as tf  
>>>
>>> with tf.device("/GPU:0"):
...     tensorflow_tensor = tf.zeros((100, 10), dtype=tf.float32)
...
>>> warp_array = interops_utils.tensorflow2warp(tensorflow_tensor)
>>> type(warp_array)
<class 'warp._src.types.array'>

torch2jax(tensor: torch.Tensor) → jax.Array#

Convert PyTorch tensor to JAX array.

Parameters:: tensor – PyTorch tensor.
Returns:: JAX array.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import torch
>>>
>>> torch_tensor = torch.zeros((100, 10), dtype=torch.float32, device=torch.device("cuda:0"))
>>> jax_array = interops_utils.torch2jax(torch_tensor)
>>> type(jax_array)
<class 'jaxlib.xla_extension.Array...'>

torch2numpy(tensor: torch.Tensor) → numpy.ndarray#

Convert PyTorch tensor to NumPy array.

Parameters:: tensor – PyTorch tensor.
Returns:: NumPy array.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import torch
>>>
>>> torch_tensor = torch.zeros((100, 10), dtype=torch.float32, device=torch.device("cuda:0"))
>>> numpy_array = interops_utils.torch2numpy(torch_tensor)
>>> print(type(numpy_array))
<class 'numpy.ndarray'>

torch2tensorflow(tensor: torch.Tensor) → tensorflow.Tensor#

Convert PyTorch tensor to TensorFlow tensor.

Parameters:: tensor – PyTorch tensor.
Returns:: TensorFlow tensor.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import torch
>>>
>>> torch_tensor = torch.zeros((100, 10), dtype=torch.float32, device=torch.device("cuda:0"))
>>> tensorflow_tensor = interops_utils.torch2tensorflow(torch_tensor)
>>> type(tensorflow_tensor)
<class 'tensorflow.python...Tensor'>

torch2warp(tensor: torch.Tensor) → warp.array#

Convert PyTorch tensor to Warp array.

Parameters:: tensor – PyTorch tensor.
Returns:: Warp array.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import torch
>>>
>>> torch_tensor = torch.zeros((100, 10), dtype=torch.float32, device=torch.device("cuda:0"))
>>> warp_array = interops_utils.torch2warp(torch_tensor)
>>> type(warp_array)
<class 'warp._src.types.array'>

warp2jax(array: warp.array) → jax.Array#

Convert Warp array to JAX array.

Parameters:: array – Warp array.
Returns:: JAX array.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import warp as wp
>>>
>>> wp.init()  
>>> warp_array = wp.zeros((100, 10), dtype=wp.float32, device="cuda:0")
>>> jax_array = interops_utils.warp2jax(warp_array)
>>> type(jax_array)
<class 'jaxlib.xla_extension.Array...'>

warp2numpy(array: warp.array) → numpy.ndarray#

Convert Warp array to NumPy array.

Parameters:: array – Warp array.
Returns:: NumPy array.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import warp as wp
>>>
>>> wp.init()  
>>> warp_array = wp.zeros((100, 10), dtype=wp.float32, device="cuda:0")
>>> numpy_array = interops_utils.warp2numpy(warp_array)
>>> type(numpy_array)
<class 'numpy.ndarray'>

warp2tensorflow(array: warp.array) → tensorflow.Tensor#

Convert Warp array to TensorFlow tensor.

Parameters:: array – Warp array.
Returns:: TensorFlow tensor.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import warp as wp
>>>
>>> wp.init()  
>>> warp_array = wp.zeros((100, 10), dtype=wp.float32, device="cuda:0")
>>> tensorflow_tensor = interops_utils.warp2tensorflow(warp_array)
>>> type(tensorflow_tensor)
<class 'tensorflow.python...Tensor'>

warp2torch(array: warp.array) → torch.Tensor#

Convert Warp array to PyTorch tensor.

Parameters:: array – Warp array.
Returns:: PyTorch tensor.

Example:

>>> import isaacsim.core.utils.interops as interops_utils
>>> import warp as wp
>>>
>>> wp.init()  
>>> warp_array = wp.zeros((100, 10), dtype=wp.float32, device="cuda:0")
>>> torch_tensor = interops_utils.warp2torch(warp_array)
>>> type(torch_tensor)
<class 'torch.Tensor'>

Math Utils#

Deprecated math utility functions.

cross( a: ndarray | list, b: ndarray | list, ) → ndarray#

Computes the cross product between two 3-dimensional vectors.

Parameters:

a – A 3-dimensional vector.
b – A 3-dimensional vector.

Returns:

Cross product between input vectors.

normalize(v: ndarray) → ndarray#

Normalizes the vector in place and returns it.

Parameters:: v – The vector to normalize in place.
Returns:: The input vector after normalization, or unchanged if its norm is 0.

normalized(v: ndarray | None) → ndarray | None#

Returns a normalized copy of the provided vector.

Parameters:: v – The vector to normalize.
Returns:: A normalized copy of the vector, or None if input is None.

radians_to_degrees(rad_angles: ndarray) → ndarray#

Converts input angles from radians to degrees.

Parameters:: rad_angles – Input array of angles in radians.
Returns:: Array of angles in degrees.

Math Utils#

This submodule provides math bindings for vector operations, and other facilitators such as lerp functions.

add(arg0: carb::Float3, arg1: carb::Float3) → carb::Float3#

Adds two 3D vectors

Args:

arg0 (carb.Float3): First 3D vector

arg1 (carb.Float3): Second 3D vector

Returns:

carb.Float3: arg0 + arg1.

cross(arg0: carb::Float3, arg1: carb::Float3) → carb::Float3#

Performs Cross product between 3D vectors :param arg0: 3D vector :type arg0: carb.Float3 :param arg1: 3D vector :type arg1: carb.Float3

Returns:: cross poduct arg0 x arg1.
Return type:: carb.Float3

dot(*args, **kwargs)#

Overloaded function.

dot(arg0: carb::Float3, arg1: carb::Float3) -> float

Performs Dot product between 3D vectors

Args:

arg0 (carb.Float3): 3D vector

arg1 (carb.Float3): 3D vector

Returns:

carb.Float3: dot poduct arg0 * arg1.

dot(arg0: carb::Float4, arg1: carb::Float4) -> float

Performs Dot product between 4D vectors

Args:

arg0 (carb.Float4): 4D vector

arg1 (carb.Float4): 4D vector

Returns:

carb.Float4: dot poduct arg0 * arg1.

get_basis_vector_x(arg0: carb::Float4) → carb::Float3#

Gets Basis vector X of quaternion

Parameters:: arg0 (carb.Float4) – Quaternion
Returns:: Basis Vector X
Return type:: carb.Float3

get_basis_vector_y(arg0: carb::Float4) → carb::Float3#

Gets Basis vector Y of quaternion

Parameters:: arg0 (carb.Float4) – Quaternion
Returns:: Basis Vector Y
Return type:: carb.Float3

get_basis_vector_z(arg0: carb::Float4) → carb::Float3#

Gets Basis vector Z of quaternion

Parameters:: arg0 (carb.Float4) – Quaternion
Returns:: Basis Vector Z
Return type:: carb.Float3

inverse(arg0: carb::Float4) → carb::Float4#

Gets Inverse Quaternion

Args:

arg0 (carb.Float4): quaternion

Returns:

carb.Float4: The inverse quaternion

lerp(*args, **kwargs)#

Overloaded function.

lerp(arg0: carb::Float3, arg1: carb::Float3, arg2: float) -> carb::Float3

Performs Linear interpolation between points arg0 and arg1

Args:

arg0 (carb.Float3): Point

arg1 (carb.Float3): Point

arg2 (float): distance from 0 to 1, where 0 is closest to arg0, and 1 is closest to arg1

Returns:

carb.Float3: Interpolated point
lerp(arg0: carb::Float4, arg1: carb::Float4, arg2: float) -> carb::Float4

Performs Linear interpolation between quaternions arg0 and arg1

Args:

arg0 (carb.Float4): Quaternion

arg1 (carb.Float4): Quaternion

arg2 (float): distance from 0 to 1, where 0 is closest to arg0, and 1 is closest to arg1

Returns:

carb.Float4: Interpolated quaternion

mul(*args, **kwargs)#

Overloaded function.

mul(arg0: carb::Float3, arg1: float) -> carb::Float3

Scales a 3D vector by a given value

Args:
arg0 (carb.Float3): 3D vector

arg1 (float): scale factor

Returns:
carb.Float3: scaled vector.

mul(arg0: carb::Float4, arg1: float) -> carb::Float4

Scales a 4D vector by a given value

Args:
arg0 (carb.Float4): 4D vector

arg1 (float): scale factor

Returns:
carb.Float4: scaled vector.

mul(arg0: carb::Float4, arg1: carb::Float4) -> carb::Float4

Performs a Quaternion rotation between two 4D vectors

Args:
arg0 (carb.Float4): first 4D quaternion vector

arg1 (carb.Float4): second 4D quaternion vector

Returns:
carb.Float4: rotated 4D quaternion vector.

normalize(*args, **kwargs)#

Overloaded function.

normalize(arg0: carb::Float3) -> carb::Float3

Gets normalized 3D vector

Args:

arg0 (carb.Float3): 3D Vector

Returns:

carb.Float3: Normalized 3D Vector
normalize(arg0: carb::Float4) -> carb::Float4

Gets normalized 4D vector Args:

arg0 (carb.Float4): 4D Vector

Returns:

carb.Float4: Normalized 4D Vector

rotate(arg0: carb::Float4, arg1: carb::Float3) → carb::Float3#

rotates the 3D vector arg1 by the quaternion arg0

Parameters:

arg0 (carb.Float4) – quaternion
arg1 (carb.Float3) – 3D Vector

Returns:

Rotated 3D Vector

Return type:

carb.Float3

slerp( arg0: carb::Float4, arg1: carb::Float4, arg2: float, ) → carb::Float4#

Performs Spherical Linear interpolation between quaternions arg0 and arg1

Parameters:

arg0 (carb.Float4) – Quaternion
arg1 (carb.Float4) – Quaternion
arg2 (float) – distance from 0 to 1, where 0 is closest to arg0, and 1 is closest to arg1

Returns:

Interpolated quaternion

Return type:

carb.Float4

transform_inv( arg0: pxrInternal_v0_25_11__pxrReserved__::GfTransform, arg1: pxrInternal_v0_25_11__pxrReserved__::GfTransform, ) → pxrInternal_v0_25_11__pxrReserved__::GfTransform#

Computes local Transform of arg1 with respect to arg0: inv(arg0)*arg1

Parameters:

arg0 (pxr.Transform) – origin Transform
arg1 (pxr.Transform) – Transform

Returns:

resulting transform of inv(arg0)*arg1

Return type:

oxr.Transform

set_scale(arg0: int, arg1: str, arg2: carb::Float3) → None#

Set scale for an object in the stage

Parameters:

stageId (int) – Stage ID
primPath (str) – Path to the prim
scale (carb.Float3) – Scale vector

set_transform( arg0: int, arg1: str, arg2: carb::Float3, arg3: carb::Float4, ) → None#

Set transform for an object in the stage, handles physics objects if simulation is running using dynamic control

Parameters:

stageId (int) – Stage ID
primPath (str) – Path to the prim
translation (carb.Float3) – Translation vector
rotation (carb.Float4) – Rotation quaternion

Mesh Utils#

Deprecated mesh utility functions.

get_mesh_vertices_relative_to( mesh_prim: pxr.UsdGeom.Mesh, coord_prim: pxr.Usd.Prim, ) → ndarray#

Get vertices of the mesh prim in the coordinate system of the given prim.

Parameters:

mesh_prim – Mesh prim to get the vertex points.
coord_prim – Prim used as the relative coordinate.

Returns:

Vertices of the mesh in the coordinate system of the given prim. Shape is (N, 3).

Example

>>> import isaacsim.core.utils.mesh as mesh_utils
>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> # 1 stage unit length cube centered at (0.0, 0.0, 0.0)
>>> mesh_prim = stage_utils.get_current_stage().GetPrimAtPath("/World/Cube")
>>> # 1 stage unit diameter sphere centered at (1.0, 1.0, 1.0)
>>> coord_prim = stage_utils.get_current_stage().GetPrimAtPath("/World/Sphere")
>>>
>>> mesh_utils.get_mesh_vertices_relative_to(mesh_prim, coord_prim)
[[-1.5 -1.5 -0.5]
 [-0.5 -1.5 -0.5]
 [-1.5 -0.5 -0.5]
 [-0.5 -0.5 -0.5]
 [-1.5 -1.5 -1.5]
 [-0.5 -1.5 -1.5]
 [-1.5 -0.5 -1.5]
 [-0.5 -0.5 -1.5]]

Physics Utils#

Deprecated physics utility functions.

get_rigid_body_enabled(prim_path: str) → bool | None#

Get the physics:rigidBodyEnabled attribute from the USD Prim at the given path.

Parameters:: prim_path – The path to the USD Prim.
Returns:: The attribute value if it exists, otherwise None.

Example

>>> import isaacsim.core.utils.physics as physics_utils
>>>
>>> # prim without the Physics' Rigid Body property
>>> physics_utils.get_rigid_body_enabled("/World/Cube")
None
>>> # prim with the physics Rigid Body property added and enabled
>>> physics_utils.get_rigid_body_enabled("/World/Cube")
True

set_rigid_body_enabled(_value: bool, prim_path: str) → None#

If it exists, set the physics:rigidBodyEnabled attribute on the USD Prim at the given path.

Note

If the prim does not have the physics Rigid Body property added, calling this function will have no effect.

Parameters:

_value – Value to set on the physics:rigidBodyEnabled attribute.
prim_path – The path to the USD Prim.

Example

>>> import isaacsim.core.utils.physics as physics_utils
>>>
>>> physics_utils.set_rigid_body_enabled(False, "/World/Cube")

async simulate_async( seconds: float, steps_per_sec: int = 60, callback: Callable = None, ) → None#

Simulate updates for seconds * steps_per_sec frames.

Parameters:

seconds – Time in seconds to simulate for.
steps_per_sec – Steps per second.
callback – Function to run every step.

Example

>>> import asyncio
>>> import isaacsim.core.utils.physics as physics_utils
>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     # simulate 1 second with 120 steps per second
...     await physics_utils.simulate_async(1, steps_per_sec=120)
...
>>> run_coroutine(task())

>>> import asyncio
>>> import isaacsim.core.utils.physics as physics_utils
>>> from omni.kit.async_engine import run_coroutine
>>>
>>> def callback(*args, **kwargs):
...     print("callback:", args, kwargs)
...
>>> async def task():
...     # simulate 1 second with 120 steps per second and call the callback on each step
...     await physics_utils.simulate_async(1, 120, callback)
...
>>> run_coroutine(task())

Prims Utils#

Deprecated prim utility functions.

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, ) → pxr.Usd.Prim#

Create a prim in the current USD stage.

Applies specified transforms, the semantic label, and 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 a 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 – Semantic instance name.
attributes – Key-value pairs of prim attributes to set.

Raises:

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

Returns:

The created USD prim.

Example:

>>> import numpy as np
>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # create a cube (/World/Cube) of size 2 centered at (1.0, 0.5, 0.0)
>>> prims_utils.create_prim(
...     prim_path="/World/Cube",
...     prim_type="Cube",
...     position=np.array([1.0, 0.5, 0.0]),
...     attributes={"size": 2.0}
... )
Usd.Prim(</World/Cube>)

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # load an USD file (franka.usd) to the stage under the path /World/panda
>>> prims_utils.create_prim(
...     prim_path="/World/panda",
...     prim_type="Xform",
...     usd_path="/home/<user>/Documents/Assets/Robots/FrankaRobotics/FrankaPanda/franka.usd"
... )
Usd.Prim(</World/panda>)

define_prim( prim_path: str, prim_type: str = 'Xform', fabric: bool = False, ) → pxr.Usd.Prim#

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

Note

This method will create 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 create_prim function.

Parameters:

prim_path – Path of the prim in the stage.
prim_type – The type of the prim to create.
fabric – True for fabric stage and False for USD stage.

Raises:

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

Returns:

The created USD prim.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> prims_utils.define_prim("/World/Shapes", prim_type="Xform")
Usd.Prim(</World/Shapes>)

delete_prim(prim_path: str) → None#

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

Parameters:: prim_path – Path of the prim in the stage.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> prims_utils.delete_prim("/World/Cube")

find_matching_prim_paths( prim_path_regex: str, prim_type: str | None = None, ) → list[str]#

Find all matching prim paths in the stage based on a Regex expression.

Note

Only .* is supported as a regex wildcard (converted to glob * internally). Full regex syntax is not supported.

Parameters:

prim_path_regex – The prim path pattern. Use .* as a wildcard for any segment.
prim_type – The type of the prims to filter, only supports articulation and rigid_body currently.

Returns:

List of prim paths that match the input expression.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/env/Cube, /World/env_01/Cube, /World/env_02/Cube
>>> # get only the prim Cube paths from env_01 and env_02
>>> prims_utils.find_matching_prim_paths("/World/env_.*/Cube")
['/World/env_01/Cube', '/World/env_02/Cube']

get_all_matching_child_prims(prim_path: str, predicate: ~typing.Callable[[str], bool] = <function <lambda>>, depth: int | None = None) → list[pxr.Usd.Prim]#

Perform a breadth-first search starting from the root and return all prims matching the predicate.

Parameters:

prim_path – Root prim path to start traversal from.
predicate – Predicate that checks the prim path of a prim and returns a boolean.
depth – Maximum depth for traversal, should be bigger than zero if specified.

Returns:

A list containing the root and children prims matching the specified predicate.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # get all hidden prims
>>> predicate = lambda path: prims_utils.is_prim_hidden_in_stage(path)  # True if the prim at path is hidden
>>> prims_utils.get_all_matching_child_prims("/", predicate)
[Usd.Prim(</OmniverseKit_Persp>),
 Usd.Prim(</OmniverseKit_Front>),
 Usd.Prim(</OmniverseKit_Top>),
 Usd.Prim(</OmniverseKit_Right>),
 Usd.Prim(</Render>)]

get_articulation_root_api_prim_path(prim_path: str) → str#

Get the prim path that has the Articulation Root API.

Note

This function assumes that all prims defined by a regular expression correspond to the same articulation type.

Parameters:: prim_path – Path or regex of the prims on which to search for the prim containing the API.
Returns:: Path or regex of the prim that has the Articulation Root API. If no prim has been found, the same input value is returned.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/env/Ant, /World/env_01/Ant, /World/env_02/Ant
>>> # search specifying the prim with the Articulation Root API
>>> prims_utils.get_articulation_root_api_prim_path("/World/env/Ant/torso")
/World/env/Ant/torso
>>> # search specifying some ancestor prim that does not have the Articulation Root API
>>> prims_utils.get_articulation_root_api_prim_path("/World/env/Ant")
/World/env/Ant/torso
>>> # regular expression search
>>> prims_utils.get_articulation_root_api_prim_path("/World/env.*/Ant")
/World/env.*/Ant/torso

get_first_matching_child_prim( prim_path: str, predicate: Callable[[str], bool], fabric: bool = False, ) → pxr.Usd.Prim#

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

Parameters:

prim_path – Path of the prim in the stage.
predicate – Function to test the prims against.
fabric – True for fabric stage and False for USD stage.

Returns:

The first prim or child of the prim, as defined by GetChildren, that passes the predicate. If no prim matches, None is returned.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube, /World/Cube_01, /World/Cube_02.
>>> # Get the first child prim of type Cube
>>> predicate = lambda path: prims_utils.get_prim_type_name(path) == "Cube"
>>> prims_utils.get_first_matching_child_prim("/", predicate)
Usd.Prim(</World/Cube>)

get_first_matching_parent_prim( prim_path: str, predicate: Callable[[str], bool], ) → pxr.Usd.Prim#

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

Parameters:

prim_path – Path of the prim in the stage.
predicate – Function to test the prims against.

Returns:

The first prim on the parent path, as defined by GetParent, that passes the predicate. If no parent prim matches, None is returned.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube. Get the first parent of Cube prim of type Xform
>>> predicate = lambda path: prims_utils.get_prim_type_name(path) == "Xform"
>>> prims_utils.get_first_matching_parent_prim("/World/Cube", predicate)
Usd.Prim(</World>)

get_prim_at_path( prim_path: str, fabric: bool = False, ) → Usd.Prim | usdrt.Usd._Usd.Prim | None#

Get the USD or Fabric Prim at a given path string.

Parameters:

prim_path – Path of the prim in the stage.
fabric – True for fabric stage and False for USD stage.

Returns:

USD or Fabric Prim object at the given path in the current stage. If no current stage exists, None is returned.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> prims_utils.get_prim_at_path("/World/Cube")
Usd.Prim(</World/Cube>)

get_prim_attribute_names( prim_path: str, fabric: bool = False, ) → list[str]#

Get all attribute names of a prim at the path.

Parameters:

prim_path – Path of the prim in the stage.
fabric – True for fabric stage and False for USD stage.

Raises:

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

Returns:

List of the prim attribute names.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> prims_utils.get_prim_attribute_names("/World/Cube")
['doubleSided', 'extent', 'orientation', 'primvars:displayColor', 'primvars:displayOpacity',
 'purpose', 'size', 'visibility', 'xformOp:orient', 'xformOp:scale', 'xformOp:translate', 'xformOpOrder']

get_prim_attribute_value( prim_path: str, attribute_name: str, fabric: bool = False, ) → Any#

Get a prim attribute value.

Parameters:

prim_path – Path of the prim in the stage.
attribute_name – Name of the attribute to get.
fabric – True for fabric stage and False for USD stage.

Raises:

Exception – If there is not a valid prim at the given path.

Returns:

Prim attribute value.

Example

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> prims_utils.get_prim_attribute_value("/World/Cube", attribute_name="size")
1.0

get_prim_children(prim: pxr.Usd.Prim) → list[pxr.Usd.Prim]#

Return the call of the USD Prim’s GetChildren member function.

Parameters:: prim – The parent USD Prim.
Returns:: A list of the prim’s children.

Example

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube, /World/Cube_01, /World/Cube_02.
>>> # Get all prims under the prim World
>>> prim = prims_utils.get_prim_at_path("/World")
>>> prims_utils.get_prim_children(prim)
[Usd.Prim(</World/Cube>), Usd.Prim(</World/Cube_01>), Usd.Prim(</World/Cube_02>)]

get_prim_object_type(prim_path: str) → str | None#

Get the dynamic control object type of the USD Prim at the given path.

If the prim at the path is of Dynamic Control type, such as rigid_body, joint, dof, articulation, attractor, or d6joint, the corresponding string is returned. If it is an Xformable prim, “xform” is returned. Otherwise None is returned.

Parameters:: prim_path – Path of the prim in the stage.
Raises:: Exception – If the USD Prim is not a supported type.
Returns:: String corresponding to the object type.

Example

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> prims_utils.get_prim_object_type("/World/Cube")
xform

get_prim_parent(prim: pxr.Usd.Prim) → pxr.Usd.Prim#

Return the call of the USD Prim’s GetParent member function.

Parameters:: prim – The USD Prim to call GetParent on.
Returns:: The prim’s parent returned from GetParent.

Example

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube. Get the prim Cube's parent
>>> prim = prims_utils.get_prim_at_path("/World/Cube")
>>> prims_utils.get_prim_parent(prim)
Usd.Prim(</World>)

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

Get the path of a given USD prim.

Parameters:: prim – The input USD prim.
Returns:: The path to the input prim.

Example

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> prim = prims_utils.get_prim_at_path("/World/Cube")  # Usd.Prim(</World/Cube>)
>>> prims_utils.get_prim_path(prim)
/World/Cube

get_prim_property(prim_path: str, property_name: str) → Any#

Get the attribute of the USD Prim at the given path.

Parameters:

prim_path – Path of the prim in the stage.
property_name – Name of the attribute to get.

Returns:

The attribute value if it exists, None otherwise.

Example

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> prims_utils.get_prim_property("/World/Cube", property_name="size")
1.0

get_prim_type_name(prim_path: str, fabric: bool = False) → str#

Get the TypeName of the USD Prim at the path if it is valid.

Parameters:

prim_path – Path of the prim in the stage.
fabric – True for fabric stage and False for USD stage.

Raises:

Exception – If there is not a valid prim at the given path.

Returns:

The TypeName of the USD Prim at the path string.

Example

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> prims_utils.get_prim_type_name("/World/Cube")
Cube

is_prim_ancestral(prim_path: str) → bool#

Check if any of the prim’s ancestors were brought in as a reference.

Parameters:: prim_path – The path to the USD prim.
Returns:: True if prim is part of a referenced prim, false otherwise.

Example

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # /World/Cube is a prim created
>>> prims_utils.is_prim_ancestral("/World/Cube")
False
>>> # /World/panda is an USD file loaded as reference under that path
>>> prims_utils.is_prim_ancestral("/World/panda")
False
>>> prims_utils.is_prim_ancestral("/World/panda/panda_link0")
True

is_prim_hidden_in_stage(prim_path: str) → bool#

Checks if the prim is hidden in the USD stage or not.

Warning

This function checks for the hide_in_stage_window prim metadata. This metadata is not related to the visibility of the prim.

Parameters:: prim_path – The path to the USD prim.
Returns:: True if prim is hidden from stage window, False if not hidden.

Example

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # prim without the 'hide_in_stage_window' metadata
>>> prims_utils.is_prim_hidden_in_stage("/World/Cube")
False
>>> # prim with the 'hide_in_stage_window' metadata set to True
>>> prims_utils.is_prim_hidden_in_stage("/World/Cube")
True

is_prim_no_delete(prim_path: str) → bool#

Checks whether a prim can be deleted or not from USD stage.

Note

This function checks for the no_delete prim metadata. A prim with this metadata set to True cannot be deleted by using the edit menu, the context menu, or by calling the delete_prim function, for example.

Parameters:: prim_path – The path to the USD prim.
Returns:: True if prim cannot be deleted, False if it can.

Example

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # prim without the 'no_delete' metadata
>>> prims_utils.is_prim_no_delete("/World/Cube")
False
>>> # prim with the 'no_delete' metadata set to True
>>> prims_utils.is_prim_no_delete("/World/Cube")
True

is_prim_non_root_articulation_link(prim_path: str) → bool#

Query whether a prim path corresponds to a non-root link in an articulation.

Parameters:: prim_path – Prim path to query.
Returns:: True if the prim path corresponds to a non-root articulation link that cannot have a transformation applied to it.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # /World/panda contains the prim tree for the Franka panda robot.
>>> # The prim on this path has the Physics Articulation Root property applied
>>> prims_utils.is_prim_non_root_articulation_link("/World/panda")
False
>>> prims_utils.is_prim_non_root_articulation_link("/World/panda/panda_link0")
True

is_prim_path_valid(prim_path: str, fabric: bool = False) → bool#

Check whether a path has a valid USD or Fabric Prim in the current stage.

Parameters:

prim_path – Path of the prim in the stage.
fabric – True for Fabric stage and False for USD stage.

Returns:

True if the path points to a valid prim.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube
>>> prims_utils.is_prim_path_valid("/World/Cube")
True
>>> prims_utils.is_prim_path_valid("/World/Cube/")
False
>>> prims_utils.is_prim_path_valid("/World/Sphere")  # it does not exist
False

is_prim_root_path(prim_path: str) → bool#

Check whether the input prim path is the root path.

Parameters:: prim_path – Path to the USD prim.
Returns:: True if the prim path is “/”, False otherwise.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube
>>> prims_utils.is_prim_root_path("/")
True
>>> prims_utils.is_prim_root_path("/World")
False
>>> prims_utils.is_prim_root_path("/World/Cube")
False

move_prim(path_from: str, path_to: str) → None#

Run the Move command to change a prims USD path in the stage.

Parameters:

path_from – Path of the USD Prim to move.
path_to – Destination path of the prim.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube. Move the prim Cube outside the prim World
>>> prims_utils.move_prim("/World/Cube", "/Cube")

query_parent_path( prim_path: str, predicate: Callable[[str], bool], ) → bool#

Check whether one of the ancestors of the prim at the prim path passes the predicate.

Parameters:

prim_path – Path to the USD Prim for which to check ancestors.
predicate – Condition that must be True for an ancestor path.

Returns:

True if an ancestor passes the predicate, False otherwise.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube. Check if the prim Cube has an ancestor of type Xform
>>> predicate = lambda path: prims_utils.get_prim_type_name(path) == "Xform"
>>> prims_utils.query_parent_path("/World/Cube", predicate)
True

set_prim_attribute_value( prim_path: str, attribute_name: str, value: Any, fabric: bool = False, ) → None#

Set a prim attribute value.

Parameters:

prim_path – Path of the prim in the stage.
attribute_name – Name of the attribute to set.
value – Value to set the attribute to.
fabric – True for Fabric stage and False for USD stage.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube. Set the Cube size to 5.0
>>> prims_utils.set_prim_attribute_value("/World/Cube", attribute_name="size", value=5.0)

set_prim_hide_in_stage_window(prim: pxr.Usd.Prim, hide: bool) → None#

Set hide_in_stage_window metadata for a prim.

Warning

This metadata is unrelated to the visibility of the prim. Use the set_prim_visibility function for the latter purpose.

Parameters:

prim – USD Prim to set.
hide – True to hide the prim in the stage window, false to show it.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> prim = prims_utils.get_prim_at_path("/World/Cube")
>>> prims_utils.set_prim_hide_in_stage_window(prim, True)

set_prim_no_delete(prim: pxr.Usd.Prim, no_delete: bool) → None#

Set no_delete metadata for a prim.

Note

A prim with this metadata set to True cannot be deleted by using the edit menu, the context menu, or by calling the delete_prim function, for example.

Parameters:

prim – USD Prim to set.
no_delete – True to make the prim undeletable in the stage window, false to allow deletion.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> prim = prims_utils.get_prim_at_path("/World/Cube")
>>> prims_utils.set_prim_no_delete(prim, True)

set_prim_property( prim_path: str, property_name: str, property_value: Any, ) → None#

Set an attribute of the USD Prim at the path.

Parameters:

prim_path – Path of the prim in the stage.
property_name – Name of the attribute to set.
property_value – Value to set the attribute to.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube. Set the Cube size to 5.0
>>> prims_utils.set_prim_property("/World/Cube", property_name="size", property_value=5.0)

set_prim_visibility(prim: pxr.Usd.Prim, visible: bool) → None#

Set the visibility of the prim in the opened stage.

Note

The method does this through the USD API.

Parameters:

prim – USD prim to set.
visible – Flag to set the visibility of the USD prim in the stage.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube. Make the Cube not visible
>>> prim = prims_utils.get_prim_at_path("/World/Cube")
>>> prims_utils.set_prim_visibility(prim, False)

set_targets( prim: pxr.Usd.Prim, attribute: str, target_prim_paths: list, ) → None#

Set targets for a prim relationship attribute.

Parameters:

prim – Prim to create and set the relationship attribute on.
attribute – Relationship attribute to create.
target_prim_paths – List of target prim paths to set.

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube, /World/Cube_01, /World/Cube_02.
>>> # Set each prim Cube to the relationship targetPrim of the prim World
>>> prim = prims_utils.get_prim_at_path("/World")
>>> targets = ["/World/Cube", "/World/Cube_01", "/World/Cube_02"]
>>> prims_utils.set_targets(prim, "targetPrim", targets)

Random Utils#

Deprecated random utility functions.

get_random_translation_from_camera( min_distance: float, max_distance: float, fov_x: float, fov_y: float, fraction_to_screen_edge: float, ) → ndarray#

Get a random translation from the camera, in the camera frame, that is in view of the camera.

Parameters:

min_distance – Minimum distance away from the camera along the optical axis of the random translation.
max_distance – Maximum distance away from the camera along the optical axis of the random translation.
fov_x – Field of view of the camera in the x-direction in radians.
fov_y – Field of view of the camera in the y-direction in radians.
fraction_to_screen_edge – Maximum allowed fraction to the edge of the screen the translated point may appear when viewed from the camera. A value of 0 corresponds to the translated point being centered in the camera view on the optical axis, whereas a value of 1 corresponds to the translated point being on the edge of the screen in the camera view.

Returns:

Random translation from the camera, in the camera frame, that is in view of the camera. Shape is (3, ).

get_random_values_in_range( min_range: ndarray, max_range: ndarray, ) → ndarray#

Get random values where each element is between the corresponding min_range and max_range element.

Parameters:

min_range – Minimum values for each corresponding element of the array of random values. Shape is (num_values, ).
max_range – Maximum values for each corresponding element of the array of random values. Shape is (num_values, ).

Returns:

Array of random values. Shape is (num_values, ).

get_random_world_pose_in_view( camera_prim: pxr.Usd.Prim, min_distance: float, max_distance: float, fov_x: float, fov_y: float, fraction_to_screen_edge: float, coord_prim: pxr.Usd.Prim, min_rotation_range: ndarray, max_rotation_range: ndarray, ) → tuple[ndarray, ndarray]#

Get a pose defined in the world frame that is in view of the camera.

Parameters:

camera_prim – USD camera prim.
min_distance – Minimum distance away from the camera along the optical axis of the random translation.
max_distance – Maximum distance away from the camera along the optical axis of the random translation.
fov_x – Field of view of the camera in the x-direction in radians.
fov_y – Field of view of the camera in the y-direction in radians.
fraction_to_screen_edge – Maximum allowed fraction to the edge of the screen the translated point may appear when viewed from the camera. A value of 0 corresponds to the translated point being centered in the camera view on the optical axis, whereas a value of 1 corresponds to the translated point being on the edge of the screen in the camera view.
coord_prim – USD prim whose frame the orientation is defined with respect to.
min_rotation_range – Minimum XYZ Euler angles of the random pose, defined with respect to the frame of the prim at coord_prim. Shape is (3, ).
max_rotation_range – Maximum XYZ Euler angles of the random pose, defined with respect to the frame of the prim at coord_prim.

Returns:

First index is position in the world frame. Shape is (3, ). Second index is quaternion orientation in the world frame. Quaternion is scalar-first (w, x, y, z). Shape is (4, ).

Render Product Utils#

Deprecated render product utility functions.

add_aov(render_product_path: str, aov_name: str) → None#

Adds an AOV/Render Var to an existing render product.

Parameters:

render_product_path – Path to the render product prim.
aov_name – Name of the render var we want to add to this render product.

Raises:

RuntimeError – If the render product path is invalid.
RuntimeError – If the renderVar could not be created.
RuntimeError – If the renderVar could not be added to the render product.

get_camera_prim_path(render_product_path: str) → str#

Get the current camera for a render product.

Parameters:: render_product_path – Path to the render product prim.
Returns:: Path to the camera prim attached to this render product.
Raises:: RuntimeError – If the render product path is invalid.

get_resolution(render_product_path: str) → tuple[int]#

Get resolution for a render product.

Parameters:: render_product_path – Path to the render product prim.
Returns:: A tuple containing (width, height).
Raises:: RuntimeError – If the render product path is invalid.

set_camera_prim_path( render_product_path: str, camera_prim_path: str, ) → None#

Sets the camera prim path for a render product.

Also applies the OmniRtxCameraExposureAPI_1 schema to the camera prim and sets the exposure:time attribute to 0.02.

Parameters:

render_product_path – Path to the render product prim.
camera_prim_path – Path to the camera prim.

Raises:

RuntimeError – If the render product path is invalid.
RuntimeError – If the camera prim path is invalid.

set_resolution( render_product_path: str, resolution: tuple[int], ) → None#

Set resolution for a render product.

Parameters:

render_product_path – Path to the render product prim.
resolution – Width and height for render product.

Raises:

RuntimeError – If the render product path is invalid.

Rotations Utils#

Deprecated rotation utility functions.

euler_angles_to_quat( euler_angles: ndarray, degrees: bool = False, extrinsic: bool = True, ) → ndarray#

Convert Euler angles to quaternion.

Parameters:

euler_angles – Euler XYZ angles.
degrees – Whether input angles are in degrees.
extrinsic – True if the Euler angles follow the extrinsic angles convention (equivalent to ZYX ordering but returned in reverse), and False if they follow the intrinsic angles convention (equivalent to XYZ ordering).

Returns:

Quaternion in (w, x, y, z).

euler_to_rot_matrix( euler_angles: ndarray, degrees: bool = False, extrinsic: bool = True, ) → ndarray#

Convert Euler XYZ or ZYX angles to rotation matrix.

Parameters:

euler_angles – Euler angles.
degrees – Whether passed angles are in degrees.
extrinsic – True if the Euler angles follow the extrinsic angles convention (equivalent to ZYX ordering but returned in reverse), and False if they follow the intrinsic angles convention (equivalent to XYZ ordering).

Returns:

A 3x3 rotation matrix in its extrinsic or intrinsic form depending on extrinsic.

gf_quat_to_np_array( orientation: Gf.Quatd | Gf.Quatf | Gf.Quaternion, ) → np.ndarray#

Converts a pxr Quaternion type to a numpy array following [w, x, y, z] convention.

Parameters:: orientation – Input quaternion object.
Returns:: A (4,) quaternion array in (w, x, y, z).

gf_rotation_to_np_array( orientation: pxr.Gf.Rotation, ) → ndarray#

Converts a pxr Rotation type to a numpy array following [w, x, y, z] convention.

Parameters:: orientation – Pxr rotation object.
Returns:: A (4,) quaternion array in (w, x, y, z).

lookat_to_quatf( camera: pxr.Gf.Vec3f, target: pxr.Gf.Vec3f, up: pxr.Gf.Vec3f, ) → pxr.Gf.Quatf#

Compute a quaternion rotation from camera position looking at target.

Parameters:

camera – The camera position as a 3D vector.
target – The target position to look at as a 3D vector.
up – The up direction vector.

Returns:

Pxr quaternion object representing the look-at rotation.

matrix_to_euler_angles( mat: ndarray, degrees: bool = False, extrinsic: bool = True, ) → ndarray#

Convert rotation matrix to Euler XYZ extrinsic or intrinsic angles.

Parameters:

mat – A 3x3 rotation matrix.
degrees – Whether returned angles should be in degrees.
extrinsic – True if the rotation matrix follows the extrinsic matrix convention (equivalent to ZYX ordering but returned in reverse), and False if it follows the intrinsic matrix convention (equivalent to XYZ ordering).

Returns:

Euler XYZ angles in intrinsic form if extrinsic is False, or Euler XYZ angles in extrinsic form if extrinsic is True.

quat_to_euler_angles( quat: ndarray, degrees: bool = False, extrinsic: bool = True, ) → ndarray#

Convert input quaternion to Euler XYZ or ZYX angles.

Parameters:

quat – Input quaternion (w, x, y, z).
degrees – Whether returned angles should be in degrees.
extrinsic – True if the Euler angles follow the extrinsic angles convention (equivalent to ZYX ordering but returned in reverse), and False if they follow the intrinsic angles convention (equivalent to XYZ ordering).

Returns:

Euler XYZ angles in intrinsic form if extrinsic is False, or Euler XYZ angles in extrinsic form if extrinsic is True.

quat_to_rot_matrix(quat: ndarray) → ndarray#

Convert input quaternion to rotation matrix.

Parameters:: quat – Input quaternion (w, x, y, z).
Returns:: A 3x3 rotation matrix.

rot_matrix_to_quat(mat: ndarray) → ndarray#

Convert rotation matrix to Quaternion.

Parameters:: mat – A 3x3 rotation matrix.
Returns:: Quaternion in (w, x, y, z).

Semantics Utils#

Deprecated semantic labeling utility functions.

add_labels( prim: pxr.Usd.Prim, labels: list[str], instance_name: str = 'class', overwrite: bool = True, ) → None#

Apply semantic labels to a prim using UsdSemantics.LabelsAPI.

Parameters:

prim – USD prim to add or update labels on.
labels – Labels to apply.
instance_name – Name of the semantic instance.
overwrite – If True, existing labels for this instance are replaced. If False, new labels are appended to existing labels.

check_incorrect_labels( prim_path: str | None = None, validate_against_prim_path: bool = False, ) → list[list[str]]#

Return [prim_path, label] pairs for meshes where at least one semantic label is considered incorrect.

Labeled meshes have no mismatches unless validate_against_prim_path enables the legacy heuristic that treats labels absent from the prim path as incorrect.

Parameters:

prim_path – Prim path whose children’s labels are checked. If None, checks the whole stage.
validate_against_prim_path – Whether to check if labels appear in the prim path string.

Returns:

List containing pairs of [prim_path, first_incorrect_label].

check_missing_labels(prim_path: str | None = None) → list[str]#

Return prim paths of meshes with missing semantic labels using UsdSemantics.LabelsAPI.

Parameters:: prim_path – Prim path whose children’s labels are checked. If None, checks the whole stage.
Returns:: Prim paths of meshes with no LabelsAPI applied.

count_labels_in_scene(prim_path: str | None = None) → dict[str, int]#

Return semantic labels using UsdSemantics.LabelsAPI and their corresponding counts.

Parameters:: prim_path – Prim path whose children’s labels are checked. If None, checks the whole stage.
Returns:: Dictionary mapping individual labels to their total count across all instances. Includes a ‘missing_labels’ count for meshes with no LabelsAPI.

get_labels(prim: pxr.Usd.Prim) → dict[str, list[str]]#

Return semantic labels using UsdSemantics.LabelsAPI applied to a prim.

Parameters:: prim – Prim to return labels for.
Returns:: Dictionary mapping instance names to lists of labels. Returns an empty dict if no LabelsAPI instances are found.

remove_labels( prim: pxr.Usd.Prim, instance_name: str | None = None, include_descendants: bool = False, ) → None#

Remove semantic labels using UsdSemantics.LabelsAPI from a prim.

Parameters:

prim – Prim to remove labels from.
instance_name – Specific instance name to remove. If None, removes all LabelsAPI instances.
include_descendants – Whether to traverse children and remove labels recursively.

upgrade_prim_semantics_to_labels( prim: pxr.Usd.Prim, include_descendants: bool = False, ) → int#

Upgrade a prim and optionally its descendants from the deprecated SemanticsAPI to UsdSemantics.LabelsAPI.

Converts each found SemanticsAPI instance on the processed prims to a corresponding LabelsAPI instance. The old ‘semanticType’ becomes the new LabelsAPI ‘instance_name’, and the old ‘semanticData’ becomes the single label in the new ‘labels’ list. The old SemanticsAPI is always removed after upgrading.

Parameters:

prim – Starting prim to upgrade.
include_descendants – If True, upgrades the prim and all its descendants. If False, upgrades only the specified prim.

Returns:

Total number of SemanticsAPI instances successfully upgraded to LabelsAPI.

Stage Utils#

Deprecated USD stage utility functions.

add_reference_to_stage( usd_path: str, prim_path: str, prim_type: str = 'Xform', ) → pxr.Usd.Prim#

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

Adds a reference to an external USD file at the specified prim path on the current stage. If the prim does not exist, it is created with the specified type. This function also handles stage units verification to ensure compatibility.

Parameters:

usd_path – Path to the USD file to reference.
prim_path – Prim path where the reference is attached.
prim_type – Prim type to create if it does not exist.

Returns:

The USD prim at the specified prim path.

Raises:

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

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> # load an USD file (franka.usd) to the stage under the path /World/panda
>>> prim = stage_utils.add_reference_to_stage(
...     usd_path="/home/<user>/Documents/Assets/Robots/FrankaRobotics/FrankaPanda/franka.usd",
...     prim_path="/World/panda"
... )
>>> prim
Usd.Prim(</World/panda>)

clear_stage( predicate: Callable[[str], bool] | None = None, ) → None#

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

Parameters:: predicate – User defined function that takes a prim_path as input and returns True or False if the prim should or should not be deleted. If predicate is None, a default is used that deletes all prims.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> # clear the whole stage
>>> stage_utils.clear_stage()
>>>
>>> # given the stage: /World/Cube, /World/Cube_01, /World/Cube_02.
>>> # Delete only the prims of type Cube
>>> predicate = lambda path: prims_utils.get_prim_type_name(path) == "Cube"
>>> stage_utils.clear_stage(predicate)  # after the execution the stage will be /World

close_stage(callback_fn: Callable = None) → bool#

Closes the current opened 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 – Callback function to call while closing.
Returns:: True if operation is successful, otherwise false.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_utils.close_stage()
True

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> def callback(*args, **kwargs):
...     print("callback:", args, kwargs)
...
>>> stage_utils.close_stage(callback)
True
>>> stage_utils.close_stage(callback)
callback: (False, 'Stage opening or closing already in progress!!') {}
False

create_new_stage() → pxr.Usd.Stage#

Create a new stage attached to the USD context.

Returns:: The created USD stage.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_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>)

async create_new_stage_async() → None#

Create a new stage.

Example:

>>> import asyncio
>>> import isaacsim.core.utils.stage as stage_utils
>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await stage_utils.create_new_stage_async()
...
>>> run_coroutine(task())

create_new_stage_in_memory() → pxr.Usd.Stage#

Create a new stage in memory.

Returns:: The created USD stage.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_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>)

get_current_stage( fabric: bool = False, ) → Usd.Stage | usdrt.Usd._Usd.Stage#

Get the current open USD or Fabric stage.

Parameters:: fabric – True to get the Fabric stage. False to get the USD stage.
Returns:: The USD or Fabric stage as specified by the fabric argument.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_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>)

get_current_stage_id() → int#

Get the current open stage id.

Returns:: The stage id.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_utils.get_current_stage_id()
1234567890

get_next_free_path(path: str, parent: str = None) → str#

Returns the next free USD path for the current stage.

Parameters:

path – Path to check.
parent – Parent prim for the given path.

Returns:

A new path that does not exist on the current stage.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> # given the stage: /World/Cube, /World/Cube_01.
>>> # Get the next available path for /World/Cube
>>> stage_utils.get_next_free_path("/World/Cube")
/World/Cube_02

get_stage_units() → float#

Get the stage meters per unit currently set.

The most common units and their values are listed in the following table:

Unit	Value
kilometer (km)	1000.0
meters (m)	1.0
inch (in)	0.0254
centimeters (cm)	0.01
millimeter (mm)	0.001

Returns:: Current stage meters per unit.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_utils.get_stage_units()
1.0

get_stage_up_axis() → str#

Get the current up-axis of USD stage.

Returns:: The up-axis of the stage.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_utils.get_stage_up_axis()
Z

is_stage_loading() → bool#

Convenience function to see if any files are being loaded.

Returns:: True if loading, False otherwise.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_utils.is_stage_loading()
False

open_stage(usd_path: str) → bool#

Open the given USD file and replace currently opened stage.

Parameters:: usd_path – Path to the USD file to open.
Raises:: ValueError – When input path is not a supported file type by USD.
Returns:: True if operation is successful, otherwise False.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_utils.open_stage("/home/<user>/Documents/Assets/Robots/FrankaRobotics/FrankaPanda/franka.usd")
True

async open_stage_async(usd_path: str) → tuple[bool, int]#

Open the given USD file and replace currently opened stage.

Parameters:: usd_path – Path to the USD file to open.
Raises:: ValueError – When input path is not a supported file type by USD.
Returns:: A tuple containing (success status, error code).

Example:

>>> import asyncio
>>> import isaacsim.core.utils.stage as stage_utils
>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await stage_utils.open_stage_async("/home/<user>/Documents/Assets/Robots/FrankaRobotics/FrankaPanda/franka.usd")
...
>>> run_coroutine(task())

print_stage_prim_paths(fabric: bool = False) → None#

Traverses the stage and logs all prim paths, including hidden prims, via carb.log_info.

Parameters:: fabric – True to get the Fabric stage. False to get the USD stage.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> # given the stage: /World/Cube, /World/Cube_01, /World/Cube_02.
>>> # prim paths are logged via carb.log_info
>>> stage_utils.print_stage_prim_paths()

remove_deleted_references() → None#

Clean up deleted references in the current USD stage.

Removes any deleted items from both payload and references lists for all prims in the stage’s root layer. Prints information about any deleted items that were cleaned up.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>> stage_utils.remove_deleted_references()
Removed 2 deleted payload items from </World/Robot>
Removed 1 deleted reference items from </World/Scene>

save_stage( usd_path: str, save_and_reload_in_place: bool = True, ) → bool#

Save USD file to path, overwriting it with the current stage.

Parameters:

usd_path – File path to save the current stage to.
save_and_reload_in_place – Use save_as_stage to save and reload the root layer in place.

Raises:

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

Returns:

True if operation is successful, otherwise False.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_utils.save_stage("/home/<user>/Documents/Save/stage.usd")
True

set_livesync_stage(usd_path: str, enable: bool) → bool#

Save the stage and set Live Sync mode for real-time live editing of shared files on a Nucleus server.

Parameters:

usd_path – Path to enable Live Sync for. It will be overwritten with the current stage.
enable – True to enable Live Sync, False to disable Live Sync.

Raises:

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

Returns:

True if operation is successful, otherwise False.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_utils.set_livesync_stage("omniverse://localhost/Users/Live/stage.usd", enable=True)
server omniverse://localhost: ConnectionStatus.CONNECTING
server omniverse://localhost: ConnectionStatus.CONNECTED
True

set_stage_units(stage_units_in_meters: float) → None#

Set the stage meters per unit.

The most common units and their values are listed in the following table:

Unit	Value
kilometer (km)	1000.0
meters (m)	1.0
inch (in)	0.0254
centimeters (cm)	0.01
millimeter (mm)	0.001

Parameters:: stage_units_in_meters – Units for stage.
Raises:: Exception – When there is no stage currently opened.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_utils.set_stage_units(1.0)

set_stage_up_axis(axis: str = 'z') → None#

Change the up axis of the current stage.

Parameters:: axis – Valid values are "x", "y" and "z".
Raises:: Exception – When there is no stage currently opened.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> # set stage up axis to Y-up
>>> stage_utils.set_stage_up_axis("y")

traverse_stage(fabric: bool = False) → Iterable#

Traverse through prims, hidden or not, in the opened USD or Fabric stage.

Parameters:: fabric – Whether to use the Fabric stage instead of the USD stage.
Returns:: Generator which yields prims from the stage in depth-first-traversal order.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> # given the stage: /World/Cube, /World/Cube_01, /World/Cube_02.
>>> # Traverse through prims in the stage
>>> for prim in stage_utils.traverse_stage():
>>>     print(prim)
Usd.Prim(</World>)
Usd.Prim(</World/Cube>)
Usd.Prim(</World/Cube_01>)
Usd.Prim(</World/Cube_02>)
Usd.Prim(</OmniverseKit_Persp>)
Usd.Prim(</OmniverseKit_Front>)
Usd.Prim(</OmniverseKit_Top>)
Usd.Prim(</OmniverseKit_Right>)
Usd.Prim(</Render>)

update_stage() → None#

Update the current USD stage.

Example:

>>> import isaacsim.core.utils.stage as stage_utils
>>>
>>> stage_utils.update_stage()

async update_stage_async() → None#

Update the current USD stage.

Example:

>>> import asyncio
>>> import isaacsim.core.utils.stage as stage_utils
>>> from omni.kit.async_engine import run_coroutine
>>>
>>> async def task():
...     await stage_utils.update_stage_async()
...
>>> run_coroutine(task())

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

Context manager that sets a thread-local stage.

Parameters:: stage – The USD stage to set in the context.
Yields:: Control to the caller with the stage set in thread-local context.
Raises:: AssertionError – If the stage is not a USD stage instance.

Example:

>>> from pxr import Usd
>>> import isaacsim.core.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

String Utils#

Deprecated string utility functions.

find_root_prim_path_from_regex( prim_path_regex: str, ) → tuple[str, int]#

Find the first prim above the regex pattern prim and its position.

Parameters:: prim_path_regex – Full prim path including the regex pattern prim.
Returns:: A tuple where the first element is the prim path to the parent of the regex prim and the second element represents the level of the regex prim in the USD stage tree representation.

find_unique_string_name( initial_name: str, is_unique_fn: Callable[[str], bool], ) → str#

Find a unique string name based on the predicate function provided.

The string is appended with “_N”, where N is a natural number until the resultant string is unique.

Parameters:

initial_name – The initial string name.
is_unique_fn – The predicate function to validate against.

Returns:

A unique string based on the input function.

Transformations Utils#

Deprecated transformation utility functions.

get_relative_transform( source_prim: pxr.Usd.Prim, target_prim: pxr.Usd.Prim, ) → ndarray#

Get the relative transformation matrix from the source prim to the target prim.

Parameters:

source_prim – Source prim from which frame to compute the relative transform.
target_prim – Target prim to which frame to compute the relative transform.

Returns:

Column-major transformation matrix with shape (4, 4).

get_transform_with_normalized_rotation( transform: ndarray, ) → ndarray#

Get the transform after normalizing rotation component.

Parameters:: transform – Transformation matrix with shape (4, 4).
Returns:: Transformation matrix with normalized rotation with shape (4, 4).

get_translation_from_target( translation_from_source: ndarray, source_prim: pxr.Usd.Prim, target_prim: pxr.Usd.Prim, ) → ndarray#

Get a translation with respect to the target’s frame, from a translation in the source’s frame.

Parameters:

translation_from_source – Translation from the frame of the prim at source_path. Shape is (3, ).
source_prim – Prim path of the prim whose frame the original/untransformed translation (translation_from_source) is defined with respect to.
target_prim – Prim path of the prim whose frame corresponds to the target frame that the returned translation will be defined with respect to.

Returns:

Translation with respect to the target’s frame. Shape is (3, ).

get_world_pose_from_relative( coord_prim: pxr.Usd.Prim, relative_translation: ndarray, relative_orientation: ndarray, ) → tuple[ndarray, ndarray]#

Get a pose defined in the world frame from a pose defined relative to the frame of the coord_prim.

Parameters:

coord_prim – Path of the prim whose frame the relative pose is defined with respect to.
relative_translation – Translation relative to the frame of the prim at prim_path. Shape is (3, ).
relative_orientation – Quaternion orientation relative to the frame of the prim at prim_path. Quaternion is scalar-first (w, x, y, z). Shape is (4, ).

Returns:

First index is position in the world frame. Shape is (3, ). Second index is quaternion orientation in the world frame. Quaternion is scalar-first (w, x, y, z). Shape is (4, ).

pose_from_tf_matrix( transformation: ndarray, ) → tuple[ndarray, ndarray]#

Gets pose corresponding to input transformation matrix.

Parameters:: transformation – Column-major transformation matrix. Shape is (4, 4).
Returns:: First index is translation corresponding to transformation. Shape is (3, ). Second index is quaternion orientation corresponding to transformation. Quaternion is scalar-first (w, x, y, z). Shape is (4, ).

tf_matrices_from_poses( translations: ndarray | Tensor, orientations: ndarray | Tensor, ) → ndarray | Tensor#

Compute transformation matrices from translation and orientation arrays.

Parameters:

translations – Translations with shape (N, 3).
orientations – Quaternion orientations in scalar-first order with shape (N, 4).

Returns:

Transformation matrices with shape (N, 4, 4).

tf_matrix_from_pose( translation: Sequence[float], orientation: Sequence[float], ) → ndarray#

Compute input pose to transformation matrix.

Parameters:

translation – The translation vector.
orientation – The orientation quaternion in scalar-first (w, x, y, z) order.

Returns:

A 4x4 matrix.

Types Utils#

Deprecated type definitions for simulation data structures.

Bases: object

Action to apply to an articulation’s joints.

Parameters:

joint_positions – Target joint positions.
joint_velocities – Target joint velocities.
joint_efforts – Target joint efforts (torques/forces).
joint_indices – Joint indices to specify which joints to manipulate.

get_dict() → dict#

Convert the ArticulationAction to a dictionary representation.

Returns:: Dictionary with joint_positions, joint_velocities, and joint_efforts.

get_dof_action(index: int) → dict#

Get the action for a specific degree of freedom (DOF) as a dictionary.

Parameters:: index – Index of the DOF to get the action for.
Returns:: Dictionary containing the position, velocity, or effort for this DOF.

get_length() → int | None#

Get the number of joints this action applies to.

Returns:: The length of the action arrays, or None if all arrays are None.

Bases: object

Actions to apply to multiple articulations’ joints.

Parameters:

joint_positions – Target joint positions.
joint_velocities – Target joint velocities.
joint_efforts – Target joint efforts (torques/forces).
joint_indices – Joint indices to specify which joints to manipulate. Shape (K,). Where K <= number of DOFs.
joint_names – Joint names to specify which joints to manipulate. Cannot be specified together with joint_indices. Shape (K,). Where K <= number of DOFs.

Raises:

Exception – If both joint_names and joint_indices are specified.

class DOFInfo(prim_path: str, handle: int, prim: pxr.Usd.Prim, index: int)#

Bases: object

Information about a degree of freedom in an articulation.

Parameters:

prim_path – The USD prim path for this DOF.
handle – The physics handle for this DOF.
prim – The USD prim object for this DOF.
index – The index of this DOF in the articulation.

class DataFrame(current_time_step: int, current_time: float, data: dict)#

Bases: object

Container for simulation data at a specific time step.

Parameters:

current_time_step – The current simulation time step index.
current_time – The current simulation time in seconds.
data – Dictionary containing the simulation data.

get_dict() → dict#

Convert the DataFrame to a dictionary representation.

Returns:: Dictionary with current_time_step, current_time, and data fields.

classmethod init_from_dict( dict_representation: dict, ) → DataFrame#

Create a DataFrame instance from a dictionary.

Parameters:: dict_representation – Dictionary containing current_time_step, current_time, and data.
Returns:: A new DataFrame instance initialized from the dictionary.

class DynamicState( position: ndarray, orientation: ndarray, linear_velocity: ndarray, angular_velocity: ndarray, )#

Bases: object

State of a dynamic rigid body including pose and velocities.

Parameters:

position – The position as a NumPy array of shape (3,).
orientation – The orientation quaternion (w, x, y, z) as a NumPy array of shape (4,).
linear_velocity – The linear velocity as a NumPy array of shape (3,).
angular_velocity – The angular velocity as a NumPy array of shape (3,).

class DynamicsViewState( positions: ndarray | Tensor, orientations: ndarray | Tensor, linear_velocities: ndarray | Tensor, angular_velocities: ndarray | Tensor, )#

Bases: object

State of multiple dynamic rigid bodies including poses and velocities.

Parameters:

positions – Positions with shape (N, 3).
orientations – Quaternion orientations (scalar first) with shape (N, 4).
linear_velocities – Linear velocities with shape (N, 3).
angular_velocities – Angular velocities with shape (N, 3).

class JointsState( positions: ndarray, velocities: ndarray, efforts: ndarray, )#

Bases: object

State of articulation joints including positions, velocities, and efforts.

Parameters:

positions – Joint positions array.
velocities – Joint velocities array.
efforts – Joint efforts (torques/forces) array.

class XFormPrimState(position: ndarray, orientation: ndarray)#

Bases: object

State of an XFormPrim containing position and orientation.

Parameters:

position – The position as a NumPy array of shape (3,).
orientation – The orientation quaternion (w, x, y, z) as a NumPy array of shape (4,).

class XFormPrimViewState( positions: ndarray | Tensor, orientations: ndarray | Tensor, )#

Bases: object

State of multiple XFormPrims containing positions and orientations.

Parameters:

positions – Positions with shape (N, 3).
orientations – Quaternion orientations (scalar first) with shape (N, 4).

Viewports Utils#

Deprecated viewport utility functions.

add_aov_to_viewport(viewport_api: object, aov_name: str) → bool#

Add an arbitrary output variable (AOV) to the specified viewport for rendering.

Parameters:

viewport_api – Handle to viewport API.
aov_name – Name of the AOV to add to the viewport.

Returns:

True if successful.

Raises:

RuntimeError – If the render product is invalid or render variable cannot be created.

backproject_depth( depth_image: array, viewport_api: Any, max_clip_depth: float, ) → array#

Backproject depth image to image space.

Parameters:

depth_image – Depth image buffer.
viewport_api – Handle to viewport API.
max_clip_depth – Depth values larger than this will be clipped.

Returns:

3D point cloud with shape (height * width, 3) in camera space.

create_viewport_for_camera( viewport_name: str, camera_prim_path: str, width: int = 1280, height: int = 720, position_x: int = 0, position_y: int = 0, ) → object#

Create a new viewport and peg it to a specific camera specified by camera_prim_path.

If a viewport exists with viewport_name, it is replaced with the new camera view.

Parameters:

viewport_name – Name of the viewport.
camera_prim_path – Prim path of the camera.
width – Width of the viewport window, in pixels.
height – Height of the viewport window, in pixels.
position_x – X location of the viewport window.
position_y – Y location of the viewport window.

Returns:

The created viewport window.

Raises:

ValueError – If the provided camera_prim_path is an invalid prim in the scene.

destroy_all_viewports( usd_context_name: str = None, destroy_main_viewport: bool = True, ) → None#

Destroy all viewport windows.

Parameters:

usd_context_name – USD context to use.
destroy_main_viewport – Whether to destroy the default viewport.

get_id_from_index(index: int) → int | None#

Get the viewport id for a given index.

This function was added for backwards compatibility for VP2 because viewport IDs are not the same as the viewport index.

Parameters:: index – Viewport index to retrieve ID for.
Returns:: The viewport id, or None if the window index was not found.

get_intrinsics_matrix(viewport_api: Any) → ndarray#

Get intrinsic matrix for the camera attached to a specific viewport.

Parameters:: viewport_api – Handle to viewport API.
Returns:: The intrinsic matrix associated with the specified viewport. The image convention assumes +x points to the right in the image and +y points down in the image.

get_viewport_names(usd_context_name: str = None) → list[str]#

Get list of all viewport names.

Parameters:: usd_context_name – USD context to use.
Returns:: Viewport names.

get_window_from_id( id: object, usd_context_name: str = None, ) → object | None#

Find window that matches a given viewport id.

Parameters:

id – Viewport ID to get window for.
usd_context_name – USD context to use.

Returns:

The matching window, or None if a window with the matching ID was not found.

project_depth_to_worldspace( depth_image: array, viewport_api: Any, max_clip_depth: float, ) → list[carb.Float3]#

Project depth image to world space.

Parameters:

depth_image – Depth image buffer.
viewport_api – Handle to viewport API.
max_clip_depth – Depth values larger than this will be clipped.

Returns:

Points from depth in world space.

set_active_viewport_camera(camera_prim_path: str) → None#

Set the camera for the active viewport.

This method sets the active viewport to display the camera at the specified prim path.

Parameters:: camera_prim_path – Prim path of the camera.

set_camera_view( eye: array, target: array, camera_prim_path: str = '/OmniverseKit_Persp', viewport_api: object = None, ) → None#

Set the location and target for a camera prim in the stage given its path.

Parameters:

eye – Location of camera.
target – Location of camera target.
camera_prim_path – Path to camera prim being set.
viewport_api – Viewport API instance. If None, uses the active viewport.

set_intrinsics_matrix( viewport_api: Any, intrinsics_matrix: ndarray, focal_length: float = 1.0, ) → None#

Set intrinsic matrix for the camera attached to a specific viewport.

Note

We assume cx and cy are centered in the camera. horizontal_aperture_offset and vertical_aperture_offset are computed and set on the camera prim but are not used.

Parameters:

viewport_api – Handle to viewport api.
intrinsics_matrix – A 3x3 intrinsic matrix.
focal_length – Focal length to use when computing aperture values.

Raises:

ValueError – If intrinsic matrix is not a 3x3 matrix.
ValueError – If camera prim is not valid.

XForms Utils#

Deprecated xform operation utility functions.

clear_xform_ops(prim: pxr.Usd.Prim) → None#

Remove all xform ops from input prim.

Parameters:: prim – The input USD prim.

get_local_pose(prim_path: str) → tuple#

Get the local pose of a prim relative to its parent.

Parameters:: prim_path – Path to the prim.
Returns:: A tuple containing the local translation as numpy array and orientation as quaternion in w,x,y,z format.
Raises:: Exception – If the prim path is not valid.

get_world_pose(prim_path: str, fabric: bool = False) → tuple#

Get the world pose of a prim.

Parameters:

prim_path – Path to the prim.
fabric – Whether to use fabric API for retrieving the pose.

Returns:

A tuple containing the world translation as numpy array and orientation as quaternion in w,x,y,z format.

Raises:

Exception – If the prim path is not valid.

reset_and_set_xform_ops( prim: pxr.Usd.Prim, translation: pxr.Gf.Vec3d, orientation: pxr.Gf.Quatd, scale: pxr.Gf.Vec3d = pxr.Gf.Vec3d, ) → None#

Reset xform ops to Isaac Sim defaults and set their values.

Parameters:

prim – Prim to reset.
translation – Translation to set.
orientation – Orientation to set.
scale – Scale to set.

reset_xform_ops(prim: pxr.Usd.Prim) → None#

Reset xform ops for a prim to Isaac Sim defaults while preserving its local pose.

Parameters:: prim – Prim to reset xform ops on.

NumPy Utils#

Rotations#

Provides NumPy-based functions for 3D rotation conversions between quaternions, Euler angles, rotation matrices, and rotation vectors.

deg2rad( degree_value: ndarray, device: object = None, ) → ndarray#

Converts angles from degrees to radians.

Parameters:

degree_value – Angle values in degrees.
device – Device parameter, unused and maintained for compatibility.

Returns:

Angle values converted to radians.

euler_angles_to_quats( euler_angles: ndarray, degrees: bool = False, extrinsic: bool = True, device: object = None, ) → ndarray#

Vectorized version of converting euler angles to quaternion, scalar first.

Parameters:

euler_angles – euler angles with shape (N, 3) or (3,) representation XYZ in extrinsic coordinates.
degrees – True if degrees, False if radians.
extrinsic – True if the euler angles follows the extrinsic angles convention, equivalent to ZYX ordering but returned in the reverse, and False if it follows the intrinsic angles conventions, equivalent to XYZ ordering.
device – Device parameter, unused and maintained for compatibility.

Returns:

quaternions representation of the angles (N, 4) or (4,), scalar first.

gf_quat_to_tensor( orientation: Gf.Quatd | Gf.Quatf | Gf.Quaternion, device: object = None, ) → np.ndarray#

Converts a pxr Quaternion type to a numpy array following [w, x, y, z] convention.

Parameters:

orientation – Input quaternion from USD.
device – Device parameter, unused and maintained for compatibility.

Returns:

Quaternion as numpy array in [w, x, y, z] format.

quats_to_euler_angles( quaternions: ndarray, degrees: bool = False, extrinsic: bool = True, device: object = None, ) → ndarray#

Vectorized version of converting quaternions, scalar first, to euler angles.

Parameters:

quaternions – quaternions with shape (N, 4) or (4,), scalar first.
degrees – Return euler angles in degrees if True, radians if False.
extrinsic – True if the euler angles follows the extrinsic angles convention, equivalent to ZYX ordering but returned in the reverse, and False if it follows the intrinsic angles conventions, equivalent to XYZ ordering.
device – Device parameter, unused and maintained for compatibility.

Returns:

Euler angles in extrinsic or intrinsic coordinates XYZ order with shape (N, 3) or (3,) corresponding to the quaternion rotations.

quats_to_rot_matrices( quaternions: ndarray, device: object = None, ) → ndarray#

Vectorized version of converting quaternions to rotation matrices.

Parameters:

quaternions – quaternions with shape (N, 4) or (4,) and scalar first.
device – Device parameter, unused and maintained for compatibility.

Returns:

N Rotation matrices with shape (N, 3, 3) or (3, 3).

quats_to_rotvecs( quaternions: ndarray, device: object = None, ) → ndarray#

Vectorized version of converting quaternions to rotation vectors.

Parameters:

quaternions – quaternions with shape (N, 4) or (4,) and scalar first.
device – Device parameter, unused and maintained for compatibility.

Returns:

N rotation vectors with shape (N,3) or (3,). The magnitude of the rotation vector describes the magnitude of the rotation. The normalized rotation vector represents the axis of rotation.

rad2deg( radian_value: ndarray, device: object = None, ) → ndarray#

Converts angles from radians to degrees.

Parameters:

radian_value – Angle values in radians.
device – Device parameter, unused and maintained for compatibility.

Returns:

Angle values converted to degrees.

rot_matrices_to_quats( rotation_matrices: ndarray, device: object = None, ) → ndarray#

Vectorized version of converting rotation matrices to quaternions.

Parameters:

rotation_matrices – N Rotation matrices with shape (N, 3, 3) or (3, 3).
device – Device parameter, unused and maintained for compatibility.

Returns:

quaternion representation of the rotation matrices (N, 4) or (4,), scalar first.

rotvecs_to_quats( rotation_vectors: ndarray, degrees: bool = False, device: object = None, ) → ndarray#

Vectorized version of converting rotation vectors to quaternions.

Parameters:

rotation_vectors – N rotation vectors with shape (N, 3) or (3,). The magnitude of the rotation vector describes the magnitude of the rotation. The normalized rotation vector represents the axis of rotation.
degrees – The magnitude of the rotation vector will be interpreted as degrees if True, and radians if False.
device – Device parameter, unused and maintained for compatibility.

Returns:

quaternion representation of the rotation matrices (N, 4) or (4,), scalar first.

wxyz2xyzw( q: ndarray, ret_torch: bool = False, ) → ndarray#

Converts quaternion from WXYZ order to XYZW order.

Parameters:

q – Quaternion in WXYZ order.
ret_torch – Return format parameter, unused and maintained for compatibility.

Returns:

Quaternion in XYZW order.

xyzw2wxyz( q: ndarray, ret_torch: bool = False, ) → ndarray#

Converts quaternion from XYZW format to WXYZ format.

Parameters:

q – Quaternion array in XYZW format (x, y, z, w).
ret_torch – Currently unused parameter for potential torch tensor output.

Returns:

Quaternion array in WXYZ format (w, x, y, z).

Maths#

Mathematical utility functions for matrix operations and trigonometric computations.

cos(data: ndarray) → ndarray#

Compute the cosine of the input data.

Parameters:: data – Input array or scalar value.
Returns:: The cosine values of the input data.

inverse(data: ndarray) → ndarray#

Compute the matrix inverse of the input data.

Parameters:: data – Input matrix to invert.
Returns:: The inverse of the input matrix.

matmul( matrix_a: ndarray, matrix_b: ndarray, ) → ndarray#

Perform matrix multiplication between two matrices.

Parameters:

matrix_a – First input matrix.
matrix_b – Second input matrix.

Returns:

The result of matrix multiplication.

sin(data: ndarray) → ndarray#

Compute the sine of the input data.

Parameters:: data – Input array or scalar value.
Returns:: The sine values of the input data.

transpose_2d(data: ndarray) → ndarray#

Transpose the input 2D array.

Parameters:: data – Input 2D array to transpose.
Raises:: ValueError – If input array has more than 2 dimensions.
Returns:: The transposed array.

Tensor#

NumPy-based tensor operations and data manipulation utilities for Isaac Sim.

as_type(data: ndarray, dtype: str) → ndarray | None#

Convert data to the specified data type.

Parameters:

data – The input data to convert.
dtype – Target data type (“float32”, “bool”, “int32”, “int64”, “long”, “uint8”).

Returns:

The data converted to the specified type, or None if the type is not supported.

assign( src: ndarray, dst: ndarray, indices: object, ) → ndarray#

Assign source data to destination array at specified indices.

Parameters:

src – Source data to assign.
dst – Destination array to modify.
indices – Indices where to assign the source data.

Returns:

The modified destination array.

clone_tensor( data: ndarray, device: object = None, ) → ndarray#

Create a copy of the input data.

Parameters:

data – The data to clone.
device – Device parameter not used in the NumPy implementation.

Returns:

A copy of the input data.

convert( data: object, device: object = None, dtype: str = 'float32', indexed: object = None, ) → ndarray | None#

Convert data to a NumPy array with specified data type.

Parameters:

data – Input data to convert.
device – Device parameter not used in the NumPy implementation.
dtype – Target data type for conversion.
indexed – Indexing parameter not used in current implementation.

Returns:

The converted NumPy array with the specified data type, or None if the type is not supported.

create_tensor_from_list( data: list, dtype: str, device: object = None, ) → ndarray | None#

Create a tensor from a list with specified data type.

Parameters:

data – List data to convert to tensor.
dtype – Target data type for the tensor.
device – Device parameter not used in the NumPy implementation.

Returns:

A tensor created from the list with the specified data type, or None if the type is not supported.

create_zeros_tensor( shape: object, dtype: str, device: object = None, ) → ndarray | None#

Create a tensor of zeros with specified shape and data type.

Parameters:

shape – Shape of the tensor to create.
dtype – Data type for the tensor elements.
device – Device parameter not used in the NumPy implementation.

Returns:

A tensor filled with zeros of the specified shape and data type, or None if the type is not supported.

expand_dims(data: ndarray, axis: int) → ndarray#

Expand the dimensions of the data array.

Parameters:

data – Input data array.
axis – Axis along which to expand dimensions.

Returns:

Array with expanded dimensions.

move_data( data: ndarray, device: object = None, ) → ndarray#

Move data to the specified device.

Parameters:

data – Data to move.
device – Target device not used in the NumPy implementation.

Returns:

The input data unchanged.

pad( data: ndarray, pad_width: object, mode: str = 'constant', value: object = None, ) → ndarray#

Pad an array with specified padding mode and values.

Parameters:

data – Input array to pad.
pad_width – Number of values padded to the edges of each axis.
mode – Padding mode (“constant”, “linear_ramp”, etc.).
value – Values to use for padding depending on the mode.

Returns:

Padded array.

resolve_indices( indices: object, count: int, device: object = None, ) → ndarray#

Resolve indices into a NumPy array format.

Parameters:

indices – Input indices as list, array, or None.
count – Total count for generating indices when indices is None.
device – Device parameter not used in the NumPy implementation.

Returns:

Resolved indices as a NumPy array.

tensor_cat( data: list, device: object = None, dim: int = -1, ) → ndarray#

Concatenate tensors along a specified dimension.

Parameters:

data – List of NumPy arrays to concatenate.
device – Device parameter ignored by the NumPy implementation.
dim – Dimension along which to concatenate the arrays.

Returns:

The concatenated NumPy array.

tensor_stack(data: list, dim: int = 0) → ndarray#

Stack tensors along a new dimension.

Parameters:

data – List of NumPy arrays to stack.
dim – Dimension along which to stack the arrays.

Returns:

The stacked NumPy array.

to_list(data: object) → list#

Convert NumPy array data to list format.

Parameters:: data – Data to convert to list. If already a list, returns unchanged.
Returns:: List representation of the input data.

to_numpy(data: ndarray) → ndarray#

Convert data to NumPy array format.

Parameters:: data – Data to convert to NumPy format.
Returns:: The input data unchanged.

Transformations#

Utilities for 3D transformation operations including coordinate frame conversions and pose manipulations using NumPy arrays.

assign_pose( current_positions: ndarray, current_orientations: ndarray, positions: object, orientations: object, indices: object, device: object = None, pose: object = None, ) → ndarray#

Update pose arrays by assigning new positions and orientations at specified indices.

Parameters:

current_positions – Current position array with shape (N, 3).
current_orientations – Current orientation array with shape (N, 4).
positions – New positions to assign. If None, uses current positions at indices.
orientations – New orientations to assign. If None, uses current orientations at indices.
indices – Indices where new poses should be assigned.
device – Unused device parameter.
pose – Unused pose parameter.

Returns:

Updated pose array with new positions and orientations assigned at specified indices.

get_local_from_world( parent_transforms: ndarray, positions: ndarray, orientations: ndarray, device: object = None, ) → tuple#

Convert world space poses to local space relative to parent transformations.

Parameters:

parent_transforms – Parent transformation matrices.
positions – World space positions with shape (N, 3).
orientations – World space quaternion orientations with shape (N, 4).
device – Device for creating the output tensors.

Returns:

The local translations and local orientations in the parent coordinate frame.

get_pose( positions: ndarray, orientations: ndarray, device: object = None, ) → ndarray#

Concatenate position and orientation arrays into a single pose array.

Parameters:

positions – Position array with shape (N, 3).
orientations – Orientation array with shape (N, 4).
device – Unused device parameter.

Returns:

Combined pose array with shape (N, 7) containing positions and orientations.

get_world_from_local( parent_transforms: ndarray, translations: ndarray, orientations: ndarray, device: object = None, ) → tuple#

Convert local space poses to world space using parent transformations.

Parameters:

parent_transforms – Parent transformation matrices.
translations – Local space translations with shape (N, 3).
orientations – Local space quaternion orientations with shape (N, 4).
device – Device for creating the output tensors.

Returns:

The world positions and world orientations in the world coordinate frame.

tf_matrices_from_poses( translations: ndarray, orientations: ndarray, device: object = None, ) → ndarray#

Compute transformation matrices from translation and orientation arrays.

Parameters:

translations – Translations with shape (N, 3).
orientations – Quaternion orientations (scalar first) with shape (N, 4).
device – Unused device parameter.

Returns:

Transformation matrices with shape (N, 4, 4).

Torch Utils#

Rotations#

Provides PyTorch-based utilities for 3D rotations, quaternions, and coordinate transformations.

deg2rad(degree_value: float, device: object = None) → Tensor#

Converts degrees to radians.

Parameters:

degree_value – Angle value in degrees.
device – Device to place the tensor on.

Returns:

Angle value in radians.

euler_angles_to_quats( euler_angles: Tensor, degrees: bool = False, extrinsic: bool = True, device: object = None, ) → Tensor#

Converts Euler angles to quaternions in scalar-first format.

Parameters:

euler_angles – Euler angles with shape (N, 3).
degrees – Whether the Euler angles are in degrees instead of radians.
extrinsic – Whether the Euler angles follow the extrinsic angles convention, equivalent to ZYX ordering but returned in reverse. If False, uses intrinsic angles convention, equivalent to XYZ ordering.
device – Device to place the tensor on.

Returns:

Quaternion representation of the angles with shape (N, 4) in scalar-first format.

gf_quat_to_tensor( orientation: Gf.Quatd | Gf.Quatf | Gf.Quaternion, device: object = None, ) → torch.Tensor#

Converts a pxr Quaternion type to a torch tensor in scalar-first format.

Parameters:

orientation – Input quaternion from USD.
device – Device to place the tensor on.

Returns:

Quaternion as torch tensor in [w, x, y, z] format.

normalise_quat_in_pose(pose: object) → object#

Normalises the quaternion portion of a pose.

Parameters:: pose – Pose with shape N, 7.
Returns:: Pose with normalised quaternion and shape N, 7.

rad2deg( radian_value: Tensor, device: object = None, ) → Tensor#

Converts radians to degrees.

Parameters:

radian_value – Angle value in radians.
device – Device to place the tensor on.

Returns:

Angle value in degrees.

rot_matrices_to_quats( rotation_matrices: Tensor, device: object = None, ) → Tensor#

Converts rotation matrices to quaternions in scalar-first format.

Parameters:

rotation_matrices – Rotation matrices with shape (N, 3, 3) or (3, 3).
device – Device to place the tensor on.

Returns:

Quaternion representation of the rotation matrices with shape (N, 4) or (4,) in scalar-first format.

wxyz2xyzw(q: object) → object#

Converts a quaternion from [w, x, y, z] to [x, y, z, w] format.

Parameters:: q – Quaternion tensor in [w, x, y, z] format.
Returns:: Quaternion tensor in [x, y, z, w] format.

xyzw2wxyz(q: object) → object#

Converts a quaternion from [x, y, z, w] to [w, x, y, z] format.

Parameters:: q – Quaternion tensor in [x, y, z, w] format.
Returns:: Quaternion tensor in [w, x, y, z] format.

Maths#

Utility functions for mathematical operations and tensor manipulations using PyTorch.

cos(data: object) → object#

Computes the cosine of the input tensor.

Parameters:: data – Input tensor.
Returns:: Tensor with cosine values computed element-wise.

inverse(data: object) → object#

Computes the matrix inverse of the input tensor.

Parameters:: data – Input tensor representing matrices to invert.
Returns:: Tensor containing the matrix inverses.

matmul(matrix_a: object, matrix_b: object) → object#

Performs matrix multiplication between two tensors.

Parameters:

matrix_a – First input matrix.
matrix_b – Second input matrix.

Returns:

Result of matrix multiplication.

set_seed(seed: int, torch_deterministic: bool = False) → int#

Sets seeds across modules.

Sets random seeds for Python, NumPy, PyTorch, Warp, and environment variables to ensure reproducibility across different libraries. Optionally enables deterministic algorithms for PyTorch operations.

Parameters:

seed – Random seed value. If -1, generates a random seed or uses 42 if torch_deterministic is True.
torch_deterministic – Whether to enable deterministic algorithms in PyTorch.

Returns:

The actual seed value that was set.

sin(data: object) → object#

Computes the sine of the input tensor.

Parameters:: data – Input tensor.
Returns:: Tensor with sine values computed element-wise.

transpose_2d(data: object) → object#

Transposes a 1D or 2D tensor by swapping dimensions 0 and 1.

Parameters:: data – Input 1D or 2D tensor to transpose.
Raises:: ValueError – If input tensor has more than 2 dimensions.
Returns:: Transposed tensor with dimensions swapped.

unscale_np( x: ndarray, lower: ndarray, upper: ndarray, ) → ndarray#

Scales values from [lower, upper] range to [-1, 1] range using NumPy operations.

Parameters:

x – Input values to scale.
lower – Lower bound of the source range.
upper – Upper bound of the source range.

Returns:

Values scaled to [-1, 1] range.

Tensor#

Utility functions for PyTorch tensor operations, data type conversion, and device management.

as_type(data: object, dtype: str) → Any#

Convert tensor data to the specified data type.

Parameters:

data – The tensor data to convert.
dtype – Target data type string (“float32”, “bool”, “int32”, “int64”, “long”, “uint8”).

Returns:

The tensor converted to the specified data type, or None if the data type is not supported.

assign(src: object, dst: object, indices: object) → Any#

Assign source values to destination tensor at specified indices.

Parameters:

src – Source values to assign.
dst – Destination tensor to modify.
indices – Indices where to assign the values. Can be a list of coordinates or tensor indices.

Returns:

The modified destination tensor.

clone_tensor(data: object, device: object) → Any#

Clone tensor data to the specified device.

Parameters:

data – The tensor data to clone.
device – Target device for the cloned tensor.

Returns:

A cloned copy of the tensor on the specified device.

convert( data: object, device: object, dtype: str = 'float32', indexed: object = None, ) → Any#

Convert data to tensor format with specified device and data type.

Parameters:

data – Input data to convert. Can be tensor or array-like data.
device – Target device for the tensor.
dtype – Target data type for the tensor.
indexed – Additional indexing parameter (currently unused).

Returns:

The converted tensor on the specified device with the specified data type.

create_tensor_from_list( data: list, dtype: str, device: object = None, ) → Any#

Create a tensor from list data with specified data type and device.

Parameters:

data – List data to convert to tensor.
dtype – Target data type for the tensor.
device – Target device for the tensor.

Returns:

A tensor created from the list data with the specified data type and device.

create_zeros_tensor( shape: object, dtype: str, device: object = None, ) → Any#

Create a tensor filled with zeros of the specified shape and data type.

Parameters:

shape – Shape of the tensor to create.
dtype – Data type for the tensor elements.
device – Target device for the tensor.

Returns:

A zero-filled tensor with the specified shape, data type, and device.

expand_dims(data: object, axis: int) → Any#

Add a new dimension to the tensor at the specified axis.

Parameters:

data – Input tensor data.
axis – Axis position where to insert the new dimension.

Returns:

The tensor with an additional dimension at the specified axis.

move_data(data: object, device: object) → Any#

Move tensor data to the specified device.

Parameters:

data – The tensor data to move.
device – Target device for the tensor.

Returns:

The tensor moved to the specified device.

pad( data: object, pad_width: object, mode: str = 'constant', value: object = None, ) → Any#

Add padding to tensor data.

Parameters:

data – Input tensor data to pad.
pad_width – Padding specification. Can be a tuple or list of tuples specifying padding for each dimension.
mode – Padding mode to use.
value – Fill value for constant padding mode.

Returns:

The padded tensor.

resolve_indices( indices: object, count: int, device: object, ) → Any#

Resolve and convert indices to a proper tensor format.

Parameters:

indices – Input indices. Can be a list, tensor, or None. If None, creates a range from 0 to count - 1.
count – Total count for creating default indices when indices is None.
device – Target device for the indices tensor.

Returns:

A long tensor containing the resolved indices on the specified device.

tensor_cat( data: object, device: object = None, dim: int = -1, ) → Any#

Concatenates tensors along a specified dimension.

Parameters:

data – Sequence of tensors to concatenate.
device – Unused device argument.
dim – Dimension along which to concatenate tensors.

Returns:

Concatenated tensor.

tensor_stack(data: object, dim: int = 0) → Any#

Stacks tensors along a new dimension.

Parameters:

data – Sequence of tensors to stack.
dim – Dimension along which to stack tensors.

Returns:

Stacked tensor.

to_list(data: object) → list#

Converts tensor data to a Python list.

Parameters:: data – Data to convert. If already a list, returns as-is.
Returns:: Python list representation of the data.

to_numpy(data: object) → Any#

Converts tensor data to a NumPy array.

Parameters:: data – Data to convert. If not a tensor, returns as-is.
Returns:: NumPy array representation of the data.

Transformations#

Tensor-based transformation utilities for 3D poses, coordinate frame conversions, and spatial operations.

assign_pose( current_positions: object, current_orientations: object, positions: object, orientations: object, indices: object, device: object, pose: object = None, ) → object#

Assigns new pose values to specific indices in current pose arrays.

Parameters:

current_positions – Current position values for all objects.
current_orientations – Current orientation values for all objects.
positions – New position values to assign. If None, uses current positions at indices.
orientations – New orientation values to assign. If None, uses current orientations at indices.
indices – Array indices where new pose values should be assigned.
device – Device for tensor operations.
pose – Unused parameter for compatibility.

Returns:

Updated pose array with new values assigned at specified indices.

get_local_from_world( parent_transforms: object, positions: object, orientations: object, device: object, ) → tuple#

Converts world-space positions and orientations to local-space relative to parent transforms.

Parameters:

parent_transforms – Transformation matrices of parent objects.
positions – World-space positions to convert.
orientations – World-space orientations to convert.
device – Device for tensor operations.

Returns:

Tuple of (local_translations, local_orientations) in parent coordinate frames.

get_pose( positions: object, orientations: object, device: object, ) → object#

Combines position and orientation arrays into a single pose tensor.

Parameters:

positions – Position values (shape N, 3).
orientations – Orientation quaternions (shape N, 4).
device – Device for tensor operations.

Returns:

Combined pose tensor with shape (N, 7) containing positions and orientations.

get_world_from_local( parent_transforms: object, translations: object, orientations: object, device: object, ) → tuple#

Converts local-space translations and orientations to world-space using parent transforms.

Parameters:

parent_transforms – Transformation matrices of parent objects.
translations – Local-space translations to convert.
orientations – Local-space orientations to convert.
device – Device for tensor operations.

Returns:

Tuple of (world_positions, world_orientations) in global coordinate frame.

normalise_quat_in_pose(pose: object) → object#

Takes a pose and normalises the quaternion portion of it.

Parameters:: pose – Pose with shape N, 7.
Returns:: Pose with normalised quat and shape N, 7.

tf_matrices_from_poses( translations: Tensor, orientations: Tensor, device: object = None, ) → Tensor#

Compute transformation matrices from translation and orientation tensors.

Parameters:

translations – Translations with shape (N, 3).
orientations – Quaternion orientations (scalar first) with shape (N, 4).
device – Device for tensor operations.

Returns:

Transformation matrices with shape (N, 4, 4).

Warp Utils#

Rotations#

Provides PyTorch-based utilities for 3D rotations, quaternions, and coordinate transformations.

deg2rad(degree_value: float, device: object = None) → Tensor#

Converts degrees to radians.

Parameters:

degree_value – Angle value in degrees.
device – Device to place the tensor on.

Returns:

Angle value in radians.

euler_angles_to_quats( euler_angles: Tensor, degrees: bool = False, extrinsic: bool = True, device: object = None, ) → Tensor#

Converts Euler angles to quaternions in scalar-first format.

Parameters:

euler_angles – Euler angles with shape (N, 3).
degrees – Whether the Euler angles are in degrees instead of radians.
extrinsic – Whether the Euler angles follow the extrinsic angles convention, equivalent to ZYX ordering but returned in reverse. If False, uses intrinsic angles convention, equivalent to XYZ ordering.
device – Device to place the tensor on.

Returns:

Quaternion representation of the angles with shape (N, 4) in scalar-first format.

gf_quat_to_tensor( orientation: Gf.Quatd | Gf.Quatf | Gf.Quaternion, device: object = None, ) → torch.Tensor#

Converts a pxr Quaternion type to a torch tensor in scalar-first format.

Parameters:

orientation – Input quaternion from USD.
device – Device to place the tensor on.

Returns:

Quaternion as torch tensor in [w, x, y, z] format.

normalise_quat_in_pose(pose: object) → object#

Normalises the quaternion portion of a pose.

Parameters:: pose – Pose with shape N, 7.
Returns:: Pose with normalised quaternion and shape N, 7.

rad2deg( radian_value: Tensor, device: object = None, ) → Tensor#

Converts radians to degrees.

Parameters:

radian_value – Angle value in radians.
device – Device to place the tensor on.

Returns:

Angle value in degrees.

rot_matrices_to_quats( rotation_matrices: Tensor, device: object = None, ) → Tensor#

Converts rotation matrices to quaternions in scalar-first format.

Parameters:

rotation_matrices – Rotation matrices with shape (N, 3, 3) or (3, 3).
device – Device to place the tensor on.

Returns:

Quaternion representation of the rotation matrices with shape (N, 4) or (4,) in scalar-first format.

wxyz2xyzw(q: object) → object#

Converts a quaternion from [w, x, y, z] to [x, y, z, w] format.

Parameters:: q – Quaternion tensor in [w, x, y, z] format.
Returns:: Quaternion tensor in [x, y, z, w] format.

xyzw2wxyz(q: object) → object#

Converts a quaternion from [x, y, z, w] to [w, x, y, z] format.

Parameters:: q – Quaternion tensor in [x, y, z, w] format.
Returns:: Quaternion tensor in [w, x, y, z] format.

Tensor#

Utility functions for PyTorch tensor operations, data type conversion, and device management.

as_type(data: object, dtype: str) → Any#

Convert tensor data to the specified data type.

Parameters:

data – The tensor data to convert.
dtype – Target data type string (“float32”, “bool”, “int32”, “int64”, “long”, “uint8”).

Returns:

The tensor converted to the specified data type, or None if the data type is not supported.

assign(src: object, dst: object, indices: object) → Any#

Assign source values to destination tensor at specified indices.

Parameters:

src – Source values to assign.
dst – Destination tensor to modify.
indices – Indices where to assign the values. Can be a list of coordinates or tensor indices.

Returns:

The modified destination tensor.

clone_tensor(data: object, device: object) → Any#

Clone tensor data to the specified device.

Parameters:

data – The tensor data to clone.
device – Target device for the cloned tensor.

Returns:

A cloned copy of the tensor on the specified device.

convert( data: object, device: object, dtype: str = 'float32', indexed: object = None, ) → Any#

Convert data to tensor format with specified device and data type.

Parameters:

data – Input data to convert. Can be tensor or array-like data.
device – Target device for the tensor.
dtype – Target data type for the tensor.
indexed – Additional indexing parameter (currently unused).

Returns:

The converted tensor on the specified device with the specified data type.

create_tensor_from_list( data: list, dtype: str, device: object = None, ) → Any#

Create a tensor from list data with specified data type and device.

Parameters:

data – List data to convert to tensor.
dtype – Target data type for the tensor.
device – Target device for the tensor.

Returns:

A tensor created from the list data with the specified data type and device.

create_zeros_tensor( shape: object, dtype: str, device: object = None, ) → Any#

Create a tensor filled with zeros of the specified shape and data type.

Parameters:

shape – Shape of the tensor to create.
dtype – Data type for the tensor elements.
device – Target device for the tensor.

Returns:

A zero-filled tensor with the specified shape, data type, and device.

expand_dims(data: object, axis: int) → Any#

Add a new dimension to the tensor at the specified axis.

Parameters:

data – Input tensor data.
axis – Axis position where to insert the new dimension.

Returns:

The tensor with an additional dimension at the specified axis.

move_data(data: object, device: object) → Any#

Move tensor data to the specified device.

Parameters:

data – The tensor data to move.
device – Target device for the tensor.

Returns:

The tensor moved to the specified device.

pad( data: object, pad_width: object, mode: str = 'constant', value: object = None, ) → Any#

Add padding to tensor data.

Parameters:

data – Input tensor data to pad.
pad_width – Padding specification. Can be a tuple or list of tuples specifying padding for each dimension.
mode – Padding mode to use.
value – Fill value for constant padding mode.

Returns:

The padded tensor.

resolve_indices( indices: object, count: int, device: object, ) → Any#

Resolve and convert indices to a proper tensor format.

Parameters:

indices – Input indices. Can be a list, tensor, or None. If None, creates a range from 0 to count - 1.
count – Total count for creating default indices when indices is None.
device – Target device for the indices tensor.

Returns:

A long tensor containing the resolved indices on the specified device.

tensor_cat( data: object, device: object = None, dim: int = -1, ) → Any#

Concatenates tensors along a specified dimension.

Parameters:

data – Sequence of tensors to concatenate.
device – Unused device argument.
dim – Dimension along which to concatenate tensors.

Returns:

Concatenated tensor.

tensor_stack(data: object, dim: int = 0) → Any#

Stacks tensors along a new dimension.

Parameters:

data – Sequence of tensors to stack.
dim – Dimension along which to stack tensors.

Returns:

Stacked tensor.

to_list(data: object) → list#

Converts tensor data to a Python list.

Parameters:: data – Data to convert. If already a list, returns as-is.
Returns:: Python list representation of the data.

to_numpy(data: object) → Any#

Converts tensor data to a NumPy array.

Parameters:: data – Data to convert. If not a tensor, returns as-is.
Returns:: NumPy array representation of the data.

Transformations#

Tensor-based transformation utilities for 3D poses, coordinate frame conversions, and spatial operations.

assign_pose( current_positions: object, current_orientations: object, positions: object, orientations: object, indices: object, device: object, pose: object = None, ) → object#

Assigns new pose values to specific indices in current pose arrays.

Parameters:

current_positions – Current position values for all objects.
current_orientations – Current orientation values for all objects.
positions – New position values to assign. If None, uses current positions at indices.
orientations – New orientation values to assign. If None, uses current orientations at indices.
indices – Array indices where new pose values should be assigned.
device – Device for tensor operations.
pose – Unused parameter for compatibility.

Returns:

Updated pose array with new values assigned at specified indices.

get_local_from_world( parent_transforms: object, positions: object, orientations: object, device: object, ) → tuple#

Converts world-space positions and orientations to local-space relative to parent transforms.

Parameters:

parent_transforms – Transformation matrices of parent objects.
positions – World-space positions to convert.
orientations – World-space orientations to convert.
device – Device for tensor operations.

Returns:

Tuple of (local_translations, local_orientations) in parent coordinate frames.

get_pose( positions: object, orientations: object, device: object, ) → object#

Combines position and orientation arrays into a single pose tensor.

Parameters:

positions – Position values (shape N, 3).
orientations – Orientation quaternions (shape N, 4).
device – Device for tensor operations.

Returns:

Combined pose tensor with shape (N, 7) containing positions and orientations.

get_world_from_local( parent_transforms: object, translations: object, orientations: object, device: object, ) → tuple#

Converts local-space translations and orientations to world-space using parent transforms.

Parameters:

parent_transforms – Transformation matrices of parent objects.
translations – Local-space translations to convert.
orientations – Local-space orientations to convert.
device – Device for tensor operations.

Returns:

Tuple of (world_positions, world_orientations) in global coordinate frame.

normalise_quat_in_pose(pose: object) → object#

Takes a pose and normalises the quaternion portion of it.

Parameters:: pose – Pose with shape N, 7.
Returns:: Pose with normalised quat and shape N, 7.

tf_matrices_from_poses( translations: Tensor, orientations: Tensor, device: object = None, ) → Tensor#

Compute transformation matrices from translation and orientation tensors.

Parameters:

translations – Translations with shape (N, 3).
orientations – Quaternion orientations (scalar first) with shape (N, 4).
device – Device for tensor operations.

Returns:

Transformation matrices with shape (N, 4, 4).