Index Page MKDSK User's Guide

## Table of Contents

       MKDSK User's Guide
          Abstract
          Summary
          References
          Usage
          Running MKDSK
       MKDSK Setup File
          Setup File Format
          Setup File Assignments
             Required Assignments
             Conditional Assignments
             Optional Assignments
          Detailed Description of Setup File Keywords
       Setup File Examples
             Input Using Latitudinal Coordinates and Plate Type 2
             Input Using Planetodetic Coordinates and Plate Type 1
             Input Using Planetocentric Coordinates and Plate Type 5
       Input Data File
          Units
          Reference Frame
          Vertex order
             Vertex IDs
          Plate Data File Type 1 (Plate-Vertex Table)
             Sample Plate-Vertex Table Input File
          Plate Data File Type 2 (Gaskell Shape Model)
             Sample Gaskell Shape Model Input File
          Plate Data File Type 3 (Vertex-Facet Table)
             Sample Vertex-Facet Input File
          Rosetta/OSIRIS ``ver'' File
             Sample Rosetta/OSIRIS ``ver'' File
          ASCII Height Grid File
             Domain Coordinates
             Heights
             Height Grid File Format
             Height Grid Data Order
             Polar Caps
             Longitude Wrapping
       Output DSK File
       Appendix A: Spatial Index and Voxels

Top

# MKDSK User's Guide

Last revised on 2017 APR 05 by N. J. Bachman.

Top

## Abstract

MKDSK is a utility program that creates a SPICE Digital Shape Kernel (DSK) file from a text file containing shape data for an extended object.

Top

## Summary

MKDSK converts a text file containing surface shape and size data to a binary Digital Shape Kernel (DSK).

The MKDSK program requires as input a setup file containing input parameters and a second file containing the shape data to be processed.

Data files provided to this program either represent an object's surface as a collection of triangular plates, or as a height grid.

Currently the only supported output DSK data type is type 2: this type represents the surface of a specified body as a collection of triangular plates.

The program allows the user to optionally specify some descriptive text in a separate file, called the ``comment file,'' to be placed into the ``comment area'' of the DSK file. (Doing this is highly recommended.)

For archival documentation purposes the content of the MKDSK setup file is automatically placed at the end of the ``comment area'' of the DSK file.

Top

## References

`1.` DSK Required Reading (dsk.req)

`2.` NAIF Integer ID Codes (naif_ids.req)

`3.` Frames Required Reading (frames.req)

`4.` Kernel Required Reading (kernel.req)

`5.` DSKBRIEF User's Guide (dskbrief.ug)

`6.` DSKEXP User's Guide (dskexp.ug)

`7.` COMMNT User's Guide (commnt.ug)

`8.` Convert User's Guide (convert.ug)

`9.` SPICE Tutorials. Thes are available on the NAIF web site at

                https://naif.jpl.nasa.gov/naif/tutorials.html

Top

## Usage

The diagram below shows MKDSK's command options. This diagram can be displayed by executing the command

       mkdsk -u

       Program usage:

                > mkdsk   [-setup <setup file name>]
                          [-input <input shape data file name>]
                          [-output <output DSK file name>]
                          [-h|-help]
                          [-t|-template]
                          [-u|-usage]
                          [-v|-version]

If a setup file name isn't provided on the command line, MKDSK will prompt for it. It will not prompt for the input or output file names; these file names must be provided on the command line or in the setup file. If the input or output file names are provided on the command line, any corresponding file names assigned using setup keywords are ignored. The input file must already exist and the output file must be a new file.

Top

## Running MKDSK

You will need a setup file to run MKDSK. The format for the setup file is described below.

As the program runs, it will print out messages describing its progress. If an error is encountered, the program normally will display a diagnostic message. The program attempts to delete the output file if it encounters an error while creating it.

Only one DSK file containing one segment may be generated during a single MKDSK run.

Top

# MKDSK Setup File

Top

## Setup File Format

Other than the input and output file names, which may be provided on the command line, the program requires all inputs such as surface and central body name or ID, frame name or ID, types of input and output data, spatial coverage bounds, etc. to be provided in a setup file.

The format of this file must conform to the SPICE text kernel specification. This format uses a ``keyword = value'' syntax for assignment of parameter values.

The Kernel Required Reading document, which is included in the SPICE Toolkit, provides details of this format specification. The ``Intro to Kernels'' tutorial, which is available on the NAIF web site

       http://naif.jpl.nasa.gov/naif/tutorials.html

may also be helpful.

Examples of setup files are included in this document. Often the easiest way to create a setup file for your own use is to modify an existing example.

For quick reference, a few details concerning the SPICE text kernel format are listed below:

The names of the setup file keywords must be strictly uppercase while parameterized keyword values (for example 'DEGREES'), reference frame names, and body names may be upper, lower or mixed case. File names should be assumed to be case sensitive to maximize portability. Any white space preceding or following keyword names, values and the equal sign is ignored.

All character string values and time strings must be enclosed in single quotes. They must be provided on a single line or continued with the '+' character as the final character of the value. The portion of the string value on a single line can be no longer than 80 characters. When multiple values are allowed and used, enclose the complete set in the "()" characters: KEYWORD = ( 'value1' 'value2' ... ).

Top

## Setup File Assignments

All assignments are either required, conditional or optional as described below.

A setup file may contain blank lines. Non-printing characters including TAB should not be used in setup file lines containing keyword assignments or in blank lines separating assignment lines within the data sections of a setup file. The program may not be able to parse correctly any of the setup file lines that contain non-printing characters and will signal a setup file parsing error on some computer platforms.

Top

### Required Assignments

The following assignments must be present in a setup file:

       SURFACE_NAME        = 'Surface name' (name of the specific
                             shape data set for the central body)
                             An ID code may be specified as a
                             single-quoted string.
       CENTER_NAME         = 'Central body name'. An ID code may be
                             specified as a single-quoted string.
       REF_FRAME_NAME      = 'Reference frame name'
       START_TIME          = 'Start time'
       STOP_TIME           = 'Stop time'
       DATA_CLASS          = 1 to indicate a surface that can be
                             represented as a single-valued function
                             of its domain coordinates.

                             2 indicates a general surface. Surfaces
                             that have multiple points for a given pair
                             of domain coordinates---for example,
                             multiple radii for a given latitude and
                             longitude---belong to class 2.

       INPUT_DATA_UNITS    = ( 'ANGLES    = angular unit'
                               'DISTANCES = distance unit' )

       COORDINATE_SYSTEM   = 'LATITUDINAL' or
                             'RECTANGULAR' or
                             'PLANETODETIC'

       DATA_TYPE           = 2 (triangular plates)
                             This is the data type of the single
                             segment in the output file created
                             by this program. Currently only type 2
                             is supported.

       PLATE_TYPE          = an integer in the range 1:5 specifying
                             the input data file format. This assignment
                             is applicable only to output data type 2.
                             See the chapter ``Input Data File'' for
                             further information.

