Index Page
cspice_spkobj
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_SPKOBJ returns the set of ID codes of all objects in a
   specified SPK file.

I/O


   Given:

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

              [n,c] = size(spk), char = class(spk)

                 or

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

      room    an integer scalar defining the maximum number of SPK IDs to
              return from 'spk'.

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

      ids_i   an optional input describing an (Nx1) array of SPK
              ID codes. Inclusion of this array results in an output
              array consisting of a union of the data retrieved from
              the 'spk' kernels and the data in 'ids_i'.

              [m,1] = size(ids_i), int32 = class(ids_i)

                 or

              [0,0] = size(ids_i), int32 = class(ids_i)

   the call:

      ids = cspice_spkobj( spk, room, ids_i)

         or

      ids = cspice_spkobj( spk, room)

   returns:

      ids   an array containing the set of unique NAIF ID
            codes for which ephemeris data exists in 'spk'. If 'ids_i'
            exists in the argument list, 'ids' returns as a union of
            the coverage data found in 'spk' and the data in 'ids_i'.
            'ids' can overwrite 'ids_i'.

            [p,1] = size(ids), int32 = class(ids)

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.

   function spkobj_t(SPK)

      MAXIV  = 1000;
      WINSIZ = 2 * MAXIV;
      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):

      Assign an SPK kernel list as:

      >> SPK = { '/kernels/gen/spk/de405_2000-2050.bsp', ...
                 '/kernels/gen/spk/jup100.bsp' };

      >> spkobj_t(SPK)

   MATLAB outputs:

      ========================================
      Coverage for object 1
      Interval: 1
         Start: 2000 JAN 01 00:01:04.183 (TDB)
          Stop: 2050 JAN 01 00:01:04.183 (TDB)

      ========================================
      Coverage for object 2
      Interval: 1
         Start: 2000 JAN 01 00:01:04.183 (TDB)
          Stop: 2050 JAN 01 00:01:04.183 (TDB)

      ========================================
      Coverage for object 3
      Interval: 1
         Start: 1973 NOV 01 00:00:00.000 (TDB)
          Stop: 2050 JAN 01 00:01:04.183 (TDB)

      ========================================
      Coverage for object 4
      Interval: 1
         Start: 2000 JAN 01 00:01:04.183 (TDB)
          Stop: 2050 JAN 01 00:01:04.183 (TDB)

      ========================================
      Coverage for object 5
      Interval: 1
         Start: 1973 NOV 01 00:00:00.000 (TDB)
          Stop: 2050 JAN 01 00:01:04.183 (TDB)

             ... continued ...

      ========================================
      Coverage for object 501
      Interval: 1
         Start: 1973 NOV 01 00:00:00.000 (TDB)
          Stop: 2023 NOV 03 00:00:00.000 (TDB)

      ========================================
      Coverage for object 502
      Interval: 1
         Start: 1973 NOV 01 00:00:00.000 (TDB)
          Stop: 2023 NOV 03 00:00:00.000 (TDB)

      ========================================
      Coverage for object 503
      Interval: 1
         Start: 1973 NOV 01 00:00:00.000 (TDB)
          Stop: 2023 NOV 03 00:00:00.000 (TDB)

      ========================================
      Coverage for object 504
      Interval: 1
         Start: 1973 NOV 01 00:00:00.000 (TDB)
          Stop: 2023 NOV 03 00:00:00.000 (TDB)

      ========================================
      Coverage for object 599
      Interval: 1
         Start: 1973 NOV 01 00:00:00.000 (TDB)
          Stop: 2023 NOV 03 00:00:00.000 (TDB)

   Example (2):

      Assign an SPK kernel list as:

      >> SPK = { '/kernels/Hubble/1990-01-01_1996-01-01.bsp', ...
                 '/kernels/Hubble/2002-01-01_2006-12-31.bsp' };

      >> spkobj_t(SPK)

   MATLAB outputs:

      ========================================
      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 set of objects for which there are ephemeris data in a
   specified SPK file.

Required Reading


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

   MICE.REQ
   SPK.REQ
   CELLS.REQ
   DAF.REQ
   SETS.REQ
   NAIF_IDS.REQ
   WINDOWS.REQ

Version


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

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

      Added error check on 'ids_i' to ensure the argument either has
      shape [N,1] or is an empty array with shape [0,0].

      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.2.0, 13-AUG-2009, EDW (JPL)

      The union of 'ids_i'  with the interface return argument 'ids'
      again calculated using the "unique" function, replacing "union."
      This implementation results in the expected behavior of the
      call in octave when 'ids_i' contains zero or one element.

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

      Corrected error in comment description for 'ids_i'.
      Removed the line:

         Note: 'ids_i' cannot be an empty array.

      The argument can have the empty array value, [], on
      input.

      'ids_i' union with interface return call now calculated
      using the "union" function instead of "unique."

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

Index_Entries


   find id codes in spk file


Wed Apr  5 18:00:35 2017