Euler angles and gimbal lock

A rotation in 3D has three degrees of freedom, so the most obvious way to store one is as three angles. A camera in a walkthrough has a heading, a tilt up or down and maybe a bank. An inclined column might be stored as a turn in plan followed by a lean. These three-angle descriptions are called Euler angles. They are easy to type and easy to read, which is why dialogs and file formats use them.

The widget shows the same idea the way a physical gimbal (the frame of rings that holds a ship’s compass or a camera stabiliser) does: each ring turns about one axis and carries the rings inside it.

Yaw, pitch and roll

With Z up, the usual convention in BIM is:

• Yaw (heading): a turn about the vertical Z axis, the angle you see in plan.
• Pitch: a turn about the object’s own Y axis, after the yaw. It tips the nose up or down.
• Roll (bank): a turn about the object’s own X axis, the nose, after both of the others.

As one matrix this is R = Rz(yaw) · Ry(pitch) · Rx(roll). Read from the right it says “roll about world X, then pitch about world Y, then yaw about world Z”. Read from the left it says “yaw, then pitch about the turned Y, then roll about the turned X”. Both readings give the same matrix, so you will see the convention described both ways: as turns about fixed axes in one order, or about moving axes in the reverse order.

The order matters

Three angles mean nothing until you also know the order and the axes. There are twelve possible conventions (ZYX, XYZ, ZXZ and so on), and different programs, file formats and libraries pick different ones. The same three numbers in a different order give a different orientation:

1var nose = new V3(1, 0, 0);2double yaw = 90, pitch = 30;3 4var zyx = Mul(Rz(yaw), Ry(pitch));      // yaw, then pitch about the turned Y5var yzx = Mul(Ry(pitch), Rz(yaw));      // pitch about world Y first, then yaw6Console.WriteLine($"Rz * Ry: nose -> {Apply(zyx, nose)}");7Console.WriteLine($"Ry * Rz: nose -> {Apply(yzx, nose)}");8 9static double[,] Rz(double d) { double c = Cos(d), s = Sin(d); return new[,] { { c, -s, 0 }, { s, c, 0 }, { 0, 0, 1 } }; }10static double[,] Ry(double d) { double c = Cos(d), s = Sin(d); return new[,] { { c, 0, s }, { 0, 1, 0 }, { -s, 0, c } }; }11static double Cos(double d) => Math.Cos(d * Math.PI / 180);12static double Sin(double d) => Math.Sin(d * Math.PI / 180);13 14static double[,] Mul(double[,] a, double[,] b)15{16    var m = new double[3, 3];17    for (int i = 0; i < 3; i++)18        for (int j = 0; j < 3; j++)19            for (int k = 0; k < 3; k++) m[i, j] += a[i, k] * b[k, j];20    return m;21}22 23static V3 Apply(double[,] m, V3 v) => new(24    m[0, 0] * v.X + m[0, 1] * v.Y + m[0, 2] * v.Z,25    m[1, 0] * v.X + m[1, 1] * v.Y + m[1, 2] * v.Z,26    m[2, 0] * v.X + m[2, 1] * v.Y + m[2, 2] * v.Z);27 28readonly record struct V3(double X, double Y, double Z)29{30    public static V3 operator +(V3 a, V3 b) => new(a.X + b.X, a.Y + b.Y, a.Z + b.Z);31    public static V3 operator -(V3 a, V3 b) => new(a.X - b.X, a.Y - b.Y, a.Z - b.Z);32    public static V3 operator *(V3 v, double k) => new(v.X * k, v.Y * k, v.Z * k);33    public static double Dot(V3 a, V3 b) => a.X * b.X + a.Y * b.Y + a.Z * b.Z;34    public static V3 Cross(V3 a, V3 b) =>35        new(a.Y * b.Z - a.Z * b.Y, a.Z * b.X - a.X * b.Z, a.X * b.Y - a.Y * b.X);36    public double Length => Math.Sqrt(Dot(this, this));37    public V3 Normalized() => this * (1 / Length);38    static string F(double v) => Math.Abs(v) < 5e-4 ? "0" : v.ToString("0.###");39    public override string ToString() => $"({F(X)}, {F(Y)}, {F(Z)})";40}

Rz * Ry: nose -> (0, 0.866, -0.5)
Ry * Rz: nose -> (0, 1, 0)

In the first order the nose swings round to +Y and then tips down by 30°. In the second, the pitch happens while the nose still points along X, but the yaw then carries it to +Y, and the pitch was about world Y, which is now the nose itself: the tilt has turned into a roll and the nose stays level. (With Z up, a positive turn about Y tips the nose down, because the right-hand rule carries X towards −Z.)

Gimbal lock

Set the pitch in the widget to 90° and move the yaw and roll sliders. They now do the same thing. The pitch has tipped the red roll ring into the plane of the blue yaw ring, so both turn the body about the same vertical line. Three angles, but only two independent ways to turn: this is gimbal lock.

You can see it in the matrix. At pitch = 90°, Ry turns the X axis onto −Z, so a roll about the turned X is a turn about −Z, which is a yaw in the opposite direction. Only yaw − roll has any effect:

