Eulers (Rotations)

Eulers (Rotations) — Functions for initializing and manipulating euler angles.

Synopsis

                    CoglEuler;
void                cogl_euler_init                     (CoglEuler *euler,
                                                         float heading,
                                                         float pitch,
                                                         float roll);
void                cogl_euler_init_from_matrix         (CoglEuler *euler,
                                                         const CoglMatrix *matrix);
void                cogl_euler_init_from_quaternion     (CoglEuler *euler,
                                                         const CoglQuaternion *quaternion);
CoglBool            cogl_euler_equal                    (const void *v1,
                                                         const void *v2);
CoglEuler *         cogl_euler_copy                     (const CoglEuler *src);
void                cogl_euler_free                     (CoglEuler *euler);

Description

Euler angles are a simple representation of a 3 dimensional rotation; comprised of 3 ordered heading, pitch and roll rotations. An important thing to understand is that the axis of rotation belong to the object being rotated and so they also rotate as each of the heading, pitch and roll rotations are applied.

One way to consider euler angles is to imagine controlling an aeroplane, where you first choose a heading (Such as flying south east), then you set the pitch (such as 30 degrees to take off) and then you might set a roll, by dipping the left, wing as you prepare to turn.

They have some advantages and limitations that it helps to be aware of:

Advantages:

Easy to understand and use, compared to quaternions and matrices, so may be a good choice for a user interface.
Efficient storage, needing only 3 components any rotation can be represented.

Note
Actually the CoglEuler type isn't optimized for size because we may cache the equivalent CoglQuaternion along with a euler rotation, but it would be trivial for an application to track the components of euler rotations in a packed float array if optimizing for size was important. The values could be passed to Cogl only when manipulation is necessary.

Disadvantages:

Aliasing: it's possible to represent some rotations with multiple different heading, pitch and roll rotations.
They can suffer from a problem called Gimbal Lock. A good explanation of this can be seen on wikipedia here: http://en.wikipedia.org/wiki/Gimbal_lock but basically two of the axis of rotation may become aligned and so you loose a degree of freedom. For example a pitch of +-90° would mean that heading and bank rotate around the same axis.
If you use euler angles to orient something in 3D space and try to transition between orientations by interpolating the component angles you probably wont get the transitions you expect as they may not follow the shortest path between the two orientations.
There's no standard to what order the component axis rotations are applied. The most common convention seems to be what we do in Cogl with heading (y-axis), pitch (x-axis) and then roll (z-axis), but other software might apply x-axis, y-axis then z-axis or any other order so you need to consider this if you are accepting euler rotations from some other software. Other software may also use slightly different aeronautical terms, such as "yaw" instead of "heading" or "bank" instead of "roll".

To minimize the aliasing issue we may refer to "Canonical Euler" angles where heading and roll are restricted to +- 180° and pitch is restricted to +- 90°. If pitch is +- 90° bank is set to 0°.

Quaternions don't suffer from Gimbal Lock and they can be nicely interpolated between, their disadvantage is that they don't have an intuitive representation.

A common practice is to accept angles in the intuitive Euler form and convert them to quaternions internally to avoid Gimbal Lock and handle interpolations. See cogl_quaternion_init_from_euler().

Details

CoglEuler

typedef struct {
  float heading;
  float pitch;
  float roll;
} CoglEuler;

Represents an ordered rotation first of heading degrees around an object's y axis, then pitch degrees around an object's x axis and finally roll degrees around an object's z axis.

Note

It's important to understand the that axis are associated with the object being rotated, so the axis also rotate in sequence with the rotations being applied.

The members of a CoglEuler can be initialized, for example, with cogl_euler_init() and cogl_euler_init_from_quaternion().

You may also want to look at cogl_quaternion_init_from_euler() if you want to do interpolation between 3d rotations.

float `heading`;	Angle to rotate around an object's y axis
float `pitch`;	Angle to rotate around an object's x axis
float `roll`;	Angle to rotate around an object's z axis

Since 2.0

cogl_euler_init ()

void                cogl_euler_init                     (CoglEuler *euler,
                                                         float heading,
                                                         float pitch,
                                                         float roll);

Initializes euler to represent a rotation of x_angle degrees around the x axis, then y_angle degrees around the y_axis and z_angle degrees around the z axis.

`euler` :	The CoglEuler angle to initialize
`heading` :	Angle to rotate around an object's y axis
`pitch` :	Angle to rotate around an object's x axis
`roll` :	Angle to rotate around an object's z axis

Since 2.0

cogl_euler_init_from_matrix ()

void                cogl_euler_init_from_matrix         (CoglEuler *euler,
                                                         const CoglMatrix *matrix);

Extracts a euler rotation from the given matrix and initializses euler with the component x, y and z rotation angles.

`euler` :	The CoglEuler angle to initialize
`matrix` :	A CoglMatrix containing a rotation, but no scaling, mirroring or skewing.

cogl_euler_init_from_quaternion ()

void                cogl_euler_init_from_quaternion     (CoglEuler *euler,
                                                         const CoglQuaternion *quaternion);

Initializes a euler rotation with the equivalent rotation represented by the given quaternion.

`euler` :	The CoglEuler angle to initialize
`quaternion` :	A CoglEuler with the rotation to initialize with

cogl_euler_equal ()

CoglBool            cogl_euler_equal                    (const void *v1,
                                                         const void *v2);

Compares the two given euler angles v1 and v1 and it they are equal returns TRUE else FALSE.

Note

This function only checks that all three components rotations are numerically equal, it does not consider that some rotations can be represented with different component rotations

`v1` :	The first euler angle to compare
`v2` :	The second euler angle to compare
Returns :	`TRUE` if `v1` and `v2` are equal else `FALSE`.

Since 2.0

cogl_euler_copy ()

CoglEuler *         cogl_euler_copy                     (const CoglEuler *src);

Allocates a new CoglEuler and initilizes it with the component angles of src. The newly allocated euler should be freed using cogl_euler_free().

`src` :	A CoglEuler to copy
Returns :	A newly allocated CoglEuler

Since 2.0

cogl_euler_free ()

void                cogl_euler_free                     (CoglEuler *euler);

Frees a CoglEuler that was previously allocated using cogl_euler_copy().

euler :

A CoglEuler allocated via cogl_euler_copy()

Since 2.0

			Cogl 2.0 Reference Manual
Top \| Description