[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.6

Overview#

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

The isaacsim.core.utils extension provides a comprehensive set of utility functions for working with USD stages, physics simulation, mathematics, and rendering operations within Isaac Sim. This extension serves as a foundational toolkit that simplifies common development tasks through high-level APIs for stage manipulation, geometry processing, coordinate transformations, and data interchange between different computational frameworks.

Functionality#

USD Stage Management#

The extension provides comprehensive stage operations including creating, opening, saving, and manipulating USD stages. Users can traverse stage hierarchies, manage prim lifecycles, and handle references and payloads. Stage utilities support both synchronous and asynchronous operations for file I/O and stage updates.

Prim Operations and Manipulation#

Extensive prim utilities enable creating, querying, and modifying USD prims with support for attributes, properties, and metadata. The extension handles prim hierarchies, parent-child relationships, and provides advanced search capabilities using regex patterns and predicate functions.

Physics Integration#

Physics utilities facilitate rigid body management, simulation control, and raycasting operations. The extension integrates with Omni Physics to provide seamless physics-enabled prim manipulation and simulation stepping with configurable timing and callback support.

Mathematical Operations#

Comprehensive mathematical utilities support coordinate transformations, quaternion operations, rotation matrix conversions, and pose calculations. The extension provides both single-value and vectorized operations for efficient batch processing of geometric data.

Multi-Framework Data Interchange#

The extension includes comprehensive interoperability utilities for converting data between NumPy, PyTorch, JAX, TensorFlow, and Warp arrays. This enables seamless integration across different computational frameworks commonly used in robotics and simulation workflows.

Rendering and Viewport Control#

Rendering utilities provide viewport management, camera control, and render product configuration. Users can create custom viewports, manipulate camera transforms, configure AOVs (Arbitrary Output Variables), and manage intrinsic camera parameters.

Mesh and Geometry Processing#

Geometry utilities support mesh analysis, bounding box calculations, and vertex processing. The extension provides tools for computing axis-aligned and oriented bounding boxes, extracting mesh vertices in different coordinate systems, and performing geometric transformations.

Key Components#

Commands System#

The extension registers several commands for common operations:

IsaacSimSpawnPrim creates new prims with USD references and applies transformations using physics-aware positioning.

IsaacSimTeleportPrim relocates existing prims with proper physics handling for articulated objects.

IsaacSimScalePrim applies scaling transformations to prims.

IsaacSimDestroyPrim removes prims from the stage with optimized performance for batch operations.

Data Structures#

Several specialized data classes facilitate state management:

DataFrame encapsulates simulation data at specific time steps with time indexing.

XFormPrimState and XFormPrimViewState manage transformation states for single and multiple prims.

DynamicState and DynamicsViewState handle dynamic rigid body states including velocities.

ArticulationAction and ArticulationActions define joint control commands for robotic systems.

Semantic Labeling System#

Semantic utilities provide comprehensive labeling support using UsdSemantics.LabelsAPI for scene understanding and automated annotation. The system supports label validation, missing label detection, and automatic migration from deprecated semantic APIs.

Physics Utilities#

Tetrahedral mesh generation and physics simulation utilities support soft body dynamics and advanced material modeling. The extension includes tools for creating tetrahedral meshes from voxel grids and geometric primitives.

Camera and Viewport Systems#

Dynamic camera utilities implement physics-based camera movement using spring-damper systems for smooth, natural motion. The system supports automatic focus adjustment and configurable motion characteristics for cinematic camera control.

Relationships#

The extension integrates with omni.physics and omni.physx for physics simulation capabilities, omni.warp.core for high-performance array operations, and omni.usd.schema.semantics for semantic labeling functionality. These integrations enable seamless data flow between USD authoring, physics simulation, and computational frameworks commonly used in robotics and AI applications.

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

# Delete a prim at the specified path
omni.kit.commands.execute("IsaacSimDestroyPrim", prim_path="/World/Prim")

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 a prim at path "/World/Cube" to 1.5 times its original size on all axes
omni.kit.commands.execute(
    "IsaacSimScalePrim",
    prim_path="/World/Cube",
    scale=(1.5, 1.5, 1.5)
)

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
import carb

# Spawn a new prim by referencing a USD file
omni.kit.commands.execute(
    "IsaacSimSpawnPrim",
    usd_path="/path/to/asset.usd",
    prim_path="/World/MySpawnedPrim",
    translation=(1.0, 2.0, 0.5),
    rotation=(0.0, 0.0, 0.707, 0.707)  # 90 degree rotation around Z-axis
)

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 a prim to a new position and rotation
omni.kit.commands.execute(
    "IsaacSimTeleportPrim",
    prim_path="/World/Cube",
    translation=(5.0, 0.0, 2.0),
    rotation=(0.0, 0.0, 0.707, 0.707)
)

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 – include children of specified prim in calculation

Returns:

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

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, [min x, min y, min z, max x, max y, max z]

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:

The centroid of the OBB as a NumPy array.
The axes of the OBB as a 2D NumPy array, where each row represents a different axis.
The half extent of the OBB as a NumPy array.

Return type:

A tuple containing the following OBB information

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:

NumPy 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 cache should be initialized
use_extents_hint – Use existing extents attribute on prim to compute bounding box

Returns:

Initialized bbox 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 – The centroid of the OBB as a NumPy array.
axes – The axes of the OBB as a 2D NumPy array, where each row represents a different axis.
half_extent – The half extent of the OBB as a NumPy array.

Returns:

NumPy 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 – include children of specified prim in 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 change.

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 to set the 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 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, a 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, returns None, 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 as it doesn’t 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 a 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 a 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 input arg fabric.

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 GfMatrix3d() 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.

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 GfMatrix3d() 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.

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 GfMatrix3d() 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).

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).

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 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 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 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 extension path for a loaded extension by its full id.

