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
npedln_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

npedln_c ( Nearest point on ellipsoid to line )

void npedln_c ( SpiceDouble         a,
SpiceDouble         b,
SpiceDouble         c,
ConstSpiceDouble    linept,
ConstSpiceDouble    linedr,
SpiceDouble         pnear,
SpiceDouble       * dist      )

Abstract

Find nearest point on a triaxial ellipsoid to a specified line,
and the distance from the ellipsoid to the line.

ELLIPSES

ELLIPSOID
GEOMETRY
MATH

Brief_I/O

VARIABLE  I/O  DESCRIPTION
--------  ---  --------------------------------------------------
a          I   Length of ellipsoid's semi-axis in the x direction
b          I   Length of ellipsoid's semi-axis in the y direction
c          I   Length of ellipsoid's semi-axis in the z direction
linept     I   Point on line
linedr     I   Direction vector of line
pnear      O   Nearest point on ellipsoid to line
dist       O   Distance of ellipsoid from line

Detailed_Input

a,
b,
c           are the lengths of the semi-axes of a triaxial
ellipsoid which is centered at the origin and
oriented so that its axes lie on the x-, y- and
z- coordinate axes.  a, b, and c are the lengths of
the semi-axes that point in the x, y, and z
directions respectively.

linept
linedr      are, respectively, a point and a direction vector
that define a line. The line is the set of vectors

linept   +   t * linedr

where t is any real number.

Detailed_Output

pnear       is the point on the ellipsoid that is closest to
the line, if the line doesn't intersect the
ellipsoid.

If the line intersects the ellipsoid, pnear will
be a point of intersection. If linept is outside
of the ellipsoid, pnear will be the closest point
of intersection. If linept is inside the
ellipsoid, pnear will not necessarily be the
closest point of intersection.

dist        is the distance of the line from the ellipsoid.
This is the minimum distance between any point on
the line and any point on the ellipsoid.

If the line intersects the ellipsoid, dist is zero.

None.

Exceptions

If this routine detects an error, the output arguments `pnear' and
`dist' are not modified.

1)  If the length of any semi-axis of the ellipsoid is
non-positive, the error SPICE(INVALIDAXISLENGTH) is signaled.

2)  If the line's direction vector is the zero vector, the error
SPICE(ZEROVECTOR) is signaled.

3)  If the length of any semi-axis of the ellipsoid is zero after
the semi-axis lengths are scaled by the reciprocal of the
magnitude of the longest semi-axis and then squared, the error
SPICE(DEGENERATECASE) is signaled.

4)  If the input ellipsoid is extremely flat or needle-shaped
and has its shortest axis close to perpendicular to the input
line, numerical problems could cause this routine's algorithm
to fail, in which case, the error SPICE(DEGENERATECASE) is
signaled.

None.

Particulars

For any ellipsoid and line, if the line does not intersect the
ellipsoid, there is a unique point on the ellipsoid that is
closest to the line. Therefore, the distance dist between
ellipsoid and line is well-defined. The unique line segment of
length dist that connects the line and ellipsoid is normal to
both of these objects at its endpoints.

If the line intersects the ellipsoid, the distance between the
line and ellipsoid is zero.

Examples

1)   We can find the distance between an instrument optic axis ray
and the surface of a body modelled as a tri-axial ellipsoid
using this routine. If the instrument position and pointing
unit vector in body-fixed coordinates are

linept = ( 1.0e6,  2.0e6,  3.0e6 )

and

linedr = ( -4.472091234e-1
-8.944182469e-1,
-4.472091234e-3  )

and the body semi-axes lengths are

a = 7.0e5
b = 7.0e5
c = 6.0e5,

then the call to npedln_c

npedln_c ( a, b, c, linept, linedr, pnear, &dist );

yields a value for pnear, the nearest point on the body to
the optic axis ray, of

(  -.16333110792340931E+04,
-.32666222157820771E+04,
.59999183350006724E+06  )

and a value for dist, the distance to the ray, of

.23899679338299707E+06

(These results were obtained on a PC-Linux system under gcc.)

In some cases, it may not be clear that the closest point
on the line containing an instrument boresight ray is on
the boresight ray itself; the point may lie on the ray
having the same vertex as the boresight ray and pointing in
the opposite direction. To rule out this possibility, we
can make the following test:

/.
Find the difference vector between the closest point
on the ellipsoid to the line containing the boresight
ray and the boresight ray's vertex. Find the
angular separation between this difference vector
and the boresight ray. If the angular separation
does not exceed pi/2, we have the nominal geometry.
Otherwise, we have an error.
./

vsub_c ( pnear,  linept,  diff );

sep = vsep_c ( diff, linedr );

if (  sep <= halfpi_c()  )
{
[ perform normal processing ]
}
else
{
[ handle error case ]
}

None.

None.

Author_and_Institution

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

Version

-CSPICE Version 1.1.1, 04-AUG-2021 (JDR)

Edited the header to comply with NAIF standard.

-CSPICE Version 1.1.0, 01-JUN-2010 (NJB)

Added touchd_ calls to tests for squared, scaled axis length
underflow. This forces rounding to zero in certain cases where
it otherwise might not occur due to use of extended registers.

-CSPICE Version 1.0.1, 06-DEC-2002 (NJB)

Outputs shown in header example have been corrected to
be consistent with those produced by this routine.

-CSPICE Version 1.0.0, 03-SEP-1999 (NJB)

Index_Entries

distance between line and ellipsoid
distance between line of sight and body
nearest point on ellipsoid to line
Fri Dec 31 18:41:10 2021