Main Page
Geometric Event Finding Hands-On Lesson (FORTRAN)

Table of Contents 

   Geometric Event Finding Hands-On Lesson (FORTRAN)
      Overview
      Note About HTML Links
      References
         Tutorials
         Required Readings
         The Permuted Index
         Source Code Header Comments
      Kernels Used
      SPICE Routines Used
   Find View Periods
      Task Statement
      Learning Goals
      Approach
         Solution steps
      Solution
         Solution Meta-Kernel
         Solution Code
         Solution Sample Output
   Find Times when Target is Visible
      Task Statement
      Learning Goals
      Approach
         Solution steps
      Solution
         Solution Code
         Solution Sample Output


Top

Geometric Event Finding Hands-On Lesson (FORTRAN)




May 12, 2009



Top

Overview



This lesson illustrates how the Geometry Finder (GF) subsystem of the SPICE Toolkit can be used to find time intervals when specified geometric conditions are satisfied.

In this lesson the student is asked to construct a program that finds the time intervals, within a specified time range, when the Mars Express Orbiter (MEX) is visible from the DSN station DSS-14. Possible occultation of the spacecraft by Mars is to be considered.



Top

Note About HTML Links



The HTML version of this lesson contains links pointing to various HTML documents provided with the Toolkit. All of these links are relative and, in order to function, require this document to be in a certain location in the Toolkit HTML documentation directory tree.

In order for the links to be resolved, create a subdirectory called ``lessons'' under the ``doc/html'' directory of the ``toolkit/'' tree and copy this document to that subdirectory before loading it into a Web browser.



Top

References





Top

Tutorials



The following SPICE tutorials serve as references for the discussions in this lesson: 

 
   Name             Lesson steps/routines it describes
   ---------------  -----------------------------------------
   Time             Time Conversion
   SCLK and LSK     Time Conversion
   SPK              Obtaining Ephemeris Data
   Frames           Reference Frames
   Using Frames     Reference Frames
   PCK              Planetary Constants Data
   Lunar-Earth PCK  Lunar and Earth Orientation Data
   GF               The SPICE Geometry Ginder (GF) subsystem
These tutorials are available from the NAIF ftp server at JPL: 

   http://naif.jpl.nasa.gov/naif/tutorials.html


Top

Required Readings



The Required Reading documents are provided with the SPICE Toolkit and are located under the ``toolkit/doc'' directory in the FORTRAN installation tree. 

   Name             Lesson steps/routines that it describes
   ---------------  -----------------------------------------
   cells.req        Cell/window initialization
   frames.req       Using reference frames
   gf.req           The SPICE geometry finder (GF) subsystem
   kernel.req       Loading SPICE kernels
   naif_ids.req     Body and reference frame names
   pck.req          Obtaining planetary constants data
   spk.req          Computing positions and velocities
   time.req         UTC to ET time conversion
   windows.req      The SPICE window data type


Top

The Permuted Index



Another useful document distributed with the Toolkit is the permuted index. This is located under the ``toolkit/doc'' directory in the FORTRAN installation tree.

This text document provides a simple mechanism by which users can discover which SPICE routines perform functions of interest, as well as the names of the source files that contain these routines. This is particularly useful for FORTRAN programmers because some of the routines are entry points; the names of these routines do not translate directly into the name of the respective source files that contain them.



Top

Source Code Header Comments



The most detailed specification of a given SPICE FORTRAN routine is contained in the header section of its source code. The source code is distributed with the Toolkit and is located under the ``toolkit/src/spicelib'' path.

For example path of the source code of the STR2ET routine is 

   toolkit/src/spicelib/str2et.for


Top

Kernels Used



The following kernels are used in examples provided in this lesson: 

   File Name                       Type  Description
   -----------------------         ----  --------------------------
   de405xs.bsp                     SPK   Planetary ephemeris SPK,
                                         subsetted to cover only
                                         time range of interest
   earthstns_itrf93_050714.bsp     SPK   DSN station SPK
   earth_topo_050714.tf            FK    DSN station frame definitions
   earth_000101_060525_060303.bpc  PCK   Binary PCK for Earth
   ORMM__040501000000_00076XS.BSP  SPK   MEX Orbiter trajectory SPK,
                                         subsetted to cover only
                                         time range of interest
   naif0008.tls                    LSK   Generic LSK
   pck00008.tpc                    PCK   Generic PCK
These SPICE kernels are included in the lesson package available from the NAIF server at JPL: 

   ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons/


Top

SPICE Routines Used



