embodichain.utils

Submodules

warp
configclass(cls, **kwargs)	Wrapper around dataclass functionality to add extra checks and utilities.
file
logger
math
module_utils
string
utility
visualizer

High Performance Computing with Warp

• embodichain.utils.warp

Configuration Classes

Functions:

class_to_dict(obj)	Convert an object into dictionary recursively.
combined_function(f1, f2)	Combine two functions into one.
configclass(cls, **kwargs)	Wrapper around dataclass functionality to add extra checks and utilities.
custom_post_init(obj)	Deepcopy all elements to avoid shared memory issues for mutable objects in dataclasses initialization.
is_configclass(cls)	Check if a class is a configclass.
update_class_from_dict(obj, data[, _ns])	Reads a dictionary and sets object variables recursively.

embodichain.utils.configclass.class_to_dict(obj)

Convert an object into dictionary recursively.

Note

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

Parameters:

obj (object) – An instance of a class to convert.

Raises:

ValueError – When input argument is not an object.

Return type:

dict[str, Any]

Returns:

Converted dictionary mapping.

embodichain.utils.configclass.combined_function(f1, f2)

Combine two functions into one.

Parameters:

• f1 (Callable) – The first function.

• f2 (Callable) – The second function.

Return type:

Callable

Returns:

The combined function.

embodichain.utils.configclass.configclass(cls, **kwargs)

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:

1. Requiring a type annotation for all its members.

2. 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 isaaclab.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.

Reference:

isaac-sim/IsaacLab

embodichain.utils.configclass.custom_post_init(obj)

Deepcopy all elements to avoid shared memory issues for mutable objects in dataclasses initialization.

This function is called explicitly instead of as a part of _process_mutable_types() to prevent mapping proxy type i.e. a read only proxy for mapping objects. The error is thrown when using hierarchical data-classes for configuration.

embodichain.utils.configclass.is_configclass(cls)

Check if a class is a configclass.

Parameters:

cls (Any) – The class to check.

Return type:

bool

Returns:

True if the class is a configclass, False otherwise.

embodichain.utils.configclass.update_class_from_dict(obj, data, _ns='')

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 (dict[str, Any]) – Input dictionary to update from.

• _ns (str) – 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.

Return type:

None

File Operations

Functions:

get_all_files_in_directory(directory[, ...])

Get all files in a directory with optional filtering by extensions or regex patterns.

embodichain.utils.file.get_all_files_in_directory(directory, exts=None, patterns=None)

Get all files in a directory with optional filtering by extensions or regex patterns.

Parameters:

• directory (str) – The directory to search for files.

• exts (Optional[List[str]]) – List of file extensions to filter by. If None, all files are returned.

• patterns (Optional[List[str]]) – List of regex patterns to match file names. If None, no pattern matching is applied.

Returns:

List of file paths in the directory matching the specified extensions or patterns.

Return type:

List[str]

Logging

Functions:

decorate_str_color(msg, color)	Decorate a string with a specific color.
format_message(level, message)	Format the log message with a consistent prefix.
log_debug(message[, color])	Log a debug message.
log_error(message[, error_type])	Log an error message.
log_info(message[, color])	Log an info message.
log_warning(message)	Log a warning message.
set_log_level(level)	Set the logging level.

embodichain.utils.logger.decorate_str_color(msg, color)

Decorate a string with a specific color.

embodichain.utils.logger.format_message(level, message)

Format the log message with a consistent prefix.

embodichain.utils.logger.log_debug(message, color='blue')

Log a debug message.

embodichain.utils.logger.log_error(message, error_type=<class 'RuntimeError'>)

Log an error message.

embodichain.utils.logger.log_info(message, color=None)

Log an info message.

embodichain.utils.logger.log_warning(message)

Log a warning message.

embodichain.utils.logger.set_log_level(level)

Set the logging level.

Mathematical Operations

Functions:

