Table of contents
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.
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'.
None.
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
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.
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.
None.
See -Exceptions section.
ICY.REQ
ELLIPSES.REQ
None.
N.J. Bachman (JPL)
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-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)
distance from point to ellipsoid
nearest point on an ellipsoid
|