CSPICE_NEARPT calculates the point on the surface of an
ellipsoid nearest to a specified offellipsoid position.
The routine also returns the altitude of the position
above the ellipsoid
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 bodyfixed reference frame. The semiaxes of the
ellipsoid are aligned with the x, y, and zaxes of the
bodyfixed 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 semiaxis of the ellipsoid
parallel to the xaxis of the bodyfixed reference frame.
[1,1] = size(a); double = class(a)
'b' is length in kilometers of the semiaxis of the ellipsoid
parallel to the yaxis of the bodyfixed reference frame.
[1,1] = size(b); double = class(b)
'c' is length in kilometers of the semiaxis of the ellipsoid
parallel to the zaxis of the bodyfixed 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'.
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 Earthfixed
% 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
A sister version of this routine exists named mice_nearpt that returns
the output arguments as fields in a single structure.
For important details concerning this module's function, please refer to
the CSPICE routine nearpt_c.
MICE.REQ
Mice Version 1.0.1, 03DEC2014, EDW (JPL)
Edited I/O section to conform to NAIF standard for Mice documentation.
Mice Version 1.0.0, 21DEC2005, EDW (JPL)
distance from point to ellipsoid
nearest point on an ellipsoid