This section provides a summary of the routines that are suggested for usage in each of the exercises in this tutorial. (You may wish to not look at this list unless/until you ``get stuck'' while working on your own.) 

   Name        Function that it performs
   ----------  ---------------------------------------------------
   FURNSH      Loads kernels, individually or listed in meta-kernel
   GFOCLT      Solve for times of occultation or transit
   GFPOSC      Solve for times when a position vector coordinate
               constraint is met
   REPMC       Substitute a substring for a marker in a string
   REPMF       Substitute double precision value for marker in string
   RPD         Return number of radians per degree
   SSIZED      Set the size of a d.p. cell
   STR2ET      Converts a time string to ET seconds past J2000
   TIMOUT      Format a time string for output
   TOSTDO      Write a string to standard output
   WNCARD      Return cardinality of a SPICE window
   WNDIFD      Find the difference of two d.p. windows
   WNFETD      Fetch a specified interval from a d.p. window
   WNINSD      Insert an interval into a d.p. window
Refer to the headers of the various routines listed above, as detailed interface specifications are provided with the source code.



Top

Find View Periods






Top

Task Statement



Write a program that finds the set of time intervals, within the time range 

   2004 MAY 2 TDB
   2004 MAY 6 TDB
when the Mars Express Orbiter (MEX) is visible from the DSN station DSS-14. These time intervals are frequently called ``view periods.''

The spacecraft is considered visible if its apparent position (that is, its position corrected for light time and stellar aberration) has elevation of at least 6 degrees in the topocentric reference frame DSS-14_TOPO. In this exercise, we ignore the possibility of occultation of the spacecraft by Mars.

Use a search step size that ensures that no view periods of duration 5 minutes or longer will be missed by the search.

Display the start and stop times of these intervals using TDB calendar dates and millisecond precision.



Top

Learning Goals



Exposure to SPICE GF event finding routines. Familiarity with SPICE windows and routines that manipulate them. Exposure to SPICE time parsing and output formatting routines.



Top

Approach





Top

Solution steps



A possible solution could consist of the following steps:

Preparation:

    1. Review the SPICELIB cell and window Required Reading.

    2. Decide what SPICE kernels are necessary. Use the SPICE summary tool BRIEF to examine the coverage of the binary kernels and verify the availability of required data.

    3. Create a meta-kernel listing the SPICE kernels to be loaded. (Hint: consult a programming example tutorial, or the Introduction to Kernels tutorial, for a reminder of how to do this.)

    Name the meta-kernel 'viewpr.tm'.

Next, write a program that performs the following steps:

    1. Use FURNSH to load the meta-kernel.

    2. Declare a SPICELIB window ``CNFINE'' to hold the time period within which the search is to be conducted, and a SPICELIB window RISWIN ("rise/set window") to hold the view periods found by the search. Initialize the confinement and result windows using SSIZED.

    3. Insert the given time bounds into the confinement window using WNINSD.

    4. Select a step size for searching for visibility state transitions: in this case, each target rise or set event is a state transition.

    The step size must be large enough so the search proceeds with reasonable speed, but small enough so that no visibility transition events---that is, target rise or set events---are missed.

    5. Use the GF routine GFPOSC to find the window of times, within the confinement window CNFINE, during which the MEX spacecraft is above the elevation limit as seen from DSN station DSS-14, in the the reference frame DSS-14_TOPO.

    Use light time and stellar aberration corrections for the apparent position of the spacecraft as seen from the station.

    6. Fetch and display the contents of the result window. Use WNFETD to extract from the result window the start and stop times of each time interval. Display each of the intervals in the result window as a pair of start and stop times. Express each time as a TDB calendar date using the routine TIMOUT.

    The SPICELIB ``replace marker'' routines REPxxx are useful for substituting values into output strings. Consult, for example, the header of REPMC.

You may find it useful to consult the references listed above. In particular, the header of the SPICE GF routine GFPOSC contains pertinent documentation.



Top

Solution





Top

Solution Meta-Kernel



The meta-kernel we created for the solution to this exercise is named 'viewpr.tm'. Its contents follow: 

 
   KPL/MK
 
      Example meta-kernel for geometric event finding hands-on
      coding lesson.
 
         Version 2.0.0 15-MAR-2008 (NJB)
 
 
      Identify names of kernels to load:
 
   \begindata
 
      KERNELS_TO_LOAD = (
 
              'kernels/spk/de405xs.bsp'
              'kernels/spk/earthstns_itrf93_050714.bsp'
              'kernels/fk/earth_topo_050714.tf'
              'kernels/pck/earth_000101_060525_060303.bpc'
              'kernels/lsk/naif0008.tls'
              'kernels/spk/ORMM__040501000000_00076XS.BSP'
              'kernels/pck/pck00008.tpc'
                        )
 
   \begintext


Top

Solution Code



