vsepg_c

Index Page vsepg_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 vsepg_c ( ConstSpiceDouble * v1,
                             ConstSpiceDouble * v2,
                             SpiceInt           ndim )
#### Abstract
       vsepg_c finds the separation angle in radians between two double
       precision vectors of arbitrary dimension. 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.
         ndim      I     The number of elements in v1 and v2.
#### Detailed_Input
        v1      is any double precision vector of arbitrary dimension.
        v2      is also a double precision vector of arbitrary dimension.
                v1 or v2 or both may be the zero vector.
        ndim    is the dimension of the both of the input vectors
                v1 and v2.
#### Detailed_Output
        vsepg_c the angle between v1 and v2 expressed in radians.
                vsepg_c is strictly non-negative.  For input vectors of
                four or more dimensions, the angle is defined as the
                generalization of the definition for three dimensions.
                If either v1 or v2 is the zero vector, then vsepg_c is
                defined to be 0 radians.
#### Parameters
        None.
#### Exceptions
       Error free.
#### Files
        None
#### Particulars
        In four or more dimensions this angle does not have a physically
        realizable interpretation.  However, the angle is defined as
        the generalization of the following definition which is valid in
        three or two dimensions:

        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 * sine ( vsepg/2.0 )

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

              length = norm ( u1 - u2 )

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

              vsepg_c = 2.0 * arcsine ( length/2.0 )

        This expression becomes increasingly unstable when vsepg_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 vsepg_c is given by

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

        v1               v2               ndim          vsepg_c
        -----------------------------------------------------------------
        (1, 0, 0, 0)     (1, 0, 0, 0)       4           0.0
        (1, 0, 0)        (0, 1, 0)          3           pi/2 (=1.71...)
        (3, 0)           (-5, 0)            2           pi   (=3.14...)
#### 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
       C.A. Curzon     (JPL)
       K.R. Gehringer  (JPL)
       H.A. Neilan     (JPL)
       W.L. Taber      (JPL)
       E.D. Wright     (JPL)
#### Version
       -CSPICE Version 1.0.0, 29-JUN-1999
#### Index_Entries
       angular separation of n-dimensional vectors
#### Link to routine vsepg_c source file vsepg_c.c

    Thu Apr 16 08:59:36 2009