Quaternions
***********

Quaternions are hypercomplex numbers used to represent spatial rotations in three dimensions.  This set of routines provides a useful basis for working with quaternions in Octave.  A tutorial is in the Octave source, scripts/quaternion/quaternion.ps.

These functions were written by A. S. Hodel, Associate Professor, Auburn University.

 -- Function File: [A, B, C, D] = quaternion (w)
 -- Function File: [VV, THETA] = quaternion (w)
 -- Function File: W = quaternion (A, B, C, D)
 -- Function File: W = quaternion (VV, THETA)
     Construct or extract a quaternion

          w = a*i + b*j + c*k + d

     from given data.

 -- Function File: qconj (Q)
     Conjugate of a quaternion.

          q = [w, x, y, z] = w*i + x*j + y*k + z
          qconj (q) = -w*i -x*j -y*k + z

 -- Function File: qderiv (omega)
     Derivative of a quaternion.

     Let Q be a quaternion to transform a vector from a fixed frame to a rotating frame.  If the rotating frame is rotating about the [x, y, z] axes at angular rates [wx, wy, wz], then the derivative of Q is given by

          Q' = qderivmat (omega) * Q

     If the passive convention is used (rotate the frame, not the vector), then

          Q' = -qderivmat (omega) * Q

 -- Function File: qderivmat (OMEGA)
     Derivative of a quaternion.

     Let Q be a quaternion to transform a vector from a fixed frame to a rotating frame.  If the rotating frame is rotating about the [x, y, z] axes at angular rates [wx, wy, wz], then the derivative of Q is given by

          Q' = qderivmat (omega) * Q

     If the passive convention is used (rotate the frame, not the vector), then

          Q' = -qderivmat (omega) * Q.

 -- Function File: qinv (Q)
     Return the inverse of a quaternion.

          q = [w, x, y, z] = w*i + x*j + y*k + z
          qmult (q, qinv (q)) = 1 = [0 0 0 1]

 -- Function File: qmult (A, B)
     Multiply two quaternions.

          [w, x, y, z] = w*i + x*j + y*k + z

     identities:

          i^2 = j^2 = k^2 = -1
          ij = k                 jk = i
          ki = j                 kj = -i
          ji = -k                ik = -j

 -- Function File: qtrans (V, Q)
     Transform the unit quaternion V by the unit quaternion Q. Returns V = Q*V/Q.

 -- Function File: qtransv (V, Q)
     Transform the 3-D vector V by the unit quaternion Q. Return a column vector.

          vi = (2*real(q)^2 - 1)*vb + 2*imag(q)*(imag(q)'*vb)
             + 2*real(q)*cross(imag(q),vb)

     Where imag(q) is a column vector of length 3.

 -- Function File: qtransvmat (QIB)
     Construct a 3x3 transformation matrix from quaternion QIB that is equivalent to rotation of th radians about axis VV, where [VV, TH] = quaternion (QIB).

 -- Function File: qcoordinate_plot (QF, QB, QV)
     Plot in the current figure a set of coordinate axes as viewed from the orientation specified by quaternion QV.  Inertial axes are also plotted:

     qf
          Quaternion from reference (x,y,z) to inertial.

     qb
          Quaternion from reference to body.

     qv
          Quaternion from reference to view angle.