Table of contents
Deprecated: This routine has been superseded by the Icy routine
cspice_subpnt. This routine is supported for purposes of
backward compatibility only.
CSPICE_SUBPT determines the coordinates of the sub-observer point
on a target body at a particular epoch, optionally corrected
for planetary (light time) and stellar aberration. The call also
returns the observer's altitude above the target body.
Given:
method the scalar string name of the computation method.
help, method
STRING = Scalar
The choices are:
'Near point' The sub-observer point is
defined as the nearest point on
the target relative to the
observer.
'Intercept' The sub-observer point is
defined as the target surface
intercept of the line
containing the observer and the
target's center.
In both cases, the intercept computation treats the
surface of the target body as a triaxial ellipsoid.
The ellipsoid's radii must be available in the kernel
pool.
Neither case nor white space are significant in
'method'. For example, the string ' NEARPOINT' is
valid.
target the scalar string name of the observed target body.
help, target
STRING = Scalar
'target' is case-insensitive, and leading and trailing blanks
in 'target' are not significant. Optionally, you may supply a
string containing the integer ID code for the object. For
example both 'MOON' and '301' are legitimate strings that
indicate the moon is the target body.
This routine assumes that the target body is modeled by
a tri-axial ellipsoid, and that a PCK file containing
its radii has been loaded into the kernel pool via
cspice_furnsh.
et the double precision scalar or N-vector of epochs in ephemeris
seconds past J2000 at which to compute the sub-observer point on
the target body.
help, et
DOUBLE = Scalar or DOUBLE = Array[N]
abcorr the scalar string name of the aberration corrections to apply
when computing the observer-target state.
help, abcorr
STRING = Scalar
'abcorr' may be any of the following.
'NONE' Apply no correction. Return the
geometric sub-observer point on the
target body.
'LT' Correct for planetary (light time)
aberration. Both the state and rotation
of the target body are corrected for
light time.
'LT+S' Correct for planetary (light time) and
stellar aberrations. Both the state and
rotation of the target body are
corrected for light time.
'CN' Converged Newtonian light time
correction. In solving the light time
equation, the 'CN' correction iterates
until the solution converges (three
iterations on all supported platforms).
Whether the 'CN+S' solution is
substantially more accurate than the
'LT' solution depends on the geometry
of the participating objects and on the
accuracy of the input data. In all
cases this routine will execute more
slowly when a converged solution is
computed. See the -Particulars section of
CSPICE_SPKEZR for a discussion of
precision of light time corrections.
Both the state and rotation of the target
body are corrected for light time.
'CN+S' Converged Newtonian light time correction
and stellar aberration correction.
Both the state and rotation of the
target body are corrected for light
time.
obsrvr the scalar string name of the observing body.
help, obsrvr
STRING = Scalar
This is typically a spacecraft, the earth, or a surface point
on the earth. 'obsrvr' is case-insensitive, and leading and
trailing blanks in 'obsrvr' are not significant. Optionally, you
may supply a string containing the integer ID code for the
object. For example both 'EARTH' and '399' are legitimate
strings that indicate the earth is the observer.
the call:
cspice_subpt, method, target, et, abcorr, obsrvr, spoint, alt
returns:
spoint a double precision 3-vector or 3xN array coordinates of the
'obsrvr' subpoint on 'target' at 'et' expressed relative to the
body-fixed frame of the target body.
help, spoint
DOUBLE = Array[3] or DOUBLE = Array[3,N]
The sub-observer point is defined either as the point
on the target body that is closest to the observer,
or the target surface intercept of the line from the
observer to the target's center; the input argument
'method' selects the definition to be used.
The body-fixed frame, which is time-dependent, is
evaluated at 'et' if 'abcorr' is 'NONE'; otherwise the
frame is evaluated at et-lt, where 'lt' is the one-way
light time from target to observer.
The state of the target body is corrected for
aberration as specified by 'abcorr'; the corrected
state is used in the geometric computation. As
indicated above, the rotation of the target is
retarded by one-way light time if 'abcorr' specifies
that light time correction is to be done.
alt the double precision, scalar or N-vector, altitude of 'obsrvr'
above 'target'.
help, alt
DOUBLE = Scalar or DOUBLE = Array[N]
When 'method' specifies a "near point" computation, 'alt' is
truly altitude in the standard geometric sense: the length of a
segment dropped from the observer to the target's surface, such
that the segment is perpendicular to the surface at the contact
point 'spoint'.
When 'method' specifies an "intercept" computation, 'alt'
is still the length of the segment from the observer
to the surface point 'spoint', but this segment in
general is not perpendicular to the surface.
None.
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.
1) Find the sub-point position of the Moon on the Earth at
epoch JAN 1, 2006 using the "near point" then the "intercept"
options. Apply light time correction to return apparent position.
Compute the distance between the location of the sub-points
computed using the two different options, and the angular
separation between their position vectors.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File name: subpt_ex1.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
pck00008.tpc Planet orientation and
radii
naif0009.tls Leapseconds
\begindata
KERNELS_TO_LOAD = ( 'de421.bsp',
'pck00008.tpc',
'naif0009.tls' )
\begintext
End of meta-kernel
Example code begins here.
PRO subpt_ex1
;;
;; Load kernels.
;;
cspice_furnsh, 'subpt_ex1.tm'
;;
;; Calculate the location of the sub-point of the Moon as
;; seen from Earth at epoch JAN 1, 2006.
;;
cspice_str2et, 'JAN 1, 2006', et
;;
;; First use option 'Near Point'
;;
cspice_subpt, 'near point', 'earth', et, 'lt+s', 'moon', $
point1, alt
print, 'Sub-point location coordinates - near point:'
print, FORMAT='(" ",3F15.8)', point1
print, 'Sub-point observer altitude:'
print, FORMAT='(" ",F15.8)', alt
print
;;
;; Now use option 'Intercept'
;;
cspice_subpt, 'intercept', 'earth', et, 'lt+s', 'moon', $
point2, alt2
print, 'Sub-point location coordinates - intercept:'
print, FORMAT='(" ",3F15.8)', point2
print, 'Sub-point observer altitude:'
print, FORMAT='(" ",F15.8)', alt2
print
;;
;; Calculate the Euclidean distance between the two locations
;; and the angular separation between the position vectors.
;;
dist = norm( point1 - point2)
sep = cspice_vsep(point1, point2 )*cspice_dpr();
print, FORMAT ='(A,F8.5)', $
'Distance between locations (km): ', dist
print, FORMAT ='(A,F8.5)', $
'Angular separation between locations (deg): ', sep
;;
;; 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:
Sub-point location coordinates - near point:
-5532.84459341 -1443.48674452 -2816.23526877
Sub-point observer altitude:
356091.70835039
Sub-point location coordinates - intercept:
-5525.64307897 -1441.60791159 -2831.19586108
Sub-point observer altitude:
356091.73073431
Distance between locations (km): 16.70961
Angular separation between locations (deg): 0.15020
Note that the difference between the location of the sub-points
computed using the two different options, results from the
non-spherical shape of the Earth.
cspice_subpt computes the sub-observer point on a target body.
(The sub-observer point is commonly called the sub-spacecraft
point when the observer is a spacecraft.) cspice_subpt also
determines the altitude of the observer above the target body.
There are two different popular ways to define the sub-observer
point: "nearest point on target to observer" or "target surface
intercept of line containing observer and target." These
coincide when the target is spherical and generally are distinct
otherwise.
When comparing sub-point computations with results from sources
other than SPICE, it's essential to make sure the same geometric
definitions are used.
If any of the listed errors occur, the output arguments are
left unchanged.
1) If the input argument `method' is not recognized, the error
SPICE(DUBIOUSMETHOD) is signaled by a routine in the call tree
of this routine.
2) If either of the input body names `target' or `obsrvr' cannot be
mapped to NAIF integer codes, the error SPICE(IDCODENOTFOUND)
is signaled by a routine in the call tree of this routine.
3) If `obsrvr' and `target' map to the same NAIF integer ID codes,
the error SPICE(BODIESNOTDISTINCT) is signaled by a routine in
the call tree of this routine.
4) If frame definition data enabling the evaluation of the state
of the target relative to the observer in target body-fixed
coordinates have not been loaded prior to calling cspice_subpt, an
error is signaled by a routine in the call tree of this
routine.
5) If the specified aberration correction is not recognized, an
error is signaled by a routine in the call tree of this
routine.
6) If insufficient ephemeris data have been loaded prior to
calling cspice_subpt, an error is signaled by a
routine in the call tree of this routine.
7) If the triaxial radii of the target body have not been loaded
into the kernel pool prior to calling cspice_subpt, an error is
signaled by a routine in the call tree of this routine.
8) If the size of the `target' body radii kernel variable is not
three, an error is signaled by a routine in the call tree of
this routine.
9) If any of the three `target' body radii is less-than or equal to
zero, an error is signaled by a routine in the call tree of
this routine.
10) If PCK data supplying a rotation model for the target body
have not been loaded prior to calling cspice_subpt, an error is
signaled by a routine in the call tree of this routine.
11) If any of the input arguments, `method', `target', `et',
`abcorr' or `obsrvr', is undefined, an error is signaled by
the IDL error handling system.
12) If any of the input arguments, `method', `target', `et',
`abcorr' or `obsrvr', is not of the expected type, or it does
not have the expected dimensions and size, an error is
signaled by the Icy interface.
13) If any of the output arguments, `spoint' or `alt', is not a
named variable, an error is signaled by the Icy interface.
Appropriate SPK, PCK, and frame kernels must be loaded
prior by the calling program before this routine is called.
The following data are required:
- SPK data: ephemeris data for target and observer must be
loaded. If aberration corrections are used, the states of
target and observer relative to the solar system barycenter
must be calculable from the available ephemeris data.
Typically ephemeris data are made available by loading one
or more SPK files via cspice_furnsh.
- PCK data: triaxial radii for the target body must be loaded
into the kernel pool. Typically this is done by loading a
text PCK file via cspice_furnsh.
- Further PCK data: rotation data for the target body must
be loaded. These may be provided in a text or binary PCK
file. Either type of file may be loaded via cspice_furnsh.
- Frame data: if a frame definition is required to convert
the observer and target states to the body-fixed frame of
the target, that definition must be available in the kernel
pool. Typically the definition is supplied by loading a
frame kernel via cspice_furnsh.
In all cases, kernel data are normally loaded once per program
run, NOT every time this routine is called.
None.
ICY.REQ
FRAMES.REQ
PCK.REQ
SPK.REQ
TIME.REQ
None.
N.J. Bachman (JPL)
J. Diaz del Rio (ODC Space)
B.V. Semenov (JPL)
E.D. Wright (JPL)
-Icy Version 1.1.4, 01-NOV-2021 (JDR)
Edited the -Examples section to comply with NAIF standard. Added
example's problem statement and meta-kernel. Reformatted
example's output and added call to cspice_kclear. Extended
-Particulars section.
Added -Parameters, -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.1.3, 10-JUL-2014 (NJB) (EDW)
Discussion of light time corrections was updated. Assertions
that converged light time corrections are unlikely to be
useful were removed.
Changed double quote delimiters of literal strings to single
quotes in comments.
-Icy Version 1.1.2, 18-MAY-2010 (BVS)
Index line now states that this routine is deprecated.
-Icy Version 1.1.1, 11-NOV-2008 (EDW)
Edits to header; -Abstract now states that this routine is
deprecated.
-Icy Version 1.1.0, 18-JUL-2005 (EDW)
Added capability to process vector 'et' as input returning
vectors 'spoint' and 'alt' as outputs.
-Icy Version 1.0.1, 16-JUN-2005 (EDW)
Reworked example and -I/O header comments.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
DEPRECATED sub-observer point
|