The following assignments are required in the setup file if their values are not provided on the command line:

       INPUT_SHAPE_FILE    = 'Name of input shape data file'
       OUTPUT_DSK_FILE     = 'Name of output DSK file '

Top

### Conditional Assignments

One or more of the following assignments may be needed depending on the kind of input data being used and other conditions.

          KERNELS_TO_LOAD     =  ( 'kernel_1' 'kernel_2' ... )
                                 Leapseconds kernel (if not specified
                                 by the LEAPSECONDS_KERNEL assignment)
                                 and names of additional kernels, for
                                 example frame kernels to provide
                                 body-fixed frame specifications.

          LEAPSECONDS_KERNEL  =  'file name' A leapseconds kernel
                                 must be specified using either
                                 this assignment or using a
                                 KERNELS_TO_LOAD assignment.

          NAIF_BODY_NAME      += 'body name'
          NAIF_BODY_CODE      += integer ID code
                                 These assignments are needed if
                                 the central body name is not
                                 built into SPICE and its body
                                 name-ID association is not defined
                                 in a kernel listed in a
                                 KERNELS_TO_LOAD assignment.

          NAIF_SURFACE_NAME   += 'surface name'
          NAIF_SURFACE_CODE   += integer surface ID code
          NAIF_SURFACE_BODY   += integer body ID code
                                 These assignments are needed if
                                 the surface name-ID association
                                 is not defined in a kernel listed
                                 in a KERNELS_TO_LOAD assignment.

       For latitudinal coordinates:

          MINIMUM_LATITUDE    = lower latitude bound in selected
                                angular units
          MAXIMUM_LATITUDE    = upper latitude bound in selected
                                angular units
          MINIMUM_LONGITUDE   = lower longitude bound in selected
                                angular units
          MAXIMUM_LONGITUDE   = upper longitude bound in selected
                                angular units

       For rectangular coordinates:

          MINIMUM_X           = lower X coordinate bound in selected units
          MAXIMUM_X           = upper X coordinate bound in selected units
          MINIMUM_Y           = lower Y coordinate bound in selected units
          MAXIMUM_Y           = upper Y coordinate bound in selected units

       For planetodetic coordinates:

          MINIMUM_LATITUDE    = lower latitude bound in selected units
          MAXIMUM_LATITUDE    = upper latitude bound in selected units
          MINIMUM_LONGITUDE   = lower longitude bound in selected units
          MAXIMUM_LONGITUDE   = upper longitude bound in selected units

          EQUATORIAL_RADIUS   = equatorial spheroid radius in selected units
          POLAR_RADIUS        = polar spheroid radius in selected units

       For data type 2, plate type 5, the following additional assignments
       are required:

          WRAP_LONGITUDE              = connect leftmost column to
                                        rightmost column: 'YES' or 'NO'
          MAKE_NORTH_POLAR_CAP        = extend plate set to north pole:
                                        'YES' or 'NO'
          MAKE_SOUTH_POLAR_CAP        = extend plate set to south pole:
                                        'YES' or 'NO'
          INPUT_GRID_ORDER_ROW_MAJOR  = input data set is row-major:
                                        'YES' or 'NO'
          COLUMN_VALUE_ORDER_TOP_DOWN = input data set is top-down:
                                        'YES' or 'NO'
          ROW_VALUE_ORDER_LEFT_RIGHT  = input data set is left-right:
                                        'YES' or 'NO'

          NUMBER_OF_ROWS              = number of rows in grid
          NUMBER_OF_COLUMNS           = number of columns in grid
          COLUMN_STEP_SIZE            = column separation: longitude or X
                                        step
          ROW_STEP_SIZE               = row separation: latitude or Y step
          HEIGHT_SCALE                = value by which to multiply the
                                        height data to convert to km

       For data type 2, plate type 5,  latitudinal or rectangular
       coordinates, the following additional assignment
       is required:

          HEIGHT_REFERENCE            = value to add to input heights;
                                        units are always km

       For data type 2, plate type 5, rectangular coordinates, the
       following additional assignments are required:

          LEFT_COLUMN_X_COORDINATE    = X-coordinate of leftmost column of
                                        grid
          TOP_ROW_Y_COORDINATE        = Y-coordinate of top row of grid

       For data type 2, plate type 5, latitudinal or planetodetic
       coordinates, the following additional assignments
       are required:

          LEFT_COLUMN_LONGITUDE       = longitude of leftmost column of
                                        grid
          TOP_ROW_LATITUDE            = latitude of top row of grid

Top

### Optional Assignments

       COMMENT_FILE          = 'Name of optional comment file'

       FINE_VOXEL_SCALE      = Double precision value > 0.0
       COARSE_VOXEL_SCALE    = Integer >= 1

       Optional assignment:
       MAKE_VERTEX_PLATE_MAP =  'YES' or 'NO'
                                If this assignment is not provided,
                                MKDSK will not create a vertex-plate
                                mapping.

Top

## Detailed Description of Setup File Keywords

See the DSK Required Reading [1] for definitions of terms used in the discussion below.

CENTER_NAME
  Name of central body with which the surface is associated. An integer ID code enclosed in single quotes may be provided instead of a name, e.g. '499' instead of 'MARS'. This assignment is required.

COARSE_VOXEL_SCALE
  This assignment is optional and need not be used for most applications. It is applicable only to type 2 segments. See the section ``Appendix A: Spatial Index and Voxels'' below for a more detailed discussion. The coarse voxel scale is an integer representing the ratio of the edge length of coarse voxels to fine voxels. This number must be greater than or equal to 1.

