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
cspice_isrot

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_ISROT returns a boolean indicating whether an input matrix
   numerically appears to be a rotation matrix to within some tolerance
   for the norms of each column and a tolerance for the matrix determinant.

I/O


   Given:

      m        a 3x3 matrix to be tested.

               help, m
                  DOUBLE = Array[3,3]

      ntol     the tolerance for the norms of the columns of `m'.

               help, ntol
                  DOUBLE = Scalar

      dtol     the tolerance for the determinant of a matrix whose columns are
               the unitized columns of `m'.

               help, dtol
                  DOUBLE = Scalar

   the call:

      isrot = cspice_isrot( m, ntol, dtol )

   returns:

      isrot    True if and only if `m' is found to be a rotation matrix.

               help, isrot
                  BOOLEAN = Scalar

               The criteria that `m' must meet are:

               1) The norm of each column of `m' must satisfy the relation

                     1.0 - ntol  <   || column ||   <  1.0 + ntol
                                 -                  -

               2) The determinant of the matrix whose columns are the
                  unitized columns of `m' must satisfy

                     1.0 - dtol  <   determinant   <  1.0 + dtol
                                 -                 -

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) Check if an identity 3x3 matrix appears to be a rotation matrix
      to within a given tolerance for the norms of each column and for
      the matrix determinant. Perform the same check on a rotation
      matrix created from some arbitrary angles using cspice_eul2m,
      and on its inverse.

      Example code begins here.


      PRO isrot_ex1

         ;;
         ;; Define tolerances for the matrix norm and determinant.
         ;;
         norm_tol = .00001d
         det_tol  = .00001d

         ;;
         ;; Create an identity matrix.
         ;;
         cspice_ident, rident

         ;;
         ;; Check it...
         ;;
         print, 'Identity matrix: '
         if ( cspice_isrot( rident, norm_tol, det_tol ) ) then begin

            print, '   Matrix is a rotation matrix'

         endif else begin

            print, '   Matrix is not a rotation matrix'

         endelse

         ;;
         ;; Now create a  3-1-3 rotation matrix from some
         ;; arbitrary angles.
         ;;
         cspice_eul2m, .05d, .75d, 1.d, 3, 1, 3, rot

         ;;
         ;; Test rot using cspice_isrot.
         ;;
         print, 'Matrix created using cspice_eul2m:'
         if ( cspice_isrot( rot, norm_tol, det_tol) ) then begin

            print, '   Matrix is a rotation matrix'

         endif else begin

            print, '   Matrix is not a rotation matrix'

         endelse

         ;;
         ;; Now perform a numerical test. A rotation matrix is
         ;; orthogonal so the invert of the matrix is also the transpose.
         ;; Therefore, transpose(rot) . rot = ident.
         ;;
         print, 'Matrix times inverse: '
         print, transpose(rot) ## rot

      END


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


      Identity matrix:
         Matrix is a rotation matrix
      Matrix created using cspice_eul2m:
         Matrix is a rotation matrix
      Matrix times inverse:
             1.0000000  -1.1102230e-16       0.0000000
        -1.1102230e-16       1.0000000   5.5511151e-17
             0.0000000   5.5511151e-17       1.0000000


      Note that the result appears as an identity matrix to within
      roundoff error for double precision numbers.

Particulars


   This routine is an error checking `filter'; its purpose is to
   detect gross errors, such as uninitialized matrices. Matrices
   that do not pass the tests used by this routine hardly qualify as
   rotation matrices. The test criteria can be adjusted by varying
   the parameters `ntol' and `dtol'.

   A property of rotation matrices is that their columns form a
   right-handed, orthonormal basis in 3-dimensional space. The
   converse is true: all 3x3 matrices with this property are
   rotation matrices.

   An ordered set of three vectors `v1', `v2', `v3' forms a right-handed,
   orthonormal basis if and only if

      1)   || v1 ||  =  || v2 ||  =  || v3 ||  =  1

      2)   v3 = v1 x v2. Since `v1', `v2', and `v3' are unit vectors,
           we also have

           < v3, v1 x v2 > = 1.

           This quantity is the determinant of the matrix whose
           columns are `v1', `v2' and `v3'.

   When finite precision numbers are used, rotation matrices will
   usually fail to satisfy these criteria exactly. We must use
   criteria that indicate approximate conformance to the criteria
   listed above. We choose

      1)   |   || vi ||  -  1   |   <   ntol,  i = 1, 2, 3.
                                    -

      2)   Let

                      vi
              ui = -------- ,   i = 1, 2, 3.
                    ||vi||

           Then we require

              | < u3, u1 x u2 > - 1 |  <  dtol;
                                       -

           equivalently, letting `u' be the matrix whose columns
           are `u1', `u2', and u3, we insist on

              | det(u) - 1 |  <  dtol.
                              -

Exceptions


   1)  If either of `ntol' or `dtol' is negative, the error
       SPICE(VALUEOUTOFRANGE) is signaled by a routine in the call
       tree of this routine. cspice_isrot returns the value False in this
       case.

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

   3)  If any of the input arguments, `m', `ntol' or `dtol', is not
       of the expected type, or it does not have the expected
       dimensions and size, 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.1, 17-JUN-2021 (JDR)

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

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

       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.0, 16-JUN-2003 (EDW)

Index_Entries


   indicate whether a matrix is a rotation matrix



Fri Dec 31 18:43:05 2021