Procedure

     NPEDLN ( Nearest point on ellipsoid to line )

     SUBROUTINE NPEDLN ( A, B, C, LINEPT, LINEDR, PNEAR, DIST )

Abstract

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

Required_Reading

     ELLIPSES

Keywords

     ELLIPSOID
     GEOMETRY
     MATH

Declarations

     IMPLICIT NONE

     INTEGER               UBEL
     PARAMETER           ( UBEL = 9 )

     INTEGER               UBPL
     PARAMETER           ( UBPL = 4 )

     DOUBLE PRECISION      A
     DOUBLE PRECISION      B
     DOUBLE PRECISION      C
     DOUBLE PRECISION      LINEPT ( 3 )
     DOUBLE PRECISION      LINEDR ( 3 )
     DOUBLE PRECISION      PNEAR  ( 3 )
     DOUBLE PRECISION      DIST

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
     UBEL       P   Upper bound of array containing SPICE ellipse.
     UBPL       P   Upper bound of array containing SPICE plane.

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.

Parameters

     UBEL     is the upper bound of the array used to contain
              a SPICE ellipse. See the ELLIPSES Required
              Reading for details.

     UBPL     is the upper bound of the array used to contain
              a SPICE plane. See the PLANES Required Reading
              for details.

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.

Files

     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 modeled as a tri-axial ellipsoid
          using this routine. If the instrument position and pointing
          unit vector in body-fixed coordinates are

             LINEPT = ( 1.0D6,  2.0D6,  3.0D6 )

          and

             LINEDR = ( -4.472091234D-1
                        -8.944182469D-1,
                        -4.472091234D-3  )

          and the body semi-axes lengths are

             A = 7.0D5
             B = 7.0D5
             C = 6.0D5,

          then the call to NPEDLN

             CALL NPEDLN ( A,      B,      C,
            .              LINEPT, LINEDR,
            .              PNEAR,  DIST        )

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


             (  -1.6333110792340931E+03,
                -3.2666222157820771E+03,
                 5.9999183350006724E+05  )

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

             2.3899679338299707E+06

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

          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:

             C
             C     Find the difference vector between the closest point
             C     on the ellipsoid to the line containing the
             C     boresight ray and the boresight ray's vertex. Find
             C     the angular separation between this difference
             C     vector and the boresight ray. If the angular
             C     separation does not exceed pi/2, we have the nominal
             C     geometry. Otherwise, we have an error.
             C
                   CALL  VSUB ( PNEAR,  LINEPT,  DIFF )
                   SEP = VSEP ( DIFF,   LINEDR        )

                   IF (  SEP .LE. HALFPI()  ) THEN

                      [ perform normal processing ]

                   ELSE

                      [ handle error case ]

                   END IF

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.4.0, 24-AUG-2021 (JDR)

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard. Corrected
        argument name in $Exceptions section.

    SPICELIB Version 1.3.0, 15-NOV-2005 (NJB)

        Updated to remove non-standard use of duplicate arguments
        in VSCL calls. Changed exponents to DOUBLE PRECISION type
        in the test for underflow of squared, scaled axis lengths.

    SPICELIB Version 1.2.1, 06-DEC-2002 (NJB)

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

    SPICELIB Version 1.2.0, 25-NOV-1992 (NJB)

        Bug fix: in the intercept case, PNEAR is now properly
        re-scaled prior to output. Also, an error in the $Examples
        section was corrected.

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

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

    SPICELIB Version 1.1.0, 04-DEC-1990 (NJB)

        Error message and description changed for non-positive
        axis length error.

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