Rotation conversions¶
xbarray.transformations.rotation_conversions converts between rotation
representations. The code is ported from
PyTorch3D's rotation_conversions.py
and runs on all three backends.
Modules¶
| Module | Use |
|---|---|
xbarray.transformations.rotation_conversions.numpy |
Functions bound to NumpyComputeBackend |
xbarray.transformations.rotation_conversions.pytorch |
Functions bound to PyTorchComputeBackend |
xbarray.transformations.rotation_conversions.jax |
Functions bound to JaxComputeBackend |
xbarray.transformations.rotation_conversions.base |
Generic functions that take the backend as the first argument |
The bound modules are functools.partial(base.f, Backend) for each function f, so
numpy.quaternion_to_matrix(q) is base.quaternion_to_matrix(NumpyComputeBackend, q).
Conventions¶
- Quaternions have shape
(..., 4)with the real part first:(w, x, y, z). - Rotation matrices have shape
(..., 3, 3). - Euler angles have shape
(..., 3), in radians. Theconventionargument is three letters fromX,Y,Z, such as"XYZ"or"ZYX", with the middle letter different from its neighbours. - Axis-angle vectors have shape
(..., 3). The direction is the axis, and the length is the angle in radians, anticlockwise around the axis. - 6D representation has shape
(..., 6): the first two rows of the rotation matrix, from Zhou et al., 2019.
All functions accept any number of leading batch dimensions.
Example¶
A rotation of 90 degrees around the z axis, in several representations:
import math
import numpy as np
from xbarray.transformations.rotation_conversions import numpy as rc
q = np.array([math.cos(math.pi / 4), 0.0, 0.0, math.sin(math.pi / 4)], dtype=np.float32)
R = rc.quaternion_to_matrix(q)
print(np.round(R, 3))
# [[ 0. -1. 0.]
# [ 1. 0. 0.]
# [ 0. 0. 1.]]
print(rc.matrix_to_euler_angles(R, "XYZ")) # [-0. 0. 1.5707964]
print(rc.quaternion_to_axis_angle(q)) # [0. 0. 1.5707963]
print(rc.matrix_to_rotation_6d(R).shape) # (6,)
import math
import torch
from xbarray.transformations.rotation_conversions import pytorch as rc
q = torch.tensor([math.cos(math.pi / 4), 0.0, 0.0, math.sin(math.pi / 4)])
R = rc.quaternion_to_matrix(q)
print(R.round(decimals=3))
# tensor([[ 0., -1., 0.],
# [ 1., 0., 0.],
# [ 0., 0., 1.]])
print(rc.matrix_to_euler_angles(R, "XYZ")) # tensor([-0.0000, 0.0000, 1.5708])
print(rc.quaternion_to_axis_angle(q)) # tensor([0.0000, 0.0000, 1.5708])
print(rc.matrix_to_rotation_6d(R).shape) # torch.Size([6])
import math
import jax.numpy as jnp
from xbarray.transformations.rotation_conversions import jax as rc
q = jnp.array([math.cos(math.pi / 4), 0.0, 0.0, math.sin(math.pi / 4)])
R = rc.quaternion_to_matrix(q)
print(jnp.round(R, 3))
# [[ 0. -1. 0.]
# [ 1. 0. 0.]
# [ 0. 0. 1.]]
print(rc.matrix_to_euler_angles(R, "XYZ")) # [-0. 0. 1.5707964]
print(rc.quaternion_to_axis_angle(q)) # [0. 0. 1.5707964]
print(rc.matrix_to_rotation_6d(R).shape) # (6,)
Rotating points and composing rotations¶
quaternion_apply rotates 3D points. quaternion_multiply(a, b) composes two
rotations (apply b, then a) and returns a quaternion with a non-negative real part.
import math
import numpy as np
from xbarray.transformations.rotation_conversions import numpy as rc
q = np.array([math.cos(math.pi / 4), 0.0, 0.0, math.sin(math.pi / 4)]) # 90 deg about z
points = np.array([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0]])
print(np.round(rc.quaternion_apply(q, points), 6))
# [[ 0. 1. 0.]
# [-1. 0. 0.]]
q180 = rc.quaternion_multiply(q, q)
print(np.round(q180, 6)) # [0. 0. 0. 1.]
print(np.round(rc.quaternion_invert(q), 6)) # [ 0.707107 -0. -0. -0.707107]
quaternion_invert expects unit quaternions. standardize_quaternion flips the sign
of quaternions whose real part is negative, so q and -q map to the same value.
Function list¶
| From \ To | Matrix | Quaternion | Euler angles | Axis-angle | 6D |
|---|---|---|---|---|---|
| Matrix | matrix_to_quaternion |
matrix_to_euler_angles |
matrix_to_axis_angle |
matrix_to_rotation_6d |
|
| Quaternion | quaternion_to_matrix |
quaternion_to_axis_angle |
|||
| Euler angles | euler_angles_to_matrix |
||||
| Axis-angle | axis_angle_to_matrix |
axis_angle_to_quaternion |
|||
| 6D | rotation_6d_to_matrix |
Quaternion operations: quaternion_multiply, quaternion_invert, quaternion_apply,
standardize_quaternion.
axis_angle_to_matrix and matrix_to_axis_angle take a fast flag, as in PyTorch3D.
The default, fast=False, goes through quaternions.
Generic use¶
Inside your own backend-agnostic function, call the base module with the backend:
from xbarray import ComputeBackend
from xbarray.transformations.rotation_conversions import base as rc
def rotate_by_euler(backend: ComputeBackend, points, euler, convention="XYZ"):
"""Rotate (..., N, 3) points by (..., 3) Euler angles."""
R = rc.euler_angles_to_matrix(backend, euler, convention) # (..., 3, 3)
return backend.matmul(points, backend.matrix_transpose(R)) # (..., N, 3)
from xbarray.backends.pytorch import PyTorchComputeBackend as backend
import math
pts = backend.asarray([[1.0, 0.0, 0.0]])
print(rotate_by_euler(backend, pts, backend.asarray([0.0, 0.0, math.pi / 2])))
# tensor([[-4.3711e-08, 1.0000e+00, 0.0000e+00]])