orbit.utils

orbit.utils#

Sub-package containing utilities for common operations and helper functions.

Submodules

`io`	Submodules for files IO operations.
`array`	Sub-module containing utilities for working with different array backends.
`assets`	Sub-module that defines the host-server where assets and resources are stored.
`dict`	Sub-module for utilities for working with dictionaries.
`math`	Sub-module containing utilities for various math operations.
`noise`	Sub-module containing different noise models implementations.
`string`	Sub-module containing utilities for transforming strings and regular expressions.
`timer`	Sub-module for a timer class that can be used for performance measurements.
`warp`	Sub-module containing operations based on warp.

Functions

configclass(cls, **kwargs)

Wrapper around dataclass functionality to add extra checks and utilities.

Configuration class#

Sub-module that provides a wrapper around the Python 3.7 onwards dataclasses module.

Functions:

configclass(cls, **kwargs)

Wrapper around dataclass functionality to add extra checks and utilities.

omni.isaac.orbit.utils.configclass.configclass(cls, **kwargs)[source]#

Wrapper around dataclass functionality to add extra checks and utilities.

As of Python 3.7, the standard dataclasses have two main issues which makes them non-generic for configuration use-cases. These include:

Requiring a type annotation for all its members.
Requiring explicit usage of field(default_factory=...)() to reinitialize mutable variables.

This function provides a decorator that wraps around Python’s dataclass utility to deal with the above two issues. It also provides additional helper functions for dictionary <-> class conversion and easily copying class instances.

Usage:

from dataclasses import MISSING

from omni.isaac.orbit.utils.configclass import configclass


@configclass
class ViewerCfg:
    eye: list = [7.5, 7.5, 7.5]  # field missing on purpose
    lookat: list = field(default_factory=[0.0, 0.0, 0.0])


@configclass
class EnvCfg:
    num_envs: int = MISSING
    episode_length: int = 2000
    viewer: ViewerCfg = ViewerCfg()

# create configuration instance
env_cfg = EnvCfg(num_envs=24)

# print information as a dictionary
print(env_cfg.to_dict())

# create a copy of the configuration
env_cfg_copy = env_cfg.copy()

# replace arbitrary fields using keyword arguments
env_cfg_copy = env_cfg_copy.replace(num_envs=32)

Parameters:

cls – The class to wrap around.
**kwargs – Additional arguments to pass to dataclass().

Returns:

The wrapped class.

IO operations#

Submodules for files IO operations.

Functions:

`dump_pickle`(filename, data)	Saves data into a pickle file safely.
`load_pickle`(filename)	Loads an input PKL file safely.
`dump_yaml`(filename, data[, sort_keys])	Saves data into a YAML file safely.
`load_yaml`(filename)	Loads an input PKL file safely.

omni.isaac.orbit.utils.io.dump_pickle(filename: str, data: Any)[source]#

Saves data into a pickle file safely.

Note

The function creates any missing directory along the file’s path.

Parameters:

filename – The path to save the file at.
data – The data to save.

omni.isaac.orbit.utils.io.load_pickle(filename: str) → Any[source]#

Loads an input PKL file safely.

Parameters:: filename – The path to pickled file.
Raises:: FileNotFoundError – When the specified file does not exist.
Returns:: The data read from the input file.

omni.isaac.orbit.utils.io.dump_yaml(filename: str, data: dict | object, sort_keys: bool = False)[source]#

Saves data into a YAML file safely.

Note

The function creates any missing directory along the file’s path.

Parameters:

filename – The path to save the file at.
data – The data to save either a dictionary or class object.
sort_keys – Whether to sort the keys in the output file. Defaults to False.

omni.isaac.orbit.utils.io.load_yaml(filename: str) → dict[source]#

Loads an input PKL file safely.

Parameters:: filename – The path to pickled file.
Raises:: FileNotFoundError – When the specified file does not exist.
Returns:: The data read from the input file.

Array operations#

Sub-module containing utilities for working with different array backends.

Data:

`TENSOR_TYPES`	A dictionary containing the types for each backend.
`TENSOR_TYPE_CONVERSIONS`	A nested dictionary containing the conversion functions for each backend.

Functions:

convert_to_torch(array[, dtype, device])

Converts a given array into a torch tensor.

omni.isaac.orbit.utils.array.TensorData(*args, **kwargs)#

Type definition for a tensor data.

Union of numpy, torch, and warp arrays.

alias of Union[ndarray, Tensor, array]

omni.isaac.orbit.utils.array.TENSOR_TYPES = {'numpy': numpy.ndarray, 'torch': torch.Tensor, 'warp': warp.array}#

A dictionary containing the types for each backend.

The keys are the name of the backend (“numpy”, “torch”, “warp”) and the values are the corresponding type (np.ndarray, torch.Tensor, wp.array).

omni.isaac.orbit.utils.array.TENSOR_TYPE_CONVERSIONS = {'numpy': {warp.array: <function <lambda>>, torch.Tensor: <function <lambda>>}, 'torch': {warp.array: <function <lambda>>, numpy.ndarray: <function <lambda>>}, 'warp': {numpy.array: <function <lambda>>, torch.Tensor: <function <lambda>>}}#

A nested dictionary containing the conversion functions for each backend.

The keys of the outer dictionary are the name of target backend (“numpy”, “torch”, “warp”). The keys of the inner dictionary are the source backend (np.ndarray, torch.Tensor, wp.array).

omni.isaac.orbit.utils.array.convert_to_torch(array: TensorData, dtype: torch.dtype = None, device: torch.device | str | None = None) → torch.Tensor[source]#

Converts a given array into a torch tensor.

The function tries to convert the array to a torch tensor. If the array is a numpy/warp arrays, or python list/tuples, it is converted to a torch tensor. If the array is already a torch tensor, it is returned directly.

If device is None, then the function deduces the current device of the data. For numpy arrays, this defaults to “cpu”, for torch tensors it is “cpu” or “cuda”, and for warp arrays it is “cuda”.

Note

Since PyTorch does not support unsigned integer types, unsigned integer arrays are converted to signed integer arrays. This is done by casting the array to the corresponding signed integer type.

Parameters:

array – The input array. It can be a numpy array, warp array, python list/tuple, or torch tensor.
dtype – Target data-type for the tensor.
device – The target device for the tensor. Defaults to None.

Returns:

The converted array as torch tensor.

Asset operations#

Sub-module that defines the host-server where assets and resources are stored.

By default, we use the Isaac Sim Nucleus Server for hosting assets and resources. This makes distribution of the assets easier and makes the repository smaller in size code-wise.

For more information, please check information on Omniverse Nucleus.

