eul2m

 Procedure Abstract Required_Reading Keywords Declarations Brief_I/O Detailed_Input Detailed_Output Parameters Exceptions Files Particulars Examples Restrictions Literature_References Author_and_Institution Version

#### Procedure

```      EUL2M ( Euler angles to matrix )

SUBROUTINE EUL2M (  ANGLE3,   ANGLE2,   ANGLE1,
.                    AXIS3,    AXIS2,    AXIS1,   R  )

```

#### Abstract

```     Construct a rotation matrix from a set of Euler angles.
```

```     ROTATION
```

#### Keywords

```     MATRIX
ROTATION
TRANSFORMATION
```

#### Declarations

```
DOUBLE PRECISION      ANGLE3
DOUBLE PRECISION      ANGLE2
DOUBLE PRECISION      ANGLE1

INTEGER               AXIS3
INTEGER               AXIS2
INTEGER               AXIS1

DOUBLE PRECISION      R ( 3, 3 )

```

#### Brief_I/O

```     Variable  I/O  Description
--------  ---  --------------------------------------------------
ANGLE3,
ANGLE2,
ANGLE1     I   Rotation angles about third, second, and first
AXIS3,
AXIS2,
AXIS1      I   Axis numbers of third, second, and first rotation
axes.

R          O   Product of the 3 rotations.
```

#### Detailed_Input

```     ANGLE3,
ANGLE2,
ANGLE1,

AXIS3,
AXIS2,
AXIS1          are, respectively, a set of three angles and three
coordinate axis numbers; each pair ANGLEx and
AXISx specifies a coordinate transformation
the coordinate axis indexed by AXISx.  These
coordinate transformations are typically
symbolized by

[ ANGLEx ]     .
AXISx

See the \$ Particulars section below for details
concerning this notation.

Note that these coordinate transformations rotate
vectors by

-ANGLEx

The values of AXISx may be 1, 2, or 3, indicating
the x, y, and z axes respectively.
```

#### Detailed_Output

```     R              is a rotation matrix representing the composition
of the rotations defined by the input angle-axis
pairs.  Together, the three pairs specify a
composite transformation that is the result of
performing the rotations about the axes indexed
by AXIS1, AXIS2, and AXIS3, in that order.  So,

R = [ ANGLE3 ]    [ ANGLE2 ]      [ ANGLE1 ]
AXIS3          AXIS2          AXIS1

See the \$ Particulars section below for details
concerning this notation.

The resulting matrix R may be thought of as a
coordinate transformation; applying it to a vector
yields the vector's coordinates in the rotated
system.

Viewing R as a coordinate transformation matrix,
the basis that R transforms vectors to is created
by rotating the original coordinate axes first by
coordinate axis indexed by AXIS2, and finally by
AXIS3.  At the second and third steps of this
process, the coordinate axes about which rotations
are performed belong to the bases resulting from
the previous rotations.
```

#### Parameters

```     None.
```

#### Exceptions

```     1)   If any of AXIS3, AXIS2, or AXIS1 do not have values in

{ 1, 2, 3 },

```

#### Files

```     None.
```

#### Particulars

```     A word about notation:  the symbol

[ x ]
i

To be specific, the symbol

[ x ]
1

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
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  |
+-                    -+

From time to time, (depending on one's line of work, perhaps) one
may happen upon a pair of coordinate systems related by a
sequence of rotations.  For example, the coordinate system
defined by an instrument such as a camera is sometime specified
by RA, DEC, and twist; if alpha, delta, and phi are the rotation
angles, then the series of rotations

[ phi ]     [ pi/2  -  delta ]     [ alpha ]
3                      2             3

produces a transformation from inertial to camera coordinates.

This routine is related to the SPICELIB routine M2EUL, which
produces a sequence of Euler angles, given a rotation matrix.
This routine is a `left inverse' of M2EUL:  the sequence of
calls

CALL M2EUL ( R,  AXIS3,   AXIS2,   AXIS1,
.                 ANGLE3,  ANGLE2,  ANGLE1     )

CALL EUL2M (     ANGLE3,  ANGLE2,  ANGLE1,
.                 AXIS3,   AXIS2,   AXIS1,   R )