compute_pose_error(t01, q01, t02, q02[, ...])	Compute the position and orientation error between source and target frames.
convert_camera_frame_orientation_convention(...)	Converts a quaternion representing a rotation from one convention to another.
convert_quat(quat[, to])	Converts quaternion from one convention to another.
create_rotation_matrix_from_view(eyes, targets)	Compute the rotation matrix from world to view coordinates.
generate_random_rotation([rot_boundary])	Generates a random rotation matrix using Euler angles.
generate_random_transformation_matrix([...])	Generates a random transformation matrix combining rotation and translation.
generate_random_translation([pos_boundary])	Generates a random translation vector.
interpolate_poses(pose_1, pose_2[, ...])	Performs linear interpolation between two poses.
interpolate_rotations(R1, R2, num_steps[, ...])	Interpolates between two rotation matrices.
is_identity_pose(pos, rot)	Checks if input poses are identity transforms.
look_at_to_pose(eye, target[, up])	Get the camera pose from eye to target with up direction, supporting batch processing.
make_pose(pos, rot)	Creates transformation matrices from positions and rotation matrices.
matrix_from_euler(euler_angles[, convention])	Convert rotations given as Euler angles (intrinsic) in radians to rotation matrices.
pose_in_A_to_pose_in_B(pose_in_A, pose_A_in_B)	Converts poses from one coordinate frame to another.
pose_inv(pose)	Computes the inverse of transformation matrices.
quat_slerp(q1, q2, tau)	Performs spherical linear interpolation (SLERP) between two quaternions.
rigid_body_twist_transform(v0, w0, t01, q01)	Transform the linear and angular velocity of a rigid body between reference frames.
sample_cylinder(radius, h_range, size, device)	Sample 3D points uniformly on a cylinder's surface.
sample_gaussian(mean, std, size, device)	Sample using gaussian distribution.
sample_log_uniform(lower, upper, size, device)	Sample using log-uniform distribution within a range.
sample_triangle(lower, upper, size, device)	Randomly samples tensor from a triangular distribution.
sample_uniform(lower, upper, size)	Sample uniformly within a range.
subtract_frame_transforms(t01, q01[, t02, q02])	Subtract transformations between two reference frames into a stationary frame.
trans_matrix_to_xyz_quat(matrix)	Convert a (4, 4) pose transformation matrix ((R, t), (0, 1)) to a 7D pose vector.
transform_points(points[, pos, quat])	Transform input points in a given frame to a target frame.
transform_poses_from_frame_A_to_frame_B(...)	Transforms poses from one coordinate frame to another preserving relative poses.
unmake_pose(pose)	Splits transformation matrices into positions and rotation matrices.
xyz_quat_to_4x4_matrix(xyz_quat)	Convert a 7D pose vector (x, y, z, qw, qx, qy, qz) to a 4x4 transformation matrix.

embodichain.utils.math.compute_pose_error(t01, q01, t02, q02, rot_error_type='axis_angle')

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

Parameters:

• t01 (Tensor) – Position of source frame. Shape is (N, 3).

• q01 (Tensor) – Quaternion orientation of source frame in (w, x, y, z). Shape is (N, 4).

• t02 (Tensor) – Position of target frame. Shape is (N, 3).

• q02 (Tensor) – Quaternion orientation of target frame in (w, x, y, z). Shape is (N, 4).

• rot_error_type (Literal['quat', 'axis_angle']) – The rotation error type to return: “quat”, “axis_angle”. Defaults to “axis_angle”.

Return type:

tuple[Tensor, Tensor]

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.

embodichain.utils.math.convert_camera_frame_orientation_convention(orientation, origin='opengl', target='ros')

Converts a quaternion representing a rotation from one convention to another.

In USD, the camera follows the "opengl" convention. Thus, it is always in Y up convention. This means that the camera is looking down the -Z axis with the +Y axis pointing up , and +X axis pointing right. However, in ROS, the camera is looking down the +Z axis with the +Y axis pointing down, and +X axis pointing right. Thus, the camera needs to be rotated by \(180^{\circ}\) around the X axis to follow the ROS convention.

\[\begin{split}T_{ROS} = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & -1 & 0 & 0 \\ 0 & 0 & -1 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix} T_{USD}\end{split}\]

On the other hand, the typical world coordinate system is with +X pointing forward, +Y pointing left, and +Z pointing up. The camera can also be set in this convention by rotating the camera by \(90^{\circ}\) around the X axis and \(-90^{\circ}\) around the Y axis.

\[\begin{split}T_{WORLD} = \begin{bmatrix} 0 & 0 & -1 & 0 \\ -1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 1 \end{bmatrix} T_{USD}\end{split}\]

Thus, based on their application, cameras follow different conventions for their orientation. This function converts a quaternion from one convention to another.

Possible conventions are:

• "opengl" - forward axis: -Z - up axis +Y - Offset is applied in the OpenGL (Usd.Camera) convention

• "ros" - forward axis: +Z - up axis -Y - Offset is applied in the ROS convention

• "world" - forward axis: +X - up axis +Z - Offset is applied in the World Frame convention

Parameters:

• orientation (Tensor) – Quaternion of form (w, x, y, z) with shape (…, 4) in source convention.

• origin (Literal['opengl', 'ros', 'world']) – Convention to convert from. Defaults to “opengl”.

