| DSKBRIEF User's Guide |
Table of ContentsDSKBRIEF 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. DSKBRIEF User's Guide
Abstract
Summary
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 [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:
Data aggregation
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 SystemIn 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
Ways to Provide File Names
When names of these attributes are not available, DSKBRIEF will display the corresponding ID codes. Default Summary
dskbrief <DSK name>For example, to summarize the DSK file
phobos512.bdsthe run command is:
dskbrief phobos512.bdsThe 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:
Extended Summary
-extoption on the command line, for example
dskbrief -ext phobos512.bdsThe 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:
Full Summary
-fulloption on the command line, for example
dskbrief -full phobos512.bdsThe 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
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.tmlists 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.tmThe 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
-extoption 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
-gapsoption:
dskbrief -a -gaps mola128.tmThe 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
dskbrief -a -gaps -d 17 mola128.tmThe 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
-segoption. 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
The command is
dskbrief -a mola_gap.tm phobos_3_3_3seg.bdsThe 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 History2017 FEB 10 by N. J. Bachman.
2010 JUN 03 by N. J. Bachman.
|