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

Table of Contents

   Geometric Event Finding Hands-On Lesson (MATLAB)
      Overview
      Note About HTML Links
      References
         Tutorials
         Required Readings
         The Permuted Index
         Mice API Documentation
      Kernels Used
      Mice 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
   Extra Credit
      Task statements
      Solutions




Top

Geometric Event Finding Hands-On Lesson (MATLAB)





August 31, 2016



Top

Overview




This lesson illustrates how the Geometry Finder (GF) subsystem of the Mice 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 ExoMars-16 Trace Gas Orbiter (TGO) is visible from ESA's deep space station in New Norcia. 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 ``mice/'' 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/functions 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 Toolkit and are located under the ``mice/doc'' directory in the MATLAB installation tree.

   Name             Lesson steps/functions that it describes
   ---------------  -----------------------------------------
   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
   mice.req         The Mice API


Top

The Permuted Index



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

This text document provides a simple mechanism by which users can discover which Mice routines perform functions of interest, as well as the names of the source files that contain these routines.



Top

Mice API Documentation



A Mice routine's specification is found in the API documentation page located under ``mice/doc/html/mice''.

For example, the document

   mice/doc/html/mice/cspice_str2et.html
describes the cspice_str2et routine.



Top

Kernels Used




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

    1.  Solar System Ephemeris SPK, subsetted to cover only the time
        range of interest:
 
           de430.bsp
 
    2.  Martian Satellite Ephemeris SPK, subsetted to cover only the
        time range of interest:
 
           mar085.bsp
 
    3.  ESA stations SPK:
 
           estrack_v01.bsp
 
    4.  ESA stations frame definitions:
 
           estrack_v01.tf
 
    5.  EARTH_FIXED/ITRF93 frame connection:
 
           earthfixeditrf93.tf
 
    6.  Binary PCK for Earth:
 
           earth_070425_370426_predict.bpc
 
    7.  ExoMars-16 TGO Spacecraft Trajectory SPK, subsetted to cover
        only the time range of interest:
 
           em16_tgo_mlt_20171205_20230115_v01.bsp
 
    8.  Generic LSK:
 
           naif0012.tls
 
    9.  Generic PCK:
 
           pck00010.tpc
 
   10.  ExoMars-16 TGO FK, containing the SPICE ID/name mappings for
        the TGO spacecraft:
 
           em16_tgo_v07.tf
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

Mice Routines Used




This section provides a summary of the functions 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
   -------------- ---------------------------------------------------
   cspice_furnsh  Loads kernels, individually or listed in meta-kernel
   cspice_gfoclt  Solve for times of occultation or transit
   cspice_gfposc  Solve for times when a position vector coordinate
                  constraint is met
   cspice_rpd     Return number of radians per degree
   cspice_str2et  Converts a time string to ET seconds past J2000
   cspice_timout  Format a time string for output
   cspice_wndifd  Find the difference of two d.p. windows
   cspice_wnfetd  Fetch a specified interval from a d.p. window
   cspice_wninsd  Insert an interval into a d.p. window
Refer to the headers of the various functions 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

   2018 JUN 10 TDB
   2018 JUN 14 TDB
when the ExoMars-16 Trace Gas Orbiter (TGO) is visible from ESA's New Norcia station. 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 NEW_NORCIA_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. 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.

    2. 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:

    2. Use cspice_wninsd to create a Mice confinement window ```cnfine''' to hold the time period within which the search is to be conducted: insert the given time bounds into the confinement window using cspice_wninsd.

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

    4. Use the GF routine cspice_gfposc to find the window of times, within the confinement window `cnfine', during which the ExoMars-16 TGO spacecraft is above the elevation limit as seen from ESA's New Norcia station, in the the reference frame NEW_NORCIA_TOPO.

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

    5. Fetch and display the contents of the result window. Use cspice_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 cspice_timout.

