Quaternion Rotation Visualizer

Hold a book flat in front of you. Give it a quarter turn about a line pointing to your right, then a quarter turn about the vertical. Start again and make the same two turns in the opposite order. The book ends up facing two different ways.

That small experiment is the whole difficulty of rotation in three dimensions. Turns do not commute, so an orientation cannot be stored as a casual list of how much to turn about each axis without also storing which axis came first, whether the axes moved with the object, and which way counts as positive. Most rotation bugs are not arithmetic mistakes. They are two correct pieces of code that disagree about one of those choices.

Why three angles feel right

A rigid body pinned at one point has three degrees of freedom, so three numbers ought to be enough, and they are. Leonhard Euler introduced three angles for exactly this purpose: turn about one axis, then a second, then a third, and any orientation can be reached. The appeal is that each number means something to a person. A pilot reads them as heading, elevation and bank.

The trouble starts with the word “then”. There are 12 sequences of axes that work. Six repeat the first axis at the end, such as Z, X, Z, and are called proper Euler angles. Six use three different axes, such as Z, Y, X, and carry the names of Peter Guthrie Tait and George Bryan; they are the yaw, pitch and roll of aircraft and ships. Each sequence gives a different triple of numbers for the same orientation.

Each sequence can also be read two ways. In the intrinsic reading every turn is made about an axis fixed in the body, so the second axis has already been moved by the first turn. In the extrinsic reading every turn is made about an axis fixed in the room. The two are tied together neatly: intrinsic Z, Y, X is the same rotation as extrinsic X, Y, Z with the angles listed in reverse. Twelve sequences and two readings make 24 ways to label one orientation with three angles, before anyone has chosen degrees or radians.

A triple such as 30, 20, 10 therefore means nothing by itself. It needs its sequence, its reading and its units written beside it.

The angle that goes missing

Three angles have a deeper flaw than ambiguity, and a mechanical model shows it best. A gimbal is a set of nested rings, each pivoting inside the next, built so that an instrument at the centre can stay pointing the same way while the vehicle around it turns. Three rings give three axes. The outer ring’s axis is fixed to the vehicle, the middle ring’s axis rides on the outer ring, and the inner axis rides on the middle one. It is an intrinsic Euler sequence made of metal.

Now give the middle ring a quarter turn. The inner axis swings round until it lies along the outer axis, and two of the three rings turn the instrument about the same line. One direction of rotation is no longer available. Nothing is jammed, and every ring still spins freely, which is why the name gimbal lock is a little misleading. What has been lost is a degree of freedom.

The numbers show the same thing. Take the aircraft sequence, intrinsic Z, Y, X, and set yaw 35 degrees, pitch 90 and roll 20. Now set yaw 15 and roll 0 instead: the orientation is identical, because at a pitch of 90 degrees only the difference between the first and third angles, here 15 degrees, has any effect. Infinitely many triples name that one orientation. A converter asked for the yaw and the roll must pick one of them, and an honest converter says which. The tool on this page reports the third angle as zero and puts the whole turn in the first.

Proper Euler sequences have the same defect in a different place. Their singular position is a middle angle of zero or 180 degrees, so the untouched starting position is itself singular. Every three-angle scheme has such a spot somewhere. Changing the sequence only moves it.

The designers of the Apollo guidance system met this as a hardware decision. A NASA experience report on that system records that a three-gimbal inertial platform was chosen over a four-gimbal one for its advantages in complexity, weight, power, reliability and cost. A fourth gimbal would have let the platform accommodate every attitude of the spacecraft without gimbal lock. The question, posed in 1961 and 1962, was whether the danger was high enough to need it. The answer was that normal maneuvers could stay clear of the bad attitude by operating procedure, with a warning as it approached.

Software has no weight budget. It can simply stop storing orientation as three angles.

Four numbers and a bridge in Dublin

The replacement is older than aviation. On 16 October 1843 William Rowan Hamilton was walking along the Royal Canal in Dublin with his wife, on his way to preside at a meeting of the Royal Irish Academy, when the rule for multiplying a new kind of number took shape in his mind. He cut it into the stone of Broome Bridge as they passed: i squared, j squared, k squared and the product ijk all equal minus one. His quaternions were the first algebra to be studied in which a times b can differ from b times a.

