Index Page
cspice_illum
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


   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.

I/O

   
   Given:
   
      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
 
   the call:

      cspice_illum, target, et,    abcorr, obsrvr, spoint, $
                    phase,  solar, emissn

   returns:
   
      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].
                  

Examples


   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
      ;; kernel.
      ;;
      cspice_furnsh, 'standard.tm'
      cspice_furnsh, 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]
         print

      endfor

   IDL outputs:

      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

Particulars


   None.

Required Reading


   ICY.REQ
   KERNEL.REQ
   NAIF_IDS.REQ
   SPK.REQ
   TIME.REQ
 

Version


   -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
      deprecated.

   -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)

Index_Entries

 
   DEPRECATED illumination angles 
   DEPRECATED lighting angles
   DEPRECATED phase angle
   DEPRECATED emission angle
   DEPRECATED solar incidence angle
 



Wed Apr  5 17:58:01 2017