Index Page dskgd_c

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

Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries

#### Procedure

       void dskgd_c ( SpiceInt               handle,
                      ConstSpiceDLADescr   * dladsc,
                      SpiceDSKDescr        * dskdsc )

#### Abstract

       Return the DSK descriptor from a DSK segment identified
       by a DAS handle and DLA descriptor.

#### Required_Reading

       DAS
       DSK
       NAIF_IDS

#### Keywords

       DAS
       DSK
       FILES
       TOPOGRAPHY

#### Brief_I/O

       Variable  I/O  Description
       --------  ---  --------------------------------------------------
       handle     I   Handle of a DSK file.
       dladsc     I   DLA segment descriptor.
       dskdsc     O   DSK segment descriptor.

#### Detailed_Input

       handle         is the handle of a DSK file that is open for
                      read access.

       dladsc         is the DLA segment descriptor corresponding to
                      a DSK segment.

#### Detailed_Output

       dskdsc         is the DSK segment descriptor of the segment
                      designated by the input handle and DLA descriptor.

#### Parameters

       See the header files

          SpiceDLA.h
          SpiceDSK.h

#### Exceptions

       1) If the input handle is invalid, the error will be
          diagnosed by routines in the call tree of this
          routine.

       2) If the input DLA descriptor is invalid, the behavior
          of this routine is undefined.

       3) DAS read errors will be diagnosed by routines in the
          call tree of this routine.

