Procedure

     NPELPT  ( Nearest point on ellipse to point )

     SUBROUTINE NPELPT ( POINT, ELLIPS, PNEAR, 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

Declarations

     IMPLICIT NONE

     INTEGER               UBEL
     PARAMETER           ( UBEL    =   9 )

     DOUBLE PRECISION      ELLIPS ( UBEL )
     DOUBLE PRECISION      POINT  (    3 )
     DOUBLE PRECISION      PNEAR  (    3 )
     DOUBLE PRECISION      DIST

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     POINT      I   Point whose distance to an ellipse is to be found.
     ELLIPS     I   A SPICE ellipse.
     PNEAR      O   Nearest point on ellipse to input point.
     DIST       O   Distance of input point to ellipse.

Detailed_Input

     POINT    is a point in 3-dimensional space.

     ELLIPS   is a SPICE ellipse that represents an ellipse
              in three-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)  If the input ellipse ELLIPS has one or both semi-axis lengths
         equal to zero, the error SPICE(DEGENERATECASE) is signaled.

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

     3)  If a ratio of non-zero ellipse radii violates the constraints
         imposed by NEARPT, an error is signaled by a routine in the
         call tree of this routine.

     4)  The routine does not check for overflow when scaling or
         translating the input point.

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 SPICELIB routine NEARPT. 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, 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 modeled 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

            C
            C     Make a SPICE ellipse representing the ring,
            C     then use NPELPT to find the distance between
            C     the spacecraft position and RING.
            C
                  CALL CGV2EL ( CENTER, SMAJOR, SMINOR, RING )
                  CALL NPELPT ( 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 carries
         out this process and uses NPELPT to find the ellipse-to-point
         distance.

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     W.L. Taber         (JPL)

Version

    SPICELIB Version 1.3.0, 24-AUG-2021 (JDR) (NJB)

        Added IMPLICT NONE statement.

        Edited the header to comply with NAIF standard.

        Added entries #3 and #4 to $Exceptions section.

    SPICELIB Version 1.2.0, 02-SEP-2005 (NJB)

        Updated to remove non-standard use of duplicate arguments
        in VADD, VSCL, MTXV and MXV calls.

    SPICELIB Version 1.0.1, 10-MAR-1992 (WLT)

        Comment section for permuted index source lines was added
        following the header.

    SPICELIB Version 1.0.0, 02-NOV-1990 (NJB)