Index Page
cspice_occult
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_OCCULT determines the occultation condition (not occulted,
   partially, etc.) of one target relative to another target as seen
   by an observer at a given time.

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

I/O


   Given:

      target1    is the name of the first target body. Both object
                 names and NAIF IDs are accepted. For example, both
                 'Moon' and '301' are accepted.

      shape1     is a string indicating the geometric model used to
                 represent the shape of the first target body.

                 The supported options are:

                    'ELLIPSOID'

                       Use a triaxial ellipsoid model with radius values
                       provided via 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 conditions
                       can only be total, annular, or none.

                    '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
                 `targ1' and `targ2' must be one of:

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

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

      frame1     is the name of the body-fixed, body-centered reference
                 frame associated with the first target body. Examples
                 of such names are 'IAU_SATURN' (for Saturn) and
                 'ITRF93' (for the Earth).

                 If the first target body is modeled as a point, 'frame1'
                 should be left blank (Ex: ' ').

                 Case and leading or trailing blanks bracketing a
                 non-blank frame name are not significant in the string.

      target2    is the name of the second target body. See the description of
                 'target1' above for more details.

      shape2     is the shape specification for the body designated
                 by 'target2'. See the description of 'shape1' above for
                 details.

      frame2     is the name of the body-fixed, body-centered reference
                 frame associated with the second target body. See the
                 description of 'frame1' above for more details.

      abcorr     indicates the aberration corrections to be applied to
                 the state of each 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.

                 See the header of the SPICE routine spkezr_c for a
                 detailed description of the aberration correction
                 options. For convenience, the options supported by
                 this routine are listed below:

                    'NONE'     Apply no correction.

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

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

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

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

                 Case and blanks are not significant in the string
                 'abcorr'.

      observer   is the name of the body from which the occultation
                 is observed. See the description of 'target1' for more
                 details.

      time       is the observation time in seconds past the J2000
                 epoch.

   the call:

      cspice_occult, target1, shape1,   frame1,             $
                     target2, shape2,   frame2,             $
                     abcorr,  observer, time,   occult_code )

   returns:

      occult_code    is an integer occultation code indicating the geometric
                     relationship of the three bodies.

                     The meaning of the sign of 'occult_code' is given below.

                        Code sign          Meaning
                        ---------          ------------------------------
                           > 0             The second ellipsoid is
                                           partially or fully occulted
                                           by the first.

                           < 0             The first ellipsoid is
                                           partially of fully
                                           occulted by the second.

                           = 0             No occultation.

                     Possible 'occult_code' values and meanings are given
                     below. The names in the left column can be accessed
                     in a user's program by calling 'IcyUser' as shown
                     in the example program below. The variable names indicate
                     the type of occultation and which target is in the back.
                     For example, ICY_TOTAL1_BACK represents a total
                     occultation in which the first target is in the back (or
                     occulted by) the second target.

                        Name             Code    Meaning
                        ------           -----   ---------------------------
                        ICY_TOTAL1_BACK   -3     Total occultation of first
                                                 target by second. First
                                                 target is in back.

                        ICY_ANNLR1_BACK   -2     Annular occultation of first
                                                 target by second. The second
                                                 target does not block the limb
                                                 of the first. First target
                                                 is in back.

                        ICY_PARTL1_BACK   -1     Partial occultation of first
                                                 target by second target. First
                                                 target is in back.

                        ICY_NOOCC          0     No occultation or transit:
                                                 both objects are completely
                                                 visible to the observer.

                        ICY_PARTL2_BACK    1     Partial occultation of second
                                                 target by first target. Second
                                                 target is in back.

                        ICY_ANNLR2_BACK    2     Annular occultation of second
                                                 target by first. Second target
                                                 is in back.

                        ICY_TOTAL2_BACK    3     Total occultation of second
                                                 target by first. Second target
                                                 is in back.

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 whether MRO is occulted by Mars as seen by
      the DSS-13 ground station at a few specific
      times.

      Use the meta-kernel shown below to load the required SPICE
      kernels.

         KPL/MK

         File name: mro_ex_occult.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
               earthstns_itrf93_050714.bsp     DSN station ephemeris
               pck00010.tpc                    Planet orientation and
                                               radii
               earth_000101_120409_120117.bpc  High precision Earth
                                               orientation
               mro_psp_rec.bsp                 MRO ephemeris
               naif0010.tls                    Leapseconds
               earth_topo_050714.tf            Topocentric reference
                                               frames for
                                               DSN stations

         \begindata

         KERNELS_TO_LOAD = ( 'de421.bsp',
                             'earthstns_itrf93_050714.bsp',
                             'pck00010.tpc',
                             'earth_000101_120409_120117.bpc',
                             'mro_psp_rec.bsp',
                             'naif0010.tls',
                             'earth_topo_050714.tf' )

         \begintext

      End of meta-kernel.

      Beginning of example program.

         PRO occult_ex

            ;;
            ;; IcyUser is a file that makes certain variables global.
            ;; You must call IcyUser to have access to occultation-specific
            ;; variable names like ICY_TOTAL1_BACK, which indicates there
            ;; is a total occultation in which the first target is in the back
            ;; of the second target. These variables are defined so you don't
            ;; need to remember what the integer codes mean that the
            ;; occultation routine returns. For more information, please see
            ;; IcyUser.pro and IcyOccult.pro.
            ;;
            ;; To use the variables in IcyUser, add the 'src/icy' directory
            ;; to your IDL path by doing the following in which /path/to is the
            ;; local path to Icy.
            ;;
            ;;    pref_set, 'IDL_PATH', '/path/to/icy/src/icy:<IDL_DEFAULT>', $
            ;;                           /COMMIT
            ;;
            @IcyUser

            ;;
            ;; Local variables
            ;;
            ;; The meta-kernel to be loaded is the variable 'metakr'.
            ;;
            metakr = '/home/skrening/kernels/MRO/mro_ex_occult.tm'

            target1 = ' MRO  '
            target2 = ' Mars '
            observer = 'DSS-13'
            dt = 1000.
            out_char = ['totally occulted by  ',  $
                        'transited by         ',  $
                        'partially occulted by',  $
                        'not occulted by      ']

            ;;
            ;; Load kernels
            ;;
            cspice_furnsh, metakr

            cspice_str2et, '2012-jan-5 1:15:00 UTC', et_start
            cspice_str2et, '2012-jan-5 2:50:00 UTC', et_stop

            ;;
            ;; Initialize the time array in ET.
            ;;
            size_et = long( (et_stop-et_start)/dt ) + 1
            et = dt * dindgen ( size_et ) + et_start

            ;;
            ;; Calculate the type of occultation that
            ;; corresponds to time ET.
            ;;
            cspice_occult, target1, 'point', ' ',             $
                           target2, 'ellipsoid', 'iau_mars',  $
                           'cn', observer, et, occult_code

            ;;
            ;; Convert the times to a readable format.
            ;;
            cspice_timout, et, 'YYYY-MM-DD HR:MN ::UTC-8', 22, time

            ;;
            ;; Output the results.
            ;;
            for j = 0, size_et-1 do begin
               ;;
               ;; Remember: You must call '@IcyUser' before
               ;; using the parameters in the case statements below.
               ;; See the beginning of the example or IcyUser for
               ;; details.
               ;;
               case occult_code(j) of
                  ICY_TOTAL1_BACK: print, time(j), target1, out_char(0), $
                                          target1, 'wrt ', observer
                  ICY_ANNLR1_BACK: print, time(j), target1, out_char(1), $
                                          target1, 'wrt ', observer
                  ICY_PARTL1_BACK: print, time(j), target1, out_char(2), $
                                          target1, 'wrt ', observer
                  ICY_NOOCC:       print, time(j), target1, out_char(3), $
                                          target2, 'wrt ', observer
                  ICY_PARTL2_BACK: print, time(j), target2, out_char(2), $
                                          target2, 'wrt ', observer
                  ICY_ANNLR2_BACK: print, time(j), target2, out_char(1), $
                                          target2, 'wrt ', observer
                  ICY_TOTAL2_BACK: print, time(j), target2, out_char(0), $
                                          target2, 'wrt ', observer
               endcase

            endfor

            ;;
            ;; Unload kernels.
            ;;
            cspice_kclear

         END

   IDL outputs:

      2012-01-04 17:15 Mars transited by          Mars wrt DSS-13
      2012-01-04 17:31 MRO  not occulted by       Mars wrt DSS-13
      2012-01-04 17:48 MRO  totally occulted by   MRO  wrt DSS-13
      2012-01-04 18:04 MRO  totally occulted by   MRO  wrt DSS-13
      2012-01-04 18:21 MRO  not occulted by       Mars wrt DSS-13
      2012-01-04 18:38 Mars transited by          Mars wrt DSS-13

Particulars


   For many purposes, modeling extended bodies as triaxial
   ellipsoids is adequate for determining whether one body is
   occulted by another as seen from a specified observer.

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

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

      DSK files providing data used by this routine are loaded by
      calling furnsh_c and can be unloaded by calling unload_c or
      kclear_c. See the documentation of furnsh_c 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 `shape1' and `shape2' arguments.


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

      The keywords and surface list in the target shape arguments
      `shape1' and `shape2' 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

Version


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

      Updated to support use of DSKs.

   -Icy Version 1.0.0, 14-NOV-2013, SCK (JPL)

Index_Entries


   occultation type at a specified time



















Wed Apr  5 17:58:02 2017