Abstract

   CSPICE_VHAT calculates the unit vector along a double precision
   3-vector.

I/O

   Given:

      v1       any double precision, 3-dimensional vector.

               help, v1
                  DOUBLE = Array[3]

   the call:

      cspice_vhat, v1, vout

   returns:

      vout     the unit vector in the direction of `v1'.

               help, vout
                  DOUBLE = Array[3]

               If `v1' represents the zero vector, then `vout' will also be
               the zero vector. `vout' may overwrite `v1'.

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) Define a set of vectors and compute their corresponding unit
      vector.


      Example code begins here.


      PRO vhat_ex1

         ;;
         ;; Local parameters.
         ;;
         SETSIZ = 2

         ;;
         ;; Define the vector set.
         ;;
         seta = [[5.0,  12.0,  0.0], [1.e-7,  2.e-7, 2.e-7]]

         ;;
         ;; Calculate the unit vectors.
         ;;
         for i=0, SETSIZ - 1L do begin

            cspice_vhat, seta[*,i], vout

            print, format='(A,3F13.8)', 'Vector     : ', seta[0,i],          $
                                        seta[1,i], seta[2,i]
            print, format='(A,3F13.8)', 'Unit vector: ', vout[0], vout[1],   $
                                        vout[2]
            print, ' '

         endfor

      END


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


      Vector     :    5.00000000  12.00000000   0.00000000
      Unit vector:    0.38461538   0.92307692   0.00000000

      Vector     :    0.00000010   0.00000020   0.00000020
      Unit vector:    0.33333333   0.66666667   0.66666667


      Note that the IDL native code to perform this operation is:

         vout = vin/norm(vin)

      The IDL version accepts arbitrary N-vectors.

Particulars

   cspice_vhat determines the magnitude of `v1' and then divides each
   component of `v1' by the magnitude. This process is highly stable
   over the whole range of 3-dimensional vectors.

Exceptions

   1)  If `v1' represents the zero vector, then `vout' will also be the
       zero vector.

   2)  If the input argument `v1' is undefined, an error is signaled
       by the IDL error handling system.

   3)  If the input argument `v1' 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 `vout' is not a named variable, an
       error is signaled by the Icy interface.

Files

   None.

Restrictions

   1)  There is no known case whereby floating point overflow may
       occur. Thus, no error recovery or reporting scheme is
       incorporated into this routine.

Required_Reading

   ICY.REQ

Literature_References

   None.

Author_and_Institution

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

Version

   -Icy Version 1.0.3, 10-AUG-2021 (JDR)

       Updated the header to comply with NAIF standard. Added
       complete code example to -Examples section.

       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.2, 09-DEC-2005 (EDW)

       Added -Examples section.

   -Icy Version 1.0.1, 10-OCT-2005 (EDW)

       Corrected notation |vin| to ||vin||

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

Index_Entries

   unitize a 3-dimensional vector