You may find it useful to consult the references listed above. In particular, the header of the SPICE GF function cspice_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
 
      This is the meta-kernel used in the solution of the tasks in the
      Geometric Event Finding Hands On Lesson.
 
 
   \begindata
 
      KERNELS_TO_LOAD = (
 
         'kernels/spk/de430.bsp'
         'kernels/spk/mar085.bsp',
         'kernels/spk/estrack_v01.bsp'
         'kernels/fk/estrack_v01.tf'
         'kernels/fk/earthfixeditrf93.tf'
         'kernels/pck/earth_070425_370426_predict.bpc'
         'kernels/lsk/naif0012.tls'
         'kernels/spk/em16_tgo_mlt_20171205_20230115_v01.bsp'
         'kernels/pck/pck00010.tpc'
         'kernels/fk/em16_tgo_v07.tf'
 
                        )
 
   \begintext
 


Top

Solution Code



The example program below shows one possible solution.

 
   %
   % Find and display the window of times when the ExoMars-16
   % TGO spacecraft is above a specified elevation limit in the
   % topocentric reference frame of ESA's New Norcia station.
   %
   function viewpr()
 
   %
   % The meta-kernel:
   %
   META   = 'viewpr.tm';
 
   %
   % Maximum number of intervals in any window:
   %
   MAXIVL = 1000;
 
   %
   % Time string length:
   %
   TIMLEN = 50;
 
   %
   % Format string for time output:
   %
   TDBFMT = 'YYYY MON DD HR:MN:SC.### (TDB) ::TDB';
 
   %
   % Load the meta-kernel.
   %
   cspice_furnsh( META );
 
   %
   % Assign the inputs for our search.
   %
   % Since we're interested in the apparent location of the
   % target, we use light time and stellar aberration
   % corrections. We use the "converged Newtonian" form
   % of the light time correction because this choice may
   % increase the accuracy of the occultation times we'll
   % compute using cspice_gfoclt.
   %
   srfpt  = 'NEW_NORCIA';
   obsfrm = 'NEW_NORCIA_TOPO';
   target = 'TGO';
   abcorr = 'CN+S';
   start  = '2018 JUN 10 TDB';
   stop   = '2018 JUN 14 TDB';
   elvlim =  6.0;
 
   %
   % The elevation limit above has units of degrees; we convert
   % this value to radians for computation using SPICE routines.
   % We'll store the equivalent value in radians in REVLIM.
   %
   revlim = cspice_rpd() * elvlim;
 
   %
   % Since SPICE doesn't directly support the AZ/EL coordinate
   % system, we use the equivalent constraint
   %
   %    latitude > REVLIM
   %
   % in the latitudinal coordinate system, where the reference
   % frame is topocentric and is centered at the viewing location.
   %
   crdsys = 'LATITUDINAL';
   coord  = 'LATITUDE';
   relate = '>';
 
   %
   % The adjustment value only applies to absolute extrema
   % searches; simply give it an initial value of zero
   % for this inequality search.
   %
   adjust = 0.0;
 
   %
   % STEPSZ is the step size, measured in seconds, used to search
   % for times bracketing a state transition. Since we don't expect
   % any events of interest to be shorter than five minutes, and
   % since the separation between events is well over 5 minutes,
   % we'll use this value as our step size. Units are seconds.
   %
   stepsz = 300.0;
 
   %
   % Display a banner for the output report:
   %
 
   disp( ' ' );
   disp( 'Inputs for target visibility search:' );
   disp( ' ' );
 
   fprintf( '   Target                       = %s\n',  target );
   fprintf( '   Observation surface location = %s\n',  srfpt  );
   fprintf( '   Observer''s reference frame   = %s\n', obsfrm );
   fprintf( '   Elevation limit (degrees)    = %f\n',  elvlim );
   fprintf( '   Aberration correction        = %s\n',  abcorr );
   fprintf( '   Step size (seconds)          = %f\n',  stepsz );
 
   %
   % Convert the start and stop times to ET.
   %
   etbeg = cspice_str2et( start );
   etend = cspice_str2et( stop  );
 
   %
   % Display the search interval start time and stop
   % times using the format shown below.
   %
   %     2004 MAY 06 20:15:00.000 (TDB)
   %
   timstr0 = cspice_timout( etbeg, TDBFMT );
   timstr1 = cspice_timout( etend, TDBFMT );
 
   fprintf( '   Start time                   = %s\n', timstr0 );
   fprintf( '   Stop time                    = %s\n', timstr1 );
   disp( ' ' );
 
   %
   % Create the "confinement" window; store in this window
   % the interval over which we'll conduct the search.
   %
   cnfine = cspice_wninsd( etbeg, etend );
 
   %
   % In the call below, the maximum number of window
   % intervals cspice_gfposc can store internally is
   % set to MAXIVL. We'll also use MAXIVL as the maximum
   % number of intervals in the result window.
   %
   % Now search for the time period, within our confinement
   % window, during which the apparent target has elevation
   % at least equal to the elevation limit.
   %
   riswin = cspice_gfposc ( target, obsfrm, abcorr, srfpt,  ...
                            crdsys, coord,  relate, revlim, ...
                            adjust, stepsz, MAXIVL, cnfine     );
 
   %
   % Let winsiz contain the number of intervals
   % in the SPICE window riswin.
   %
   winsiz = length( riswin )/2;
 
   %
   % Display the rise and set times.
   %
 
   if  winsiz == 0
 
      disp( 'No events were found.' );
 
   else
 
      %
      %  Display the visibility time periods.
      %
      fprintf( [ 'Visibility times of %s '  ...
                 'as seen from %s:\n\n' ], target, srfpt );
 
      for i = 1:winsiz
 
         %
         % Fetch the Ith interval from the window.
         %
         [intbeg, intend] = cspice_wnfetd( riswin, i );
 
         %
         % Convert the rise time to a TDB calendar string.
         %
         timstr = cspice_timout( intbeg, TDBFMT );
 
         %
         % Write the string to standard output.
         %
         if  i == 1
 
            line = 'Visibility or window start time:  ';
 
         else
 
            line = 'Visibility start time:            ';
 
         end
 
         fprintf( '%s%s\n', line, timstr );
 
         %
         % Convert the set time to a TDB calendar string.
         %
         timstr = cspice_timout( intend, TDBFMT );
 
         %
         % Write the string to standard output.
         %
         if  i == winsiz
 
            line = 'Visibility or window stop time:   ';
 
         else
 
            line = 'Visibility stop time:             ';
 
         end
 
         fprintf( '%s%s\n\n', line, timstr );
 
      end
 
   end
 
   %
   % Unload kernels so they are not accidentally used by another
   % SPICE-based program during the current MATLAB session.
   %
   cspice_kclear;
 
   %
   % End of function viewpr
   %


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.

