API Documentation

Mappings

Various mappings between different rotation representations.

procrustes(M, force_rotation=False, gradient_eps=1e-05)

Returns the orthonormal matrix R minimizing Frobenius norm \(\| M - R \|_F\).

Parameters

  • M (...xNxN tensor) – batch of square matrices.

  • force_rotation (bool) – if True, forces the output to be a rotation matrix.

  • gradient_eps (float > 0) – small value used to enforce numerical stability during backpropagation.

Returns

batch of orthonormal matrices (…xNxN tensor).

procrustes_naive(M, force_rotation: bool = False)

Implementation of procrustes() relying on default backward pass of autograd and roma.internal.svd. It could be slightly less stable than procrustes().

rotmat_to_rotvec(R)

Converts rotation matrix to rotation vector representation.

Parameters

R (...x3x3 tensor) – batch of rotation matrices.

Returns

batch of rotation vectors (…x3 tensor).

rotmat_to_unitquat(matrix)

Converts rotation matrix to unit quaternion representation.

Parameters

matrix (...x3x3 tensor) – batch of rotation matrices.

Returns

batch of unit quaternions (…x4 tensor).

rotvec_to_rotmat(rotvec: torch.Tensor, epsilon=1e-06) → torch.Tensor

Converts rotation vector to rotation matrix representation. Conversion uses Rodrigues formula in general, and a first order approximation for small angles.

Parameters

  • rotvec (...x3 tensor) – batch of rotation vectors.

  • epsilon (float) – small angle threshold.

Returns

batch of rotation matrices (…x3x3 tensor).

rotvec_to_unitquat(rotvec)

Converts rotation vector into unit quaternion representation.

Parameters

rotvec (...x3 tensor) – batch of rotation vectors.

Returns

batch of unit quaternions (…x4 tensor).

special_gramschmidt(M, epsilon=0)

Returns the 3x3 rotation matrix corresponding to Gram-Schmidt orthonormalisation of two 3D input vectors.

Parameters

  • M (...x3xN tensor) – batch of 3xN matrices, with N >= 2. Only the first two columns of the matrices are used for orthonormalization.

  • epsilon (float >= 0) – optional clamping value to avoid returning Not-a-Number values in case of ill-defined input.

Returns

batch of rotation matrices (…x3x3 tensor).

Warning

In case of ill-defined input (colinear input column vectors), the output will not be a rotation matrix.

special_procrustes(M, gradient_eps=1e-05)

Returns the rotation matrix R minimizing Frobenius norm \(\| M - R \|_F\).

Parameters

  • M (...xNxN tensor) – batch of square matrices.

  • gradient_eps (float > 0) – small value used to enforce numerical stability during backpropagation.

Returns

batch of rotation matrices (…xNxN tensor).

special_procrustes_naive(M)

Implementation of special_procrustes() relying on default backward pass of autograd and roma.internal.svd. It could be slightly less stable than special_procrustes().

symmatrix_to_projective_point(A)

Converts a DxD symmetric matrix A into a projective point represented as a unit vector q minimizing \(q^T @ A @ q\).

Parameters

A (...xDxD tensor) – batch of symmetric matrices. Only the lower triangular part is considered.

Returns

batch of unit vectors q (…xD tensor).

Warning

  • This mapping is unstable when the smallest eigenvalue of A has a multiplicity strictly greater than 1.

  • Current implementation is rather slow due to the implementation of torch.symeig function. CuSolver library provides a faster eigenvalue decomposition alternative, but results where found to be unreliable.

Reference:

  1. Peretroukhin, M. Giamou, D. M. Rosen, W. N. Greene, N. Roy, and J. Kelly, “A Smooth Representation of Belief over SO(3) for Deep Rotation Learning with Uncertainty,” 2020, doi: 10.15607/RSS.2020.XVI.007.

symmatrixvec_to_unitquat(x)

Converts a 10D vector into a unit quaternion representation.

Parameters

x (...x10 tensor) – batch of 10D vectors.

Returns

batch of unit quaternions (…x4 tensor).

Reference:

  1. Peretroukhin, M. Giamou, D. M. Rosen, W. N. Greene, N. Roy, and J. Kelly, “A Smooth Representation of Belief over SO(3) for Deep Rotation Learning with Uncertainty,” 2020, doi: 10.15607/RSS.2020.XVI.007.

unitquat_to_rotmat(quat)

Converts unit quaternion into rotation matrix representation.

Parameters

quat (...x4 tensor) – batch of unit quaternions. No normalization is applied before computation.

Returns

batch of rotation matrices (…x3x3 tensor).

unitquat_to_rotvec(quat)

Converts unit quaternion into rotation vector representation.

Parameters

quat (...x4 tensor) – batch of unit quaternions. No normalization is applied before computation.

Returns

batch of rotation vectors (…x3 tensor).

Utils

Various utility functions related to rotation representations.

is_orthonormal_matrix(R, epsilon=1e-07)

Test if matrices are orthonormal.

Parameters

  • R (...xDxD tensor) – batch of square matrices.

  • epsilon – tolerance threshold.

Returns

boolean tensor (shape …).

is_rotation_matrix(R, epsilon=1e-07)

Test if matrices are rotation matrices.

Parameters

  • R (...xDxD tensor) – batch of square matrices.

  • epsilon – tolerance threshold.

Returns

boolean tensor (shape …).

quat_composition(*args, normalize=False)

Returns the product of a sequence of quaternions.

Parameters

  • *args (...x4 tensors) – sequence of batches of quaternions.

  • normalize (bool) – it True, normalize the returned quaternion.

