Lesson 31 of 44 16 minAdvanced

Quaternions without fear

Store a rotation as four numbers, an axis and half the angle. Rotate points with q·v·q*, combine rotations by multiplying, and see why q and −q are the same rotation.

Quaternions have a reputation for being mysterious, mostly because of how they are usually introduced: as four-dimensional numbers with three different square roots of −1. You do not need any of that to use them well. For rotations, a quaternion is just an axis and an angle, packed into four numbers in a clever way.

Interactive

A quaternion is an axis and half an angle

Use −q instead of q

angle θ = 90°

w0.707

x0.000

y0.000

z0.707

θ / 2	45°
w = cos θ/2	0.707
(x, y, z) = sin θ/2 · k	(0, 0, 0.707)
\|q\|	1.000
nose (1, 0, 0) →	(0, 1, 0)

q = (cos 45°, sin 45° · k). The axis sits in x, y, z, scaled by sin θ/2, and w = cos θ/2 says how far to turn. All four squared add up to 1, which is why the length stays 1.

Four numbers from an axis and an angle

To turn by θ about a unit axis k = (kx, ky, kz), write:

q = (w, x, y, z) = (cos θ/2, kx·sin θ/2, ky·sin θ/2, kz·sin θ/2)

The axis sits in the last three numbers, scaled down by sin θ/2, and w says how far to turn. Because cos² + sin² = 1 and k has length 1, w² + x² + y² + z² = 1: a rotation is always a unit quaternion. No angle is special. There is no lock, and every orientation is reached by a small change of the four numbers from any nearby orientation.

Rotation	w	x	y	z
None (identity)	1	0	0	0
90° about Z	0.707	0	0	0.707
180° about X	0	1	0	0
120° about (1, 1, 1)	0.5	0.5	0.5	0.5
360° about any axis	−1	0	0	0

Multiplying quaternions

Quaternions have their own multiplication (the Hamilton product, after the mathematician who invented them). You can treat it as a formula to copy: it is the operator * in the Q struct below. What matters is what it does: a · b is the rotation b followed by a, just as with matrices. Like matrices it is associative but not commutative.

To rotate a vector v, write it as a quaternion with w = 0 and compute q · v · q*, where q* = (w, −x, −y, −z) is the conjugate. For a unit quaternion the conjugate is also the inverse, the turn back. You do not need to know why the vector is sandwiched like this, only that the result again has w = 0 and its x, y, z are the rotated vector.

QuaternionRotate.cs

1var turnZ = Q.FromAxisAngle(new V3(0, 0, 1), 90);2var turnX = Q.FromAxisAngle(new V3(1, 0, 0), 90);3Console.WriteLine($"90 deg about Z: {turnZ}");4Console.WriteLine($"(1, 0, 0) -> {turnZ.Rotate(new V3(1, 0, 0))}");5 6var both = turnZ * turnX;                      // turn about X first, then about Z7Console.WriteLine($"X then Z: {both}");8foreach (var v in new V3[] { new(1, 0, 0), new(0, 1, 0), new(0, 0, 1) })9    Console.WriteLine($"  {v} -> {both.Rotate(v)}");10 11var (axis, angle) = ToAxisAngle(both);12Console.WriteLine($"One turn of {angle:0.#} deg about {axis}");13 14static (V3 Axis, double Degrees) ToAxisAngle(Q q)15{16    if (q.W < 0) q = -q;                                       // pick the turn of 180 deg or less17    double half = Math.Acos(Math.Min(1, q.W)), s = Math.Sin(half);18    if (s < 1e-9) return (new V3(1, 0, 0), 0);                 // no turn: any axis will do19    return (new V3(q.X / s, q.Y / s, q.Z / s), 2 * half * 180 / Math.PI);20}21 22readonly record struct Q(double W, double X, double Y, double Z)23{24    public static Q FromAxisAngle(V3 axis, double degrees)25    {26        var k = axis.Normalized();27        double h = degrees * Math.PI / 360, s = Math.Sin(h);     // half the angle, in radians28        return new(Math.Cos(h), k.X * s, k.Y * s, k.Z * s);29    }30    public static Q operator *(Q a, Q b) => new(               // b first, then a31        a.W * b.W - a.X * b.X - a.Y * b.Y - a.Z * b.Z,32        a.W * b.X + a.X * b.W + a.Y * b.Z - a.Z * b.Y,33        a.W * b.Y - a.X * b.Z + a.Y * b.W + a.Z * b.X,34        a.W * b.Z + a.X * b.Y - a.Y * b.X + a.Z * b.W);35    public static Q operator -(Q q) => new(-q.W, -q.X, -q.Y, -q.Z);36    public static double Dot(Q a, Q b) => a.W * b.W + a.X * b.X + a.Y * b.Y + a.Z * b.Z;37    public Q Conjugate => new(W, -X, -Y, -Z);38    public double Length => Math.Sqrt(Dot(this, this));39    public Q Normalized() { double l = Length; return new(W / l, X / l, Y / l, Z / l); }40    public V3 Rotate(V3 v)                                     // q * v * conjugate(q)41    {42        var p = this * new Q(0, v.X, v.Y, v.Z) * Conjugate;43        return new(p.X, p.Y, p.Z);44    }45    static string F(double v) => Math.Abs(v) < 5e-4 ? "0" : v.ToString("0.###");46    public override string ToString() => $"({F(W)}, {F(X)}, {F(Y)}, {F(Z)})";47}48 49readonly record struct V3(double X, double Y, double Z)50{51    public static V3 operator +(V3 a, V3 b) => new(a.X + b.X, a.Y + b.Y, a.Z + b.Z);52    public static V3 operator -(V3 a, V3 b) => new(a.X - b.X, a.Y - b.Y, a.Z - b.Z);53    public static V3 operator *(V3 v, double k) => new(v.X * k, v.Y * k, v.Z * k);54    public static double Dot(V3 a, V3 b) => a.X * b.X + a.Y * b.Y + a.Z * b.Z;55    public static V3 Cross(V3 a, V3 b) =>56        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);57    public double Length => Math.Sqrt(Dot(this, this));58    public V3 Normalized() => this * (1 / Length);59    static string F(double v) => Math.Abs(v) < 5e-4 ? "0" : v.ToString("0.###");60    public override string ToString() => $"({F(X)}, {F(Y)}, {F(Z)})";61}

