Index Page
cspice_spkcov
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_SPKCOV finds the coverage window for a specified ephemeris
   object in a specified SPK file.

   For important details concerning this module's function, please refer to
   the CSPICE routine spkcov_c.

I/O


   Given:

      spk      the scalar string name of an SPK file.

      idcode   is the integer ID code of an object for which
               ephemeris data are expected to exist in the
               specified SPK file.

      cover    is an initialized ICY window data structure.
               'cover' may optionally 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 'spk'.

               The user must create 'cover' using cspice_celld.

   the call:

         cspice_spkcov, spk, idcode, cover

   returns:

      cover    is an ICY window data structure which
               represents the merged coverage for `idcode'. This is
               the set of time intervals for which data for
               'idcode' are present in the file 'spk', 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.

               The interval endpoints contained in 'cover' are
               ephemeris times, expressed as seconds past J2000
               TDB.

               See the Examples section below for a complete
               example program showing how to retrieve the
               endpoints from 'cover'.

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.

   Use a simple function to display the SPK IDs found in an SPK or set of
   SPKs, and the time coverage of the data corresponding to those IDs.
   This example calls both cspice_spkobj and cspice_spkcov. In practice,
   algorithms using cspice_spkobj will also use cspice_spkcov and
   vice-versa.

      PRO SPKOBJ_T, spk

            ;;
            ;; From a given SPK file, retrieve the list of objects listed
            ;; in the file then retrieve the time coverage for each object.
            ;;
            ;; Local parameters...
            ;;
            MAXIV  = 1000
            WINSIZ = 2 * MAXIV
            TIMLEN = 51
            MAXOBJ = 1000
            LSK    = '/ftp/pub/naif/generic_kernels/lsk//naif0012.tls'

            ;;
            ;; Local variables
            ;;
            cover = cspice_celld( WINSIZ )
            ids   = cspice_celli( MAXOBJ )

            ;;
            ;; Note, neither cspice_spkcov or cspice_spkobs requires this
            ;; kernel to function. We need the data for output time
            ;; conversion.
            ;;
            cspice_furnsh, LSK

            ;;
            ;; Find the set of objects in the SPK file.
            ;;
            for i = 1, n_elements(spk) do begin
               cspice_spkobj, spk[i-1], ids
            endfor

            ;;
            ;; 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

               for k = 1, n_elements(spk) do begin
                  cspice_spkcov, spk[k-1], obj, cover
               endfor

               ;;
               ;; Get the number of intervals in the coverage window.
               ;;
               niv = cspice_card( cover ) / 2

               ;;
               ;; 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

         ;;
         ;; Empty the kernel pool.
         ;;
         cspice_kclear

      END

   IDL outputs:

      IDL> spkobj_t , ['sat393.bsp', 'ura112.bsp']
      ========================================
      Coverage for object:           3
      Interval:        0
      Start   : 1900 JAN 01 00:00:41.183 (TDB)
      Stop    : 2099 DEC 24 00:01:07.183 (TDB)

      ========================================
      Coverage for object:           6
      Interval:        0
      Start   : 1950 JAN 01 00:00:41.183 (TDB)
      Stop    : 2050 JAN 01 00:01:08.183 (TDB)

      ========================================
      Coverage for object:           7
      Interval:        0
      Start   : 1900 JAN 01 00:00:41.183 (TDB)
      Stop    : 2099 DEC 24 00:01:07.183 (TDB)

      ========================================
      Coverage for object:          10
      Interval:        0
      Start   : 1900 JAN 01 00:00:41.183 (TDB)
      Stop    : 2099 DEC 24 00:01:07.183 (TDB)

      ========================================
      Coverage for object:         399
      Interval:        0
      Start   : 1900 JAN 01 00:00:41.183 (TDB)
      Stop    : 2099 DEC 24 00:01:07.183 (TDB)

      ========================================
      Coverage for object:         610
      Interval:        0
      Start   : 1950 JAN 01 00:00:41.183 (TDB)
      Stop    : 2050 JAN 01 00:01:08.183 (TDB)

         ...

      Coverage for object:         723
      Interval:        0
      Start   : 1900 JAN 01 00:00:41.183 (TDB)
      Stop    : 2099 DEC 24 00:01:07.183 (TDB)

      ========================================
      Coverage for object:         724
      Interval:        0
      Start   : 1900 JAN 01 00:00:41.183 (TDB)
      Stop    : 2099 DEC 24 00:01:07.183 (TDB)

      ========================================
      Coverage for object:         799
      Interval:        0
      Start   : 1900 JAN 01 00:00:41.183 (TDB)
      Stop    : 2099 DEC 24 00:01:07.183 (TDB)

Particulars


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

Required Reading


   ICY.REQ
   SPK.REQ
   CELLS.REQ
   DAF.REQ
   TIME.REQ
   WINDOWS.REQ

Version


   -Icy Version 1.0.3, 05-JAN-2016, EDW (JPL)

      Modified example code to use arrays of SPKs an inputs.

   -Icy Version 1.0.2, 25-APR-2013, EDW (JPL), BSV (JPL)

      Corrected error in header I/O section where the call and the
      output were not described.

   -Icy Version 1.0.1, 30-NOV-2007, NJB(JPL), 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.0, 30-DEC-2004, EDW (JPL)

Index_Entries


   get coverage window for spk object




Wed Apr  5 17:58:03 2017