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

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


   CSPICE_NEARPT calculates the point on the surface of an
   ellipsoid nearest to a specified off-ellipsoid position.
   The routine also returns the altitude of the position
   above the ellipsoid

I/O


   Given:

      positn   the array(s) defining the Cartesian position of a point with
               respect to the center of an ellipsoid. 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.

               [3,n] = size(rectan); double = class(rectan)

      a,       
      b,
      c           values of the ellipsoid's triaxial radii ellipsoid, where:

                  'a' is length in kilometers of the semi-axis of the ellipsoid
                  parallel to the x-axis of the body-fixed reference frame.

                  [1,1] = size(a); double = class(a)

                  'b' is length in kilometers of the semi-axis of the ellipsoid
                  parallel to the y-axis of the body-fixed reference frame.

                  [1,1] = size(b); double = class(b)

                  'c' is length in kilometers of the semi-axis of the ellipsoid
                  parallel to the z-axis of the body-fixed reference frame.

                  [1,1] = size(c); double = class(c)

   the call:

      [ npoint, alt ] = cspice_nearpt( positn, a, b, c )

   returns:

      npoint   the array(s) defining the location on the ellipsoid closest
               to 'positn'.

               [3,n] = size(npoint); double = class(npoint)

      alt      the value(s) of the altitudes of 'positn' above the ellipsoid.
               If 'positn' is inside the ellipsoid, 'alt' will be negative
               and have magnitude equal to the distance between 'pos' and
               'positn'.

               [1,n] = size(alt); double = class(alt)

               'npoint' and 'alt' return with the same vectorization
               measure, N, as 'positn'.

Examples


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

      Example(1):

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

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

   MATLAB outputs:

      pnear =

           1
           0
           0

      alt =

         2.50000000000000

      Example(2):

      %
      % Load a meta kernel containing SPK and leapseconds kernels.
      %
      cspice_furnsh( 'standard.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.;
      abcorr      = 'LT+S';
      [pos,ltime] = cspice_spkpos( 'moon', epoch, 'IAU_EARTH', ...
                                    abcorr, 'earth');

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

      %
      % Now calculate the point on the Earth nearest to the Moon
      % given LT+S aberration correction at the epoch time.
      %
      [npoint,alt]= cspice_nearpt( pos, radii(1), radii(2), radii(3) )


   MATLAB outputs:

      npoint =

         1.0e+03 *

         3.34708386495926
        -5.29453888129091
        -1.19828126398311

      alt =

         3.960372197033597e+05

Particulars


   A sister version of this routine exists named mice_nearpt that returns
   the output arguments as fields in a single structure.

Required Reading


   For important details concerning this module's function, please refer to
   the CSPICE routine nearpt_c.

   MICE.REQ

Version


   -Mice Version 1.0.1, 03-DEC-2014, EDW (JPL)

       Edited I/O section to conform to NAIF standard for Mice documentation.

   -Mice Version 1.0.0, 21-DEC-2005, EDW (JPL)

Index_Entries


   distance from point to ellipsoid
   nearest point on an ellipsoid


Wed Apr  5 18:00:33 2017