Find a unit quaternion corresponding to a specified rotation
   matrix.

   ROTATION

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

   r              is a rotation matrix.

   q              is a unit quaternion representing r.  q is a
                  4-dimensional vector.  If r rotates vectors by an
                  angle of R radians about a unit vector a, where
                  R is in [0, pi], then if h = R/2,

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

                  The restriction that R must be in the range [0, pi]
                  determines the output quaternion q uniquely
                  except when R = pi; in this special case, both of
                  the quaternions

                     q = ( 0,  a ,  a ,  a  )
                                1    2    3
                  and

                     q = ( 0, -a , -a , -a  )
                                1    2    3

                 are possible outputs, if a is a choice of rotation
                 axis for r.

   None.

   A unit quaternion is a 4-dimensional vector for which the sum of
   the squares of the components is 1.  Unit quaternions can be used
   to represent rotations in the following way:  Given a rotation
   angle R in [0, pi] and a unit vector a that acts as a rotation
   axis, we define the quaternion q by

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

   As mentioned in Detailed_Output, our restriction on the range of
   R determines q uniquely, except when R = pi.

   The CSPICE routine q2m_c is an 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 rotation matrix

                   +-              -+
                   |  0     1    0  |
                   |                |
             r  =  | -1     0    0  |
                   |                |
                   |  0     0    1  |
                   +-              -+

          also represented as

             [ pi/2 ]
                     3

          to a quaternion, we can use the code fragment

             rotate_c (  halfpi_c(),  3,  r  );
             m2q_c    (  r,               q  );

          m2q_c will return q as

             ( sqrt(2)/2, 0, 0, -sqrt(2)/2 ).

          Why?  Well, r is a coordinate transformation that
          rotates vectors by -pi/2 radians about the axis vector

             a  = ( 0, 0, 1 ),

          so our definition of q,

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

          implies that in this case,

             q =  ( cos(-pi/4),  0,  0,   sin(-pi/4) )

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


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

          Suppose our original rotation R is the product

             [ tau ]  [ pi/2 - delta ]  [ alpha ] .
                    3                 2          3

          The code fragment

             eul2m_c  ( tau,   halfpi_c() - delta,   alpha,
                        3,     2,                    3,      r );

             m2q_c    ( r, q );

          yields a quaternion q that represents r.

   None.

   1)   If r is not a rotation matrix, the error SPICE(NOTAROTATION)
        is signalled.

   None.

   N.J. Bachman   (JPL)

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

   -CSPICE Version 1.1.0, 21-OCT-1998 (NJB)

       Made input matrix const.

   -CSPICE Version 1.0.1, 13-FEB-1998 (EDW)

       Minor corrections to header.

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

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

   matrix to quaternion