• target (Literal['opengl', 'ros', 'world']) – Convention to convert to. Defaults to “ros”.

Return type:

Tensor

Returns:

Quaternion of form (w, x, y, z) with shape (…, 4) in target convention

embodichain.utils.math.convert_quat(quat, to='xyzw')

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 (Union[Tensor, ndarray]) – The quaternion of shape (…, 4).

• to (Literal['xyzw', 'wxyz']) – Convention to convert quaternion to.. Defaults to “xyzw”.

Return type:

Union[Tensor, ndarray]

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

embodichain.utils.math.create_rotation_matrix_from_view(eyes, targets, up_axis='Z', device='cpu')

Compute the rotation matrix from world to view coordinates.

This function takes a vector ‘’eyes’’ which specifies the location of the camera in world coordinates and the vector ‘’targets’’ which indicate the position of the object. The output is a rotation matrix representing the transformation from world coordinates -> view coordinates.

The inputs eyes and targets can each be a - 3 element tuple/list - torch tensor of shape (1, 3) - torch tensor of shape (N, 3)

Parameters:

• eyes (Tensor) – Position of the camera in world coordinates.

• targets (Tensor) – Position of the object in world coordinates.

• up_axis (Literal['Y', 'Z']) – The up axis of the camera. Defaults to “Z”.

• device (str) – The device to create torch tensors on. Defaults to “cpu”.

The vectors are broadcast against each other so they all have shape (N, 3).

Returns:

(N, 3, 3) batched rotation matrices

Return type:

R

Reference: Based on PyTorch3D (facebookresearch/pytorch3d)

embodichain.utils.math.generate_random_rotation(rot_boundary=6.283185307179586)

Generates a random rotation matrix using Euler angles.

Parameters:

rot_boundary (float) – Range for random rotation angles around each axis (x, y, z).

Return type:

Tensor

Returns:

3x3 rotation matrix.

embodichain.utils.math.generate_random_transformation_matrix(pos_boundary=1, rot_boundary=6.283185307179586)

Generates a random transformation matrix combining rotation and translation.

Parameters:

• pos_boundary (float) – Range for random translation values.

• rot_boundary (float) – Range for random rotation angles.

Return type:

Tensor

Returns:

4x4 transformation matrix.

embodichain.utils.math.generate_random_translation(pos_boundary=1)

Generates a random translation vector.

Parameters:

pos_boundary (float) – Range for random translation values in 3D space.

Return type:

Tensor

Returns:

3-element translation vector.

embodichain.utils.math.interpolate_poses(pose_1, pose_2, num_steps=None, step_size=None, perturb=False)

Performs linear interpolation between two poses.

Parameters:

• pose_1 (Tensor) – 4x4 start pose.

• pose_2 (Tensor) – 4x4 end pose.

• num_steps (Optional[int]) – If provided, specifies the number of desired interpolated points. Passing 0 corresponds to no interpolation. If None, step_size must be provided.

• step_size (Optional[float]) – If provided, determines number of steps based on distance between poses.

• perturb (bool) – If True, randomly perturbs interpolated position points.

Returns:

• Array of shape (N + 2, 4, 4) corresponding to the interpolated pose path.

• Number of interpolated points (N) in the path.

Return type:

Tuple containing

embodichain.utils.math.interpolate_rotations(R1, R2, num_steps, axis_angle=True)

Interpolates between two rotation matrices.

Parameters:

• R1 (Tensor) – First rotation matrix. (4x4).

• R2 (Tensor) – Second rotation matrix. (4x4).

• num_steps (int) – Number of desired interpolated rotations (excluding start and end).

• axis_angle (bool) – If True, interpolate in axis-angle representation; otherwise use slerp. Defaults to True.

Return type:

Tensor

Returns:

Stack of interpolated rotation matrices of shape (num_steps + 1, 4, 4), including the start and end rotations.

embodichain.utils.math.is_identity_pose(pos, rot)

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 (tensor) – The cartesian position. Shape is (N, 3).

• rot (tensor) – The quaternion in (w, x, y, z). Shape is (N, 4).

Return type:

bool

Returns:

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

embodichain.utils.math.look_at_to_pose(eye, target, up=[0, 0, 1])

Get the camera pose from eye to target with up direction, supporting batch processing.

Parameters:

• eye (Union[torch.Tensor, list]) – Camera positions with shape (N, 3).

• target (Union[torch.Tensor, list]) – Target positions with shape (N, 3).

• up (Union[torch.Tensor, list], optional) – Up directions with shape (N, 3) or (3,). Defaults to [0, 0, 1].

Returns:

