Find the rotation matrix corresponding to a specified unit 
   quaternion. 

   ROTATION 

   Variable  I/O  Description 
   --------  ---  -------------------------------------------------- 
   q          I   A unit quaternion. 
   r          O   A rotation matrix corresponding to q. 

   q              is a unit quaternion representing a rotation.  q 
                  is a 4-dimensional vector.  q has the property that 

                     || q ||  =  1. 

   r              is a 3 by 3 rotation matrix representing the same 
                  rotation as does q.  If q represents a rotation by 
                  R radians about some axis vector a, then for any 
                  vector v, r*v yields v, rotated by R radians 
                  about a. 

   None. 

   If a 4-dimensional vector q satisfies the equality 

      || q ||   =  1 

   or equivalently 

          2          2          2          2 
      q(0)   +   q(1)   +   q(2)   +   q(3)   =  1, 

   then we can always find a unit vector q and a scalar R such that 

      q = ( cos(R/2), sin(R/2)a(1), sin(R/2)a(2), sin(R/2)a(3) ). 

   We can interpret a and R as the axis and rotation angle of a 
   rotation in 3-space.  If we restrict R to the range [0, pi], 
   then R and a are uniquely determined, except if R = pi.  In this 
   special case, a and -a are both valid rotation axes. 

   Every rotation is represented by a unique orthogonal matrix; this 
   routine returns that unique rotation matrix corresponding to q. 

   The CSPICE routine m2q_c is a one-sided inverse of this routine: 
   given any rotation matrix r, the calls 

      m2q_c ( r, q ) 
      q2m_c ( q, r ) 

   leave r unchanged, except for round-off error.  However, the 
   calls 

      q2m_c ( q, r ) 
      m2q_c ( r, q ) 

   might preserve q or convert q to -q. 

   1)  A case amenable to checking by hand calculation: 

          To convert the quaternion 

             q = ( sqrt(2)/2, 0, 0, -sqrt(2)/2 ) 

          to a rotation matrix, we can use the code fragment 

             q[0] =  sqrt(2.)/2.; 
             q[1] =  0.;
             q[2] =  0.; 
             q[3] = -sqrt(2.)/2.; 

             q2m_c ( q, r ); 

          The matrix r will be set equal to 

             +-              -+ 
             |  0     1    0  | 
             |                | 
             | -1     0    0  |. 
             |                | 
             |  0     0    1  | 
             +-              -+ 

          Why?  Well, q represents a rotation by some angle R about 
          some axis vector q, where R and a satisfy 

             q = ( cos(R/2), sin(R/2)a(1), sin(R/2)a(2), sin(R/2)a(3) ). 

          In this example, 

             q = ( sqrt(2)/2, 0, 0, -sqrt(2)/2 ), 

          so 

             cos(R/2) = sqrt(2)/2. 

          Assuming that R is in the interval [0, pi], we must have 

             R = pi/2, 

          so 

             sin(R/2) = sqrt(2)/2. 

          Since the second through fourth components of q represent 

             sin(r/2) * a, 

          it follows that 

             a = ( 0, 0, -1 ). 

          So q represents a transformation that rotates vectors by 
          pi/2 about the negative z-axis.  This is equivalent to a 
          coordinate system rotation of pi/2 about the positive 
          z-axis; and we recognize R as the matrix 

             [ pi/2 ] . 
                     3 


   2)  Finding a set of Euler angles that represent a rotation 
       specified by a quaternion: 

          Suppose our rotation r is represented by the quaternion 
          q.  To find angles tau, alpha, delta such that 


             r  =  [ tau ]  [ pi/2 - delta ]  [ alpha ] , 
                          3                 2          3 

          we can use the code fragment 


             q2m_c   ( q, r );
             m2eul_c ( r, 3, 2, 3, tau, delta, alpha );

             delta = halfpi_c() - delta; 

   None. 

   Error free. 

   1)  If q is not a unit quaternion, the output matrix r is 
       unlikely to be a rotation matrix. 

   None. 

   N.J. Bachman   (JPL) 

   [1]    NAIF document 179.0, "Rotations and their Habits", by 
          W. L. Taber. 

   -CSPICE Version 1.3.1, 06-FEB-2003 (EDW)

       Corrected typo error in Examples section.

   -CSPICE Version 1.3.0, 24-JUL-2001   (NJB)

       Changed protoype:  input q is now type (ConstSpiceDouble [4]).
       Implemented interface macro for casting input q to const.

   -CSPICE Version 1.2.0, 08-FEB-1998 (NJB)

      Removed local variables used for temporary capture of outputs.
      Removed tracing calls, since the underlying Fortran routine
      is error-free.

   -CSPICE Version 1.0.0, 25-OCT-1997 (NJB)

      Based on SPICELIB Version 1.0.1, 10-MAR-1992 (WLT)

   quaternion to matrix