IMU fusion libraries (the MPU-6050's DMP, the BNO055, Madgwick and Mahony filters) report orientation as a quaternion: four numbers w, x, y, z. People think in roll, pitch and yaw. Converting between them is a few lines of maths, and the details are where the bugs live.
Why quaternions at all
Euler angles describe an orientation as three rotations in turn. They're easy to read but have two problems: the order of the rotations matters, and at a pitch of ±90° they break down (gimbal lock, below). Quaternions describe the same orientation as a single rotation about an axis, with no special cases, which is why filters use them internally.
A rotation of angle θ about a unit axis (a_x, a_y, a_z) is:
w = cos(θ/2)
x = a_x · sin(θ/2), y = a_y · sin(θ/2), z = a_z · sin(θ/2)
| Rotation | w | x | y | z |
|---|---|---|---|---|
| none (level, facing forward) | 1 | 0 | 0 | 0 |
| 90° yaw (about Z) | 0.7071 | 0 | 0 | 0.7071 |
| 180° yaw | 0 | 0 | 0 | 1 |
| 90° roll (about X) | 0.7071 | 0.7071 | 0 | 0 |
The convention: ZYX
The formulas below use the aerospace ZYX order: yaw about Z first, then pitch about the new Y, then roll about the newest X. It's what most IMU libraries and flight controllers use. If your library documents a different order, its angles won't match these, and that's the most common reason two tools disagree.
Quaternion → roll, pitch, yaw
Normalise first: divide w, x, y, z by √(w² + x² + y² + z²). Then:
roll = atan2( 2(w·x + y·z), 1 − 2(x² + y²) )
pitch = asin( 2(w·y − z·x) ) clamp the argument to [−1, 1]
yaw = atan2( 2(w·z + x·y), 1 − 2(y² + z²) )
Example. (w, x, y, z) = (0.896, 0.1713, 0.2525, 0.3225) gives roll 30°, pitch 20°, yaw 45°.
Why normalising matters
Sensor output and hand-typed values are often slightly off unit length, and the formulas assume a unit quaternion. Skip the normalisation and the angles come out wrong. Take (1, 1, 0, 0), which is a 90° roll that just hasn't been normalised. Plugged in directly, the roll formula gives atan2(2, −1) = 116.6°. Normalised to (0.7071, 0.7071, 0, 0), it gives the correct 90°.
A slightly-off example: (0.9, 0.1, 0.2, 0.3) has length 0.9747. Normalised, it is roll 19.44°, pitch 18.41°, yaw 40.05°.
Roll, pitch, yaw → quaternion
With half-angles c_r = cos(roll/2), s_r = sin(roll/2), and the same for pitch (p) and yaw (y):
w = c_r·c_p·c_y + s_r·s_p·s_y
x = s_r·c_p·c_y − c_r·s_p·s_y
y = c_r·s_p·c_y + s_r·c_p·s_y
z = c_r·c_p·s_y − s_r·s_p·c_y
Roll 30°, pitch 20°, yaw 45° gives (0.896, 0.1713, 0.2525, 0.3225), the example above in reverse. The result is always a unit quaternion.
q and −q are the same orientation
(−0.9239, 0, 0, −0.3827) and (0.9239, 0, 0, 0.3827) both mean a 45° yaw. Filters can flip sign between readings. That's harmless for the angles but matters if you interpolate or average quaternions: flip one so their dot product is positive first.
Gimbal lock
At a pitch of exactly ±90° the nose points straight up or down, and roll and yaw become rotations about the same axis. Only their difference is defined. Roll 10°, pitch 90°, yaw 0° and roll 0°, pitch 90°, yaw −10° are the same quaternion, (0.7044, 0.0616, 0.7044, −0.0616). Any conversion has to pick one split; near ±90° the angles can jump wildly between readings.
The fix is to keep the quaternion for control and maths and convert to Euler angles only for display, or to choose a convention whose singularity sits somewhere your robot never points.
Common mistakes
- Mixing up the component order. Some libraries store (w, x, y, z), others (x, y, z, w). A wrong order gives nonsense angles.
- Skipping normalization.
- Assuming a different rotation order. XYZ and ZYX give different angles for the same orientation.
- Not clamping the asin argument. Rounding can push it to 1.0000001 and asin returns NaN.
- Degrees vs radians. The trig functions want radians.
Try it
The IMU orientation converter converts quaternions to roll, pitch and yaw and back in the ZYX convention. It normalises the input and tells you when it did, and it warns you at gimbal lock. When the angles feed a control loop, the PID tuning helper is the next step.
For a related walkthrough, read Bode Plot: Gain and Phase Margin Example.