Euler Angle Convention Used in Doom3

From The DarkMod Wiki
Jump to navigationJump to search

Euler Angles are a way of specifying the orientation of a given object relative to three reference axes in the world. To orient objects, Doom3 uses the "angles" spawnarg, which takes three space-delimited values, defined as: "pitch yaw roll". We need to know more than this to precisely specify the orientation of something. We need to know which axis is which, and we need to know the order in which these operations are performed.

Definition of axes

Imagine you are standing in a Doom3 map. The z axis is up. A pure yaw rotates about the z axis. The x axis is forward. A pure roll rotates about the x axis. The y axis extends out to your left. A pure pitch rotates about the y axis.

Order of rotations

It turns out that Doom3 uses the "yaw, pitch, roll" convention (also known as "zyx," the full rotation matrix for this convention is given in this article). Let's say you have entered a spawnarg as "pitch yaw roll." This is how Doom3 applies these values to orient an object: First, the yaw is applied about the world z axis, second, the pitch is applied about the yawed y axis, and third, the roll is applied about the yawed and pitched x axis.

Sign Conventions

In mathematics, a clockwise rotation is a positive angle, and a counterclockwise rotation is a negative angle. Pitch, yaw and roll have their own conventions (positive pitch is rotating something from forward to the ceiling). The combination of the defined axes, the mathematical rotation sign convention, and the sign conventions of pitch, yaw and roll result in some sign changes when going from the pitch, yaw, roll angles to the actual angular rotation about the axis that is entered in to the rotation matrix. The conventions are described below:

Pitch is positive when pitching from forward to up. This is a counterclockwise rotation about the y (left) axis. Therefore, positive pitch means negative rotation angle. Yaw is positive when rotating from the forward to the right. This is a counterclockwise rotation about the z (up) axis. Therefore, positive yaw means negative rotation angle. Roll is positive when rotating from up to right. This is a clockwise rotation about the x (forward) axis. Therefore, positive roll means positive rotation angle.

Example 1

Suppose you start out with an airplane pointing straight ahead with level wings. You want the airplane to end up pointing all the way to your right, with the right wing pointing down at the ground. Keeping in mind that the angles are applied in the order of yaw, pitch, roll, we enter a yaw of +90 degrees, and a roll of 90 degrees. We would enter in an angles spawnarg "pitch yaw roll" of "0 90 90". (NOTE: If instead the roll had been applied before the yaw, these angles would have resulted in an airplane pointing straight down with its wings extending forward and back, so the order of rotations matters).

Example 2

Again you start out with an airplane pointing straight ahead with wings level. Now, you want the airplane nose pointing to your left and up 45 degrees, and you want the airplane to be upside-down. Again, yaw is applied first, then pitch, then roll. So we know yaw must be -90, pointing the airplane left. Pitch is +45, tipping the nose up, and roll is 180, rotating the plane upside-down about its long axis. We therefore enter an angles spawnarg "pitch yaw roll" of "45 -90 180".