Index Page occult_c

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

Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries

#### Procedure

       void occult_c ( ConstSpiceChar   * targ1,
                       ConstSpiceChar   * shape1,
                       ConstSpiceChar   * frame1,
                       ConstSpiceChar   * targ2,
                       ConstSpiceChar   * shape2,
                       ConstSpiceChar   * frame2,
                       ConstSpiceChar   * abcorr,
                       ConstSpiceChar   * obsrvr,
                       SpiceDouble        et,
                       SpiceInt         * ocltid )

#### Abstract

       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.

#### Required_Reading

       SPK
       TIME
       KERNEL

#### Keywords

       GEOMETRY
       OCCULTATION
       ELLIPSOID

#### Brief_I/O

       VARIABLE    I/O  DESCRIPTION
       --------    ---  -------------------------------------------
       targ1        I   Name or ID of first target.
       shape1       I   Type of shape model used for first target.
       frame1       I   Body-fixed, body-centered frame for first body.
       targ2        I   Name or ID of second target.
       shape2       I   Type of shape model used for second target.
       frame2       I   Body-fixed, body-centered frame for second body.
       abcorr       I   Aberration correction flag.
       obsrvr       I   Name or ID of the observer.
       et           I   Time of the observation (seconds past J2000).
       ocltid       O   Occultation identification code.

#### Detailed_Input

       targ1      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 `shape1'.

       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.

       targ2      is the name of the second target body. See the description
                  of `targ1' above for more details.

       shape2     is the shape specification for the body designated
                  by `targ2'. 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'.

       obsrvr     is the name of the body from which the occultation
                  is observed. See the description of `targ1' above for
                  more details.

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

#### Detailed_Output

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

                     The meaning of the sign of `ocltid' 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 `ocltid' values and meanings are given below.
                  The variable names indicate the type of occultation and
                  which target is in the back. For example,
                  SPICE_OCCULT_TOTAL1 represents a total occultation in
                  which the first target is in the back (or occulted by)
                  the second target.

                     Name                Code    Meaning
                     ------              -----   ------------------------------
                     SPICE_OCCULT_TOTAL1  -3     Total occultation of first
                                                 target by second.

                     SPICE_OCCULT_ANNLR1  -2     Annular occultation of first
                                                 target by second. The second
                                                 target does not block the limb
                                                 of the first.

                     SPICE_OCCULT_PARTL1  -1     Partial occultation of first
                                                 target by second target.

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

                     SPICE_OCCULT_PARTL2   1     Partial occultation of second
                                                 target by first target.

                     SPICE_OCCULT_ANNLR2   2     Annular occultation of
                                                 second target by first.

                     SPICE_OCCULT_TOTAL2   3     Total occultation of second
                                                 target by first.

#### Parameters

       None.

#### Exceptions

       1)  If the target or observer body names input by the user are
           not recognized, the error will be diagnosed by a routine in
           the call tree of this routine.

       2)  If the input shapes are not accepted, the error will be
           diagnosed by a routine in the call tree of this routine.

       3)  If both input shapes are points, the error will be
           diagnosed by a routine in the call tree of this routine.

       4)  If the radii of a target body modeled as an ellipsoid cannot
           be determined by searching the kernel pool for a kernel
           variable having a name of the form

              "BODYnnn_RADII"

           where nnn represents the NAIF integer code associated with
           the body, the error will be diagnosed by a routine in the
           call tree of this routine.

       5)  If any of the target or observer bodies (`targ1', `targ2', or
           `obsrvr') are the same, the error will be diagnosed
           by a routine in the call tree of this routine.

       6)  If the loaded kernels provide insufficient data to
           compute any required state vector, the deficiency will
           be diagnosed by a routine in the call tree of this routine.

       7)  If an error occurs while reading an SPK or other kernel,
           the error will be diagnosed by a routine in the call tree
           of this routine.

       8)  Invalid aberration correction specifications will be
           diagnosed by a routine in the call tree of this routine.

       9)  If either `shape1' or `shape2' specifies that the target surface
           is represented by DSK data, and no DSK files are loaded for
           the specified target, the error is signaled by a routine in
           the call tree of this routine.

      10)  If either `shape1' or `shape2' specifies that the target surface
           is represented by DSK data, but the shape specification is
           invalid, the error is signaled by a routine in the call tree
           of this routine.

      11)  If any input string argument pointer is null, the error
           SPICE(NULLPOINTER) will be signaled.

      12)  If any input string argument, other than `frame2' or `frame1',
           is empty, the error SPICE(EMPTYSTRING) will be signaled.