Data:

`NVIDIA_NUCLEUS_DIR`	Path to the root directory on the NVIDIA Nucleus Server.
`ISAAC_NUCLEUS_DIR`	Path to the `Isaac` directory on the NVIDIA Nucleus Server.
`ISAAC_ORBIT_NUCLEUS_DIR`	Path to the `Isaac/Samples/Orbit` directory on the NVIDIA Nucleus Server.

Functions:

`check_file_path`(path)	Checks if a file exists on the Nucleus Server or locally.
`retrieve_file_path`(path[, download_dir, ...])	Retrieves the path to a file on the Nucleus Server or locally.
`read_file`(path)	Reads a file from the Nucleus Server or locally.

omni.isaac.orbit.utils.assets.NUCLEUS_ASSET_ROOT_DIR(*args: Any, **kwargs: Any) → Any#

Path to the root directory on the Nucleus Server.

This is resolved using Isaac Sim’s Nucleus API. If the Nucleus Server is not running, then this will be set to None. The path is resolved using the following steps:

Based on simulation parameter: /persistent/isaac/asset_root/default.
Iterating over all the connected Nucleus Servers and checking for the first server that has the the connected status.
Based on simulation parameter: /persistent/isaac/asset_root/cloud.

omni.isaac.orbit.utils.assets.NVIDIA_NUCLEUS_DIR = 'omni.isaac.core.utils.nucleus.get_assets_root_path/NVIDIA'#: Path to the root directory on the NVIDIA Nucleus Server.

omni.isaac.orbit.utils.assets.ISAAC_NUCLEUS_DIR = 'omni.isaac.core.utils.nucleus.get_assets_root_path/Isaac'#: Path to the Isaac directory on the NVIDIA Nucleus Server.

omni.isaac.orbit.utils.assets.ISAAC_ORBIT_NUCLEUS_DIR = 'omni.isaac.core.utils.nucleus.get_assets_root_path/Isaac/Samples/Orbit'#: Path to the Isaac/Samples/Orbit directory on the NVIDIA Nucleus Server.

omni.isaac.orbit.utils.assets.check_file_path(path: str) → Literal[0, 1, 2][source]#

Checks if a file exists on the Nucleus Server or locally.

Parameters:

path – The path to the file.

Returns:

The status of the file. Possible values are listed below.

0 if the file does not exist
1 if the file exists locally
2 if the file exists on the Nucleus Server

omni.isaac.orbit.utils.assets.retrieve_file_path(path: str, download_dir: str | None = None, force_download: bool = True) → str[source]#

Retrieves the path to a file on the Nucleus Server or locally.

If the file exists locally, then the absolute path to the file is returned. If the file exists on the Nucleus Server, then the file is downloaded to the local machine and the absolute path to the file is returned.

Parameters:

path – The path to the file.
download_dir – The directory where the file should be downloaded. Defaults to None, in which case the file is downloaded to the system’s temporary directory.
force_download – Whether to force download the file from the Nucleus Server. This will overwrite the local file if it exists. Defaults to True.

Returns:

The path to the file on the local machine.

Raises:

FileNotFoundError – When the file not found locally or on Nucleus Server.
RuntimeError – When the file cannot be copied from the Nucleus Server to the local machine. This can happen when the file already exists locally and force_download is set to False.

omni.isaac.orbit.utils.assets.read_file(path: str) → BytesIO[source]#

Reads a file from the Nucleus Server or locally.

Parameters:: path – The path to the file.
Raises:: FileNotFoundError – When the file not found locally or on Nucleus Server.
Returns:: The content of the file.

Dictionary operations#

Sub-module for utilities for working with dictionaries.

Functions:

`class_to_dict`(obj)	Convert an object into dictionary recursively.
`update_class_from_dict`(obj, data[, _ns])	Reads a dictionary and sets object variables recursively.
`dict_to_md5_hash`(data)	Convert a dictionary into a hashable key using MD5 hash.
`convert_dict_to_backend`(data[, backend, ...])	Convert all arrays or tensors in a dictionary to a given backend.
`update_dict`(orig_dict, new_dict)	Updates existing dictionary with values from a new dictionary.
`print_dict`(val[, nesting, start])	Outputs a nested dictionary.

omni.isaac.orbit.utils.dict.class_to_dict(obj: object) → dict[str, Any][source]#

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:: obj – An instance of a class to convert.
Raises:: ValueError – When input argument is not an object.
Returns:: Converted dictionary mapping.

omni.isaac.orbit.utils.dict.update_class_from_dict(obj, data: dict[str, Any], _ns: str = '') → None[source]#

Reads a dictionary and sets object variables recursively.

This function performs in-place update of the class member attributes.

Parameters:

obj – An instance of a class to update.
data – Input dictionary to update from.
_ns – Namespace of the current object. This is useful for nested configuration classes or dictionaries. Defaults to “”.

Raises:

TypeError – When input is not a dictionary.
ValueError – When dictionary has a value that does not match default config type.
KeyError – When dictionary has a key that does not exist in the default config type.

omni.isaac.orbit.utils.dict.dict_to_md5_hash(data: object) → str[source]#

Convert a dictionary into a hashable key using MD5 hash.

Parameters:: data – Input dictionary or configuration object to convert.
Returns:: A string object of double length containing only hexadecimal digits.

omni.isaac.orbit.utils.dict.convert_dict_to_backend(data: dict, backend: str = 'numpy', array_types: Iterable[str] = ('numpy', 'torch', 'warp')) → dict[source]#

Convert all arrays or tensors in a dictionary to a given backend.

This function iterates over the dictionary, converts all arrays or tensors with the given types to the desired backend, and stores them in a new dictionary. It also works with nested dictionaries.

Currently supported backends are “numpy”, “torch”, and “warp”.

Note

This function only converts arrays or tensors. Other types of data are left unchanged. Mutable types (e.g. lists) are referenced by the new dictionary, so they are not copied.

Parameters:

data – An input dict containing array or tensor data as values.
backend – The backend (“numpy”, “torch”, “warp”) to which arrays in this dict should be converted. Defaults to “numpy”.
array_types – A list containing the types of arrays that should be converted to the desired backend. Defaults to (“numpy”, “torch”, “warp”).

Raises:

ValueError – If the specified backend or array_types are unknown, i.e. not in the list of supported backends (“numpy”, “torch”, “warp”).

Returns:

The updated dict with the data converted to the desired backend.

omni.isaac.orbit.utils.dict.update_dict(orig_dict: dict, new_dict: Mapping) → dict[source]#

Updates existing dictionary with values from a new dictionary.

