Index of Functions: A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 
Index Page
cspice_xf2eul

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_XF2EUL converts a state transformation matrix to Euler angles and
   their derivatives, given a specified set of axes.

I/O


   Given:

      xform    a double precision, 6x6 state transformation matrix from some
               frame FRAME1 to another frame FRAME2.

               help, xform
                  DOUBLE = Array[6,6]

               Pictorially, `xform' has the structure shown here.

                  .-             -.
                  |       |       |
                  |   r   |   0   |
                  |       |       |
                  |-------+-------|
                  |       |       |
                  | dr/dt |   r   |
                  |       |       |
                  `-             -'

               where `r' is a rotation matrix that varies with respect to
               time and dr/dt is its time derivative.

               More specifically, if `s1' is the state of some object
               in FRAME1, then `s2', the state of the same object
               relative to FRAME2 is given by

                  s2 = xform * s1

               where "*" denotes the matrix vector product.

      axisa,
      axisb,
      axisc    the integer code identifying the axes of the Euler factorization
               for `r'.

               help, axisa
                  LONG = Scalar
               help, axisb
                  LONG = Scalar
               help, axisc
                  LONG = Scalar

               All must be in the range from 1 to 3. Moreover
               it must be the case that `axisa' and `axisb' are distinct
               and that `axisb' and `axisc' are distinct.

               Every rotation matrix can be represented as a product
               of three rotation matrices about the principal axes
               of a reference frame.

                  r =  [ alpha ]      [ beta ]      [ gamma ]
                                axisa         axisb          axisc

               The value 1 corresponds to the X axis.
               The value 2 corresponds to the Y axis.
               The value 3 corresponds to the Z axis.

   the call:

      cspice_xf2eul, xform, axisa, axisb, axisc, eulang, unique

   returns:

      eulang   a double precision 6-vector of Euler angles corresponding to the
               specified factorization.

               help, eulang
                  DOUBLE = Array[6]

               If we represent `r' as shown here:

                  r =  [ alpha ]      [ beta ]      [ gamma ]
                                axisa         axisb          axisc

               then

                  eulang[0] = alpha
                  eulang[1] = beta
                  eulang[2] = gamma
                  eulang[3] = d(alpha)/dt
                  eulang[4] = d(beta)/dt
                  eulang[5] = d(gamma)/dt

               The range of `alpha' and `gamma' is (-pi, pi].

               The range of `beta' depends on the exact set of
               axes used for the factorization. For
               factorizations in which the first and third axes
               are the same, the range of `beta' is [0, pi].

               For factorizations in which the first and third
               axes are different, the range of `beta' is
               [-pi/2, pi/2].

               For rotations such that `alpha' and `gamma' are not
               uniquely determined, `alpha' and d(alpha)/dt will
               always be set to zero; `gamma' and d(gamma)/dt are
               then uniquely determined.

      unique   a scalar boolean that indicates whether or not the values in
               `eulang' are uniquely determined.

               help, unique
                  BOOLEAN = Scalar

               If the values are unique then `unique' will be set to True. If
               the values are not unique and some components (eulang[0] and
               eulang[3]) have been set to zero, then `unique' will have the
               value False.

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) Determine the rate of change of the right ascension and
      declination of the pole of the moon, from the state
      transformation matrix that transforms J2000 states to object
      fixed states.

      Recall that the rotation component of the state transformation
      matrix is given by

         [w]  [cspice_halfpi-dec]  [ra+cspice_halfpi]
            3                    1                   3

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


         KPL/MK

         File name: xf2eul_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
            ---------                     --------
            pck00010.tpc                  Planet orientation and
                                          radii
            naif0012.tls                  Leapseconds


         \begindata

            KERNELS_TO_LOAD = ( 'pck00010.tpc',
                                'naif0012.tls'  )

         \begintext

         End of meta-kernel


      Example code begins here.


      PRO xf2eul_ex1

         ;;
         ;; Local parameters.
         ;;
         META   =   'xf2eul_ex1.tm'
         UTCSTR =   'May 15, 2007'

         ;;
         ;; 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
         ;; IAU_MOON.
         ;;
         cspice_sxform, 'J2000', 'IAU_MOON', et, ftmtrx

         ;;
         ;; Convert the transformation matrix to
         ;; Euler angles (3-1-3).
         ;;
         cspice_xf2eul, ftmtrx, 3L, 1L, 3L, eulang, unique

         ;;
         ;; Display the results.
         ;;
         if ( unique ) then begin

            print, format='(2A)', 'UTC: ', UTCSTR
            print, format='(A,F20.16)', 'W       = ', eulang[0]
            print, format='(A,F20.16)', 'DEC     = ',                        $
                                        cspice_halfpi() - eulang[1]
            print, format='(A,F20.16)', 'RA      = ',                        $
                                        eulang[2] - cspice_halfpi()
            print, format='(A,F20.16)', 'dW/dt   = ', eulang[3]
            print, format='(A,F20.16)', 'dDEC/dt = ', eulang[4]
            print, format='(A,F20.16)', 'dRA/dt  = ', eulang[5]

         endif else begin

            print, 'The values in EULANG are not uniquely determined.'

         endelse

      END


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


      UTC: May 15, 2007
      W       =  -2.6490877296701218
      DEC     =   1.1869108599473206
      RA      =  -1.5496443908099826
      dW/dt   =   0.0000026578085601
      dDEC/dt =   0.0000000004021737
      dRA/dt  =   0.0000000039334471


Particulars


   A word about notation: the symbol

      [ x ]
           i

   indicates a coordinate system rotation of x radians about the
   ith coordinate axis. To be specific, the symbol

      [ x ]
           1

   indicates a coordinate system rotation of x radians about the
   first, or x-, axis; the corresponding matrix is

      .-                    -.
      |  1    0        0     |
      |                      |
      |  0    cos(x)  sin(x) |
      |                      |
      |  0   -sin(x)  cos(x) |
      `-                    -'

   Remember, this is a COORDINATE SYSTEM rotation by x radians; this
   matrix, when applied to a vector, rotates the vector by -x
   radians, not x radians. Applying the matrix to a vector yields
   the vector's representation relative to the rotated coordinate
   system.

   The analogous rotation about the second, or y-, axis is
   represented by

      [ x ]
           2

   which symbolizes the matrix

      .-                    -.
      | cos(x)   0   -sin(x) |
      |                      |
      |  0       1    0      |
      |                      |
      | sin(x)   0    cos(x) |
      `-                    -'

   and the analogous rotation about the third, or z-, axis is
   represented by

      [ x ]
           3

   which symbolizes the matrix

      .-                    -.
      |  cos(x)  sin(x)   0  |
      |                      |
      | -sin(x)  cos(x)   0  |
      |                      |
      |  0        0       1  |
      `-                    -'

   The input matrix is assumed to be the product of three
   rotation matrices, each one of the form

      .-                    -.
      |  1      0       0    |
      |                      |
      |  0    cos(r)  sin(r) |     (rotation of r radians about the
      |                      |      x-axis),
      |  0   -sin(r)  cos(r) |
      `-                    -'


      .-                    -.
      | cos(s)   0   -sin(s) |
      |                      |
      |  0       1      0    |     (rotation of s radians about the
      |                      |      y-axis),
      | sin(s)   0    cos(s) |
      `-                    -'

   or

      .-                    -.
      |  cos(t)  sin(t)   0  |
      |                      |
      | -sin(t)  cos(t)   0  |     (rotation of t radians about the
      |                      |      z-axis),
      |  0        0       1  |
      `-                    -'

   where the second rotation axis is not equal to the first or
   third. Any rotation matrix can be factored as a sequence of
   three such rotations, provided that this last criterion is met.

   This routine is related to the routine cspice_eul2xf which produces
   a state transformation from an input set of axes, Euler angles
   and derivatives.

   The two procedure calls shown here will not change
   `xform' except for round off errors.

      cspice_xf2eul, xform,  axisa, axisb, axisc, eulang, unique
      cspice_eul2xf, eulang, axisa, axisb, axisc, xform'

   On the other hand the two calls

      cspice_eul2xf, eulang, axisa, axisb, axisc, xform
      cspice_xf2eul, xform,  axisa, axisb, axisc, eulang, unique

   will leave `eulang' unchanged only if the components of `eulang'
   are in the range produced by cspice_xf2eul and the Euler representation
   of the rotation component of `xform' is unique within that range.

Exceptions


   1)  If any of `axisa', `axisb', or `axisc' do not have values in

          { 1, 2, 3 }

       an error is signaled by a routine in the call tree of this
       routine.

   2)  If `axisb' is equal to `axisc' or `axisa', an error is signaled by a
       routine in the call tree of this routine. An arbitrary
       rotation matrix cannot be expressed using a sequence of Euler
       angles unless the second rotation axis differs from the other
       two.

   3)  If the input matrix `xform' is not a rotation matrix, an error
       is signaled by a routine in the call tree of this routine.

   4)  If eulang[0] and eulang[2] are not uniquely determined,
       eulang[0] is set to zero, and eulang[2] is determined.

   5)  If any of the input arguments, `xform', `axisa', `axisb' or
       `axisc', is undefined, an error is signaled by the IDL error
       handling system.

   6)  If any of the input arguments, `xform', `axisa', `axisb' or
       `axisc', is not of the expected type, or it does not have the
       expected dimensions and size, an error is signaled by the Icy
       interface.

   7)  If any of the output arguments, `eulang' or `unique', is not a
       named variable, an error is signaled by the Icy interface.

Files


   None.

Restrictions


   None.

Required_Reading


   ICY.REQ
   PCK.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, 01-NOV-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. Added pck.req to Required readings.

       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, 09-DEC-2005 (EDW)

       Added -Examples section.

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

Index_Entries


   Euler angles and derivatives from state transformation



Fri Dec 31 18:43:09 2021