Abstract

   CSPICE_ROTATE calculates the 3x3 rotation matrix generated
   by a rotation of a specified angle about a specified axis.
   This rotation operates as a rotation of the coordinate
   system.

I/O

   Given:

      angle    the angle, given in radians, through which the rotation is
               performed.

               help, angle
                  DOUBLE = Scalar

      iaxis    the index of the axis of rotation.

               help, iaxis
                  LONG = Scalar

               The X, Y, and Z axes have indices 1, 2 and 3 respectively.

   the call:

      cspice_rotate, angle, iaxis, mout

   returns:

      mout     the rotation matrix which describes the rotation of a reference
               frame through `angle' radians about the axis whose index is
               `iaxis'.

               help, mout
                  DOUBLE = Array[3,3]

Parameters

   None.

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.

   1) Compute the 3x3 matrix that rotates vectors from one
      frame to another frame rotated by pi/10 radians about
      +Z with respect to the first frame, and use it to transform
      an arbitrary vector from the first frame to the second frame.

      Example code begins here.


      PRO rotate_ex1

       ;;
       ;; Compute the 3x3 matrix that rotates vectors from one
       ;; frame to another frame rotated by pi/10 radians about
       ;; +Z with respect to the first frame
       ;;
       cspice_rotate, 0.1d*cspice_pi(), 3, rot_mat
       print, 'Rotation matrix:'
       print, rot_mat

       ;;
       ;; Apply the rotation to a vector.
       ;;
       vec = [ 1.2d, 3.4d, 4.5d ]

       ;;
       ;; First use the Icy matrix vector multiplication
       ;; routine.
       ;;
       cspice_mxv, rot_mat, vec, vec1
       print, FORMAT='("Result using SPICE          :",3F12.8)', vec1

       ;;
       ;; Now use the IDL # operator to perform the same
       ;; calculation, transposing the rot_mat matrix to
       ;; the IDL nominal format.
       ;;
       vec2 = transpose( rot_mat ) # vec
       print, FORMAT='("Result using IDL # operator :",3F12.8)', vec2

       ;;
       ;; Finally, use the IDL ## operator to again perform
       ;; the operation, this time as in linear algebra.
       ;;
       vec3 = rot_mat ## vec
       print, FORMAT='("Result using IDL ## operator:",3F12.8)', vec3

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      Rotation matrix:
            0.95105652      0.30901699       0.0000000
           -0.30901699      0.95105652       0.0000000
             0.0000000       0.0000000       1.0000000
      Result using SPICE          :  2.19192560  2.86277176  4.50000000
      Result using IDL # operator :  2.19192560  2.86277176  4.50000000
      Result using IDL ## operator:  2.19192560  2.86277176  4.50000000

Particulars

   A rotation about the first, i.e. x-axis, is described by

      .-                           -.
      |  1        0          0      |
      |  0   cos(theta) sin(theta)  |
      |  0  -sin(theta) cos(theta)  |
      `-                           -'

   A rotation about the second, i.e. y-axis, is described by

      .-                            -.
      |  cos(theta)  0  -sin(theta)  |
      |      0       1        0      |
      |  sin(theta)  0   cos(theta)  |
      `-                            -'

   A rotation about the third, i.e. z-axis, is described by

      .-                            -.
      |  cos(theta) sin(theta)   0   |
      | -sin(theta) cos(theta)   0   |
      |       0          0       1   |
      `-                            -'

   cspice_rotate decides which form is appropriate according to the value
   of `iaxis'.

Exceptions

   1)  If the axis index is not in the range 1 to 3, it will be
       treated the same as that integer 1, 2, or 3 that is congruent
       to it mod 3.

   2)  If any of the input arguments, `angle' or `iaxis', is
       undefined, an error is signaled by the IDL error handling
       system.

   3)  If any of the input arguments, `angle' or `iaxis', is not of
       the expected type, or it does not have the expected dimensions
       and size, an error is signaled by the Icy interface.

   4)  If the output argument `mout' is not a named variable, an
       error is signaled by the Icy interface.

Files

   None.

Restrictions

   None.

Required_Reading

   ICY.REQ
   ROTATION.REQ

Literature_References

   None.

Author_and_Institution

   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version

   -Icy Version 1.0.2, 01-JUN-2021 (JDR)

       Edited the header to comply with NAIF standard. Added example's
       problem statement and reformatted example's output.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections, and
       completed -Particulars section.

       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, 26-JAN-2006 (EDW)

       Reformatted Example section to improve reading clarity.

   -Icy Version 1.0.0, 16-JUN-2003 (EDW)

Index_Entries

   generate a rotation matrix