fastdev.xform.rotation¶

Module Contents¶

fastdev.xform.rotation.random_rotation_matrix(num: int | None = None, random_state: int | numpy.random.Generator | numpy.random.RandomState | None = None, return_tensors: Literal['np', 'pt'] = 'np')[source]¶

Parameters:

num (Optional[int])
random_state (Optional[Union[int, numpy.random.Generator, numpy.random.RandomState]])
return_tensors (Literal['np', 'pt'])

fastdev.xform.rotation.split_axis_angle_vector(axis_angle)[source]¶

fastdev.xform.rotation.compose_axis_angle_vector(axis, angle)[source]¶

fastdev.xform.rotation.axis_angle_vector_to_quaternion(axis_angle)[source]¶

Convert rotations given as axis/angle to quaternions.

Parameters:: axis_angle – 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.
Returns:: quaternions with real part first, as tensor of shape (…, 4).

Reference: https://en.wikipedia.org/wiki/Axis%E2%80%93angle_representation#Unit_quaternions

fastdev.xform.rotation.quaternion_to_axis_angle_vector(quaternions)[source]¶

Convert rotations given as quaternions to axis/angle.

Parameters:

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

Returns:

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.

Reference: https://en.wikipedia.org/wiki/Axis%E2%80%93angle_representation#Unit_quaternions

fastdev.xform.rotation.standardize_quaternion(quaternions: torch.Tensor) → torch.Tensor[source]¶

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

Parameters:: quaternions (torch.Tensor) – Quaternions with real part first, as tensor of shape (…, 4).
Returns:: Standardized quaternions as tensor of shape (…, 4).
Return type:: torch.Tensor

fastdev.xform.rotation.quaternion_real_to_last(quaternions)[source]¶

fastdev.xform.rotation.quaternion_real_to_first(quaternions)[source]¶

fastdev.xform.rotation.quaternion_to_matrix(quaternions: torch.Tensor) → torch.Tensor[source]¶

Convert rotations given as quaternions to rotation matrices.

Parameters:: quaternions (Tensor) – quaternions with real part first with shape (…, 4).
Returns:: Rotation matrices as tensor of shape (…, 3, 3).
Return type:: Tensor

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

fastdev.xform.rotation.matrix_to_quaternion(matrix: jaxtyping.Float[torch.Tensor, ... 3 3]) → jaxtyping.Float[torch.Tensor, ... 4][source]¶

Convert rotation matrices to quaternions using Shepperds’s method.

Parameters:: matrix (jaxtyping.Float[torch.Tensor, ... 3 3]) – (np.ndarray, torch.Tensor): rotation matrices, the shape could be …3x3.
Returns:: quaternions with real part first in shape of (…, 4).
Return type:: jaxtyping.Float[torch.Tensor, … 4]

Example

>>> rot_mat = torch.tensor([[-0.2533, -0.6075,  0.7529],
...                         [ 0.8445, -0.5185, -0.1343],
...                         [ 0.4720,  0.6017,  0.6443]])
>>> matrix_to_quaternion(rot_mat)
tensor([0.4671, 0.3940, 0.1503, 0.7772])

Ref: http://www.iri.upc.edu/files/scidoc/2068-Accurate-Computation-of-Quaternions-from-Rotation-Matrices.pdf: Note that the way to determine the best solution is slightly different from the PDF.

fastdev.xform.rotation.axis_angle_to_matrix(axis: jaxtyping.Float[torch.Tensor, ... 3], angle: jaxtyping.Float[torch.Tensor, ...]) → jaxtyping.Float[torch.Tensor, ... 3 3][source]¶

Converts axis angles to rotation matrices using Rodrigues formula.

Parameters:

axis (torch.Tensor) – axis, the shape could be […, 3].
angle (torch.Tensor) – angle, the shape could be […].

Returns:

Rotation matrices […, 3, 3].

Return type:

torch.Tensor

Example

>>> axis = torch.tensor([1.0, 0.0, 0.0])
>>> angle = torch.tensor(0.5)
>>> axis_angle_to_matrix(axis, angle)
tensor([[ 1.0000,  0.0000,  0.0000],
        [ 0.0000,  0.8776, -0.4794],
        [ 0.0000,  0.4794,  0.8776]])

fastdev.xform.rotation.matrix_to_euler_angles(matrix: torch.Tensor, convention: str = 'xyz') → torch.Tensor[source]¶

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

Parameters:

matrix (torch.Tensor) – Rotation matrices with shape (…, 3, 3).
convention (str) – Convention string of 3/4 letters, e.g. “xyz”, “sxyz”, “rxyz”, “exyz”. If the length is 3, the extrinsic rotation is assumed. If the length is 4, the first character is “r/i” (rotating/intrinsic), or “s/e” (static / extrinsic). The remaining characters are the axis “x, y, z” in the order.

Returns:

Euler angles in radians with shape (…, 3).

Return type:

torch.Tensor

fastdev.xform.rotation.euler_angles_to_matrix(euler_angles: jaxtyping.Float[torch.Tensor, ... 3], axes: _AXES = 'sxyz') → jaxtyping.Float[torch.Tensor, ... 3 3][source]¶

Converts Euler angles to rotation matrices.

Parameters:

euler_angles (torch.Tensor) – Euler angles, the shape could be […, 3].
axes (str) – Axis specification; one of 24 axis string sequences - e.g. `sxyz (the default). It’s recommended to use the full name of the axes, e.g. “sxyz” instead of “xyz”, but if 3 characters are provided, it will be prefixed with “s”.

Returns:

Rotation matrices […, 3, 3].

Return type:

torch.Tensor

Example

>>> euler_angles = torch.tensor([1.0, 0.5, 2.0])
>>> euler_angles_to_matrix(euler_angles, axes="sxyz")
tensor([[-0.3652, -0.6592,  0.6574],
        [ 0.7980,  0.1420,  0.5857],
        [-0.4794,  0.7385,  0.4742]])
>>> euler_angles_to_matrix(euler_angles, axes="rxyz")
tensor([[-0.3652, -0.7980,  0.4794],
        [ 0.3234, -0.5917, -0.7385],
        [ 0.8729, -0.1146,  0.4742]])

fastdev.xform.rotation.rotation_6d_to_matrix(d6: torch.Tensor) → torch.Tensor[source]¶

Converts 6D rotation representation by Zhou et al. [1] to rotation matrix using Gram–Schmidt orthogonalization per Section B of [1].

Parameters:: d6 (Tensor) – 6D rotation representation of shape […, 6]
Returns:: Rotation matrices of shape […, 3, 3]
Return type:: Tensor

[1] Zhou, Y., Barnes, C., Lu, J., Yang, J., & Li, H. On the Continuity of Rotation Representations in Neural Networks. CVPR 2019. arxiv

pytorch3d implementation

fastdev.xform.rotation.matrix_to_rotation_6d(matrix: torch.Tensor) → torch.Tensor[source]¶

Converts rotation matrices to 6D rotation representation by Zhou et al. [1] by dropping the last row. Note that 6D representation is not unique.

Parameters:: matrix (torch.Tensor) – batch of rotation matrices of size […, 3, 3]
Returns:: 6D rotation representation, of shape […, 6]
Return type:: torch.Tensor

[1] Zhou, Y., Barnes, C., Lu, J., Yang, J., & Li, H. On the Continuity of Rotation Representations in Neural Networks. CVPR 2019. arxiv