Index Page
DSKBRIEF User's Guide

Table of Contents 

   DSKBRIEF User's Guide
      Abstract
      Summary
      Usage
      Data aggregation
   Running DSKBRIEF
      Ways to Provide File Names
      Default Summary
      Extended Summary
      Full Summary
      Summary of Multiple DSK Files
      Aggregated Summary of Multiple DSK Files
      Summary of Multiple DSK Files with Gap Display
      Summary with Higher Output Precision
      Segment Summary
      Summary of DSK Files Having Incompatible Attributes
   Appendix A --- Revision History
         2017 FEB 10 by N. J. Bachman.
         2010 JUN 03 by N. J. Bachman.


Top

DSKBRIEF User's Guide




Last revised on 2017 FEB 10 by N. J. Bachman.



Top

Abstract



DSKBRIEF is a command-line utility program that displays a summary of the spatial coverage and additional attributes of one or more binary Digital Shape Kernel (DSK) files.



Top

Summary



DSKBRIEF is a command-line utility program that displays summary information for a set of one or more specified DSK files. A DSK summary includes at a minimum:

    -- The names or ID codes of the body or bodies for which the DSK provides data

    -- The surface names or surface ID codes associated with the bodies (see the DSK Required Reading, dsk.req, for a discussion of surfaces.)

    -- The names or ID codes of the reference frames relative to which DSK data are expressed

    -- The coordinate systems used to describe spatial coverage

    -- The bounds of the spatial regions for which the DSK provides data

Coverage for multiple DSK segments and files can be aggregated and displayed as though the DSK data were contained in a single file.

The user can command DSKBRIEF to produce detailed summaries, including summaries of individual DSK segments. See the Usage section and the command examples below.



Top

Usage



DSKBRIEF is executed on the command line using the syntax shown below: 

 
     > dskbrief [options] file [file ...]
where [file]s are binary DSK files, and possibly meta-kernels or text kernels needed to support some of the display elements. The options are: 

   -a       Treat all DSK files as a single file.
 
   -gaps    Display coverage gaps.
 
   -ext     Display extended summaries: in addition to the default
            set of attributes, these include data type, data
            class, and time bounds. This option applies to summaries
            of groups of DSK segments.
 
   -seg     Display a segment-by-segment summary.
 
   -full    Display a detailed summary for each segment, including
            data-type-specific parameters. This option implies a
            segment-by-segment summary.
 
   -d <n>   Display n significant digits of floating point values.
            The range of n is 3:17.
 
   -v       Display the version of this program.
 
   -h       Display help text.
 
   -u       Display usage text.
The options can be provided in any order and can appear before, after, or intermixed with file names. The case of option keys is significant: they must be lowercase as shown above.

All option combinations are valid; however, some options override others:

    -- The options -full and -seg both override -a.

    -- The option -ext has no effect when -full or -seg are present.

    -- The option -gaps applies to sets of DSK files only when -a is used. It applies to sets of matching segments within a given DSK file unless -full or -seg are used.

    -- The program terminates after displaying the requested information when any of -h, -v, or -u are present. In this case no DSK summary is displayed.



Top

Data aggregation



By default, for an individual DSK file, DSKBRIEF summarizes the aggregated coverage of the file's segments. The coverage bounds that are displayed are those of the union of the coverage regions of the individual segments.

In order for coverage of multiple DSK segments to be aggregated, each segment must have compatible attributes, so that combining the coverage makes sense. The following attributes must match across the segments: 

   Body
   Surface
   Reference Frame
   Data Type
   Data Class
   Coordinate System
In addition, if the coordinate system is planetodetic, the reference ellipsoid shape parameters (equatorial radius and flattening coefficient) must match exactly.

When some of the segments of a DSK file don't have compatible attributes, the ones that are compatible are grouped together, and summaries for each group are displayed.

Aggregation of data across multiple DSKs can be commanded as well. Groups of DSKs in which all segments have compatible attributes can be summarized as though the coverage were provided by a single DSK file containing one segment. See the section ``Aggregated Summary of Multiple DSK Files'' below.



Top

Running DSKBRIEF




When DSKBRIEF is executed, it displays summary information for the DSK files specified on the command line.



Top

Ways to Provide File Names



DSKBRIEF supports two ways of providing names of files to be summarized:

    -- by listing them on the command line

    -- by getting them from a meta-kernel(s) provided on the command line

In some cases DSKBRIEF requires text kernels to be provided in order to produce complete summary output. Names of

    -- Bodies

    -- Surfaces

    -- Reference Frames

that are not built into SPICE can appear in DSKBRIEF's output only if one or more text kernels containing name-ID associations for these items are specified on the command line.

When names of these attributes are not available, DSKBRIEF will display the corresponding ID codes.



