scipy.spatial.transform.Rotation

class scipy.spatial.transform.Rotation

Rotation in 3 dimensions.

This class provides an interface to initialize from and represent rotations with:

  • Quaternions

  • Rotation Matrices

  • Rotation Vectors

  • Modified Rodrigues Parameters

  • Euler Angles

The following operations on rotations are supported:

  • Application on vectors

  • Rotation Composition

  • Rotation Inversion

  • Rotation Indexing

Indexing within a rotation is supported since multiple rotation transforms can be stored within a single Rotation instance.

To create Rotation objects use from_... methods (see examples below). Rotation(...) is not supposed to be instantiated directly.

See also

Slerp

Notes

Examples

>>> from scipy.spatial.transform import Rotation as R

A Rotation instance can be initialized in any of the above formats and converted to any of the others. The underlying object is independent of the representation used for initialization.

Consider a counter-clockwise rotation of 90 degrees about the z-axis. This corresponds to the following quaternion (in scalar-last format):

>>> r = R.from_quat([0, 0, np.sin(np.pi/4), np.cos(np.pi/4)])

The rotation can be expressed in any of the other formats:

>>> r.as_matrix()
array([[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
[ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
[ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])
>>> r.as_rotvec()
array([0.        , 0.        , 1.57079633])
>>> r.as_euler('zyx', degrees=True)
array([90.,  0.,  0.])

The same rotation can be initialized using a rotation matrix:

>>> r = R.from_matrix([[0, -1, 0],
...                    [1, 0, 0],
...                    [0, 0, 1]])

Representation in other formats:

>>> r.as_quat()
array([0.        , 0.        , 0.70710678, 0.70710678])
>>> r.as_rotvec()
array([0.        , 0.        , 1.57079633])
>>> r.as_euler('zyx', degrees=True)
array([90.,  0.,  0.])

The rotation vector corresponding to this rotation is given by:

>>> r = R.from_rotvec(np.pi/2 * np.array([0, 0, 1]))

Representation in other formats:

>>> r.as_quat()
array([0.        , 0.        , 0.70710678, 0.70710678])
>>> r.as_matrix()
array([[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
       [ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
       [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])
>>> r.as_euler('zyx', degrees=True)
array([90.,  0.,  0.])

The from_euler method is quite flexible in the range of input formats it supports. Here we initialize a single rotation about a single axis:

>>> r = R.from_euler('z', 90, degrees=True)

Again, the object is representation independent and can be converted to any other format:

>>> r.as_quat()
array([0.        , 0.        , 0.70710678, 0.70710678])
>>> r.as_matrix()
array([[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
       [ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
       [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])
>>> r.as_rotvec()
array([0.        , 0.        , 1.57079633])

It is also possible to initialize multiple rotations in a single instance using any of the from_… functions. Here we initialize a stack of 3 rotations using the from_euler method:

>>> r = R.from_euler('zyx', [
... [90, 0, 0],
... [0, 45, 0],
... [45, 60, 30]], degrees=True)

The other representations also now return a stack of 3 rotations. For example:

>>> r.as_quat()
array([[0.        , 0.        , 0.70710678, 0.70710678],
       [0.        , 0.38268343, 0.        , 0.92387953],
       [0.39190384, 0.36042341, 0.43967974, 0.72331741]])

Applying the above rotations onto a vector:

>>> v = [1, 2, 3]
>>> r.apply(v)
array([[-2.        ,  1.        ,  3.        ],
       [ 2.82842712,  2.        ,  1.41421356],
       [ 2.24452282,  0.78093109,  2.89002836]])

A Rotation instance can be indexed and sliced as if it were a single 1D array or list:

>>> r.as_quat()
array([[0.        , 0.        , 0.70710678, 0.70710678],
       [0.        , 0.38268343, 0.        , 0.92387953],
       [0.39190384, 0.36042341, 0.43967974, 0.72331741]])
>>> p = r[0]
>>> p.as_matrix()
array([[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
       [ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
       [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])
>>> q = r[1:3]
>>> q.as_quat()
array([[0.        , 0.38268343, 0.        , 0.92387953],
       [0.39190384, 0.36042341, 0.43967974, 0.72331741]])

In fact it can be converted to numpy.array:

>>> r_array = np.asarray(r)
>>> r_array.shape
(3,)
>>> r_array[0].as_matrix()
array([[ 2.22044605e-16, -1.00000000e+00,  0.00000000e+00],
       [ 1.00000000e+00,  2.22044605e-16,  0.00000000e+00],
       [ 0.00000000e+00,  0.00000000e+00,  1.00000000e+00]])

Multiple rotations can be composed using the * operator:

>>> r1 = R.from_euler('z', 90, degrees=True)
>>> r2 = R.from_rotvec([np.pi/4, 0, 0])
>>> v = [1, 2, 3]
>>> r2.apply(r1.apply(v))
array([-2.        , -1.41421356,  2.82842712])
>>> r3 = r2 * r1 # Note the order
>>> r3.apply(v)
array([-2.        , -1.41421356,  2.82842712])

Finally, it is also possible to invert rotations:

>>> r1 = R.from_euler('z', [90, 45], degrees=True)
>>> r2 = r1.inv()
>>> r2.as_euler('zyx', degrees=True)
array([[-90.,   0.,   0.],
       [-45.,   0.,   0.]])

These examples serve as an overview into the Rotation class and highlight major functionalities. For more thorough examples of the range of input and output formats supported, consult the individual method’s examples.

Attributes
single

Whether this instance represents a single rotation.

Methods

__len__

Number of rotations contained in this object.

from_quat

Initialize from quaternions.

from_matrix

Initialize from rotation matrix.

from_rotvec

Initialize from rotation vectors.

from_mrp

Initialize from Modified Rodrigues Parameters (MRPs).

from_euler

Initialize from Euler angles.

as_quat

Represent as quaternions.

as_matrix

Represent as rotation matrix.

as_rotvec

Represent as rotation vectors.

as_mrp

Represent as Modified Rodrigues Parameters (MRPs).

as_euler

Represent as Euler angles.

apply

Apply this rotation to a set of vectors.

__mul__

Compose this rotation with the other.

inv

Invert this rotation.

magnitude

Get the magnitude(s) of the rotation(s).

mean

Get the mean of the rotations.

reduce

Reduce this rotation with the provided rotation groups.

create_group

Create a 3D rotation group.

__getitem__

Extract rotation(s) at given index(es) from object.

identity

Get identity rotation(s).

random

Generate uniformly distributed rotations.

align_vectors

Estimate a rotation to optimally align two sets of vectors.