axisar_c

Index Page axisar_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       void axisar_c ( ConstSpiceDouble  axis   [3],
                       SpiceDouble       angle,
                       SpiceDouble       r      [3][3]  )
#### Abstract
       Construct a rotation matrix that rotates vectors by a specified
       angle about a specified axis.
#### Required_Reading
       ROTATION
#### Keywords
       MATRIX
       ROTATION
#### Brief_I/O
       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       axis       I   Rotation axis.
       angle      I   Rotation angle, in radians.
       r          O   Rotation matrix corresponding to axis and angle.
#### Detailed_Input
       axis,
       angle          are, respectively, a rotation axis and a rotation
                      angle.  axis and angle determine a coordinate
                      transformation whose effect on any vector v is to
                      rotate v by angle radians about the vector axis.
#### Detailed_Output
       r              is a rotation matrix representing the coordinate
                      transformation determined by axis and angle:  for
                      each vector v, r*v is the vector resulting from
                      rotating v by angle radians about axis.
#### Parameters
       None.
#### Exceptions
       Error free.

       1)  If axis is the zero vector, the rotation generated is the
           identity.  This is consistent with the specification of vrotv.
#### Files
       None.
#### Particulars
       axisar_c can be thought of as a partial inverse of raxisa_c.
       axisar_c is really is a `left inverse':  the code fragment

          raxisa_c ( r,    axis,  &angle );
          axisar_c ( axis, angle, r      );

       preserves r, except for round-off error, as long as r is a
       rotation matrix.

       On the other hand, the code fragment

          axisar_c ( axis, angle, r      );
          raxisa_c ( r,    axis,  &angle );

       preserves axis and angle, except for round-off error, only if
       angle is in the range (0, pi).  So axisar_c is a right inverse
       of raxisa_c only over a limited domain.
#### Examples
       1)  A matrix that rotates vectors by pi/2 radians about the z-axis
           can be found using the code fragment

              axis[0] = 0.
              axis[1] = 0.
              axis[2] = 1.

              axisar_c ( axis, halfpi_c(), r );

           The returned matrix r will equal

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

       2)  Linear interpolation between two rotation matrices:

              Let r(t) be a time-varying rotation matrix; r could be
              a C-matrix describing the orientation of a spacecraft
              structure.  Given two points in time t1 and t2 at which
              r(t) is known, and given a third time t3, where

                 t1  <  t3  <  t2,

              we can estimate r(t3) by linear interpolation.  In other
              words, we approximate the motion of r by pretending that
              r rotates about a fixed axis at a uniform angular rate
              during the time interval [t1, t2].  More specifically, we
              assume that each column vector of r rotates in this
              fashion.  This procedure will not work if r rotates through
              an angle of pi radians or more during the time interval
              [t1, t2]; an aliasing effect would occur in that case.

              If we let

                 r1 = r(t1)
                 r2 = r(t2), and

                             -1
                 q  = r2 * r1  ,

              then the rotation axis and angle of q define the rotation
              that each column of r(t) undergoes from time t1 to time
              t2.  Since r(t) is orthogonal, we can find q using the
              transpose of r1.  We find the rotation axis and angle via
              raxisa_c.

                 mxmt_c   ( r2,   r1,    q      );
                 raxisa_c ( q,    axis,  &angle );

              Find the fraction of the total rotation angle that r
              rotates through in the time interval [t1, t3].

                 frac = ( t3 - t1 )  /  ( t2 - t1 )

              Finally, find the rotation delta that r(t) undergoes
              during the time interval [t1, t3], and apply that rotation
              to r1, yielding r(t3), which we'll call r3.

                 axisar_c ( axis,   frac * angle,  delta  );
                 mxm_c    ( delta,  r1,            r3     );
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman   (JPL)
#### Version
       -CSPICE Version 1.0.0, 18-JUN-1999 (NJB)
#### Index_Entries
       axis and angle to rotation
#### Link to routine axisar_c source file axisar_c.c

    Thu Apr 16 08:57:21 2009