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.