Index Page vsep_c
A B C D E F G H I J K L M N O P Q R S T U V W X
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       SpiceDouble vsep_c ( ConstSpiceDouble v1[3], ConstSpiceDouble v2[3] )
#### Abstract
       Find the separation angle in radians between two double
       precision, 3-dimensional vectors.  This angle is defined as zero
       if either vector is zero.
#### Required_Reading
       None.
#### Keywords
       ANGLE,  VECTOR
#### Brief_I/O
       VARIABLE  I/O  DESCRIPTION
       --------  ---  --------------------------------------------------
        v1        I     First vector.
        v2        I     Second vector.
#### Detailed_Input
       v1      is an arbitrary double precision, 3-dimensional vector.
       v2      is also an arbitrary double precision, 3-dimensional
                vector.  v1 or v2 or both may be the zero vector.
#### Detailed_Output
       vsep_c    is the angle between v1 and v2 expressed in radians.
                vsep_c is strictly non-negative.  If either v1 or v2 is
                the zero vector, then vsep_c is defined to be 0 radians.
#### Parameters
       None.
#### Exceptions
       Error free.
#### Files
       None
#### Particulars
       In the plane, it is a simple matter to calculate the angle
       between two vectors once the two vectors have been made to be
       unit length.  Then, since the two vectors form the two equal
       sides of an isosceles triangle, the length of the third side
       is given by the expression

              length = 2.0 * sin ( vsep /2.0 )

       The length is given by the magnitude of the difference of the
       two unit vectors

              length = norm_c ( u1 - u2 )

       Once the length is found, the value of vsep_c may be calculated
       by inverting the first expression given above as

              vsep  = 2.0 * arcsin ( length/2.0 )

       This expression becomes increasingly unstable when vsep_c gets
       larger than PI/2 or 90 degrees.  In this situation (which is
       easily detected by determining the sign of the dot product of
       v1 and v2) the supplementary angle is calculated first and
       then vsep_c is given by

              vsep  = pi - supplementary_angle
#### Examples
       The following table gives sample values for v1, v2 and vsep_c
       implied by the inputs.

       v1                        v2                      vsep_c
       -----------------------------------------------------------------
       (1, 0, 0)                (1, 0, 0)                0.0
       (1, 0, 0)                (0, 1, 0)                PI/2 (=1.571...)
#### Restrictions
       The user is required to insure that the input vectors will not
       cause floating point overflow upon calculation of the vector
       dot product since no error detection or correction code is
       implemented.  In practice, this is not a significant
       restriction.
#### Literature_References
       None
#### Author_and_Institution
       K.R. Gehringer  (JPL)
       W.M. Owen       (JPL)
       W.L. Taber      (JPL)
#### Version
       -CSPICE Version 1.1.1, 17-APR-2006 (EDW)

          Typo correction to the value of PI/2 in the Examples
          section, 1.571 instead of 1.71.

       -CSPICE Version 1.1.0, 22-OCT-1998 (NJB)

          Made input vectors const.

       -CSPICE Version 1.0.0, 08-FEB-1998   (EDW)
#### Index_Entries
       angular separation of 3-dimensional vectors
#### Link to routine vsep_c source file vsep_c.c

    Wed Jun  9 13:05:32 2010