Abstract

   CSPICE_UNORM normalizes a double precision 3-vector and returns its
   magnitude.

I/O

   Given:

      v1       an arbitrary 3-vector, including the zero vector.

               help, v1
                  DOUBLE = Array[3]

   the call:

      cspice_unorm, v1, vout, vmag

   returns:

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

               help, vout
                  DOUBLE = Array[3]

               If `v1' is the zero vector, then `vout' will also be the zero
               vector.

      vmag     the magnitude of `v1'.

               help, vmag
                  DOUBLE = Scalar

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 and magnitude.


      Example code begins here.


      PRO unorm_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 and magnitudes.
         ;;
         for i=0, SETSIZ - 1L do begin

            cspice_unorm, seta[*,i], vout, vmag

            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, format='(A,F13.8)',  'Magnitude  : ', vmag
            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
      Magnitude  :   13.00000000

      Vector     :    0.00000010   0.00000020   0.00000020
      Unit vector:    0.33333333   0.66666667   0.66666667
      Magnitude  :    0.00000030


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

         vout = v1/norm( v1 )
         mag  = norm( v1 )

      The IDL version accepts arbitrary N-vectors.

Particulars

   cspice_unorm references a procedure called cspice_vnorm (which itself is
   numerically stable) to calculate the norm of the input vector `v1'.
   If the norm is equal to zero, then each component of the output
   vector `vout' is set to zero. Otherwise, `vout' is calculated by
   dividing `v1' by the norm.

Exceptions

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

   2)  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.

   3)  If any of the output arguments, `vout' or `vmag', is not a
       named variable, an error is signaled by the Icy interface.

Files

   None.

Restrictions

   None.

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, 27-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, 13-JUN-2011 (EDW)

       Edits to comply with NAIF standard for Icy headers.

   -Icy Version 1.0.1, 09-DEC-2005 (EDW)

       Added -Examples section.

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

Index_Entries

   3-dimensional unit vector and norm