COLUMN_STEP_SIZE
  Applies only to height grid inputs for data type 2 segments. This is the grid's step size for longitude or for X, depending on the specified coordinate system. Units are given by the INPUT_DATA_UNITS assignment.

COLUMN_VALUE_ORDER_TOP_DOWN
  Applies only to height grid inputs for data type 2 segments. Indicates that columns of the vertex grid are filled in in top-to-bottom order (in order of decreasing latitude or Y values) as data are read from the input file. (This does not imply that adjacent elements of a column in the vertex grid are filled in consecutively: see the description of INPUT_GRID_ORDER_ROW_MAJOR.) Values are 'YES' or 'NO'.

COMMENT_FILE
  Comment file name. This keyword is used if you want to include comments provided in this file in the comment area of the DSK file. Include full or relative path specification.

COORDINATE_SYSTEM
  Name of the coordinate system used to represent the bounds of spatial coverage of the data set. The supported values are 'LATITUDINAL', 'PLANETODETIC', and 'RECTANGULAR'. 'LATITUDINAL' refers to planetocentric coordinates.

DATA_CLASS
  Code identifying the category of topography represented by the surface. Supported codes are: 1 for a surface that can be represented as a single-valued function of its domain coordinates; an example is a surface defined by a function that maps each planetodetic longitude and latitude pair to a unique altitude. 2 for arbitrary topography (e.g. that of a dumbbell-shaped asteroid). This assignment is required.

DATA_TYPE
  Code indicating the DSK data type of the DSK segment to be created. Currently the only supported code is 2 (triangular plates). This assignment is required.

EQUATORIAL_RADIUS
  Applies only to planetodetic coordinates. This is the equatorial radius of the reference ellipsoid. Units are always km.

FINE_VOXEL_SCALE
  This assignment is optional and need not be used for most applications. It is applicable only to type 2 segments. See the section ``Appendix A: Spatial Index and Voxels'' below for a more detailed discussion. The fine voxel scale is a double precision number. Normally the fine voxel scale should be set to at least 1.0.

HEIGHT_REFERENCE
  Applies only to height grid inputs for data type 2 segments using 'LATITUDINAL' or 'RECTANGULAR' coordinates. Input height values are scaled by the height scale and then added to the height reference value to produce vertex heights. Units are always km.

HEIGHT_SCALE
  Applies only to height grid inputs for data type 2 segments. Input height values are multiplied by the height scale to convert them to km. This value is unitless.

INPUT_DATA_UNITS
  Array of two strings specifying the units of the input data. The right hand side of the assignment has the format ( 'ANGLES = angular unit' 'DISTANCES = distance unit' ). The units accepted by the CSPICE routine convrt_c are accepted in this assignment. This assignment is required.

INPUT_GRID_ORDER_ROW_MAJOR
  Applies only to height grid inputs for data type 2 segments. Indicates that rows of the vertex grid are filled sequentially as data are read from the input file. The alternative is that columns of the vertex grid are filled in sequentially. Values are 'YES' or 'NO'.

INPUT_SHAPE_FILE
  Name of input shape data file. This keyword must be used if the input data file name is not provided on the command line; if the input data file name is supplied on the command line, this assignment is ignored. Include full or relative path specification. The file must exist.

KERNELS_TO_LOAD
  This is the SPICE meta-kernel keyword that identifies kernels to load. The right hand side is a list of single-quoted kernel names; the list is enclosed in parentheses. A leapseconds kernel may be specified using this assignment rather than a LEAPSECONDS_FILE assignment. Other kernels that might be needed are frame kernels, a kernel defining body name-ID associations, and a kernel defining surface name-ID associations.

LEAPSECONDS_FILE
  leapseconds file name. This is the SPICE LSK file name, including full or relative path specification. A leapseconds kernel can be specified using a KERNELS_TO_LOAD assignment instead of this one. Specification of a leapseconds kernel by one of these means is required. Only one leapseconds kernel should be specified, but if distinct leapseconds kernels are specified using both keywords, the one specified by the LEAPSECONDS_FILE keyword is loaded last and hence overrides the other.

LEFT_COLUMN_LONGITUDE
  Applies only to height grid inputs for data type 2 segments, when the coordinate system is 'LATITUDINAL' or 'PLANETODETIC'. This is the longitude of the grid's leftmost column. Units are given by the INPUT_DATA_UNITS assignment.

LEFT_COLUMN_X_COORDINATE
  Applies only to height grid inputs for data type 2 segments, when the coordinate system is 'RECTANGULAR'. This is the X value of the grid's leftmost column. Units are given by the INPUT_DATA_UNITS assignment.

MAKE_NORTH_POLAR_CAP
  Applies only to height grid inputs for data type 2 segments, when the coordinate system is 'LATITUDINAL' or 'PLANETODETIC'. Indicates that the vertex grid should be augmented by a vertex at the north pole, and that plates should be formed using this vertex and the vertices of the grid's top row. Values are 'YES' or 'NO'.

MAKE_SOUTH_POLAR_CAP
  Applies only to height grid inputs for data type 2 segments, when the coordinate system is 'LATITUDINAL' or 'PLANETODETIC'. Indicates that the vertex grid should be augmented by a vertex at the south pole, and that plates should be formed using this vertex and the vertices of the grid's bottom row. Values are 'YES' or 'NO'.

MAKE_VERTEX_PLATE_MAP
  Indicates that the optional vertex-plate mapping data structure should be created. Values are 'YES' or 'NO'.

MAXIMUM_LATITUDE
  Upper latitude bound of spatial coverage in selected angular units. Units are those specified by the INPUT_DATA_UNITS assignment. This assignment is required when the coordinate system is LATITUDINAL or PLANETODETIC.

MAXIMUM_LONGITUDE
  Upper longitude bound of spatial coverage in selected angular units. Units are those specified by the INPUT_DATA_UNITS assignment. When the longitude coverage of the segment is 360 degrees, MAXIMUM_LONGITUDE should be set to a value equivalent to 360 degrees greater than the value assigned to MINIMUM_LONGITUDE. For example, if the angular units are degrees, the longitude bounds could be set to -180.0 and 180.0 respectively, or if the angular units are radians, the bounds could be set to the numeric values of -pi and pi, respectively. This assignment is required when the coordinate system is LATITUDINAL or PLANETODETIC.

