The coordinate system

Transformations between the Earth coordinate frame and the device coordinate frame uses the following system of rotations.

Rotations use the right-hand convention, such that positive rotation around an axis is clockwise when viewed along the positive direction of the axis. When considering rotations, always think in terms of looking down: either at your feet on the ground or at a device (or map) lying flat on a table. We count clockwise rotation as a positive number, and anti-clockwise as negative. In this case, rotations are measured in degrees.

If you are not familiar with using a compass to navigate, here is an illustrated explanation of relating compass readings to the real-world/a map.

As well as the (2D) left/right, forward/backward directions on a map (or HTML5 canvas!), we need to consider other types of movements.

For example height/depth: there might be a huge difference in position between being at the top or the bottom of a cliff, and yet the horizontal distance from one to the other is small. 

Another direction that is not apparent when we assume our world is as flat as a map, is to tilt. If you've ever ridden a motor-cycle you will know that it is easier to change its direction by leaning over, than by trying to turn the handlebar. Imagine then, tilting or twisting your device to steer your character in a motorcycle or airplane game!

Before making use of a location-aware device, we must align its understanding of direction with our own view of 'the Earth'. Once we have a unified coordinate system, we apply rotations in the following order:

Rotate the device frame around its z axis by alpha degrees, with alpha in [0, 360]

Device in the initial position, with Earth (XYZ) and body (xyz) frames aligned.

Device rotated through angle beta about new x axis, with previous locations of y and z axes shown as y₀ and z₀.

Rotate the device frame around its y axis by gamma degrees, with gamma in [-90, 90]

Device in the initial position, with Earth (XYZ) and body (xyz) frames aligned.