Returns

batch of quaternions (…x4 tensor).

quat_conjugation(quat)

Returns the conjugation of input batch of quaternions.

Parameters

quat (...x4 tensor) – batch of quaternions.

Returns

batch of quaternions (…x4 tensor).

Remarks:

Conjugation of a unit quaternion is equal to its inverse.

quat_inverse(quat)

Returns the inverse of a batch of quaternions.

Parameters

quat (...x4 tensor) – batch of quaternions.

Returns

batch of quaternions (…x4 tensor).

Remarks:

  • Inverse of null quaternion is undefined.

  • For unit quaternions, consider using conjugation instead.

quat_product(p, q)

Returns the product of two quaternions.

Parameters

  • p (...x4 tensor) – batch of quaternions.

  • q (...x4 tensor) – batch of quaternions.

Returns

batch of quaternions (…x4 tensor).

random_rotmat(size=(), device=None)

Generates a batch of random 3x3 rotation matrices, uniformly sampled according to the usual rotation metric.

Parameters

size (tuple or int) – batch size. Use for example tuple() to generate a single element, and (5,2) to generate a 5x2 batch.

Returns

batch of rotation matrices (size x 3x3 tensor).

random_rotvec(size=(), device=None)

Generates a batch of random rotation vectors, uniformly sampled according to the usual rotation metric.

Parameters

size (tuple or int) – batch size. Use for example tuple() to generate a single element, and (5,2) to generate a 5x2 batch.

Returns

batch of rotation vectors (size x 3 tensor).

random_unitquat(size=(), device=None)

Generates a batch of random unit quaternions, uniformly sampled according to the usual quaternion metric.

Parameters

size (tuple or int) – batch size. Use for example tuple() to generate a single element, and (5,2) to generate a 5x2 batch.

Returns

batch of unit quaternions (size x 4 tensor).

rotmat_composition(*args, normalize=False)

Returns the product of a sequence of rotation matrices.

Parameters

  • *args (...xNxN tensors) – sequence of batches of rotation matrices.

  • normalize – if True, apply special Procrustes orthonormalization to compensate for numerical errors.

Returns

batch of rotation matrices (…xNxN tensor).

rotmat_cosine_angle(R)

Returns the cosine angle of the input 3x3 rotation matrix R. Based on the equality \(Trace(R) = 1 + 2 cos(alpha)\).

Parameters

R (...x3x3 tensor) – batch of 3w3 rotation matrices.

Returns

batch of cosine angles (… tensor).

rotmat_geodesic_distance(R1, R2)

Returns the angular distance alpha between a pair of rotation matrices. Based on the equality \(|R_2 - R_1|_F = 2 \sqrt{2} sin(alpha/2)\).

Parameters

  • R1 (...x3x3 tensor) – batch of 3x3 rotation matrices.

  • R2 (...x3x3 tensor) – batch of 3x3 rotation matrices.

Returns

batch of angles in radian (… tensor).

rotmat_geodesic_distance_naive(R1, R2)

Returns the angular distance between a pair of rotation matrices. Based on rotmat_cosine_angle() and potentially less precise than rotmat_geodesic_distance() for nearby rotations.

Parameters

  • R1 (...x3x3 tensor) – batch of 3x3 rotation matrices.

  • R2 (...x3x3 tensor) – batch of 3x3 rotation matrices.

Returns

batch of angles in radian (… tensor).

rotmat_inverse(R)

Returns the inverse of a rotation matrix.

Parameters

R (...xNxN tensor) – batch of rotation matrices.

Returns

batch of inverted rotation matrices (…xNxN tensor).

Warning

The function returns a transposed view of the input, therefore one should be careful with in-place operations.

rotvec_composition(*args, normalize=False)

Returns a rotation vector corresponding to the composition of a sequence of rotations represented by rotation vectors. Composition is performed using an intermediary quaternion representation.

Parameters

  • *args (...x3 tensors) – sequence of batches of rotation vectors.

  • normalize (bool) – if True, normalize intermediary representation to compensate for numerical errors.

rotvec_inverse(rotvec)

Returns the inverse of the input rotation expressed using rotation vector representation.

Parameters

rotvec (...x3 tensor) – batch of rotation vectors.

Returns

batch of rotation vectors (…x3 tensor).

rotvec_slerp(rotvec0, rotvec1, steps)

Spherical linear interpolation between two rotation vector representations.

Parameters

  • rotvec0 (Ax3 tensor) – batch of rotation vectors (A may contain multiple dimensions).

  • rotvec1 (Ax3 tensor) – batch of rotation vectors (A may contain multiple dimensions).

  • steps (tensor of shape B) – interpolation steps, 0.0 corresponding to rotvec0 and 1.0 to rotvec1 (B may contain multiple dimensions).

Returns

batch of interpolated rotation vectors (BxAx3 tensor).

unitquat_slerp(q0, q1, steps)

Spherical linear interpolation between two unit quaternions.

Parameters

  • q0 (Ax4 tensor) – batch of unit quaternions (A may contain multiple dimensions).

  • q1 (Ax4 tensor) – batch of unit quaternions (A may contain multiple dimensions).

  • steps (tensor of shape B) – interpolation steps, 0.0 corresponding to q0 and 1.0 to q1 (B may contain multiple dimensions).

Returns

batch of interpolated quaternions (BxAx4 tensor).

Note

When considering quaternions as rotation representations, one should keep in mind that interpolation is not necessarily performed along the shortest arc, depending on the sign of torch.sum(q0*q1,dim=-1).