Camera pose matrices with shape (N, 4, 4).

Return type:

torch.Tensor

embodichain.utils.math.make_pose(pos, rot)

Creates transformation matrices from positions and rotation matrices.

Parameters:

• pos (Tensor) – Batch of position vectors with last dimension of 3.

• rot (Tensor) – Batch of rotation matrices with last 2 dimensions of (3, 3).

Return type:

Tensor

Returns:

Batch of pose matrices with last 2 dimensions of (4, 4).

embodichain.utils.math.matrix_from_euler(euler_angles, convention='XYZ')

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

Parameters:

• euler_angles (Tensor) – Euler angles in radians. Shape is (…, 3).

• convention (str) – 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. Defaults to “XYZ”.

Return type:

Tensor

Returns:

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

Reference:

facebookresearch/pytorch3d

embodichain.utils.math.pose_in_A_to_pose_in_B(pose_in_A, pose_A_in_B)

Converts poses from one coordinate frame to another.

Transforms matrices representing point C in frame A to matrices representing the same point C in frame B.

Example usage:

frame_C_in_B = pose_in_A_to_pose_in_B(frame_C_in_A, frame_A_in_B)

Parameters:

• pose_in_A (Tensor) – Batch of transformation matrices of point C in frame A.

• pose_A_in_B (Tensor) – Batch of transformation matrices of frame A in frame B.

Return type:

Tensor

Returns:

Batch of transformation matrices of point C in frame B.

embodichain.utils.math.pose_inv(pose)

Computes the inverse of transformation matrices.

The inverse of a pose matrix [R t; 0 1] is [R.T -R.T*t; 0 1].

Parameters:

pose (Tensor) – Batch of pose matrices with last 2 dimensions of (4, 4).

Return type:

Tensor

Returns:

Batch of inverse pose matrices with last 2 dimensions of (4, 4).

embodichain.utils.math.quat_slerp(q1, q2, tau)

Performs spherical linear interpolation (SLERP) between two quaternions.

This function does not support batch processing.

Parameters:

• q1 (Tensor) – First quaternion in (w, x, y, z) format.

• q2 (Tensor) – Second quaternion in (w, x, y, z) format.

• tau (float) – Interpolation coefficient between 0 (q1) and 1 (q2).

Return type:

Tensor

Returns:

Interpolated quaternion in (w, x, y, z) format.

embodichain.utils.math.rigid_body_twist_transform(v0, w0, t01, q01)

Transform the linear and angular velocity of a rigid body between reference frames.

Given the twist of 0 relative to frame 0, this function computes the twist of 1 relative to frame 1 from the position and orientation of frame 1 relative to frame 0. The transformation follows the equations:

\[w_11 = R_{10} w_00 = R_{01}^{-1} w_00 v_11 = R_{10} v_00 + R_{10} (w_00 \times t_01) = R_{01}^{-1} (v_00 + (w_00 \times t_01))\]

where

• \(R_{01}\) is the rotation matrix from frame 0 to frame 1 derived from quaternion \(q_{01}\).

• \(t_{01}\) is the position of frame 1 relative to frame 0 expressed in frame 0

• \(w_0\) is the angular velocity of 0 in frame 0

• \(v_0\) is the linear velocity of 0 in frame 0

Parameters:

• v0 (Tensor) – Linear velocity of 0 in frame 0. Shape is (N, 3).

• w0 (Tensor) – Angular velocity of 0 in frame 0. Shape is (N, 3).

• t01 (Tensor) – Position of frame 1 w.r.t. frame 0. Shape is (N, 3).

• q01 (Tensor) – Quaternion orientation of frame 1 w.r.t. frame 0 in (w, x, y, z). Shape is (N, 4).

Returns:

• The transformed linear velocity in frame 1. Shape is (N, 3).

• The transformed angular velocity in frame 1. Shape is (N, 3).

Return type:

A tuple containing

embodichain.utils.math.sample_cylinder(radius, h_range, size, device)

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 (float) – The radius of the cylinder.

• h_range (tuple[float, float]) – The minimum and maximum height of the cylinder.

• size (Union[int, tuple[int, ...]]) – The shape of the tensor.

• device (str) – Device to create tensor on.

Return type:

Tensor

Returns:

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

embodichain.utils.math.sample_gaussian(mean, std, size, device)

Sample using gaussian distribution.

Parameters:

• mean (Union[Tensor, float]) – Mean of the gaussian.

• std (Union[Tensor, float]) – Std of the gaussian.

• size (Union[int, tuple[int, ...]]) – The shape of the tensor.

• device (str) – Device to create tensor on.

Return type:

