Skip to content

xbarray.transformations.rotation_conversions.base

Functions:

Name Description
quaternion_to_matrix

Convert rotations given as quaternions to rotation matrices.

matrix_to_quaternion

Convert rotations given as rotation matrices to quaternions.

euler_angles_to_matrix

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

matrix_to_euler_angles

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

random_quaternions

Generate random quaternions representing rotations,

random_rotations

Generate random rotations as 3x3 rotation matrices.

random_rotation

Generate a single random 3x3 rotation matrix.

standardize_quaternion

Convert a unit quaternion to a standard form: one in which the real

quaternion_multiply

Multiply two quaternions representing rotations, returning the quaternion

quaternion_invert

Given a quaternion representing rotation, get the quaternion representing

quaternion_apply

Apply the rotation given by a quaternion to a 3D point.

axis_angle_to_matrix

Convert rotations given as axis/angle to rotation matrices.

matrix_to_axis_angle

Convert rotations given as rotation matrices to axis/angle.

axis_angle_to_quaternion

Convert rotations given as axis/angle to quaternions.

quaternion_to_axis_angle

Convert rotations given as quaternions to axis/angle.

rotation_6d_to_matrix

Converts 6D rotation representation by Zhou et al. [1] to rotation matrix

matrix_to_rotation_6d

Converts rotation matrices to 6D rotation representation by Zhou et al. [1]

quaternion_to_matrix

quaternion_to_matrix(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    quaternions: BArrayType,
) -> BArrayType

Convert rotations given as quaternions to rotation matrices.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
quaternions BArrayType

quaternions with real part first, as tensor of shape (..., 4).

required

Returns: Rotation matrices as tensor of shape (..., 3, 3).

matrix_to_quaternion

matrix_to_quaternion(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    matrix: BArrayType,
) -> BArrayType

Convert rotations given as rotation matrices to quaternions.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
matrix BArrayType

Rotation matrices as tensor of shape (..., 3, 3).

required

Returns:

Type Description
BArrayType

quaternions with real part first, as tensor of shape (..., 4).

euler_angles_to_matrix

euler_angles_to_matrix(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    euler_angles: BArrayType,
    convention: str,
) -> BArrayType

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

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
euler_angles BArrayType

Euler angles in radians as tensor of shape (..., 3).

required
convention str

Convention string of three uppercase letters from {"X", "Y", and "Z"}.

required

Returns:

Type Description
BArrayType

Rotation matrices as tensor of shape (..., 3, 3).

matrix_to_euler_angles

matrix_to_euler_angles(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    matrix: BArrayType,
    convention: str,
) -> BArrayType

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

Parameters:

Name Type Description Default
matrix BArrayType

Rotation matrices as tensor of shape (..., 3, 3).

required
convention str

Convention string of three uppercase letters.

required

Returns:

Type Description
BArrayType

Euler angles in radians as tensor of shape (..., 3).

random_quaternions

random_quaternions(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    rng: BRNGType,
    n: int,
    dtype: Optional[BDtypeType] = None,
    device: Optional[BDeviceType] = None,
) -> BArrayType

Generate random quaternions representing rotations, i.e. versors with nonnegative real part.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
rng BRNGType

A random number generator of the appropriate type for the backend.

required
n int

Number of quaternions in a batch to return.

required
dtype Optional[BDtypeType]

Type to return.

None
device Optional[BDeviceType]

Desired device of returned tensor. Default: uses the current device for the default tensor type.

None

Returns:

Type Description
BArrayType

Quaternions as tensor of shape (N, 4).

random_rotations

random_rotations(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    rng: BRNGType,
    n: int,
    dtype: Optional[BDtypeType] = None,
    device: Optional[BDeviceType] = None,
) -> BArrayType

Generate random rotations as 3x3 rotation matrices.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
rng BRNGType

A random number generator of the appropriate type for the backend.

required
n int

Number of rotation matrices in a batch to return.

required
dtype Optional[BDtypeType]

Type to return.

None
device Optional[BDeviceType]

Device of returned tensor. Default: if None, uses the current device for the default tensor type.

None

Returns:

Type Description
BArrayType

Rotation matrices as tensor of shape (n, 3, 3).

random_rotation

random_rotation(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    rng: BRNGType,
    dtype: Optional[BDtypeType] = None,
    device: Optional[BDeviceType] = None,
) -> BArrayType

Generate a single random 3x3 rotation matrix.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
rng BRNGType

A random number generator of the appropriate type for the backend.

required
dtype Optional[BDtypeType]

Type to return

None
device Optional[BDeviceType]

Device of returned tensor. Default: if None, uses the current device for the default tensor type

None

Returns:

Type Description
BArrayType

Rotation matrix as tensor of shape (3, 3).

standardize_quaternion

standardize_quaternion(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    quaternions: BArrayType,
) -> BArrayType

Convert a unit quaternion to a standard form: one in which the real part is non negative.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
quaternions BArrayType

Quaternions with real part first, as tensor of shape (..., 4).

required

Returns:

Type Description
BArrayType

Standardized quaternions as tensor of shape (..., 4).

quaternion_raw_multiply

quaternion_raw_multiply(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    a: BArrayType,
    b: BArrayType,
) -> BArrayType

Multiply two quaternions. Usual torch rules for broadcasting apply.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
a BArrayType

Quaternions as tensor of shape (..., 4), real part first.

required
b BArrayType

