euler
¶
Generic Euler rotations
See:
 http://en.wikipedia.org/wiki/Rotation_matrix
 http://en.wikipedia.org/wiki/Euler_angles
 http://mathworld.wolfram.com/EulerAngles.html
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 righthanded 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 socalled Euler rotations (rotation about one axis, then a second and then the first again), and TaitBryan angles (rotations about all three axes). The two groups (Euler rotations and TaitBryan 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 righthand 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 nonhomogenous 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 TaitBryan 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: axes : str
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 TaitBryan ZYX Euler angle convention functions

__init__
()¶ Initialize TaitBryan 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: vector : 3 element sequence
vector specifying axis for rotation.
theta : scalar
angle of rotation
axes : str, optional
Axis specification; one of 24 axis sequences as string or encoded tuple  e.g.
sxyz
(the default).Returns: ai : float
First rotation angle (according to axes).
aj : float
Second rotation angle (according to axes).
ak : float
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: ai : float
First rotation angle (according to axes).
aj : float
Second rotation angle (according to axes).
ak : float
Third rotation angle (according to axes).
axes : str, optional
Axis specification; one of 24 axis sequences as string or encoded tuple  e.g.
sxyz
(the default).Returns: vector : array shape (3,)
axis around which rotation occurs
theta : scalar
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: ai : float
First rotation angle (according to axes).
aj : float
Second rotation angle (according to axes).
ak : float
Third rotation angle (according to axes).
axes : str, optional
Axis specification; one of 24 axis sequences as string or encoded tuple  e.g.
sxyz
(the default).Returns: mat : arraylike shape (3, 3) or (4, 4)
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: ai : float
First rotation angle (according to axes).
aj : float
Second rotation angle (according to axes).
ak : float
Third rotation angle (according to axes).
axes : str, optional
Axis specification; one of 24 axis sequences as string or encoded tuple  e.g.
sxyz
(the default).Returns: quat : array 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: mat : arraylike shape (3, 3) or (4, 4)
Rotation matrix or affine.
axes : str, optional
Axis specification; one of 24 axis sequences as string or encoded tuple  e.g.
sxyz
(the default).Returns: ai : float
First rotation angle (according to axes).
aj : float
Second rotation angle (according to axes).
ak : float
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: q : 4 element sequence
w, x, y, z of quaternion
axes : str, optional
Axis specification; one of 24 axis sequences as string or encoded tuple  e.g.
sxyz
(the default).Returns: ai : float
First rotation angle (according to axes).
aj : float
Second rotation angle (according to axes).
ak : float
Third rotation angle (according to axes).
Examples
>>> angles = quat2euler([0.99810947, 0.06146124, 0, 0]) >>> np.allclose(angles, [0.123, 0, 0]) True