1var pairs = new (double[] A, double[] B)[]2{3    (new double[] { 30, 90, 0 }, new double[] { 0, 90, -30 }),4    (new double[] { 30, 90, 0 }, new double[] { 50, 90, 20 }),5    (new double[] { 30, 89, 0 }, new double[] { 0, 89, -30 })6};7foreach (var (a, b) in pairs)8{9    bool same = Same(Euler(a[0], a[1], a[2]), Euler(b[0], b[1], b[2]));10    Console.WriteLine($"({string.Join(", ", a)}) and ({string.Join(", ", b)}): same orientation = {same}");11}12 13static double[,] Euler(double yaw, double pitch, double roll) => Mul(Rz(yaw), Mul(Ry(pitch), Rx(roll)));14static double[,] Rx(double d) { double c = Cos(d), s = Sin(d); return new[,] { { 1, 0, 0 }, { 0, c, -s }, { 0, s, c } }; }15static double[,] Ry(double d) { double c = Cos(d), s = Sin(d); return new[,] { { c, 0, s }, { 0, 1, 0 }, { -s, 0, c } }; }16static double[,] Rz(double d) { double c = Cos(d), s = Sin(d); return new[,] { { c, -s, 0 }, { s, c, 0 }, { 0, 0, 1 } }; }17static double Cos(double d) => Math.Cos(d * Math.PI / 180);18static double Sin(double d) => Math.Sin(d * Math.PI / 180);19 20static double[,] Mul(double[,] a, double[,] b)21{22    var m = new double[3, 3];23    for (int i = 0; i < 3; i++)24        for (int j = 0; j < 3; j++)25            for (int k = 0; k < 3; k++) m[i, j] += a[i, k] * b[k, j];26    return m;27}28 29static bool Same(double[,] a, double[,] b)30{31    for (int i = 0; i < 3; i++)32        for (int j = 0; j < 3; j++)33            if (Math.Abs(a[i, j] - b[i, j]) > 1e-9) return false;34    return true;35}

(30, 90, 0) and (0, 90, -30): same orientation = True
(30, 90, 0) and (50, 90, 20): same orientation = True
(30, 89, 0) and (0, 89, -30): same orientation = False

Nothing is wrong with the orientation itself: the body can still point anywhere. What breaks is the description. Near pitch = ±90°:

• Going back from a matrix to angles has no unique answer, so a round trip through a file or a dialog can change yaw and roll even though the object has not moved.
• A small change in orientation can need a huge jump in yaw and roll, so animations and camera paths that blend the angles spin wildly.
• One direction of turning simply cannot be reached by a small change of the three angles.

Every three-angle convention has a pitch like this somewhere; choosing a different order only moves the problem. In BIM it bites for things that really do point straight up or down: a camera looking straight down for a plan view, a vertical pipe or duct segment, a column whose “nose” is its axis.

Where Euler angles are still the right tool

• User input and display: “rotate 30° in plan, tilt 5°” is how people think. Keep the angles for the dialog.
• Rotations that stay well away from the lock: a family that only turns in plan and tilts a few degrees never gets near pitch = 90°.
• Storage formats that ask for them. Convert once on import, then work with a matrix or a quaternion.

For composing, interpolating and storing rotations inside a program, the next two lessons use quaternions, which have no lock and no special angle.

1foreach (var a in new[] { (40.0, 25.0, -60.0), (-120.0, -10.0, 170.0), (75.0, 90.0, 15.0) })2{3    var (y, p, r) = ToEuler(Euler(a.Item1, a.Item2, a.Item3));4    Console.WriteLine($"{a} -> ({y:0.#}, {p:0.#}, {r:0.#})");5}6 7static (double Yaw, double Pitch, double Roll) ToEuler(double[,] m)8{9    double sp = Math.Clamp(-m[2, 0], -1, 1);10    double pitch = Deg(Math.Asin(sp));11    if (Math.Abs(sp) > 0.99999)                                  // gimbal lock: only yaw - roll is known12        return (Deg(Math.Atan2(-m[0, 1], m[1, 1])), pitch, 0);13    return (Deg(Math.Atan2(m[1, 0], m[0, 0])), pitch, Deg(Math.Atan2(m[2, 1], m[2, 2])));14}15 16static double Deg(double r) => r * 180 / Math.PI;17static double[,] Euler(double yaw, double pitch, double roll) => Mul(Rz(yaw), Mul(Ry(pitch), Rx(roll)));18static double[,] Rx(double d) { double c = Cos(d), s = Sin(d); return new[,] { { 1, 0, 0 }, { 0, c, -s }, { 0, s, c } }; }19static double[,] Ry(double d) { double c = Cos(d), s = Sin(d); return new[,] { { c, 0, s }, { 0, 1, 0 }, { -s, 0, c } }; }20static double[,] Rz(double d) { double c = Cos(d), s = Sin(d); return new[,] { { c, -s, 0 }, { s, c, 0 }, { 0, 0, 1 } }; }21static double Cos(double d) => Math.Cos(d * Math.PI / 180);22static double Sin(double d) => Math.Sin(d * Math.PI / 180);23 24static double[,] Mul(double[,] a, double[,] b)25{26    var m = new double[3, 3];27    for (int i = 0; i < 3; i++)28        for (int j = 0; j < 3; j++)29            for (int k = 0; k < 3; k++) m[i, j] += a[i, k] * b[k, j];30    return m;31}

(40, 25, -60) -> (40, 25, -60)
(-120, -10, 170) -> (-120, -10, 170)
(75, 90, 15) -> (60, 90, 0)