Quaternion

Overview

A quaternion is a set of four values (W X Y Z) that specify a rotation in 3D space. To specify a particular rotation you need to think about the axis about which the rotation is made and the angle or amount by which the model is to be rotated.

For a given axis (x y z) and angle (a), the quaternion representing a rotation of a degrees around the axis from the origin (0,0,0) to (x,y,x) is:

W = cosine( 0.5 * a )

X = x * sine( 0.5 * a )

Y = y * sine( 0.5 * a )

Z = z * sine( 0.5 * a )

So a rotation of 90 degrees about the z axis (0 0 1) would be:

W = cosine ( 45 degrees ) = 0.707..

X = 0 * sine( 45 degrees ) = 0

Y = 0 * sine( 45 degrees ) = 0

Z = 1 * sine( 45 degrees ) = 0.707..

Now because quaternions are normalised (adjusted so that W * W + X * X + Y * Y + Z * Z = 1) when Oolite reads them in, you can multiply each part of a quaternion by the same value and still have it represent the same angle. So this rotation can also be represented as W = 1, X = 0, Y = 0, Z= 1 (let's use [1 0 0 1] as shorthand).

Example

Oolite uses quaternions to specify rotations in some parts of shipdata.plist, most notably in the subentities part of an entry, like here in the entry for coriolis-station:

Code:

<string>new_coriolis.dat</string> 
<key>name</key> 
<string>Coriolis Station</string> 
<key>port_radius</key> 
<real>500</real> 
<key>roles</key> 
<string>coriolis station</string> 
<key>subentities</key> 
<array> 
   <string>dock 0 0 500 1 0 0 0</string> 
   <string>arc-detail 0 0 0 1 0 0 0</string> 
   <string>arc-detail 0 0 0 1 0 0 1</string> 
   <string>arc-detail 0 0 0 0 0 0 1</string> 
   <string>arc-detail 0 0 0 1 0 0 -1</string> 

The last four numbers after the four 'arc-detail' lines are the W X Y and Z of quaternions representing rotations about the z-axis of 0 degrees, 90 degrees, 180 degrees, and 270 degrees (the first three numbers are the subentity's position relative to the station, in this case all are at the same place at the station's origin).

---