Quaternions as tensor of shape (..., 4), real part first.

required

Returns:

Type Description
BArrayType

The product of a and b, a tensor of quaternions shape (..., 4).

quaternion_multiply

quaternion_multiply(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    a: BArrayType,
    b: BArrayType,
) -> BArrayType

Multiply two quaternions representing rotations, returning the quaternion representing their composition, i.e. the versor with nonnegative real part. Usual torch rules for broadcasting apply.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
a BArrayType

Quaternions as tensor of shape (..., 4), real part first.

required
b BArrayType

Quaternions as tensor of shape (..., 4), real part first.

required

Returns:

Type Description
BArrayType

The product of a and b, a tensor of quaternions of shape (..., 4).

quaternion_invert

quaternion_invert(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    quaternion: BArrayType,
) -> BArrayType

Given a quaternion representing rotation, get the quaternion representing its inverse.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
quaternion BArrayType

Quaternions as tensor of shape (..., 4), with real part first, which must be versors (unit quaternions).

required

Returns:

Type Description
BArrayType

The inverse, a tensor of quaternions of shape (..., 4).

quaternion_apply

quaternion_apply(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    quaternion: BArrayType,
    point: BArrayType,
) -> BArrayType

Apply the rotation given by a quaternion to a 3D point. Usual torch rules for broadcasting apply.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
quaternion BArrayType

Tensor of quaternions, real part first, of shape (..., 4).

required
point BArrayType

Tensor of 3D points of shape (..., 3).

required

Returns:

Type Description
BArrayType

Tensor of rotated points of shape (..., 3).

axis_angle_to_matrix

axis_angle_to_matrix(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    axis_angle: BArrayType,
    fast: bool = False,
) -> BArrayType

Convert rotations given as axis/angle to rotation matrices.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
axis_angle BArrayType

Rotations given as a vector in axis angle form, as a tensor of shape (..., 3), where the magnitude is the angle turned anticlockwise in radians around the vector's direction.

required
fast bool

Whether to use the new faster implementation (based on the Rodrigues formula) instead of the original implementation (which first converted to a quaternion and then back to a rotation matrix).

False

Returns:

Type Description
BArrayType

Rotation matrices as tensor of shape (..., 3, 3).

matrix_to_axis_angle

matrix_to_axis_angle(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    matrix: BArrayType,
    fast: bool = False,
) -> BArrayType

Convert rotations given as rotation matrices to axis/angle.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
matrix BArrayType

Rotation matrices as tensor of shape (..., 3, 3).

required
fast bool

Whether to use the new faster implementation (based on the Rodrigues formula) instead of the original implementation (which first converted to a quaternion and then back to a rotation matrix).

False

Returns:

Type Description
BArrayType

Rotations given as a vector in axis angle form, as a tensor of shape (..., 3), where the magnitude is the angle turned anticlockwise in radians around the vector's direction.

axis_angle_to_quaternion

axis_angle_to_quaternion(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    axis_angle: BArrayType,
) -> BArrayType

Convert rotations given as axis/angle to quaternions.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
axis_angle BArrayType

Rotations given as a vector in axis angle form, as a tensor of shape (..., 3), where the magnitude is the angle turned anticlockwise in radians around the vector's direction.

required

Returns:

Type Description
BArrayType

quaternions with real part first, as tensor of shape (..., 4).

quaternion_to_axis_angle

quaternion_to_axis_angle(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    quaternions: BArrayType,
) -> BArrayType

Convert rotations given as quaternions to axis/angle.

Parameters:

Name Type Description Default
backend ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType]

The backend to use for the computation.

required
quaternions BArrayType

quaternions with real part first, as tensor of shape (..., 4).

required

Returns:

Type Description
BArrayType

Rotations given as a vector in axis angle form, as a tensor of shape (..., 3), where the magnitude is the angle turned anticlockwise in radians around the vector's direction.

rotation_6d_to_matrix

rotation_6d_to_matrix(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    d6: BArrayType,
) -> BArrayType

Converts 6D rotation representation by Zhou et al. [1] to rotation matrix using Gram--Schmidt orthogonalization per Section B of [1]. Args: backend: The backend to use for the computation. d6: 6D rotation representation, of size (*, 6)

Returns:

Type Description
BArrayType

batch of rotation matrices of size (*, 3, 3)

[1] Zhou, Y., Barnes, C., Lu, J., Yang, J., & Li, H. On the Continuity of Rotation Representations in Neural Networks. IEEE Conference on Computer Vision and Pattern Recognition, 2019. Retrieved from http://arxiv.org/abs/1812.07035

matrix_to_rotation_6d

matrix_to_rotation_6d(
    backend: ComputeBackend[BArrayType, BDeviceType, BDtypeType, BRNGType],
    matrix: BArrayType,
) -> BArrayType

Converts rotation matrices to 6D rotation representation by Zhou et al. [1] by dropping the last row. Note that 6D representation is not unique. Args: backend: The backend to use for the computation. matrix: batch of rotation matrices of size (*, 3, 3)

Returns:

Type Description
BArrayType

6D rotation representation, of size (*, 6)

[1] Zhou, Y., Barnes, C., Lu, J., Yang, J., & Li, H. On the Continuity of Rotation Representations in Neural Networks. IEEE Conference on Computer Vision and Pattern Recognition, 2019. Retrieved from http://arxiv.org/abs/1812.07035