MAXIMUM_X
  Applies only to height grid inputs for data type 2 segments, when the coordinate system is 'RECTANGULAR'. This is the maximum value of the X-coordinates of the vertices. Units are given by the INPUT_DATA_UNITS assignment.

MAXIMUM_Y
  Applies only to height grid inputs for data type 2 segments, when the coordinate system is 'RECTANGULAR'. This is the maximum value of the Y-coordinates of the vertices. Units are given by the INPUT_DATA_UNITS assignment.

MINIMUM_LATITUDE
  Lower latitude bound of spatial coverage in selected angular units. Units are those specified by the INPUT_DATA_UNITS assignment. This assignment is required when the coordinate system is LATITUDINAL or PLANETODETIC.

MINIMUM_LONGITUDE
  Lower longitude bound of spatial coverage in selected angular units. Units are those specified by the INPUT_DATA_UNITS assignment. This assignment is required when the coordinate system is LATITUDINAL or PLANETODETIC.

MINIMUM_X
  Applies only to height grid inputs for data type 2 segments, when the coordinate system is 'RECTANGULAR'. This is the minimum value of the X-coordinates of the vertices. Units are given by the INPUT_DATA_UNITS assignment.

MINIMUM_Y
  Applies only to height grid inputs for data type 2 segments, when the coordinate system is 'RECTANGULAR'. This is the minimum value of the Y-coordinates of the vertices. Units are given by the INPUT_DATA_UNITS assignment.

NUMBER_OF_COLUMNS
  Applies only to height grid inputs for data type 2 segments. This is the number of columns of vertices in the grid.

NUMBER_OF_ROWS
  Applies only to height grid inputs for data type 2 segments. This is the number of rows of vertices in the grid.

OUTPUT_DSK_FILE
  Name of output DSK file. This keyword must be used if the output data file name is not provided on the command line; if the output data file name is supplied on the command line, this assignment is ignored. Include full or relative path specification. The file must not exist when MKDSK is run.

PLATE_TYPE
  Code indicating the format of the input data file. This code is applicable only when the data type is 2; in this case, this assignment is required. Supported values are: 1 for plate-vertex table; 2 for Gaskell shape model; 3 for vertex-facet table; 4 for Rosetta/OSIRIS ``ver'' table; 5 for an ASCII height grid. See the chapter below titled ``Input Data File'' for details.

POLAR_RADIUS
  Applies only to 'PLANETODETIC' coordinates. This is the polar radius of the reference ellipsoid. Units are always km.

REF_FRAME_NAME
  Name of the body-fixed reference frame relative to which the surface data are expressed. This frame need not be centered on the body specified by the keyword CENTER_NAME, but this frame must be fixed to that body. The center of this frame is the origin of the coordinate system in which the shape data are expressed. For example, for a DSK type 2 segment for Mars that uses the reference frame IAU_MARS, the vertices of the segment are assumed to emanate from the center of mass of Mars. This assignment is required.

ROW_STEP_SIZE
  Applies only to height grid inputs for data type 2 segments. This is the grid's step size for latitude or for Y, depending on the specified coordinate system. Units are given by the INPUT_DATA_UNITS assignment.

ROW_VALUE_ORDER_LEFT_RIGHT
  Applies only to height grid inputs for data type 2 segments. Indicates that rows of the vertex grid are filled in in left-to-right order as data are read from the input file. (This does not imply that adjacent elements of a row in the vertex grid are filled in consecutively: see the description of INPUT_GRID_ORDER_ROW_MAJOR.) Values are 'YES' or 'NO'.

START_TIME
  Start time of coverage interval during which this surface representation is applicable. The value is a quoted string; any string acceptable to the SPICE routine STR2ET is allowed. This assignment is required.

STOP_TIME
  Stop time of coverage interval during which this surface representation is applicable. The value is a quoted string; any string acceptable to the SPICE routine STR2ET is allowed. This assignment is required.

SURFACE_NAME
  Name of the surface represented by the DSK, for example 'MGS MOLA MEGDR 128 PIXELS/DEG'. An integer ID code enclosed in single quotes may be provided instead of a name, e. g. '1' instead of 'MGS MOLA MEGDR 128 PIXELS/DEG'. Surface name-ID associations must be defined in a text kernel or in the MKDSK setup file. Multiple surfaces can be associated with a given central body and used together during a single application program run. For example, versions of surfaces having different resolutions could be associated with a given central body. This assignment is required.

TOP_ROW_LATITUDE
  Applies only to height grid inputs for data type 2 segments, when the coordinate system is 'LATITUDINAL' or 'PLANETODETIC'. This is the latitude of the grid's top row. Units are given by the INPUT_DATA_UNITS assignment.

TOP_ROW_Y_COORDINATE
  Applies only to height grid inputs for data type 2 segments, when the coordinate system is 'RECTANGULAR'. This is the Y value of the grid's top row. Units are given by the INPUT_DATA_UNITS assignment.

WRAP_LONGITUDE
  Applies only to height grid inputs for data type 2 segments, when the coordinate system is 'LATITUDINAL' or 'PLANETODETIC'. Indicates that plates are to be formed connecting vertices in the rightmost column to those in the leftmost column. Values are 'YES' or 'NO'.

Top

# Setup File Examples

Top

### Input Using Latitudinal Coordinates and Plate Type 2

An example command file for a Phobos DSK:

       \begindata

       INPUT_SHAPE_FILE    = 'phobos_q512.txt'
       OUTPUT_DSK_FILE     = 'phobos512.bds'
       COMMENT_FILE        = ' '
       KERNELS_TO_LOAD     = ( 'naif0012.tls' )
       SURFACE_NAME        = 'Gaskell Phobos Q=512'
       CENTER_NAME         = 'PHOBOS'
       REF_FRAME_NAME      = 'IAU_PHOBOS'
       START_TIME          = '1950-JAN-1/00:00:00'
       STOP_TIME           = '2050-JAN-1/00:00:00'
       DATA_CLASS          = 1
       INPUT_DATA_UNITS    = ( 'ANGLES    = DEGREES'
                               'DISTANCES = KILOMETERS' )
       COORDINATE_SYSTEM   = 'LATITUDINAL'
       MINIMUM_LATITUDE    =  -90.0
       MAXIMUM_LATITUDE    =   90.0
       MINIMUM_LONGITUDE   = -180.0
       MAXIMUM_LONGITUDE   =  180.0
       DATA_TYPE           = 2
       PLATE_TYPE          = 2

       NAIF_SURFACE_NAME   += 'Gaskell Phobos Q=512'
       NAIF_SURFACE_CODE   += 1
       NAIF_SURFACE_BODY   += 401

       \begintext

