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_dskd02

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


Abstract


   CSPICE_DSKD02 fetches double precision data from a type 2 DSK segment.

I/O


   Given:

      handle   the handle of a DSK file containing a type 2 segment from which
               data are to be fetched.

               help, handle
                  LONG = Scalar

      dladsc   the DLA descriptor associated with the segment from which data
               are to be fetched.

               help, dladsc
                  LONG = Array[SPICE_DLA_DSCSIZ]

      item     an integer "keyword" parameter designating the double precision
               data item to fetch.

               help, item
                  LONG = Scalar

               Names, values, and meanings of keyword parameters
               supported by this routine are shown below.

               Use of the names shown here is enabled by calling
               the DSK Icy parameter definition routine as shown:

                  @IcyUser

               This call must be made before the parameter names
               are referenced. See the example program below.

                  Name              Value Description
                  ----              ----- ----------

                  SPICE_DSK02_KWDSC   15  Array containing contents of Fortran
                                          DSK descriptor of segment. Note
                                          that DSK descriptors are not to be
                                          confused with DLA descriptors, which
                                          contain segment component base
                                          address and size information. The
                                          dimension of this array is
                                          SPICE_DSK_DSCSIZ.

                  SPICE_DSK02_KWVTBD  16  Vertex bounds. This is an array of
                                          six values giving the minimum and
                                          maximum values of each component
                                          of the vertex set.

                  SPICE_DSK02_KWVXOR  17  Voxel grid origin. This is the
                                          location of the voxel grid origin in
                                          the body-fixed frame associated with
                                          the target body.

                  SPICE_DSK02_KWVXSZ  18  Voxel size. DSK voxels are cubes;
                                          the edge length of each cube is
                                          given by the voxel size. This size
                                          applies to the fine voxel grid. Units
                                          are km.

                  SPICE_DSK02_KWVERT  19  Vertex coordinates.

      start    the start index within the specified data item from which data
               are to be fetched.

               help, start
                  LONG = Scalar

               The index of the first element of each data item is 0. This
               convention applies uniformly to all data, even if the data are
               associated with a set of 1-based indices. For example, the
               vertex ID range starts at 1 (this fact is language-independent),
               but a caller would use a `start' value of 0 to fetch the first
               vertex.

      room     the amount of room in the output array.

               help, room
                  LONG = Scalar

               It is permissible to provide an output array that has too
               little room to fetch an item in one call.

   the call:

      cspice_dskd02, handle, dladsc, item, start, room, values

   returns:

      values   a contiguous set of elements of the item designated by `item'.

               help, values
                  DOUBLE = Array[N]

               The correspondence of `values' with the elements
               of the data item is:

                  values[0]      item[start]
                     ...             ...
                  values[n-1]    item[start+n-1]

               If an error occurs on the call, `values' is undefined.

               Note, room >= n.

Parameters


   See the parameter definitions file

      IcyDLA.pro

   for declarations of DLA descriptor sizes and documentation of the
   contents of DLA descriptors.

   See the parameter definitions file

      IcyDSK.pro

   for declarations of DSK descriptor sizes and documentation of the
   contents of DSK descriptors.

   See the parameter definitions file

      IcyDSK.pro

   for declarations of DSK data type 2 (plate model) parameters.

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) Look up all the vertices associated with each plate
      of the model contained in a specified type 2 segment.
      For the first 5 plates, display the plate's vertices.

      For this example, we'll show the context of this look-up:
      opening the DSK file for read access, traversing a trivial,
      one-segment list to obtain the segment of interest.

      Example code begins here.


      PRO dskd02_ex1

         ;;
         ;; IcyUser globally defines DSK parameters.
         ;; For more information, please see IcyDSK.pro
         ;;
         @IcyUser

         ;;
         ;; Local constants
         ;;
         FMT    = '(A,3(1X,E14.6))'

         ;;
         ;; Local variables
         ;;
         dsk = ''

         ;;
         ;; Set the dimensions of the array `vrtces', which
         ;; will be used later.
         ;;
         vrtces = dindgen(3, 3) * 0.D

         ;;
         ;;  Prompt for the name of the file to search.
         ;;
         read, dsk, PROMPT='Enter name of DSK file > '

         ;;
         ;; Open the DSK file for read access.
         ;; We use the DAS-level interface for
         ;; this function.
         ;;
         cspice_dasopr, dsk, handle

         ;;
         ;; Begin a forward search through the
         ;; kernel, treating the file as a DLA.
         ;; In this example, it's a very short
         ;; search.
         ;;
         cspice_dlabfs, handle, dladsc, found

         if ( ~found ) then begin
            ;;
            ;; We arrive here only if the kernel
            ;; contains no segments. This is
            ;; unexpected, but we're prepared for it.
            ;;
            message, 'No segments found in DSK file ', + dsk
            return

         endif

         ;;
         ;; If we made it this far, `dladsc' is the
         ;; DLA descriptor of the first segment.
         ;;

         ;;
         ;; Find the number of plates in the model.
         ;;
         cspice_dski02, handle, dladsc, SPICE_DSK02_KWNP, 0, 1, ival
         print, 'Number of plates: ', ival[0]

         ;;
         ;; For the first 5 plates, look up the desired data.
         ;; Note that plate numbers range from 1 to np.
         ;;
         np = min([ival[0], 5])
         for i=1, np do begin

            ;;
            ;; For the Ith plate, find the associated
            ;; vertex IDs.  We must take into account
            ;; the fact that each plate has three
            ;; vertices when we compute the start
            ;; index.
            ;;

            start = 3*(i-1);

            ;;
            ;; Fetch the ith plate.
            ;;
            cspice_dski02, handle, dladsc, SPICE_DSK02_KWPLAT, $
                                    start,  3, vrtids

            for  j = 0, 2 do begin

               ;;
               ;; Fetch the jth vertex of the ith plate.
               ;;
               start = (vrtids[j]-1) * 3;

               cspice_dskd02, handle, dladsc, SPICE_DSK02_KWVERT, $
                                      start,  3 , vtemp

               vrtces[j,*] = vtemp

            endfor

            ;;
            ;; Display the vertices of the ith plate:
            ;;
            print
            print, 'Plate number: ', i
            print, format=FMT, 'Vertex 1: ', vrtces[0,*]
            print, format=FMT, 'Vertex 2: ', vrtces[1,*]
            print, format=FMT, 'Vertex 3: ', vrtces[2,*]

         endfor

         ;;
         ;; Close the DSK.
         ;;
         cspice_dascls, handle

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, using the DSK file named phobos512.bds, the output
      was:


      Enter name of DSK file > phobos512.bds
      Number of plates:      3145728

      Plate number:        1
      Vertex 1:   -6.774440E+00   6.268150E+00   6.011490E+00
      Vertex 2:   -6.762380E+00   6.257280E+00   6.025560E+00
      Vertex 3:   -6.757100E+00   6.277540E+00   6.020960E+00

      Plate number:        2
      Vertex 1:   -6.774440E+00   6.268150E+00   6.011490E+00
      Vertex 2:   -6.779730E+00   6.247900E+00   6.016100E+00
      Vertex 3:   -6.762380E+00   6.257280E+00   6.025560E+00

      Plate number:        3
      Vertex 1:   -6.779730E+00   6.247900E+00   6.016100E+00
      Vertex 2:   -6.767680E+00   6.237010E+00   6.030190E+00
      Vertex 3:   -6.762380E+00   6.257280E+00   6.025560E+00

      Plate number:        4
      Vertex 1:   -6.779730E+00   6.247900E+00   6.016100E+00
      Vertex 2:   -6.784990E+00   6.227620E+00   6.020700E+00
      Vertex 3:   -6.767680E+00   6.237010E+00   6.030190E+00

      Plate number:        5
      Vertex 1:   -6.784990E+00   6.227620E+00   6.020700E+00
      Vertex 2:   -6.772990E+00   6.216740E+00   6.034820E+00
      Vertex 3:   -6.767680E+00   6.237010E+00   6.030190E+00