Tensor

Returns:

Sampled tensor.

embodichain.utils.math.sample_log_uniform(lower, upper, size, device)

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 (Union[Tensor, float]) – Lower bound of uniform range.

• upper (Union[Tensor, float]) – Upper bound of uniform range.

• size (Union[int, tuple[int, ...]]) – The shape of the tensor.

• device (str) – Device to create tensor on.

Return type:

Tensor

Returns:

Sampled tensor. Shape is based on size.

embodichain.utils.math.sample_triangle(lower, upper, size, device)

Randomly samples tensor from a triangular distribution.

Parameters:

• lower (float) – The lower range of the sampled tensor.

• upper (float) – The upper range of the sampled tensor.

• size (Union[int, tuple[int, ...]]) – The shape of the tensor.

• device (str) – Device to create tensor on.

Return type:

Tensor

Returns:

Sampled tensor. Shape is based on size.

embodichain.utils.math.sample_uniform(lower, upper, size)

Sample uniformly within a range.

Parameters:

• lower (Union[Tensor, float]) – Lower bound of uniform range.

• upper (Union[Tensor, float]) – Upper bound of uniform range.

• size (Union[int, tuple[int, ...]]) – The shape of the tensor.

• device – Device to create tensor on.

Return type:

Tensor

Returns:

Sampled tensor. Shape is based on size.

embodichain.utils.math.subtract_frame_transforms(t01, q01, t02=None, q02=None)

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 (Tensor) – Position of frame 1 w.r.t. frame 0. Shape is (N, 3).

• q01 (Tensor) – Quaternion orientation of frame 1 w.r.t. frame 0 in (w, x, y, z). Shape is (N, 4).

• t02 (Optional[Tensor]) – 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 (Optional[Tensor]) – 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.

Return type:

tuple[Tensor, Tensor]

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.

embodichain.utils.math.trans_matrix_to_xyz_quat(matrix)

Convert a (4, 4) pose transformation matrix ((R, t), (0, 1)) to a 7D pose vector.

Parameters:

matrix (Tensor) – The pose transformation matrix in ((R, t), (0, 1)). Shape is (…, 4, 4).

Return type:

Tensor

Returns:

The pose vector in (x, y, z, qw, qx, qy, qz). Shape is (…, 7).

embodichain.utils.math.transform_points(points, pos=None, quat=None)

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 (Tensor) – Points to transform. Shape is (N, P, 3) or (P, 3).

• pos (Optional[Tensor]) – 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 (Optional[Tensor]) – 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.

Return type:

Tensor

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

embodichain.utils.math.transform_poses_from_frame_A_to_frame_B(src_poses, frame_A, frame_B)

Transforms poses from one coordinate frame to another preserving relative poses.

Parameters:

• src_poses (Tensor) – Input pose sequence (shape [T, 4, 4]) from source demonstration.

• frame_A (Tensor) – 4x4 frame A pose.

• frame_B (Tensor) – 4x4 frame B pose.

Return type:

Tensor

Returns:

Transformed pose sequence of shape [T, 4, 4].

embodichain.utils.math.unmake_pose(pose)

Splits transformation matrices into positions and rotation matrices.

Parameters:

pose (Tensor) – Batch of pose matrices with last 2 dimensions of (4, 4).

Returns:

• Batch of position vectors with last dimension of 3.

• Batch of rotation matrices with last 2 dimensions of (3, 3).

Return type:

Tuple containing

embodichain.utils.math.xyz_quat_to_4x4_matrix(xyz_quat)

Convert a 7D pose vector (x, y, z, qw, qx, qy, qz) to a 4x4 transformation matrix.

Parameters:

xyz_quat (Tensor) – The pose vector in (x, y, z, qw, qx, qy, qz). Shape is (…, 7).

Return type:

Tensor

Returns:

The transformation matrix. Shape is (…, 4, 4).

Module Utilities

Functions:

find_class_from_modules(class_name, modules)	Find a class from multiple Python modules.
find_function_by_pattern(pattern, modules[, ...])	Find functions matching a pattern from multiple modules.
find_function_from_modules(function_name, ...)	Find a function from multiple Python modules.
get_all_exported_items_from_module(module)	Get all exported items from a module by checking its __all__ attribute.
get_all_functions_from_module(module)	Get all functions from a module.

embodichain.utils.module_utils.find_class_from_modules(class_name, modules, raise_if_not_found=True)

Find a class from multiple Python modules.

Parameters:

• class_name (str) – Name of the class to find

• modules (List[Union[str, Any]]) – List of module names (strings) or module objects

