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

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_SPKCOV finds the coverage window for a specified ephemeris object
   in a specified SPK file.

I/O


   Given:

      spkfnm   the name of an SPK file.

               help, spkfnm
                  STRING = Scalar

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

               help, idcode
                  LONG = Scalar

      cover    an initialized SPICE window data structure.

               help, cover
                  STRUCT = cspice_celld(2*N)

               `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 `spkfnm'.

               The user must create `cover' using cspice_celld.

   the call:

      cspice_spkcov, spkfnm, idcode, cover

   returns:

      cover    a SPICE window data structure which represents the merged
               coverage for `idcode'.

               help, cover
                  STRUCT = cspice_celld(2*N)

               This is the set of time intervals for which data for `idcode'
               are present in the file `spkfnm', 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'.

Parameters


   None.

Examples


   Any numerical results shown for these examples may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

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

      Use the LSK kernel below to load the leap seconds and time
      constants required for the time conversions.

         naif0012.tls


      Example code begins here.


      PRO spkcov_ex1, spknam

            ;;
            ;; 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    = 'naif0012.tls'

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

            ;;
            ;; Note, neither cspice_spkcov or cspice_spkobj 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(spknam) do begin
               cspice_spkobj, spknam[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(spknam) do begin
                  cspice_spkcov, spknam[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


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, with the following variable as input

         spknam = ['sat393.bsp', 'ura112.bsp']

      the output was:


      ========================================
      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:         611
      Interval:        0
      Start   : 1950 JAN 01 00:00:41.183 (TDB)
      Stop    : 2050 JAN 01 00:01:08.183 (TDB)

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

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

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

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

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

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

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

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

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

      ========================================
      Coverage for object:         649
      Interval:        0
      Start   : 1950 JAN 01 00:00:41.183 (TDB)

      [...]


      Warning: incomplete output. Only 100 out of 174 lines have been
      provided.


   2) When Example #1 was executed on a Mac/Intel/IDL8.x/64-bit
      platform, with the following variable as input

         spknam = [ 'mgs_ext12_ipng_mgs95j.bsp', 'mgs_ext26_ipng_mgs95j.bsp' ]

      the output was:


      ========================================
      Coverage for object:         -94
      Interval:        0
      Start   : 2003 JUL 23 00:00:00.000 (TDB)
      Stop    : 2003 OCT 15 01:00:00.000 (TDB)

      Interval:        1
      Start   : 2006 OCT 11 00:00:00.000 (TDB)
      Stop    : 2006 NOV 08 01:00:00.000 (TDB)


Particulars


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

Exceptions


   1)  If the input file has transfer format, the error
       SPICE(INVALIDFORMAT) is signaled by a routine in the call tree
       of this routine.

   2)  If the input file is not a transfer file but has architecture
       other than DAF, the error SPICE(INVALIDARCHTYPE) is signaled
       by a routine in the call tree of this routine.

   3)  If the input file is a binary DAF file of type other than SPK,
       the error SPICE(INVALIDFILETYPE) is signaled by a routine in
       the call tree of this routine.

   4)  If the SPK file cannot be opened or read, an error is signaled
       by a routine in the call tree of this routine. The output
       window will not be modified.

   5)  If the size of the output window argument `cover' is
       insufficient to contain the actual number of intervals in the
       coverage window for `idcode', an error is signaled by a routine
       in the call tree of this routine.

   6)  If any of the input arguments, `spkfnm', `idcode' or `cover',
       is undefined, an error is signaled by the IDL error handling
       system.

   7)  If any of the input arguments, `spkfnm', `idcode' or `cover',
       is not of the expected type, or it does not have the expected
       dimensions and size, an error is signaled by the Icy
       interface.

Files


   This routine reads an SPK file.

Restrictions


   1)  If an error occurs while this routine is updating the window
       `cover', the window may be corrupted.

Required_Reading


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

Literature_References


   None.

Author_and_Institution


   N.J. Bachman        (JPL)
   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version


   -Icy Version 1.1.0, 24-NOV-2021 (JDR)

       Changed the input argument name "spk" to "spkfnm" for consistency
       with other routines.

       Edited the header to comply with NAIF standard. Extended
       -Index_Entries.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

       Added arguments' type and size information in the -I/O section.

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

       Modified example code to use arrays of SPKs an inputs.

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

       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) (EDW)

       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)

Index_Entries


   get coverage window for spk_object
   get coverage start and stop time for spk_object
   get coverage start and stop time for ephemeris_object
   get coverage start and stop time for body



Fri Dec 31 18:43:07 2021