DSKBRIEF User's Guide =========================================================================== Last revised on 2017 FEB 10 by N. J. Bachman. 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. 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. 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 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. 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. Running DSKBRIEF =========================================================================== When DSKBRIEF is executed, it displays summary information for the DSK files specified on the command line. 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. Default Summary -------------------------------------------------------- The simplest DSKBRIEF run command is of the form: dskbrief 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. 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. 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. 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. 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. 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. 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). 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 ===================================================================== ========= 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. Appendix A --- Revision History =========================================================================== 2017 FEB 10 by N. J. Bachman. Updated to document the first SPICE Toolkit version of the program. 2010 JUN 03 by N. J. Bachman. Initial release.