Index Page
cspice_gfoclt
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_GFOCLT determines time intervals when an observer sees one target
   body occulted by, or in transit across, another.

   The surfaces of the target bodies may be represented by triaxial
   ellipsoids or by topographic data provided by DSK files.

   For important details concerning this module's function, please refer to
   the CSPICE routine gfoclt_c.

I/O


   Given:

      Parameters-

      All parameters described here are declared in the header file
      SpiceGF.h. See that file for parameter values.

      SPICE_GF_CNVTOL

               is the convergence tolerance used for finding endpoints of
               the intervals comprising the result window.
               SPICE_GF_CNVTOL is used to determine when binary searches
               for roots should terminate: when a root is bracketed
               within an interval of length SPICE_GF_CNVTOL, the root is
               considered to have been found.

               The accuracy, as opposed to precision, of roots found
               by this routine depends on the accuracy of the input
               data. In most cases, the accuracy of solutions will be
               inferior to their precision.


      Arguments-

      occtyp   the scalar string naming the type of occultation to find.
               Note that transits are considered to be a type of
               occultation.

               Supported values and corresponding definitions are:

                  'FULL'               denotes the full occultation
                                       of the body designated by
                                       'back' by the body designated
                                       by 'front', as seen from
                                       the location of the observer.
                                       In other words, the occulted
                                       body is completely invisible
                                       as seen from the observer's
                                       location.

                  'ANNULAR'            denotes an annular
                                       occultation: the body
                                       designated by 'front' blocks
                                       part of, but not the limb of,
                                       the body designated by 'back',
                                       as seen from the location of
                                       the observer.

                  'PARTIAL'            denotes a partial,
                                       non-annular occultation: the
                                       body designated by 'front'
                                       blocks part, but not all, of
                                       the limb of the body
                                       designated by 'back', as seen
                                       from the location of the
                                       observer.

                  'ANY'                denotes any of the above three
                                       types of occultations:
                                       'PARTIAL', 'ANNULAR', or
                                       'FULL'.

                                       'ANY' should be used to search
                                       for times when the body
                                       designated by 'front' blocks
                                       any part of the body designated
                                       by 'back'.

                                       The option 'ANY' must be used
                                       if either the front or back
                                       target body is modeled as
                                       a point.

               Case and leading or trailing blanks are not significant in
               the string 'occtyp'.

      front    the scalar string naming the target body that occults---that
               is, passes in front of---the other. Optionally, you may
               supply the integer NAIF ID code for the body as a
               string. For example both 'MOON' and '301' are
               legitimate strings that designate the Moon.

               The 'front' string lacks sensitivity to case, leading
               and trailing blanks.

      fshape   the scalar string naming the geometric model used
               to represent the shape of the front target body. The
               supported options are:

                 'ELLIPSOID'     Use a triaxial ellipsoid model
                                 with radius values provided from the
                                 kernel pool. A kernel variable
                                 having a name of the form

                                    'BODYnnn_RADII'

                                 where nnn represents the NAIF
                                 integer code associated with the
                                 body, must be present in the kernel
                                 pool. This variable must be
                                 associated with three numeric
                                 values giving the lengths of the
                                 ellipsoid's X, Y, and Z semi-axes.

                 'POINT'         Treat the body as a single point.
                                 When a point target is specified,
                                 the occultation type must be
                                 set to 'ANY'.

                 'DSK/UNPRIORITIZED[/SURFACES = <surface list>]'

                     Use topographic data provided by DSK files to
                     model the body's shape. These data must be
                     provided by loaded DSK files.

                     The surface list specification is optional. The
                     syntax of the list is

                        <surface 1> [, <surface 2>...]

                     If present, it indicates that data only for the
                     listed surfaces are to be used; however, data
                     need not be available for all surfaces in the
                     list. If absent, loaded DSK data for any surface
                     associated with the target body are used.

                     The surface list may contain surface names or
                     surface ID codes. Names containing blanks must
                     be delimited by double quotes, for example

                        SURFACES = "Mars MEGDR 128 PIXEL/DEG"

                     If multiple surfaces are specified, their names
                     or IDs must be separated by commas.

                     See the Particulars section below for details
                     concerning use of DSK data.

              The combinations of the shapes of the target bodies
              `front' and `back' must be one of:

                 One ELLIPSOID, one POINT
                 Two ELLIPSOIDs
                 One DSK, one POINT

               The 'fshape' string lacks sensitivity to case, leading
               and trailing blanks.

      fframe   the scalar string naming the body-fixed, body-centered
               reference frame associated with the front target body. Examples
               of such names are 'IAU_SATURN' (for Saturn) and
               'ITRF93' (for the Earth).

               If the front target body is modeled as a point, 'fframe'
               should be left empty or blank.

               The 'fframe' string lacks sensitivity to case, leading
               and trailing blanks.

      back     the scalar string naming the target body that is occulted
               by---that is, passes in back of---the other.
               Optionally, you may supply the integer NAIF ID code
               for the body as a string. For example both 'MOON' and
               '301' are legitimate strings that designate the Moon.

               The 'back' string lacks sensitivity to case, leading
               and trailing blanks.

      bshape   the string scalar naming the shape specification for the body
               designated by 'back'. The supported options are those for
               'fshape'. See the description of 'fshape' above for
                details.

      bframe   the scalar string naming the body-fixed, body-centered reference
               frame associated with the ''back'' target body.
               Examples of such names are 'IAU_SATURN' (for Saturn)
               and 'ITRF93' (for the Earth).

               If the back target body is modeled as a point, 'bframe'
               should be left empty or blank.

               The 'bframe' string lacks sensitivity to case, leading
               and trailing blanks.

      abcorr   indicates the aberration corrections to be applied to
               the state of the target body to account for one-way
               light time.  Stellar aberration corrections are
               ignored if specified, since these corrections don't
               improve the accuracy of the occultation determination.

               This routine accepts the same aberration corrections as does
               the CSPICE routine spkezr_c. See the header of spkezr_c for a
               detailed description of the aberration correction options.
               For convenience, the options are listed below:

                  'NONE'     Apply no correction.

                  'LT'       'Reception' case:  correct for
                             one-way light time using a Newtonian
                             formulation.

                  'LT+S'     'Reception' case:  correct for
                             one-way light time and stellar
                             aberration using a Newtonian
                             formulation.

                  'CN'       'Reception' case:  converged
                             Newtonian light time correction.

                  'CN+S'     'Reception' case:  converged
                             Newtonian light time and stellar
                             aberration corrections.

                  'XLT'      'Transmission' case:  correct for
                             one-way light time using a Newtonian
                             formulation.

                  'XLT+S'    'Transmission' case:  correct for
                             one-way light time and stellar
                             aberration using a Newtonian
                             formulation.

                  'XCN'      'Transmission' case:  converged
                             Newtonian light time correction.

                  'XCN+S'    'Transmission' case:  converged
                             Newtonian light time and stellar
                             aberration corrections.

               The 'abcorr' string lacks sensitivity to case, and to embedded,
               leading and trailing blanks.

      obsrvr   the scalar string naming the observing body. 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.

               Case and leading or trailing blanks are not significant in
               the string 'obsrvr'.

      step     a double precision value defining the step size to use in
               the search. 'step' must be shorter than any interval,
               within the confinement window, over which the specified
               occultation condition is met. In other words, 'step' must
               be shorter than the shortest occultation event that the user
               wishes to detect; 'step' must also be shorter than the
               shortest time interval between two occultation events that
               occur within the confinement window (see below). However,
               'step' must not be *too* short, or the search will take
               an unreasonable amount of time.

               The choice of 'step' affects the completeness but not
               the precision of solutions found by this routine; the
               precision is controlled by the convergence tolerance.
               See the discussion of the parameter SPICE_GF_CNVTOL for
               details.

               'step' has units of TDB seconds.

      cnfine   a double precision SPICE window that confines the time period
               over which the specified search is conducted. 'cnfine' may
               consist of a single interval or a collection of intervals.

               In some cases the confinement window can be used to greatly
               reduce the time period that must be searched for the desired
               solution. See the Particulars section below for further
               discussion.

               See the Examples section below for a code example
               that shows how to create a confinement window.

   the call:

      cspice_gfoclt, occtyp, front, fshape, fframe, $
                     back, bshape, bframe,          $
                     abcorr, obsrvr, step, cnfine, result

 returns:

      result   the double precision SPICE window of intervals, contained
               within the confinement window 'cnfine', on which the specified
               constraint is satisfied.

               If 'result' is non-empty on input, its contents
               will be discarded before cspice_gfoclt conducts its
               search.

               'result' must be declared and initialized with sufficient
               size to capture the full set of time intervals
               within the search region on which the specified constraint
               is satisfied.

               If no times within the confinement window satisfy the
               constraint, 'result' will be returned with a
               cardinality of zero.