This function mimics the dict.update() function. However, it works for nested dictionaries as well.

Reference:: https://stackoverflow.com/questions/3232943/update-value-of-a-nested-dictionary-of-varying-depth

Parameters:

orig_dict – The original dictionary to insert items to.
new_dict – The new dictionary to insert items from.

Returns:

The updated dictionary.

omni.isaac.orbit.utils.dict.print_dict(val, nesting: int = -4, start: bool = True)[source]#: Outputs a nested dictionary.

Math operations#

Sub-module containing utilities for various math operations.

Functions:

`scale_transform`	Normalizes a given input tensor to a range of [-1, 1].
`unscale_transform`	De-normalizes a given input tensor from range of [-1, 1] to (lower, upper).
`saturate`	Clamps a given input tensor to (lower, upper).
`normalize`	Normalizes a given input tensor to unit length.
`wrap_to_pi`	Wraps input angles (in radians) to the range [-pi, pi].
`copysign`	Create a new floating-point tensor with the magnitude of input and the sign of other, element-wise.
`matrix_from_quat`	Convert rotations given as quaternions to rotation matrices.
`convert_quat`(quat[, to])	Converts quaternion from one convention to another.
`quat_conjugate`	Computes the conjugate of a quaternion.
`quat_inv`	Compute the inverse of a quaternion.
`quat_from_euler_xyz`	Convert rotations given as Euler angles in radians to Quaternions.
`quat_from_matrix`	Convert rotations given as rotation matrices to quaternions.
`matrix_from_euler`(euler_angles, convention)	Convert rotations given as Euler angles in radians to rotation matrices.
`euler_xyz_from_quat`	Convert rotations given as quaternions to Euler angles in radians.
`quat_unique`	Convert a unit quaternion to a standard form where the real part is non-negative.
`quat_mul`	Multiply two quaternions together.
`quat_box_minus`	The box-minus operator (quaternion difference) between two quaternions.
`yaw_quat`	Extract the yaw component of a quaternion.
`quat_apply`	Apply a quaternion rotation to a vector.
`quat_apply_yaw`	Rotate a vector only around the yaw-direction.
`quat_rotate`	Rotate a vector by a quaternion.
`quat_rotate_inverse`	Rotate a vector by the inverse of a quaternion.
`quat_from_angle_axis`	Convert rotations given as angle-axis to quaternions.
`axis_angle_from_quat`	Convert rotations given as quaternions to axis/angle.
`quat_error_magnitude`	Computes the rotation difference between two quaternions.
`skew_symmetric_matrix`	Computes the skew-symmetric matrix of a vector.
`is_identity_pose`(pos, rot)	Checks if input poses are identity transforms.
`combine_frame_transforms`(t01, q01[, t12, q12])	Combine transformations between two reference frames into a stationary frame.
`subtract_frame_transforms`(t01, q01[, t02, q02])	Subtract transformations between two reference frames into a stationary frame.
`compute_pose_error`(t01, q01, t02, q02[, ...])	Compute the position and orientation error between source and target frames.
`apply_delta_pose`	Applies delta pose transformation on source pose.
`transform_points`(points[, pos, quat])	Transform input points in a given frame to a target frame.
`unproject_depth`	Unproject depth image into a pointcloud.
`project_points`	Projects 3D points into 2D image plane.
`default_orientation`	Returns identity rotation transform.
`random_orientation`	Returns sampled rotation in 3D as quaternion.
`random_yaw_orientation`	Returns sampled rotation around z-axis.
`sample_triangle`(lower, upper, size, device)	Randomly samples tensor from a triangular distribution.
`sample_uniform`(lower, upper, size, device)	Sample uniformly within a range.
`sample_log_uniform`(lower, upper, size, device)	Sample using log-uniform distribution within a range.
`sample_cylinder`(radius, h_range, size, device)	Sample 3D points uniformly on a cylinder's surface.

omni.isaac.orbit.utils.math.scale_transform(x: torch.Tensor, lower: torch.Tensor, upper: torch.Tensor) → torch.Tensor#

Normalizes a given input tensor to a range of [-1, 1].

Note

It uses pytorch broadcasting functionality to deal with batched input.

Parameters:

x – Input tensor of shape (N, dims).
lower – The minimum value of the tensor. Shape is (N, dims) or (dims,).
upper – The maximum value of the tensor. Shape is (N, dims) or (dims,).

Returns:

Normalized transform of the tensor. Shape is (N, dims).

omni.isaac.orbit.utils.math.unscale_transform(x: torch.Tensor, lower: torch.Tensor, upper: torch.Tensor) → torch.Tensor#

De-normalizes a given input tensor from range of [-1, 1] to (lower, upper).

Note

It uses pytorch broadcasting functionality to deal with batched input.

Parameters:

x – Input tensor of shape (N, dims).
lower – The minimum value of the tensor. Shape is (N, dims) or (dims,).
upper – The maximum value of the tensor. Shape is (N, dims) or (dims,).

Returns:

De-normalized transform of the tensor. Shape is (N, dims).

omni.isaac.orbit.utils.math.saturate(x: torch.Tensor, lower: torch.Tensor, upper: torch.Tensor) → torch.Tensor#

Clamps a given input tensor to (lower, upper).

It uses pytorch broadcasting functionality to deal with batched input.

Parameters:

x – Input tensor of shape (N, dims).
lower – The minimum value of the tensor. Shape is (N, dims) or (dims,).
upper – The maximum value of the tensor. Shape is (N, dims) or (dims,).

Returns:

Clamped transform of the tensor. Shape is (N, dims).

omni.isaac.orbit.utils.math.normalize(x: torch.Tensor, eps: float = 1e-09) → torch.Tensor#

Normalizes a given input tensor to unit length.

Parameters:

x – Input tensor of shape (N, dims).
eps – A small value to avoid division by zero. Defaults to 1e-9.

Returns:

Normalized tensor of shape (N, dims).

omni.isaac.orbit.utils.math.wrap_to_pi(angles: torch.Tensor) → torch.Tensor#

Wraps input angles (in radians) to the range [-pi, pi].

Parameters:: angles – Input angles of any shape.
Returns:: Angles in the range [-pi, pi].

omni.isaac.orbit.utils.math.copysign(mag: float, other: torch.Tensor) → torch.Tensor#

Create a new floating-point tensor with the magnitude of input and the sign of other, element-wise.

Note

The implementation follows from torch.copysign. The function allows a scalar magnitude.

Parameters:

mag – The magnitude scalar.
other – The tensor containing values whose signbits are applied to magnitude.

Returns:

The output tensor.