#### Files

       See input argument `handle'.

#### Particulars

       This is a convenience routine intended for use by low-level routines
       that read DSK segments. This routine may also be called by user
       applications that must access DSK files at the segment level.

#### Examples

       The numerical results shown for this example may differ across
       platforms. The results depend on the SPICE kernels used as
       input, the compiler and supporting libraries, and the machine
       specific arithmetic implementation.

       1) Dump the DSK descriptors of a DSK file.

       Example code begins here.

          #include <stdio.h>
          #include "SpiceUsr.h"

          int main()
          {
             /.
             Local constants
             ./
             #define FILSIZ              256

             /.
             Local variables
             ./
             SpiceChar               dsk    [FILSIZ];
             SpiceBoolean            found;
             SpiceDLADescr           dladsc;
             SpiceDLADescr           nxtdsc;
             SpiceDSKDescr           dskdsc;
             SpiceInt                handle;
             SpiceInt                i;

             /.
             Prompt for the name of a DSK file; open the file.
             ./
             prompt_c ( "Enter DSK name > ", FILSIZ, dsk );
             dasopr_c ( dsk, &handle );

             /.
             Search for the first segment in the file; obtain
             the segment's DLA descriptor.
             ./
             dlabfs_c ( handle, &nxtdsc, &found );

             while ( found )
             {
                dladsc = nxtdsc;

                dskgd_c ( handle, &dladsc, &dskdsc );

                printf ( "\nDSK descriptor contents:\n" );

                printf ( "   %15d\n",  (int) dskdsc.surfce );
                printf ( "   %15d\n",  (int) dskdsc.center );
                printf ( "   %15d\n",  (int) dskdsc.dclass );
                printf ( "   %15d\n",  (int) dskdsc.dtype  );
                printf ( "   %15d\n",  (int) dskdsc.frmcde );
                printf ( "   %15d\n",  (int) dskdsc.corsys );

                for ( i = 0; i < SPICE_DSK_NSYPAR;  i++ )
                {
                   printf ( "   %15.6f\n",        dskdsc.corpar[i] );
                }

                printf ( "   %15.6f\n",    dskdsc.co1min );
                printf ( "   %15.6f\n",    dskdsc.co1max );
                printf ( "   %15.6f\n",    dskdsc.co2min );
                printf ( "   %15.6f\n",    dskdsc.co2max );
                printf ( "   %15.6f\n",    dskdsc.co3min );
                printf ( "   %15.6f\n",    dskdsc.co3max );
                printf ( "% 15.6f\n",   dskdsc.start  );
                printf ( "% 15.6f\n",   dskdsc.stop   );

                /.
                Fetch next DLA descriptor.
                ./
                dlafns_c ( handle, &dladsc, &nxtdsc, &found );
             }
             return ( 0 );
          }

       When this program was executed on a PC/Linux/gcc platform,
       and when the input DSK name was

          phobos512.bds

       (this file is available on the NAIF server), the output was:

          Enter DSK name > phobos512.bds

          DSK descriptor contents:
                         401
                         401
                           1
                           2
                       10021
                           1
                    0.000000
                    0.000000
                    0.000000
                    0.000000
                    0.000000
                    0.000000
                    0.000000
                    0.000000
                    0.000000
                    0.000000
                   -3.141593
                    3.141593
                   -1.570796
                    1.570796
                    8.049632
                   13.940940
          -1577879958.816059
           1577880066.183913

       2) Again, dump the DSK descriptors of a DSK file, this time
          interpreting the descriptor information and displaying
          it in a user-friendly form. This display is a simplified
          version of that created by the utility DSKBRIEF.

          This program requests the name of an optional meta-kernel.
          The meta-kernel can be used to define surface name-ID
          associations. If no meta-kernel is needed, the user can
          enter a carriage return at the prompt for this file.

       Example code begins here.

          /.
          Program EX2
          ./
          #include <stdio.h>
          #include "SpiceUsr.h"

          int main()
          {
             /.
             Local constants
             ./
             #define BDNMLN          37
             #define FILSIZ          256
             #define FRNMLN          33
             #define TIMLEN          41
             #define NSYS             4
             #define NAMLEN          21
             #define NCLASS           2
             #define SFNMLN          CSPICE_SRF_SFNMLN

             /.
             Local variables
             ./
             SpiceBoolean            found;
             SpiceBoolean            isname;

             SpiceChar               bodnam [ SFNMLN ];
             SpiceChar               btime  [ TIMLEN ];

             SpiceChar             * clsnms [2] =
                                    { "Single-valued surface",
                                      "General surface"       };

             SpiceChar               dsk    [ FILSIZ ];
             SpiceChar               etime  [ TIMLEN ];
             SpiceChar               frame  [ FRNMLN ];
             SpiceChar               meta   [ FILSIZ ];
             SpiceChar               srfnam [ SFNMLN ];
             SpiceChar             * sysnam;

             SpiceChar             * sysnms [ NSYS ] =
                                      { "Latitudinal", "Cylindrical",
                                        "Rectangular", "Planetodetic" };

             SpiceDLADescr           dladsc;
             SpiceDLADescr           nxtdsc;

             SpiceDouble             f;
             SpiceDouble             re;
             SpiceDouble             rp;

             SpiceDSKDescr           dskdsc;

             SpiceInt                bodyid;
             SpiceInt                corsys;
             SpiceInt                dclass;
             SpiceInt                dtype;
             SpiceInt                framid;
             SpiceInt                handle;
             SpiceInt                segno;
             SpiceInt                surfid;

             prompt_c ( "Enter DSK name         > ", FILSIZ, dsk  );
             prompt_c ( "Enter meta-kernel name > ", FILSIZ, meta );

             if (    ( !eqstr_c( meta, " ") )
                  && ( !eqstr_c( meta, "" ) )  )
             {
                furnsh_c ( meta );
             }

             /.
             Open the DLA file and begin a forward search
             for segments.
             ./
             dasopr_c ( dsk, &handle );

             segno = 0;

             dlabfs_c ( handle, &nxtdsc, &found );

             while ( found )
             {
                ++segno;

                /.
                Make the DLA descriptor we just fetched
                the current one.
                ./
                dladsc = nxtdsc;

                dskgd_c ( handle, &dladsc, &dskdsc );

                bodyid = dskdsc.center;
                surfid = dskdsc.surfce;
                framid = dskdsc.frmcde;
                dtype  = dskdsc.dtype;
                dclass = dskdsc.dclass;

                bodc2s_c ( bodyid, BDNMLN, bodnam );
                srfc2s_c ( surfid, bodyid, SFNMLN, srfnam, &isname );
                frmnam_c ( framid, FRNMLN, frame  );

                if ( eqstr_c( frame, " " ) )
                {
                   sprintf ( frame, "%d", (int)framid );
                }

                etcal_c ( dskdsc.start, TIMLEN, btime );
                etcal_c ( dskdsc.stop,  TIMLEN, etime );

                corsys = dskdsc.corsys;
                sysnam = sysnms[corsys-1];

                printf ( "%s\n"
                         " DSK descriptor for segment %d\n"
                         "  Body:              %s\n"
                         "  Surface:           %s\n"
                         "  Frame:             %s\n"
                         "  Start time (TDB):  %s\n"
                         "  Stop time  (TDB):  %s\n"
                         "  Data type:         %d\n"
                         "  Data class:        %s\n"
                         "  Coordinate System: %s\n",
                         "====================================",
                         (int) segno,
                         bodnam,
                         srfnam,
                         frame,
                         btime,
                         etime,
                         (int) dtype,
                         clsnms[ dclass-1 ],
                         sysnam                                );

                if ( corsys == SPICE_DSK_PDTSYS )
                {
                   re = dskdsc.corpar[0];
                   f  = dskdsc.corpar[1];
                   rp = re * (1.0 - f);

                   printf ( "    Equatorial radius (km): %21.14f\n"
                            "    Polar radius      (km): %21.14f\n",
                            re, rp                                  );
                }

                printf ( "  Segment boundaries:\n" );

                if ( corsys == SPICE_DSK_LATSYS )
                {
                   printf ( "    Longitude (deg):   %21.14f  %21.14f\n"
                            "    Latitude  (deg):   %21.14f  %21.14f\n"
                            "    Radius     (km):   %21.14f  %21.14f\n",
                            dskdsc.co1min * dpr_c(),
                            dskdsc.co1max * dpr_c(),
                            dskdsc.co2min * dpr_c(),
                            dskdsc.co2max * dpr_c(),
                            dskdsc.co3min,
                            dskdsc.co3max                      );
                }
                else if ( corsys == SPICE_DSK_CYLSYS )
                {
                   setmsg_c ( "Coordinate system was Cylindrical." );
                   sigerr_c ( "SPICE(NOTSUPPORTED)" );
                }
                else if ( corsys == SPICE_DSK_RECSYS )
                {
                   printf ( "    X-coordinate (km): %21.14f  %21.14f\n"
                            "    Y-coordinate (km): %21.14f  %21.14f\n"
                            "    Z-coordinate (km): %21.14f  %21.14f\n",
                            dskdsc.co1min,
                            dskdsc.co1max,
                            dskdsc.co2min,
                            dskdsc.co2max,
                            dskdsc.co3min,
                            dskdsc.co3max                      );
                }
                else if ( corsys == SPICE_DSK_PDTSYS )
                {
                   printf ( "    Longitude (deg):   %21.14f  %21.14f\n"
                            "    Latitude  (deg):   %21.14f  %21.14f\n"
                            "    Altitude   (km):   %21.14f  %21.14f\n",
                            dskdsc.co1min * dpr_c(),
                            dskdsc.co1max * dpr_c(),
                            dskdsc.co2min * dpr_c(),
                            dskdsc.co2max * dpr_c(),
                            dskdsc.co3min,
                            dskdsc.co3max                      );
                }
                /.
                Find the next segment, if it exists.
                ./
                dlafns_c ( handle, &dladsc, &nxtdsc, &found );
             }
             return ( 0 );
          }

       When this program was executed on a PC/Linux/gcc/64-bit platform,
       and when the input DSK name was

          phobos512.bds

       (this file is available on the NAIF server), the output was:

          Enter DSK name         > phobos512.bds
          Enter meta-kernel name >
          ====================================
           DSK descriptor for segment 1
            Body:              PHOBOS
            Surface:           401
            Frame:             IAU_PHOBOS
            Start time (TDB):  1950 JAN 01 00:00:41.183
            Stop time  (TDB):  2050 JAN 01 00:01:06.183
            Data type:         2
            Data class:        Single-valued surface
            Coordinate System: Latitudinal
            Segment boundaries:
              Longitude (deg):     -180.00000000000000     180.00000000000000
              Latitude  (deg):      -90.00000000000000      90.00000000000000
              Radius     (km):        8.04963224872155      13.94093983212395

       3) Again, dump the DSK descriptors of a DSK file, using the
          program from example 2, but this time reading the DSK file

             phobos_3_3_3seg.bds

          which can be created by running an example program from
          DSKW02. Use the meta-kernel below to demonstrate surface
          name-ID mapping:

             KPL/MK

             File: dskgd_ex3.tm

             This meta-kernel is intended to support operation of SPICE
             example programs. The file contents shown here should not be
             assumed to contain adequate or correct versions of data
             required by SPICE-based user applications.

             \begindata

             NAIF_SURFACE_NAME += ( 'Phobos example surface 1',
                                    'Phobos example surface 2',
                                    'Phobos example surface 3' )
             NAIF_SURFACE_CODE += (   1,   2,   3 )
             NAIF_SURFACE_BODY += ( 401, 401, 401 )

             \begintext

       When this program was executed on a PC/Linux/gcc/64-bit
       platform, using the example DSK named above, the output was:

          Enter DSK name         > phobos_3_3_3seg.bds
          Enter meta-kernel name > dskgd_ex3.tm
          ====================================
           DSK descriptor for segment 1
            Body:              PHOBOS
            Surface:           Phobos example surface 1
            Frame:             IAU_PHOBOS
            Start time (TDB):  1950 JAN 01 00:00:00.000
            Stop time  (TDB):  2050 JAN 01 00:00:00.000
            Data type:         2
            Data class:        General surface
            Coordinate System: Latitudinal
            Segment boundaries:
              Longitude (deg):     -180.00000000000000     180.00000000000000
              Latitude  (deg):      -90.00000000000000      90.00000000000000
              Radius     (km):        8.22529807597397      14.01176814562576
          ====================================
           DSK descriptor for segment 2
            Body:              PHOBOS
            Surface:           Phobos example surface 2
            Frame:             IAU_PHOBOS
            Start time (TDB):  1950 JAN 01 00:00:00.000
            Stop time  (TDB):  2050 JAN 01 00:00:00.000
            Data type:         2
            Data class:        General surface
            Coordinate System: Rectangular
            Segment boundaries:
              X-coordinate (km):     -1.30000000000000       1.31000000000000
              Y-coordinate (km):     -1.21000000000000       1.20000000000000
              Z-coordinate (km):     -9.45293235778800       9.63817977905300
          ====================================
           DSK descriptor for segment 3
            Body:              PHOBOS
            Surface:           Phobos example surface 3
            Frame:             IAU_PHOBOS
            Start time (TDB):  1950 JAN 01 00:00:00.000
            Stop time  (TDB):  2050 JAN 01 00:00:00.000
            Data type:         2
            Data class:        General surface
            Coordinate System: Planetodetic
              Equatorial radius (km):     13.00000000000000
              Polar radius      (km):      9.10000000000000
            Segment boundaries:
              Longitude (deg):     -180.00000000000000     180.00000000000000
              Latitude  (deg):      -90.00000000000000      90.00000000000000
              Altitude   (km):       -3.72866868360370       1.37201579108146

#### Restrictions

       1) See Exception #2.

#### Literature_References

       None.

#### Author_and_Institution

       N.J. Bachman    (JPL)

#### Version

       -CSPICE Version 1.1.0, 05-APR-2017 (NJB)

          Corrected a header comment typo.

        22-JAN-2016 (NJB)

          CSPICE header file references were updated.
          Example program 1 was re-written;
          example program 2 was added.

       -CSPICE Version 1.0.0, 13-NOV-2012 (NJB)

#### Index_Entries

       return dsk segment_descriptor

#### Link to routine dskgd_c source file dskgd_c.c

    Wed Apr  5 17:54:32 2017