Table of contents
CSPICE_SPKPOS returns the position of a target body relative
to an observing body, optionally corrected for light time
(planetary aberration) and stellar aberration.
Given:
targ the name of a target body.
help, targ
STRING = Scalar
Optionally, you may supply the integer ID code for the object
as an integer string. For example both 'MOON' and '301' are
legitimate strings that indicate the moon is the target body.
The target and observer define a position vector
which points from the observer to the target.
et the ephemeris time, expressed as seconds past J2000 TDB, at
which the position of the target body relative to the observer
is to be computed, or an N-vector of times.
help, et
DOUBLE = Scalar or DOUBLE = Array[N]
`et' refers to time at the observer's location.
ref the name of the reference frame relative to which the output
position vector should be expressed.
help, ref
STRING = Scalar
This may be any frame supported by the SPICE system, including
built-in frames (documented in the Frames Required Reading) and
frames defined by a loaded frame kernel (FK).
When `ref' designates a non-inertial frame, the
orientation of the frame is evaluated at an epoch
dependent on the selected aberration correction. See
the description of the output position vector `ptarg'
for details.
abcorr indicates the aberration corrections to be applied to the
position of the target body to account for one-way light time
and stellar aberration.
help, abcorr
STRING = Scalar
See the discussion in the -Particulars section for
recommendations on how to choose aberration corrections.
`abcorr' may be any of the following:
'NONE' Apply no correction. Return the
geometric position 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 position 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
position obtained with the 'LT' option
to account for the observer's velocity
relative to the solar system
barycenter. The result is the apparent
position of the target---the position
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
position 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
position obtained with the 'XLT' option
to account for the observer's velocity
relative to the solar system
barycenter. The computed target
position 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.
Case and blanks are not significant in the string
`abcorr'.
obs the name of an observing body.
help, obs
STRING = Scalar
Optionally, you may supply the ID code of the object as an
integer string. For example, both 'EARTH' and '399' are
legitimate strings to supply to indicate the observer is Earth.
the call:
cspice_spkpos, targ, et, ref, abcorr, obs, ptarg, ltime
returns:
ptarg a Cartesian 3-vector representing the position of the target
body relative to the specified observer, or an N-vector of
vectors.
help, ptarg
DOUBLE = Array[3] or DOUBLE = Array[3,N]
`ptarg' is corrected for the specified aberrations, and is
expressed with respect to the reference frame specified by
`ref'. The three components of `ptarg' represent the x-, y- and
z-components of the target's position.
`ptarg' points from the observer's location at `et' to
the aberration-corrected location of the target.
Note that the sense of this position vector is
independent of the direction of radiation travel
implied by the aberration correction.
Units are always km.
Non-inertial frames are treated as follows: letting
`ltcent' be the one-way light time between the observer
and the central body associated with the frame, the
orientation of the frame is evaluated at et-ltcent,
et+ltcent, or `et' depending on whether the requested
aberration correction is, respectively, for received
radiation, transmitted radiation, or is omitted.
`ltcent' is computed using the method indicated by
`abcorr'.
ltime the one-way light time between the observer and target in
seconds, or an N-vector of times.
help, ltime
DOUBLE = Scalar or DOUBLE = Array[N]
If the target position is corrected for aberrations, then
`ltime' is the one-way light time between the observer and the
light time corrected target location.
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) Load a planetary SPK, and look up the position of Mars
as seen from the Earth in the J2000 frame with aberration
corrections 'LT+S' (ligth time plus stellar aberration) at
different epochs.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File: spkpos_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
--------- --------
de430.bsp Planetary ephemeris
mar097.bsp Mars satellite ephemeris
naif0011.tls Leapseconds
\begindata
KERNELS_TO_LOAD = ( 'de430.bsp',
'mar097.bsp',
'naif0011.tls' )
\begintext
End of meta-kernel
Example code begins here.
PRO spkpos_ex1
;;
;; Load a set of kernels: an SPK file, a PCK
;; file and a leapseconds file. Use a meta
;; kernel for convenience.
;;
cspice_furnsh, 'spkpos_ex1.tm'
;;
;; Define parameters for a position lookup:
;;
;; Return the position vector of Mars as seen from
;; Earth in the J2000 frame using aberration
;; correction LT+S (light time plus stellar aberration)
;; at the epoch July 4, 2003 11:00 AM PST.
;;
target = 'Mars'
epoch = 'July 4, 2003 11:00 AM PST'
frame = 'J2000'
abcorr = 'LT+S'
observer = 'Earth'
;;
;; Convert the epoch to ephemeris time.
;;
cspice_str2et, epoch, et
;;
;; Look-up the position for the defined parameters.
;;
cspice_spkpos, target, et, frame, abcorr, observer, $
ptarg, ltime
;;
;; Output...
;;
print, 'Scalar:'
print, 'The position of : ', target
print, 'As observed from : ', observer
print, 'In reference frame : ', frame
print, 'At epoch : ', epoch
;;
;; The first three entries of 'ptarg' contain the
;; X, Y, Z position components.
;;
print, 'R (kilometers) : ', ptarg[0:2]
print
print, 'Light time (secs) between observer and target: ', ltime
print
;;
;; Create a vector of et's, starting at 'epoch'
;; in steps of 100000 ephemeris seconds.
;;
SIZE = 5
vec_et = dindgen( SIZE )*100000.D + et
;;
;; Look up the 'ptarg' vectors and light time values
;; 'ltime' corresponding to the vector of input
;; ephemeris time 'vec_et'.
;;
cspice_spkpos, target , vec_et, frame, abcorr, $
observer, ptarg , ltime
print, 'Vector'
cspice_et2utc, vec_et, 'C', 3, vec_epoch
;;
;; When called with a vector 'et', cspice_spkpos returns
;; 'ptarg' as an 3xN matrix. Extract the ith position from
;; the matrix as:
;;
;; ptarg_i = ptarg[*,i]
;;
for i=0, 4 do begin
print, 'At epoch (UTC) : ', vec_epoch[i]
print, 'R (kilometers) : ', (ptarg[*,i])[0:2]
print, 'Light time (secs) : ', ltime[i]
print, ' between observer'
print, ' and target'
print
endfor
;;
;; 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:
Scalar:
The position of : Mars
As observed from : Earth
In reference frame : J2000
At epoch : July 4, 2003 11:00 AM PST
R (kilometers) : 73822235. -27127919. -18741306.
Light time (secs) between observer and target: 269.68988
Vector
At epoch (UTC) : 2003 JUL 04 19:00:00.000
R (kilometers) : 73822235. -27127919. -18741306.
Light time (secs) : 269.68988
between observer
and target
At epoch (UTC) : 2003 JUL 05 22:46:40.000
R (kilometers) : 73140185. -26390525. -18446763.
Light time (secs) : 266.56404
between observer
and target
At epoch (UTC) : 2003 JUL 07 02:33:20.000
R (kilometers) : 72456240. -25681031. -18163339.
Light time (secs) : 263.48035
between observer
and target
At epoch (UTC) : 2003 JUL 08 06:20:00.000
R (kilometers) : 71771127. -24999260. -17890947.
Light time (secs) : 260.43952
between observer
and target
At epoch (UTC) : 2003 JUL 09 10:06:40.000
R (kilometers) : 71085544. -24345021. -17629491.
Light time (secs) : 257.44220
between observer
and target
This routine is part of the user interface to the SPICE ephemeris
system. It allows you to retrieve position information for any
ephemeris object relative to any other in a reference frame that
is convenient for further computations.
This routine is identical in function to the routine cspice_spkezp
except that it allows you to refer to ephemeris objects by name
(via a character string).
Please refer to the Aberration Corrections Required Reading
abcorr.req for detailed information describing the nature and
calculation of the applied corrections.
1) If name of target or observer cannot be translated to its NAIF
ID code, the error SPICE(IDCODENOTFOUND) is signaled by a
routine in the call tree of this routine.
2) 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.
3) If the loaded kernels provide insufficient data to compute the
requested position vector, an error is signaled by a routine
in the call tree of this routine.
4) 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.
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, `ptarg' or `ltime', is not a
named variable, an error is signaled by the Icy interface.
This routine computes positions 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 position `ptarg' is to be expressed relative to a
non-inertial frame, or if any of the ephemeris data used to
compute `ptarg' 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 position. These additional kernels may be C-kernels,
PCK files or frame kernels. Any such kernels must already be
loaded at the time this routine is called.
None.
ABCORR.REQ
FRAMES.REQ
ICY.REQ
NAIF_IDS.REQ
SPK.REQ
TIME.REQ
None.
N.J. Bachman (JPL)
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.1.6, 02-NOV-2021 (JDR)
Edited the header to comply with NAIF standard. Added example's
problem statement and meta-kernel.
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.5, 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.1.4, 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.1.3, 07-NOV-2013 (EDW)
Added aberration algorithm explanation to -Particulars section.
-Icy Version 1.1.2, 22-DEC-2008 (EDW)
Header edits performed to improve argument descriptions.
These descriptions should now closely match the descriptions
in the corresponding CSPICE routine.
-Icy Version 1.1.1, 29-SEP-2007 (EDW)
Replaced the comment fragment in the -I/O section
"return with the same order"
with
"return with the same measure of vectorization"
-Icy Version 1.1.0, 12-SEP-2004 (EDW)
Added capability to process vector 'et' input
returning a matrix 'ptarg' and vector 'ltime'
on output.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
using names get target position relative to an observer
position relative to observer corrected for aberrations
read ephemeris data
read trajectory data
|