Abstract

   CSPICE_DSKOBJ finds the set of body ID codes of all objects for which
   topographic data are provided in a specified DSK file.

I/O

   Given:

      dskfnm   the name of a DSK file.

               help, dskfnm
                  STRING = Scalar

               This file will be opened for read access by this routine.

      bodids   an initialized SPICE set data structure.

               help, bodids
                  STRUCT = cspice_celli(N)

               `bodids' optionally may contain a set of body ID codes on
               input; on output, the data already present in `bodids' will
               be combined with ID code set found for the file `dskfnm'.

               If `bodids' contains no data on input, its size and
               cardinality still must be initialized.

               The user must create `bodids' using cspice_celli. (Note:
               a set is a type of cell).

   the call:

      cspice_dskobj, dskfnm, bodids

   returns:

      bodids   a SPICE set data structure that contains the union of its
               contents upon input with the set of body ID codes of segments in
               the indicated DSK file.

               help, bodids
                  STRUCT = cspice_celli(N)

               The elements of SPICE sets are unique; each ID code in
               `bodids' appears only once, even if the DSK file contains
               multiple segments for that ID code.

               See the -Examples section below for a complete example
               program showing how to retrieve the body and surface ID
               codes from a DSK file.

Parameters

   None.

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.

   1) Display the coverage for each object in a specified DSK file.
      Find the set of objects in the file. Loop over the contents
      of the ID code set: find the surface ID for each item in the
      set and display the surface ID.


      Example code begins here.


      ;;
      ;; Examine a DSK file and identify the set of
      ;; central bodies associated with the segments
      ;; in the file. For each body, find the
      ;; set of surfaces associated with that body.
      ;;
      PRO dskobj_ex1, dsknam

         ;;
         ;; Local constants
         ;;
         MAXID  = 1000L

         ;;
         ;; Local variables
         ;;
         bodids = cspice_celli(MAXID)
         srfids = cspice_celli(MAXID)

         cspice_dskobj, dsknam, bodids

         for i=0, cspice_card( bodids ) - 1 do begin

            obj = bodids.base[ bodids.data + i ]

            print, 'Body ID:     '  , obj

            ;;
            ;; Get the surface IDs for the Ith body.
            ;;
            cspice_dsksrf, dsknam, obj, srfids

            for i=0, cspice_card( srfids ) - 1 do begin

               srf = srfids.base[ srfids.data + i ]

               print, '   Surface ID:  '  , srf

            endfor

         endfor

      END


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

         dsknam = 'phobos512.bds'

      the output was:


      Body ID:              401
         Surface ID:           401

Particulars

   This routine provides an API via which applications can determine
   the set of objects for which there are topographic data in a
   specified DSK file.

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 DAS, the error SPICE(INVALIDARCHTYPE) is signaled
       by a routine in the call tree of this routine.

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

   4)  If the DSK file cannot be opened or read, an error is signaled
       by a routine in the call tree of this routine.

   5)  If the size of the output set argument `bodids' is insufficient
       to contain the actual number of ID codes of objects covered by
       the indicated DSK file, the error SPICE(CELLTOOSMALL) is
       signaled by a routine in the call tree of this routine.

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

   7)  If any of the input arguments, `dskfnm' or `bodids', 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

   See the description of the argument `dskfnm' above.

Restrictions

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

Required_Reading

   CELLS.REQ
   DAS.REQ
   DSK.REQ
   ICY.REQ
   NAIF_IDS.REQ
   SETS.REQ

Literature_References

   None.

Author_and_Institution

   J. Diaz del Rio     (ODC Space)
   M. Liukis           (JPL)
   E.D. Wright         (JPL)

Version

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

       Changed the input argument name "dsk" to "dskfnm" for consistency
       with other routines.

       Edited the header to comply with NAIF standard.

       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.0, 14-DEC-2016 (ML) (EDW)

Index_Entries

   find id codes of ephemeris objects in DSK file
   find id codes of bodies in DSK file