The example program below shows one possible solution. 

 
         PROGRAM VIEWPR
         IMPLICIT NONE
   C
   C     Find and display the window of times when the MEX
   C     spacecraft is above a specified elevation limit in the
   C     topocentric reference frame of DSN station DSS-14.
   C
 
   C
   C     SPICELIB functions
   C
         DOUBLE PRECISION      RPD
         INTEGER               WNCARD
 
   C
   C     Global GF parameters: we import from this file
   C     the definition of the GF workspace size parameter
   C
   C        NWMAX
   C
         INCLUDE 'gf.inc'
 
   C
   C     Local parameters
   C
   C     Format string for time output:
   C
         CHARACTER*(*)         TDBFMT
         PARAMETER           ( TDBFMT =
        .                    'YYYY MON DD HR:MN:SC.### (TDB) ::TDB' )
 
   C
   C     The meta-kernel:
   C
         CHARACTER*(*)         METAKR
         PARAMETER           ( METAKR = 'viewpr.tm' )
 
 
   C
   C     Maximum number of intervals in any window:
   C
         INTEGER               MAXIVL
         PARAMETER           ( MAXIVL = 1000 )
 
   C
   C     Maximum result window size:
   C
         INTEGER               MAXWIN
         PARAMETER           ( MAXWIN = 2 * MAXIVL )
 
   C
   C     SPICELIB cell bound:
   C
         INTEGER               LBCELL
         PARAMETER           ( LBCELL = -5 )
 
   C
   C     String length parameters:
   C
         INTEGER               CORLEN
         PARAMETER           ( CORLEN = 10 )
 
         INTEGER               FRNMLN
         PARAMETER           ( FRNMLN = 32 )
 
         INTEGER               LNSIZE
         PARAMETER           ( LNSIZE = 200 )
 
         INTEGER               NAMLEN
         PARAMETER           ( NAMLEN = 32 )
 
         INTEGER               OPLEN
         PARAMETER           ( OPLEN  = 50 )
 
         INTEGER               TIMLEN
         PARAMETER           ( TIMLEN = 50 )
 
   C
   C     Local variables
   C
         CHARACTER*(CORLEN)    ABCORR
         CHARACTER*(NAMLEN)    CRDSYS
         CHARACTER*(NAMLEN)    COORD
         CHARACTER*(LNSIZE)    LINE
         CHARACTER*(FRNMLN)    OBSFRM
         CHARACTER*(OPLEN)     RELATE
         CHARACTER*(NAMLEN)    SRFPT
         CHARACTER*(TIMLEN)    START
         CHARACTER*(TIMLEN)    STOP
         CHARACTER*(NAMLEN)    TARGET
         CHARACTER*(TIMLEN)    TIMSTR
         CHARACTER*(LNSIZE)    TITLE
 
         DOUBLE PRECISION      ADJUST
 
   C
   C     Confinement window used to store interval to be searched:
   C
         DOUBLE PRECISION      CNFINE ( LBCELL : MAXWIN )
         DOUBLE PRECISION      ELVLIM
         DOUBLE PRECISION      ETBEG
         DOUBLE PRECISION      ETEND
         DOUBLE PRECISION      INTBEG
         DOUBLE PRECISION      INTEND
         DOUBLE PRECISION      REVLIM
 
   C
   C     STEPSZ is the step size, measured in seconds, used to search
   C     for times bracketing a state transition.
   C
         DOUBLE PRECISION      STEPSZ
 
   C
   C     Result window used to store rise/set times:
   C
         DOUBLE PRECISION      RISWIN ( LBCELL : MAXWIN )
 
   C
   C     Workspace array:
   C
         DOUBLE PRECISION      WORK   ( LBCELL : MAXWIN,  NWMAX )
 
 
         INTEGER               I
         INTEGER               WINSIZ
 
   C
   C     Load the meta-kernel.
   C
         CALL FURNSH ( METAKR )
 
   C
   C     Assign the inputs for our search.
   C
   C     Since we're interested in the apparent location of the
   C     target, we use light time and stellar aberration
   C     corrections.  We use the "converged Newtonian" form
   C     of the light time correction because this choice may
   C     increase the accuracy of the occultation times we'll
   C     compute using GFOCLT.
   C
         SRFPT  = 'DSS-14'
         OBSFRM = 'DSS-14_TOPO'
         TARGET = 'MEX'
         ABCORR = 'CN+S'
         START  = '2004 MAY 2 TDB'
         STOP   = '2004 MAY 6 TDB'
         ELVLIM =  6.0D0
   C
   C     The elevation limit above has units of degrees; we convert
   C     this value to radians for computation using SPICE routines.
   C     We'll store the equivalent value in radians in REVLIM.
   C
         REVLIM = RPD() * ELVLIM
 
   C
   C     Since SPICE doesn't directly support the AZ/EL coordinate
   C     system, we use the equivalent constraint
   C
   C        latitude > REVLIM
   C
   C     in the latitudinal coordinate system, where the reference
   C     frame is topocentric and is centered at the viewing location.
   C
         CRDSYS = 'LATITUDINAL'
         COORD  = 'LATITUDE'
         RELATE = '>'
 
   C
   C     The adjustment value only applies to absolute extrema
   C     searches; simply give it an initial value of zero
   C     for this inequality search.
   C
         ADJUST = 0.D0
 
   C
   C     STEPSZ is the step size, measured in seconds, used to search
   C     for times bracketing a state transition. Since we don't expect
   C     any events of interest to be shorter than five minutes, and
   C     since the separation between events is well over 5 minutes,
   C     we'll use this value as our step size. Units are seconds.
   C
         STEPSZ = 300.D0
 
   C
   C     Display a banner for the output report:
   C
         TITLE  = 'Inputs for target visibility search:'
         CALL TOSTDO ( ' '   )
         CALL TOSTDO ( TITLE )
         CALL TOSTDO ( ' '   )
 
         LINE   = '   Target                       = #'
         CALL REPMC  ( LINE, '#', TARGET, LINE )
         CALL TOSTDO ( LINE )
 
         LINE   = '   Observation surface location = #'
         CALL REPMC  ( LINE, '#', SRFPT,  LINE )
         CALL TOSTDO ( LINE )
 
         LINE   = '   Observer''s reference frame   = #'
         CALL REPMC  ( LINE, '#', OBSFRM,  LINE )
         CALL TOSTDO ( LINE )
 
         LINE   = '   Elevation limit (degrees)    = #'
         CALL REPMF ( LINE, '#', ELVLIM, 7, 'F', LINE )
         CALL TOSTDO ( LINE )
 
         LINE   = '   Aberration correction        = #'
         CALL REPMC  ( LINE, '#', ABCORR, LINE )
         CALL TOSTDO ( LINE )
 
         LINE   = '   Step size (seconds)          = #'
         CALL REPMF ( LINE, '#', STEPSZ, 9, 'F', LINE )
         CALL TOSTDO ( LINE )
 
   C
   C     Convert the start and stop times to ET.
   C
         CALL STR2ET ( START, ETBEG )
         CALL STR2ET ( STOP,  ETEND )
 
   C
   C     Display the search interval start and stop times
   C     using the format shown below.
   C
   C        2004 MAY 06 20:15:00.000 (TDB)
   C
         CALL TIMOUT ( ETBEG, TDBFMT, TIMSTR )
         LINE = '   Start time                   = '//TIMSTR
         CALL TOSTDO ( LINE )
 
         CALL TIMOUT ( ETEND, TDBFMT, TIMSTR )
         LINE = '   Stop time                    = '//TIMSTR
         CALL TOSTDO ( LINE )
 
         CALL TOSTDO ( ' ' )
 
   C
   C     Every SPICELIB window must have its size initialized.
   C
   C     Initialize the "confinement" window with the interval
   C     over which we'll conduct the search.
   C
         CALL SSIZED ( MAXWIN, CNFINE )
 
         CALL WNINSD ( ETBEG,  ETEND, CNFINE )
 
   C
   C     Initialize the result window; this window will contain
   C     the rise/set times found by our search.
   C
         CALL SSIZED ( MAXWIN, RISWIN )
 
   C
   C     In the call below, the workspace dimensions are
   C
   C        ( MAXWIN, NWMAX )
   C
   C     Now search for the time period, within our confinement
   C     window, during which the apparent target has elevation
   C     at least equal to the elevation limit.
   C
         CALL GFPOSC ( TARGET, OBSFRM, ABCORR, SRFPT,
        .              CRDSYS, COORD,  RELATE, REVLIM,
        .              ADJUST, STEPSZ, CNFINE, MAXWIN,
        .              NWMAX,  WORK,   RISWIN         )
 
   C
   C     The function WNCARD returns the number of intervals
   C     in a SPICE window.
   C
         WINSIZ = WNCARD( RISWIN )
 
         IF ( WINSIZ .EQ. 0 ) THEN
 
            WRITE (*,*) 'No events were found.'
 
         ELSE
   C
   C        Display the view periods.
   C
            LINE = 'Visibility times of # as seen from #:'
            CALL REPMC ( LINE, '#', TARGET, LINE )
            CALL REPMC ( LINE, '#', SRFPT,  LINE )
 
            CALL TOSTDO ( LINE )
            CALL TOSTDO ( ' '  )
 
            DO I = 1, WINSIZ
   C
   C           Fetch the start and stop times of the Ith interval
   C           from the search result window VISWIN.
   C
               CALL WNFETD ( RISWIN, I, INTBEG, INTEND )
 
   C
   C           Convert the rise time to a TDB calendar string.
   C
               CALL TIMOUT ( INTBEG, TDBFMT, TIMSTR )
 
   C
   C           Write the string to standard output.
   C
               IF ( I .EQ. 1 ) THEN
                  LINE = 'Visibility or window start time:  #'
               ELSE
                  LINE = 'Visibility start time:            #'
               END IF
 
               CALL REPMC ( LINE, '#', TIMSTR, LINE )
               CALL TOSTDO ( LINE )
 
   C
   C           Convert the set time to a TDB calendar string.
   C
               CALL TIMOUT ( INTEND, TDBFMT, TIMSTR )
   C
   C           Write the string to standard output.
   C
               IF ( I .EQ. WINSIZ ) THEN
                  LINE = 'Visibility or window stop time:   #'
               ELSE
                  LINE = 'Visibility stop time:             #'
               END IF
 
               CALL REPMC ( LINE, '#', TIMSTR, LINE )
               CALL TOSTDO ( LINE )
 
               CALL TOSTDO ( ' ' )
 
            END DO
 
         END IF
 
         END