preserves R, except for round-off error.

On the other hand, the sequence of calls

CALL EUL2M (     ANGLE3,  ANGLE2,  ANGLE1,
.                 AXIS3,   AXIS2,   AXIS1,   R )

CALL M2EUL ( R,  AXIS3,   AXIS2,   AXIS1,
.                 ANGLE3,  ANGLE2,  ANGLE1     )

preserve ANGLE3, ANGLE2, and ANGLE1 only if these angles start
out in the ranges that M2EUL's outputs are restricted to.
```

#### Examples

```     1)  Create a coordinate transformation matrix by rotating
the original coordinate axes first by 30 degrees about
the z axis, next by 60 degrees about the y axis resulting
from the first rotation, and finally by -50 degrees about
the z axis resulting from the first two rotations.

C
C     Create the coordinate transformation matrix
C
C                   o          o          o
C        R  =  [ -50  ]   [  60  ]   [  30  ]
C                      3          2          3
C
C     function RPD (radians per degree) gives the
C     conversion factor.
C
C     The z axis is `axis 3'; the y axis is `axis 2'.
C
ANGLE1 = RPD() *  30.D0
ANGLE2 = RPD() *  60.D0
ANGLE3 = RPD() * -50.D0

AXIS1  = 3
AXIS2  = 2
AXIS3  = 3

CALL EUL2M (  ANGLE3, ANGLE2, ANGLE1,
.              AXIS3,  AXIS2,  AXIS1,   R  )

2)  A trivial example using actual numbers.

The code fragment

CALL EUL2M (  0.D0,     0.D0,     HALFPI(),
.                 1,        1,            3,      R  )

sets R equal to the matrix

+-                  -+
|  0      1       0  |
|                    |
| -1      0       0  |.
|                    |
|  0      0       1  |
+-                  -+

3)  Finding the rotation matrix specified by a set of `clock,
cone, and twist' angles, as defined on the Voyager 2 project:

Voyager 2 narrow angle camera pointing, relative to the
Sun-Canopus coordinate system, was frequently specified
by a set of Euler angles called `clock, cone, and twist'.
These defined a 3-2-3 coordinate transformation matrix
TSCTV as the product

[ twist ]  [ cone ]   [ clock ] .
3         2           3

Given the angles CLOCK, CONE, and TWIST (in units of
radians), we can compute TSCTV with the code fragment

CALL EUL2M (  TWIST,  CONE,  CLOCK,
.              3,      2,     3,      TSCTV  )

4)  Finding the rotation matrix specified by a set of `right
ascension, declination, and twist' angles, as defined on the
Galileo project:

Galileo scan platform pointing, relative to an inertial
reference frame, (EME50 variety) is frequently specified
by a set of Euler angles called `right ascension (RA),
declination (Dec), and twist'. These define a 3-2-3
coordinate transformation matrix TISP as the product

[ Twist ]  [ pi/2 - Dec ]   [ RA ] .
3               2        3

Given the angles RA, DEC, and TWIST (in units of radians),
we can compute TISP with the code fragment

CALL EUL2M (  TWIST,   HALFPI()-DEC,   RA,
.              3,       2,              3,   TISP  )
```

#### Restrictions

```     Beware:  more than one definition of "RA, DEC and twist" exists.
```

#### Literature_References

```       `Galileo Attitude and Camera Models', JPL IOM 314-323,
W. M. Owen, Jr.,  Nov. 11, 1983.  NAIF document number
204.0.
```

#### Author_and_Institution

```     N.J. Bachman   (JPL)
```

#### Version

```    SPICELIB Version 1.2.1, 26-DEC-2006 (NJB)

SPICELIB Version 1.2.0, 25-AUG-2005 (NJB)

Updated to remove non-standard use of duplicate arguments
in ROTMAT calls.

SPICELIB Version 1.1.2, 14-OCT-2004 (LSE)

Corrected a typo in the header.

SPICELIB Version 1.1.1, 10-MAR-1992 (WLT)

Comment section for permuted index source lines was added
`Wed Apr  5 17:46:36 2017`