Particulars


   Most user applications will not need to call this routine. The
   routines

      cspice_dskz02
      cspice_dskp02
      cspice_dskv02

   have simpler interfaces and may be used to fetch the plates
   and vertex counts, and the plates and vertices themselves,
   from a type DSK segment. See the documentation of those
   routines for code examples.

   DSK files are built using the DLA low-level format and
   the DAS architecture; DLA files are a specialized type of DAS
   file in which data are organized as a doubly linked list of
   segments. Each segment's data belong to contiguous components of
   character, double precision, and integer type.

   Note that the DSK descriptor for the segment is not needed by this
   routine; the DLA descriptor contains the base address and size
   information for the integer, double precision, and character
   components of the segment, and these suffice for the purpose of
   fetching data.

Exceptions


   1)  If the input handle is invalid, an error is signaled by a
       routine in the call tree of this routine.

   2)  If a file read error occurs, the error is signaled by a
       routine in the call tree of this routine.

   3)  If the input DLA descriptor is invalid, the effect of this
       routine is undefined. The error *may* be diagnosed by
       routines in the call tree of this routine, but there are no
       guarantees.

   4)  If `room' is non-positive, the error SPICE(VALUEOUTOFRANGE)
       is signaled by a routine in the call tree of this routine.

   5)  If the coarse voxel scale read from the designated segment is
       less than 1, the error SPICE(VALUEOUTOFRANGE) is signaled by a
       routine in the call tree of this routine.

   6)  If the input keyword parameter is not recognized, the error
       SPICE(NOTSUPPORTED) is signaled by a routine in the call tree
       of this routine.

   7)  If `start' is less than 1 or greater than the size of the
       item to be fetched, the error SPICE(INDEXOUTOFRANGE) is
       signaled by a routine in the call tree of this routine.

   8)  If any of the input arguments, `handle', `dladsc', `item',
       `start' or `room', is undefined, an error is signaled by the
       IDL error handling system.

   9)  If any of the input arguments, `handle', `dladsc', `item',
       `start' or `room', is not of the expected type, or it does not
       have the expected dimensions and size, an error is signaled by
       the Icy interface.

   10) If the output argument `values' is not a named variable, an
       error is signaled by the Icy interface.

Files


   See input argument `handle'.

Restrictions


   1)  This routine uses discovery check-in to boost
       execution speed. However, this routine is in
       violation of NAIF standards for use of discovery
       check-in:  routines called from this routine may
       signal errors. If errors are signaled in called
       routines, this routine's name will be missing
       from the traceback message.

Required_Reading


   DAS.REQ
   DSK.REQ
   ICY.REQ

Literature_References


   None.

Author_and_Institution


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

Version


   -Icy Version 1.0.1, 31-MAY-2021 (JDR)

       Edited the header to comply with NAIF standard. Updated
       code example to prompt for the input DSK file and reduce the
       number of plates whose vertices are shown on output.

       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, 04-APR-2017 (ML) (EDW)

Index_Entries


   fetch double precision data from a type 2 DSK segment



Fri Dec 31 18:43:03 2021