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

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

   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 nearp 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) 
 

Version

 
   -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 
 
Wed Apr  5 17:54:39 2017