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

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


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

   The companion routine cspice_eul2xf converts Euler angles
   and their derivatives with respect to a specified set of axes
   to a state transformation matrix.

I/O


   Given:

      xform   operator(s) that transform state vector(s) from some frame
              "frame1" to another frame "frame2."

              [6,6]   = size(xform); double = class(xform)
              
              or     

              [6,6,n] = size(xform); double = class(xform)

      axisa
      axisb
      axisc   the axes desired for the factorization of "r". 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.

              [1,1] = size(axisa); int32 = class(axisa)
              [1,1] = size(axisb); int32 = class(axisb)
              [1,1] = size(axisc); int32 = class(axisc)

              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:

      [eulang, unique] = cspice_xf2eul(xform,  axisa, axisb, axisc)

   returns:

       eulang   the vector/matrix of Euler angles corresponding to the
                specified factorization.

                If    [6,6]   = size(xform)
                then  [6,6]   = size(eulang); double = class(eulang)

                If    [6,6,n] = size(xform)
                then  [6,6,n] = size(eulang); double = class(eulang)

                If we represent r as shown here:

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

                then (6x1)

                   eulang[1] = alpha
                   eulang[2] = beta
                   eulang[3] = gamma
                   eulang[4] = dalpha/dt
                   eulang[5] = dbeta/dt
                   eulang[6] = dgamma/dt

                or (6xN)

                   eulang[:,N] = alpha_N
                   eulang[:,N] = beta_N
                   eulang[:,N] = gamma_N
                   eulang[:,N] = dalpha_N/dt
                   eulang[:,N] = dbeta_N/dt
                   eulang[:,N] = dgamma_N/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 dalpha/dt will
                always be set to zero; gamma and dgamma/dt are
                then uniquely determined.

       unique   flag(s) indicating whether the values in 'eulang' are
                uniquely determined.

                [1,n] = size(found); logical = class(found)

                If he values are unique then 'unique' will be set to
                true. If the values are not unique and some
                components ( eulang[1] and eulang[4] ) have value
                zero, then 'unique' will have the value false.

                'eulang' and 'unique' return with the same vectorization
                measure, N, as 'xform'.

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.

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

         KPL/MK

         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
            ---------                     --------
            de421.bsp                     Planetary ephemeris
            pck00009.tpc                  Planet orientation and
                                          radii
            naif0009.tls                  Leapseconds


         \begindata

            KERNELS_TO_LOAD = ( '/kernels/gen/lsk/naif0009.tls'
                                '/kernels/gen/spk/de421.bsp'
                                '/kernels/gen/pck/pck00009.tpc'
                      )

         \begintext


      %
      % Load the SPK, PCK and LSK kernels.
      %
      cspice_furnsh( 'standard.tm' )

      %
      % Suppose that you wish to 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.
      %
      % Using this routine with the routine cspice_sxform_c you can determine
      % these instantaneous rates.
      %
      % Recall that the rotation component of 'tsipm' is given by
      %
      %  [w]  [halfpi_c-dec] [ra+halfpi_c]
      %     3               1             3
      %
      % Define the number of ephemeris times to perform the calculation.
      %
      N = 100;

      %
      % Calculate the separation of each ephemeris time, in seconds,
      % over an eighteen year span.
      %
      STEP = 18 * 365 * cspice_spd/N;

      %
      % Base the ephemeris time set at May 15, 2007.
      %
      et = [0:N]*STEP +  cspice_str2et( 'May 15, 2007' );

      %
      % Calculate the state transformation matrices corresponding
      % to 'et', then convert those matrices to Euler angles (3-1-3).
      %
      tsipm              = cspice_sxform( 'J2000', 'IAU_MOON', et );
      [ eulang, unique ] = cspice_xf2eul( tsipm , 3, 1, 3 );

      %
      % From the Euler angles, calculate right ascension and declination.
      % Form the UTC time string from 'et' (for output purposes).
      %
      ra  = eulang(3,:) - cspice_halfpi;
      dec = cspice_halfpi - eulang(2,:);
      utc = cspice_et2utc( et, 'c', 3 );

      %
      % As a convenience, output in a loop.
      %
      for m=1:N+1

         if( unique(m) )
            fprintf( 'UTC: %s\n', utc(m,:)                 )
            fprintf( 'w        = %12.6f\n'  , eulang(1,m)  )
            fprintf( 'dec      = %12.6f\n'  , dec(m)       )
            fprintf( 'ra       = %12.6f\n'  , ra(m)        )
            fprintf( 'd w/dt   = %14.9f\n'  , eulang(4,m)  )
            fprintf( 'd dec/dt = %14.9f\n'  ,-eulang(5,m)  )
            fprintf( 'd ra/dt  = %14.9f\n\n', eulang(6,m)  )
         else
            disp( 'The values in ''eulang'' not uniquely determined.' )
         end

      end

      %
      % It's always good form to unload kernels after use,
      % particularly in MATLAB due to data persistence.
      %
      cspice_kclear

      %
      % It is left as an exercise to the user to graphically display
      % a plot of ra vs dec.
      %
      % plot(ra,dec)
      %

   MATLAB outputs:

      The final five output sets, radians.

               ...

      UTC: 2024 AUG 20 04:48:00.002
      w        =     2.719238
      dec      =     1.188057
      ra       =    -1.581646
      d w/dt   =    0.000002658
      d dec/dt =   -0.000000001
      d ra/dt  =    0.000000004

      UTC: 2024 OCT 24 21:36:00.003
      w        =    -1.026611
      dec      =     1.188773
      ra       =    -1.576003
      d w/dt   =    0.000002662
      d dec/dt =    0.000000001
      d ra/dt  =   -0.000000000

      UTC: 2024 DEC 29 14:24:00.001
      w        =     1.514167
      dec      =     1.188984
      ra       =    -1.573372
      d w/dt   =    0.000002663
      d dec/dt =   -0.000000001
      d ra/dt  =   -0.000000001

      UTC: 2025 MAR 05 07:12:00.000
      w        =    -2.231256
      dec      =     1.188290
      ra       =    -1.567771
      d w/dt   =    0.000002658
      d dec/dt =    0.000000000
      d ra/dt  =    0.000000004

      UTC: 2025 MAY 10 00:00:00.000
      w        =     0.307001
      dec      =     1.188934
      ra       =    -1.562882
      d w/dt   =    0.000002663
      d dec/dt =    0.000000001
      d ra/dt  =   -0.000000001

Particulars


   This function is intended to provide an inverse for the function
   cspice_eul2xf.

Required Reading


   For important details concerning this module's function, please refer to
   the CSPICE routine xf2eul_c.

   MICE.REQ

Version


   -Mice Version 1.2.1, 19-SEP-2016, EDW (JPL)

      Corrected usage string typo, 'xform' should show dimension as (6,6).

      Edited I/O section to conform to NAIF standard for Mice documentation.

   -Mice Version 1.2.0, 10-MAY-2011, EDW (JPL)

      "logical" call replaced with "zzmice_logical."

   -Mice Version 1.0.1, 06-MAY-2009, EDW (JPL)

      Added MICE.REQ reference to the Required Reading section.

   -Mice Version 1.0.0, 02-APR-2007, EDW (JPL)

Index_Entries


   Euler angles and derivatives from state transformation


Wed Apr  5 18:00:36 2017