The graphene:euler-t structure defines a rotation along three axes using three angles. It also optionally can describe the order of the rotations.

Euler's rotation theorem states that, in three-dimensional space, any displacement of a rigid body such that a point on the rigid body remains fixed, is equivalent to a single rotation about some axis that runs through the fixed point. The angles on each axis can be placed in a vector of three components - α, β, and γ - called the Euler angle vector. Each rotation described by these components results in a rotation matrix:

rot(α) = A
rot(β) = B
rot(γ) = G  

The resulting rotation matrix expressed by the Euler angle vector is given by the product of each rotation matrix:

G × B × A = R  

In order to specify the meaning of an Euler angle vector, we need to assign each axis of rotation to the corresponding α, β, and γ components, for instance X, Y, and Z.

Additionally, we need to specify whether the rotations move the axes as they are applied, also known as intrinsic, or relative rotations; or if the axes stay fixed and the vectors move within the axis frame, also known as extrinsic, or static rotations. For instance, a static rotation alongside the ZYX axes will be interpreted as relative to extrinsic coordinate axes, and be performed, in order, about the Z, Y, and finally X axis. A relative rotation alongside the ZXZ axes will be interpreted as relative to intrinsic coordinate axes, and be performed, in order, about the Z axis, about the rotated X axis, and finally about the rotated Z axis.

Finally, we need to define the direction of the rotation, or the handedness of the coordinate system. In the case of Graphene, the direction is given by the right-hand rule, which means all rotations are counterclockwise.

Rotations described by Euler angles are typically immediately understandable, compared to rotations expressed using quaternions, but they are susceptible of "Gimbal lock" - the loss of one degree of freedom caused by two axis on the same plane. You typically should use the graphene:euler-t structure to expose rotation angles in your API, or to store them, but use the graphene:quaternion-t structure to apply rotations to modelview matrices, or interpolate between initial and final rotation transformations.

For more information, see:

• Wikipedia, Rotation Matrix
• Wikipedia, Euler Angels
• Mathworld, Euler Angles
• "Representing Attitude with Euler Angles and Quaternions: A Reference" by James Diebel, 2006
• "Graphics Gems IV", edited by Paul Heckbert, Academic Press, 1994.