View source for Euler Angle Convention Used in Doom3

[http://en.wikipedia.org/wiki/Euler_angles 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 == 
To determine the order of multiple rotations, Doom3 uses the "yaw, pitch, roll" convention (also known as "zyx," the full rotation matrix for this convention is given in [http://en.wikipedia.org/wiki/Euler_angles 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.  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".  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 does matter.

== 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".

== Attaching to AI Joints of Unknown Orientation ==
When attaching objects to AI joints and trying to orient the attached object relative to the joint, oftentimes you don't know how the joint is oriented relative to the world axes.  You can use '''r_showskel 1''' in the console to show the joints and display a line for each axis.  You still don't know which axis is which.  To figure out how to orient something relative to the joint, first apply a yaw rotation by setting the attachment angles to "0 <test angle> 0", and see how that differs from angles of "0 0 0".  (It is easiest to see the difference by spawning the AI with the attachment angle set to "0 0 0", changing the angle, then calling '''reloaddecls''' and spawning another AI).  Now you know which way yaw rotates.  Do the same for pitch, now you know which way pitch rotates, and by process of elimination you know roll.  Now you know what will happen when you input angles to orient something relative to the joint.  First it will rotate in the sense you identified as yaw, then in pitch, then finally in roll.  

{{editing}} {{coding}} {{ai}} [[Category:Conventions]]