#### Files

       Appropriate SPICE kernels must be loaded by the calling program
       before this routine is called.

       The following data are required:

          - SPK data: the calling application must load ephemeris data
            for the targets, source and observer that cover the time
            period specified by the window `cnfine'. If aberration
            corrections are used, the states of the target bodies and of
            the 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 furnsh_c.

          - PCK data: bodies modeled as triaxial ellipsoids must have
            semi-axis lengths provided by variables in the kernel pool.
            Typically these data are made available by loading a text
            PCK file via furnsh_c.

          - FK data: if either of the reference frames designated by
            `frame1' or `frame2' are not built in to the SPICE system,
            one or more FKs specifying these frames must be loaded.

       The following data may be required:

          - DSK data: if either `shape1' or `shape2' indicates that DSK
            data are to be used, DSK files containing topographic data
            for the target body must be loaded. If a surface list is
            specified, data for at least one of the listed surfaces must
            be loaded.

          - Surface name-ID associations: if surface names are specified
            in `shape1' or `shape2', the association of these names with
            their corresponding surface ID codes must be established by
            assignments of the kernel variables

               NAIF_SURFACE_NAME
               NAIF_SURFACE_CODE
               NAIF_SURFACE_BODY

            Normally these associations are made by loading a text
            kernel containing the necessary assignments. An example
            of such a set of assignments is

               NAIF_SURFACE_NAME += 'Mars MEGDR 128 PIXEL/DEG'
               NAIF_SURFACE_CODE += 1
               NAIF_SURFACE_BODY += 499

          - CK data: either of the body-fixed frames to which `frame2' or
            `frame1' refer might be a CK frame. If so, at least one CK
            file will be needed to permit transformation of vectors
            between that frame and the J2000 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).

       Kernel data are normally loaded once per program run, NOT every
       time this routine is called.

#### 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\""

          Escaped 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"

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

       1) Find whether MRO is occulted by Mars as seen by
          the DSS-13 ground station at a few specific
          times.

             KPL/MK

             File: mro_ex_occult.tm

             This is the meta-kernel file for the example problem for
             the subroutine occult_c. These kernel files can be found in
             the NAIF archives.

             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

          Example code begins here.

             #include <stdio.h>
             #include "SpiceUsr.h"

             int main()
             {
                /.
                Constants

                `abcorr' is the desired light time and stellar
                aberration correction setting.

                METAKR is the name of the meta-kernel.
                ./
                #define ABCORR "CN+S"
                #define METAKR "mro_ex_occult.tm"
                #define TIMLEN  41

                /.
                Local variables
                ./
                SpiceChar             * abcorr      = "CN";
                SpiceChar             * time_format = "YYYY-MON-DD HR:MN ::UTC-8";
                SpiceChar             * obsrvr      = "DSS-13";
                SpiceChar             * out_format  = "%s %s %s %s wrt %s\n";
                SpiceChar             * shape1      = "point";
                SpiceChar             * shape2      = "ellipsoid";
                SpiceChar             * targ1       = "MRO";
                SpiceChar             * targ2       = "Mars";
                SpiceChar               time[TIMLEN];

                static SpiceChar      * ouputStr[4] =
                                        {
                                           "totally occulted by",
                                           "transited by",
                                           "partially occulted by",
                                           "not occulted by"
                                        };

                SpiceDouble             et;
                SpiceDouble             et_start;
                SpiceDouble             et_stop;

                SpiceInt                dt = 1000;
                SpiceInt                ocltid;

                /.
                Load kernel files via the meta-kernel.
                ./
                furnsh_c ( METAKR );

                /.
                Calculate the type of occultation that
                corresponds to time ET.
                ./
                str2et_c ( "2012-JAN-5 1:15:00 UTC", &et_start );
                str2et_c ( "2012-JAN-5 2:50:00 UTC", &et_stop  );

                et = et_start;
                while ( et < et_stop ) {
                   /.
                   Calculate the type of occultation that
                   corresponds to time ET.
                   ./
                   occult_c ( targ1, shape1,  " ",
                              targ2, shape2,  "IAU_MARS",
                              abcorr,  obsrvr, et, &ocltid );

                   /.
                   Output the results.
                   ./
                   timout_c ( et, time_format, TIMLEN, time );

                   switch ( ocltid ) {

                      case SPICE_OCCULT_TOTAL1:

                         printf( out_format, time, targ1, ouputStr[0],
                                             targ2, obsrvr );
                         break;

                      case SPICE_OCCULT_ANNLR1:

                         printf( out_format, time, targ1, ouputStr[1],
                                             targ2, obsrvr );
                         break;

                      case SPICE_OCCULT_PARTL1:

                         printf( out_format, time, targ1, ouputStr[2],
                                             targ2, obsrvr );
                         break;

                      case SPICE_OCCULT_NOOCC:

                         printf( out_format, time, targ1, ouputStr[3],
                                             targ2, obsrvr );
                         break;

                      case SPICE_OCCULT_PARTL2:

                         printf( out_format, time, targ2, ouputStr[2],
                                             targ1, obsrvr );
                         break;

                      case SPICE_OCCULT_ANNLR2:

                         printf( out_format, time, targ2, ouputStr[1],
                                             targ1, obsrvr );
                         break;

                      case SPICE_OCCULT_TOTAL2:

                         printf( out_format, time, targ2, ouputStr[0],
                                             targ1, obsrvr );
                         break;

                      default:

                         printf( "Bad occultation code: %d", ocltid );
                         break;

                   }
                   /.
                   Increment the time.
                   ./
                   et += dt;
                }

                return 0;
             }

          When this program was executed on a Linux/PC gcc platform, the
          output was:

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

#### Restrictions

       None.

#### Literature_References

       None.

#### Author_and_Institution

       S.C. Krening  (JPL)
       N.J. Bachman  (JPL)

#### Version

     -CSPICE Version 2.0.0  29-FEB-2016 (NJB)

       Upgraded to support surfaces represented by DSKs. Renamed some
       arguments. Updated example program to show use of DSKs. Updated
       example meta-kernel. Corrected various comment typos.

     -CSPICE Version 1.0.0  1-FEB-2012 (SCK) (NJB)

#### Index_Entries

       occultation type at a specified time

#### Link to routine occult_c source file occult_c.c

    Wed Apr  5 17:54:39 2017