void subpt_c ( ConstSpiceChar * method,
ConstSpiceChar * target,
SpiceDouble et,
ConstSpiceChar * abcorr,
ConstSpiceChar * obsrvr,
SpiceDouble spoint [3],
SpiceDouble * alt )
Deprecated: This routine has been superseded by the CSPICE
routine subpnt_c. This routine is supported for purposes of
backward compatibility only.
Compute the rectangular coordinates of the sub-observer point on
a target body at a particular epoch, optionally corrected for
planetary (light time) and stellar aberration. Return these
coordinates expressed in the body-fixed frame associated with the
target body. Also, return the observer's altitude above the
target body.
FRAMES
PCK
SPK
TIME
GEOMETRY
Variable I/O Description
-------- --- --------------------------------------------------
method I Computation method.
target I Name of target body.
et I Epoch in ephemeris seconds past J2000 TDB.
abcorr I Aberration correction.
obsrvr I Name of observing body.
spoint O Sub-observer point on the target body.
alt O Altitude of the observer above the target body.
method is a short string specifying the computation method
to be used. 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 is the name of the target body. `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
furnsh_c.
et is the epoch in ephemeris seconds past J2000 at which
the sub-observer point on the target body is to be
computed.
abcorr indicates the aberration corrections to be applied
when computing the observer-target state. `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
spkezr_c 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 is the name of the observing body. 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.
spoint is the sub-observer point on the target body at `et'
expressed relative to the body-fixed frame of the
target body.
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 is the "altitude" of the observer above the target
body. 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.
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.
2) If either of the input body names `target' or `obsrvr' cannot be
mapped to NAIF integer codes, the error SPICE(IDCODENOTFOUND)
is signaled.
3) If `obsrvr' and `target' map to the same NAIF integer ID codes, the
error SPICE(BODIESNOTDISTINCT) is signaled.
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 subpt_c, the
error will be diagnosed and signaled by a routine in the call
tree of this routine.
5) If the specified aberration correction is not recognized, the
error will be diagnosed and signaled by a routine in the call
tree of this routine.
6) If insufficient ephemeris data have been loaded prior to
calling subpt_c, the error will be diagnosed and 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 subpt_c, the error will be
diagnosed and signaled by a routine in the call tree of this
routine.
8) The target must be an extended body: if any of the radii of
the target body are non-positive, the error will be diagnosed
and signaled by routines in the call tree of this routine.
9) If PCK data supplying a rotation model for the target body
have not been loaded prior to calling subpt_c, the error will be
diagnosed and signaled by a routine in the call tree of this
routine.
Appropriate SPK, PCK, and frame data must be available to
the calling program before this routine is called. Typically
the data are made available by loading kernels; however the
data may be supplied via subroutine interfaces if applicable.
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 furnsh_c.
- 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 furnsh_c.
- 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 furnsh_c
- 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 furnsh_c.
In all cases, kernel data are normally loaded once per program
run, NOT every time this routine is called.
subpt_c 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.) subpt_c 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.
The numerical results shown for this example may differ across
platforms. The results depend on the SPICE kernels used as
input, the compiler and supporting libraries, and the machine
specific arithmetic implementation.
In the following example program, the file
spk_m_031103-040201_030502.bsp
is a binary SPK file containing data for Mars Global Surveyor,
Mars, and the Sun for a time interval bracketing the date
2004 JAN 1 12:00:00 UTC.
pck00007.tpc is a planetary constants kernel file containing
radii and rotation model constants. naif0007.tls is a
leapseconds kernel.
Find the sub-observer point of the Mars Global Surveyor (MGS)
spacecraft on Mars for a specified time. Perform the computation
twice, using both the "intercept" and "near point" options.
#include <stdio.h>
#include "SpiceUsr.h"
int main ()
{
#define METHODLEN 25
SpiceChar method [2][METHODLEN] =
{
"Intercept", "Near point"
};
SpiceDouble alt;
SpiceDouble et;
SpiceDouble lat;
SpiceDouble lon;
SpiceDouble radius;
SpiceDouble spoint [3];
SpiceInt i;
/.
Load kernel files.
./
furnsh_c ( "naif0007.tls" );
furnsh_c ( "pck00007.tpc" );
furnsh_c ( "spk_m_031103-040201_030502.bsp" );
/.
Convert the UTC request time to ET (seconds past J2000 TDB).
./
str2et_c ( "2004 JAN 1 12:00:00", &et );
/.
Compute sub-spacecraft point using light time and stellar
aberration corrections. Use the "target surface intercept"
definition of sub-spacecraft point on the first loop
iteration, and use the "near point" definition on the
second.
./
for ( i = 0; i < 2; i++ )
{
subpt_c ( method[i],
"MARS", et, "LT+S",
"MGS", spoint, &alt );
/.
Convert rectangular coordinates to planetocentric
latitude and longitude. Convert radians to degrees.
./
reclat_c ( spoint, &radius, &lon, &lat );
lon *= dpr_c ();
lat *= dpr_c ();
/.
Write the results.
./
printf ( "\n"
"Computation method: %s\n"
"\n"
" Radius (km) = %25.15e\n"
" Planetocentric Latitude (deg) = %25.15e\n"
" Planetocentric Longitude (deg) = %25.15e\n"
" Altitude (km) = %25.15e\n"
"\n",
method[i],
radius,
lat,
lon,
alt );
}
return ( 0 );
}
When this program is executed, the output will be:
Computation method: Intercept
Radius (km) = 3.387970765126046e+03
Planetocentric Latitude (deg) = -3.970227239033073e+01
Planetocentric Longitude (deg) = -1.592266633611679e+02
Altitude (km) = 3.731735060549094e+02
Computation method: Near point
Radius (km) = 3.387984503271711e+03
Planetocentric Latitude (deg) = -3.966593293571449e+01
Planetocentric Longitude (deg) = -1.592266633611679e+02
Altitude (km) = 3.731666361282019e+02
None.
None.
C.H. Acton (JPL)
N.J. Bachman (JPL)
J.E. McLean (JPL)
-CSPICE Version 1.0.5, 10-JUL-2014 (NJB)
Discussion of light time corrections was updated. Assertions
that converged light time corrections are unlikely to be
useful were removed.
-CSPICE Version 1.0.4, 19-MAY-2010 (BVS)
Index line now states that this routine is deprecated.
-CSPICE Version 1.0.3, 07-FEB-2008 (NJB)
Abstract now states that this routine is deprecated.
-CSPICE Version 1.0.2, 22-JUL-2004 (NJB)
Updated header to indicate that the `target' and `observer'
input arguments can now contain string representations of
integers.
-CSPICE Version 1.0.1, 27-JUL-2003 (NJB) (CHA)
Various header corrections were made. The example program
was upgraded to use real kernels, and the program's output is
shown.
-CSPICE Version 1.0.0, 31-MAY-1999 (NJB) (JEM)
DEPRECATED sub-observer point
Link to routine subpt_c source file subpt_c.c
|