Top

Default Summary



The simplest DSKBRIEF run command is of the form: 

   dskbrief <DSK name>
For example, to summarize the DSK file 

   phobos512.bds
the run command is: 

   dskbrief phobos512.bds
The resulting summary is: 

 
   DSKBRIEF Program; Ver. 2.0.0, 30-JAN-2017; Toolkit Ver. N0065
 
   Summary for: phobos512.bds
 
   Body:                               401 (PHOBOS)
     Surface:                          401 (Name not available)
     Reference frame:                  IAU_PHOBOS
     Coordinate system:                Planetocentric Latitudinal
       Min, max longitude  (deg):       -180.000     180.000
       Min, max latitude   (deg):        -90.0000     90.0000
       Min, max radius      (km):          8.04963    13.9409
The top portion of the summary shows the basic attributes and the spatial coverage of the DSK file:

    -- Central body ID code and if available, center name.

    -- Surface ID code and if available, surface name

    -- Name of coordinate system associated with the segment or segments.

    -- Spatial region covered. This region is defined by the coordinate bounds and reference frame.

    When the spatial coverage of multiple segments is aggregated, the bounds shown are the minimum and maximum coordinates of the group of segments. If the region described by these extrema has coverage gaps, a message to that effect will be displayed.

The names of the central body, the surface, and the reference frame will be displayed if they are built into SPICE. Otherwise, the names of one or more text kernels containing these name-ID associations may be supplied on the command line; the recognized names will then appear in the summary.



Top

Extended Summary



A more detailed view of a DSK's attributes can be displayed by supplying the 

   -ext
option on the command line, for example 

   dskbrief -ext phobos512.bds
The resulting output is 

 
   Summary for: phobos512.bds
 
   Body:                               401 (PHOBOS)
     Surface:                          401 (Name not available)
     Reference frame:                  IAU_PHOBOS
     Data type:                        2 (Shape model using triangular
                                          plates)
     Data class:                       1 (Single-valued surface)
     Coordinate system:                Planetocentric Latitudinal
       Min, max longitude  (deg):       -180.000     180.000
       Min, max latitude   (deg):        -90.0000     90.0000
       Min, max radius      (km):          8.04963    13.9409
     Start time:                       1950 JAN 01 00:00:41.183 TDB
     Stop time:                        2050 JAN 01 00:01:06.183 TDB
In addition to the items shown in the default summary, the output includes:

    -- The segment's data type.

    -- The segment's data class.

    -- The time bounds that apply to the segment's data.

See the DSK Required Reading dsk.req for further information on the concepts of DSK data type and data class.



Top

Full Summary



Details of the segment's data type-independent attributes and data type-specific parameters can be displayed by supplying the 

   -full
option on the command line, for example 

   dskbrief -full phobos512.bds
The resulting output is 

 
   DSKBRIEF Program; Ver. 2.0.0, 30-JAN-2017; Toolkit Ver. N0065
 
 
   Summary for: phobos512.bds
 
   =====================================================================
   Segment number 1 of file phobos512.bds
 
   Body:                               401 (PHOBOS)
     Surface:                          401 (Name not available)
     Reference frame:                  IAU_PHOBOS
     Data type:                        2 (Shape model using triangular
                                          plates)
     Data class:                       1 (Single-valued surface)
     Coordinate system:                Planetocentric Latitudinal
       Min, max longitude  (deg):       -180.000     180.000
       Min, max latitude   (deg):        -90.0000     90.0000
       Min, max radius      (km):          8.04963    13.9409
     Start time:                       1950 JAN 01 00:00:41.183 TDB
     Stop time:                        2050 JAN 01 00:01:06.183 TDB
 
       Type 2 parameters
       -----------------
         Number of vertices:                 1579014
         Number of plates:                   3145728
         Voxel edge length (km):             1.04248E-01
         Number of voxels:                   11914500
         Number of coarse voxels:            95316
         Voxel grid X, Y, Z extents:         260 235 195
         Coarse voxel grid X, Y, Z extents:  52 47 39
         Min, max vertex X value (km):       -13.4400    12.7628
         Min, max vertex Y value (km):       -11.5206    12.0611
         Min, max vertex Z value (km):        -9.57078   10.0550
   =====================================================================
In addition to the items shown in the extended summary, the output includes parameters specific to the segment's data type (2).

See the DSK Required Reading dsk.req for a detailed description of DSK data type 2.



Top

Summary of Multiple DSK Files



Multiple DSKs can be specified individually on the command line, or in one or more meta-kernels.

When multiple DSKs are summarized together, the default output is a concatenation of the default summaries of each individual DSK file, displayed in the order the files are processed.

A more manageable summary for multiple DSKs is obtained by displaying aggregate coverage. The following section discusses this option.