Output

90 deg about Z: (0.707, 0, 0, 0.707)
(1, 0, 0) -> (0, 1, 0)
X then Z: (0.5, 0.5, 0.5, 0.5)
  (1, 0, 0) -> (0, 1, 0)
  (0, 1, 0) -> (0, 0, 1)
  (0, 0, 1) -> (1, 0, 0)
One turn of 120 deg about (0.577, 0.577, 0.577)

A quarter turn about X followed by a quarter turn about Z is a single turn of 120° about the diagonal (1, 1, 1), which cycles the axes X → Y → Z → X. Getting the axis and angle back out is just the first formula backwards: half the angle is acos w, and the axis is (x, y, z) divided by sin of that half angle.

q and −q are the same rotation

In the widget, turn the angle up to 360°. The box is back where it started, but q = (−1, 0, 0, 0), not (1, 0, 0, 0). Because the formula uses half the angle, the quaternion goes round only halfway while the object makes a full turn, and needs 720° to come back to where it started. Every rotation therefore has exactly two quaternions, q and −q. Tick “Use −q” to see that flipping all four signs does not move the box.

DoubleCover.cs

1var q = Q.FromAxisAngle(new V3(0, 0.6, 0.8), 70);2var full = Q.FromAxisAngle(new V3(0, 0, 1), 360);3var v = new V3(2, 1, 0.5);4 5Console.WriteLine($"q          = {q}");6Console.WriteLine($"-q         = {-q}");7Console.WriteLine($"q rotates  {v} -> {q.Rotate(v)}");8Console.WriteLine($"-q rotates {v} -> {(-q).Rotate(v)}");9Console.WriteLine($"360 deg about Z: {full}, rotates {v} -> {full.Rotate(v)}");10Console.WriteLine($"q . (-q) = {Q.Dot(q, -q):0.###}");11 12readonly record struct Q(double W, double X, double Y, double Z)13{14    public static Q FromAxisAngle(V3 axis, double degrees)15    {16        var k = axis.Normalized();17        double h = degrees * Math.PI / 360, s = Math.Sin(h);     // half the angle, in radians18        return new(Math.Cos(h), k.X * s, k.Y * s, k.Z * s);19    }20    public static Q operator *(Q a, Q b) => new(               // b first, then a21        a.W * b.W - a.X * b.X - a.Y * b.Y - a.Z * b.Z,22        a.W * b.X + a.X * b.W + a.Y * b.Z - a.Z * b.Y,23        a.W * b.Y - a.X * b.Z + a.Y * b.W + a.Z * b.X,24        a.W * b.Z + a.X * b.Y - a.Y * b.X + a.Z * b.W);25    public static Q operator -(Q q) => new(-q.W, -q.X, -q.Y, -q.Z);26    public static double Dot(Q a, Q b) => a.W * b.W + a.X * b.X + a.Y * b.Y + a.Z * b.Z;27    public Q Conjugate => new(W, -X, -Y, -Z);28    public double Length => Math.Sqrt(Dot(this, this));29    public Q Normalized() { double l = Length; return new(W / l, X / l, Y / l, Z / l); }30    public V3 Rotate(V3 v)                                     // q * v * conjugate(q)31    {32        var p = this * new Q(0, v.X, v.Y, v.Z) * Conjugate;33        return new(p.X, p.Y, p.Z);34    }35    static string F(double v) => Math.Abs(v) < 5e-4 ? "0" : v.ToString("0.###");36    public override string ToString() => $"({F(W)}, {F(X)}, {F(Y)}, {F(Z)})";37}38 39readonly record struct V3(double X, double Y, double Z)40{41    public static V3 operator +(V3 a, V3 b) => new(a.X + b.X, a.Y + b.Y, a.Z + b.Z);42    public static V3 operator -(V3 a, V3 b) => new(a.X - b.X, a.Y - b.Y, a.Z - b.Z);43    public static V3 operator *(V3 v, double k) => new(v.X * k, v.Y * k, v.Z * k);44    public static double Dot(V3 a, V3 b) => a.X * b.X + a.Y * b.Y + a.Z * b.Z;45    public static V3 Cross(V3 a, V3 b) =>46        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);47    public double Length => Math.Sqrt(Dot(this, this));48    public V3 Normalized() => this * (1 / Length);49    static string F(double v) => Math.Abs(v) < 5e-4 ? "0" : v.ToString("0.###");50    public override string ToString() => $"({F(X)}, {F(Y)}, {F(Z)})";51}

Output

q          = (0.819, 0, 0.344, 0.459)
-q         = (-0.819, 0, -0.344, -0.459)
q rotates  (2, 1, 0.5) -> (0.214, 2.24, -0.43)
-q rotates (2, 1, 0.5) -> (0.214, 2.24, -0.43)
360 deg about Z: (-1, 0, 0, 0), rotates (2, 1, 0.5) -> (2, 1, 0.5)
q . (-q) = -1

This matters in two places. When you compare two orientations, q and −q must count as equal: test |q₁ · q₂| close to 1 (the dot product of the four numbers), not the numbers themselves. And when you interpolate, the sign decides whether you take the short or the long way round, as the next lesson shows.

Why programs prefer quaternions

	Euler angles	3×3 matrix	Quaternion
Numbers stored	3	9	4
Gimbal lock	Yes	No	No
Combine two rotations	Hard	Matrix product (27 multiplications)	Hamilton product (16)
Rotate a point	Build a matrix first	Cheapest (9 multiplications)	More work; convert to a matrix for many points
Fix rounding drift	Not needed	Re-orthonormalise the columns	Divide by the length
Smooth interpolation	Poor	Poor	Slerp (next lesson)

The usual pattern is to keep a quaternion as the master copy of an orientation, combine and interpolate with it, and convert it to a matrix only when many points have to be transformed. Rounding is the other reason. Every product adds a little error, so after thousands of small turns a rotation is no longer exactly a rotation. Here is a 0.1° turn applied 36,000 times in single precision (float, as graphics code uses):

Drift.cs

1float h = 0.05f * MathF.PI / 180;                       // half of 0.1 deg2float qs = MathF.Sin(h), qc = MathF.Cos(h);3float[] step = { qc, 0, 0.6f * qs, 0.8f * qs };         // 0.1 deg about (0, 0.6, 0.8)4float[] q = { 1, 0, 0, 0 };5 6for (int i = 0; i < 36000; i++)                          // ten full turns7    q = Mul(step, q);8 9Console.WriteLine($"After 36,000 steps |q| = {Len(q):0.000000}");10float l = Len(q);11for (int i = 0; i < 4; i++) q[i] /= l;12Console.WriteLine($"After dividing by it  = {Len(q):0.000000}");13 14static float Len(float[] q) => MathF.Sqrt(q[0] * q[0] + q[1] * q[1] + q[2] * q[2] + q[3] * q[3]);15 16static float[] Mul(float[] a, float[] b) => new[]17{18    a[0] * b[0] - a[1] * b[1] - a[2] * b[2] - a[3] * b[3],19    a[0] * b[1] + a[1] * b[0] + a[2] * b[3] - a[3] * b[2],20    a[0] * b[2] - a[1] * b[3] + a[2] * b[0] + a[3] * b[1],21    a[0] * b[3] + a[1] * b[2] - a[2] * b[1] + a[3] * b[0]22};

Output

After 36,000 steps |q| = 1.000723
After dividing by it  = 1.000000

The quaternion has grown 0.07% too long, and because q appears twice in q·v·q*, every point it rotates is now scaled by |q|², about 1.0014: a 30 m building would grow by 4 cm. The fix is one division. Repairing a drifted matrix means making three columns unit length and at right angles again (the Gram–Schmidt process), which is more work and easier to get wrong.

Quaternions in .NET

.NET has a ready-made float quaternion in System.Numerics, the same library that provides Vector3 and Matrix4x4. Its CreateFromAxisAngle takes radians, and Quaternion.Concatenate(a, b) means “a, then b”, which is b · a in the Hamilton order used above.

NumericsQuaternion.cs

1using System.Numerics;2 3var turnX = Quaternion.CreateFromAxisAngle(Vector3.UnitX, MathF.PI / 2);4var turnZ = Quaternion.CreateFromAxisAngle(Vector3.UnitZ, MathF.PI / 2);5 6var both = Quaternion.Concatenate(turnX, turnZ);        // X first, then Z7Console.WriteLine($"Same as turnZ * turnX: {Quaternion.Dot(both, turnZ * turnX) > 0.99999f}");8Console.WriteLine($"(0, 1, 0) -> {F(Vector3.Transform(Vector3.UnitY, both))}");9 10var m = Matrix4x4.CreateFromQuaternion(both);           // for transforming many points11Console.WriteLine($"Matrix gives the same: {F(Vector3.Transform(Vector3.UnitY, m))}");12 13static string F(Vector3 v) => $"({R(v.X)}, {R(v.Y)}, {R(v.Z)})";14static string R(float x) => MathF.Abs(x) < 5e-4f ? "0" : x.ToString("0.###");

Output

Same as turnZ * turnX: True
(0, 1, 0) -> (0, 0, 1)
Matrix gives the same: (0, 0, 1)

Quick check

What is the quaternion for a 180° turn about the Z axis?

Quick check

Two stored orientations have quaternions q₁ and q₂ with q₁ · q₂ = −1 (dot product). What does that mean?

Practice

Turn Euler angles into a quaternion by multiplying three single-axis quaternions in the same order as the matrices: q = qZ(yaw) · qY(pitch) · qX(roll). For yaw 30°, pitch 20° and roll 10°, rotate the nose (1, 0, 0) and the up vector (0, 0, 1) with it, and check the answers against the Euler matrix Rz·Ry·Rx.

Show a hint

Use Q.FromAxisAngle for the three single turns. For the matrix, reuse Euler, Mul and the rotation matrices from GimbalLock.cs and write a small Apply.

Show the solution

Solution.cs

1double yaw = 30, pitch = 20, roll = 10;2var q = Q.FromAxisAngle(new V3(0, 0, 1), yaw)3      * Q.FromAxisAngle(new V3(0, 1, 0), pitch)4      * Q.FromAxisAngle(new V3(1, 0, 0), roll);5var m = Euler(yaw, pitch, roll);6Console.WriteLine($"q = {q}");7 8foreach (var v in new V3[] { new(1, 0, 0), new(0, 0, 1) })9{10    V3 a = q.Rotate(v), b = Apply(m, v);11    Console.WriteLine($"{v}: quaternion {a}, matrix {b}, match {(a - b).Length < 1e-12}");12}13 14static V3 Apply(double[,] m, V3 v) => new(15    m[0, 0] * v.X + m[0, 1] * v.Y + m[0, 2] * v.Z,16    m[1, 0] * v.X + m[1, 1] * v.Y + m[1, 2] * v.Z,17    m[2, 0] * v.X + m[2, 1] * v.Y + m[2, 2] * v.Z);18static double[,] Euler(double yaw, double pitch, double roll) => Mul(Rz(yaw), Mul(Ry(pitch), Rx(roll)));19static double[,] Rx(double d) { double c = Cos(d), s = Sin(d); return new[,] { { 1, 0, 0 }, { 0, c, -s }, { 0, s, c } }; }20static double[,] Ry(double d) { double c = Cos(d), s = Sin(d); return new[,] { { c, 0, s }, { 0, 1, 0 }, { -s, 0, c } }; }21static double[,] Rz(double d) { double c = Cos(d), s = Sin(d); return new[,] { { c, -s, 0 }, { s, c, 0 }, { 0, 0, 1 } }; }22static double Cos(double d) => Math.Cos(d * Math.PI / 180);23static double Sin(double d) => Math.Sin(d * Math.PI / 180);24static double[,] Mul(double[,] a, double[,] b)25{26    var r = 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++) r[i, j] += a[i, k] * b[k, j];30    return r;31}32 33readonly record struct Q(double W, double X, double Y, double Z)34{35    public static Q FromAxisAngle(V3 axis, double degrees)36    {37        var k = axis.Normalized();38        double h = degrees * Math.PI / 360, s = Math.Sin(h);     // half the angle, in radians39        return new(Math.Cos(h), k.X * s, k.Y * s, k.Z * s);40    }41    public static Q operator *(Q a, Q b) => new(               // b first, then a42        a.W * b.W - a.X * b.X - a.Y * b.Y - a.Z * b.Z,43        a.W * b.X + a.X * b.W + a.Y * b.Z - a.Z * b.Y,44        a.W * b.Y - a.X * b.Z + a.Y * b.W + a.Z * b.X,45        a.W * b.Z + a.X * b.Y - a.Y * b.X + a.Z * b.W);46    public static Q operator -(Q q) => new(-q.W, -q.X, -q.Y, -q.Z);47    public static double Dot(Q a, Q b) => a.W * b.W + a.X * b.X + a.Y * b.Y + a.Z * b.Z;48    public Q Conjugate => new(W, -X, -Y, -Z);49    public double Length => Math.Sqrt(Dot(this, this));50    public Q Normalized() { double l = Length; return new(W / l, X / l, Y / l, Z / l); }51    public V3 Rotate(V3 v)                                     // q * v * conjugate(q)52    {53        var p = this * new Q(0, v.X, v.Y, v.Z) * Conjugate;54        return new(p.X, p.Y, p.Z);55    }56    static string F(double v) => Math.Abs(v) < 5e-4 ? "0" : v.ToString("0.###");57    public override string ToString() => $"({F(W)}, {F(X)}, {F(Y)}, {F(Z)})";58}59 60readonly record struct V3(double X, double Y, double Z)61{62    public static V3 operator +(V3 a, V3 b) => new(a.X + b.X, a.Y + b.Y, a.Z + b.Z);63    public static V3 operator -(V3 a, V3 b) => new(a.X - b.X, a.Y - b.Y, a.Z - b.Z);64    public static V3 operator *(V3 v, double k) => new(v.X * k, v.Y * k, v.Z * k);65    public static double Dot(V3 a, V3 b) => a.X * b.X + a.Y * b.Y + a.Z * b.Z;66    public static V3 Cross(V3 a, V3 b) =>67        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);68    public double Length => Math.Sqrt(Dot(this, this));69    public V3 Normalized() => this * (1 / Length);70    static string F(double v) => Math.Abs(v) < 5e-4 ? "0" : v.ToString("0.###");71    public override string ToString() => $"({F(X)}, {F(Y)}, {F(Z)})";72}

Output

q = (0.952, 0.038, 0.189, 0.239)
(1, 0, 0): quaternion (0.814, 0.47, -0.342), matrix (0.814, 0.47, -0.342), match True
(0, 0, 1): quaternion (0.379, 0.018, 0.925), matrix (0.379, 0.018, 0.925), match True

Remember

A rotation of θ about the unit axis k is the unit quaternion (cos θ/2, k·sin θ/2).
a · b means b, then a; rotate a vector with q · v · q*, where q* = (w, −x, −y, −z) is the inverse.
q and −q are the same rotation; compare orientations with |q₁ · q₂| ≈ 1.
Quaternions have no gimbal lock, are cheap to combine and are repaired by dividing by their length.
In .NET use System.Numerics.Quaternion: angles in radians, Concatenate(a, b) is a then b, and storage order is X, Y, Z, W.

Foundations

Vectors

Lines and curves

Planes and polygons

Matrices and transforms

Rotations in depth

3D geometry and solids

Master level

Quaternions without fear

A quaternion is an axis and half an angle

Four numbers from an axis and an angle

Multiplying quaternions

q and −q are the same rotation

Why programs prefer quaternions

Quaternions in .NET

Remember