Parameters:: ext_id – full id of extension
Returns:: Path to 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 extension path for a loaded extension by its name.

Parameters:: extension_name – name of the extension
Returns:: Path to loaded extension root directory

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 inline (and also returns it).

Parameters:: v – The vector to normalize.
Returns:: The normalized vector.

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 vertice points.
coord_prim – Prim used as 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 value of physics:rigidBodyEnabled attribute if it exists, and None if it does not exist.

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 physics:rigidBodyEnabled attribute to
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#

Helper function to simulate async for seconds * steps_per_sec frames.

Parameters:

seconds – time in seconds to simulate for
steps_per_sec – steps per second
callback – optional 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 into current USD stage.

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

Parameters:

prim_path – The path of the new prim.
prim_type – Prim type name
position – prim position (applied last)
translation – prim translation (applied last)
orientation – prim rotation as quaternion
scale – scaling factor in x, y, z.
usd_path – Path to the USD that this prim will reference.
semantic_label – Semantic label.
semantic_type – set to “class” unless otherwise specified.
attributes – Key-value pairs of prim attributes to set.

Raises:

Exception – 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:

Exception – 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 the matching prim paths in the stage based on 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 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]#

Performs a breadth-first search starting from the root and returns all the 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. Defaults to None (i.e: traversal till the end of the tree).

Returns:

A list containing the root and children prims matching 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 prim(s) on which to search for the prim containing the API

Returns:

path or regex of the prim(s) 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

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

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.

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 the 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:

Exception – 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 e.g.: rigid_body, joint, dof, articulation, attractor, d6joint, then the corresponding string returned. If is an Xformable prim, then “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 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 prims 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#

Used to query if the prim_path corresponds to a link in an articulation which is a non root link.

Parameters:: prim_path – prim_path to query
Returns:: True if the prim path corresponds to a link in an articulation which is a non root link and can’t 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 if a path has a valid USD Prim at it.

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 doesn't exist
False

