cspice_xf2eul

 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 = alpha
eulang = beta
eulang = gamma
eulang = dalpha/dt
eulang = dbeta/dt
eulang = 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 and eulang ) 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`