Execute the program. The output is:

 
 
   Inputs for target visibility search:
 
      Target                       = TGO
      Observation surface location = NEW_NORCIA
      Observer's reference frame   = NEW_NORCIA_TOPO
      Elevation limit (degrees)    = 6.000000
      Aberration correction        = CN+S
      Step size (seconds)          = 300.000000
      Start time                   = 2018 JUN 10 00:00:00.000 (TDB)
      Stop time                    = 2018 JUN 14 00:00:00.000 (TDB)
 
   Visibility times of TGO as seen from NEW_NORCIA:
 
   Visibility or window start time:  2018 JUN 10 00:00:00.000 (TDB)
   Visibility stop time:             2018 JUN 10 02:11:17.355 (TDB)
 
   Visibility start time:            2018 JUN 10 13:19:58.777 (TDB)
   Visibility stop time:             2018 JUN 11 02:08:16.008 (TDB)
 
   Visibility start time:            2018 JUN 11 13:16:50.542 (TDB)
   Visibility stop time:             2018 JUN 12 02:05:12.548 (TDB)
 
   Visibility start time:            2018 JUN 12 13:13:38.573 (TDB)
   Visibility stop time:             2018 JUN 13 02:02:06.618 (TDB)
 
   Visibility start time:            2018 JUN 13 13:10:23.432 (TDB)
   Visibility or window stop time:   2018 JUN 14 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 ExoMars-16 TGO orbiter is:

    -- Above the elevation limit in the NEW_NORCIA_TOPO topocentric reference frame.

    -- and is not occulted by Mars