Examples


   The numerical results shown for these examples may differ across
   platforms. The results depend on the SPICE kernels used as
   input, the compiler and supporting libraries, and the machine
   specific arithmetic implementation.

   Example(1):

      Find occultations of the Sun by the Moon (that is, solar
      eclipses)as seen from the center of the Earth over the month
      December, 2001.

      Use light time corrections to model apparent positions of Sun
      and Moon. Stellar aberration corrections are not specified
      because they don't affect occultation computations.

      We select a step size of 3 minutes, which means we
      ignore occultation events lasting less than 3 minutes,
      if any exist.


      MAXWIN  =  1000
      TIMFMT  = 'YYYY-MON-DD HR:MN:SC.###### (TDB) ::TDB ::RND'
      TIMLEN  =  41

      ;;
      ;; Load kernels.
      ;;
      cspice_furnsh, 'standard.tm'

      ;;
      ;; Store the time bounds of our search interval in
      ;; the cnfine confinement window.
      ;;
      cspice_str2et, [ '2001 DEC 01 00:00:00 TDB', $
                       '2002 JAN 01 00:00:00 TDB'], et

      cnfine = cspice_celld( 2 )
      cspice_wninsd, et[0], et[1], cnfine

      ;;
      ;; Select a 3-minute step. We'll ignore any occultations
      ;; lasting less than 3 minutes.
      ;;
      step    = 180.D

      occtyp  = 'any'
      front   = 'moon'
      fshape  = 'ellipsoid'
      fframe  = 'iau_moon'
      back    = 'sun'
      bshape  = 'ellipsoid'
      bframe  = 'iau_sun'
      obsrvr  = 'earth'
      abcorr  = 'lt'

      ;;
      ;; List the beginning and ending points in each interval
      ;; if result contains data.
      ;;
      result = cspice_celld( MAXWIN*2)

      cspice_gfoclt, occtyp, front, fshape, fframe, $
                     back, bshape, bframe,          $
                     abcorr, obsrvr, step, cnfine, result

      count = cspice_wncard( result )

      if ( count eq 0 ) then begin

         print, 'Result window is empty.'

      endif else begin

         for i= 0L, (count - 1L ) do begin

            cspice_wnfetd, result, i, left, right
            cspice_timout, [left, right], TIMFMT, TIMLEN, timstr

            if ( left eq right ) then begin

               print, 'Event time: ', timstr[0]

            endif else begin

               print, 'From : ',   timstr[0]
               print, 'To   : ',   timstr[1]
               print

            endelse

         endfor

      endelse

      ;;
      ;; It's always good form to unload kernels after use,
      ;; particularly in IDL due to data persistence.
      ;;
      cspice_kclear

   IDL outputs:

      From : 2001-DEC-14 20:10:14.196213 (TDB)
      To   : 2001-DEC-14 21:35:50.318416 (TDB)


   Example(2):

      Find occultations of Titan by Saturn or of Saturn by
      Titan as seen from the center of the Earth over the
      last three months of 2008. Search for every type
      of occultation.

      Use light time corrections to model apparent positions of
      Saturn and Titan. Stellar aberration corrections are not
      specified because they don't affect occultation computations.

      We select a step size of 15 minutes, which means we
      ignore occultation events lasting less than 15 minutes,
      if any exist.

      MAXWIN  =  1000
      TIMFMT  = 'YYYY-MON-DD HR:MN:SC.###### (TDB) ::TDB ::RND'
      TIMLEN  =  41
      OCCTYP  = ['FULL', 'ANNULAR', 'PARTIAL', 'ANY' ]

      ;;
      ;; Load kernels.
      ;;
      cspice_furnsh, 'standard.tm'
      cspice_furnsh, 'sat288.bsp'

      ;;
      ;; Store the time bounds of our search interval in
      ;; the cnfine confinement window.
      ;;
      cspice_str2et, [ '2008 SEP 01 00:00:00 TDB', $
                       '2009 JAN 01 00:00:00 TDB'], et

      cnfine = cspice_celld( 2 )
      cspice_wninsd, et[0], et[1], cnfine

      ;;
      ;; Select a 15-minute step. We'll ignore any occultations
      ;; lasting less than 15 minutes.
      ;;
      step    = 900.D

      ;;
      ;; The observation location is the Earth.
      ;;
      obsrvr  = 'earth'
      shape   = 'ellipsoid'
      abcorr = 'lt'

      result = cspice_celld( MAXWIN*2)


      ;;
      ;; Loop over the occultation types.
      ;;
      for i=0, n_elements(OCCTYP)-1 do begin


         ;;
         ;; For each type, do a search for both transits of
         ;; Titan across Saturn and occultations of Titan by
         ;; Saturn.
         ;;
         for j=0, 1 do begin

            if ( j EQ 0 ) then begin

               front  = 'TITAN'
               fframe = 'IAU_TITAN'
               back   = 'SATURN'
               bframe = 'IAU_SATURN'

            endif else begin

               front  = 'SATURN'
               fframe = 'IAU_SATURN'
               back   = 'TITAN'
               bframe = 'IAU_TITAN'

            endelse

            ;;
            ;; Perform the search.
            ;;
            cspice_gfoclt, OCCTYP[i], front, shape, fframe, $
                           back, shape, bframe,             $
                           abcorr, obsrvr, step, cnfine, result


            ;;
            ;; List the beginning and ending points in each interval
            ;; if result contains data.
            ;;

            print, 'Condition      : ', OCCTYP[i]
            print, 'Occultation of : ', back
            print, 'by             : ', front
            print

            count = cspice_wncard( result )
            if ( count eq 0 ) then begin

               print, 'Result window is empty.'
               print

            endif else begin

               for k= 0L, (count - 1L ) do begin

                  cspice_wnfetd, result, k, left, right
                  cspice_timout, [left, right], TIMFMT, TIMLEN, timstr

                  if ( left eq right ) then begin

                     print, 'Event time: ', timstr[0]
                     print

                  endif else begin

                     print, 'From : ',   timstr[0]
                     print, 'To   : ',   timstr[1]
                     print

                  endelse

               endfor

            endelse

            ;;
            ;; We've finished displaying the results of the
            ;; current search.
            ;;

         endfor

         ;;
         ;; We've finished displaying the results of the
         ;; searches using the current occultation type.
         ;;

      endfor


      ;;
      ;; It's always good form to unload kernels after use,
      ;; particularly in IDL due to data persistence.
      ;;
      cspice_kclear

   IDL outputs:

      Condition      : FULL
      Occultation of : SATURN
      by             : TITAN

      Result window is empty.

      Condition      : FULL
      Occultation of : TITAN
      by             : SATURN

      From : 2008-OCT-27 22:08:01.627053 (TDB)
      To   : 2008-OCT-28 01:05:03.375237 (TDB)

      From : 2008-NOV-12 21:21:59.252263 (TDB)
      To   : 2008-NOV-13 02:06:05.053051 (TDB)

      From : 2008-NOV-28 20:49:02.402832 (TDB)
      To   : 2008-NOV-29 02:13:58.986344 (TDB)

      From : 2008-DEC-14 20:05:09.246177 (TDB)
      To   : 2008-DEC-15 01:44:53.523002 (TDB)

      From : 2008-DEC-30 19:00:56.577073 (TDB)
      To   : 2008-DEC-31 00:42:43.222909 (TDB)

      Condition      : ANNULAR
      Occultation of : SATURN
      by             : TITAN

      From : 2008-OCT-19 21:29:20.599088 (TDB)
      To   : 2008-OCT-19 22:53:34.518737 (TDB)

      From : 2008-NOV-04 20:15:38.620369 (TDB)
      To   : 2008-NOV-05 00:18:59.139979 (TDB)

      From : 2008-NOV-20 19:38:59.647712 (TDB)
      To   : 2008-NOV-21 00:35:26.725909 (TDB)

      From : 2008-DEC-06 18:58:34.073269 (TDB)
      To   : 2008-DEC-07 00:16:17.647040 (TDB)

      From : 2008-DEC-22 18:02:46.288290 (TDB)
      To   : 2008-DEC-22 23:26:52.712459 (TDB)

      Condition      : ANNULAR
      Occultation of : TITAN
      by             : SATURN

      Result window is empty.

      Condition      : PARTIAL
      Occultation of : SATURN
      by             : TITAN

      From : 2008-OCT-19 20:44:30.326772 (TDB)
      To   : 2008-OCT-19 21:29:20.599088 (TDB)

      From : 2008-OCT-19 22:53:34.518737 (TDB)
      To   : 2008-OCT-19 23:38:26.250580 (TDB)

      From : 2008-NOV-04 19:54:40.339331 (TDB)
      To   : 2008-NOV-04 20:15:38.620369 (TDB)

      From : 2008-NOV-05 00:18:59.139979 (TDB)
      To   : 2008-NOV-05 00:39:58.612936 (TDB)

      From : 2008-NOV-20 19:21:46.689523 (TDB)
      To   : 2008-NOV-20 19:38:59.647712 (TDB)

      From : 2008-NOV-21 00:35:26.725909 (TDB)
      To   : 2008-NOV-21 00:52:40.604704 (TDB)

      From : 2008-DEC-06 18:42:36.100544 (TDB)
      To   : 2008-DEC-06 18:58:34.073269 (TDB)

      From : 2008-DEC-07 00:16:17.647040 (TDB)
      To   : 2008-DEC-07 00:32:16.324244 (TDB)

      From : 2008-DEC-22 17:47:10.776723 (TDB)
      To   : 2008-DEC-22 18:02:46.288290 (TDB)

      From : 2008-DEC-22 23:26:52.712459 (TDB)
      To   : 2008-DEC-22 23:42:28.850543 (TDB)

      Condition      : PARTIAL
      Occultation of : TITAN
      by             : SATURN

      From : 2008-OCT-27 21:37:16.970175 (TDB)
      To   : 2008-OCT-27 22:08:01.627053 (TDB)

      From : 2008-OCT-28 01:05:03.375237 (TDB)
      To   : 2008-OCT-28 01:35:49.266507 (TDB)

      From : 2008-NOV-12 21:01:47.105499 (TDB)
      To   : 2008-NOV-12 21:21:59.252263 (TDB)

      From : 2008-NOV-13 02:06:05.053051 (TDB)
      To   : 2008-NOV-13 02:26:18.227358 (TDB)

      From : 2008-NOV-28 20:31:28.522707 (TDB)
      To   : 2008-NOV-28 20:49:02.402832 (TDB)

      From : 2008-NOV-29 02:13:58.986344 (TDB)
      To   : 2008-NOV-29 02:31:33.691598 (TDB)

      From : 2008-DEC-14 19:48:27.094229 (TDB)
      To   : 2008-DEC-14 20:05:09.246177 (TDB)

      From : 2008-DEC-15 01:44:53.523002 (TDB)
      To   : 2008-DEC-15 02:01:36.360243 (TDB)

      From : 2008-DEC-30 18:44:23.485899 (TDB)
      To   : 2008-DEC-30 19:00:56.577073 (TDB)

      From : 2008-DEC-31 00:42:43.222909 (TDB)
      To   : 2008-DEC-31 00:59:17.030569 (TDB)

      Condition      : ANY
      Occultation of : SATURN
      by             : TITAN

      From : 2008-OCT-19 20:44:30.326772 (TDB)
      To   : 2008-OCT-19 23:38:26.250580 (TDB)

      From : 2008-NOV-04 19:54:40.339331 (TDB)
      To   : 2008-NOV-05 00:39:58.612936 (TDB)

      From : 2008-NOV-20 19:21:46.689523 (TDB)
      To   : 2008-NOV-21 00:52:40.604704 (TDB)

      From : 2008-DEC-06 18:42:36.100544 (TDB)
      To   : 2008-DEC-07 00:32:16.324244 (TDB)

      From : 2008-DEC-22 17:47:10.776723 (TDB)
      To   : 2008-DEC-22 23:42:28.850543 (TDB)

      Condition      : ANY
      Occultation of : TITAN
      by             : SATURN

      From : 2008-OCT-27 21:37:16.970175 (TDB)
      To   : 2008-OCT-28 01:35:49.266507 (TDB)

      From : 2008-NOV-12 21:01:47.105499 (TDB)
      To   : 2008-NOV-13 02:26:18.227358 (TDB)

      From : 2008-NOV-28 20:31:28.522707 (TDB)
      To   : 2008-NOV-29 02:31:33.691598 (TDB)

      From : 2008-DEC-14 19:48:27.094229 (TDB)
      To   : 2008-DEC-15 02:01:36.360243 (TDB)

      From : 2008-DEC-30 18:44:23.485899 (TDB)
      To   : 2008-DEC-31 00:59:17.030569 (TDB)