Top

### Input Using Planetodetic Coordinates and Plate Type 1

This is an example command file for a Mars DSK. The input plate data were derived from the MGS MOLA data set named

       megr90n000cb

This data set has a resolution of 4 pixels/degree. The surface coverage is global.

This example presumes that vertices and plates have already been derived from original input data, which constitute a digital elevation model (DEM).

       \begindata

       INPUT_SHAPE_FILE    = 'megr90n000cb.inp'
       OUTPUT_DSK_FILE     = 'megr90n000cb_1.bds'
       COMMENT_FILE        = ' '
       KERNELS_TO_LOAD     = ( 'naif0012.tls' )
       SURFACE_NAME        = 'megr90n000cb --- plates'
       CENTER_NAME         = 'MARS'
       REF_FRAME_NAME      = 'IAU_MARS'
       START_TIME          = '1950-JAN-1/00:00:00'
       STOP_TIME           = '2050-JAN-1/00:00:00'
       DATA_CLASS          = 1
       INPUT_DATA_UNITS    = ( 'ANGLES    = DEGREES'
                               'DISTANCES = KILOMETERS' )

       COORDINATE_SYSTEM   = 'PLANETODETIC'
       EQUATORIAL_RADIUS   = 3396.19
       POLAR_RADIUS        = 3376.20

       MINIMUM_LATITUDE    =  -90.0
       MAXIMUM_LATITUDE    =   90.0
       MINIMUM_LONGITUDE   = -180.0
       MAXIMUM_LONGITUDE   =  180.0
       DATA_TYPE           = 2
       PLATE_TYPE          = 1

       NAIF_SURFACE_NAME   += 'megr90n000cb --- plates'
       NAIF_SURFACE_CODE   += 1
       NAIF_SURFACE_BODY   += 499

       \begintext

Top

### Input Using Planetocentric Coordinates and Plate Type 5

This example uses the same data as the previous one, but in this case, the height values have been transferred to an ASCII file, which serves as the input data file.

We give this surface a distinct name from that of the previous example, since the plate set created from the input data will differ.

The input data file is organized in row-major, top-down, left-to-right order.

The top and bottom input pixel centers are 1/2 pixel away from the poles, so we add polar caps. Similarly, the pixel centers of leftmost and rightmost columns are one pixel apart, so we invoke longitude wrapping. These choices create a plate set with complete coverage.

The distance units are meters.

       \begindata

       INPUT_SHAPE_FILE            = 'megr90n000cb.inp'
       OUTPUT_DSK_FILE             = 'megr90n000cb_2.bds'
       COMMENT_FILE                = ' '
       KERNELS_TO_LOAD             = ( 'naif0012.tls' )
       SURFACE_NAME                = 'megr90n000cb --- grid'
       CENTER_NAME                 = 'MARS'
       REF_FRAME_NAME              = 'IAU_MARS'
       START_TIME                  = '1950-JAN-1/00:00:00'
       STOP_TIME                   = '2050-JAN-1/00:00:00'
       DATA_CLASS                  = 1
       INPUT_DATA_UNITS            = ( 'ANGLES    = DEGREES'
                                       'DISTANCES = METERS' )

       COORDINATE_SYSTEM           = 'LATITUDINAL'

       NUMBER_OF_ROWS              = 720
       NUMBER_OF_COLUMNS           = 1440

       ROW_STEP_SIZE               = 0.25
       COLUMN_STEP_SIZE            = 0.25

       LEFT_COLUMN_LONGITUDE       = -180.0
       TOP_ROW_LATITUDE            =   89.875

       INPUT_GRID_ORDER_ROW_MAJOR  = 'YES'
       COLUMN_VALUE_ORDER_TOP_DOWN = 'YES'
       ROW_VALUE_ORDER_LEFT_RIGHT  = 'YES'

       WRAP_LONGITUDE              = 'YES'
       MAKE_NORTH_POLAR_CAP        = 'YES'
       MAKE_SOUTH_POLAR_CAP        = 'YES'

       HEIGHT_SCALE                = 1.D-3
       HEIGHT_REFERENCE            = 3396000

       MINIMUM_LATITUDE            =  -90.0
       MAXIMUM_LATITUDE            =   90.0
       MINIMUM_LONGITUDE           = -180.0
       MAXIMUM_LONGITUDE           =  180.0

       DATA_TYPE                   = 2
       PLATE_TYPE                  = 5

       NAIF_SURFACE_NAME           += 'megr90n000cb --- grid'
       NAIF_SURFACE_CODE           += 2
       NAIF_SURFACE_BODY           += 499

       \begintext

Top

# Input Data File

All of the input files discussed below are particular to type 2 (triangular plate model) DSK segments.

The type 2 segment design has no restrictions on sizes or configuration of the triangular plates defined by the vertices, even within a single plate model file. Indeed it is quite normal that the plate sizes and local plate density vary across the model in order to achieve desired shape fidelity without using an excessive number of plates.

It is recommended that the input data not define any degenerate plates (plates having zero-length edges). Such plates may cause run-time failures of computations that require each plate to have a computable outward normal vector.

MKDSK reads an ASCII text file containing body shape data. This text file must conform to one of the following formats:

Plate-vertex table
  Contains the body-fixed coordinates of each vertex in a plate model followed by a list that associates particular vertices with each plate. This file explicitly assigns integer IDs to the plates and vertices.

Gaskell shape model
  Contains the body-fixed coordinates of each vertex in a plate model. The order of the vertex data implicitly defines the plate-vertex mapping.

Vertex-facet table
  Is similar to the plate-vertex table, but without the plate and vertex ID assignment. A data line has the prefix 'v' for vertex data and 'f' for the plate-vertex mapping (the facet map).

Rosetta/OSIRIS ``ver'' table
  (The format of M. Kasalaainen.) Contains the body-fixed coordinates of each vertex in a plate model followed by a list that associates particular vertices with each plate. Each line of plate vertex indices is preceded by a line containing a vertex count. Only triangular plates are supported by this program.