Top

Solution Sample Output



Numerical results shown for this example may differ across platforms since the results depend on the SPICE kernels used as input and on the host platform's arithmetic implementation.

After compiling the program, execute it. The output is: 

 
 
   Inputs for target visibility search:
 
      Target                       = MEX
      Observation surface location = DSS-14
      Observer's reference frame   = DSS-14_TOPO
      Elevation limit (degrees)    = 6.000000
      Aberration correction        = CN+S
      Step size (seconds)          = 300.000000
      Start time                   = 2004 MAY 02 00:00:00.000 (TDB)
      Stop time                    = 2004 MAY 06 00:00:00.000 (TDB)
 
   Visibility times of MEX as seen from DSS-14:
 
   Visibility or window start time:  2004 MAY 02 00:00:00.000 (TDB)
   Visibility stop time:             2004 MAY 02 05:35:03.096 (TDB)
 
   Visibility start time:            2004 MAY 02 16:09:14.078 (TDB)
   Visibility stop time:             2004 MAY 03 05:33:57.257 (TDB)
 
   Visibility start time:            2004 MAY 03 16:08:02.279 (TDB)
   Visibility stop time:             2004 MAY 04 05:32:50.765 (TDB)
 
   Visibility start time:            2004 MAY 04 16:06:51.259 (TDB)
   Visibility stop time:             2004 MAY 05 05:31:43.600 (TDB)
 
   Visibility start time:            2004 MAY 05 16:05:40.994 (TDB)
   Visibility or window stop time:   2004 MAY 06 00:00:00.000 (TDB)


