Index of Functions: A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X
npelpt_c

 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

```   npelpt_c ( Nearest point on ellipse to point )

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.
```

```   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 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_c, 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 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 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

#include "SpiceUsr.h"
.
.
.
/.
Make a SPICE 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)
J. Diaz del Rio     (ODC Space)
```

#### Version

```   -CSPICE Version 1.0.1, 24-AUG-2021 (JDR)

Edited the header to comply with NAIF standard.

-CSPICE Version 1.0.0, 02-SEP-1999 (NJB)
```

#### Index_Entries

```   nearest point on ellipse to point
```
`Fri Dec 31 18:41:10 2021`