omni.isaac.orbit.utils.math.matrix_from_quat(quaternions: torch.Tensor) → torch.Tensor#

Convert rotations given as quaternions to rotation matrices.

Parameters:: quaternions – The quaternion orientation in (w, x, y, z). Shape is (…, 4).
Returns:: Rotation matrices. The shape is (…, 3, 3).

Reference:: facebookresearch/pytorch3d

omni.isaac.orbit.utils.math.convert_quat(quat: torch.Tensor | np.ndarray, to: Literal['xyzw', 'wxyz'] = 'xyzw') → torch.Tensor | np.ndarray[source]#

Converts quaternion from one convention to another.

The convention to convert TO is specified as an optional argument. If to == ‘xyzw’, then the input is in ‘wxyz’ format, and vice-versa.

Parameters:

quat – The quaternion of shape (…, 4).
to – Convention to convert quaternion to.. Defaults to “xyzw”.

Returns:

The converted quaternion in specified convention.

Raises:

ValueError – Invalid input argument to, i.e. not “xyzw” or “wxyz”.
ValueError – Invalid shape of input quat, i.e. not (…, 4,).

omni.isaac.orbit.utils.math.quat_conjugate(q: torch.Tensor) → torch.Tensor#

Computes the conjugate of a quaternion.

Parameters:: q – The quaternion orientation in (w, x, y, z). Shape is (…, 4).
Returns:: The conjugate quaternion in (w, x, y, z). Shape is (…, 4).

omni.isaac.orbit.utils.math.quat_inv(q: torch.Tensor) → torch.Tensor#

Compute the inverse of a quaternion.

Parameters:: q – The quaternion orientation in (w, x, y, z). Shape is (N, 4).
Returns:: The inverse quaternion in (w, x, y, z). Shape is (N, 4).

omni.isaac.orbit.utils.math.quat_from_euler_xyz(roll: torch.Tensor, pitch: torch.Tensor, yaw: torch.Tensor) → torch.Tensor#

Convert rotations given as Euler angles in radians to Quaternions.

Note

The euler angles are assumed in XYZ convention.

Parameters:

roll – Rotation around x-axis (in radians). Shape is (N,).
pitch – Rotation around y-axis (in radians). Shape is (N,).
yaw – Rotation around z-axis (in radians). Shape is (N,).

Returns:

The quaternion in (w, x, y, z). Shape is (N, 4).

omni.isaac.orbit.utils.math.quat_from_matrix(matrix: torch.Tensor) → torch.Tensor#

Convert rotations given as rotation matrices to quaternions.

Parameters:: matrix – The rotation matrices. Shape is (…, 3, 3).
Returns:: The quaternion in (w, x, y, z). Shape is (…, 4).

Reference:: facebookresearch/pytorch3d

omni.isaac.orbit.utils.math.matrix_from_euler(euler_angles: torch.Tensor, convention: str) → torch.Tensor[source]#

Convert rotations given as Euler angles in radians to rotation matrices.

Parameters:

euler_angles – Euler angles in radians. Shape is (…, 3).
convention – Convention string of three uppercase letters from {“X”, “Y”, and “Z”}. For example, “XYZ” means that the rotations should be applied first about x, then y, then z.

Returns:

Rotation matrices. Shape is (…, 3, 3).

Reference:: facebookresearch/pytorch3d

omni.isaac.orbit.utils.math.euler_xyz_from_quat(quat: torch.Tensor) → tuple[torch.Tensor, torch.Tensor, torch.Tensor]#

Convert rotations given as quaternions to Euler angles in radians.

Note

The euler angles are assumed in XYZ convention.

Parameters:: quat – The quaternion orientation in (w, x, y, z). Shape is (N, 4).
Returns:: A tuple containing roll-pitch-yaw. Each element is a tensor of shape (N,).

Reference:: https://en.wikipedia.org/wiki/Conversion_between_quaternions_and_Euler_angles

omni.isaac.orbit.utils.math.quat_unique(q: torch.Tensor) → torch.Tensor#

Convert a unit quaternion to a standard form where the real part is non-negative.

Quaternion representations have a singularity since q and -q represent the same rotation. This function ensures the real part of the quaternion is non-negative.

Parameters:: q – The quaternion orientation in (w, x, y, z). Shape is (…, 4).
Returns:: Standardized quaternions. Shape is (…, 4).

omni.isaac.orbit.utils.math.quat_mul(q1: torch.Tensor, q2: torch.Tensor) → torch.Tensor#

Multiply two quaternions together.

Parameters:

q1 – The first quaternion in (w, x, y, z). Shape is (…, 4).
q2 – The second quaternion in (w, x, y, z). Shape is (…, 4).

Returns:

The product of the two quaternions in (w, x, y, z). Shape is (…, 4).

Raises:

ValueError – Input shapes of q1 and q2 are not matching.

omni.isaac.orbit.utils.math.quat_box_minus(q1: torch.Tensor, q2: torch.Tensor) → torch.Tensor#

The box-minus operator (quaternion difference) between two quaternions.

Parameters:

q1 – The first quaternion in (w, x, y, z). Shape is (N, 4).
q2 – The second quaternion in (w, x, y, z). Shape is (N, 4).

Returns:

The difference between the two quaternions. Shape is (N, 3).

Reference:: https://docs.leggedrobotics.com/kindr/cheatsheet_latest.pdf

omni.isaac.orbit.utils.math.yaw_quat(quat: torch.Tensor) → torch.Tensor#

Extract the yaw component of a quaternion.

Parameters:: quat – The orientation in (w, x, y, z). Shape is (…, 4)
Returns:: A quaternion with only yaw component.

omni.isaac.orbit.utils.math.quat_apply(quat: torch.Tensor, vec: torch.Tensor) → torch.Tensor#

Apply a quaternion rotation to a vector.

Parameters:

quat – The quaternion in (w, x, y, z). Shape is (…, 4).
vec – The vector in (x, y, z). Shape is (…, 3).

Returns:

The rotated vector in (x, y, z). Shape is (…, 3).

omni.isaac.orbit.utils.math.quat_apply_yaw(quat: torch.Tensor, vec: torch.Tensor) → torch.Tensor#

Rotate a vector only around the yaw-direction.

Parameters:

quat – The orientation in (w, x, y, z). Shape is (N, 4).
vec – The vector in (x, y, z). Shape is (N, 3).

Returns:

The rotated vector in (x, y, z). Shape is (N, 3).

omni.isaac.orbit.utils.math.quat_rotate(q: torch.Tensor, v: torch.Tensor) → torch.Tensor#

Rotate a vector by a quaternion.

Parameters:

q – The quaternion in (w, x, y, z). Shape is (N, 4).
v – The vector in (x, y, z). Shape is (N, 3).

Returns:

The rotated vector in (x, y, z). Shape is (N, 3).

omni.isaac.orbit.utils.math.quat_rotate_inverse(q: torch.Tensor, v: torch.Tensor) → torch.Tensor#

Rotate a vector by the inverse of a quaternion.

Parameters:

q – The quaternion in (w, x, y, z). Shape is (N, 4).
v – The vector in (x, y, z). Shape is (N, 3).

Returns:

The rotated vector in (x, y, z). Shape is (N, 3).

omni.isaac.orbit.utils.math.quat_from_angle_axis(angle: torch.Tensor, axis: torch.Tensor) → torch.Tensor#

Convert rotations given as angle-axis to quaternions.

Parameters:

angle – The angle turned anti-clockwise in radians around the vector’s direction. Shape is (N,).
axis – The axis of rotation. Shape is (N, 3).

Returns:

The quaternion in (w, x, y, z). Shape is (N, 4).

omni.isaac.orbit.utils.math.axis_angle_from_quat(quat: torch.Tensor, eps: float = 1e-06) → torch.Tensor#

Convert rotations given as quaternions to axis/angle.

Parameters:

quat – The quaternion orientation in (w, x, y, z). Shape is (…, 4).
eps – The tolerance for Taylor approximation. Defaults to 1.0e-6.

Returns:

Rotations given as a vector in axis angle form. Shape is (…, 3). The vector’s magnitude is the angle turned anti-clockwise in radians around the vector’s direction.

Reference:: facebookresearch/pytorch3d

omni.isaac.orbit.utils.math.quat_error_magnitude(q1: torch.Tensor, q2: torch.Tensor) → torch.Tensor#

Computes the rotation difference between two quaternions.

Parameters:

q1 – The first quaternion in (w, x, y, z). Shape is (…, 4).
q2 – The second quaternion in (w, x, y, z). Shape is (…, 4).

Returns:

Angular error between input quaternions in radians.

omni.isaac.orbit.utils.math.skew_symmetric_matrix(vec: torch.Tensor) → torch.Tensor#

Computes the skew-symmetric matrix of a vector.

Parameters:: vec – The input vector. Shape is (3,) or (N, 3).
Returns:: The skew-symmetric matrix. Shape is (1, 3, 3) or (N, 3, 3).
Raises:: ValueError – If input tensor is not of shape (…, 3).

omni.isaac.orbit.utils.math.is_identity_pose(pos: torch.tensor, rot: torch.tensor) → bool[source]#

Checks if input poses are identity transforms.

The function checks if the input position and orientation are close to zero and identity respectively using L2-norm. It does NOT check the error in the orientation.

Parameters:

pos – The cartesian position. Shape is (N, 3).
rot – The quaternion in (w, x, y, z). Shape is (N, 4).

Returns:

True if all the input poses result in identity transform. Otherwise, False.

omni.isaac.orbit.utils.math.combine_frame_transforms(t01: torch.Tensor, q01: torch.Tensor, t12: torch.Tensor | None = None, q12: torch.Tensor | None = None) → tuple[torch.Tensor, torch.Tensor][source]#

Combine transformations between two reference frames into a stationary frame.

It performs the following transformation operation: \(T_{02} = T_{01} \times T_{12}\), where \(T_{AB}\) is the homogeneous transformation matrix from frame A to B.

Parameters:

t01 – Position of frame 1 w.r.t. frame 0. Shape is (N, 3).
q01 – Quaternion orientation of frame 1 w.r.t. frame 0 in (w, x, y, z). Shape is (N, 4).
t12 – Position of frame 2 w.r.t. frame 1. Shape is (N, 3). Defaults to None, in which case the position is assumed to be zero.
q12 – Quaternion orientation of frame 2 w.r.t. frame 1 in (w, x, y, z). Shape is (N, 4). Defaults to None, in which case the orientation is assumed to be identity.

Returns:

A tuple containing the position and orientation of frame 2 w.r.t. frame 0. Shape of the tensors are (N, 3) and (N, 4) respectively.

omni.isaac.orbit.utils.math.subtract_frame_transforms(t01: torch.Tensor, q01: torch.Tensor, t02: torch.Tensor | None = None, q02: torch.Tensor | None = None) → tuple[torch.Tensor, torch.Tensor][source]#

Subtract transformations between two reference frames into a stationary frame.

It performs the following transformation operation: \(T_{12} = T_{01}^{-1} \times T_{02}\), where \(T_{AB}\) is the homogeneous transformation matrix from frame A to B.

Parameters:

t01 – Position of frame 1 w.r.t. frame 0. Shape is (N, 3).
q01 – Quaternion orientation of frame 1 w.r.t. frame 0 in (w, x, y, z). Shape is (N, 4).
t02 – Position of frame 2 w.r.t. frame 0. Shape is (N, 3). Defaults to None, in which case the position is assumed to be zero.
q02 – Quaternion orientation of frame 2 w.r.t. frame 0 in (w, x, y, z). Shape is (N, 4). Defaults to None, in which case the orientation is assumed to be identity.

Returns:

A tuple containing the position and orientation of frame 2 w.r.t. frame 1. Shape of the tensors are (N, 3) and (N, 4) respectively.

omni.isaac.orbit.utils.math.compute_pose_error(t01: torch.Tensor, q01: torch.Tensor, t02: torch.Tensor, q02: torch.Tensor, rot_error_type: Literal['quat', 'axis_angle'] = 'axis_angle') → tuple[torch.Tensor, torch.Tensor][source]#

Compute the position and orientation error between source and target frames.

Parameters:

t01 – Position of source frame. Shape is (N, 3).
q01 – Quaternion orientation of source frame in (w, x, y, z). Shape is (N, 4).
t02 – Position of target frame. Shape is (N, 3).
q02 – Quaternion orientation of target frame in (w, x, y, z). Shape is (N, 4).
rot_error_type – The rotation error type to return: “quat”, “axis_angle”. Defaults to “axis_angle”.

Returns:

A tuple containing position and orientation error. Shape of position error is (N, 3). Shape of orientation error depends on the value of rot_error_type:

If rot_error_type is “quat”, the orientation error is returned as a quaternion. Shape is (N, 4).
If rot_error_type is “axis_angle”, the orientation error is returned as an axis-angle vector. Shape is (N, 3).

Raises:

ValueError – Invalid rotation error type.

omni.isaac.orbit.utils.math.apply_delta_pose(source_pos: torch.Tensor, source_rot: torch.Tensor, delta_pose: torch.Tensor, eps: float = 1e-06) → tuple[torch.Tensor, torch.Tensor]#