ASCII height grid
  Contains height values of a regular grid of vertices. For segments using the planetocentric latitudinal or planetodetic coordinate systems, the vertices are separated by equal longitude increments and by equal latitude increments. In the rectangular system, the vertices are separated by equal X increments and equal Y increments.

Top

## Units

The distance units of plate model vertex data may be any supported by the SPICE unit conversion routine convrt_c. Distance units must be specified in the MKDSK setup file.

Top

## Reference Frame

The reference frame of all plate model vertex data must be specified in the MKDSK setup file. The frame must be body-fixed with respect to the body identified in the setup file as the ``center'' associated with the surface. However, the frame need not have that body as its own center.

Top

## Vertex order

The ordering of the plate vertices is expected to follow a "right-handed" convention where the order of vertices implicitly defines the orientation of the outward normal, i.e. given the assignment

          plate =  vertex_1, vertex_2, vertex_3

derive the outward normal as:

          -      --------   --------     --------   --------
          n  = ( vertex_2 - vertex_1) X (vertex_3 - vertex_2)

Top

### Vertex IDs

Vertex IDs always start at 1. Their upper bound is NV, the number of vertices. Input data files that use plates must conform to this convention.

Top

## Plate Data File Type 1 (Plate-Vertex Table)

The data input file consists of two sections, the first for vertex data, the second describing the plate-vertex mapping.

       N
       1 X(1) Y(1) Z(1)
       2 X(2) Y(2) Z(2)

             ...

       N X(N) Y(N) Z(N)
       M
       1 V1(1) V2(1) V3(1)
       2 V1(2) V2(2) V3(2)

             ...

       M V1(M) V2(M) V3(M)

where

N
  is the number of vertices listed in the file.

1 through N
  are the indices of the plate model vertices, provided as the first space-separated item on the file lines 2 through (N+1).

X(i) Y(i) Z(i)
  are the body-fixed Cartesian coordinates of the plate model vertices, provided for each vertex as the 2nd, 3rd, and 4th space-separated items on lines 2 through (N+1).

M
  is the number of plate-vertex mappings in the file.

1 through M
  are the indices of the plate model plates, provided as the first space-separated item on the file lines (N+3) through (N+M+2).

V1(i) V2(i) V3(i)
  are the indices of the plate model vertices for the corners of a given plate, provided for each plate as the 2nd, 3rd, and 4th space-separated items on lines (N+3) through (N+M+2).

Top

### Sample Plate-Vertex Table Input File

          12
          1 0. 0. 1.17557
          2 0.32492 1. 0.525731
          3 1.05146 0. 0.525731
          4 -0.850651 0.618034 0.525731
          5 -0.850651 -0.618034 0.525731
          6 0.32492 -1. 0.525731
          7 0.850651 0.618034 -0.525731
          8 -0.32492 1. -0.525731
          9 -1.05146 0. -0.525731
          10 -0.32492 -1. -0.525731
          11 0.850651 -0.618034 -0.525731
          12 0. 0. -1.17557
          20
          1 1 3 2
          2 1 2 4
          3 1 4 5
          4 1 5 6
          5 1 6 3
          6 3 7 2
          7 2 8 4
          8 4 9 5
          9 5 10 6
          10 6 11 3
          11 7 8 2
          12 8 9 4
          13 9 10 5
          14 10 11 6
          15 11 7 3
          16 7 12 8
          17 8 12 9
          18 9 12 10
          19 10 12 11
          20 11 12 7

Top

## Plate Data File Type 2 (Gaskell Shape Model)

A Gaskell shape model data file has no explicit plate-vertex mapping data as that information is implicit in the ordering of the vertex data.

The data file has the form:

          Q
          X(1)          Y(1)          Z(1)
          X(2)          Y(2)          Z(2)

           ...          ...           ...
          X(6*(Q+1)^2)  Y(6*(Q+1)^2)  Z(6*(Q+1)^2)

where

Q
  is the number of divisions per side on a cube face. The number of vertices in the file is

                                            6 * (Q+1)^2

X(i) Y(i) Z(i)
  are the body-fixed Cartesian coordinates of the plate model vertices, provided for each vertex as the 1st, 2nd, and 3rd space-separated items on lines 2 through Nvert+1.

Top

### Sample Gaskell Shape Model Input File

           64
           -9.36329     3.76796     3.80970
           -9.12138     3.82357     3.86143
           -8.87987     3.88047     3.91416
           -8.63347     3.92422     3.95698
           -8.39016     3.97415     4.00291
           -8.14081     4.03950     4.05743
           -7.88861     4.08816     4.09352
           -7.63058     4.07331     4.08113
           -7.37114     4.03909     4.05807
           -7.11810     4.05018     4.08515
           -6.89451     4.12730     4.15128
           -6.69135     4.24326     4.25130
           -6.46167     4.30681     4.31349

             ...         ...         ...

Top

## Plate Data File Type 3 (Vertex-Facet Table)

The data input file consists of two sections, the first for vertex data, the second describing the plate-vertex mapping.

       v X(1)  Y(1)  Z(1)
       v X(2)  Y(2)  Z(2)

              ...

       v X(N)  Y(N)  Z(N)
       f V1(1) V2(1) V3(1)
       f V1(2) V2(2) V3(2)

              ...

       f V1(M) V2(M) V3(M)

where

X(i) Y(i) Z(i)
  are the body-fixed Cartesian coordinates of the plate model vertices, provided for each vertex as the 2nd, 3rd, and 4th space-separated items on the data lines. Each vertex line has the prefix character 'v'.

V1(i) V2(i) V3(i)
  are the indices of the plate model vertices for the corners of a given plate, provided for each plate as the 2nd, 3rd, and 4th space-separated items on the data lines. Each vertex line has the prefix character 'f'.

Top

### Sample Vertex-Facet Input File

       v 0. 0. 1.17557
       v 0.32492 1. 0.525731
       v 1.05146 0. 0.525731
       v -0.850651 0.618034 0.525731
       v -0.850651 -0.618034 0.525731
       v 0.32492 -1. 0.525731
       v 0.850651 0.618034 -0.525731
       v -0.32492 1. -0.525731
       v -1.05146 0. -0.525731
       v -0.32492 -1. -0.525731
       v 0.850651 -0.618034 -0.525731
       v 0. 0. -1.17557
       f 1 3 2
       f 1 2 4
       f 1 4 5
       f 1 5 6
       f 1 6 3
       f 3 7 2
       f 2 8 4
       f 4 9 5
       f 5 10 6
       f 6 11 3
       f 7 8 2
       f 8 9 4
       f 9 10 5
       f 10 11 6
       f 11 7 3
       f 7 12 8
       f 8 12 9
       f 9 12 10
       f 10 12 11
       f 11 12 7

