euler

Generic Euler rotations

See:

See also: Representing Attitude with Euler Angles and Quaternions: A Reference (2006) by James Diebel. A cached PDF link last found here:

http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.110.5134

Defining rotations

Euler’s rotation theorem tells us that any rotation in 3D can be described by 3 angles. Let’s call the 3 angles the Euler angle vector and call the angles in the vector \(alpha\), \(beta\) and \(gamma\). The vector is [ \(alpha\), \(beta\). \(gamma\) ] and, in this description, the order of the parameters specifies the order in which the rotations occur (so the rotation corresponding to \(alpha\) is applied first).

In order to specify the meaning of an Euler angle vector we need to specify the axes around which each of the rotations corresponding to \(alpha\), \(beta\) and \(gamma\) will occur.

There are therefore three axes for the rotations \(alpha\), \(beta\) and \(gamma\); let’s call them \(i\) \(j\), \(k\).

Let us express the rotation \(alpha\) around axis i as a 3 by 3 rotation matrix A. Similarly \(beta\) around j becomes 3 x 3 matrix B and \(gamma\) around k becomes matrix G. Then the whole rotation expressed by the Euler angle vector [ \(alpha\), \(beta\). \(gamma\) ], R is given by:

R = np.dot(G, np.dot(B, A))

See http://mathworld.wolfram.com/EulerAngles.html

The order \(G B A\) expresses the fact that the rotations are performed in the order of the vector (\(alpha\) around axis i = A first).

To convert a given Euler angle vector to a meaningful rotation, and a rotation matrix, we need to define:

  • the axes i, j, k;

  • whether the rotations move the axes as they are applied (intrinsic rotations) - compared the situation where the axes stay fixed and the vectors move within the axis frame (extrinsic);

  • whether a rotation matrix should be applied on the left of a vector to be transformed (vectors are column vectors) or on the right (vectors are row vectors);

  • the handedness of the coordinate system.

See: http://en.wikipedia.org/wiki/Rotation_matrix#Ambiguities

This module implements intrinsic and extrinsic axes, with standard conventions for axes i, j, k. We assume that the matrix should be applied on the left of the vector, and right-handed coordinate systems. To get the matrix to apply on the right of the vector, you need the transpose of the matrix we supply here, by the matrix transpose rule: \((M . V)^T = V^T M^T\).

Rotation axes

Rotations given as a set of three angles can refer to any of 24 different ways of applying these rotations, or equivalently, 24 conventions for rotation angles. See http://en.wikipedia.org/wiki/Euler_angles.

The different conventions break down into two groups of 12. In the first group, the rotation axes are fixed (also, global, static), and do not move with rotations. These are called extrinsic axes. The axes can also move with the rotations. These are called intrinsic, local or rotating axes.

Each of the two groups (intrinsic and extrinsic) can further be divided into so-called Euler rotations (rotation about one axis, then a second and then the first again), and Tait-Bryan angles (rotations about all three axes). The two groups (Euler rotations and Tait-Bryan rotations) each have 6 possible choices. There are therefore 2 * 2 * 6 = 24 possible conventions that could apply to rotations about a sequence of three given angles.

This module gives an implementation of conversion between angles and rotation matrices for which you can specify any of the 24 different conventions.

Specifying angle conventions

You specify conventions for interpreting the sequence of angles with a four character string.

The first character is ‘r’ (rotating == intrinsic), or ‘s’ (static == extrinsic).

The next three characters give the axis (‘x’, ‘y’ or ‘z’) about which to perform the rotation, in the order in which the rotations will be performed.

For example the string ‘szyx’ specifies that the angles should be interpreted relative to extrinsic (static) coordinate axes, and be performed in the order: rotation about z axis; rotation about y axis; rotation about x axis. This is a relatively common convention, with customized implementations in taitbryan in this package.

The string ‘rzxz’ specifies that the angles should be interpreted relative to intrinsic (rotating) coordinate axes, and be performed in the order: rotation about z axis; rotation about the rotated x axis; rotation about the rotated z axis. Wolfram Mathworld claim this is the most common convention : http://mathworld.wolfram.com/EulerAngles.html.

Direction of rotation

The direction of rotation is given by the right-hand rule (orient the thumb of the right hand along the axis around which the rotation occurs, with the end of the thumb at the positive end of the axis; curl your fingers; the direction your fingers curl is the direction of rotation). Therefore, the rotations are counterclockwise if looking along the axis of rotation from positive to negative.

Terms used in function names

  • mat : array shape (3, 3) (3D non-homogenous coordinates)

  • euler : (sequence of) rotation angles about the z, y, x axes (in that order)

  • axangle : rotations encoded by axis vector and angle scalar

  • quat : quaternion shape (4,)

EulerFuncs(axes)

Namespace for Euler angles functions with given axes specification

TBZYX()

Namespace for Tait-Bryan ZYX Euler angle convention functions

axangle2euler(vector, theta[, axes])

Convert axis, angle pair to Euler angles

euler2axangle(ai, aj, ak[, axes])

Return angle, axis corresponding to Euler angles, axis specification

euler2mat(ai, aj, ak[, axes])

Return rotation matrix from Euler angles and axis sequence.

euler2quat(ai, aj, ak[, axes])

Return quaternion from Euler angles and axis sequence axes

mat2euler(mat[, axes])

Return Euler angles from rotation matrix for specified axis sequence.

quat2euler(quaternion[, axes])

Euler angles from quaternion for specified axis sequence axes

EulerFuncs

class transforms3d.euler.EulerFuncs(axes)

Bases: object

Namespace for Euler angles functions with given axes specification

__init__(axes)

Initialize namespace for Euler angles functions