Applies delta pose transformation on source pose.

The first three elements of delta_pose are interpreted as cartesian position displacement. The remaining three elements of delta_pose are interpreted as orientation displacement in the angle-axis format.

Parameters:

source_pos – Position of source frame. Shape is (N, 3).
source_rot – Quaternion orientation of source frame in (w, x, y, z). Shape is (N, 4)..
delta_pose – Position and orientation displacements. Shape is (N, 6).
eps – The tolerance to consider orientation displacement as zero. Defaults to 1.0e-6.

Returns:

A tuple containing the displaced position and orientation frames. Shape of the tensors are (N, 3) and (N, 4) respectively.

omni.isaac.orbit.utils.math.transform_points(points: torch.Tensor, pos: torch.Tensor | None = None, quat: torch.Tensor | None = None) → torch.Tensor[source]#

Transform input points in a given frame to a target frame.

This function transform points from a source frame to a target frame. The transformation is defined by the position \(t\) and orientation \(R\) of the target frame in the source frame.

\[p_{target} = R_{target} \times p_{source} + t_{target}\]

If the input points is a batch of points, the inputs pos and quat must be either a batch of positions and quaternions or a single position and quaternion. If the inputs pos and quat are a single position and quaternion, the same transformation is applied to all points in the batch.

If either the inputs pos and quat are None, the corresponding transformation is not applied.

Parameters:

points – Points to transform. Shape is (N, P, 3) or (P, 3).
pos – Position of the target frame. Shape is (N, 3) or (3,). Defaults to None, in which case the position is assumed to be zero.
quat – Quaternion orientation of the target frame in (w, x, y, z). Shape is (N, 4) or (4,). Defaults to None, in which case the orientation is assumed to be identity.

Returns:

Transformed points in the target frame. Shape is (N, P, 3) or (P, 3).

Raises:

ValueError – If the inputs points is not of shape (N, P, 3) or (P, 3).
ValueError – If the inputs pos is not of shape (N, 3) or (3,).
ValueError – If the inputs quat is not of shape (N, 4) or (4,).

omni.isaac.orbit.utils.math.unproject_depth(depth: torch.Tensor, intrinsics: torch.Tensor) → torch.Tensor#

Unproject depth image into a pointcloud.

This function converts depth images into points given the calibration matrix of the camera.

\[p_{3D} = K^{-1} \times [u, v, 1]^T \times d\]

where \(p_{3D}\) is the 3D point, \(d\) is the depth value, \(u\) and \(v\) are the pixel coordinates and \(K\) is the intrinsic matrix.

If depth is a batch of depth images and intrinsics is a single intrinsic matrix, the same calibration matrix is applied to all depth images in the batch.

The function assumes that the width and height are both greater than 1. This makes the function deal with many possible shapes of depth images and intrinsics matrices.

Parameters:

depth – The depth measurement. Shape is (H, W) or or (H, W, 1) or (N, H, W) or (N, H, W, 1).
intrinsics – A tensor providing camera’s calibration matrix. Shape is (3, 3) or (N, 3, 3).

Returns:

The 3D coordinates of points. Shape is (P, 3) or (N, P, 3).

Raises:

ValueError – When depth is not of shape (H, W) or (H, W, 1) or (N, H, W) or (N, H, W, 1).
ValueError – When intrinsics is not of shape (3, 3) or (N, 3, 3).

omni.isaac.orbit.utils.math.project_points(points: torch.Tensor, intrinsics: torch.Tensor) → torch.Tensor#

Projects 3D points into 2D image plane.

This project 3D points into a 2D image plane. The transformation is defined by the intrinsic matrix of the camera.

\[\begin{split}\begin{align} p &= K \times p_{3D} = \\ p_{2D} &= \begin{pmatrix} u \\ v \\ d \end{pmatrix} = \begin{pmatrix} p[0] / p[2] \\ p[1] / p[2] \\ Z \end{pmatrix} \end{align}\end{split}\]

where \(p_{2D} = (u, v, d)\) is the projected 3D point, \(p_{3D} = (X, Y, Z)\) is the 3D point and \(K \in \mathbb{R}^{3 \times 3}\) is the intrinsic matrix.

If points is a batch of 3D points and intrinsics is a single intrinsic matrix, the same calibration matrix is applied to all points in the batch.

Parameters:

points – The 3D coordinates of points. Shape is (P, 3) or (N, P, 3).
intrinsics – Camera’s calibration matrix. Shape is (3, 3) or (N, 3, 3).

Returns:

Projected 3D coordinates of points. Shape is (P, 3) or (N, P, 3).

omni.isaac.orbit.utils.math.default_orientation(num: int, device: str) → torch.Tensor#

Returns identity rotation transform.

Parameters:

num – The number of rotations to sample.
device – Device to create tensor on.

Returns:

Identity quaternion in (w, x, y, z). Shape is (num, 4).

omni.isaac.orbit.utils.math.random_orientation(num: int, device: str) → torch.Tensor#

Returns sampled rotation in 3D as quaternion.

Parameters:

num – The number of rotations to sample.
device – Device to create tensor on.

Returns:

Sampled quaternion in (w, x, y, z). Shape is (num, 4).

Reference:: https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.transform.Rotation.random.html

omni.isaac.orbit.utils.math.random_yaw_orientation(num: int, device: str) → torch.Tensor#

Returns sampled rotation around z-axis.

Parameters:

num – The number of rotations to sample.
device – Device to create tensor on.

Returns:

Sampled quaternion in (w, x, y, z). Shape is (num, 4).

omni.isaac.orbit.utils.math.sample_triangle(lower: float, upper: float, size: int | tuple[int, ...], device: str) → torch.Tensor[source]#

Randomly samples tensor from a triangular distribution.

Parameters:

lower – The lower range of the sampled tensor.
upper – The upper range of the sampled tensor.
size – The shape of the tensor.
device – Device to create tensor on.

Returns:

Sampled tensor. Shape is based on size.

omni.isaac.orbit.utils.math.sample_uniform(lower: torch.Tensor | float, upper: torch.Tensor | float, size: int | tuple[int, ...], device: str) → torch.Tensor[source]#

Sample uniformly within a range.

Parameters:

lower – Lower bound of uniform range.
upper – Upper bound of uniform range.
size – The shape of the tensor.
device – Device to create tensor on.

Returns:

Sampled tensor. Shape is based on size.

omni.isaac.orbit.utils.math.sample_log_uniform(lower: torch.Tensor | float, upper: torch.Tensor | float, size: int | tuple[int, ...], device: str) → torch.Tensor[source]#