Top

## Rosetta/OSIRIS ``ver'' File

The file starts with a line containing vertex and plate counts. Vertex data follow; the coordinates of each vertex are placed on a line. The vertex indices are implied by the order of the vertex data lines. A section of plate data follows the section of vertex data. Each line of plate data is preceded by a line containing that plate's vertex count. Each plate must be triangular in order to be processed by this program.

Top

### Sample Rosetta/OSIRIS ``ver'' File

       12  20
        0. 0. 1.17557
        0.32492 1. 0.525731
        1.05146 0. 0.525731
        -0.850651 0.618034 0.525731
        -0.850651 -0.618034 0.525731
        0.32492 -1. 0.525731
        0.850651 0.618034 -0.525731
        -0.32492 1. -0.525731
        -1.05146 0. -0.525731
        -0.32492 -1. -0.525731
        0.850651 -0.618034 -0.525731
        0. 0. -1.17557
       3
         1 3 2
       3
         1 2 4
       3
         1 4 5
       3
         1 5 6
       3
         1 6 3
       3
         3 7 2
       3
         2 8 4
       3
         4 9 5
       3
         5 10 6
       3
        6 11 3
       3
        7 8 2
       3
        8 9 4
       3
        9 10 5
       3
        10 11 6
       3
        11 7 3
       3
        7 12 8
       3
        8 12 9
       3
        9 12 10
       3
        10 12 11
       3
        11 12 7

Top

## ASCII Height Grid File

An ASCII height grid file defines a surface by means of a set of height values associated with a regular grid of coordinate pairs, which may be any of

`--` Planetocentric longitude and latitude

`--` Planetodetic longitude and latitude

`--` Rectangular X and Y

The coordinate pairs and heights define a vertex grid in 3-dimensional space. The vertex grid has a rectangular shape in either longitude and latitude or X and Y, depending on the specified coordinate system. It has row and column counts specified by the setup file.

Each group of four adjacent vertices in the grid defines a pair of plates as shown below:

                vertex(I,J)      vertex(I,J+1)
                    +----------------+
                    |\               |
                    | \              |
                    |  \             |
                    |   \            |
                    |    \           |
                    |     \          |
                    |      \         |
                    |       \        |
                    |        \       |
                    |         \      |
                    |          \     |
                    |           \    |
                    |            \   |
                    |             \  |
                    |              \ |
                    |               \|
                    +----------------+
                vertex(I+1,J)      vertex(I+1,J+1)

Top

### Domain Coordinates

The pairs of coordinates (longitude, latitude) or (X, Y) are called ``domain coordinates,'' since they constitute the domain of a function whose range is the set of input height values.

The size of the grid is given by a row count NROWS and a column count NCOLS; these are the values assigned by the setup file to the keywords NUMBER_OF_ROWS and NUMBER_OF_COLUMNS.

The domain coordinates of the grid are defined by starting values and constant step values. For planetocentric latitudinal and planetodetic coordinates, longitudes are defined by a ``leftmost'' (minimum) longitude LFTLON and a longitude step size LONSTP. These are the values assigned to the keywords LEFT_COLUMN_LONGITUDE and COLUMN_STEP_SIZE. The longitudes of the grid points increase from

       LFTLON to LFTLON + ((NCOLS-1) * LONSTP)

Latitudes are defined by a top (maximum) latitude TOPLAT and a latitude step size LATSTP. These are the values assigned to the keywords TOP_ROW_LATITUDE and ROW_STEP_SIZE. The latitudes of the grid points decrease from

       TOPLAT to TOPLAT - ((NROWS-1) * LATSTP)

For rectangular coordinates, X vaues are defined by a ``leftmost'' (minimum) X value LEFTX and an X step size XSTEP. These are the values assigned to the keywords LEFT_COLUMN_X and COLUMN_STEP_SIZE. The X values of the grid points increase from

       LEFTX to LEFTX + ((NCOLS-1) * XSTEP)

Y values are defined by a top (maximum) Y value TOPY and a Y step size YSTEP. These are the values assigned to the keywords TOP_ROW_Y and ROW_STEP_SIZE. The Y values of the grid points decrease from

       TOPY to TOPY - ((NROWS-1) * YSTEP)

Top

### Heights

Height values need not be given in standard units; rather, an input parameter called the ``height scale'' must be present in the setup file. The keyword for the height scale is

       HEIGHT_SCALE

This scale is a factor by which the input heights are to be multiplied to convert them to km.

For planetodetic coordinates, heights are expressed relative to the reference spheroid of the coordinate system. The equatorial and polar radii of this spheroid are provided as setup file inputs.

For planetocentric latitudinal and rectangular coordinates, input heights are expressed relative to a reference height value which is supplied in the setup file; the keyword for this value is HEIGHT_REFERENCE. Units of the reference height are always km.

Top

### Height Grid File Format

The input height grid file should contain only printable ASCII characters. It should not contain tab characters. The line length should not exceed 255 characters. Each data value must be parseable as a double precision number. Data values cannot have embedded blanks. Values must not be split across lines.

The data values must be separated by blanks or commas.

There are no restrictions on the precision of the data values.

The count of data values per line need not be constant. However, the file may be easier to human readers to scan if data values are placed in fixed-width columns.

Top

### Height Grid Data Order

MKDSK reads the input file sequentially: it views the values in a height grid file as a 1-dimensional stream of data. Values in lines are read from the file from left to right; lines are read from the start of the file to the end.

MKDSK can accept a variety of data orders. The order of data in the input file are described by keywords in the setup file.

The input data can be in either ``row-major'' or ``column-major'' order.

Row-major order means that data for rows in the vertex grid are adjacent in the input file: the first NCOLS elements of the file belong to a row, the next NCOLS elements belong to a row, and so on.

Column-major order means that data for columns in the vertex grid are adjacent in the input file: the first NROWS elements of the file belong to a column, the next NROWS elements belong to a column, and so on.

