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
Index Page npedln_c
Table of contents
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[3],
                       ConstSpiceDouble    linedr[3],
                       SpiceDouble         pnear[3],
                       SpiceDouble       * 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
#### 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.
#### Parameters
       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.
#### 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 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 ]
               }
#### Restrictions
       None.
#### Literature_References
       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
#### Link to routine npedln_c source file npedln_c.c

    Fri Dec 31 18:41:10 2021