Abstract

   CSPICE_VDIST returns the scalar distance between two three-dimensional
   vectors.

I/O

   Given:

      v1,
      v2       two vectors in three-dimensional space, the distance between
               which is desired.

               help, v1
                  DOUBLE = Array[3]
               help, v2
                  DOUBLE = Array[3]

   the call:

      vdist = cspice_vdist( v1, v2 )

   returns:

      vdist    the distance between `v1' and `v2'.

               help, vdist
                  DOUBLE = Scalar

               This is defined as

                  ||  v1 - v2  ||,

               where || x || indicates the Euclidean norm of the vector x.

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 two three-dimensional vectors and calculate the distance
      between them.

      Example code begins here.


      PRO vdist_ex1

         v1 = [ 12.3d   , -4.32d ,  76.d  ]
         v2 = [ 23.0423d, -11.99d, -0.10d ]

         print, 'Distance between v1 and v2:', cspice_vdist( v1, v2)

      END


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


      Distance between v1 and v2:       77.236234


      Note, the native IDL code to calculate the same scalar result:

         norm( v1 - v2 )

      The IDL function accepts an arbitrary size N-vectors.

Particulars

   This function is simply shorthand for the code

      cspice_vsub, v1, v2, diff

      dist = cspice_vnorm( diff )

   Using this function saves you the annoyance of declaring local
   storage for the difference vector `diff'.


   The Euclidean norm of a three-dimensional vector (x, y, z) is
   defined as

                                   1/2
           2        2        2
      (   x    +   y    +   z    ).


   This number is the distance of the point (x, y, z) from the
   origin. If `a' and `b' are two vectors whose components are

      ( a[0], a[1], a[2] )    and    ( b[0], b[1], b[2] ),

   then the distance between `a' and `b' is the norm of the difference
   a - b, which has components


      (  a[0] - b[0],  a[1] - b[1],  a[2] - b[2]  ).


   A related routine is cspice_vdistg, which computes the distance between
   two vectors of general dimension.

Exceptions

   1)  If any of the input arguments, `v1' or `v2', is undefined, an
       error is signaled by the IDL error handling system.

   2)  If any of the input arguments, `v1' or `v2', 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

Literature_References

   None.

Author_and_Institution

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

Version

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

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

       Added -Parameters, -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.2, 13-JUN-2011 (EDW)

       Edits to comply with NAIF standard for Icy headers.

       Corrected version ID for 18-APR-2006 entry "1.0.1"
       rather than "1.0.2."

   -Icy Version 1.0.1, 18-APR-2006 (EDW)

       Expanded header comments.

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

Index_Entries

   distance between 3-dimensional vectors