is_prim_root_path(prim_path: str) → bool#

Checks if the input prim path is root or not.

Parameters:: prim_path – The 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 you wish to move
path_to – Final destination 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 if one of the ancestors of the prim at the prim_path can pass the predicate.

Parameters:

prim_path – path to the USD Prim for which to check the ancestors
predicate – The condition that must be True about the ancestors

Returns:

True if there is an ancestor that can pass the predicate, False otherwise

Example:

>>> import isaacsim.core.utils.prims as prims_utils
>>>
>>> # given the stage: /World/Cube. Check is 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 – Prim to set
hide – True to hide in stage window, false to show

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 – Prim to set
no_delete – True to make prim undeletable in 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 the 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#

Sets the visibility of the prim in the opened stage.

Note

The method does this through the USD API.

Parameters:

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

Example:

>>> import 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 attribute on.
attribute – Relationship attribute to create.
target_prim_paths – List of targets 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’s frame, that’s 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’s 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’s view.

Returns:

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

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

Get an array of 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’s in view of the camera.

Parameters:

camera_prim – Prim path of the camera.
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’s 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’s view.
coord_prim – 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. Defaults to 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). Defaults to True.

Returns:

quaternion (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 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). Defaults to True.

Returns:

A 3x3 rotation matrix in its extrinsic or intrinsic form depends on the extrinsic argument.

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 the reverse) and False if it follows the intrinsic matrix conventions (equivalent to XYZ ordering). Defaults to True.

Returns:

Euler XYZ angles (intrinsic form) if extrinsic is False and Euler XYZ angles (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. Defaults to 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). Defaults to True.

Returns:

Euler XYZ angles (intrinsic form) if extrinsic is False and Euler XYZ angles (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 (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 the UsdSemantics.LabelsAPI.

Parameters:

prim – Usd Prim to add or update labels on.
labels – The list of labels to apply.
instance_name – The name of the semantic instance.
overwrite – If True, existing labels for this instance are replaced. If False, the new labels are appended to existing ones (if any).

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

Returns a list of [prim_path, label] for meshes where at least one semantic label (LabelsAPI).

is considered incorrect. By default, this returns no mismatches for labeled meshes. The legacy heuristic that treats labels absent from the prim path as incorrect can be enabled with validate_against_prim_path.

Parameters:

prim_path – This will check Prim path and its childrens’ labels. 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]#

Returns a list of prim paths of meshes with missing semantic labels (UsdSemantics.LabelsAPI).

Parameters:: prim_path – This will check Prim path and its childrens’ labels. 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]#

Returns a dictionary of semantic labels (UsdSemantics.LabelsAPI) and their corresponding count.

Parameters:: prim_path – This will check Prim path and its childrens’ labels. 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]]#

Returns semantic labels (UsdSemantics.LabelsAPI) applied to a prim.

Parameters:: prim – Prim to return labels for.
Returns:: Dictionary mapping instance names to a list 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#

