Table of contents
CSPICE_XF2EUL converts a state transformation matrix to Euler angles and
their derivatives, given a specified set of axes.
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.
None.
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
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.
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.
None.
None.
ICY.REQ
PCK.REQ
ROTATION.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-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)
Euler angles and derivatives from state transformation
|