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
cspice_nearpt

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_NEARPT locates the point on the surface of an ellipsoid that is
   nearest to a specified position. This routine also returns the altitude
   of the position above the ellipsoid.

I/O


   Given:

      positn   a 3-vector giving the position of a point with respect to the
               center of an ellipsoid.

               help, positn
                  DOUBLE = Array[3]

               The vector is expressed in a body-fixed reference frame. The
               semi-axes of the ellipsoid are aligned with the x, y, and z-axes
               of the body-fixed frame.

      a        the length of the semi-axis of the ellipsoid that is parallel to
               the X-axis of the body-fixed reference frame.

               help, a
                  DOUBLE = Scalar

      b        the length of the semi-axis of the ellipsoid that is parallel to
               the Y-axis of the body-fixed reference frame.

               help, b
                  DOUBLE = Scalar

      c        the length of the semi-axis of the ellipsoid that is parallel to
               the Z-axis of the body-fixed reference frame.

               help, c
                  DOUBLE = Scalar

   the call:

      cspice_nearpt, positn, a, b, c, npoint, alt

   returns:

      npoint   the nearest point on the ellipsoid to `positn'.

               help, npoint
                  DOUBLE = Array[3]

               `npoint' is a 3-vector expressed in the body-fixed reference
               frame.

      alt      the altitude of `positn' above the ellipsoid.

               help, alt
                  DOUBLE = Scalar

               If `positn' is inside the ellipsoid, `alt' will be negative and
               have magnitude equal to the distance between `npoint' and
               `positn'.

Parameters


   None.

Examples


   Any numerical results shown for these examples may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

   1) Given a point outside an ellipsoid, compute the nearest point
      on its surface.

      Example code begins here.


      PRO nearpt_ex1

         ;;
         ;; Define the radii of an ellipsoid.
         ;;
         a  =  1.d
         b  =  2.d
         c  =  3.d

         ;;
         ;; Use point on the X axis, outside the ellipsoid.
         ;;
         point  = [ 3.5d, 0.d, 0.d ]
         cspice_nearpt, point, a, b, c, pnear, alt

         print, FORMAT='(A,3F6.2)', 'Nearest point:', pnear
         print, FORMAT='(A,F6.2)',  'Altitude     :', alt

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      Nearest point:  1.00  0.00  0.00
      Altitude     :  2.50


   2) Compute the point on the Earth nearest to the Moon at ephemeris
      time 0.0 (Jan 1 2000, 12:00 TBD).

      Use the meta-kernel shown below to load the required SPICE
      kernels.


         KPL/MK

         File name: nearpt_ex2.tm

         This meta-kernel is intended to support operation of SPICE
         example programs. The kernels shown here should not be
         assumed to contain adequate or correct versions of data
         required by SPICE-based user applications.

         In order for an application to use this meta-kernel, the
         kernels referenced here must be present in the user's
         current working directory.

         The names and contents of the kernels referenced
         by this meta-kernel are as follows:

            File name                     Contents
            ---------                     --------
            de421.bsp                     Planetary ephemeris
            pck00010.tpc                  Planet orientation and
                                          radii

         \begindata

            KERNELS_TO_LOAD = ( 'de421.bsp',
                                'pck00010.tpc' )

         \begintext

         End of meta-kernel


      Example code begins here.


      PRO nearpt_ex2

         ;;
         ;; Load a meta kernel containing an SPK and a PCK.
         ;;
         cspice_furnsh, 'nearpt_ex2.tm'

         ;;
         ;; Retrieve the position of the Moon wrt the Earth at
         ;; ephemeris time 0.d (Jan 1 2000 12:00 TDB) in the Earth-fixed
         ;; reference frame.
         ;;
         epoch = 0.d
         abcorr= 'LT+S'
         cspice_spkezr, 'moon', epoch, 'IAU_EARTH', abcorr, 'earth', $
                         state, ltime

         ;;
         ;; Retrieve the triaxial radii for Earth (body ID 399).
         ;;
         cspice_bodvrd, 'EARTH', 'RADII', 3, radii

         ;;
         ;; Now calculate the point on the Earth nearest to the Moon
         ;; given LT+S aberration correction at the epoch time.
         ;;
         cspice_nearpt, state[0:2], radii[0], radii[1], radii[2], $
                        npoint, alt
         print, FORMAT='(A,F16.8)',  'Epoch        : ', epoch
         print, FORMAT='(A,3F16.8)', 'Nearest point: ', npoint
         print, FORMAT='(A,F16.8)',  'Altitude     : ', alt

         ;;
         ;; It's always good form to unload kernels after use,
         ;; particularly in IDL due to data persistence.
         ;;
         cspice_kclear

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      Epoch        :       0.00000000
      Nearest point:    3347.08204098  -5294.53585186  -1198.28264121
      Altitude     :  396037.22419372