The assignment of the string 'YES' to the keyword

       INPUT_GRID_ORDER_ROW_MAJOR

indicates that the data are in row-major order. The assignment of 'NO' indicates the data are in column-major order.

The columns of the vertex grid can be filled in in top-down or bottom-up order. When top-down ordering is used, data within each vertex grid column are filled in in order of decreasing latitude or Y-value. This applies whether or not the input file has row-major order. If the order is not top-down, it is bottom-up. The assignment of the string 'YES' to the keyword

       COLUMN_VALUE_ORDER_TOP_DOWN

indicates that the data are in top-down order. The assignment of 'NO' indicates the data are in bottom-up order.

The rows of the vertex grid can be filled in in left-to-right or right-to-left order. When left-to-right ordering is used, data within each vertex grid row are filled in in order of increasing longitude or X-value. This applies whether or not the input file has row-major order. If the order is not left-to-right, it is right-to-left. The assignment of the string 'YES' to the keyword

       ROW_VALUE_ORDER_LEFT_RIGHT

indicates that the data are in left-to-right order. The assignment of 'NO' indicates the data are in right-to-left order.

The following examples show different possible orderings of the input height data. All orderings shown can be described by assignments in the setup file.

For this example, we use an extremely small vertex grid having two rows and three columns. Let the vertices of the vertex grid be numbered as follows:

          1     2     3

          4     5     6

The orderings of the data for these vertices, as a function of the data file's attributes, are shown below.

Row-major, top-down, left-right:

        1  2  3
        4  5  6

Row-major, top-down, right-left:

        3  2  1
        6  5  4

Row-major, bottom-up, left-right:

        4  5  6
        1  2  3

Row-major, bottom-up, right-left:

        6  5  4
        3  2  1

Column-major, top-down, left-right:

        1  4
        2  5
        3  6

Column-major, top-down, right-left:

        3  6
        2  5
        1  4

Column-major, bottom-up, left-right:

        4  1
        5  2
        6  3

Column-major, bottom-up, right-left:

        6  3
        5  2
        4  1

Top

### Polar Caps

If the segment's coordinate system is 'LATITUDINAL' or 'PLANETODETIC', then if polar latitude coverage by the plate set is desired, it may be necessary to fill in a gap above the northernmost or below the southernmost rows of the vertex grid.

A polar cap is created by placing an artificial vertex on the positive or negative Z axis, as specified. The height of the vertex is derived by taking the average of the heights from the adjacent row of the vertex grid. Plates are formed using the polar vertex and vertices of the adjacent row of vertices.

If longitude wrapping is enabled, a plate is created that covers the region between the specified pole and that filled in by longitude wrapping.

North and south polar caps can be created independently. The assignment of the string 'YES' to either of the keywords

       MAKE_NORTH_POLAR_CAP
       MAKE_SOUTH_POLAR_CAP

enables creation of the specified polar caps.

Plates created for the north polar cap have the following form:

                north polar vertex
                    +
                    |\
                    | \
                    |  \
                    |   \
                    |    \
                    |     \
                    |      \
                    |       \
                    |        \
                    |         \
                    |          \
                    |           \
                    |            \
                    |             \
                    |              \
                    |               \
                    +----------------+
                vertex(1,J)      vertex(1,J+1)

Plates created for the south polar cap are like the above, but include vertices of the southernmost row of the grid, and are inverted in the direction of latitude.

A polar cap should not be generated if the input data set already has a row of vertices with latitude on that pole: the cap would contain degenerate plates.

Top

### Longitude Wrapping

If the segment's coordinate system is 'LATITUDINAL' or 'PLANETODETIC', then if 360-degree longitude coverage by the plate set is desired, it may be necessary to fill in a gap between the rightmost and leftmost vertex columns. When the ``longitude wrapping'' feature is enabled, plates are formed that join the vertices of these columns. The assignment of the string 'YES' to the keyword

       WRAP_LONGITUDE

enables longitude wrapping.

Plates created by longitude wrapping have the following form:

                vertex(I,NCOLS)     vertex(I,1)
                    +----------------+
                    |\               |
                    | \              |
                    |  \             |
                    |   \            |
                    |    \           |
                    |     \          |
                    |      \         |
                    |       \        |
                    |        \       |
                    |         \      |
                    |          \     |
                    |           \    |
                    |            \   |
                    |             \  |
                    |              \ |
                    |               \|
                    +----------------+
                vertex(I+1,NCOLS)    vertex(I+1,1)

The plate created by longitude wrapping for the north polar cap has the form:

                north polar vertex
                    +
                    |\
                    | \
                    |  \
                    |   \
                    |    \
                    |     \
                    |      \
                    |       \
                    |        \
                    |         \
                    |          \
                    |           \
                    |            \
                    |             \
                    |              \
                    |               \
                    +----------------+
                vertex(1,NCOLS)    vertex(1,1)

The plate created by longitude wrapping for the south polar cap is like the above, but includes vertices of the southernmost row of the grid, and is inverted in the direction of latitude.

Longitude wrapping should not be used if the input data set already has the rightmost column overlapping the leftmost column. The new plates would either be degenerate or inward-facing.

Top

# Output DSK File

The output DSK file has a single segment, the contents of which are derived from the input data and from parameters specified in the setup file.

The output file is not human-readable: it is a binary file designed to support rapid read access by SPICE software and SPICE-based applications.

The contents of the output file can be summarized by running the SPICE utility program DSKBRIEF. It is recommended that DSK creators use DSKBRIEF to verify that the output file has the intended attributes.

Data may be extracted from the output DSK file using the interface software provided in the SPICE library. Data also may be exported from the DSK file to a human-readable text file by means of the SPICE utility program DSKEXP.

Top

# Appendix A: Spatial Index and Voxels

This discussion applies to type 2 segments.

``Voxel scales'' are attributes of a data structure in type 2 DSK segments called a ``spatial index.'' The spatial index enables type 2 DSK software to rapidly locate plates in a given region of space.

Starting with the release of the N0066 SPICE Toolkit, MKDSK automatically computes voxel scales appropriate for the input data.

In some cases, speed of ray-surface intercept computations can be improved by manually adjusting the voxel scales.

See the DSK Required Reading [1] for a detailed description of DSK type 2 spatial indexes.