That failure to commute is exactly what rotations needed. Euler had already proved, in 1775, that any orientation of a body with one fixed point can be reached by a single turn about a single axis. A unit quaternion stores that axis and angle directly: its scalar part is the cosine of half the angle, and its vector part is the axis scaled by the sine of half the angle. Multiplying two quaternions composes two turns, and the order of the factors is the order of the turns.

The opening experiment can be done in numbers. Written scalar first, a quarter turn about X is the quaternion (0.7071, 0.7071, 0, 0) and a quarter turn about Z is (0.7071, 0, 0, 0.7071). Turn about X first and then about the fixed Z axis, and the product is (0.5, 0.5, 0.5, 0.5): a single turn of 120 degrees about the diagonal (1, 1, 1). Make the second turn about the body’s own Z axis instead and the result is 120 degrees about (1, -1, 1). The same two turns give two outcomes, and the only difference is the side on which the second factor is written.

The half angle has a curious consequence. Add a full 360 degrees to a turn and the object is back where it was, but the half angle has advanced by only 180, so every component of the quaternion has changed sign. So q and -q are the same rotation. Unit quaternions form a sphere in four dimensions, and each orientation appears on it twice, at opposite points. Code that compares or averages orientations has to remember that.

There is no missing angle on that sphere. Every direction of turning is available from every point, which is why strapdown inertial navigation integrates its sensed rotations with quaternion methods. Three angles are best kept for showing the result to a person. A 1977 NASA working note for the Space Shuttle program opens by citing the extensive use of the quaternion in the onboard computer. Its appendix then tabulates all twelve Euler sequences, because the engineers still needed to read and write angles.

Blending two orientations

The sphere also answers a question that angles answer badly: what lies part of the way between two orientations? Blending each Euler angle separately gives a path that depends on the sequence chosen and does not turn at a steady rate. On the quaternion sphere the natural path is the great arc between the two points. Moving along it at a steady rate is spherical linear interpolation, slerp for short, which Ken Shoemake brought into computer animation in a 1985 paper. The object turns about one fixed axis at constant angular speed.

A cheaper trick is to draw the straight chord between the two quaternions and stretch each point of it back onto the sphere. This normalized blend, often called nlerp, reaches the same two ends along the same arc, but not at a steady rate. Measured in the tool for a turn of 90 degrees, its angular speed climbs from 81 to 95 degrees per unit of time and falls back again, where slerp holds 90 throughout. For small turns the difference is hard to see. Near a half turn, the middle of the path runs almost twice as fast as the ends.

Both methods have to face the double cover. Because q and -q are the same orientation but different points, there are two arcs to choose from, a short one and a long one. The usual rule is to negate one end when the dot product of the two quaternions is negative, which keeps the turn at 180 degrees or less. A blend that forgets the rule will sometimes send an object the long way round for no visible reason.

The traps, in the order they bite

First comes component order. Some code lists the scalar first, as w, x, y, z, and some lists it last. Four numbers pasted in the wrong order still have length one, so nothing complains. Second comes the product. A flipped multiplication, in which i times j is minus k, is also in common use and is often associated with one NASA laboratory; a 2018 paper in the journal Aerospace argues for discontinuing it. Under the flipped rule the matrix of a quaternion comes out transposed.

Third is active against passive. The same matrix either turns a vector inside a fixed frame or gives the coordinates of a fixed vector in a turned frame, and each is the inverse of the other. Fourth is handedness and the sign of an angle: in a right-handed frame, a positive quarter turn about Z carries the X axis onto Y. Fifth is everything already said about Euler sequences. None of these can be detected from the numbers alone.

No tool can recover a convention that was never written down, and this one does not try. It works in right-handed frames with Hamilton’s product only, and says so; numbers from a left-handed frame or a flipped product have to be converted by someone who knows their origin. It also treats an orientation as a point with no history. A quaternion records which way an object faces, not how many times it spun to get there, so a turn of 370 degrees is stored as a turn of 10.

The safest habit costs one line. Beside every stored rotation, write the order of the components, the product, the sense, the frame, and for angles the sequence, the reading and the units. The mathematics has been settled since a walk beside a canal. The labels are where the errors still come from.