Store the set of time intervals when the spacecraft is visible in a Mice 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 cspice_gfoclt. Further experience with the Mice window functions.



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. Search for occultations of the ExoMars-16 TGO orbiter as seen from New Norcia station using cspice_gfoclt. Use as the confinement window for this search the result window from the elevation search performed by cspice_gfposc.

    Since occultations occur when the apparent ExoMars-16 TGO 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.

    4. Use the Mice window subtraction routine cspice_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.

    5. Modify the code to display the contents of the window `viswin'.

This completes the assignment.



Top

Solution






Top

Solution Code



 
   %
   % Find and display the window of times when the ExoMars-16
   % TGO spacecraft is above a specified elevation limit in the
   % topocentric reference frame of ESA's New Norcia station
   % and is not occulted by Mars.
   %
   function visibl()
 
   %
   % The meta-kernel:
   %
   META   = 'viewpr.tm';
 
   %
   % Maximum number of intervals in any window:
   %
   MAXIVL = 1000;
 
   %
   % Time string length:
   %
   TIMLEN = 50;
 
   %
   % Format string for time output:
   %
   TDBFMT = 'YYYY MON DD HR:MN:SC.### (TDB) ::TDB';
 
   %
   % Load the meta-kernel.
   %
   cspice_furnsh( META );
 
   %
   % Assign the inputs for our search.
   %
   % Since we're interested in the apparent location of the
   % target, we use light time and stellar aberration
   % corrections. We use the "converged Newtonian" form
   % of the light time correction because this choice may
   % increase the accuracy of the occultation times we'll
   % compute using cspice_gfoclt.
   %
   srfpt  = 'NEW_NORCIA';
   obsfrm = 'NEW_NORCIA_TOPO';
   target = 'TGO';
   abcorr = 'CN+S';
   start  = '2018 JUN 10 TDB';
   stop   = '2018 JUN 14 TDB';
   elvlim =  6.0;
 
   %
   % The elevation limit above has units of degrees; we convert
   % this value to radians for computation using SPICE routines.
   % We'll store the equivalent value in radians in REVLIM.
   %
   revlim = cspice_rpd() * elvlim;
 
 
   %
   % We model the target shape as a point and the blocking body's
   % shape as an ellipsoid. No body-fixed reference frame is
   % required for the target since its orientation is not used.
   %
   back   = target;
   bshape = 'POINT';
   bframe = ' ';
   front  = 'MARS';
   fshape = 'ELLIPSOID';
   fframe = 'IAU_MARS';
 
   %
   % The occultation type should be set to 'ANY' for a point
   % target.
   %
   occtyp = 'any';
 
   %
   % Since SPICE doesn't directly support the AZ/EL coordinate
   % system, we use the equivalent constraint
   %
   %    latitude > REVLIM
   %
   % in the latitudinal coordinate system, where the reference
   % frame is topocentric and is centered at the viewing location.
   %
   crdsys = 'LATITUDINAL';
   coord  = 'LATITUDE';
   relate = '>';
 
   %
   % The adjustment value only applies to absolute extrema
   % searches; simply give it an initial value of zero
   % for this inequality search.
   %
   adjust = 0.0;
 
   %
   % STEPSZ is the step size, measured in seconds, used to search
   % for times bracketing a state transition. Since we don't expect
   % any events of interest to be shorter than five minutes, and
   % since the separation between events is well over 5 minutes,
   % we'll use this value as our step size. Units are seconds.
   %
   stepsz = 300.0;
 
   %
   % Display a banner for the output report:
   %
 
   disp( ' ' );
   disp( 'Inputs for target visibility search:' );
   disp( ' ' );
 
   fprintf( '   Target                       = %s\n',  target );
   fprintf( '   Observation surface location = %s\n',  srfpt  );
   fprintf( '   Observer''s reference frame   = %s\n', obsfrm );
   fprintf( '   Blocking body                = %s\n',  front  );
   fprintf( '   Blocker''s reference frame    = %s\n', fframe );
   fprintf( '   Elevation limit (degrees)    = %f\n',  elvlim );
   fprintf( '   Aberration correction        = %s\n',  abcorr );
   fprintf( '   Step size (seconds)          = %f\n',  stepsz );
 
   %
   % Convert the start and stop times to ET.
   %
   etbeg = cspice_str2et( start );
   etend = cspice_str2et( stop  );
 
   %
   % Display the search interval start time and stop
   % times using the format shown below.
   %
   %     2004 MAY 06 20:15:00.000 (TDB)
   %
   timstr0 = cspice_timout( etbeg, TDBFMT );
   timstr1 = cspice_timout( etend, TDBFMT );
 
   fprintf( '   Start time                   = %s\n', timstr0 );
   fprintf( '   Stop time                    = %s\n', timstr1 );
   disp( ' ' );
 
   %
   % Create the "confinement" window; store in this window
   % the interval over which we'll conduct the search.
   %
   cnfine = cspice_wninsd( etbeg, etend );
 
   %
   % In the call below, the maximum number of window
   % intervals cspice_gfposc can store internally is
   % set to MAXIVL. We'll also use MAXIVL as the maximum
   % number of intervals in the result window.
   %
   % Now search for the time period, within our confinement
   % window, during which the apparent target has elevation
   % at least equal to the elevation limit.
   %
   riswin = cspice_gfposc ( target, obsfrm, abcorr, srfpt,  ...
                            crdsys, coord,  relate, revlim, ...
                            adjust, stepsz, MAXIVL, cnfine      );
   %
   % Now find the times when the apparent target is above
   % the elevation limit and is not occulted by the
   % blocking body (Mars). We'll find the window of times when
   % the target is above the elevation limit and *is* occulted,
   % then subtract that window from the view period window
   % riswin found above.
   %
   % For this occultation search, we can use riswin as
   % the confinement window because we're not interested in
   % occultations that occur when the target is below the
   % elevation limit.
   %
   % Find occultations within the view period window.
   %
   occwin = cspice_gfoclt( occtyp, front,  fshape,  fframe, ...
                           back,   bshape, bframe,  abcorr, ...
                           srfpt,  stepsz, riswin,  MAXIVL     );
 
   %
   % Subtract the occultation window from the view period
   % window: this yields the time periods when the target
   % is visible.
   %
   viswin = cspice_wndifd( riswin, occwin );
 
   %
   % Let winsiz contain the number of intervals
   % in the SPICE window riswin.
   %
   winsiz = length( viswin )/2;
 
   %
   % Display the rise and set times.
   %
 
   if  winsiz == 0
 
      disp( 'No events were found.' );
 
   else
 
      %
      %  Display the visibility time periods.
      %
      fprintf( [ 'Visibility times of %s '  ...
                 'as seen from %s:\n\n' ], target, srfpt );
 
      for i = 1:winsiz
 
         %
         % Fetch the Ith interval from the window.
         %
         [intbeg, intend] = cspice_wnfetd( viswin, i );
 
         %
         % Convert the rise time to a TDB calendar string.
         %
         timstr = cspice_timout( intbeg, TDBFMT );
 
         %
         % Write the string to standard output.
         %
         if  i == 1
 
            line = 'Visibility or window start time:  ';
 
         else
 
            line = 'Visibility start time:            ';
 
         end
 
         fprintf( '%s%s\n', line, timstr );
 
         %
         % Convert the set time to a TDB calendar string.
         %
         timstr = cspice_timout( intend, TDBFMT );
 
         %
         % Write the string to standard output.
         %
         if  i == winsiz
 
            line = 'Visibility or window stop time:   ';
 
         else
 
            line = 'Visibility stop time:             ';
 
         end
 
         fprintf( '%s%s\n\n', line, timstr );
 
      end
 
   end
 
   %
   % Unload kernels so they are not accidentally used by another
   % SPICE-based program during the current MATLAB session.
   %
   cspice_kclear;
 
   %
   % End of function visibl
   %


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.

Execute the program. The output is:

 
   Inputs for target visibility search:
 
      Target                       = TGO
      Observation surface location = NEW_NORCIA
      Observer's reference frame   = NEW_NORCIA_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                   = 2018 JUN 10 00:00:00.000 (TDB)
      Stop time                    = 2018 JUN 14 00:00:00.000 (TDB)
 
   Visibility times of TGO as seen from NEW_NORCIA:
 
   Visibility or window start time:  2018 JUN 10 00:00:00.000 (TDB)
   Visibility stop time:             2018 JUN 10 01:00:30.640 (TDB)
 
   Visibility start time:            2018 JUN 10 01:41:03.610 (TDB)
   Visibility stop time:             2018 JUN 10 02:11:17.355 (TDB)
 
   Visibility start time:            2018 JUN 10 13:28:28.785 (TDB)
   Visibility stop time:             2018 JUN 10 14:45:38.197 (TDB)
 
   Visibility start time:            2018 JUN 10 15:26:21.981 (TDB)
   Visibility stop time:             2018 JUN 10 16:43:32.192 (TDB)
 
   Visibility start time:            2018 JUN 10 17:24:17.290 (TDB)
   Visibility stop time:             2018 JUN 10 18:41:27.535 (TDB)
 
   Visibility start time:            2018 JUN 10 19:22:13.628 (TDB)
   Visibility stop time:             2018 JUN 10 20:39:21.785 (TDB)
 
   Visibility start time:            2018 JUN 10 21:20:08.856 (TDB)
   Visibility stop time:             2018 JUN 10 22:37:12.445 (TDB)
 
   Visibility start time:            2018 JUN 10 23:18:00.834 (TDB)
   Visibility stop time:             2018 JUN 11 00:35:01.034 (TDB)
 
   Visibility start time:            2018 JUN 11 01:15:50.883 (TDB)
   Visibility stop time:             2018 JUN 11 02:08:16.008 (TDB)
 
   Visibility start time:            2018 JUN 11 13:16:50.542 (TDB)
   Visibility stop time:             2018 JUN 11 14:20:09.789 (TDB)
 
   Visibility start time:            2018 JUN 11 15:01:08.370 (TDB)
   Visibility stop time:             2018 JUN 11 16:18:03.385 (TDB)
 
   Visibility start time:            2018 JUN 11 16:59:03.014 (TDB)
   Visibility stop time:             2018 JUN 11 18:15:58.739 (TDB)
 
   Visibility start time:            2018 JUN 11 18:56:59.199 (TDB)
   Visibility stop time:             2018 JUN 11 20:13:54.308 (TDB)
 
   Visibility start time:            2018 JUN 11 20:54:55.301 (TDB)
   Visibility stop time:             2018 JUN 11 22:11:47.045 (TDB)
 
   Visibility start time:            2018 JUN 11 22:52:48.925 (TDB)
   Visibility stop time:             2018 JUN 12 00:09:35.868 (TDB)
 
   Visibility start time:            2018 JUN 12 00:50:39.046 (TDB)
   Visibility stop time:             2018 JUN 12 02:05:12.548 (TDB)
 
   Visibility start time:            2018 JUN 12 13:13:38.573 (TDB)
   Visibility stop time:             2018 JUN 12 13:54:43.524 (TDB)
 
   Visibility start time:            2018 JUN 12 14:35:54.054 (TDB)
   Visibility stop time:             2018 JUN 12 15:52:36.256 (TDB)
 
   Visibility start time:            2018 JUN 12 16:33:47.502 (TDB)
   Visibility stop time:             2018 JUN 12 17:50:30.988 (TDB)
 
   Visibility start time:            2018 JUN 12 18:31:42.896 (TDB)
   Visibility stop time:             2018 JUN 12 19:48:26.827 (TDB)
 
   Visibility start time:            2018 JUN 12 20:29:39.039 (TDB)
   Visibility stop time:             2018 JUN 12 21:46:20.933 (TDB)
 
   Visibility start time:            2018 JUN 12 22:27:33.596 (TDB)
   Visibility stop time:             2018 JUN 12 23:44:11.473 (TDB)
 
   Visibility start time:            2018 JUN 13 00:25:24.992 (TDB)
   Visibility stop time:             2018 JUN 13 01:42:00.777 (TDB)
 
   Visibility start time:            2018 JUN 13 13:10:23.432 (TDB)
   Visibility stop time:             2018 JUN 13 13:29:19.789 (TDB)
 
   Visibility start time:            2018 JUN 13 14:10:38.985 (TDB)
   Visibility stop time:             2018 JUN 13 15:27:11.882 (TDB)
 
   Visibility start time:            2018 JUN 13 16:08:31.566 (TDB)
   Visibility stop time:             2018 JUN 13 17:25:06.068 (TDB)
 
   Visibility start time:            2018 JUN 13 18:06:26.219 (TDB)
   Visibility stop time:             2018 JUN 13 19:23:01.820 (TDB)
 
   Visibility start time:            2018 JUN 13 20:04:22.175 (TDB)
   Visibility stop time:             2018 JUN 13 21:20:57.296 (TDB)
 
   Visibility start time:            2018 JUN 13 22:02:17.650 (TDB)
   Visibility or window stop time:   2018 JUN 13 23:18:49.624 (TDB)
 


Top

Extra Credit





In this ``extra credit'' section you will be presented with more complex tasks, aimed at improving your understanding of the geometry event finding subsystem and particularly the cspice_gfposc and cspice_gfdist functions.

These ``extra credit'' tasks are provided as task statements, and unlike the regular tasks, no approach or solution source code is provided. In the next section, you will find the numeric solutions to the questions asked in these tasks.



Top

Task statements




    1. Write a program that finds the times, within the time range

         2018 JUN 10 TDB
         2018 JUN 11 TDB
    when the ExoMars-16 Trace Gas Orbiter (TGO) crosses Mars' equator. Display the results using TDB calendar dates and millisecond precision.

    2. Write a program that finds the times, within the time range

         2018 JUN 10 TDB
         2018 JUN 11 TDB
    when the ExoMars-16 Trace Gas Orbiter (TGO) is at periapsis. Display the results using TDB calendar dates and millisecond precision.

    3. Write a program that finds the times, within the time range

         2018 JUN 10 TDB
         2018 JUN 11 TDB
    when the ExoMars-16 Trace Gas Orbiter (TGO) is at apoapsis. Display the results using TDB calendar dates and millisecond precision.



Top

Solutions




   1. Inputs for the equator crossing search, using cspice_gfposc for
   the spacecraft latitude in the Mars body-fixed frame equal to 0:
 
         Target                       = TGO
         Observer                     = MARS
         Observer's reference frame   = IAU_MARS
         Elevation limit (degrees)    = 0.000000
         Aberration correction        = NONE
         Step size (seconds)          = 300.000000
         Start time                   = 2018 JUN 10 00:00:00.000 (TDB)
         Stop time                    = 2018 JUN 11 00:00:00.000 (TDB)
 
      TGO Mars' equator crossing times:
 
      Equator crossing time:            2018 JUN 10 00:14:08.836 (TDB)
      Equator crossing time:            2018 JUN 10 01:12:34.582 (TDB)
      Equator crossing time:            2018 JUN 10 02:12:00.375 (TDB)
      Equator crossing time:            2018 JUN 10 03:10:28.808 (TDB)
      Equator crossing time:            2018 JUN 10 04:09:53.955 (TDB)
      Equator crossing time:            2018 JUN 10 05:08:23.919 (TDB)
      Equator crossing time:            2018 JUN 10 06:07:48.630 (TDB)
      Equator crossing time:            2018 JUN 10 07:06:17.539 (TDB)
      Equator crossing time:            2018 JUN 10 08:05:42.659 (TDB)
      Equator crossing time:            2018 JUN 10 09:04:09.120 (TDB)
      Equator crossing time:            2018 JUN 10 10:03:34.270 (TDB)
      Equator crossing time:            2018 JUN 10 11:01:59.269 (TDB)
      Equator crossing time:            2018 JUN 10 12:01:22.866 (TDB)
      Equator crossing time:            2018 JUN 10 12:59:49.352 (TDB)
      Equator crossing time:            2018 JUN 10 13:59:13.289 (TDB)
      Equator crossing time:            2018 JUN 10 14:57:41.242 (TDB)
      Equator crossing time:            2018 JUN 10 15:57:07.576 (TDB)
      Equator crossing time:            2018 JUN 10 16:55:35.266 (TDB)
      Equator crossing time:            2018 JUN 10 17:55:02.773 (TDB)
      Equator crossing time:            2018 JUN 10 18:53:30.271 (TDB)
      Equator crossing time:            2018 JUN 10 19:52:56.383 (TDB)
      Equator crossing time:            2018 JUN 10 20:51:23.966 (TDB)
      Equator crossing time:            2018 JUN 10 21:50:47.729 (TDB)
      Equator crossing time:            2018 JUN 10 22:49:14.385 (TDB)
      Equator crossing time:            2018 JUN 10 23:48:37.583 (TDB)
 
 
 
   2. Inputs for the periapsis search, using cspice_gfdist for the
   spacecraft distance from Mars at a local minimum:
 
         Target                       = TGO
         Observer                     = MARS
         Observer's reference frame   = J2000
         Aberration correction        = NONE
         Step size (seconds)          = 300.000000
         Start time                   = 2018 JUN 10 00:00:00.000 (TDB)
         Stop time                    = 2018 JUN 11 00:00:00.000 (TDB)
 
      TGO periapsis times:
 
      Periapsis time:                   2018 JUN 10 00:43:06.357 (TDB)
      Periapsis time:                   2018 JUN 10 02:40:47.168 (TDB)
      Periapsis time:                   2018 JUN 10 04:38:45.496 (TDB)
      Periapsis time:                   2018 JUN 10 06:36:32.706 (TDB)
      Periapsis time:                   2018 JUN 10 08:34:10.548 (TDB)
      Periapsis time:                   2018 JUN 10 10:31:49.108 (TDB)
      Periapsis time:                   2018 JUN 10 12:29:20.342 (TDB)
      Periapsis time:                   2018 JUN 10 14:27:07.089 (TDB)
      Periapsis time:                   2018 JUN 10 16:25:36.081 (TDB)
      Periapsis time:                   2018 JUN 10 18:24:02.653 (TDB)
      Periapsis time:                   2018 JUN 10 20:22:23.184 (TDB)
      Periapsis time:                   2018 JUN 10 22:20:12.453 (TDB)
 
 
   3. Inputs for the apoapsis search, using cspice_gfdist for the
   spacecraft distance from Mars at a local maximum:
 
         Target                       = TGO
         Observer                     = MARS
         Observer's reference frame   = J2000
         Aberration correction        = NONE
         Step size (seconds)          = 300.000000
         Start time                   = 2018 JUN 10 00:00:00.000 (TDB)
         Stop time                    = 2018 JUN 11 00:00:00.000 (TDB)
 
      TGO apoapsis times:
 
      Apoapsis time:                    2018 JUN 10 01:41:44.632 (TDB)
      Apoapsis time:                    2018 JUN 10 03:39:31.106 (TDB)
      Apoapsis time:                    2018 JUN 10 05:37:22.115 (TDB)
      Apoapsis time:                    2018 JUN 10 07:34:59.674 (TDB)
      Apoapsis time:                    2018 JUN 10 09:32:25.708 (TDB)
      Apoapsis time:                    2018 JUN 10 11:29:47.945 (TDB)
      Apoapsis time:                    2018 JUN 10 13:27:30.200 (TDB)
      Apoapsis time:                    2018 JUN 10 15:26:02.524 (TDB)
      Apoapsis time:                    2018 JUN 10 17:24:37.842 (TDB)
      Apoapsis time:                    2018 JUN 10 19:23:11.265 (TDB)
      Apoapsis time:                    2018 JUN 10 21:21:13.530 (TDB)
      Apoapsis time:                    2018 JUN 10 23:18:56.796 (TDB)