API Reference

Submodules

tensorflow3d_transforms.rotation_conversions module

This module contains functions to convert between rotation representations.

The transformation matrices returned from the functions in this file assume the points on which the transformation will be applied are column vectors that is the R matrix is structured as

R = [
        [Rxx, Rxy, Rxz],
        [Ryx, Ryy, Ryz],
        [Rzx, Rzy, Rzz],
    ]  # (3, 3)

Furthermore, we will assume for any functions in this module that these are quaternions with real part first that is a tensor of shape (…, 4).

tensorflow3d_transforms.rotation_conversions.axis_angle_to_matrix(axis_angle: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as axis/angle to rotation matrices.

Example:

axis_angle = tf.constant((1.,1.,1.))
axis_angle_to_matrix(axis_angle=axis_angle)
# <tf.Tensor: shape=(3, 3), dtype=float32, numpy=
# array([[ 0.22629571, -0.18300788,  0.9567122 ],
#        [ 0.9567122 ,  0.22629571, -0.18300788],
#        [-0.18300788,  0.9567122 ,  0.22629571]], dtype=float32)>

Parameters: axis_angle (tf.Tensor) – 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: Rotation matrices as tensor of shape (…, 3, 3).
Return type: tf.Tensor

tensorflow3d_transforms.rotation_conversions.axis_angle_to_quaternion(axis_angle: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as axis/angle to quaternions.

Example:

axis_angle = tf.constant((1.,1.,1.))
axis_angle_to_quaternion(axis_angle=axis_angle)
# <tf.Tensor: shape=(4,), dtype=float32, numpy=array([0.64785933, 0.43980235, 0.43980235, 0.43980235], dtype=float32)>

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

tensorflow3d_transforms.rotation_conversions.euler_angles_to_matrix(euler_angles: tensorflow.python.framework.ops.Tensor, convention: str) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as euler angles to rotation matrices.

Example:

euler_angles = tf.constant(
    [
        [
            [0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0],
        ]
    ]
)

euler_angles_to_matrix(euler_angles=euler_angles, convention="XYZ")
# <tf.Tensor: shape=(1, 3, 3, 3), dtype=float32, numpy=
# array([[[[1., 0., 0.],
#          [0., 1., 0.],
#          [0., 0., 1.]],
#
#         [[1., 0., 0.],
#          [0., 1., 0.],
#          [0., 0., 1.]],
#
#         [[1., 0., 0.],
#          [0., 1., 0.],
#          [0., 0., 1.]]]], dtype=float32)>

Parameters

euler_angles (tf.Tensor) – A tensor of shape (…, 3) representing euler angles.
convention (str) – The euler angle convention. A string containing a combination of three uppercase letters from {“X”, “Y”, and “Z”}.

Returns

A tensor of shape (…, 3, 3) representing rotation matrices.

Return type

tf.Tensor

Raises

ValueError – If the shape of the input euler angles is invalid that is does not have the shape (…, 3).
ValueError – If the convention string is invalid that is does not have the length 3.
ValueError – If the second character of the convention string is the same as the first or third.
ValueError – If the convention string contains characters other than {“X”, “Y”, and “Z”}.

tensorflow3d_transforms.rotation_conversions.matrix_to_axis_angle(matrix: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as rotation matrices to axis/angle.

Example:

matrix = tf.constant(
    [
        [
            [0.15885946, -0.56794965, -0.48926896],
            [-1.0064808, -0.39120296, 1.6047943],
            [0.05503756, 0.817741, 0.4543775],
        ]
    ]
)
matrix_to_axis_angle(matrix)
# <tf.Tensor: shape=(1, 3), dtype=float32, numpy=array([[-0.5801526,  3.2366152,  2.2535346]], dtype=float32)>

Param: matrix: Rotation matrices as tensor of shape (…, 3, 3).
Parameters: matrix (tf.Tensor) –
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.
Return type: tf.Tensor

tensorflow3d_transforms.rotation_conversions.matrix_to_euler_angles(matrix: tensorflow.python.framework.ops.Tensor, convention: str) → tensorflow.python.framework.ops.Tensor[source]

Convert rotation matrices to euler angles in radians.

Example:

matrix = tf.constant(
    [
        [
            [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
            [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
            [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
        ]
    ]
)
matrix_to_euler_angles(matrix=matrix, convention="XYZ")
# <tf.Tensor: shape=(1, 3, 3), dtype=float32, numpy=
# array([[[-0.,  0., -0.],
#         [-0.,  0., -0.],
#         [-0.,  0., -0.]]], dtype=float32)>

Parameters

matrix (tf.Tensor) – A tensor of shape (…, 3, 3) representing rotation matrices.
convention (str) – The euler angle convention. A string containing a combination of three uppercase letters from {“X”, “Y”, and “Z”}.

Returns

A tensor of shape (…, 3) representing euler angles.

Return type

tf.Tensor

Raises

ValueError – If the shape of the input matrix is invalid that is does not have the shape (…, 3, 3).
ValueError – If the convention string is invalid that is does not have the length 3.
ValueError – If the second character of the convention string is the same as the first or third.
ValueError – If the convention string contains characters other than {“X”, “Y”, and “Z”}.

tensorflow3d_transforms.rotation_conversions.matrix_to_quaternion(matrix: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as rotation matrices to quaternions.

Example:

matrix = tf.constant(
    [
        [
            [0.15885946, -0.56794965, -0.48926896],
            [-1.0064808, -0.39120296, 1.6047943],
            [0.05503756, 0.817741, 0.4543775],
        ]
    ]
)

matrix_to_quaternion(matrix)
# <tf.Tensor: shape=(1, 4), dtype=float32, numpy=
# array([[-0.1688297 , -0.16717434,  0.9326495 ,  0.6493691 ]],
# dtype=float32)>

Parameters: matrix (tf.Tensor) – A tensor of shape (…, 3, 3) representing rotation matrices.
Returns: A tensor of shape (…, 4) representing quaternions with real part first.
Return type: tf.Tensor
Raises: ValueError – If the shape of the input matrix is invalid that is does not have the shape (…, 3, 3).

tensorflow3d_transforms.rotation_conversions.matrix_to_rotation_6d(matrix: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

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

[1] by dropping the last row.

Example:

matrix = tf.constant([[2.0, 1.0, 1.0], [1.0, 2.0, 1.0], [1.0, 1.0, 2.0]])
matrix_to_rotation_6d(matrix)
# <tf.Tensor: shape=(6,), dtype=float32, numpy=array([2., 1., 1., 1., 2., 1.], dtype=float32)>

[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

Parameters: matrix (tf.Tensor) – Rotation matrices as tensor of shape (…, 3, 3).
Returns: 6D rotation representation as tensor of shape (…, 6).
Return type: tf.Tensor

tensorflow3d_transforms.rotation_conversions.quaternion_apply(quaternion: tensorflow.python.framework.ops.Tensor, point: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

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

Example:

quaternion = tf.constant((1.,1.,1.,4.))
point = tf.constant((1.,1.,1.))
quaternion_apply(quaternion=quaternion, point=point)
# <tf.Tensor: shape=(3,), dtype=float32, numpy=array([-11.,   1.,  31.], dtype=float32)>

Parameters

quaternion (tf.Tensor) – Quaternions as tensor of shape (…, 4), with real part first
point (tf.Tensor) – Points as tensor of shape (…, 3)

Returns

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

Return type

tf.Tensor

Raises

ValueError – If the last dimension of point is not 3.

tensorflow3d_transforms.rotation_conversions.quaternion_invert(quaternion: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

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

Example:

quaternion = tf.constant((1.,2.,3.,4.))
quaternion_invert(quaternion=quaternion)
# <tf.Tensor: shape=(4,), dtype=float32, numpy=array([ 1., -2., -3., -4.], dtype=float32)>

Parameters: quaternion (tf.Tensor) – Quaternions as tensor of shape (…, 4), with real part first, which must be versors (unit quaternions).
Returns: The inverse, a tensor of quaternions of shape (…, 4).
Return type: tf.Tensor

tensorflow3d_transforms.rotation_conversions.quaternion_multiply(a: tensorflow.python.framework.ops.Tensor, b: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Multiply two quaternions representing rotations, returning the quaternion representing their composition, i.e. the versor with nonnegative real part.

Example:

a = tf.constant((1.,2.,3.,4.))
b = tf.constant((5.,6.,7.,8.))
quaternion_multiply(a=a, b=b)
# <tf.Tensor: shape=(4,), dtype=float32, numpy=array([ 60., -12., -30., -24.], dtype=float32)>

Parameters

a (tf.Tensor) – First quaternion with real part first, as tensor of shape (…, 4).
b (tf.Tensor) – Second quaternion with real part first, as tensor of shape (…, 4).

Returns

Product of a and b as tensor of shape (…, 4).

Return type

tf.Tensor

tensorflow3d_transforms.rotation_conversions.quaternion_raw_multiply(a: tensorflow.python.framework.ops.Tensor, b: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Multiply two quaternions.

Example:

a = tf.constant((1.,2.,3.,4.))
b = tf.constant((5.,6.,7.,8.))
quaternion_raw_multiply(a=a, b=b)
# <tf.Tensor: shape=(4,), dtype=float32, numpy=array([-60.,  12.,  30.,  24.], dtype=float32)>

Parameters

a (tf.Tensor) – First quaternion with real part first, as tensor of shape (…, 4).
b (tf.Tensor) – Second quaternion with real part first, as tensor of shape (…, 4).

Returns

Product of a and b as tensor of shape (…, 4).

Return type

tf.Tensor

tensorflow3d_transforms.rotation_conversions.quaternion_to_axis_angle(quaternions: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as quaternions to axis/angle.

Example:

quaternions = tf.constant((1.,1.,1.,4.))
quaternion_to_axis_angle(quaternions=quaternions)
# <tf.Tensor: shape=(3,), dtype=float32, numpy=array([ 2.752039,  2.752039, 11.008156], dtype=float32)>

Parameters

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

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.

Return type

tf.Tensor

tensorflow3d_transforms.rotation_conversions.quaternion_to_matrix(quaternions: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as quaternions to rotation matrices.

Example:

quaternion = tf.constant([0.0, 0.0, 0.0, 4.0])
output = tensorflow3d_transforms.quaternion_to_matrix(quaternions=quaternion)
# <tf.Tensor: shape=(3, 3), dtype=float32, numpy=
# array([[-1.,  0.,  0.],
#     [ 0., -1.,  0.],
#     [ 0.,  0.,  1.]], dtype=float32)>

Parameters: quaternions (tf.Tensor) – A tensor of shape (…, 4) representing quaternions with real part first.
Returns: A tensor of shape (…, 3, 3) representing rotation matrices.
Return type: tf.Tensor

tensorflow3d_transforms.rotation_conversions.random_quaternions(n: int, dtype: Optional[tensorflow.python.framework.dtypes.DType] = tf.float32) → tensorflow.python.framework.ops.Tensor[source]

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

Example:

random_quaternions(2)
# <tf.Tensor: shape=(2, 4), dtype=float32, numpy=...>

Parameters

n (int) – Number of quaternions to generate.
dtype (Optional[tf.dtype], optional) – Data type of the returned tensor, defaults to tf.float32.

Returns

Tensor of shape (n, 4) representing quaternions.

Return type

tf.Tensor

tensorflow3d_transforms.rotation_conversions.random_rotations(n: int, dtype: Optional[tensorflow.python.framework.dtypes.DType] = tf.float32) → tensorflow.python.framework.ops.Tensor[source]

Generate random rotations as 3x3 rotation matrices.

Example:

random_rotations(2)
# <tf.Tensor: shape=(2, 3, 3), dtype=float32, numpy=...>

Parameters

n (int) – Number of rotation matrices to generate.
dtype (Optional[tf.dtype], optional) – Data type of the returned tensor, defaults to tf.float32.

Returns

Tensor of shape (n, 3, 3) representing rotation matrices.

Return type

tf.Tensor

tensorflow3d_transforms.rotation_conversions.rotation_6d_to_matrix(d6: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

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

Example:

d6 = tf.constant((1.,1.,1.,1.,1.,1.))
rotation_6d_to_matrix(d6)
# <tf.Tensor: shape=(3, 3), dtype=float32, numpy=
# array([[0.57735026, 0.57735026, 0.57735026],
#        [0.57735026, 0.57735026, 0.57735026],
#        [0.        , 0.        , 0.        ]], dtype=float32)>

[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

Parameters: d6 (tf.Tensor) – 6D rotation representation as tensor of shape (…, 6).
Returns: Rotation matrices as tensor of shape (…, 3, 3).
Return type: tf.Tensor

tensorflow3d_transforms.rotation_conversions.standardize_quaternion(quaternions: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

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

Example:

quaternions = tf.constant((-1.,-2.,-1.,-1.))
standardize_quaternion(quaternions=quaternions)
# <tf.Tensor: shape=(4,), dtype=float32, numpy=array([ 1.,  2.,  1.,  1.], dtype=float32)>

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

tensorflow3d_transforms.so3_ops module

The SO(3) group, also known as the special orthogonal group in three dimensions, is a mathematical group that consists of all rotations in three- dimensional space.

It’s the collection of rotations of three-dimensional space that preserve one distinguished point, the origin. It is important in 3D geometry because it represents the set of all possible rotations that can be performed in three- dimensional space and operations on it are pretty helpful; thus the existence of this module.

tensorflow3d_transforms.so3_ops.acos_linear_extrapolation(x: tensorflow.python.framework.ops.Tensor, bounds: Tuple[float, float] = (- 0.9999, 0.9999)) → tensorflow.python.framework.ops.Tensor[source]

Implements arccos(x) which is linearly extrapolated outside x’s original domain of (-1, 1). This allows for stable backpropagation in case x is not guaranteed to be strictly within (-1, 1).

More specifically:

bounds=(lower_bound, upper_bound)
if lower_bound <= x <= upper_bound:
    acos_linear_extrapolation(x) = acos(x)
elif x <= lower_bound: # 1st order Taylor approximation
    acos_linear_extrapolation(x)
        = acos(lower_bound) + dacos/dx(lower_bound) * (x - lower_bound)
else:  # x >= upper_bound
    acos_linear_extrapolation(x)
        = acos(upper_bound) + dacos/dx(upper_bound) * (x - upper_bound)

Example:

x = tf.constant((1.0, 1.0, 1.0, 1.0, 1.0))
acos_linear_extrapolation(x=x)
# <tf.Tensor: shape=(5,), dtype=float32, numpy=
# array([0.00706984, 0.00706984, 0.00706984, 0.00706984, 0.00706984],
#       dtype=float32)>

Parameters

x (tf.Tensor) – Input Tensor.
bounds (Tuple[float, float]) – A float 2-tuple defining the region for the linear extrapolation of acos. The first/second element of bound describes the lower/upper bound that defines the lower/upper extrapolation region, i.e. the region where x <= bound[0]/bound[1] <= x. Note that all elements of bound have to be within (-1, 1).

Returns

acos_linear_extrapolation: Tensor containing the extrapolated arccos(x).

Return type

tf.Tensor

tensorflow3d_transforms.so3_ops.hat(v: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Computes the hat operator of a batch of 3D vector.

Example:

v = tf.constant([[1., 1., 1.], [1., 1., 1.]])
hat(v)
# <tf.Tensor: shape=(2, 3, 3), dtype=float32, numpy=
# array([[[ 0., -1.,  1.],
#         [ 1.,  0., -1.],
#         [-1.,  1.,  0.]],

#        [[ 0., -1.,  1.],
#         [ 1.,  0., -1.],
#         [-1.,  1.,  0.]]], dtype=float32)>

Parameters

v (tf.Tensor) – Batch of 3D vectors of shape (minibatch, 3).

Returns

Batch of skew-symmetric matrices of shape (minibatch, 3 , 3) where each matrix is of the form:

`[ 0 -v_z v_y ]
[ v_z 0 -v_x ] [ -v_y v_x 0 ]`

Raises

ValueError – if v is of incorrect shape.

tensorflow3d_transforms.so3_ops.hat_inverse(h: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Computes the inverse hat operator of a batch of skew-symmetric matrices.

Example:

h = tf.constant([[[ 0., -1.,  1.],
    [ 1.,  0., -1.],
    [-1.,  1.,  0.]],
[[ 0., -1.,  1.],
    [ 1.,  0., -1.],
    [-1.,  1.,  0.]]])
hat_inverse(h)
# <tf.Tensor: shape=(2, 3), dtype=float32, numpy=
# array([[1., 1., 1.],
#        [1., 1., 1.]], dtype=float32)>

Parameters

h (tf.Tensor) – Batch of skew-symmetric matrices of shape (minibatch, 3, 3).

Returns

Return type

Batch of 3D vectors of shape (minibatch, 3) where each vector is of the form

Raises

ValueError – if h is of incorrect shape.
ValueError – if h is not skew-symmetric.

tensorflow3d_transforms.so3_ops.so3_exp_map(log_rot: tensorflow.python.framework.ops.Tensor, eps: float = 0.0001) → tensorflow.python.framework.ops.Tensor[source]

Computes the exponential map of a batch of 3D rotation vectors.

Example:

log_rot = tf.constant(((1.,1.,1.),(1.,1.,1.)))
so3_exp_map(log_rot)
# <tf.Tensor: shape=(2, 3, 3), dtype=float32, numpy=
# array([[[ 0.22629565, -0.18300793,  0.95671225],
#         [ 0.95671225,  0.22629565, -0.18300793],
#         [-0.18300793,  0.95671225,  0.22629565]],
#        [[ 0.22629565, -0.18300793,  0.95671225],
#         [ 0.95671225,  0.22629565, -0.18300793],
#         [-0.18300793,  0.95671225,  0.22629565]]], dtype=float32)>

Parameters

log_rot (tf.Tensor) – Batch of 3D rotation vectors of shape (minibatch, 3).
eps (float) – Threshold for the norm of the rotation vector. If the norm is below this threshold, the exponential map is approximated with the first order Taylor expansion.

Returns

Batch of rotation matrices of shape (minibatch, 3, 3).

Return type

tf.Tensor

Raises

ValueError – if log_rot is of incorrect shape.

tensorflow3d_transforms.so3_ops.so3_log_map(R: tensorflow.python.framework.ops.Tensor, eps: float = 0.0001, cos_bound: float = 0.0001) → tensorflow.python.framework.ops.Tensor[source]

Convert a batch of 3x3 rotation matrices R to a batch of 3-dimensional matrix logarithms of rotation matrices The conversion has a singularity around (R=I) which is handled by clamping controlled with the eps and cos_bound arguments.

Example:

R = tf.constant([[[1., 1., 1.],[1., 1., 1.],[1., 1., 1.]]])
so3_log_map(R)
# <tf.Tensor: shape=(1, 3), dtype=float32, numpy=array([[0., 0., 0.]], dtype=float32)>

Parameters

R – batch of rotation matrices of shape (minibatch, 3, 3).
eps – A float constant handling the conversion singularity.
cos_bound – Clamps the cosine of the rotation angle to [-1 + cos_bound, 1 - cos_bound] to avoid non-finite outputs/gradients of the acos call when computing so3_rotation_angle. Note that the non-finite outputs/gradients are returned when the rotation angle is close to 0 or π.

Returns

Batch of logarithms of input rotation matrices of shape (minibatch, 3).

Raises

ValueError – if R is of incorrect shape.
ValueError – if R has an unexpected trace.

tensorflow3d_transforms.so3_ops.so3_relative_angle(R1: tensorflow.python.framework.ops.Tensor, R2: tensorflow.python.framework.ops.Tensor, cos_angle: bool = False, cos_bound: float = 0.0001, eps: float = 0.0001) → tensorflow.python.framework.ops.Tensor[source]

Calculates the relative angle (in radians) between pairs of.

rotation matrices R1 and R2 with angle = acos(0.5 * (Trace(R1 R2^T)-1))

Note

This corresponds to a geodesic distance on the 3D manifold of rotation matrices.

Example:

R = tf.constant([[[1., 1., 1.], [1., 1., 1.], [1., 1., 1.]]])
so3_relative_angle(R, R, eps=1e2)
# <tf.Tensor: shape=(1,), dtype=float32, numpy=array([-212.13028], dtype=float32)>

Parameters

R1 – Batch of rotation matrices of shape (minibatch, 3, 3).
R2 – Batch of rotation matrices of shape (minibatch, 3, 3).
cos_angle – If==True return cosine of the relative angle rather than the angle itself. This can avoid the unstable calculation of acos.
cos_bound – Clamps the cosine of the relative rotation angle to [-1 + cos_bound, 1 - cos_bound] to avoid non-finite outputs/gradients of the acos call. Note that the non-finite outputs/gradients are returned when the angle is requested (i.e. cos_angle==False) and the rotation angle is close to 0 or π.
eps – Tolerance for the valid trace check of the relative rotation matrix in so3_rotation_angle.

Returns

Corresponding rotation angles of shape (minibatch,). If cos_angle==True, returns the cosine of the angles.

Raises

ValueError – if R1 or R2 is of incorrect shape.
ValueError – if R1 or R2 has an unexpected trace.

tensorflow3d_transforms.so3_ops.so3_rotation_angle(R: tensorflow.python.framework.ops.Tensor, eps: float = 0.0001, cos_angle: bool = False, cos_bound: float = 0.0001) → tensorflow.python.framework.ops.Tensor[source]

Calculates angles (in radians) of a batch of rotation matrices R with.

\(angle = acos(0.5 * (Trace(R)-1))\). The trace of the input matrices is checked to be in the valid range [-1-eps,3+eps]. The eps argument is a small constant that allows for small errors caused by limited machine precision.

Example:

v = tf.constant([[[1., 1., 1.], [1., 1., 1.], [1., 1., 1.]]])
so3_rotation_angle(v)
# <tf.Tensor: shape=(1,), dtype=float32, numpy=array([0.00706984], dtype=float32)>

Parameters

R (tf.Tensor) – Batch of rotation matrices of shape (minibatch, 3, 3).
eps (float) – Tolerance for the valid trace check.
cos_angle (bool) – If==True return cosine of the rotation angles rather than the angle itself. This can avoid the unstable calculation of acos.
cos_bound (float) – Clamps the cosine of the rotation angle to [-1 + cos_bound, 1 - cos_bound] to avoid non-finite outputs/gradients of the acos call. Note that the non-finite outputs/gradients are returned when the angle is requested (i.e. cos_angle==False) and the rotation angle is close to 0 or \(\pi\).

Returns

Corresponding rotation angles of shape (minibatch,). If cos_angle==True, returns the cosine of the angles.

Return type

tf.Tensor

Raises

ValueError – if R is of incorrect shape.
ValueError – if R has an unexpected trace.

tensorflow3d_transforms.version module

This module exports the __version__ attribute showing the current version of the package installed:

import tensorflow3dtransforms as t3d
print(t3d.__version__)

Module contents

tensorflow3d_transforms.acos_linear_extrapolation(x: tensorflow.python.framework.ops.Tensor, bounds: Tuple[float, float] = (- 0.9999, 0.9999)) → tensorflow.python.framework.ops.Tensor[source]

Implements arccos(x) which is linearly extrapolated outside x’s original domain of (-1, 1). This allows for stable backpropagation in case x is not guaranteed to be strictly within (-1, 1).

More specifically:

bounds=(lower_bound, upper_bound)
if lower_bound <= x <= upper_bound:
    acos_linear_extrapolation(x) = acos(x)
elif x <= lower_bound: # 1st order Taylor approximation
    acos_linear_extrapolation(x)
        = acos(lower_bound) + dacos/dx(lower_bound) * (x - lower_bound)
else:  # x >= upper_bound
    acos_linear_extrapolation(x)
        = acos(upper_bound) + dacos/dx(upper_bound) * (x - upper_bound)

Example:

x = tf.constant((1.0, 1.0, 1.0, 1.0, 1.0))
acos_linear_extrapolation(x=x)
# <tf.Tensor: shape=(5,), dtype=float32, numpy=
# array([0.00706984, 0.00706984, 0.00706984, 0.00706984, 0.00706984],
#       dtype=float32)>

Parameters

x (tf.Tensor) – Input Tensor.
bounds (Tuple[float, float]) – A float 2-tuple defining the region for the linear extrapolation of acos. The first/second element of bound describes the lower/upper bound that defines the lower/upper extrapolation region, i.e. the region where x <= bound[0]/bound[1] <= x. Note that all elements of bound have to be within (-1, 1).

Returns

acos_linear_extrapolation: Tensor containing the extrapolated arccos(x).

Return type

tf.Tensor

tensorflow3d_transforms.axis_angle_to_matrix(axis_angle: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as axis/angle to rotation matrices.

Example:

axis_angle = tf.constant((1.,1.,1.))
axis_angle_to_matrix(axis_angle=axis_angle)
# <tf.Tensor: shape=(3, 3), dtype=float32, numpy=
# array([[ 0.22629571, -0.18300788,  0.9567122 ],
#        [ 0.9567122 ,  0.22629571, -0.18300788],
#        [-0.18300788,  0.9567122 ,  0.22629571]], dtype=float32)>

Parameters: axis_angle (tf.Tensor) – 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: Rotation matrices as tensor of shape (…, 3, 3).
Return type: tf.Tensor

tensorflow3d_transforms.axis_angle_to_quaternion(axis_angle: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as axis/angle to quaternions.

Example:

axis_angle = tf.constant((1.,1.,1.))
axis_angle_to_quaternion(axis_angle=axis_angle)
# <tf.Tensor: shape=(4,), dtype=float32, numpy=array([0.64785933, 0.43980235, 0.43980235, 0.43980235], dtype=float32)>

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

tensorflow3d_transforms.euler_angles_to_matrix(euler_angles: tensorflow.python.framework.ops.Tensor, convention: str) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as euler angles to rotation matrices.

Example:

euler_angles = tf.constant(
    [
        [
            [0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0],
            [0.0, 0.0, 0.0],
        ]
    ]
)

euler_angles_to_matrix(euler_angles=euler_angles, convention="XYZ")
# <tf.Tensor: shape=(1, 3, 3, 3), dtype=float32, numpy=
# array([[[[1., 0., 0.],
#          [0., 1., 0.],
#          [0., 0., 1.]],
#
#         [[1., 0., 0.],
#          [0., 1., 0.],
#          [0., 0., 1.]],
#
#         [[1., 0., 0.],
#          [0., 1., 0.],
#          [0., 0., 1.]]]], dtype=float32)>

Parameters

euler_angles (tf.Tensor) – A tensor of shape (…, 3) representing euler angles.
convention (str) – The euler angle convention. A string containing a combination of three uppercase letters from {“X”, “Y”, and “Z”}.

Returns

A tensor of shape (…, 3, 3) representing rotation matrices.

Return type

tf.Tensor

Raises

ValueError – If the shape of the input euler angles is invalid that is does not have the shape (…, 3).
ValueError – If the convention string is invalid that is does not have the length 3.
ValueError – If the second character of the convention string is the same as the first or third.
ValueError – If the convention string contains characters other than {“X”, “Y”, and “Z”}.

tensorflow3d_transforms.hat(v: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Computes the hat operator of a batch of 3D vector.

Example:

v = tf.constant([[1., 1., 1.], [1., 1., 1.]])
hat(v)
# <tf.Tensor: shape=(2, 3, 3), dtype=float32, numpy=
# array([[[ 0., -1.,  1.],
#         [ 1.,  0., -1.],
#         [-1.,  1.,  0.]],

#        [[ 0., -1.,  1.],
#         [ 1.,  0., -1.],
#         [-1.,  1.,  0.]]], dtype=float32)>

Parameters

v (tf.Tensor) – Batch of 3D vectors of shape (minibatch, 3).

Returns

Batch of skew-symmetric matrices of shape (minibatch, 3 , 3) where each matrix is of the form:

`[ 0 -v_z v_y ]
[ v_z 0 -v_x ] [ -v_y v_x 0 ]`

Raises

ValueError – if v is of incorrect shape.

tensorflow3d_transforms.hat_inverse(h: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Computes the inverse hat operator of a batch of skew-symmetric matrices.

Example:

h = tf.constant([[[ 0., -1.,  1.],
    [ 1.,  0., -1.],
    [-1.,  1.,  0.]],
[[ 0., -1.,  1.],
    [ 1.,  0., -1.],
    [-1.,  1.,  0.]]])
hat_inverse(h)
# <tf.Tensor: shape=(2, 3), dtype=float32, numpy=
# array([[1., 1., 1.],
#        [1., 1., 1.]], dtype=float32)>

Parameters

h (tf.Tensor) – Batch of skew-symmetric matrices of shape (minibatch, 3, 3).

Returns

Return type

Batch of 3D vectors of shape (minibatch, 3) where each vector is of the form

Raises

ValueError – if h is of incorrect shape.
ValueError – if h is not skew-symmetric.

tensorflow3d_transforms.matrix_to_axis_angle(matrix: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as rotation matrices to axis/angle.

Example:

matrix = tf.constant(
    [
        [
            [0.15885946, -0.56794965, -0.48926896],
            [-1.0064808, -0.39120296, 1.6047943],
            [0.05503756, 0.817741, 0.4543775],
        ]
    ]
)
matrix_to_axis_angle(matrix)
# <tf.Tensor: shape=(1, 3), dtype=float32, numpy=array([[-0.5801526,  3.2366152,  2.2535346]], dtype=float32)>

Param: matrix: Rotation matrices as tensor of shape (…, 3, 3).
Parameters: matrix (tf.Tensor) –
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.
Return type: tf.Tensor

tensorflow3d_transforms.matrix_to_euler_angles(matrix: tensorflow.python.framework.ops.Tensor, convention: str) → tensorflow.python.framework.ops.Tensor[source]

Convert rotation matrices to euler angles in radians.

Example:

matrix = tf.constant(
    [
        [
            [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
            [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
            [[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]],
        ]
    ]
)
matrix_to_euler_angles(matrix=matrix, convention="XYZ")
# <tf.Tensor: shape=(1, 3, 3), dtype=float32, numpy=
# array([[[-0.,  0., -0.],
#         [-0.,  0., -0.],
#         [-0.,  0., -0.]]], dtype=float32)>

Parameters

matrix (tf.Tensor) – A tensor of shape (…, 3, 3) representing rotation matrices.
convention (str) – The euler angle convention. A string containing a combination of three uppercase letters from {“X”, “Y”, and “Z”}.

Returns

A tensor of shape (…, 3) representing euler angles.

Return type

tf.Tensor

Raises

ValueError – If the shape of the input matrix is invalid that is does not have the shape (…, 3, 3).
ValueError – If the convention string is invalid that is does not have the length 3.
ValueError – If the second character of the convention string is the same as the first or third.
ValueError – If the convention string contains characters other than {“X”, “Y”, and “Z”}.

tensorflow3d_transforms.matrix_to_quaternion(matrix: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as rotation matrices to quaternions.

Example:

matrix = tf.constant(
    [
        [
            [0.15885946, -0.56794965, -0.48926896],
            [-1.0064808, -0.39120296, 1.6047943],
            [0.05503756, 0.817741, 0.4543775],
        ]
    ]
)

matrix_to_quaternion(matrix)
# <tf.Tensor: shape=(1, 4), dtype=float32, numpy=
# array([[-0.1688297 , -0.16717434,  0.9326495 ,  0.6493691 ]],
# dtype=float32)>

Parameters: matrix (tf.Tensor) – A tensor of shape (…, 3, 3) representing rotation matrices.
Returns: A tensor of shape (…, 4) representing quaternions with real part first.
Return type: tf.Tensor
Raises: ValueError – If the shape of the input matrix is invalid that is does not have the shape (…, 3, 3).

tensorflow3d_transforms.matrix_to_rotation_6d(matrix: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

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

[1] by dropping the last row.

Example:

matrix = tf.constant([[2.0, 1.0, 1.0], [1.0, 2.0, 1.0], [1.0, 1.0, 2.0]])
matrix_to_rotation_6d(matrix)
# <tf.Tensor: shape=(6,), dtype=float32, numpy=array([2., 1., 1., 1., 2., 1.], dtype=float32)>

[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

Parameters: matrix (tf.Tensor) – Rotation matrices as tensor of shape (…, 3, 3).
Returns: 6D rotation representation as tensor of shape (…, 6).
Return type: tf.Tensor

tensorflow3d_transforms.quaternion_apply(quaternion: tensorflow.python.framework.ops.Tensor, point: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

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

Example:

quaternion = tf.constant((1.,1.,1.,4.))
point = tf.constant((1.,1.,1.))
quaternion_apply(quaternion=quaternion, point=point)
# <tf.Tensor: shape=(3,), dtype=float32, numpy=array([-11.,   1.,  31.], dtype=float32)>

Parameters

quaternion (tf.Tensor) – Quaternions as tensor of shape (…, 4), with real part first
point (tf.Tensor) – Points as tensor of shape (…, 3)

Returns

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

Return type

tf.Tensor

Raises

ValueError – If the last dimension of point is not 3.

tensorflow3d_transforms.quaternion_invert(quaternion: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

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

Example:

quaternion = tf.constant((1.,2.,3.,4.))
quaternion_invert(quaternion=quaternion)
# <tf.Tensor: shape=(4,), dtype=float32, numpy=array([ 1., -2., -3., -4.], dtype=float32)>

Parameters: quaternion (tf.Tensor) – Quaternions as tensor of shape (…, 4), with real part first, which must be versors (unit quaternions).
Returns: The inverse, a tensor of quaternions of shape (…, 4).
Return type: tf.Tensor

tensorflow3d_transforms.quaternion_multiply(a: tensorflow.python.framework.ops.Tensor, b: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Multiply two quaternions representing rotations, returning the quaternion representing their composition, i.e. the versor with nonnegative real part.

Example:

a = tf.constant((1.,2.,3.,4.))
b = tf.constant((5.,6.,7.,8.))
quaternion_multiply(a=a, b=b)
# <tf.Tensor: shape=(4,), dtype=float32, numpy=array([ 60., -12., -30., -24.], dtype=float32)>

Parameters

a (tf.Tensor) – First quaternion with real part first, as tensor of shape (…, 4).
b (tf.Tensor) – Second quaternion with real part first, as tensor of shape (…, 4).

Returns

Product of a and b as tensor of shape (…, 4).

Return type

tf.Tensor

tensorflow3d_transforms.quaternion_raw_multiply(a: tensorflow.python.framework.ops.Tensor, b: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Multiply two quaternions.

Example:

a = tf.constant((1.,2.,3.,4.))
b = tf.constant((5.,6.,7.,8.))
quaternion_raw_multiply(a=a, b=b)
# <tf.Tensor: shape=(4,), dtype=float32, numpy=array([-60.,  12.,  30.,  24.], dtype=float32)>

Parameters

a (tf.Tensor) – First quaternion with real part first, as tensor of shape (…, 4).
b (tf.Tensor) – Second quaternion with real part first, as tensor of shape (…, 4).

Returns

Product of a and b as tensor of shape (…, 4).

Return type

tf.Tensor

tensorflow3d_transforms.quaternion_to_axis_angle(quaternions: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as quaternions to axis/angle.

Example:

quaternions = tf.constant((1.,1.,1.,4.))
quaternion_to_axis_angle(quaternions=quaternions)
# <tf.Tensor: shape=(3,), dtype=float32, numpy=array([ 2.752039,  2.752039, 11.008156], dtype=float32)>

Parameters

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

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.

Return type

tf.Tensor

tensorflow3d_transforms.quaternion_to_matrix(quaternions: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

Convert rotations given as quaternions to rotation matrices.

Example:

quaternion = tf.constant([0.0, 0.0, 0.0, 4.0])
output = tensorflow3d_transforms.quaternion_to_matrix(quaternions=quaternion)
# <tf.Tensor: shape=(3, 3), dtype=float32, numpy=
# array([[-1.,  0.,  0.],
#     [ 0., -1.,  0.],
#     [ 0.,  0.,  1.]], dtype=float32)>

Parameters: quaternions (tf.Tensor) – A tensor of shape (…, 4) representing quaternions with real part first.
Returns: A tensor of shape (…, 3, 3) representing rotation matrices.
Return type: tf.Tensor

tensorflow3d_transforms.random_quaternions(n: int, dtype: Optional[tensorflow.python.framework.dtypes.DType] = tf.float32) → tensorflow.python.framework.ops.Tensor[source]

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

Example:

random_quaternions(2)
# <tf.Tensor: shape=(2, 4), dtype=float32, numpy=...>

Parameters

n (int) – Number of quaternions to generate.
dtype (Optional[tf.dtype], optional) – Data type of the returned tensor, defaults to tf.float32.

Returns

Tensor of shape (n, 4) representing quaternions.

Return type

tf.Tensor

tensorflow3d_transforms.random_rotations(n: int, dtype: Optional[tensorflow.python.framework.dtypes.DType] = tf.float32) → tensorflow.python.framework.ops.Tensor[source]

Generate random rotations as 3x3 rotation matrices.

Example:

random_rotations(2)
# <tf.Tensor: shape=(2, 3, 3), dtype=float32, numpy=...>

Parameters

n (int) – Number of rotation matrices to generate.
dtype (Optional[tf.dtype], optional) – Data type of the returned tensor, defaults to tf.float32.

Returns

Tensor of shape (n, 3, 3) representing rotation matrices.

Return type

tf.Tensor

tensorflow3d_transforms.rotation_6d_to_matrix(d6: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

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

Example:

d6 = tf.constant((1.,1.,1.,1.,1.,1.))
rotation_6d_to_matrix(d6)
# <tf.Tensor: shape=(3, 3), dtype=float32, numpy=
# array([[0.57735026, 0.57735026, 0.57735026],
#        [0.57735026, 0.57735026, 0.57735026],
#        [0.        , 0.        , 0.        ]], dtype=float32)>

[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

Parameters: d6 (tf.Tensor) – 6D rotation representation as tensor of shape (…, 6).
Returns: Rotation matrices as tensor of shape (…, 3, 3).
Return type: tf.Tensor

tensorflow3d_transforms.so3_exp_map(log_rot: tensorflow.python.framework.ops.Tensor, eps: float = 0.0001) → tensorflow.python.framework.ops.Tensor[source]

Computes the exponential map of a batch of 3D rotation vectors.

Example:

log_rot = tf.constant(((1.,1.,1.),(1.,1.,1.)))
so3_exp_map(log_rot)
# <tf.Tensor: shape=(2, 3, 3), dtype=float32, numpy=
# array([[[ 0.22629565, -0.18300793,  0.95671225],
#         [ 0.95671225,  0.22629565, -0.18300793],
#         [-0.18300793,  0.95671225,  0.22629565]],
#        [[ 0.22629565, -0.18300793,  0.95671225],
#         [ 0.95671225,  0.22629565, -0.18300793],
#         [-0.18300793,  0.95671225,  0.22629565]]], dtype=float32)>

Parameters

log_rot (tf.Tensor) – Batch of 3D rotation vectors of shape (minibatch, 3).
eps (float) – Threshold for the norm of the rotation vector. If the norm is below this threshold, the exponential map is approximated with the first order Taylor expansion.

Returns

Batch of rotation matrices of shape (minibatch, 3, 3).

Return type

tf.Tensor

Raises

ValueError – if log_rot is of incorrect shape.

tensorflow3d_transforms.so3_log_map(R: tensorflow.python.framework.ops.Tensor, eps: float = 0.0001, cos_bound: float = 0.0001) → tensorflow.python.framework.ops.Tensor[source]

Convert a batch of 3x3 rotation matrices R to a batch of 3-dimensional matrix logarithms of rotation matrices The conversion has a singularity around (R=I) which is handled by clamping controlled with the eps and cos_bound arguments.

Example:

R = tf.constant([[[1., 1., 1.],[1., 1., 1.],[1., 1., 1.]]])
so3_log_map(R)
# <tf.Tensor: shape=(1, 3), dtype=float32, numpy=array([[0., 0., 0.]], dtype=float32)>

Parameters

R – batch of rotation matrices of shape (minibatch, 3, 3).
eps – A float constant handling the conversion singularity.
cos_bound – Clamps the cosine of the rotation angle to [-1 + cos_bound, 1 - cos_bound] to avoid non-finite outputs/gradients of the acos call when computing so3_rotation_angle. Note that the non-finite outputs/gradients are returned when the rotation angle is close to 0 or π.

Returns

Batch of logarithms of input rotation matrices of shape (minibatch, 3).

Raises

ValueError – if R is of incorrect shape.
ValueError – if R has an unexpected trace.

tensorflow3d_transforms.so3_relative_angle(R1: tensorflow.python.framework.ops.Tensor, R2: tensorflow.python.framework.ops.Tensor, cos_angle: bool = False, cos_bound: float = 0.0001, eps: float = 0.0001) → tensorflow.python.framework.ops.Tensor[source]

Calculates the relative angle (in radians) between pairs of.

rotation matrices R1 and R2 with angle = acos(0.5 * (Trace(R1 R2^T)-1))

Note

This corresponds to a geodesic distance on the 3D manifold of rotation matrices.

Example:

R = tf.constant([[[1., 1., 1.], [1., 1., 1.], [1., 1., 1.]]])
so3_relative_angle(R, R, eps=1e2)
# <tf.Tensor: shape=(1,), dtype=float32, numpy=array([-212.13028], dtype=float32)>

Parameters

R1 – Batch of rotation matrices of shape (minibatch, 3, 3).
R2 – Batch of rotation matrices of shape (minibatch, 3, 3).
cos_angle – If==True return cosine of the relative angle rather than the angle itself. This can avoid the unstable calculation of acos.
cos_bound – Clamps the cosine of the relative rotation angle to [-1 + cos_bound, 1 - cos_bound] to avoid non-finite outputs/gradients of the acos call. Note that the non-finite outputs/gradients are returned when the angle is requested (i.e. cos_angle==False) and the rotation angle is close to 0 or π.
eps – Tolerance for the valid trace check of the relative rotation matrix in so3_rotation_angle.

Returns

Corresponding rotation angles of shape (minibatch,). If cos_angle==True, returns the cosine of the angles.

Raises

ValueError – if R1 or R2 is of incorrect shape.
ValueError – if R1 or R2 has an unexpected trace.

tensorflow3d_transforms.so3_rotation_angle(R: tensorflow.python.framework.ops.Tensor, eps: float = 0.0001, cos_angle: bool = False, cos_bound: float = 0.0001) → tensorflow.python.framework.ops.Tensor[source]

Calculates angles (in radians) of a batch of rotation matrices R with.

\(angle = acos(0.5 * (Trace(R)-1))\). The trace of the input matrices is checked to be in the valid range [-1-eps,3+eps]. The eps argument is a small constant that allows for small errors caused by limited machine precision.

Example:

v = tf.constant([[[1., 1., 1.], [1., 1., 1.], [1., 1., 1.]]])
so3_rotation_angle(v)
# <tf.Tensor: shape=(1,), dtype=float32, numpy=array([0.00706984], dtype=float32)>

Parameters

R (tf.Tensor) – Batch of rotation matrices of shape (minibatch, 3, 3).
eps (float) – Tolerance for the valid trace check.
cos_angle (bool) – If==True return cosine of the rotation angles rather than the angle itself. This can avoid the unstable calculation of acos.
cos_bound (float) – Clamps the cosine of the rotation angle to [-1 + cos_bound, 1 - cos_bound] to avoid non-finite outputs/gradients of the acos call. Note that the non-finite outputs/gradients are returned when the angle is requested (i.e. cos_angle==False) and the rotation angle is close to 0 or \(\pi\).

Returns

Corresponding rotation angles of shape (minibatch,). If cos_angle==True, returns the cosine of the angles.

Return type

tf.Tensor

Raises

ValueError – if R is of incorrect shape.
ValueError – if R has an unexpected trace.

tensorflow3d_transforms.standardize_quaternion(quaternions: tensorflow.python.framework.ops.Tensor) → tensorflow.python.framework.ops.Tensor[source]

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

Example:

quaternions = tf.constant((-1.,-2.,-1.,-1.))
standardize_quaternion(quaternions=quaternions)
# <tf.Tensor: shape=(4,), dtype=float32, numpy=array([ 1.,  2.,  1.,  1.], dtype=float32)>

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