Parameters
axesstr

Axis specification; one of 24 axis sequences as string or encoded tuple - e.g. sxyz (the default).

axangle2euler(vector, theta)

Convert axis, angle pair to Euler angles

See axangle2euler() for details.

euler2axangle(ai, aj, ak)

Angle, axis corresponding to Euler angles

See euler2axangle() for details.

euler2mat(ai, aj, ak)

Return rotation matrix from Euler angles

See euler2mat() for details.

euler2quat(ai, aj, ak)

Return quaternion from Euler angles

See euler2quat() for details.

mat2euler(mat)

Return Euler angles from rotation matrix mat

See mat2euler() for details.

quat2euler(quat)

Euler angles from quaternion

See quat2euler() for details.

TBZYX

class transforms3d.euler.TBZYX

Bases: transforms3d.euler.EulerFuncs

Namespace for Tait-Bryan ZYX Euler angle convention functions

__init__()

Initialize Tait-Bryan ZYX namespace

euler2mat(ai, aj, ak)

Return rotation matrix from Euler angles

See transforms3d.taitbryan.euler2mat() for details.

euler2quat(ai, aj, ak)

Return quaternion from Euler angles

See transforms3d.taitbryan.euler2quat() for details.

mat2euler(mat)

Return Euler angles from rotation matrix mat

See transforms3d.taitbryan.mat2euler() for details.

axangle2euler

transforms3d.euler.axangle2euler(vector, theta, axes='sxyz')

Convert axis, angle pair to Euler angles

Parameters
vector3 element sequence

vector specifying axis for rotation.

thetascalar

angle of rotation

axesstr, optional

Axis specification; one of 24 axis sequences as string or encoded tuple - e.g. sxyz (the default).

Returns
aifloat

First rotation angle (according to axes).

ajfloat

Second rotation angle (according to axes).

akfloat

Third rotation angle (according to axes).

Examples

>>> ai, aj, ak = axangle2euler([1, 0, 0], 0)
>>> np.allclose((ai, aj, ak), 0)
True

euler2axangle

transforms3d.euler.euler2axangle(ai, aj, ak, axes='sxyz')

Return angle, axis corresponding to Euler angles, axis specification

Parameters
aifloat

First rotation angle (according to axes).

ajfloat

Second rotation angle (according to axes).

akfloat

Third rotation angle (according to axes).

axesstr, optional

Axis specification; one of 24 axis sequences as string or encoded tuple - e.g. sxyz (the default).

Returns
vectorarray shape (3,)

axis around which rotation occurs

thetascalar

angle of rotation

Examples

>>> vec, theta = euler2axangle(0, 1.5, 0, 'szyx')
>>> np.allclose(vec, [0, 1, 0])
True
>>> theta
1.5

euler2mat

transforms3d.euler.euler2mat(ai, aj, ak, axes='sxyz')

Return rotation matrix from Euler angles and axis sequence.

Parameters
aifloat

First rotation angle (according to axes).

ajfloat

Second rotation angle (according to axes).

akfloat

Third rotation angle (according to axes).

axesstr, optional

Axis specification; one of 24 axis sequences as string or encoded tuple - e.g. sxyz (the default).

Returns
matarray (3, 3)

Rotation matrix or affine.

Examples

>>> R = euler2mat(1, 2, 3, 'syxz')
>>> np.allclose(np.sum(R[0]), -1.34786452)
True
>>> R = euler2mat(1, 2, 3, (0, 1, 0, 1))
>>> np.allclose(np.sum(R[0]), -0.383436184)
True

euler2quat

transforms3d.euler.euler2quat(ai, aj, ak, axes='sxyz')

Return quaternion from Euler angles and axis sequence axes

Parameters
aifloat

First rotation angle (according to axes).

ajfloat

Second rotation angle (according to axes).

akfloat

Third rotation angle (according to axes).

axesstr, optional

Axis specification; one of 24 axis sequences as string or encoded tuple - e.g. sxyz (the default).

Returns
quatarray shape (4,)

Quaternion in w, x, y z (real, then vector) format

Examples

>>> q = euler2quat(1, 2, 3, 'ryxz')
>>> np.allclose(q, [0.435953, 0.310622, -0.718287, 0.444435])
True

mat2euler

transforms3d.euler.mat2euler(mat, axes='sxyz')

Return Euler angles from rotation matrix for specified axis sequence.

Note that many Euler angle triplets can describe one matrix.

Parameters
matarray-like shape (3, 3) or (4, 4)

Rotation matrix or affine.

axesstr, optional

Axis specification; one of 24 axis sequences as string or encoded tuple - e.g. sxyz (the default).

Returns
aifloat

First rotation angle (according to axes).

ajfloat

Second rotation angle (according to axes).

akfloat

Third rotation angle (according to axes).

Examples

>>> R0 = euler2mat(1, 2, 3, 'syxz')
>>> al, be, ga = mat2euler(R0, 'syxz')
>>> R1 = euler2mat(al, be, ga, 'syxz')
>>> np.allclose(R0, R1)
True

quat2euler

transforms3d.euler.quat2euler(quaternion, axes='sxyz')

Euler angles from quaternion for specified axis sequence axes

Parameters
q4 element sequence

w, x, y, z of quaternion

axesstr, optional

Axis specification; one of 24 axis sequences as string or encoded tuple - e.g. sxyz (the default).

Returns
aifloat

First rotation angle (according to axes).

ajfloat

Second rotation angle (according to axes).

akfloat

Third rotation angle (according to axes).

Examples

>>> angles = quat2euler([0.99810947, 0.06146124, 0, 0])
>>> np.allclose(angles, [0.123, 0, 0])
True