Table of contents
CSPICE_SPKEZ returns the state (position and velocity) of a
target body relative to an observing body, optionally corrected
for light time (planetary aberration) and stellar aberration.
Given:
targ the scalar NAIF integer ID code for a target body.
help, targ
LONG = Scalar
The target and observer define a state vector
whose position component points from the observer
to the target.
et the scalar double precision ephemeris time, expressed as seconds
past J2000 TDB, at which the state of the target body relative
to the observer is to be computed, `et' refers to time at the
observer's location.
help, et
DOUBLE = Scalar
ref the scalar string name of the reference frame relative to which
the output state vector should be expressed.
help, ref
STRING = Scalar
abcorr a scalar string that indicates the aberration corrections to
apply to the state of the target body to account for one-way
light time and stellar aberration.
help, abcorr
STRING = Scalar
`abcorr' may be any of the following:
'NONE' Apply no correction. Return the
geometric state of the target body
relative to the observer.
The following values of `abcorr' apply to the
"reception" case in which photons depart from the
target's location at the light-time corrected epoch
et-ltime and *arrive* at the observer's location at
`et':
'LT' Correct for one-way light time (also
called "planetary aberration") using a
Newtonian formulation. This correction
yields the state of the target at the
moment it emitted photons arriving at
the observer at `et'.
The light time correction uses an
iterative solution of the light time
equation (see -Particulars for details).
The solution invoked by the "LT" option
uses one iteration.
'LT+S' Correct for one-way light time and
stellar aberration using a Newtonian
formulation. This option modifies the
state obtained with the "LT" option to
account for the observer's velocity
relative to the solar system
barycenter. The result is the apparent
state of the target---the position and
velocity of the target as seen by the
observer.
'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
below for a discussion of precision of
light time corrections.
'CN+S' Converged Newtonian light time
correction and stellar aberration
correction.
The following values of `abcorr' apply to the
"transmission" case in which photons *depart* from
the observer's location at `et' and arrive at the
target's location at the light-time corrected epoch
et+ltime:
'XLT' "Transmission" case: correct for
one-way light time using a Newtonian
formulation. This correction yields the
state of the target at the moment it
receives photons emitted from the
observer's location at `et'.
'XLT+S' "Transmission" case: correct for
one-way light time and stellar
aberration using a Newtonian
formulation This option modifies the
state obtained with the "XLT" option to
account for the observer's velocity
relative to the solar system
barycenter. The position component of
the computed target state indicates the
direction that photons emitted from the
observer's location must be "aimed" to
hit the target.
'XCN' "Transmission" case: converged
Newtonian light time correction.
'XCN+S' "Transmission" case: converged Newtonian
light time correction and stellar
aberration correction.
Neither special nor general relativistic effects are
accounted for in the aberration corrections applied
by this routine.
Both letter case and embedded blanks are not significant
in the `abcorr' string.
obs the scalar NAIF integer ID code for an observing body.
help, obs
LONG = Scalar
the call:
cspice_spkez, targ, et, ref, abcorr, obs, starg, ltime
returns:
starg a double precision Cartesian 6-vector representing the position
in kilometers and velocity in kilometers-per-second of the
target body relative to the specified observer, (the first three
components of `starg' represent the x-, y- and z-components of
the target's position; the last three components form the
corresponding velocity vector).
help, starg
DOUBLE = Array[6]
ltime the scalar, double precision one-way light time between the
observer and target in seconds; if the target state is corrected
for aberrations, then 'ltime' is the one-way light time between
the observer and the light time corrected target location.
help, ltime
DOUBLE = Scalar
Please note, CSPICE documentation and source code
uniformly uses the variable name "lt" to designate
the light-time between an observer and target. IDL
uses "lt" as the less-than numeric comparison
operator and so does not allow "lt" as a variable name.
Therefore, Icy documentation uses the name `ltime'
for the light-time value.
Note: NAIF recommends the use of cspice_spkezr over the use of
cspice_spkez.
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) Return the state vector of Mars (499) as seen from
Earth (399) in the J2000 frame using aberration
correction LT+S (light time plus stellar aberration)
at the epoch July 4, 2003 11:00 AM PST.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File name: spkez_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
pck00009.tpc Planet orientation and
radii
naif0009.tls Leapseconds
\begindata
KERNELS_TO_LOAD = ( 'de421.bsp',
'pck00009.tpc',
'naif0009.tls' )
\begintext
End of meta-kernel
Example code begins here.
PRO spkez_ex1
;;
;; Load a set of kernels: an SPK file, a PCK
;; file and a leapseconds file. Use a meta
;; kernel for convenience.
;;
cspice_furnsh, 'spkez_ex1.tm'
;;
;; Define parameters for a state lookup:
;;
target = 499
epoch = 'July 4, 2003 11:00 AM PST'
frame = 'J2000'
abcorr = 'LT+S'
observer = 399
;;
;; Convert the epoch to ephemeris time.
;;
cspice_str2et, epoch, et
;;
;; Look-up the state for the defined parameters.
;;
cspice_spkez, target, et, frame, abcorr, observer, $
state, ltime
;;
;; Output...
;;
print, 'The position of : ', target
print, 'As observed from : ', observer
print, 'In reference frame : ', frame
print, 'At epoch : ', epoch
print
;;
;; The first three entries of state contain the
;; X, Y, Z position components. The final three contain
;; the Vx, Vy, Vz velocity components.
;;
print, FORMAT='(A,3F18.6)', 'R (km): ', state[0:2]
print, FORMAT='(A,3F18.6)', 'V (km/s): ', state[3:5]
print
print, 'Light time (s) between observer and target: ', ltime
;;
;; 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:
The position of : 499
As observed from : 399
In reference frame : J2000
At epoch : July 4, 2003 11:00 AM PST
R (km): 73822235.331161 -27127919.178593 -18741306.284864
V (km/s): -6.808513 7.513996 3.001299
Light time (s) between observer and target: 269.68988
Please refer to the Aberation Corrections Required Reading (abcorr.req)
for detailed information describing the nature and calculation of the
applied corrections.
1) If the reference frame `ref' is not a recognized reference
frame, the error SPICE(UNKNOWNFRAME) is signaled by a routine
in the call tree of this routine.
2) If the loaded kernels provide insufficient data to compute the
requested state vector, an error is signaled by a routine in
the call tree of this routine.
3) If an error occurs while reading an SPK or other kernel file,
the error is signaled by a routine in the call tree
of this routine.
4) If any of the required attributes of the reference frame `ref'
cannot be determined, the error SPICE(UNKNOWNFRAME2) is
signaled by a routine in the call tree of this routine.
5) If any of the input arguments, `targ', `et', `ref', `abcorr'
or `obs', is undefined, an error is signaled by the IDL error
handling system.
6) If any of the input arguments, `targ', `et', `ref', `abcorr'
or `obs', is not of the expected type, or it does not have the
expected dimensions and size, an error is signaled by the Icy
interface.
7) If any of the output arguments, `starg' or `ltime', is not a
named variable, an error is signaled by the Icy interface.
This routine computes states using SPK files that have been loaded into
the SPICE system, normally via the kernel loading interface routine
cspice_furnsh. See the routine cspice_furnsh and the SPK and KERNEL
Required Reading for further information on loading (and unloading)
kernels.
If the output state `starg' is to be expressed relative to a
non-inertial frame, or if any of the ephemeris data used to
compute `starg' are expressed relative to a non-inertial frame in
the SPK files providing those data, additional kernels may be
needed to enable the reference frame transformations required to
compute the state. Normally these additional kernels are PCK
files or frame kernels. Any such kernels must already be loaded
at the time this routine is called.
None.
ICY.REQ
ABCORR.REQ
SPK.REQ
NAIF_IDS.REQ
FRAMES.REQ
TIME.REQ
None.
N.J. Bachman (JPL)
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.4, 10-AUG-2021 (JDR)
Edited the header to comply with NAIF standard. Added example's
problem statement and meta-kernel. Reformatted example's
output and added call to cspice_kclear.
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.0.3, 22-DEC-2015 (EDW)
Corrected typo in -Version section. The 07-NOV-2013
version entry lacked a version ID.
Particulars updated to refer to Aberration Corrections
Required Reading document.
-Icy Version 1.0.2, 07-JUL-2014 (NJB) (EDW)
Discussion of light time corrections was updated. Assertions
that converged light time corrections are unlikely to be
useful were removed.
-Icy Version 1.0.1, 07-NOV-2013 (EDW)
Added aberration algorithm explanation to -Particulars section.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
using body codes get target state relative to an observer
get state relative to observer corrected for aberrations
read ephemeris data
read trajectory data
|