npelpt_c

Index Page npelpt_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
       void npelpt_c ( ConstSpiceDouble      point  [3],
                       ConstSpiceEllipse   * ellips,
                       SpiceDouble           pnear  [3],
                       SpiceDouble         * dist       )
#### Abstract
       Find the nearest point on an ellipse to a specified point, both
       in three-dimensional space, and find the distance between the
       ellipse and the point.
#### Required_Reading
       ELLIPSES
#### Keywords
       CONIC
       ELLIPSE
       GEOMETRY
       MATH
#### Brief_I/O
       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       point      I   Point whose distance to an ellipse is to be found.
       ellips     I   A CSPICE ellipse.
       pnear      O   Nearest point on ellipse to input point.
       dist       O   Distance of input point to ellipse.
#### Detailed_Input
       ellips         is a CSPICE ellipse that represents an ellipse
                      in three-dimensional space.

       point          is a point in 3-dimensional space.
#### Detailed_Output
       pnear          is the nearest point on ellips to point.

       dist           is the distance between point and pnear.  This is
                      the distance between point and the ellipse.
#### Parameters
       None.
#### Exceptions
       1)  Invalid ellipses will be diagnosed by routines called by
           this routine.

       2)  Ellipses having one or both semi-axis lengths equal to zero
           are turned away at the door; the error SPICE(DEGENERATECASE)
           is signalled.

       3)  If the geometric ellipse represented by ellips does not
           have a unique point nearest to the input point, any point
           at which the minimum distance is attained may be returned
           in pnear.
#### Files
       None.
#### Particulars
       Given an ellipse and a point in 3-dimensional space, if the
       orthogonal projection of the point onto the plane of the ellipse
       is on or outside of the ellipse, then there is a unique point on
       the ellipse closest to the original point.  This routine finds
       that nearest point on the ellipse.  If the projection falls inside
       the ellipse, there may be multiple points on the ellipse that are
       at the minimum distance from the original point.  In this case,
       one such closest point will be returned.

       This routine returns a distance, rather than an altitude, in
       contrast to the CSPICE routine nearpt_c.  Because our ellipse is
       situated in 3-space and not 2-space, the input point is not
       `inside' or `outside' the ellipse, so the notion of altitude does
       not apply to the problem solved by this routine.  In the case of
       nearpt_c, the input point is on, inside, or outside the ellipsoid,
       so it makes sense to speak of its altitude.
#### Examples
       1)  For planetary rings that can be modelled as flat disks with
           elliptical outer boundaries, the distance of a point in
           space from a ring's outer boundary can be computed using this
           routine.  Suppose center, smajor, and sminor are the center,
           semi-major axis, and semi-minor axis of the ring's boundary.
           Suppose also that scpos is the position of a spacecraft.
           scpos, center, smajor, and sminor must all be expressed in
           the same coordinate system.  We can find the distance from
           the spacecraft to the ring using the code fragment

              #include "SpiceUsr.h"
                   .
                   .
                   .
              /.
              Make a CSPICE ellipse representing the ring,
              then use npelpt_c to find the distance between
              the spacecraft position and RING.
              ./
              cgv2el_c ( center, smajor, sminor,  ring );
              npelpt_c ( scpos,  ring,   pnear,  &dist );

       2)  The problem of finding the distance of a line from a tri-axial
           ellipsoid can be reduced to the problem of finding the
           distance between the same line and an ellipse; this problem in
           turn can be reduced to the problem of finding the distance
           between an ellipse and a point.  The routine npedln_c carries
           out this process and uses npelpt_c to find the ellipse-to-point
           distance.
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman   (JPL)
#### Version
       -CSPICE Version 1.0.0, 02-SEP-1999 (NJB)
#### Index_Entries
       nearest point on ellipse to point
#### Link to routine npelpt_c source file npelpt_c.c

    Thu Apr 16 08:58:43 2009