Abstract

   CSPICE_XF2RAV determines the rotation matrix and angular velocity of the
   rotation from a state transformation matrix.

I/O

   Given:

      xform    a state transformation matrix from one frame FRAME1 to some
               other frame FRAME2.

               help, xform
                  DOUBLE = Array[6,6]

   the call:

      cspice_xf2rav, xform, rot, av

   returns:

      rot      the 3x3 double precision rotation matrix between the frames.

               help, rot
                  DOUBLE = Array[3,3]

      av       the double precision angular velocity 3-vector of the
               transformation.

               help, av
                  DOUBLE = Array[3]

               In other words, if `p' is the position of a fixed point in
               FRAME2, then from the point of view of FRAME1, `p' rotates (in a
               right handed sense) about an axis parallel to `av'. Moreover the
               rate of rotation in radians per unit time is given by the length
               of `av'.

               More formally, the velocity `v' of `p' in FRAME1 is
               given by
                                  T
                   v  = av x ( rot  * p )

               The components of `av' are given relative to FRAME1.

Parameters

   None.

Examples

   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

   1) Suppose that you wanted to determine the angular velocity
      of the Earth body-fixed reference frame with respect to
      J2000 at a particular epoch ET. The following code example
      illustrates a procedure for computing the angular velocity.

      Use the meta-kernel shown below to load the required SPICE
      kernels.


         KPL/MK

         File name: xf2rav_ex1.tm

         This meta-kernel is intended to support operation of SPICE
         example programs. The kernels shown here should not be
         assumed to contain adequate or correct versions of data
         required by SPICE-based user applications.

         In order for an application to use this meta-kernel, the
         kernels referenced here must be present in the user's
         current working directory.

         The names and contents of the kernels referenced
         by this meta-kernel are as follows:

            File name                     Contents
            ---------                     --------
            earth_720101_070426.bpc       Earth historical
                                          binary PCK
            naif0012.tls                  Leapseconds

         \begindata

            KERNELS_TO_LOAD = ( 'earth_720101_070426.bpc',
                                'naif0012.tls'            )

         \begintext

         End of meta-kernel


      Example code begins here.


      PRO xf2rav_ex1

         ;;
         ;; Local parameters.
         ;;
         META   =   'xf2rav_ex1.tm'
         UTCSTR =   '2005-OCT-10 16:00:00'

         ;;
         ;; Load SPICE kernels.
         ;;
         cspice_furnsh, META

         ;;
         ;; Convert the input time to seconds past J2000 TDB.
         ;;
         cspice_str2et, UTCSTR, et

         ;;
         ;; Get the transformation matrix from J2000 frame to
         ;; ITRF93.
         ;;
         cspice_sxform, 'J2000', 'ITRF93', et, ftmtrx

         ;;
         ;; Now get the angular velocity by calling cspice_xf2rav
         ;;
         cspice_xf2rav, ftmtrx, rot, av

         ;;
         ;; Display the results.
         ;;
         print, format='(A)', 'Rotation matrix:'
         print, format='(3F16.11)', rot

         print
         print, format='(A)', 'Angular velocity:'
         print, format='(3F16.11)', av

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      Rotation matrix:
        -0.18603277688  -0.98254352801   0.00014659080
         0.98254338275  -0.18603282936  -0.00053610915
         0.00055402128   0.00004429795   0.99999984555

      Angular velocity:
         0.00000004025   0.00000000324   0.00007292114

Particulars

   This routine is essentially a macro routine for converting
   state transformation matrices into the equivalent representation
   in terms of a rotation and angular velocity.

   This routine is an inverse of the routine cspice_rav2xf.

Exceptions

   1)  No checks are performed on `xform' to ensure that it is indeed
       a state transformation matrix.

   2)  If the input argument `xform' is undefined, an error is
       signaled by the IDL error handling system.

   3)  If the input argument `xform' is not of the expected type, or
       it does not have the expected dimensions and size, an error is
       signaled by the Icy interface.

   4)  If any of the output arguments, `rot' or `av', is not a named
       variable, an error is signaled by the Icy interface.

Files

   None.

Restrictions

   None.

Required_Reading

   ICY.REQ
   ROTATION.REQ

Literature_References

   None.

Author_and_Institution

   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version

   -Icy Version 1.0.2, 10-AUG-2021 (JDR)

       Edited the header to comply with NAIF standard. Added complete
       code examples.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections, and
       extended -Particulars section.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

       Added arguments' type and size information in the -I/O section.

   -Icy Version 1.0.1, 12-APR-2007 (EDW)

       Edit to abstract.

   -Icy Version 1.0.0, 16-JUN-2003 (EDW)

Index_Entries

   State transformation to rotation and angular velocity