Particulars


   This routine provides a simple interface for conducting searches for
   occultation events.

   This routine determines a set of one or more time intervals
   within the confinement window when a specified type of
   occultation occurs. The resulting set of intervals is returned as
   a Icy window.

   Below we discuss in greater detail aspects of this routine's
   solution process that are relevant to correct and efficient
   use of this routine in user applications.

   The Search Process
   ==================

   The search for occultations is treated as a search for state
   transitions: times are sought when the state of the `back' body
   changes from "not occulted" to "occulted" or vice versa.

   Step Size
   =========

   Each interval of the confinement window is searched as follows:
   first, the input step size is used to determine the time
   separation at which the occultation state will be sampled.
   Starting at the left endpoint of an interval, samples will be
   taken at each step. If a state change is detected, a root has
   been bracketed; at that point, the "root"--the time at which the
   state change occurs---is found by a refinement process, for
   example, by a binary search.

   Note that the optimal choice of step size depends on the lengths
   of the intervals over which the occultation state is constant:
   the step size should be shorter than the shortest occultation
   duration and the shortest period between occultations, within
   the confinement window.

   Having some knowledge of the relative geometry of the targets and
   observer can be a valuable aid in picking a reasonable step size.
   In general, the user can compensate for lack of such knowledge by
   picking a very short step size; the cost is increased computation
   time.

   Note that the step size is not related to the precision with which
   the endpoints of the intervals of the result window are computed.
   That precision level is controlled by the convergence tolerance.

   Convergence Tolerance
   =====================

   As described above, the root-finding process used by this routine
   involves first bracketing roots and then using a search process
   to locate them. "Roots" are both times when local extrema are
   attained and times when the distance function is equal to a
   reference value. All endpoints of the intervals comprising the
   result window are either endpoints of intervals of the
   confinement window or roots.

   Once a root has been bracketed, a refinement process is used to
   narrow down the time interval within which the root must lie.
   This refinement process terminates when the location of the root
   has been determined to within an error margin called the
   "convergence tolerance." The convergence tolerance used by this
   routine is set by the parameter SPICE_GF_CNVTOL.

   The value of SPICE_GF_CNVTOL is set to a "tight" value so that the
   tolerance doesn't become the limiting factor in the accuracy of
   solutions found by this routine. In general the accuracy of input
   data will be the limiting factor.

   The user may change the convergence tolerance from the default
   SPICE_GF_CNVTOL value by calling the routine cspice_gfstol, e.g.

      cspice_gfstol, tolerance value in seconds

   Call cspice_gfstol prior to calling this routine. All subsequent
   searches will use the updated tolerance value.

   Setting the tolerance tighter than SPICE_GF_CNVTOL is unlikely to be
   useful, since the results are unlikely to be more accurate.
   Making the tolerance looser will speed up searches somewhat,
   since a few convergence steps will be omitted. However, in most
   cases, the step size is likely to have a much greater affect on
   processing time than would the convergence tolerance.

   The Confinement Window
   ======================

   The simplest use of the confinement window is to specify a time
   interval within which a solution is sought. However, the
   confinement window can, in some cases, be used to make searches
   more efficient. Sometimes it's possible to do an efficient search
   to reduce the size of the time period over which a relatively
   slow search of interest must be performed.

   Using DSK data
   ==============

      DSK loading and unloading
      -------------------------

      DSK files providing data used by this routine are loaded by
      calling cspice_furnsh and can be unloaded by calling cspice_unload or
      cspice_kclear. See the documentation of cspice_furnsh for limits on
      numbers of loaded DSK files.

      For run-time efficiency, it's desirable to avoid frequent
      loading and unloading of DSK files. When there is a reason to
      use multiple versions of data for a given target body---for
      example, if topographic data at varying resolutions are to be
      used---the surface list can be used to select DSK data to be
      used for a given computation. It is not necessary to unload
      the data that are not to be used. This recommendation presumes
      that DSKs containing different versions of surface data for a
      given body have different surface ID codes.


      DSK data priority
      -----------------

      A DSK coverage overlap occurs when two segments in loaded DSK
      files cover part or all of the same domain---for example, a
      given longitude-latitude rectangle---and when the time
      intervals of the segments overlap as well.

      When DSK data selection is prioritized, in case of a coverage
      overlap, if the two competing segments are in different DSK
      files, the segment in the DSK file loaded last takes
      precedence. If the two segments are in the same file, the
      segment located closer to the end of the file takes
      precedence.

      When DSK data selection is unprioritized, data from competing
      segments are combined. For example, if two competing segments
      both represent a surface as a set of triangular plates, the
      union of those sets of plates is considered to represent the
      surface.

      Currently only unprioritized data selection is supported.
      Because prioritized data selection may be the default behavior
      in a later version of the routine, the UNPRIORITIZED keyword is
      required in the `fshape' and `bshape' arguments.


      Syntax of the shape input arguments for the DSK case
      ----------------------------------------------------

      The keywords and surface list in the target shape arguments
      `bshape' and `fshape' are called "clauses." The clauses may
      appear in any order, for example

         "DSK/<surface list>/UNPRIORITIZED"
         "DSK/UNPRIORITIZED/<surface list>"
         "UNPRIORITIZED/<surface list>/DSK"

      The simplest form of the `method' argument specifying use of
      DSK data is one that lacks a surface list, for example:

         "DSK/UNPRIORITIZED"

      For applications in which all loaded DSK data for the target
      body are for a single surface, and there are no competing
      segments, the above string suffices. This is expected to be
      the usual case.

      When, for the specified target body, there are loaded DSK
      files providing data for multiple surfaces for that body, the
      surfaces to be used by this routine for a given call must be
      specified in a surface list, unless data from all of the
      surfaces are to be used together.

      The surface list consists of the string

         "SURFACES = "

      followed by a comma-separated list of one or more surface
      identifiers. The identifiers may be names or integer codes in
      string format. For example, suppose we have the surface
      names and corresponding ID codes shown below:

         Surface Name                              ID code
         ------------                              -------
         "Mars MEGDR 128 PIXEL/DEG"                1
         "Mars MEGDR 64 PIXEL/DEG"                 2
         "Mars_MRO_HIRISE"                         3

      If data for all of the above surfaces are loaded, then
      data for surface 1 can be specified by either

         'SURFACES = 1'

      or

         'SURFACES = "Mars MEGDR 128 PIXEL/DEG"'

      Double quotes are used to delimit the surface name because
      it contains blank characters.

      To use data for surfaces 2 and 3 together, any
      of the following surface lists could be used:

         'SURFACES = 2, 3'

         'SURFACES = "Mars MEGDR  64 PIXEL/DEG", 3'

         'SURFACES = 2, Mars_MRO_HIRISE'

         'SURFACES = "Mars MEGDR 64 PIXEL/DEG", Mars_MRO_HIRISE'

      An example of a shape argument that could be constructed
      using one of the surface lists above is

         'DSK/UNPRIORITIZED/SURFACES = "Mars MEGDR 64 PIXEL/DEG", 3'

Required Reading


   ICY.REQ
   DSK.REQ
   GF.REQ
   SPK.REQ
   CK.REQ
   TIME.REQ
   WINDOWS.REQ

Version


   -Icy Version 2.0.0, 04-APR-2017, EDW (JPL), NJB (JPL)

      Updated to support use of DSKs.

   -Icy Version 1.0.1, 14-MAY-2012, EDW (JPL)

      Header updated to describe use of cspice_gfstol.

   -Icy Version 1.0.0, 15-APR-2009, EDW (JPL)

Index_Entries


   GF occultation search



Wed Apr  5 17:58:01 2017