• raise_if_not_found (bool) – Whether to raise an exception if class is not found

Returns:

The class if found, None otherwise

Return type:

Optional[type]

Raises:

• AttributeError – If class is not found and raise_if_not_found is True

• ImportError – If a module cannot be imported

embodichain.utils.module_utils.find_function_by_pattern(pattern, modules, case_sensitive=True)

Find functions matching a pattern from multiple modules.

Parameters:

• pattern (str) – Pattern to match (supports wildcards * and ?)

• modules (List[Union[str, Any]]) – List of module names or module objects

• case_sensitive (bool) – Whether the search should be case sensitive

Returns:

Dictionary mapping module names to dictionaries of matching functions

Return type:

dict

embodichain.utils.module_utils.find_function_from_modules(function_name, modules, raise_if_not_found=True)

Find a function from multiple Python modules.

Parameters:

• function_name (str) – Name of the function to find

• modules (List[Union[str, Any]]) – List of module names (strings) or module objects

• raise_if_not_found (bool) – Whether to raise an exception if function is not found

Returns:

The function if found, None otherwise

Return type:

Optional[Callable]

Raises:

• AttributeError – If function is not found and raise_if_not_found is True

• ImportError – If a module cannot be imported

embodichain.utils.module_utils.get_all_exported_items_from_module(module)

Get all exported items from a module by checking its __all__ attribute.

Parameters:

module (Union[str, Any]) – Module name (string) or module object

Returns:

List of exported item names

Return type:

List[str]

embodichain.utils.module_utils.get_all_functions_from_module(module)

Get all functions from a module.

Parameters:

module (Union[str, Any]) – Module name (string) or module object

Returns:

Dictionary mapping function names to function objects

Return type:

dict

String Operations

Functions:

callable_to_string(value)	Converts a callable object to a string.
is_lambda_expression(name)	Checks if the input string is a lambda expression.
is_regular_expression(pattern)	Checks if the input string is a valid regular expression.
remove_regex_chars(pattern)	Remove common regex metacharacters from the input pattern.
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.
string_to_callable(name)	Resolves the module and function names to return the function.

embodichain.utils.string.callable_to_string(value)

Converts a callable object to a string.

Parameters:

value (Callable) – A callable object.

Raises:

ValueError – When the input argument is not a callable object.

Return type:

str

Returns:

A string representation of the callable object.

embodichain.utils.string.is_lambda_expression(name)

Checks if the input string is a lambda expression.

Parameters:

name (str) – The input string.

Return type:

bool

Returns:

Whether the input string is a lambda expression.

embodichain.utils.string.is_regular_expression(pattern)

Checks if the input string is a valid regular expression. :type pattern: str :param pattern: The input string to check.

Returns:

True if the input string is a valid regular expression, False otherwise.

Return type:

bool

embodichain.utils.string.remove_regex_chars(pattern)

Remove common regex metacharacters from the input pattern. :type pattern: str :param pattern: The input string pattern.

Return type:

str

Returns:

The cleaned pattern with regex metacharacters removed.

embodichain.utils.string.resolve_matching_names(keys, list_of_strings, preserve_order=False)

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 (Union[str, Sequence[str]]) – A regular expression or a list of regular expressions to match the strings in the list.

• list_of_strings (Sequence[str]) – A list of strings to match.

• preserve_order (bool) – Whether to preserve the order of the query keys in the returned values. Defaults to False.

Return type:

tuple[list[int], list[str]]

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.

embodichain.utils.string.resolve_matching_names_values(data, list_of_strings, preserve_order=False)

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 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 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 (dict[str, Any]) – A dictionary of regular expressions and values to match the strings in the list.

• list_of_strings (Sequence[str]) – A list of strings to match.

• preserve_order (bool) – Whether to preserve the order of the query keys in the returned values. Defaults to False.

Return type:

tuple[list[int], list[str], list[Any]]

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.

Reference: isaac-sim/IsaacLab

embodichain.utils.string.string_to_callable(name)

Resolves the module and function names to return the function.

Parameters:

name (str) – 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

General Utilities

Classes:

TagDecorator

Functions:

center_crop(img, dim)	Returns center cropped image Args: img: image to be center cropped dim: dimensions (width, height) to be cropped
change_nested_dict(dict, keys[, mode, value])	Update or delete a nested dictionary at a specific key.
check_shared_memory_exists(name)
class_to_dict(obj)	Convert an object into dictionary recursively.
convert_bytes(d)
create_video_writer(video_path, resolution, fps)
dict2args(d)
do_process_decorator([pre_process, post_process])	A decorator to decorate inference().
encode_image(image[, format])
encode_image_from_path(image_path)
get_class_instance(module_name, class_name, ...)	Get an instance of a class from a module.
get_func_tag(tagName)
get_mesh_md5(mesh)	get mesh md5 unique key
get_random_real_image(base_path[, read])
get_right_name(name)
inv_transform(transform)	inverse transformation
key_in_nested_dict(d, key)	Check if a key exists in a nested dictionary.
load_json(path)
load_pkl(path)
load_txt(path)
mask_to_box(mask)
pad_img_list(img_list, max_len)
pad_to_chunk(x, chunk_size)
padding_by_longest_edge(img)
parser2dict(args)
postprocess_small_regions(masks, min_area, ...)	Filter masks based on area constraints.
read_all_folder_images(base_path)	Read all images from all subfolders under the base path.
read_video(video_path)
remove_overlap_mask(masks[, ...])
reset_all_seeds([seed])
save_json(path, data)
save_pkl(path, content)
scale_image(image[, scale])
set_attributes_for_class(self[, params])
set_texture_to_material(material, texture, env)
snake_to_camel(name)
timer(func)
update_array(mat, vec[, first_is_latest])

class embodichain.utils.utility.TagDecorator

Bases: object

Methods:

__init__(tagName)

__init__(tagName)

embodichain.utils.utility.center_crop(img, dim)

Returns center cropped image Args: img: image to be center cropped dim: dimensions (width, height) to be cropped

Return type:

ndarray

embodichain.utils.utility.change_nested_dict(dict, keys, mode='update', value=None)

Update or delete a nested dictionary at a specific key.

Parameters:

• dict (dict) – The dictionary to update.

• keys (tuple) – Tuple of keys to the target value.

• mode (str) – Whether to delete or remove the given key-value pair.

• value – The new value to set.

Returns:

The updated dictionary.

Return type:

dict

embodichain.utils.utility.check_shared_memory_exists(name)

embodichain.utils.utility.class_to_dict(obj)

Convert an object into dictionary recursively.

Note

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

Parameters:

obj (object) – An instance of a class to convert.

Raises:

ValueError – When input argument is not an object.

Return type:

dict[str, Any]

Returns:

Converted dictionary mapping.

embodichain.utils.utility.convert_bytes(d)

embodichain.utils.utility.create_video_writer(video_path, resolution, fps)

Return type:

VideoWriter

embodichain.utils.utility.dict2args(d)

Return type:

ArgumentParser

embodichain.utils.utility.do_process_decorator(pre_process=True, post_process=True)

A decorator to decorate inference(). Usage and example is comming soon.

Parameters:

• pre_process (Optional[bool], optional) – whether do pre-process. Defaults to True.

• post_process (Optional[bool], optional) – whether do post-process. Defaults to True.

embodichain.utils.utility.encode_image(image, format='png')

embodichain.utils.utility.encode_image_from_path(image_path)

embodichain.utils.utility.get_class_instance(module_name, class_name, *args, **kwargs)

Get an instance of a class from a module.

Parameters:

• module_name (str) – The name of the module to import.

• class_name (str) – The name of the class to instantiate.

Returns:

An instance of the specified class.

Return type:

object

embodichain.utils.utility.get_func_tag(tagName)

embodichain.utils.utility.get_mesh_md5(mesh)

get mesh md5 unique key

Parameters:

mesh (o3d.geometry.TriangleMesh) – mesh

Returns:

mesh md5 value.

Return type:

str

embodichain.utils.utility.get_random_real_image(base_path, read=True)

Return type:

ndarray

embodichain.utils.utility.get_right_name(name)

embodichain.utils.utility.inv_transform(transform)

inverse transformation

Parameters:

transform (np.array) – [np.array of size [4 x 4]]

Returns:

[np.array of size [4 x 4]]

Return type:

np.array

embodichain.utils.utility.key_in_nested_dict(d, key)

Check if a key exists in a nested dictionary.

Parameters:

• d (Dict) – A dictionary that may contain nested dictionaries.

• key (str) – The key to search for in the dictionary.

Returns:

True if the key exists in the dictionary or any of its nested dictionaries, False otherwise.

Return type:

bool

embodichain.utils.utility.load_json(path)

Return type:

Dict

embodichain.utils.utility.load_pkl(path)

embodichain.utils.utility.load_txt(path)

Return type:

str

embodichain.utils.utility.mask_to_box(mask)

Return type:

ndarray

embodichain.utils.utility.pad_img_list(img_list, max_len)

embodichain.utils.utility.pad_to_chunk(x, chunk_size)

Return type:

ndarray

