CSPICE_ILLUM calculates the illumination angles at a specified
surface point of a target body.
Deprecated: This routine has been superseded by the routine
cspice_ilumin. This routine is supported for purposes of
backward compatibility only.
For important details concerning this module's function, please refer to
the CSPICE routine illum_c.
target is the scalar string 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.
The target and observer define a state vector whose
position component points from the observer to the target.
et the scalar or N-vector of double precision epochs,
specified in ephemeris seconds past J2000, at which the
apparent illumination angles at the specified surface
point on the target body, as seen from the observing
body, are to be computed.
abcorr the aberration correction to be used in computing the
location and orientation of the target body and the location
of the Sun.
obsrvr the name of the observing body, 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 a double precision Cartesian 3-vector or 3xN array
representing a surface point or points on the target body,
expressed in rectangular body-fixed (body equator and prime
meridian) coordinates. Each 'spoint' element (spoint[*,i])
corresponds to the same element index in 'et' (et[i]) and need
not be visible from the observer's location at time 'et'.
Note: The design of cspice_illum supposes the input 'spoint'
originates as the output of another Icy routine. Still, in
the event the user requires an 'spoint' constant over a vector
of 'et', such as a constant station location at (x,y,z),
construct 'spoint' with the IDL code:
N = n_elements( et )
spoint = dblarr(3,N)
spoint[0,*] = x
spoint[1,*] = y
spoint[2,*] = z
cspice_illum, target, et, abcorr, obsrvr, spoint, $
phase, solar, emissn
phase the double precision, scalar or N-vector phase angle at
'spoint', as seen from 'obsrvr' at time 'et'. This is the
angle between the 'spoint'-'obsrvr' vector and the 'spoint'-sun
vector. Units are radians. The range of 'phase' is [0, pi].
solar the double precision, scalar or N-vector solar incidence
angle at `spoint', as seen from 'obsrvr' at time 'et'.
This is the angle between the surface normal vector at
'spoint' and the 'spoint'-sun vector. Units are radians.
The range of 'solar' is [0, pi].
emissn the double precision, scalar or N-vector emission angle
at 'spoint', as seen from 'obsrvr' at time 'et'. This is the
angle between the surface normal vector at 'spoint' and the
'spoint'-observer vector. Units are radians. The range of
'emissn' is [0, pi].
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.
;; Compute the time evolution of the phase, solar, and
;; emission angles for the intercept sub-point of the
;; MGS orbiter from Feb 1, 2003 to April 1, 2003.
TARGET = 'MARS'
OBSERVER = 'MGS'
CORRECT = 'LT+S'
;; Assign the MGS kernel to a string variable.
;; Define the start and stop time for the computations.
MGS = '/kernels/MGS/spk/spk_m_030102-030403_021004.bsp'
START_TIME = '1 Feb 2003'
STOP_TIME = '1 APR 2003'
;; Number of steps?
STEP = 75
;; Load the standard leapseconds, PCK kernels and the MGS
;; Convert the strings to ephemeris time J2000.
cspice_str2et, START_TIME, et_start
cspice_str2et, STOP_TIME , et_stop
;; Length of a step in seconds for STEP steps.
space = (et_stop - et_start)/double(STEP)
;; Create a vector of ephemeris times.
et = et_start + dindgen(STEP)*space
;; Start at 'et_start', take STEP steps
;; of space 'length'. At each time, calculate the
;; intercept sub-point of the observer, then calculate
;; the illumination angles at the sub-point.
cspice_subpt, 'Intercept', TARGET, et, CORRECT, $
OBSERVER, pos, alt
cspice_illum, TARGET, et, CORRECT, OBSERVER, pos, $
phase, solar, emissn
;; Convert the et value to UTC for human comprehension.
cspice_et2utc, et, 'C', 3, utc
;; Convert angular measures to angles for output.
emissn = emissn*cspice_dpr()
solar = solar *cspice_dpr()
phase = phase *cspice_dpr()
for i = 0, STEP-1 do begin
;; Output the angles in degrees and time.
print, 'UTC : ', utc[i]
print, 'Emission angle: ', emissn[i]
print, 'Solar angle : ', solar[i]
print, 'Phase angle : ', phase[i]
UTC : 2003 FEB 01 00:00:00.000
Emission angle: 0.12860337
Solar angle : 49.308223
Phase angle : 49.230858
UTC : 2003 FEB 01 18:52:48.000
Emission angle: 0.30178311
Solar angle : 143.95430
Phase angle : 144.01734
UTC : 2003 MAR 30 10:14:24.000
Emission angle: 0.16030046
Solar angle : 139.57531
Phase angle : 139.58579
UTC : 2003 MAR 31 05:07:12.000
Emission angle: 0.29139563
Solar angle : 58.922414
Phase angle : 58.711270
-Icy Version 1.1.2, 18-MAY-2010, BVS (JPL)
Index lines now state that this routine is deprecated.
-Icy Version 1.1.1, 11-NOV-2008, EDW (JPL)
Edits to header; Abstract now states that this routine is
-Icy Version 1.1.0, 18-JUL-2005, EDW (JPL)
Added capability to process vector 'et' and 'spoint' as
inputs returning vectors 'dist', 'phase', 'solar', and
'emissn' as outputs.
-Icy Version 1.0.0, 16-JUN-2003, EDW (JPL)
DEPRECATED illumination angles
DEPRECATED lighting angles
DEPRECATED phase angle
DEPRECATED emission angle
DEPRECATED solar incidence angle