Sample using log-uniform distribution within a range.

The log-uniform distribution is defined as a uniform distribution in the log-space. It is useful for sampling values that span several orders of magnitude. The sampled values are uniformly distributed in the log-space and then exponentiated to get the final values.

\[x = \exp(\text{uniform}(\log(\text{lower}), \log(\text{upper})))\]

Parameters:

lower – Lower bound of uniform range.
upper – Upper bound of uniform range.
size – The shape of the tensor.
device – Device to create tensor on.

Returns:

Sampled tensor. Shape is based on size.

omni.isaac.orbit.utils.math.sample_cylinder(radius: float, h_range: tuple[float, float], size: int | tuple[int, ...], device: str) → torch.Tensor[source]#

Sample 3D points uniformly on a cylinder’s surface.

The cylinder is centered at the origin and aligned with the z-axis. The height of the cylinder is sampled uniformly from the range h_range, while the radius is fixed to radius.

The sampled points are returned as a tensor of shape (*size, 3), i.e. the last dimension contains the x, y, and z coordinates of the sampled points.

Parameters:

radius – The radius of the cylinder.
h_range – The minimum and maximum height of the cylinder.
size – The shape of the tensor.
device – Device to create tensor on.

Returns:

Sampled tensor. Shape is (*size, 3).

Noise operations#

Sub-module containing different noise models implementations.

The noise models are implemented as functions that take in a tensor and a configuration and return a tensor with the noise applied. These functions are then used in the NoiseCfg configuration class.

Usage:

import torch
from omni.isaac.orbit.utils.noise import AdditiveGaussianNoiseCfg

# create a random tensor
my_tensor = torch.rand(128, 128, device="cuda")

# create a noise configuration
cfg = AdditiveGaussianNoiseCfg(mean=0.0, std=1.0)

# apply the noise
my_noisified_tensor = cfg.func(my_tensor, cfg)

Classes:

`NoiseCfg`	Base configuration for a noise term.
`AdditiveGaussianNoiseCfg`	Configuration for a additive gaussian noise term.
`AdditiveUniformNoiseCfg`	Configuration for a additive uniform noise term.
`ConstantBiasNoiseCfg`	Configuration for a constant bias noise term.

class omni.isaac.orbit.utils.noise.NoiseCfg[source]#

Bases: object

Base configuration for a noise term.

class omni.isaac.orbit.utils.noise.AdditiveGaussianNoiseCfg[source]#

Bases: NoiseCfg

Configuration for a additive gaussian noise term.

Attributes:

`mean`	The mean of the noise.
`std`	The standard deviation of the noise.

mean: float#: The mean of the noise. Defaults to 0.0.

std: float#: The standard deviation of the noise. Defaults to 1.0.

class omni.isaac.orbit.utils.noise.AdditiveUniformNoiseCfg[source]#

Bases: NoiseCfg

Configuration for a additive uniform noise term.

Attributes:

`n_min`	The minimum value of the noise.
`n_max`	The maximum value of the noise.

n_min: float#: The minimum value of the noise. Defaults to -1.0.

n_max: float#: The maximum value of the noise. Defaults to 1.0.

class omni.isaac.orbit.utils.noise.ConstantBiasNoiseCfg[source]#

Bases: NoiseCfg

Configuration for a constant bias noise term.

Attributes:

bias

The bias to add.

bias: float#: The bias to add. Defaults to 0.0.

String operations#

Sub-module containing utilities for transforming strings and regular expressions.

Functions:

`to_camel_case`(snake_str[, to])	Converts a string from snake case to camel case.
`to_snake_case`(camel_str)	Converts a string from camel case to snake case.
`is_lambda_expression`(name)	Checks if the input string is a lambda expression.
`callable_to_string`(value)	Converts a callable object to a string.
`string_to_callable`(name)	Resolves the module and function names to return the function.
`resolve_matching_names`(keys, list_of_strings)	Match a list of query regular expressions against a list of strings and return the matched indices and names.
`resolve_matching_names_values`(data, ...[, ...])	Match a list of regular expressions in a dictionary against a list of strings and return the matched indices, names, and values.

omni.isaac.orbit.utils.string.to_camel_case(snake_str: str, to: str = 'cC') → str[source]#

Converts a string from snake case to camel case.

Parameters:

snake_str – A string in snake case (i.e. with ‘_’)
to – Convention to convert string to. Defaults to “cC”.

Raises:

ValueError – Invalid input argument to, i.e. not “cC” or “CC”.

Returns:

A string in camel-case format.

omni.isaac.orbit.utils.string.to_snake_case(camel_str: str) → str[source]#

Converts a string from camel case to snake case.

Parameters:: camel_str – A string in camel case.
Returns:: A string in snake case (i.e. with ‘_’)

omni.isaac.orbit.utils.string.is_lambda_expression(name: str) → bool[source]#

Checks if the input string is a lambda expression.

Parameters:: name – The input string.
Returns:: Whether the input string is a lambda expression.

omni.isaac.orbit.utils.string.callable_to_string(value: Callable) → str[source]#

Converts a callable object to a string.

Parameters:: value – A callable object.
Raises:: ValueError – When the input argument is not a callable object.
Returns:: A string representation of the callable object.

omni.isaac.orbit.utils.string.string_to_callable(name: str) → Callable[source]#

Resolves the module and function names to return the function.

Parameters:

name – The function name. The format should be ‘module:attribute_name’ or a lambda expression of format: ‘lambda x: x’.

Raises:

ValueError – When the resolved attribute is not a function.
ValueError – When the module cannot be found.

Returns:

The function loaded from the module.

Return type:

Callable

omni.isaac.orbit.utils.string.resolve_matching_names(keys: str | Sequence[str], list_of_strings: Sequence[str], preserve_order: bool = False) → tuple[list[int], list[str]][source]#

Match a list of query regular expressions against a list of strings and return the matched indices and names.

When a list of query regular expressions is provided, the function checks each target string against each query regular expression and returns the indices of the matched strings and the matched strings.

If the preserve_order is True, the ordering of the matched indices and names is the same as the order of the provided list of strings. This means that the ordering is dictated by the order of the target strings and not the order of the query regular expressions.

If the preserve_order is False, the ordering of the matched indices and names is the same as the order of the provided list of query regular expressions.

For example, consider the list of strings is [‘a’, ‘b’, ‘c’, ‘d’, ‘e’] and the regular expressions are [‘a|c’, ‘b’]. If preserve_order is False, then the function will return the indices of the matched strings and the strings as: ([0, 1, 2], [‘a’, ‘b’, ‘c’]). When preserve_order is True, it will return them as: ([0, 2, 1], [‘a’, ‘c’, ‘b’]).