embodichain.utils.utility.padding_by_longest_edge(img)

Return type:

ndarray

embodichain.utils.utility.parser2dict(args)

Return type:

Dict

embodichain.utils.utility.postprocess_small_regions(masks, min_area, max_area)

Filter masks based on area constraints.

Parameters:

• masks (ndarray) – Array of binary masks or list of masks.

• min_area (int) – Minimum area threshold (exclusive - areas must be strictly greater).

• max_area (int) – Maximum area threshold (inclusive - areas can equal this value).

Return type:

List[int]

Returns:

List of indices for masks that meet the area constraints (min_area < area <= max_area).

embodichain.utils.utility.read_all_folder_images(base_path)

Read all images from all subfolders under the base path.

Parameters:

base_path (str) – The base directory containing subfolders with images.

Returns:

A list of images read from the subfolders.

Return type:

List[np.ndarray]

embodichain.utils.utility.read_video(video_path)

embodichain.utils.utility.remove_overlap_mask(masks, keep_inner_threshold=0.5, eps=1e-05)

Return type:

List[int]

embodichain.utils.utility.reset_all_seeds(seed=0)

embodichain.utils.utility.save_json(path, data)

embodichain.utils.utility.save_pkl(path, content)

embodichain.utils.utility.scale_image(image, scale=0.5)

embodichain.utils.utility.set_attributes_for_class(self, params=None)

embodichain.utils.utility.set_texture_to_material(material, texture, env, type='color')

embodichain.utils.utility.snake_to_camel(name)

embodichain.utils.utility.timer(func)

embodichain.utils.utility.update_array(mat, vec, first_is_latest=True)

Return type:

ndarray

Visualization

Classes:

Gantt	Gantt Class to render a simple Gantt chart, with optional milestones
HeatMapEnv
Package	Encapsulation of a work package

Functions:

draw_action_distribution(actions[, indices, ...])
draw_feature(feature_list, vis_images)
draw_keypoints(rgb, keypoints_2d[, color_dict])
visualize_trajectory(poses)	Visualizes a 3D trajectory and its z-axis directions.

class embodichain.utils.visualizer.Gantt

Bases: object

Gantt Class to render a simple Gantt chart, with optional milestones

Methods:

__init__(dict)	Instantiation
add_legend()	Add a legend to the plot iff there are legend entries in the package definitions
add_milestones()	Add milestones to GANTT chart.
format()	Format various aspect of the plot, such as labels,ticks, BBox :todo: Refactor to use a settings object
render()	Prepare data for plotting
save([saveFile])	Save the plot to a file.
show()	Show the plot

__init__(dict)

Instantiation

Create a new Gantt using the data in the file provided or the sample data that came along with the script

Parameters:

dataFile (str) – file holding Gantt data

add_legend()

Add a legend to the plot iff there are legend entries in the package definitions

add_milestones()

Add milestones to GANTT chart. The milestones are simple yellow diamonds

format()

Format various aspect of the plot, such as labels,ticks, BBox :todo: Refactor to use a settings object

render()

Prepare data for plotting

static save(saveFile='img/GANTT.png')

Save the plot to a file. It defaults to img/GANTT.png.

Parameters:

saveFile (str) – file to save to

static show()

Show the plot

class embodichain.utils.visualizer.HeatMapEnv

Bases: object

Methods:

__init__(is_success)	Initialize the drawing environment and static elements
save_map()
update_heatmap(new_point, new_fail)

__init__(is_success)

Initialize the drawing environment and static elements

save_map()

update_heatmap(new_point, new_fail)

class embodichain.utils.visualizer.Package

Bases: object

Encapsulation of a work package

A work package is instantiated from a dictionary. It has to have a label, astart and an end. Optionally it may contain milestones and a color

Parameters:

pkg (str) – dictionary w/ package data name

Methods:

__init__(pkg)

__init__(pkg)

embodichain.utils.visualizer.draw_action_distribution(actions, indices=None, output_path=None, smooth=False, return_data=False)

embodichain.utils.visualizer.draw_feature(feature_list, vis_images)

Return type:

List[ndarray]

embodichain.utils.visualizer.draw_keypoints(rgb, keypoints_2d, color_dict=None)

Return type:

ndarray

embodichain.utils.visualizer.visualize_trajectory(poses)

Visualizes a 3D trajectory and its z-axis directions.

This function takes a series of 4x4 transformation matrices representing poses in 3D space and visualizes the trajectory along with the z-axis directions at each pose.

Parameters:

poses (np.ndarray) – A numpy array of shape (N, 4, 4), where N is the number of poses. Each pose is a 4x4 transformation matrix.