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 xf2eul_c
Table of contents
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
       xf2eul_c ( State transformation to Euler angles )

       void xf2eul_c ( ConstSpiceDouble     xform  [6][6],
                       SpiceInt             axisa,
                       SpiceInt             axisb,
                       SpiceInt             axisc,
                       SpiceDouble          eulang [6],
                       SpiceBoolean       * unique         )
#### Abstract
       Convert a state transformation matrix to Euler angles and their
       derivatives, given a specified set of axes.
#### Required_Reading
       PCK
       ROTATION
#### Keywords
       ANGLES
       DERIVATIVES
       STATE
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
       xform      I   A state transformation matrix.
       axisa      I   Axis A of the Euler angle factorization.
       axisb      I   Axis B of the Euler angle factorization.
       axisc      I   Axis C of the Euler angle factorization.
       eulang     O   An array of Euler angles and their derivatives.
       unique     O   Indicates if `eulang' is a unique representation.
#### Detailed_Input
       xform       is a state transformation matrix from some frame FRAME1
                   to another frame FRAME2. 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       are 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.

                   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.
#### Detailed_Output
       eulang      is the set of Euler angles corresponding to the
                   specified factorization.

                   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] = dalpha/dt
                      eulang[4] = dbeta/dt
                      eulang[5] = dgamma/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      is a logical that indicates whether or not the
                   values in `eulang' are uniquely determined. If
                   the values are unique then `unique' will be set to
                   SPICETRUE. 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 SPICEFALSE.
#### Parameters
       None.
#### 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.
#### Files
       None.
#### 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 eul2xf_c which produces
       a state transformation from an input set of axes, Euler angles
       and derivatives.

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

          xf2eul_c ( xform,  axisa, axisb, axisc, eulang, &unique );
          eul2xf_c ( eulang, axisa, axisb, axisc, xform           );

       On the other hand the two calls

          eul2xf_c ( eulang, axisa, axisb, axisc, xform           );
          xf2eul_c ( xform,  axisa, axisb, axisc, eulang, &unique );

       will leave `eulang' unchanged only if the components of `eulang'
       are in the range produced by xf2eul_c and the Euler representation
       of the rotation component of `xform' is unique within that range.
#### Examples
       The numerical results shown for this example may differ across
       platforms. The results depend on the SPICE kernels used as
       input, the compiler and supporting libraries, 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]  [halfpi_c-dec]  [ra+halfpi_c]
                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.

          /.
             Program xf2eul_ex1
          ./
          #include <stdio.h>
          #include "SpiceUsr.h"

          int main( )
          {

             /.
             Local parameters.
             ./
             #define META         "xf2eul_ex1.tm"
             #define UTCSTR       "May 15, 2007"

             /.
             Local variables.
             ./
             SpiceDouble          eulang [6];
             SpiceDouble          et;
             SpiceDouble          ftmtrx [6][6];

             SpiceBoolean         unique;

             /.
             Load SPICE kernels.
             ./
             furnsh_c ( META );

             /.
             Convert the input time to seconds past J2000 TDB.
             ./
             str2et_c ( UTCSTR, &et );

             /.
             Get the transformation matrix from J2000 frame to
             IAU_MOON.
             ./
             sxform_c ( "J2000", "IAU_MOON", et, ftmtrx );

             /.
             Convert the transformation matrix to
             Euler angles (3-1-3).
             ./
             xf2eul_c ( ftmtrx, 3, 1, 3, eulang, &unique );

             /.
             Display the results.
             ./
             if ( unique )
             {
                printf( "UTC: %s\n", UTCSTR );
                printf( "W       =  %19.16f\n", eulang[0] );
                printf( "DEC     =  %19.16f\n", halfpi_c() - eulang[1] );
                printf( "RA      =  %19.16f\n", eulang[2] - halfpi_c() );
                printf( "dW/dt   =  %19.16f\n", eulang[3] );
                printf( "dDEC/dt =  %19.16f\n", eulang[4] );
                printf( "dRA/dt  =  %19.16f\n", eulang[5] );
             }
             else
             {
                printf( "The values in EULANG are not uniquely determined.\n" );
             }

             return ( 0 );
          }

          When this program was executed on a Mac/Intel/cc/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
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman        (JPL)
       J. Diaz del Rio     (ODC Space)
       W.L. Taber          (JPL)
#### Version
       -CSPICE Version 1.0.2, 01-NOV-2021 (JDR)

           Edited the header to comply with NAIF standard. Added complete
           code example based on existing example.

       -CSPICE Version 1.0.1, 05-MAR-2008 (NJB)

           Fixed typo (missing double quote character) in code example.
           Corrected order of header sections.

       -CSPICE Version 1.0.0, 15-JUN-1999 (WLT) (NJB)
#### Index_Entries
       Euler angles and derivatives from state transformation
#### Link to routine xf2eul_c source file xf2eul_c.c

    Fri Dec 31 18:41:15 2021