Top

Aggregated Summary of Multiple DSK Files 



   Note: due to document formatting constraints, the
   output shown below has in some cases been truncated
   or wrapped across multiple lines. The actual program
   output is not wrapped; in these examples, the maximum
   actual output line length is 99 characters.
In the following example, the meta-kernel 

   mola_gap.tm
lists 288 DSK files. Each listed DSK has coverage of 15 degrees in longitude and 10 to 11 degrees of latitude.

We can see the aggregate coverage of the DSKs using the command 

   dskbrief -a mola128.tm
The resulting output is 

 
   DSKBRIEF Program; Ver. 2.0.0, 30-JAN-2017; Toolkit Ver. N0065
 
   Summary for: all DSK files
 
   Body:                               499 (MARS)
     Surface:                          499000 (MGS MOLA MEGDR 128
                                               PIXEL/DEG)
     Reference frame:                  IAU_MARS
     Coordinate system:                Planetocentric Latitudinal
       Min, max longitude  (deg):           0.00000     360.000
       Min, max latitude   (deg):         -87.0000       87.0000
       Min, max radius      (km):        3371.72       3414.72
       ***Coverage has gaps. Use the -gaps option to display them.***
We see that the aggregate coverage is 360 degrees in longitude and ranges from -87 to 87 degrees in latitude, and that there are gaps in the coverage.

The time coverage of the DSKs is aggregated as well, so if the 

   -ext
option is used, the displayed time bounds are the minimum and maximum time bounds of any segments in the aggregated files.



Top

Summary of Multiple DSK Files with Gap Display



We can repeat the previous command using the 

   -gaps
option: 

   dskbrief -a -gaps mola128.tm
The resulting output is 

 
   DSKBRIEF Program; Ver. 2.0.0, 30-JAN-2017; Toolkit Ver. N0065
 
   Summary for: all DSK files
 
   Body:                               499 (MARS)
     Surface:                          499000 (MGS MOLA MEGDR 128
                                               PIXEL/DEG)
     Reference frame:                  IAU_MARS
     Coordinate system:                Planetocentric Latitudinal
       Min, max longitude  (deg):           0.00000     360.000
       Min, max latitude   (deg):         -87.0000       87.0000
       Min, max radius      (km):        3371.72       3414.72
       Coverage gaps:
         Longitude range (deg)       Latitude range (deg)
            0.00000    360.000         0.00000    44.0000
           90.0000      90.0000      -87.0000      0.00000
           90.0000      90.0000       44.0000     87.0000
          255.000      255.000       -87.0000      0.00000
          255.000      255.000        44.0000     87.0000
          300.000      300.000       -87.0000      0.00000
          300.000      300.000        44.0000     87.0000
          345.000      345.000       -87.0000      0.00000
          345.000      345.000        44.0000     87.0000
The gap summary shows that aggregate latitude bounds were misleading: there's a missing latitude band ranging from 0 to 360 degrees in longitude and 0 to 44 degrees in latitude, plus eight small gaps.



Top

Summary with Higher Output Precision



In the gap summary above, there are small gaps that appear to have zero extent in longitude. We can see the dimensions of these gaps by specifying that the output values have 17 significant digits: 

   dskbrief -a -gaps -d 17 mola128.tm
