xbarray.transformations.rotation_conversions¶
Modules:
| Name | Description |
|---|---|
base |
|
jax |
|
numpy |
|
pytorch |
|
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_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