Index Page
cspice_ckcov
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Abstract
I/O
Examples
Particulars
Required Reading
Version
Index_Entries

Abstract


   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.

I/O

   
   Given:

      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
               CK file.
 
      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
               values:
  
                     "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'.

   the call:

      cspice_ckcov, ck, idcode, needav, level, tol, timsys, cover

   returns:

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

Examples


   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.
      ;;
      cspice_furnsh, 'standard.tm'
      cspice_furnsh, SCLK

      ;;
      ;; 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, '========================================'
         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 
            ;; strings.
            ;;
            cspice_timout, [b,e], $ 
                           'YYYY MON DD HR:MN:SC.### (TDB) ::TDB',  $
                           TIMLEN ,$
                           timstr 

            print, 'Interval: ', j
            print, 'Start   : ', timstr[0]
            print, 'Stop    : ', timstr[1]
            print

         
        endfor

    endfor
      
      ;;
      ;; It's always good form to unload kernels after use,
      ;; particularly in IDL due to data persistence.
      ;;
      cspice_kclear

   IDL outputs:
   
      ========================================
      Coverage for object:      -82000
      Interval:        0
      Start   : 1999 AUG 17 17:31:05.601 (TDB)
      Stop    : 1999 AUG 17 23:06:46.222 (TDB)

      Interval:        1
      Start   : 1999 AUG 17 23:06:49.472 (TDB)
      Stop    : 1999 AUG 18 06:07:10.057 (TDB)

      Interval:        2
      Start   : 1999 AUG 18 06:07:13.307 (TDB)
      Stop    : 1999 AUG 18 11:53:21.924 (TDB)

      Interval:        3
      Start   : 1999 AUG 18 11:53:25.174 (TDB)
      Stop    : 1999 AUG 18 13:31:05.135 (TDB)

Particulars


   This routine provides an API via which applications can determine 
   the coverage a specified CK file provides for a specified 
   object. 

Required Reading


   ICY.REQ
   CK.REQ
   CELLS.REQ 
   DAF.REQ 
   TIME.REQ 
   WINDOWS.REQ 

Version


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

   -Icy Version 1.0.0, 30-DEC-2004, EDW (JPL)

Index_Entries

 
   get coverage window for ck object 
 



Wed Apr  5 17:57:59 2017