Top

Find Times when Target is Visible






Top

Task Statement



Extend the program of the previous chapter to find times when the MEX orbiter is:

    -- Above the elevation limit in the DSS-14_TOPO topocentric reference frame.

    -- and is not occulted by Mars

Store the set of time intervals when the spacecraft is visible in a SPICELIB window. We'll call this the ``result window.''

Display each of the intervals in the result window as a pair of start and stop times. Express each time as a TDB calendar date using the same format as in the previous program.



Top

Learning Goals



Familiarity with the GF occultation finding routine GFOCLT. Further experience with the SPICELIB window routines.



Top

Approach





Top

Solution steps



A possible solution would consist of the following steps:

    1. Use the meta-kernel of the previous lesson.

    2. Include the code from the program of the previous chapter in a new source file; modify this code to create the new program.

    3. Declare a SPICELIB window OCCWIN to hold the results of the occultation search. Also declare a second SPICELIB window VISWIN to hold the final result. Initialize OCCWIN and VISWIN using SSIZED.

    4. Search for occultations of the MEX orbiter as seen from DSS-14 using GFOCLT. Use as the confinement window for this search the result window from the elevation search performed by GFPOSC.

    Since occultations occur when the apparent MEX spacecraft position is behind the apparent figure of Mars, light time correction must be performed for the occultation search. To improve accuracy of the occultation state determination, use ``converged Newtonian'' light time correction.

    5. Use the SPICELIB window subtraction routine WNDIFD to subtract the window of times when the spacecraft is occulted from the window of times when the spacecraft is above the elevation limit. The difference window VISWIN is the final result.

    6. Modify the code to display the contents of the window VISWIN.

This completes the assignment.



Top

Solution





Top