Removes semantic labels (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 – Also traverse children and remove labels recursively.

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

Upgrades a prim and optionally its descendants from the deprecated SemanticsAPI.

to the new UsdSemantics.LabelsAPI.

Converts each found SemanticsAPI instance on the processed prim(s) 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 – The starting prim to upgrade.
include_descendants – If True, upgrades the prim and all its descendants. If False, upgrades only the specified prim.

Returns:

The 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 USD reference to the opened stage at 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 will be created with the specified type. This function also handles stage units verification to ensure compatibility.

Parameters:

usd_path – The path to USD file to reference.
prim_path – The prim path where the reference will be attached.
prim_type – The type of prim to create if it doesn’t 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 (str) as input and returns True/False if the prim should/shouldn’t 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 (asynchronous version).

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 input arg fabric.

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 we want to check
parent – Parent prim for the given path.

Returns:

a new path that is guaranteed to 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 (asynchronous version).

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 (hidden or not) paths 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, it will be overwritten 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 the 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 livesync, false to disable livesync

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

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"

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 stage.

Parameters:: fabric – If True, 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 (asynchronous version).

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 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 till 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 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 (scalar first) 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 DOF as a dictionary.

Parameters:: index – The 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 <= num of dofs.
joint_names – Joint names to specify which joints to manipulate (cannot be specified together with joint_indices). Shape (K,). Where K <= num of dofs.

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 time step, time, and data fields.

classmethod init_from_dict( dict_representation: dict, ) → DataFrame#

Create a DataFrame instance from a dictionary.

Parameters:: dict_representation – Dictionary containing time_step, 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 the viewport already exists with the specified viewport_name, that viewport will be replaced with the new camera view.

Parameters:

viewport_name – name of the viewport. If not provided, it will default to camera name.
camera_prim_path – name of the prim path of the camera
width – width of the viewport window, in pixels.
height – height of the viewport window, in pixels.
position_x – location x of the viewport window.
position_y – location y 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#

Destroys all viewport windows.

Parameters:

usd_context_name – usd context to use.
destroy_main_viewport – set to False to not destroy the default viewport. Defaults to True (destroy all viewports including the default one).

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 as viewport IDs are not the same as the viewport index.

Parameters:: index – viewport index to retrieve ID for
Returns:: Returns None if window index was not found
Return type:: viewport id

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 following image convention is assumed:: +x should point to the right in the image +y should point 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:: List of 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:

Returns None if window with matching ID was not found

Return type:

Window

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:

List of points from depth in world space

set_active_viewport_camera(camera_prim_path: str) → None#

Sets 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 – name of the 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 – Default 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).

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.

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, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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 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 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.

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 NumPy implementation).

Returns:

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

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 NumPy implementation).

Returns:

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

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 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 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 to place the result on (ignored in numpy backend).
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 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 (already in numpy format).

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 – Device for tensor operations.
pose – Optional 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 tensor operations.

Returns:

Tuple of (local_translations, local_orientations) in 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 – Device for tensor operations.

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 tensor operations.

Returns:

Tuple of (world_positions, world_orientations) in 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 – Device for tensor operations.

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#

Vectorized version of converting euler angles to quaternion (scalar first).

Parameters:

euler_angles – euler angles with shape (N, 3)
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 to place the tensor on.

Returns:

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

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

Converts a pxr Quaternion type to a torch array (scalar first).

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#

Takes a pose and normalises the quaternion portion of it.

Parameters:: pose – shape N, 7
Returns:: Pose with normalised quat. 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#

Vectorized version of converting rotation matrices to quaternions.

Parameters:

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

Returns:

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

wxyz2xyzw(q: object) → object#

Converts 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 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#

Set seed 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 2D tensor by swapping dimensions 0 and 1.

Parameters:: data – Input 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#

Denormalizes values from [-1, 1] range back to original [lower, upper] range using NumPy operations.

Parameters:

x – Input values to denormalize.
lower – Lower bound of the target range.
upper – Upper bound of the target range.

Returns:

Denormalized values in the original 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 – Target device for the operation.
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 – shape N, 7
Returns:: Pose with normalised quat. 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#

Vectorized version of converting euler angles to quaternion (scalar first).

Parameters:

euler_angles – euler angles with shape (N, 3)
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 to place the tensor on.

Returns:

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

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

Converts a pxr Quaternion type to a torch array (scalar first).

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#

Takes a pose and normalises the quaternion portion of it.

Parameters:: pose – shape N, 7
Returns:: Pose with normalised quat. 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#

Vectorized version of converting rotation matrices to quaternions.

Parameters:

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

Returns:

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

wxyz2xyzw(q: object) → object#

Converts 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 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 – Target device for the operation.
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 – shape N, 7
Returns:: Pose with normalised quat. 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).