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 returns the coverage window for a specified ephemeris
   object in a specified SPK file.

I/O


   Given:

      spk       the name, or cell of names, of SPICE SPK file(s).

                [n,c1] = size(spk); char = class(spk)

                  or

                [1,n] = size(spk); cell = class(spk)

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

                [1,1] = size(idcode); int32 = class(idcode)

      room      the number of intervals for use as a workspace by the
                routine. This value should equal at least the number
                of intervals corresponding to 'idcode' in 'spk'.

                [1,1] = size(room); int32 = class(room)

      cover_i   an optional input describing a either an empty window or a
                window array created from a previous cspice_spkcov call.
                Inclusion of this window argument results in an output
                window consisting of a union of the data retrieved from the
                'spk' kernels and the data in 'cover_i'.

                [2m,1] = size(cover_i); double = class(cover_i)

                   or

                [0,0] = size(cover_i), double = class(cover_i)

   the call:

      cover = cspice_spkcov( spk, idcode, room, cover_i )

         or

      cover = cspice_spkcov( spk, idcode, room )

   returns:

      cover   the window containing the coverage for 'idcode'', i.e.
              the set of time intervals for which 'idcode'
              data exist in the file 'spk'. The array 'cover'
              contains the pairs of endpoints of these intervals.

              [2p,1] = size(cover), double = class(cover)

                 or

              [0,1] = size(cover), double = class(cover)

              Each window defined as a pair of endpoints such that:

                  window 1 = cover(1:2)
                  window 2 = cover(3:4)
                  window 3 = cover(5:6)
                           ...
                  window p = cover(2p-1,2p)

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

              'cover' returns an empty set if 'spk' lacks coverage for
              'idcode'.  If 'cover_i' exists in the argument list, 'cover'
              returns as a union of the coverage data found in 'spk' and
              the data in 'cover_i'. 'cover' can overwrite 'cover_i'.

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 CK IDs found in a CK, or set of
   CKs, and the time coverage of the data corresponding to those IDs.
   This example calls both cspice_ckobj and cspice_ckcov. In practice,
   algorithms using cspice_spkobj will also use cspice_spkcov and
   vice-versa.

   function spkcov_t(SPK)

      MAXOBJ = 1000;
      WINSIZ = 1000;
      LSK    = 'naif0010.tls';

      %
      % 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.
      %
      ids = cspice_spkobj( SPK, MAXIV );

      %
      % 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=1:numel(ids)

         %
         % Extract the coverage data for object 'ids(i)'.
         %
         cover     = cspice_spkcov( SPK, ids(i), WINSIZ );
         [row,col] = size(cover);

         %
         % Display a simple banner.
         %
         fprintf( '========================================\n')
         fprintf( 'Coverage for object %d\n', ids(i) )

         %
         %  'cover' has dimension 2Nx1, where 'row' has the value 2N with
         %  each window defined as a pair of endpoints such that:
         %
         %  window 1 = cover(1:2)
         %  window 2 = cover(3:4)
         %  window 3 = cover(5:6)
         %        ...
         %  window N = cover(2N-1,2N)
         %
         % Loop from 1 to 'row' with step size 2.
         %
         for j=1:2:row

            %
            % Convert the endpoints to TDB calendar format time strings
            % and display them. Pass the endpoints in an array,
            % so cspice_timout returns an array of time strings.
            %
            % Recall a vectorized input has dimension 1xM so transpose
            % the 'cover' slice.
            %
            timstr = cspice_timout( cover(j:j+1)', ...
                                'YYYY MON DD HR:MN:SC.### (TDB) ::TDB' );
            fprintf('Interval: %d\n'  , (j+1)/2 )
            fprintf('   Start: %s\n'  , timstr(1,:) )
            fprintf('    Stop: %s\n\n', timstr(2,:) )

         end

      end

      %
      % Empty the kernel pool.
      %
      cspice_kclear

   Example (1):

   Matlab outputs:

      spkobj_t ( {'/sat393.bsp', 'ura112.bsp'} )

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

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

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

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

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

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

         ...

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

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

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

   Example (2):

   MATLAB outputs:

      >> spkobj_t( { '/kernels/Hubble/1990-01-01_1996-01-01.bsp', ...
                     '/kernels/Hubble/2002-01-01_2006-12-31.bsp' } )

      ========================================
      Coverage for object -48
      Interval: 1
         Start: 1990 APR 25 02:01:40.071 (TDB)
          Stop: 1995 DEC 31 17:42:03.755 (TDB)

      Interval: 2
         Start: 2002 JAN 01 02:02:00.084 (TDB)
          Stop: 2006 DEC 29 09:36:39.732 (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


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

   MICE.REQ
   SPK.REQ
   CELLS.REQ
   DAF.REQ
   TIME.REQ
   WINDOWS.REQ

Version


   -Mice Version 1.2.1, 10-MAR-2015, EDW (JPL)

      Edited I/O section to conform to NAIF standard for Mice documentation.

   -Mice Version 1.2.0, 03-APR-2012, EDW (JPL)

      Edits to Example code and comments. No change to Example code
      functionality.

      Renamed the argument 'size' to 'room'. "size" is a Matlab function
      name and it's seriously dumb to use a function name word as an argument
      name.

      Edited I/O section to conform to NAIF standard for Mice documentation.

   -Mice Version 1.1.0, 29-DEC-2008, EDW (JPL)

      Edited description of 'size'; 'size' now defines the maximum
      number of intervals for the internal workspace window.

      The 'cover_i' argument may now have the empty array value, [],
      on input.

      Added range restriction on size.

      Corrected several typos.

   -Mice Version 1.0.0, 18-JUN-2007, EDW (JPL)

Index_Entries


   get coverage window for spk object


Wed Apr  5 18:00:34 2017