Solution Code 



 
         PROGRAM VISIBL
         IMPLICIT NONE
   C
   C     Find and display the window of times when the MEX
   C     spacecraft is above a specified elevation limit in the
   C     topocentric reference frame of DSN station DSS-14
   C     and is not occulted by Mars.
   C
 
   C
   C     SPICELIB functions
   C
         DOUBLE PRECISION      RPD
         INTEGER               WNCARD
 
   C
   C     Global GF parameters: we import from this file
   C     the definition of the GF workspace size parameter
   C
   C        NWMAX
   C
   C     and the occultation parameters
   C
   C        OCCLN
   C        SHPLEN
   C
         INCLUDE 'gf.inc'
 
   C
   C     Local parameters
   C
   C     Format string for time output:
   C
         CHARACTER*(*)         TDBFMT
         PARAMETER           ( TDBFMT =
        .                    'YYYY MON DD HR:MN:SC.### (TDB) ::TDB' )
 
   C
   C     The meta-kernel:
   C
         CHARACTER*(*)         METAKR
         PARAMETER           ( METAKR = 'viewpr.tm' )
 
 
   C
   C     Maximum number of events we can handle in our event set:
   C
         INTEGER               MAXEVT
         PARAMETER           ( MAXEVT = 1000 )
 
   C
   C     Maximum result window size:
   C
         INTEGER               MAXWIN
         PARAMETER           ( MAXWIN = 2 * MAXEVT )
 
   C
   C     SPICELIB cell bound:
   C
         INTEGER               LBCELL
         PARAMETER           ( LBCELL = -5 )
 
   C
   C     String length parameters:
   C
         INTEGER               BDNMLN
         PARAMETER           ( BDNMLN = 36 )
 
         INTEGER               CORLEN
         PARAMETER           ( CORLEN = 10 )
 
         INTEGER               FRNMLN
         PARAMETER           ( FRNMLN = 32 )
 
         INTEGER               LNSIZE
         PARAMETER           ( LNSIZE = 200 )
 
         INTEGER               NAMLEN
         PARAMETER           ( NAMLEN = 32 )
 
         INTEGER               OPLEN
         PARAMETER           ( OPLEN  = 50 )
 
         INTEGER               TIMLEN
         PARAMETER           ( TIMLEN = 50 )
 
   C
   C     Local variables
   C
         CHARACTER*(CORLEN)    ABCORR
         CHARACTER*(BDNMLN)    BACK
         CHARACTER*(FRNMLN)    BFRAME
         CHARACTER*(BDNMLN)    BSHAPE
         CHARACTER*(NAMLEN)    CRDSYS
         CHARACTER*(NAMLEN)    COORD
         CHARACTER*(FRNMLN)    FFRAME
         CHARACTER*(FRNMLN)    FRAME
         CHARACTER*(BDNMLN)    FRONT
         CHARACTER*(SHPLEN)    FSHAPE
         CHARACTER*(LNSIZE)    LINE
         CHARACTER*(OCLLN)     OCCTYP
         CHARACTER*(OPLEN)     RELATE
         CHARACTER*(NAMLEN)    SRFPT
         CHARACTER*(TIMLEN)    START
         CHARACTER*(TIMLEN)    STOP
         CHARACTER*(NAMLEN)    TARGET
         CHARACTER*(TIMLEN)    TIMSTR
         CHARACTER*(LNSIZE)    TITLE
 
         DOUBLE PRECISION      ADJUST
 
   C
   C     Confinement window used to store interval to be searched:
   C
         DOUBLE PRECISION      CNFINE ( LBCELL : MAXEVT )
         DOUBLE PRECISION      ELVLIM
         DOUBLE PRECISION      ETBEG
         DOUBLE PRECISION      ETEND
         DOUBLE PRECISION      INTBEG
         DOUBLE PRECISION      INTEND
         DOUBLE PRECISION      REVLIM
 
   C
   C     STEPSZ is the step size, measured in seconds, used to search
   C     for times bracketing a state transition.
   C
         DOUBLE PRECISION      STEPSZ
 
   C
   C     Result window used to store occultation times:
   C
         DOUBLE PRECISION      OCCWIN ( LBCELL : MAXWIN )
 
   C
   C     Result window used to store rise/set times:
   C
         DOUBLE PRECISION      RISWIN ( LBCELL : MAXWIN )
 
   C
   C     Result window used to store visibility periods:
   C
         DOUBLE PRECISION      VISWIN ( LBCELL : MAXWIN )
 
   C
   C     Workspace array:
   C
         DOUBLE PRECISION      WORK   ( LBCELL : MAXWIN,  NWMAX )
 
 
         INTEGER               I
         INTEGER               WINSIZ
 
   C
   C     Load the meta-kernel.
   C
         CALL FURNSH ( METAKR )
 
   C
   C     Assign the inputs for our search.
   C
         SRFPT  = 'DSS-14'
         FRAME  = 'DSS-14_TOPO'
         TARGET = 'MEX'
         ABCORR = 'CN+S'
         START  = '2004 MAY 2 TDB'
         STOP   = '2004 MAY 6 TDB'
         ELVLIM =  6.0D0
   C
   C     The elevation limit above has units of degrees; we convert
   C     this value to radians for computation using SPICE routines.
   C     We'll store the equivalent value in radians in REVLIM.
   C
         REVLIM = RPD() * ELVLIM
 
   C     Since we're interested in the apparent location of the
   C     target, we use light time and stellar aberration
   C     corrections.
   C
   C     Since SPICE doesn't directly support the AZ/EL coordinate
   C     system, we use the equivalent constraint
   C
   C        latitude > REVLIM
   C
   C     in the latitudinal coordinate system, where the reference
   C     frame is topocentric and is centered at the viewing location.
   C
         CRDSYS = 'LATITUDINAL'
         COORD  = 'LATITUDE'
         RELATE = '>'
 
   C
   C     STEPSZ is the step size, measured in seconds, used to search
   C     for times bracketing a state transition. Since we don't expect
   C     any events of interest to be shorter than five minutes, and
   C     since the separation between events is well over 5 minutes,
   C     we'll use this value as our step size. Units are seconds.
   C
         STEPSZ = 300.D0
 
   C
   C     We model the target shape as a point and the blocking body's
   C     shape as an ellipsoid. No body-fixed reference frame is
   C     required for the target since its orientation is not used.
   C
         BACK   = TARGET
         BSHAPE = 'POINT'
         BFRAME = ' '
         FRONT  = 'MARS'
         FSHAPE = 'ELLIPSOID'
         FFRAME = 'IAU_MARS'
 
   C
   C     The occultation type should be set to 'ANY' for a point
   C     target.
   C
         OCCTYP = 'ANY'
 
   C
   C     Display a banner for the output report:
   C
         TITLE  = 'Inputs for target visibility search:'
         CALL TOSTDO ( ' '   )
         CALL TOSTDO ( TITLE )
         CALL TOSTDO ( ' '   )
 
         LINE   = '   Target                       = #'
         CALL REPMC  ( LINE, '#', TARGET, LINE )
         CALL TOSTDO ( LINE )
 
         LINE   = '   Observation surface location = #'
         CALL REPMC  ( LINE, '#', SRFPT,  LINE )
         CALL TOSTDO ( LINE )
 
         LINE   = '   Observer''s reference frame   = #'
         CALL REPMC  ( LINE, '#', FRAME,  LINE )
         CALL TOSTDO ( LINE )
 
         LINE   = '   Blocking body                = #'
         CALL REPMC  ( LINE, '#', FRONT, LINE )
         CALL TOSTDO ( LINE )
 
         LINE   = '   Blocker''s reference frame    = #'
         CALL REPMC  ( LINE, '#', FFRAME,  LINE )
         CALL TOSTDO ( LINE )
 
         LINE   = '   Elevation limit (degrees)    = #'
         CALL REPMF ( LINE, '#', ELVLIM, 7, 'F', LINE )
         CALL TOSTDO ( LINE )
 
         LINE   = '   Aberration correction        = #'
         CALL REPMC  ( LINE, '#', ABCORR, LINE )
         CALL TOSTDO ( LINE )
 
         LINE   = '   Step size (seconds)          = #'
         CALL REPMF ( LINE, '#', STEPSZ, 9, 'F', LINE )
         CALL TOSTDO ( LINE )
 
   C
   C     Convert the start and stop times to ET.
   C
         CALL STR2ET ( START, ETBEG )
         CALL STR2ET ( STOP,  ETEND )
 
   C
   C     Display the search interval start and stop times
   C     using the format shown below.
   C
   C        2004 MAY 06 20:15:00.000 (TDB)
   C
         CALL TIMOUT ( ETBEG, TDBFMT, TIMSTR )
         LINE = '   Start time                   = '//TIMSTR
         CALL TOSTDO ( LINE )
 
         CALL TIMOUT ( ETEND, TDBFMT, TIMSTR )
         LINE = '   Stop time                    = '//TIMSTR
         CALL TOSTDO ( LINE )
 
         CALL TOSTDO ( ' ' )
 
   C
   C     Every SPICELIB window must have its size initialized.
   C
   C     Initialize the "confinement" window with the interval
   C     over which we'll conduct the search.
   C
         CALL SSIZED ( MAXWIN, CNFINE )
 
         CALL WNINSD ( ETBEG,  ETEND, CNFINE )
 
   C
   C     Initialize the result window; this window will contain
   C     the rise/set times found by our search.
   C
         CALL SSIZED ( MAXWIN, RISWIN )
 
   C
   C     Initialize the occultation and visibility windows.
   C
         CALL SSIZED ( MAXWIN, OCCWIN )
         CALL SSIZED ( MAXWIN, VISWIN )
 
   C
   C     The adjustment value only applies to absolute extrema
   C     searches;  simply give it an initial value of zero
   C     for this inequality search.
   C
         ADJUST = 0.D0
 
   C
   C     Note that the workspace dimensions are ( MAXWIN, NWMAX ).
   C
   C     Now search for the time period, within our confinement
   C     window, during which the apparent target has elevation
   C     at least equal to the elevation limit.
   C
         CALL GFPOSC ( TARGET, FRAME,  ABCORR, SRFPT,
        .              CRDSYS, COORD,  RELATE, REVLIM,
        .              ADJUST, STEPSZ, CNFINE, MAXWIN,
        .              NWMAX,  WORK,   RISWIN         )
 
   C
   C     Now find the times when the apparent target is above
   C     the elevation limit and is not occulted by the
   C     blocking body (Mars). We'll find the times when the target
   C     is above the elevation limit and *is* occulted, then subtract
   C     that window from the view period window RISWIN found above.
   C
   C     For this occultation search, we can use RISWIN as
   C     the confinement window because we're not interested in
   C     occultations that occur when the target is below the
   C     elevation limit.
   C
   C     Find occultations within the view period window.
   C
         CALL GFOCLT ( OCCTYP, FRONT,  FSHAPE, FFRAME,
        .              BACK,   BSHAPE, BFRAME, ABCORR,
        .              SRFPT,  STEPSZ, RISWIN, OCCWIN )
 
   C
   C     Subtract the occultation window from the view period
   C     window: this yields the time periods when the target
   C     is visible.
   C
         CALL WNDIFD ( RISWIN, OCCWIN, VISWIN )
 
   C
   C     The function WNCARD returns the number of intervals
   C     in a SPICE window.
   C
         WINSIZ = WNCARD( VISWIN )
 
         IF ( WINSIZ .EQ. 0 ) THEN
 
            WRITE (*,*) 'No events were found.'
 
         ELSE
   C
   C        Display the visibility time periods.
   C
            LINE = 'Visibility times of # as seen from #:'
            CALL REPMC ( LINE, '#', TARGET, LINE )
            CALL REPMC ( LINE, '#', SRFPT,  LINE )
 
            CALL TOSTDO ( LINE )
            CALL TOSTDO ( ' '  )
 
 
            DO I = 1, WINSIZ
   C
   C           Fetch the start and stop times of the Ith interval
   C           from the search result window VISWIN.
   C
               CALL WNFETD ( VISWIN, I, INTBEG, INTEND )
 
   C
   C           Convert the rise time to a TDB calendar string.
   C
               CALL TIMOUT ( INTBEG, TDBFMT, TIMSTR )
 
   C
   C           Write the string to standard output.
   C
               IF ( I .EQ. 1 ) THEN
                  LINE = 'Visibility or window start time:  #'
               ELSE
                  LINE = 'Visibility start time:            #'
               END IF
 
               CALL REPMC ( LINE, '#', TIMSTR, LINE )
               CALL TOSTDO ( LINE )
 
 
               CALL TIMOUT ( INTEND, TDBFMT, TIMSTR )
   C
   C           Write the string to standard output.
   C
               IF ( I .EQ. WINSIZ ) THEN
                  LINE = 'Visibility or window stop time:   #'
               ELSE
                  LINE = 'Visibility stop time:             #'
               END IF
 
               CALL REPMC ( LINE, '#', TIMSTR, LINE )
               CALL TOSTDO ( LINE )
 
               CALL TOSTDO ( ' ' )
 
            END DO
 
         END IF
 
         END