Note

The function does not sort the indices. It returns the indices in the order they are found.

Parameters:

keys – A regular expression or a list of regular expressions to match the strings in the list.
list_of_strings – A list of strings to match.
preserve_order – Whether to preserve the order of the query keys in the returned values. Defaults to False.

Returns:

A tuple of lists containing the matched indices and names.

Raises:

ValueError – When multiple matches are found for a string in the list.
ValueError – When not all regular expressions are matched.

omni.isaac.orbit.utils.string.resolve_matching_names_values(data: dict[str, Any], list_of_strings: Sequence[str], preserve_order: bool = False) → tuple[list[int], list[str], list[Any]][source]#

Match a list of regular expressions in a dictionary against a list of strings and return the matched indices, names, and values.

If the preserve_order is False, the ordering of the matched indices and names is the same as the order of the provided list of query regular expressions.

For example, consider the dictionary is {“a|d|e”: 1, “b|c”: 2}, the list of strings is [‘a’, ‘b’, ‘c’, ‘d’, ‘e’]. If preserve_order is False, then the function will return the indices of the matched strings, the matched strings, and the values as: ([0, 1, 2, 3, 4], [‘a’, ‘b’, ‘c’, ‘d’, ‘e’], [1, 2, 2, 1, 1]). When preserve_order is True, it will return them as: ([0, 3, 4, 1, 2], [‘a’, ‘d’, ‘e’, ‘b’, ‘c’], [1, 1, 1, 2, 2]).

Parameters:

data – A dictionary of regular expressions and values to match the strings in the list.
list_of_strings – A list of strings to match.
preserve_order – Whether to preserve the order of the query keys in the returned values. Defaults to False.

Returns:

A tuple of lists containing the matched indices, names, and values.

Raises:

TypeError – When the input argument data is not a dictionary.
ValueError – When multiple matches are found for a string in the dictionary.
ValueError – When not all regular expressions in the data keys are matched.

Timer operations#

Sub-module for a timer class that can be used for performance measurements.

Exceptions:

TimerError

A custom exception used to report errors in use of Timer class.

Classes:

Timer

A timer for performance measurements.

exception omni.isaac.orbit.utils.timer.TimerError[source]#

Bases: Exception

A custom exception used to report errors in use of Timer class.

class omni.isaac.orbit.utils.timer.Timer[source]#

Bases: ContextDecorator

A timer for performance measurements.

A class to keep track of time for performance measurement. It allows timing via context managers and decorators as well.

It uses the time.perf_counter function to measure time. This function returns the number of seconds since the epoch as a float. It has the highest resolution available on the system.

As a regular object:

import time

from omni.isaac.orbit.utils.timer import Timer

timer = Timer()
timer.start()
time.sleep(1)
print(1 <= timer.time_elapsed <= 2)  # Output: True

time.sleep(1)
timer.stop()
print(2 <= stopwatch.total_run_time)  # Output: True

As a context manager:

import time

from omni.isaac.orbit.utils.timer import Timer

with Timer() as timer:
    time.sleep(1)
    print(1 <= timer.time_elapsed <= 2)  # Output: True

Reference: https://gist.github.com/sumeet/1123871

Methods:

`__init__`([msg])	Initializes the timer.
`start`()	Start timing.
`stop`()	Stop timing.

Attributes:

`time_elapsed`	The number of seconds that have elapsed since this timer started timing.
`total_run_time`	The number of seconds that elapsed from when the timer started to when it ended.

__init__(msg: str | None = None)[source]#

Initializes the timer.

Parameters:: msg – The message to display when using the timer class in a context manager. Defaults to None.

property time_elapsed: float#: The number of seconds that have elapsed since this timer started timing.

Note

This is used for checking how much time has elapsed while the timer is still running.

property total_run_time: float#: The number of seconds that elapsed from when the timer started to when it ended.

start()[source]#: Start timing.

stop()[source]#: Stop timing.

Warp operations#

Sub-module containing operations based on warp.

Functions:

`convert_to_warp_mesh`(points, indices, device)	Create a warp mesh object with a mesh defined from vertices and triangles.
`raycast_mesh`(ray_starts, ray_directions, mesh)	Performs ray-casting against a mesh.

omni.isaac.orbit.utils.warp.convert_to_warp_mesh(points: numpy.ndarray, indices: numpy.ndarray, device: str) → warp.Mesh[source]#

Create a warp mesh object with a mesh defined from vertices and triangles.

Parameters:

points – The vertices of the mesh. Shape is (N, 3), where N is the number of vertices.
indices – The triangles of the mesh as references to vertices for each triangle. Shape is (M, 3), where M is the number of triangles / faces.
device – The device to use for the mesh.

Returns:

The warp mesh object.

omni.isaac.orbit.utils.warp.raycast_mesh(ray_starts: torch.Tensor, ray_directions: torch.Tensor, mesh: wp.Mesh, max_dist: float = 1000000.0, return_distance: bool = False, return_normal: bool = False, return_face_id: bool = False) → tuple[torch.Tensor, torch.Tensor | None, torch.Tensor | None, torch.Tensor | None][source]#

Performs ray-casting against a mesh.

Note that the ray_starts and ray_directions, and ray_hits should have compatible shapes and data types to ensure proper execution. Additionally, they all must be in the same frame.

Parameters:

ray_starts – The starting position of the rays. Shape (N, 3).
ray_directions – The ray directions for each ray. Shape (N, 3).
mesh – The warp mesh to ray-cast against.
max_dist – The maximum distance to ray-cast. Defaults to 1e6.
return_distance – Whether to return the distance of the ray until it hits the mesh. Defaults to False.
return_normal – Whether to return the normal of the mesh face the ray hits. Defaults to False.
return_face_id – Whether to return the face id of the mesh face the ray hits. Defaults to False.

Returns:

The ray hit position. Shape (N, 3).: The returned tensor contains float('inf') for missed hits.
The ray hit distance. Shape (N,).: Will only return if return_distance is True, else returns None. The returned tensor contains float('inf') for missed hits.
The ray hit normal. Shape (N, 3).: Will only return if return_normal is True else returns None. The returned tensor contains float('inf') for missed hits.
The ray hit face id. Shape (N,).: Will only return if return_face_id is True else returns None. The returned tensor contains int(-1) for missed hits.

orbit.utils

Contents

orbit.utils#

Configuration class#

IO operations#

Array operations#

Asset operations#

Dictionary operations#

Math operations#

Noise operations#

String operations#

Timer operations#

Warp operations#