Table of contents
Deprecated: This routine has been superseded by the Icy routine
cspice_sincpt. This routine is supported for purposes of
backward compatibility only.
CSPICE_SRFXPT computes the surface intercept point of a specified ray
on a target body at a specified epoch, optionally corrected for light
time and stellar aberration, given an observer and a direction vector
defining a ray.
Given:
method a short string providing parameters defining the computation
method to be used.
help, method
STRING = Scalar
-Parameters include, but are not limited to, the shape model
used to represent the surface of the target body.
The only choice currently supported is
'Ellipsoid' The intercept computation uses
a triaxial ellipsoid to model
the surface of the target body.
The ellipsoid's radii must be
available in the kernel pool.
Neither case nor white space are significant in
`method'. For example, the string ' eLLipsoid ' is
valid.
In a later Toolkit release, this argument will be
used to invoke a wider range of surface
representations. For example, it will be possible to
represent the target body's surface using a digital
model.
target the name of the 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.
When the target body's surface is represented by a
tri-axial ellipsoid, this routine assumes that a
kernel variable representing the ellipsoid's radii is
present in the kernel pool. Normally the kernel
variable would be defined by loading a PCK file.
et the epoch of participation of the observer, expressed as
ephemeris seconds past J2000 TDB: `et' is the epoch at which the
observer's state is computed, or an N-vector of epochs.
help, et
DOUBLE = Scalar or DOUBLE = Array[N]
When aberration corrections are not used, `et' is also
the epoch at which the state and orientation of the
target body are computed.
When aberration corrections are used, `et' is the epoch
at which the observer's state relative to the solar
system barycenter is computed; in this case the
position and orientation of the target body are
computed at et-ltime or et+ltime, where `ltime' is the one-way
light time between the intercept point and the
observer, and the sign applied to `ltime' depends on the
selected correction. See the description of `abcorr'
below for details.
abcorr indicates the aberration correction to be applied when computing
the observer-target state and the orientation of the target
body.
help, abcorr
STRING = Scalar
`abcorr' may be any of the following.
'NONE' Apply no correction. Return the
geometric surface intercept point on the
target body.
Let `ltime' represent the one-way light time between the
observer and the surface intercept point (note: NOT
between the observer and the target body's center).
The following values of `abcorr' apply to the
"reception" case in which photons depart from the
intercept point'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 location of the surface
intercept point 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. The solution invoked by the
'LT' option uses one iteration.
Both the target state as seen by the
observer, and rotation of the target
body, are corrected for light time.
'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
surface intercept point 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. Both the
state and rotation of the target body
are corrected for light time.
'CN+S' Converged Newtonian light time
and stellar aberration corrections.
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
intercept point 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
intercept location at the moment it
receives photons emitted from the
observer's location at `et'.
The light time correction uses an
iterative solution of the light time
equation. The solution invoked by the
'LT' option uses one iteration.
Both the target state as seen by the
observer, and rotation of the target
body, are corrected for light time.
'XLT+S' "Transmission" case: correct for
one-way light time and stellar
aberration using a Newtonian
formulation This option modifies the
intercept obtained with the 'XLT'
option to account for the observer's
velocity relative to the solar system
barycenter.
'XCN' Converged Newtonian light time
correction. This is the same as XLT
correction but with further iterations
to a converged Newtonian light time
solution.
'XCN+S' "Transmission" case: converged
Newtonian light time and stellar
aberration corrections.
obsrvr the 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 'MOON' and '301' are legitimate strings
that indicate the moon is the observer.
dref the name of the reference frame relative to which the input
direction vector is expressed.
help, dref
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 `dref' designates a non-inertial frame, the
orientation of the frame is evaluated at an epoch
dependent on the frame's center and, if the center is
not the observer, on the selected aberration
correction. See the description of the direction
vector `dvec' for details.
dvec Pointing vector emanating from the observer.
help, dvec
DOUBLE = Array[3]
The intercept with the target body's surface of the ray defined
by the observer and `dvec' is sought.
`dvec' is specified relative to the reference frame
designated by `dref'.
Non-inertial reference frames are treated as follows:
if the center of the frame is at the observer's
location, the frame is evaluated at `et'. If the
frame's center is located elsewhere, then 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'.
the call:
cspice_srfxpt, method, target, et, abcorr, obsrvr, dref, $
dvec, spoint, dist, trgepc, obspos, found
returns:
spoint the surface intercept point on the target body of the ray
defined by the observer and the direction vector, or an
N-vector of points.
help, spoint
DOUBLE = Array[3] or DOUBLE = Array[3,N]
If the ray intersects the target body in multiple points, the
selected intersection point is the one closest to the observer.
The output argument `found' (see below) indicates whether an
intercept was found.
`spoint' is expressed in Cartesian coordinates,
relative to the body-fixed frame associated with the
target body. The body-fixed target frame is
evaluated at the intercept epoch `trgepc' (see
description below).
When light time correction is used, the duration of
light travel between `spoint' to the observer is
considered to be the one way light time. When both
light time and stellar aberration corrections are
used, `spoint' is selected such that, when `spoint' is
corrected for light time and the vector from the
observer to the light-time corrected location of
`spoint' is corrected for stellar aberration, the
resulting vector is parallel to the ray defined by
the observer's location and `dvec'.
The components of `spoint' are given in units of km.
dist the distance between the observer and the surface intercept on
the target body, or an N-vector of distances.
help, dist
DOUBLE = Scalar or DOUBLE = Array[N]
`dist' is given in units of km.
trgepc the "intercept epoch", or an N-vector of epochs.
help, trgepc
DOUBLE = Scalar or DOUBLE = Array[N]
This is the epoch at which the ray defined by `obsrvr' and
`dvec' intercepts the target surface at `spoint'. `trgepc' is
defined as follows: letting `ltime' be the one-way light time
between the observer and the intercept point, `trgepc' is the
epoch et-ltime, et+ltime, or `et' depending on whether the
requested aberration correction is, respectively, for received
radiation, transmitted radiation, or omitted. `ltime' is
computed using the method indicated by `abcorr'.
`trgepc' is expressed as seconds past J2000 TDB.
obspos the vector from the center of the target body at epoch `trgepc'
to the observer at epoch `et', or an N-vector of vectors.
help, obspos
DOUBLE = Array[3] or DOUBLE = Array[3,N]
`obspos' is expressed in the target body-fixed reference frame
evaluated at `trgepc'. (This is the frame relative to which
`spoint' is given.)
`obspos' is returned to simplify various related
computations that would otherwise be cumbersome. For
example, the vector `xvec' from the observer to `spoint'
can be calculated via
xvec = spoint - obspos
The components of `obspos' are given in units of km.
found a logical flag indicating whether or not the ray intersects the
target, or an N-vector of flags.
help, found
BOOLEAN = Scalar or BOOLEAN = Array[N]
If an intersection exists `found' will be returned as True. If
the ray misses the target, `found' will be returned as False
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) The following program computes surface intercept points on
Mars for the boresight and FOV boundary vectors of the MGS MOC
narrow angle camera. The intercepts are computed for a single
observation epoch. Light time and stellar aberration
corrections are used. For simplicity, camera distortion is
ignored.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File: srfxpt_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
--------- --------
de405s.bsp Planetary ephemeris
mars_iau2000_v0.tpc Planet orientation and
radii
naif0011.tls Leapseconds
mgs_moc_v20.ti MGS MOC instrument
parameters
mgs_sclkscet_00061.tsc MGS SCLK coefficients
mgs_sc_ext12.bc MGS s/c bus attitude
mgs_ext12_ipng_mgs95j.bsp MGS ephemeris
\begindata
KERNELS_TO_LOAD = ( 'de405s.bsp',
'mars_iau2000_v0.tpc',
'naif0011.tls',
'mgs_moc_v20.ti',
'mgs_sclkscet_00061.tsc',
'mgs_sc_ext12.bc',
'mgs_ext12_ipng_mgs95j.bsp' )
\begintext
End of meta-kernel
Example code begins here.
PRO srfxpt_ex1
;;
;; Assign needed constants.
;;
BUSID = -94000
MGS = -94
NCORNR = 4
ABCORR = 'LT+S'
CAMERA = 'MGS_MOC_NA'
DREF = 'J2000'
METHOD = 'ELLIPSOID'
OBSRVR = 'MGS'
TARGET = 'MARS'
UTC = '2003 OCT 13 06:00:00 UTC'
;;
;; Load kernel files.
;;
cspice_furnsh, 'srfxpt_ex1.tm'
;;
;; Convert the UTC request time to ET (seconds past
;; J2000, TDB).
;;
cspice_str2et, UTC, et
;;
;; Get the MGS MOC Narrow angle camera (MGS_MOC_NA)
;; ID code. Then look up the field of view (FOV)
;; parameters.
;;
cspice_bodn2c, camera, camid, found
if ( NOT found ) then begin
print, 'Could not find ID code for instrument ' + camera
stop
endif
cspice_getfov, camid, NCORNR, shape, dref, bsight, bounds
print
print, 'Surface Intercept Locations for Camera'
print, 'FOV Boundary and Boresight Vectors'
print
print, ' Instrument: ' + CAMERA
print, ' Epoch: ' + UTC
print, ' Aberration correction: ' + ABCORR
print
;;
;; Now compute and display the surface intercepts for the
;; boresight and all of the FOV boundary vectors.
;;
for i = 0, NCORNR do begin
if ( i LT NCORNR ) then begin
;;
;; `bounds' represents a 3 X NCORNR array with each row a bounds
;; vector. Extract the vectors from `bounds' using as a vector
;; segment.
;;
;; corner vector 0: bounds[0:2]
;; corner vector 1: bounds[3:5]
;; corner vector 2: bounds[6:10]
;; corner vector 3: bounds[9:11]
;;
;; Recall an IDL matrix is also a vector.
;;
title = 'Corner vector ' + string(i)
dvec = bounds[ 3*i: (3*i)+2 ]
endif else begin
title = 'Boresight vector'
dvec = bsight
endelse
;;
;; Compute the surface intercept point using
;; the specified aberration corrections.
;;
cspice_srfxpt, METHOD, TARGET, et, ABCORR, $
OBSRVR, dref, dvec, spoint, $
dist, trgepc, obspos, found
if ( found ) then begin
;;
;; Convert rectangular coordinates to planetocentric
;; latitude and longitude. Convert radians to degrees.
;;
cspice_reclat, spoint, radius, lon, lat
lon = lon * cspice_dpr()
lat = lat * cspice_dpr()
;;
;; Display the results.
;;
print, title
print
print, ' Vector in ' + dref + ' frame = '
if ( i LT NCORNR ) then begin
print, FORMAT='(3E18.10)', bounds[ 3*i: (3*i)+2 ]
endif else begin
print, bsight
endelse
print
print, ' Intercept:'
print
print, FORMAT='(A38,E18.10)', $
' Radius (km) = ', radius
print, FORMAT='(A38,E18.10)', $
' Planetocentric Latitude (deg) = ', lat
print, FORMAT='(A38,E18.10)', $
' Planetocentric Longitude (deg) = ', lon
print, FORMAT='(A38,E18.10)', $
' Range (km) = ', dist
print
endif else begin
print, 'Intercept not found.'
endelse
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:
Surface Intercept Locations for Camera
FOV Boundary and Boresight Vectors
Instrument: MGS_MOC_NA
Epoch: 2003 OCT 13 06:00:00 UTC
Aberration correction: LT+S
Corner vector 0
Vector in MGS_MOC_NA frame =
1.8571383810E-06 -3.8015622659E-03 9.9999277403E-01
Intercept:
Radius (km) = 3.3849411359E+03
Planetocentric Latitude (deg) = -4.8477481852E+01
Planetocentric Longitude (deg) = -1.2347407883E+02
Range (km) = 3.8898310725E+02
Corner vector 1
Vector in MGS_MOC_NA frame =
1.8571383810E-06 3.8015622659E-03 9.9999277403E-01
Intercept:
Radius (km) = 3.3849396988E+03
Planetocentric Latitude (deg) = -4.8481636267E+01
Planetocentric Longitude (deg) = -1.2339882275E+02
Range (km) = 3.8897512490E+02
Corner vector 2
Vector in MGS_MOC_NA frame =
-1.8571383810E-06 3.8015622659E-03 9.9999277403E-01
Intercept:
Radius (km) = 3.3849396899E+03
Planetocentric Latitude (deg) = -4.8481661837E+01
Planetocentric Longitude (deg) = -1.2339882596E+02
Range (km) = 3.8897466598E+02
Corner vector 3
Vector in MGS_MOC_NA frame =
-1.8571383810E-06 -3.8015622659E-03 9.9999277403E-01
Intercept:
Radius (km) = 3.3849411271E+03
Planetocentric Latitude (deg) = -4.8477507428E+01
Planetocentric Longitude (deg) = -1.2347408199E+02
Range (km) = 3.8898264817E+02
Boresight vector
Vector in MGS_MOC_NA frame =
0.0000000 0.0000000 1.0000000
Intercept:
Radius (km) = 3.3849404102E+03
Planetocentric Latitude (deg) = -4.8479579751E+01
Planetocentric Longitude (deg) = -1.2343645375E+02
Range (km) = 3.8897573918E+02
2) Calculate the intercept point of the look vector in the DAWN_VIR
frame on Vesta as seen from Dawn for several epochs between
November 15, 2011 and November 20, 2011.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File: srfxpt_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
sb_vesta_ssd_120716.bsp Vesta ephemeris
naif0012.tls Leapseconds
dawn_vesta_v00.tf Vesta body-fixed
reference frame
dawn_vesta_v06.tpc Vesta orientation and
radii
dawn_rec_111102_111210_120618_v1.bsp DAWN ephemeris
dawn_v13.tf DAWN FK
dawn_sc_111114_111120.bc DAWN s/c bus attitude
dawn_203_sclkscet_00029.tsc DAWN SCLK coefficients
\begindata
KERNELS_TO_LOAD = ( 'de421.bsp',
'sb_vesta_ssd_120716.bsp',
'dawn_v13.tf',
'dawn_vesta_v00.tf',
'naif0012.tls',
'dawn_vesta_v06.tpc',
'dawn_rec_111102_111210_120618_v1.bsp',
'dawn_sc_111114_111120.bc',
'dawn_203_sclkscet_00029.tsc' )
\begintext
End of meta-kernel
Example code begins here.
PRO srfxpt_ex2
;;
;; Load the Dawn Mission specific meta kernel. This meta kernel
;; lists the Vesta spk and the dynamic frames kernel defining
;; the DAWN_NADIR and VESTA_FIXED reference frame.
;;
cspice_furnsh, 'srfxpt_ex2.tm'
;; Define a start and stop time for the search.
;;
cspice_str2et, '2011 NOV 15 00:00:00.000 TDB', et0
cspice_str2et, '2011 NOV 20 00:00:00.000 TDB', et1
;;
;; Set the number of intervals for the search, calculate
;; the time step corresponding to the interval.
;;
interval = 5
step = (et1 - et0)/double(interval)
;;
;; Create the vector of epochs using `step' seconds between
;; each element.
;;
et_vec = dindgen(interval)*step + et0
;;
;; Set the epoch vector to begin one step after
;; the earliest time available from the SPK, this prevents
;; any data not found errors due to LT corrections.
;;
et = et_vec[1:interval-1]
;;
;; The boresight in the DAWN_VIR frame is (0,0,1).
;; Define that vector.
dvec = [0.d, 0., 1. ]
r2d = cspice_dpr()
;;
;; Convert the time vector to UTC.
;;
cspice_et2utc, et, 'C', 3, utc
;;
;; Now calculate the intercept point of the look vector in the
;; DAWN_VIR frame on Vesta as seen from Dawn. The frame defines
;; (0,0,1) as the look vector. `trgepc' returns the `et'
;; corresponding to the time of evaluation of the body fixed
;; frame corresponding to the intercept event
;; (et > trgepc).
;;
cspice_srfxpt, 'Ellipsoid', 'Vesta', et, 'CN', 'Dawn', 'DAWN_VIR', $
dvec, spoint, dist, trgepc, obspos, found
print, FORMAT='(A24, 4A10 )', 'UTC', 'X', 'Y', 'Z'
for i=0, n_elements( et )-1 do begin
print, FORMAT='(A24, 4F10.4 )', utc[i], obspos[*,i]
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:
UTC X Y Z
2011 NOV 15 23:58:53.817 111.7988 -200.3704 -557.0932
2011 NOV 16 23:58:53.817 -234.7547 372.1653 -403.8051
2011 NOV 17 23:58:53.817 -180.7074 246.6719 394.4379
2011 NOV 18 23:58:53.817 -348.2542 417.8579 80.3122
3) cspice_srfxpt signals an error if required kernel data are
unavailable: for example, in the program of Example 1, if the
C-kernel containing data for the MGS bus had a gap at epoch `et',
cspice_srfxpt would be unable to transform the direction vector `dvec'
from the reference frame fixed to the camera to the reference
frame fixed to the target body.
We could modify the code of Example 1 as shown below to test for
the availability of C-kernel data. We would add the declarations
shown, and we'd call the C-kernel reader cspice_ckgp to find whether the
desired pointing was available. Depending on the value of the
`found' flag returned by cspice_ckgp, we'd go on to compute the surface
intercept point or respond to the error condition.
... declaration code, cspice_str2et call ....
;;
;; Look up the transformation from the J2000 frame to the
;; MGS spacecraft frame. To do this, we'll need to represent
;; our observation epoch in terms of MGS encoded SCLK.
;;
cspice_sce2c, MGS, et, sclkdp
;;
;; Look up the spacecraft attitude from the C-kernel.
;;
cspice_ckgp, BUSID, sclkdp, 0.d, 'J2000', cmat, clkout, found
if ( found ) then begin
... Proceed to compute intercept point ....
endif else begin
... Handle case where pointing is unavailable for the
epoch of interest...
else
Given a ray defined by a direction vector and the location of an
observer, cspice_srfxpt computes the surface intercept point of the ray
on a specified target body. cspice_srfxpt also determines the distance
between the observer and the surface intercept point.
When aberration corrections are used, this routine finds the
value of `spoint' such that, if `spoint' is regarded as an ephemeris
object, after the selected aberration corrections are applied to
the vector from the observer to `spoint', the resulting vector is
parallel to the direction vector `dvec'.
This routine computes light time corrections using light time
between the observer and the surface intercept point, as opposed
to the center of the target. Similarly, stellar aberration
corrections done by this routine are based on the direction of
the vector from the observer to the light-time corrected
intercept point, not to the target center. This technique avoids
errors due to the differential between aberration corrections
across the target body. Therefore it's valid to use aberration
corrections with this routine even when the observer is very
close to the intercept point, in particular when the
observer-intercept point distance is much less than the
observer-target center distance. It's also valid to use stellar
aberration corrections even when the intercept point is near or
on the limb (as may occur in occultation computations using a
point target).
When comparing surface intercept 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, an error
is signaled by a routine in the call tree of this
routine.
2) If `target' cannot be mapped to an ID code, the error
SPICE(IDCODENOTFOUND) is signaled by a routine in the call
tree of this routine.
3) If `obsrvr' cannot be mapped to an ID code, an error is signaled
by a routine in the call tree of this routine.
4) If the input argument `abcorr' is invalid, an error
is signaled by a routine in the call tree of this
routine.
5) If a body-fixed reference frame associated with the target
cannot be found, the error SPICE(NOFRAME) is signaled by a
routine in the call tree of this routine.
6) If `obsrvr' and `target' map to the same NAIF integer ID codes, an
error is signaled by a routine in the call tree of this
routine.
7) 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_srfxpt, an
error is signaled by a routine in the call tree of this
routine.
8) If the specified aberration correction is not recognized, an
error is signaled by a routine in the call tree of this
routine.
9) If insufficient ephemeris data have been loaded prior to
calling cspice_srfxpt, an error is signaled by a
routine in the call tree of this routine. Note that when
light time correction is used, sufficient ephemeris data
must be available to propagate the states of both observer
and target to the solar system barycenter.
10) If the computation method has been specified as "Ellipsoid"
and triaxial radii of the target body have not been loaded
into the kernel pool prior to calling cspice_srfxpt, an error is
signaled by a routine in the call tree of this routine.
11) If PCK data needed to define the target body-fixed frame have
not been loaded prior to calling cspice_srfxpt, an error is signaled
by a routine in the call tree of this routine.
12) If the reference frame designated by `dref' is not recognized
by the SPICE frame subsystem, an error is signaled
by a routine in the call tree of this routine.
13) If the direction vector `dvec' is the zero vector, an error
is signaled by a routine in the call tree of this routine.
14) If radii for `target' are not found in the kernel pool, an error
is signaled by a routine in the call tree of this routine.
15) 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.
16) 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.
17) If any of the input arguments, `method', `target', `et',
`abcorr', `obsrvr', `dref' or `dvec', is undefined, an error
is signaled by the IDL error handling system.
18) If any of the input arguments, `method', `target', `et',
`abcorr', `obsrvr', `dref' or `dvec', is not of the expected
type, or it does not have the expected dimensions and size, an
error is signaled by the Icy interface.
19) If any of the output arguments, `spoint', `dist', `trgepc',
`obspos' or `found', is not a named variable, an error is
signaled by the Icy interface.
Appropriate SPK, PCK, and frame kernels must be loaded by the
calling program before this routine is called. CK, SCLK, and
IK kernels may be required as well.
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: if the computation method is specified as
"Ellipsoid," 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.
- 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. Similarly, the frame definition required to map
between the frame designated by `dref' and the target
body-fixed frame must be available. Typically the
definitions of frames not already built-in to SPICE are
supplied by loading a frame kernel.
The following data may be required:
- CK data: if the frame to which `dref' refers is fixed to a
spacecraft instrument or structure, at least one CK file
will be needed to permit transformation of vectors between
that frame and both J2000 and the target body-fixed frame.
- SCLK data: if a CK file is needed, an associated SCLK
kernel is required to enable conversion between encoded SCLK
(used to time-tag CK data) and barycentric dynamical time
(TDB).
- IK data: one or more I-kernels may be required to enable
transformation of vectors from an instrument-fixed frame to
a spacecraft-fixed frame whose attitude is given by a
C-kernel.
In all cases, kernel data are normally loaded once per program
run, NOT every time this routine is called.
1) A cautionary note: if aberration corrections are used, and if
`dref' is the target body-fixed frame, the epoch at which that
frame is evaluated is offset from `et' by the light time between
the observer and the *center* of the target body. This light
time normally will differ from the light time between the
observer and intercept point. Consequently the orientation of
the target body-fixed frame at `trgepc' will not match that of
the target body-fixed frame at the epoch associated with `dref'.
As a result, various derived quantities may not be as
expected: for example, `obspos' would not be the inverse of the
aberration-corrected position of the target as seen by the
observer.
In many applications the errors arising from this frame
discrepancy may be insignificant; however a safe approach is
to always use as `dref' a frame other than the target body-fixed
frame.
ICY.REQ
FRAMES.REQ
NAIF_IDS.REQ
PCK.REQ
SPK.REQ
TIME.REQ
None.
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 header to comply with NAIF standard.
Added examples #1 and #2 problem statement and meta-kernels. Added
cspice_kclear call to examples' code. Modified example #2 to use
DAWN_VIR as reference frame instead of non-existing DAWN_NADIR.
Changed the input time frame and the number of points to be computed
in the 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.1.3, 18-MAY-2010 (BVS)
Index line now states that this routine is deprecated.
-Icy Version 1.1.2, 11-NOV-2008 (EDW)
Edits to header; -Abstract now states that this routine is
deprecated.
-Icy Version 1.1.1, 09-DEC-2005 (EDW)
Added tag for -Examples section.
-Icy Version 1.1.0, 05-AUG-2005 (EDW)
Added capability to process vector 'et' as an
input, returning arrays/vectors 'spoint', 'dist',
'trgepc', 'obspos', and 'found' as outputs.
-Icy Version 1.0.1, 16-MAR-2005 (EDW)
Corrected year value in 1.0.0 version string.
-Icy Version 1.0.0, 16-JUN-2004 (EDW)
DEPRECATED surface intercept point
|