| PHSRM Geometric Event Finding Hands-On Lesson (IDL) |
Table of ContentsPHSRM Geometric Event Finding Hands-On Lesson (IDL) Overview Note About HTML Links References Tutorials Required Readings The Permuted Index Icy API Documentation Kernels Used Icy 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 PHSRM Geometric Event Finding Hands-On Lesson (IDL)
Overview
In this lesson the student is asked to construct a program that finds the time intervals, within a specified time range, when the Phobos Sample Return spacecraft (PHSRM) is visible from the USSURIYSK tracking station. 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 ``icy/'' tree and copy this document to that subdirectory before loading it into a Web browser. ReferencesTutorials
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) subsystemThese tutorials are available from the NAIF ftp server at JPL:
http://naif.jpl.nasa.gov/naif/tutorials.html Required Readings
Name Lesson steps/routines 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 icy.req The Icy API The Permuted Index
This text document provides a simple mechanism by which users can discover which Icy routines perform functions of interest, as well as the names of the source files that contain these routines. Icy API Documentation
For example, the document
icy/doc/html/icy/cspice_str2et.htmldescribes the cspice_str2et routine. Kernels Used
File Name Type Description ----------------------- ---- -------------------------- de421xs.bsp SPK Planetary ephemeris SPK earthstns_phsrm_itrf93_110118.bsp SPK Russian stations SPK earthstns_phsrm_topo_110118.tf FK Russian stations FK earth_070425_370426_predict.bpc PCK Binary PCK for Earth phsrm_130114_130114_130214_nom2.bsp SPK PHSRM trajectory SPK naif0009.tls LSK Generic LSK pck00009.tpc PCK Generic PCK phsrm_v00.tf FK PHSRM FKThese SPICE kernels are included in the lesson package available from the PHSRM server at IKI:
http://spice.ikiweb.ru/PHSRM/kernels Icy Routines Used
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. windowRefer to the headers of the various procedures listed above, as detailed interface specifications are provided with the source code. Find View PeriodsTask Statement
2013 JAN 17 TDB 2013 JAN 27 TDBwhen PHSRM is visible from the tracking station USSURIYSK. 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 USSURIYSK_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 1.0.0 21-JUL-2011 (BVS)
Identify names of kernels to load:
\begindata
KERNELS_TO_LOAD = (
'kernels/spk/de421xs.bsp'
'kernels/spk/earthstns_phsrm_itrf93_110118.bsp'
'kernels/fk/earthstns_phsrm_topo_110118.tf'
'kernels/pck/earth_070425_370426_predict.bpc'
'kernels/lsk/naif0009.tls'
'kernels/spk/phsrm_130114_130114_130214_nom2.bsp'
'kernels/pck/pck00009.tpc'
'kernels/fk/phsrm_v00.tf'
)
\begintext
Solution Code
PRO viewpr
;; Find and display the window of times when the PHSRM
;; spacecraft is above a specified elevation limit in the
;; topocentric reference frame of tracking station USSURIYSK.
;;
;; 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 = 'USSURIYSK'
obsfrm = 'USSURIYSK_TOPO'
target = 'PHSRM'
abcorr = 'CN+S'
start = '2013 JAN 17 TDB'
stop = '2013 JAN 27 TDB'
elvlim = 6.0d
;;
;; 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.0d
;;
;; 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.0d
;;
;; Display a banner for the output report:
;;
print, ' '
print, 'Inputs for target visibility search:'
print, ' '
print, ' Target = ' + target
print, ' Observation surface location = ' + srfpt
print, ' Observer''s reference frame = ' + obsfrm
print, FORMAT = '(A,F8.6)', $
' Elevation limit (degrees) = ', elvlim
print, ' Aberration correction = ' + abcorr
print, FORMAT = '(A,F10.6)', $
' Step size (seconds) = ', stepsz
;;
;; Convert the start and stop times to ET.
;;
cspice_str2et, start, etbeg
cspice_str2et, stop, etend
;;
;; Display the search interval start time and stop
;; times using the format shown below.
;;
;; 2013 JAN 25 20:15:00.000 (TDB)
;;
cspice_timout, etbeg, TDBFMT, TIMLEN, timstr0
cspice_timout, etend, TDBFMT, TIMLEN, timstr1
print, ' Start time = ' + timstr0
print, ' Stop time = ' + timstr1
print, ' '
;;
;; Create the "confinement" window; store in this window
;; the interval over which we'll conduct the search.
;;
cnfine = cspice_celld( 2 )
cspice_wninsd, etbeg, etend, cnfine
;;
;; Create an empty search result window that can hold MAXIVL
;; intervals.
;;
riswin = cspice_celld( MAXIVL )
;;
;; In the call below, the maximum number of window
;; intervals cspice_gfposc 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.
;;
cspice_gfposc, target, obsfrm, abcorr, srfpt, $
crdsys, coord, relate, revlim, $
adjust, stepsz, MAXIVL, cnfine, riswin
;;
;; The function cspice_wncard returns the number of intervals
;; in a SPICE window.
;;
winsiz = cspice_wncard( riswin )
;;
;; Display the rise and set times.
;;
if winsiz EQ 0 then begin
print, 'No events were found.'
endif else begin
;;
;; Display the visibility time periods.
;;
print, 'Visibility times of ' + TARGET + $
' as seen from ' + SRFPT + ':'
print, ' '
for i = 0, winsiz-1 do begin
;;
;; Fetch the Ith interval from the window.
;;
cspice_wnfetd, riswin, i, intbeg, intend
;;
;; Convert the rise time to a TDB calendar string.
;;
cspice_timout, intbeg, TDBFMT, TIMLEN, timstr
;;
;; Write the string to standard output.
;;
if i EQ 0 then begin
line = 'Visibility or window start time: '
endif else begin
line = 'Visibility start time: '
endelse
print, line + timstr
;;
;; Convert the set time to a TDB calendar string.
;;
cspice_timout, intend, TDBFMT, TIMLEN, timstr
;;
;; Write the string to standard output.
;;
if i EQ (winsiz-1) then begin
line = 'Visibility or window stop time: '
endif else begin
line = 'Visibility stop time: '
endelse
print, line + timstr
print, ' '
endfor
endelse
;;
;; Unload kernels so they're not accidentally used by another
;; SPICE-based program during the current IDL session.
;;
cspice_kclear
END
Solution Sample Output
After compiling the program, execute it. The output is:
IDL Version 8.1 (linux x86_64 m64).
Installation number: 8490.
Licensed for use by: Jet Propulsion Laboratory
% Compiled module: VIEWPR.
% Loaded DLM: ICY.
Inputs for target visibility search:
Target = PHSRM
Observation surface location = USSURIYSK
Observer's reference frame = USSURIYSK_TOPO
Elevation limit (degrees) = 6.000000
Aberration correction = CN+S
Step size (seconds) = 300.000000
Start time = 2013 JAN 17 00:00:00.000 (TDB)
Stop time = 2013 JAN 27 00:00:00.000 (TDB)
Visibility times of PHSRM as seen from USSURIYSK:
Visibility or window start time: 2013 JAN 17 00:33:31.361 (TDB)
Visibility stop time: 2013 JAN 17 09:02:45.225 (TDB)
Visibility start time: 2013 JAN 18 00:31:30.565 (TDB)
Visibility stop time: 2013 JAN 18 09:03:09.674 (TDB)
Visibility start time: 2013 JAN 19 00:29:28.884 (TDB)
Visibility stop time: 2013 JAN 19 09:03:34.081 (TDB)
Visibility start time: 2013 JAN 20 00:27:26.144 (TDB)
Visibility stop time: 2013 JAN 20 09:03:58.190 (TDB)
Visibility start time: 2013 JAN 21 00:25:22.338 (TDB)
Visibility stop time: 2013 JAN 21 09:04:21.910 (TDB)
Visibility start time: 2013 JAN 22 00:23:17.607 (TDB)
Visibility stop time: 2013 JAN 22 09:04:45.379 (TDB)
Visibility start time: 2013 JAN 23 00:21:12.160 (TDB)
Visibility stop time: 2013 JAN 23 09:05:08.811 (TDB)
Visibility start time: 2013 JAN 24 00:19:06.175 (TDB)
Visibility stop time: 2013 JAN 24 09:05:32.377 (TDB)
Visibility start time: 2013 JAN 25 00:16:59.683 (TDB)
Visibility stop time: 2013 JAN 25 09:05:56.090 (TDB)
Visibility start time: 2013 JAN 26 00:14:52.583 (TDB)
Visibility or window stop time: 2013 JAN 26 09:06:19.734 (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
PRO visibl
;; Find and display the window of times when the PHSRM
;; spacecraft is above a specified elevation limit in the
;; topocentric reference frame of tracking station USSURIYSK
;; and is not occulted by Mars.
;;
;; 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 = 'USSURIYSK'
obsfrm = 'USSURIYSK_TOPO'
target = 'PHSRM'
abcorr = 'CN+S'
start = '2013 JAN 17 TDB'
stop = '2013 JAN 27 TDB'
elvlim = 6.0d
;;
;; 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.0d
;;
;; 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.0d
;;
;; Display a banner for the output report:
;;
print, ' '
print, 'Inputs for target visibility search:'
print, ' '
print, ' Target = ' + target
print, ' Observation surface location = ' + srfpt
print, ' Observer''s reference frame = ' + obsfrm
print, ' Blocking body = ' + front
print, ' Blocker''s reference frame = ' + fframe
print, FORMAT = '(A,F8.6)', $
' Elevation limit (degrees) = ', elvlim
print, ' Aberration correction = ' + abcorr
print, FORMAT = '(A,F10.6)', $
' Step size (seconds) = ', stepsz
;;
;; Convert the start and stop times to ET.
;;
cspice_str2et, start, etbeg
cspice_str2et, stop, etend
;;
;; Display the search interval start time and stop
;; times using the format shown below.
;;
;; 2013 JAN 25 20:15:00.000 (TDB)
;;
cspice_timout, etbeg, TDBFMT, TIMLEN, timstr0
cspice_timout, etend, TDBFMT, TIMLEN, timstr1
print, ' Start time = ' + timstr0
print, ' Stop time = ' + timstr1
print, ' '
;;
;; Create the "confinement" window; store in this window
;; the interval over which we'll conduct the search.
;;
cnfine = cspice_celld( 2 )
cspice_wninsd, etbeg, etend, cnfine
;;
;; Create an empty search result window that can hold MAXIVL
;; intervals.
;;
riswin = cspice_celld( MAXIVL )
;;
;; In the call below, the maximum number of window
;; intervals cspice_gfposc 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.
;;
cspice_gfposc, 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.
;;
occwin = cspice_celld( MAXIVL )
cspice_gfoclt, 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.
;;
viswin = cspice_celld( MAXIVL )
cspice_wndifd, riswin, occwin, viswin
;;
;; The function cspice_wncard returns the number of intervals
;; in a SPICE window.
;;
winsiz = cspice_wncard( viswin )
;;
;; Display the rise and set times.
;;
if winsiz EQ 0 then begin
print, 'No events were found.'
endif else begin
;;
;; Display the visibility time periods.
;;
print, 'Visibility times of ' + TARGET + $
' as seen from ' + SRFPT + ':'
print, ' '
for i = 0, winsiz-1 do begin
;;
;; Fetch the Ith interval from the window.
;;
cspice_wnfetd, viswin, i, intbeg, intend
;;
;; Convert the rise time to a TDB calendar string.
;;
cspice_timout, intbeg, TDBFMT, TIMLEN, timstr
;;
;; Write the string to standard output.
;;
if i EQ 0 then begin
line = 'Visibility or window start time: '
endif else begin
line = 'Visibility start time: '
endelse
print, line + timstr
;;
;; Convert the set time to a TDB calendar string.
;;
cspice_timout, intend, TDBFMT, TIMLEN, timstr
;;
;; Write the string to standard output.
;;
if i EQ (winsiz-1) then begin
line = 'Visibility or window stop time: '
endif else begin
line = 'Visibility stop time: '
endelse
print, line + timstr
print, ' '
endfor
endelse
;;
;; Unload kernels so they're not accidentally used by another
;; SPICE-based program during the current IDL session.
;;
cspice_kclear
END
Solution Sample Output
After compiling the program, execute it. The output is:
IDL Version 8.1 (linux x86_64 m64).
Installation number: 8490.
Licensed for use by: Jet Propulsion Laboratory
% Compiled module: VISIBL.
% Loaded DLM: ICY.
Inputs for target visibility search:
Target = PHSRM
Observation surface location = USSURIYSK
Observer's reference frame = USSURIYSK_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 = 2013 JAN 17 00:00:00.000 (TDB)
Stop time = 2013 JAN 27 00:00:00.000 (TDB)
Visibility times of PHSRM as seen from USSURIYSK:
Visibility or window start time: 2013 JAN 17 00:33:31.361 (TDB)
Visibility stop time: 2013 JAN 17 01:47:16.462 (TDB)
Visibility start time: 2013 JAN 17 02:07:19.374 (TDB)
Visibility stop time: 2013 JAN 17 09:02:45.225 (TDB)
Visibility start time: 2013 JAN 18 00:31:30.565 (TDB)
Visibility stop time: 2013 JAN 18 00:47:36.315 (TDB)
Visibility start time: 2013 JAN 18 01:05:44.180 (TDB)
Visibility stop time: 2013 JAN 18 08:26:58.267 (TDB)
Visibility start time: 2013 JAN 18 08:45:15.036 (TDB)
Visibility stop time: 2013 JAN 18 09:03:09.674 (TDB)
Visibility start time: 2013 JAN 19 00:29:28.884 (TDB)
Visibility stop time: 2013 JAN 19 07:26:28.944 (TDB)
Visibility start time: 2013 JAN 19 07:42:20.612 (TDB)
Visibility stop time: 2013 JAN 19 09:03:34.081 (TDB)
Visibility start time: 2013 JAN 20 00:27:26.144 (TDB)
Visibility stop time: 2013 JAN 20 06:25:05.813 (TDB)
Visibility start time: 2013 JAN 20 06:40:32.764 (TDB)
Visibility stop time: 2013 JAN 20 09:03:58.190 (TDB)
Visibility start time: 2013 JAN 21 00:25:22.338 (TDB)
Visibility stop time: 2013 JAN 21 05:25:49.659 (TDB)
Visibility start time: 2013 JAN 21 05:38:51.869 (TDB)
Visibility stop time: 2013 JAN 21 09:04:21.910 (TDB)
Visibility start time: 2013 JAN 22 00:23:17.607 (TDB)
Visibility stop time: 2013 JAN 22 04:24:38.313 (TDB)
Visibility start time: 2013 JAN 22 04:35:28.127 (TDB)
Visibility stop time: 2013 JAN 22 09:04:45.379 (TDB)
Visibility start time: 2013 JAN 23 00:21:12.160 (TDB)
Visibility stop time: 2013 JAN 23 03:24:26.753 (TDB)
Visibility start time: 2013 JAN 23 03:34:27.263 (TDB)
Visibility stop time: 2013 JAN 23 09:05:08.811 (TDB)
Visibility start time: 2013 JAN 24 00:19:06.175 (TDB)
Visibility stop time: 2013 JAN 24 02:26:30.810 (TDB)
Visibility start time: 2013 JAN 24 02:29:39.646 (TDB)
Visibility stop time: 2013 JAN 24 09:05:32.377 (TDB)
Visibility start time: 2013 JAN 25 00:16:59.683 (TDB)
Visibility stop time: 2013 JAN 25 09:05:56.090 (TDB)
Visibility start time: 2013 JAN 26 00:14:52.583 (TDB)
Visibility or window stop time: 2013 JAN 26 09:06:19.734 (TDB)
|