Particulars


   Many applications of this routine are more easily performed
   using the higher-level Icy routine cspice_subpnt. This routine
   is the mathematical workhorse on which cspice_subpnt relies.

   This routine solves for the location, N, on the surface of an
   ellipsoid nearest to an arbitrary location, P, relative to that
   ellipsoid.

Exceptions


   1)  If any of the axis lengths `a', `b' or `c' are non-positive, the
       error SPICE(BADAXISLENGTH) is signaled by a routine in the
       call tree of this routine.

   2)  If the ratio of the longest to the shortest ellipsoid axis
       is large enough so that arithmetic expressions involving its
       squared value may overflow, the error SPICE(BADAXISLENGTH)
       is signaled by a routine in the call tree of this routine.

   3)  If any of the expressions

          a * abs( positn[0] ) / m^2
          b * abs( positn[1] ) / m^2
          c * abs( positn[2] ) / m^2

       where `m' is the minimum of { `a', `b', `c' }, is large enough so
       that arithmetic expressions involving these sub-expressions may
       overflow, the error SPICE(INPUTSTOOLARGE) is signaled by a
       routine in the call tree of this routine.

   4)  If the axes of the ellipsoid have radically different
       magnitudes, for example, if the ratios of the axis lengths vary
       by 10 orders of magnitude, the results may have poor
       precision. No error checks are done to identify this problem.

   5)  If the axes of the ellipsoid and the input point `positn' have
       radically different magnitudes, for example if the ratio of
       the magnitude of `positn' to the length of the shortest axis is
       1.D25, the results may have poor precision. No error checks
       are done to identify this problem.

   6)  If any of the input arguments, `positn', `a', `b' or `c', is
       undefined, an error is signaled by the IDL error handling
       system.

   7)  If any of the input arguments, `positn', `a', `b' or `c', is
       not of the expected type, or it does not have the expected
       dimensions and size, an error is signaled by the Icy
       interface.

   8)  If any of the output arguments, `npoint' or `alt', is not a
       named variable, an error is signaled by the Icy interface.

Files


   None.

Restrictions


   See -Exceptions section.

Required_Reading


   ICY.REQ
   ELLIPSES.REQ

Literature_References


   None.

Author_and_Institution


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

Version


   -Icy Version 2.0.0, 01-NOV-2021 (NJB) (JDR) (EDW)

       Edit to logic to reduce unneeded operations when
       error or projection vectors equal zero. Addition
       of details concerning the "ellipsoid near point"
       problem and solution.

       Edited the header to comply with NAIF standard. Added examples'
       problem statement, and meta-kernel for code example #2. Updated code
       examples to produce formatted output and added cspice_kclear to code
       example #2.

       Added -Parameters, -Particulars, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

       Added arguments' type and size information in the -I/O section.

   -Icy Version 1.0.1, 16-DEC-2005 (EDW)

       Edits to 'alt' description in -I/O section.

   -Icy Version 1.0.0, 16-JUN-2003 (EDW)

Index_Entries


   distance from point to ellipsoid
   nearest point on an ellipsoid



Fri Dec 31 18:43:06 2021