CSPICE_CKCOV finds the coverage window for a specified object in a
specified CK file.
For important details concerning this module's function, please refer to
the CSPICE routine ckcov_c.
ck the scalar string name of an C-kernel.
idcode the scalar integer CK ID code of an object, normally a
spacecraft structure or instrument, for which
pointing data are expected to exist in the specified
needav a scalar boolean variable indicating whether only
segments having angular velocity are to be considered
when determining coverage. When 'needav' has value true,
segments without angular velocity don't
contribute to the coverage window; when 'needav' has
has value false, all segments for 'idcode' may contribute
to the coverage window.
level the scalar string defining the level (granularity) at
which the coverage is examined. Allowed values and
corresponding meanings are:
"SEGMENT" The output coverage window contains
intervals defined by the start and
stop times of segments for the object
designated by 'idcode'.
"INTERVAL" The output coverage window contains
interpolation intervals of segments
for the object designated by
'idcode'. For type 1 segments, which
don't have interpolation intervals,
each epoch associated with a pointing
instance is treated as a singleton
interval; these intervals are added
to the coverage window.
All interpolation intervals are
considered to lie within the segment
bounds for the purpose of this
summary: if an interpolation
interval extends beyond the segment
coverage interval, only its
intersection with the segment
coverage interval is considered to
contribute to the total coverage.
tol the scalar double precision tolerance value expressed
in ticks of the spacecraft clock associated with 'idcode'.
Before each interval is inserted into the coverage window,
the interval is intersected with the segment coverage
interval, then if the intersection is non-empty, it
is expanded by 'tol': the left endpoint of the
intersection interval is reduced by 'tol' and the
right endpoint is increased by 'tol'. Adjusted
interval endpoints, when expressed as encoded SCLK,
never are less than zero ticks. Any intervals that
overlap as a result of the expansion are merged.
The coverage window returned when tol > 0 indicates
the coverage provided by the file to the CK readers
cspice_ckgpav and cspice_ckgp when that value of 'tol'
is passed to them as an input.
timsys the scalar string indicating the time system used in the
output coverage window. 'timsys' may have the
"SCLK" Elements of 'cover' are expressed in
encoded SCLK ("ticks"), where the
clock is associated with the object
designated by 'idcode'.
"TDB" Elements of 'cover' are expressed as
seconds past J2000 TDB.
cover an initialized Icy window data structure.
'cover' optionally may contain coverage data on
input; on output, the data already present in 'cover'
will be combined with coverage found for the object
designated by 'idcode' in the file 'ck'.
cspice_ckcov, ck, idcode, needav, level, tol, timsys, cover
cover an Icy window data structure which represents
the merged coverage for 'idcode'. When the coverage
level is "INTERVAL", this is the set of time
intervals for which data for 'idcode' are present in
the file 'ck', merged with the set of time intervals
present in 'cover' on input. The merged coverage is
represented as the union of one or more disjoint time
intervals. The window 'cover' contains the pairs of
endpoints of these intervals.
When the coverage level is "SEGMENT", 'cover' is
computed in a manner similar to that described above,
but the coverage intervals used in the computation
are those of segments rather than interpolation
intervals within segments.
When 'tol' is > 0, the intervals comprising the
coverage window for 'idcode' are expanded by 'tol'
and any intervals overlapping as a result are merged.
The resulting window is returned in 'cover'. The
expanded window in no case extends beyond the segment
bounds in either direction by more than 'tol'.
The interval endpoints contained in 'cover' are
encoded spacecraft clock times if 'timsys' is "SCLK";
otherwise the times are converted from encoded
spacecraft clock to seconds past J2000 TDB.
The user must create 'cover' using cspice_celld. (Note:
a set is a type of cell).
Any numerical results shown for this example may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
;; From a given CK file, retrieve the list of objects listed
;; in the file then retrieve the time coverage for each object.
;; Local parameters...
SPICEFALSE = 0B
MAXIV = 1000
WINSIZ = 2 * MAXIV
TIMLEN = 51
MAXOBJ = 1000
;; ...and kernels from the Cassini mission.
CK = '/kernels/cassini/ck/990817_990818ra.bc'
SCLK = '/kernels/cassini/sclk/cas00085.tsc'
;; Local variables
cover = cspice_celld( WINSIZ )
ids = cspice_celli( MAXOBJ )
;; Load a standard kernel set.
;; Find the set of objects in the CK file.
cspice_ckobj, CK, ids
;; We want to display the coverage for each object. Loop over
;; the contents of the ID code set, find the coverage for
;; each item in the set, and display the coverage.
for i=0, cspice_card( ids ) - 1 do begin
;; Find the coverage window for the current object, 'i'.
;; Empty the coverage window each time
;; so we don't include data for the previous object.
obj = ids.base[ ids.data + i ]
cspice_scard, 0L, cover
cspice_ckcov, CK, obj, SPICEFALSE, 'INTERVAL', 0.D, 'TDB', cover
;; Get the number of intervals in the coverage window.
niv = cspice_wncard( cover )
;; Display a simple banner.
print, 'Coverage for object:', obj
;; Convert the coverage interval start and stop times to TDB
;; calendar strings.
for j=0, niv-1 do begin
;; Get the endpoints of the jth interval.
cspice_wnfetd, cover, j, b, e
;; Convert the endpoints to TDB calendar
;; format time strings and display them.
;; Pass the endpoints in an array, [b,e],
;; so cspice_timout returns an array of time
cspice_timout, [b,e], $
'YYYY MON DD HR:MN:SC.### (TDB) ::TDB', $
print, 'Interval: ', j
print, 'Start : ', timstr
print, 'Stop : ', timstr
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
Coverage for object: -82000
Start : 1999 AUG 17 17:31:05.601 (TDB)
Stop : 1999 AUG 17 23:06:46.222 (TDB)
Start : 1999 AUG 17 23:06:49.472 (TDB)
Stop : 1999 AUG 18 06:07:10.057 (TDB)
Start : 1999 AUG 18 06:07:13.307 (TDB)
Stop : 1999 AUG 18 11:53:21.924 (TDB)
Start : 1999 AUG 18 11:53:25.174 (TDB)
Stop : 1999 AUG 18 13:31:05.135 (TDB)
This routine provides an API via which applications can determine
the coverage a specified CK file provides for a specified
-Icy Version 1.0.4, 04-APR-2012, EDW (JPL)
Corrected typo in argument name used in the call example.
Explicitly described ID variables as "CK IDs."
-Icy Version 1.0.3, 06-FEB-2008, EDW (JPL)
Corrected typo in abstract and call example.
-Icy Version 1.0.2, 30-NOV-2007, NJB, EDW (JPL)
Corrected bug in the Examples section program:
program now empties the coverage window prior to collecting
data for the current object. Updated example to
use cspice_wncard rather than cspice_card.
-Icy Version 1.0.1, 27-FEB-2007, EDW (JPL)
Replaced cspice_unload call in example section with
-Icy Version 1.0.0, 30-DEC-2004, EDW (JPL)
get coverage window for ck object