Top

Solution Sample Output



Numerical results shown for this example may differ across platforms since the results depend on the SPICE kernels used as input and on the host platform's arithmetic implementation.

After compiling the program, execute it. The output is: 

 
   Inputs for target visibility search:
 
      Target                       = MEX
      Observation surface location = DSS-14
      Observer's reference frame   = DSS-14_TOPO
      Blocking body                = MARS
      Blocker's reference frame    = IAU_MARS
      Elevation limit (degrees)    = 6.000000
      Aberration correction        = CN+S
      Step size (seconds)          = 300.000000
      Start time                   = 2004 MAY 02 00:00:00.000 (TDB)
      Stop time                    = 2004 MAY 06 00:00:00.000 (TDB)
 
   Visibility times of MEX as seen from DSS-14:
 
   Visibility or window start time:  2004 MAY 02 00:00:00.000 (TDB)
   Visibility stop time:             2004 MAY 02 04:49:30.827 (TDB)
 
   Visibility start time:            2004 MAY 02 16:09:14.078 (TDB)
   Visibility stop time:             2004 MAY 02 20:00:22.514 (TDB)
 
   Visibility start time:            2004 MAY 02 21:01:38.222 (TDB)
   Visibility stop time:             2004 MAY 03 03:35:42.256 (TDB)
 
   Visibility start time:            2004 MAY 03 04:36:42.484 (TDB)
   Visibility stop time:             2004 MAY 03 05:33:57.257 (TDB)
 
   Visibility start time:            2004 MAY 03 16:08:02.279 (TDB)
   Visibility stop time:             2004 MAY 03 18:46:26.013 (TDB)
 
   Visibility start time:            2004 MAY 03 19:46:54.618 (TDB)
   Visibility stop time:             2004 MAY 04 02:21:44.562 (TDB)
 
   Visibility start time:            2004 MAY 04 03:21:56.347 (TDB)
   Visibility stop time:             2004 MAY 04 05:32:50.765 (TDB)
 
   Visibility start time:            2004 MAY 04 16:06:51.259 (TDB)
   Visibility stop time:             2004 MAY 04 17:32:25.809 (TDB)
 
   Visibility start time:            2004 MAY 04 18:32:05.975 (TDB)
   Visibility stop time:             2004 MAY 05 01:07:48.264 (TDB)
 
   Visibility start time:            2004 MAY 05 02:07:11.601 (TDB)
   Visibility stop time:             2004 MAY 05 05:31:43.600 (TDB)
 
   Visibility start time:            2004 MAY 05 16:05:40.994 (TDB)
   Visibility stop time:             2004 MAY 05 16:18:35.560 (TDB)
 
   Visibility start time:            2004 MAY 05 17:17:27.717 (TDB)
   Visibility or window stop time:   2004 MAY 05 23:54:04.672 (TDB)