| Geometric Event Finding Hands-On Lesson (C) |
Table of ContentsGeometric Event Finding Hands-On Lesson (C) Overview Note About HTML Links References Tutorials Required Readings The Permuted Index Source Code Header Comments Kernels Used CSPICE 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 Geometric Event Finding Hands-On Lesson (C)
Overview
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. Note About HTML Links
In order for the links to be resolved, create a subdirectory called ``lessons'' under the ``doc/html'' directory of the ``cspice/'' tree and copy this document to that subdirectory before loading it into a Web browser. ReferencesTutorials
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) subsystemThese tutorials are available from the NAIF ftp server at JPL:
http://naif.jpl.nasa.gov/naif/tutorials.html Required Readings
Name Lesson steps/functions 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 The Permuted Index
This text document provides a simple mechanism by which users can discover which CSPICE routines perform functions of interest, as well as the names of the source files that contain these routines. Source Code Header Comments
For example path of the source code of the str2et_c routine is
cspice/src/cspice/str2et_c.c Kernels Used
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/ CSPICE Routines Used
Name Function that it performs ---------- --------------------------------------------------- furnsh_c Loads kernels, individually or listed in meta-kernel gfoclt_c Solve for times of occultation or transit gfposc_c Solve for times when a position vector coordinate constraint is met str2et_c Converts a time string to ET seconds past J2000 timout_c Format a time string for output wncard_c Return cardinality of a SPICE window wndifd_c Find the difference of two d.p. windows wnfetd_c Fetch a specified interval from a d.p. window wninsd_c Insert an interval into a d.p. windowRefer to the headers of the various functions listed above, as detailed interface specifications are provided with the source code. Find View PeriodsTask Statement
2004 MAY 2 TDB 2004 MAY 6 TDBwhen 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. Learning Goals
ApproachSolution steps
Preparation:
SolutionSolution Meta-Kernel
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
Solution Code
#include <string.h>
#include <stdio.h>
#include "SpiceUsr.h"
/*
PROGRAM VIEWPR
Find and display the window of times when the MEX
spacecraft is above a specified elevation limit in the
topocentric reference frame of DSN station DSS-14.
*/
int main()
{
/*
Local constants
*/
/*
The meta-kernel:
*/
#define METAKR "viewpr.tm"
/*
Maximum number of intervals in any window:
*/
#define MAXIVL 1000
/*
Maximum result window size:
*/
#define MAXWIN ( 2 * MAXIVL )
/*
Format string for time output:
*/
#define TDBFMT "YYYY MON DD HR:MN:SC.### (TDB) ::TDB"
/*
String lengths and other bounds:
*/
#define LNSIZE 201
#define TIMLEN 51
/*
Local variables
*/
/*
Confinement window used to store interval to be searched:
*/
SPICEDOUBLE_CELL ( cnfine, MAXWIN );
/*
Window to hold sets of times when
target is above the elevation limit:
*/
SPICEDOUBLE_CELL ( riswin, MAXWIN );
SpiceChar * abcorr;
SpiceChar * coord;
SpiceChar * crdsys;
SpiceChar * obsfrm;
SpiceChar * relate;
SpiceChar * srfpt;
SpiceChar * start;
SpiceChar * stop;
SpiceChar * target;
SpiceChar timstr [ TIMLEN ];
SpiceDouble adjust;
SpiceDouble elvlim;
SpiceDouble etbeg;
SpiceDouble etend;
SpiceDouble intbeg;
SpiceDouble intend;
SpiceDouble revlim;
/*
stepsz is the step size, measured in seconds, used to search
for times bracketing a state transition.
*/
SpiceDouble stepsz;
SpiceInt i;
SpiceInt winsiz;
/*
Load the meta-kernel.
*/
furnsh_c ( METAKR );
/*
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 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.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 = rpd_c() * 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:
*/
printf ( "\n%s\n\n",
"Inputs for target visibility search:" );
printf ( " Target = %s\n", target );
printf ( " Observation surface location = %s\n", srfpt );
printf ( " Observer's reference frame = %s\n", obsfrm );
printf ( " Elevation limit (degrees) = %f\n", elvlim );
printf ( " Aberration correction = %s\n", abcorr );
printf ( " Step size (seconds) = %f\n", stepsz );
/*
Convert the start and stop times to ET.
*/
str2et_c ( start, &etbeg );
str2et_c ( stop, &etend );
/*
Display the search interval start and stop times
using the format shown below.
2004 MAY 06 20:15:00.000 (TDB)
*/
timout_c ( etbeg, TDBFMT, TIMLEN, timstr );
printf ( " Start time = %s\n", timstr );
timout_c ( etend, TDBFMT, TIMLEN, timstr );
printf ( " Stop time = %s\n", timstr );
printf ( "\n" );
/*
Initialize the "confinement" window with the interval
over which we'll conduct the search.
*/
wninsd_c ( etbeg, etend, &cnfine );
/*
In the call below, the maximum number of window
intervals gfposc_c can store internally is set to MAXIVL.
Now search for the time period, within our confinement
window, during which the apparent target has elevation
at least equal to the elevation limit.
*/
gfposc_c ( target, obsfrm, abcorr, srfpt,
crdsys, coord, relate, revlim,
adjust, stepsz, MAXIVL, &cnfine, &riswin );
/*
The function wncard_c returns the number of intervals
in a SPICE window.
*/
winsiz = wncard_c( &riswin );
if ( winsiz == 0 )
{
printf ( "No events were found.\n" );
}
else
{
/*
Display the visibility time periods.
*/
printf ( "Visibility times of %s as seen from %s:"
"\n\n",
target, srfpt );
for ( i = 0; i < winsiz; i++ )
{
/*
Fetch the start and stop times of the Ith interval
from the search result window viswin.
*/
wnfetd_c ( &riswin, i, &intbeg, &intend );
/*
Convert the rise time to a TDB calendar string.
*/
timout_c ( intbeg, TDBFMT, TIMLEN, timstr );
/*
Write the string to standard output.
*/
if ( i == 0 )
{
printf ( "Visibility or window start time: %s\n",
timstr );
}
else
{
printf ( "Visibility start time: %s\n",
timstr );
}
/*
Convert the set time to a TDB calendar string.
*/
timout_c ( intend, TDBFMT, TIMLEN, timstr );
/*
Write the string to standard output.
*/
if ( i == winsiz-1 )
{
printf ( "Visibility or window stop time: %s\n",
timstr );
}
else
{
printf ( "Visibility stop time: %s\n",
timstr );
}
printf ( "\n" );
}
}
return ( 0 );
}
Solution Sample Output
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)
Find Times when Target is VisibleTask Statement
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. Learning Goals
ApproachSolution steps
SolutionSolution Code
#include <string.h>
#include <stdio.h>
#include "SpiceUsr.h"
/*
PROGRAM VISIBL
Find and display the window of times when the MEX
spacecraft is above a specified elevation limit in the
topocentric reference frame of DSN station DSS-14
and is not occulted by Mars.
*/
int main()
{
/*
Local constants
*/
/*
The meta-kernel:
*/
#define METAKR "viewpr.tm"
/*
Maximum number of intervals in any window:
*/
#define MAXIVL 1000
/*
Maximum result window size:
*/
#define MAXWIN ( 2 * MAXIVL )
/*
Format string for time output:
*/
#define TDBFMT "YYYY MON DD HR:MN:SC.### (TDB) ::TDB"
/*
String lengths and other bounds:
*/
#define TIMLEN 51
/*
Local variables
*/
/*
Confinement window used to store interval to be searched:
*/
SPICEDOUBLE_CELL ( cnfine, MAXWIN );
/*
Windows to hold sets of times when
- target is occulted
- target is above the elevation limit
- target is visible
*/
SPICEDOUBLE_CELL ( occwin, MAXWIN );
SPICEDOUBLE_CELL ( riswin, MAXWIN );
SPICEDOUBLE_CELL ( viswin, MAXWIN );
SpiceChar * abcorr;
SpiceChar * back;
SpiceChar * bframe;
SpiceChar * bshape;
SpiceChar * coord;
SpiceChar * crdsys;
SpiceChar * fframe;
SpiceChar * front;
SpiceChar * fshape;
SpiceChar * obsfrm;
SpiceChar * occtyp;
SpiceChar * relate;
SpiceChar * srfpt;
SpiceChar * start;
SpiceChar * stop;
SpiceChar * target;
SpiceChar timstr [ TIMLEN ];
SpiceDouble adjust;
SpiceDouble elvlim;
SpiceDouble etbeg;
SpiceDouble etend;
SpiceDouble intbeg;
SpiceDouble intend;
SpiceDouble revlim;
/*
stepsz is the step size, measured in seconds, used to search
for times bracketing a state transition.
*/
SpiceDouble stepsz;
SpiceInt i;
SpiceInt winsiz;
/*
Load the meta-kernel.
*/
furnsh_c ( METAKR );
/*
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 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.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 = rpd_c() * 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:
*/
printf ( "\n%s\n\n",
"Inputs for target visibility search:" );
printf ( " Target = %s\n", target );
printf ( " Observation surface location = %s\n", srfpt );
printf ( " Observer's reference frame = %s\n", obsfrm );
printf ( " Blocking body = %s\n", front );
printf ( " Blocker's reference frame = %s\n", fframe );
printf ( " Elevation limit (degrees) = %f\n", elvlim );
printf ( " Aberration correction = %s\n", abcorr );
printf ( " Step size (seconds) = %f\n", stepsz );
/*
Convert the start and stop times to ET.
*/
str2et_c ( start, &etbeg );
str2et_c ( stop, &etend );
/*
Display the search interval start and stop times
using the format shown below.
2004 MAY 06 20:15:00.000 (TDB)
*/
timout_c ( etbeg, TDBFMT, TIMLEN, timstr );
printf ( " Start time = %s\n", timstr );
timout_c ( etend, TDBFMT, TIMLEN, timstr );
printf ( " Stop time = %s\n", timstr );
printf ( "\n" );
/*
Initialize the "confinement" window with the interval
over which we'll conduct the search.
*/
wninsd_c ( etbeg, etend, &cnfine );
/*
In the call below, the maximum number of window
intervals gfposc_c can store internally is set to MAXIVL.
Now search for the time period, within our confinement
window, during which the apparent target has elevation
at least equal to the elevation limit.
*/
gfposc_c ( target, obsfrm, abcorr, srfpt,
crdsys, coord, relate, revlim,
adjust, stepsz, MAXIVL, &cnfine, &riswin );
/*
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.
*/
gfoclt_c ( occtyp, front, fshape, fframe,
back, bshape, bframe, abcorr,
srfpt, stepsz, &riswin, &occwin );
/*
Subtract the occultation window from the view period
window: this yields the time periods when the target
is visible.
*/
wndifd_c ( &riswin, &occwin, &viswin );
/*
The function wncard_c returns the number of intervals
in a SPICE window.
*/
winsiz = wncard_c( &viswin );
if ( winsiz == 0 )
{
printf ( "No events were found.\n" );
}
else
{
/*
Display the visibility time periods.
*/
printf ( "Visibility times of %s as seen from %s:"
"\n\n",
target, srfpt );
for ( i = 0; i < winsiz; i++ )
{
/*
Fetch the start and stop times of the Ith interval
from the search result window viswin.
*/
wnfetd_c ( &viswin, i, &intbeg, &intend );
/*
Convert the rise time to a TDB calendar string.
*/
timout_c ( intbeg, TDBFMT, TIMLEN, timstr );
/*
Write the string to standard output.
*/
if ( i == 0 )
{
printf ( "Visibility or window start time: %s\n",
timstr );
}
else
{
printf ( "Visibility start time: %s\n",
timstr );
}
/*
Convert the set time to a TDB calendar string.
*/
timout_c ( intend, TDBFMT, TIMLEN, timstr );
/*
Write the string to standard output.
*/
if ( i == winsiz-1 )
{
printf ( "Visibility or window stop time: %s\n",
timstr );
}
else
{
printf ( "Visibility stop time: %s\n",
timstr );
}
printf ( "\n" );
}
}
return ( 0 );
}
Solution Sample Output
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)
|