The resulting output (truncated in this document) is: 

 
   Body:                               499 (MARS)
     Surface:                          499000 (MGS MOLA MEGDR 128 PIXEL/
                                               DEG
     Reference frame:                  IAU_MARS
     Coordinate system:                Planetocentric Latitudinal
       Min, max longitude  (deg):           0.0000000000000000     360.0
       Min, max latitude   (deg):         -87.000000000000000       87.0
       Min, max radius      (km):        3371.7199999966310       3414.7
       Coverage gaps:
         Longitude range (deg)                             Latitude rang
            0.0000000000000000    360.00000000000000         0.000000000
           89.999999999999986      90.000000000000000      -87.000000000
           89.999999999999986      90.000000000000000       44.000000000
          254.99999999999997      255.00000000000003       -87.000000000
          254.99999999999997      255.00000000000003        44.000000000
          299.99999999999994      300.00000000000000       -87.000000000
          299.99999999999994      300.00000000000000        44.000000000
          344.99999999999994      345.00000000000000       -87.000000000
          344.99999999999994      345.00000000000000        44.000000000
All floating point outputs now have at least 17 digits.

It's now evident that all but one of the gaps have round-off-level longitude extents. (This sort of gap is typically an artifact of the DSK production process).



Top

Segment Summary



By default, DSKBRIEF aggregates the coverage of individual segments in multi-segment DSK files. Segment-by-segment summaries of such DSK files can be commanded using the 

   -seg
option. In this example, DSKBRIEF is used to summarize a DSK containing 36 segments: 

   dskbrief -seg /usr1/N0066/dsk/precursors/dsk_math_utils/multi_global
                 _370k_36seg_row4_col8.bds
The first two segment summaries are shown below (the output has been wrapped): 

 
   DSKBRIEF Program; Ver. 2.0.0, 30-JAN-2017; Toolkit Ver. N0065
 
 
   Summary for: /usr1/N0066/dsk/precursors/dsk_math_utils/multi_global_
                370k_36seg_row4_col8.bds
 
   =====================================================================
   =========
   Segment number 1 of file /usr1/N0066/dsk/precursors/dsk_math_utils/m
                            ulti_global_370k_36seg_row4_col8.bds
 
   Body:                               499 (MARS)
     Surface:                          1 (Name not available)
     Reference frame:                  IAU_MARS
     Data type:                        2 (Shape model using triangular
                                          plates)
     Data class:                       1 (Single-valued surface)
     Coordinate system:                Planetocentric Latitudinal
       Min, max longitude  (deg):         135.000     142.500
       Min, max latitude   (deg):         -52.5000    -45.0000
       Min, max radius      (km):        2353.66     2531.45
     Start time:                       1899 DEC 31 12:00:00.000 TDB
     Stop time:                        2100 JAN 01 12:00:00.000 TDB
   =====================================================================
   =========
   Segment number 2 of file /usr1/N0066/dsk/precursors/dsk_math_utils/m
                            ulti_global_370k_36seg_row4_col8.bds
 
   Body:                               499 (MARS)
     Surface:                          1 (Name not available)
     Reference frame:                  IAU_MARS
     Data type:                        2 (Shape model using triangular
                                          plates)
     Data class:                       1 (Single-valued surface)
     Coordinate system:                Planetocentric Latitudinal
       Min, max longitude  (deg):         142.500     150.000
       Min, max latitude   (deg):         -52.5000    -45.0000
       Min, max radius      (km):        2353.66     2531.45
     Start time:                       1899 DEC 31 12:00:00.000 TDB
     Stop time:                        2100 JAN 01 12:00:00.000 TDB
   =====================================================================
   =========


Top

Summary of DSK Files Having Incompatible Attributes



Below is an example of an attempt to produce an aggregated summary for a set of files having incompatible attributes. The file set contains 288 DSKs having compatible attributes and a second DSK containing three segments that use different coordinate systems.

The command is 

   dskbrief -a mola_gap.tm phobos_3_3_3seg.bds
The output is (the output has been wrapped): 

 
   DSKBRIEF Program; Ver. 2.0.0, 30-JAN-2017; Toolkit Ver. N0065
 
   Summary for: all DSK files
 
   Body:                               499 (MARS)
     Surface:                          499000 (MGS MOLA MEGDR 128 PIXEL/
                                               DEG)
     Reference frame:                  IAU_MARS
     Coordinate system:                Planetocentric Latitudinal
       Min, max longitude  (deg):           0.00000     360.000
       Min, max latitude   (deg):         -87.0000       87.0000
       Min, max radius      (km):        3371.72       3414.72
       ***Coverage has gaps. Use the -gaps option to display them.***
 
   Body:                               401 (PHOBOS)
     Surface:                          1 (Name not available)
     Reference frame:                  IAU_PHOBOS
     Coordinate system:                Planetocentric Latitudinal
       Min, max longitude  (deg):       -180.000     180.000
       Min, max latitude   (deg):        -90.0000     90.0000
       Min, max radius      (km):          8.22530    14.0118
 
   Body:                               401 (PHOBOS)
     Surface:                          2 (Name not available)
     Reference frame:                  IAU_PHOBOS
     Coordinate system:                Rectangular
      Min, max X coordinate (km):       -1.30000   1.31000
      Min, max Y coordinate (km):       -1.21000   1.20000
      Min, max Z coordinate (km):       -9.45293   9.63818
 
   Body:                               401 (PHOBOS)
     Surface:                          3 (Name not available)
     Reference frame:                  IAU_PHOBOS
     Coordinate system:                Planetodetic
      Equatorial radius (km):           13.0000
      Polar radius      (km):            7.00000E-01
      Flattening coefficient:            3.00000E-01
       Min, max longitude  (deg):       -180.000     180.000
       Min, max latitude   (deg):        -90.0000     90.0000
       Min, max altitude    (km):         -3.72867     1.37202
In the above output, the segments that are compatible are summarized together; the others are summarized individually.



Top

Appendix A --- Revision History






Top

2017 FEB 10 by N. J. Bachman.



Updated to document the first SPICE Toolkit version of the program.



Top

2010 JUN 03 by N. J. Bachman.



Initial release.