MapMaker Basic User's Manual

ABSTRACT

MapMaker is a cartographic processing tool for generating tailor-made image maps of planetary surfaces. Maps are defined by specifying a dataset, latitude and longitude range, map scale (or resolution), map projection, and output format. Processing options such as contrast stretch and grid overlay can additionally be specified.

The sources of input for MapMaker are the digital global maps produced for NASA by flight projects and the Planetary Geology and Geophysics program. The global maps, contained on CD-ROM media, include the Mars MDIM series, Venus F-Map, and Clementine basemap mosaics. These data products are available through the Planetary Data System Imaging Node.

MapMaker is primarily intended as a "cartographic engine" for high-level applications that require custom maps of planetary surfaces. An application creates a command file describing a map to be produced and then launches MapMaker to create the map. The resulting map can be included in additional processing by the application. MapMaker has been used successfully in the World Wide Web applications "Mars Explorer for the Armchair Astronaut" and the "Planetary Atlas".

MapMaker can additionally operate as a stand-alone program. The "mmedit" interface allows a user to specify a map to be produced by MapMaker.

DOCUMENT SUMMARY

• WHAT IS MAPMAKER : An overview of the software capabilities and uses.
• HOW TO RUN MAPMAKER : This explains how to use the MapMaker stand-alone interface.
• COMMAND FILE FIELDS : A description of each of the command file fields.
• RUNNING MAPMAKER FROM THE COMMAND LINE : Discusses command line syntax.
• DATA SETS SUPPORTED BY MAPMAKER : Lists current data sets and how to get them.
• BUG REPORTING : What to do if a bug is encountered.
• DISCLAIMER : Legal warranty information.

WHAT IS MAPMAKER

MapMaker is a software package that produces tailor-made images from Planetary Data System datasets. Several datasets have been developed by NASA programs, including CD-ROM sets of Mars, Venus and the Moon. Any cartographic data with a sinusoidal projection can be used by MapMaker if the correct PDS labels and support files are created (see MAPMAKER APPLICATION DEVELOPMENT: PART III: BUILDING A DATASET).

MapMaker can access datasets on hard-drive, CD-ROM jukebox, or common CD-ROM reader. Because of the large size of the planetary datasets, a CD-ROM jukebox provides the smoothest interface between the planetary datasets and MapMaker.

Installation of MapMaker requires a knowledge of the UNIX operating system and environment (see MAPMAKER VERSION 2.0 INSTALLATION AND CONFIGURATION MANUAL) and should be performed by someone with system administration skills. Once MapMaker has been installed a user can specify and create maps through a web or web-like application, through the mmedit user interface provided, or through any other interface developed to run MapMaker (see MAPMAKER APPLICATION DEVELOPMENT). This document provides information on the stand-alone user interface, mmedit.

HOW TO RUN MAPMAKER

Platforms Supported by MapMaker

Currently, the platforms supported are Sun's Sparc20 running under Solaris 2.5.1 and PC workstations running RedHat Linux version 6.1. MapMaker was developed and tested on these platforms, but should work on similar UNIX platforms.

mminit.csh

MapMaker manages it's executable files through a series of environment variables found in the file "mminit.csh" (see MAPMAKER VERSION 2.0 INSTALLATION AND CONFIGURATION MANUAL: INITIAL CONFIGURATION). Once this file has been set up properly by your system administrator, it must be initialized during each user session. The UNIX "source" command is used to initialize all the environment variables during a session. Initialization can occur in one of two ways. The user may go to the directory that contains the "mminit.csh" (commonly "/pathname/mapmaker/exec" where pathname is the directory that MapMaker was installed in) and type the following line:

source mminit.csh

or the user may use the absolute path to the "mminit.csh" file (i.e. the hierarchy of directories , starting at the root, "/", that lead up to the "mminit.csh" file) :

source /pathname/mapmaker/exec/mminit.csh.

The second method can be used to automatically initialize the "mminit.csh" file upon logging in. Simply add the given line to the user's .cshrc file in the user's home directory, and all of MapMaker's environment variables will be initialized after a successful login.

mmedit

Mmedit is a simple user interface provided with the release of MapMaker. It allows the stand-alone operation of MapMaker. Through mmedit, a user can describe the tailor-made map by choosing from available options and filling in necessary fields. This description is then written to a command file that MapMaker parses to create the map.

There are two ways to launch mmedit from the command line: with options explicitly given, or in an interactive mode with no options. In the interactive mode, MapMaker will automatically run with the options "-vcf" (verbose, clean, and filename ... see OPTIONS in this document).

To run MapMaker from the command line, a user can use the "mmedit" executable file. An executable file contains compiled computer code, and is used to launch applications. To launch MapMaker using the "mmedit" executable file, type "mmedit" followed by any desired options (see OPTIONS in this document) and hit enter. For example, to start a simple interactive mmedit session type:

mmedit

The first screen you see will ask whether you would like to create a command file, edit an existing command file, or run an existing command file ( see Fig 1.1). If the window that you are running mmedit in is not large enough, you will get the message, "Need larger window to run mmedit". Mmedit needs a screen at least 50 rows by 19 columns to run. A screen smaller than this is too small to allow command file editing. If this is your first mmedit session, choose "create a command file". If there is an existing command file you wish to edit, choose "edit a command file". If there is an existing command file that you wish to run as-is, choose "run a command file".

The following keys perform special functions while mmedit is running:

• UP and DOWN arrows scroll up and down.
• ENTER key chooses highlighted option.
• TAB key ends session and continues to next editor screen, or launches MapMaker, as needed.
• ESCAPE key cancels session and returns to command prompt.
• SPACEBAR toggles through available options.

After an option has been chosen from the command file menu, mmedit will prompt the user for a file name (see Fig 1.2).

_______________________________________________________________________
|                                                                      |
|  ****************************************************************    |
|                Welcome to MapMaker's User Interface                  |
|  ****************************************************************    |
|     UP and DOWN arrows to change option                              |
|     (ENTER) to select option                                         |
|     (TAB) to finish                                                  |
|     (SPACEBAR) to start over                                         |
|     (ESCAPE) to exit MapMaker (ESCAPE key)                           |
|                                                                      |
|                   Create a command file                              |
|                   Edit a command file                                |
|                   Run a command file                                 | 
|                                                                      |
|     (If you are just beginning choose the first option)              |
|______________________________________________________________________|


                     Fig 1.1  First mmedit screen


________________________________________________________________________
|                                                                      |
|  ****************************************************************    |
|                Welcome to MapMaker's User Interface                  |
|  ****************************************************************    |
|     UP and DOWN arrows to change option                              |
|     (ENTER) to select option                                         |
|     (TAB) to finish                                                  |
|     (SPACEBAR) to start over                                         |
|     (ESCAPE) to exit MapMaker (ESCAPE key)                           |
|                                                                      |
|                   Input the command file name                        |
|                   (this will also be the output filename)            |
|                                                                      |
|                    --                                                |
|                                                                      |
|                                                                      |
|______________________________________________________________________|

                    Fig 1.2  Inputting command file name

If the user has chosen to create a command file, this will be used as the command file name and ultimately as the name of the finished map. If the user has chosen one of the other options, mmedit will check for the existence of the command file and either allow the user to edit it, or run it. Notice that the spacebar allows the user to start over and choose a new option. The backspace and delete keys can be used to correct a spelling error or change a file name.

For example, if the user chooses to create a command file and enters the name "Map1", mmedit will create a command file, "Map1.cmd", and the finished map will be called "Map1.jpg" (if the user chose to create a jpeg image), or "Map1.gif" (if the user chose to create a gif image). If the user chose to edit an existing command file named "MarsValles", mmedit would open the file "MarsValles.cmd" and allow the user to edit it (providing "MarsValles.cmd" exists with the proper permissions).

If the user has chosen to create or edit a command file, a second screen will appear that allows the user to edit fields to describe the desired map.

_______________________________________________________________________
|                                                                      |
|                    Filename : Map1.cmd                               |
|                                                                      |
|           UP, DOWN arrows select field                               | 
|           (SPACEBAR) will edit field                                 |
|           (TAB) will end session                                     |
|           (ESC) will exit editor, saving nothing                     |
|                                                                      |
|           MapMaker Version               MM1                         |
|           Data Set Name                  mars_viking_bw              |
|           Scale / Resolution             16.00 pix/degree            |
|           Output Pixel Type              8 bit                       |
|           Resamp Method                  Nearest Neighbor            |
|           Bands                          1                           |
|           Format                         JPEG                        |
|           Projection                     Sinusoidal                  |
|           Stretch                        Auto                        |
|           Limits                         MinMax                      |
|              Maximum Lat                 20.00                       |
|              Minimum Lat                 -10.00                      |
|              Maximum Lon                 57.00                       |
|              Minimum Lon                 113.00                      |
|              Center Lon                  100.00                      |
|           Grid                           Grid Parameters             |
|              Lat Reference               10.00                       |
|              Lat Frequency               10.00                       |
|              Lon Reference               15.00                       |
|              Lon Frequency               10.00                       |
|                                                                      |
|______________________________________________________________________|

                        Fig 1.3  Editing screen

If the display screen is too short to display the entire command file, only a portion of the available fields will be displayed. The rest of the fields can be reached by scrolling up or down using the arrow keys. When the editing session is finished, hitting the TAB key will launch MapMaker and create the map. For a description of each field and available options, see the COMMAND FILE FIELDS section.

WARNING:
Mmedit will attempt to display any given file as a command file. If mmedit does not recognize the format of the file, i.e. if it is unable to successfully parse more than ten lines of the file, mmedit will issue a warning that the given file may not be a command file. Care should be taken when editing files since the contents of the file are written over at the conclusion of the editing session (unless the escape key is used). This means that any information contained in a file will be lost if it is inadvertently used during an mmedit interactive session. If mmedit does not recognize a file, the user should use the escape key to stop the editing session and verify the file is a command file (an appropriate text editor can be used to view the file) in order to ensure that important information will not be lost.

COMMAND FILE FIELDS

This is a brief description of each of the command file fields that appear in the edit window of mmedit.

MapMaker Version - This field is required to maintain a standard for the command file format. It insures that future versions of MapMaker will be able to process older command file formats. This field can be set to one of the following values: beta1.0 or MM1.

Dataset Name - This field allows the user to choose from a list of available datasets. Datasets are the different PDS CD-ROM products that MapMaker uses to generate maps (see MAPMAKER VERSION 2.0 INSTALLATION AND CONFIGURATION MANUAL: ADDING A DATASET). These are listed in the "mapmaker/data/dataset.idx" index file. When any new dataset is added, the "dataset.idx" file must be updated to reflect the addition. Examples of typical dataset names are:


mars_viking_bw - The black and white Digital Image Model of Mars created from information received from the Viking 1 and Viking 2 spacecraft.

venus_magellan_fmap - The full resolution maps of Venus created from information received from the Magellan spacecraft.


Scale / Resolution - This field displays either the scale or the resolution of the finished map (these fields are mutually exclusive). The UP and DOWN arrows select between the two. The SPACEBAR toggles between resolution and scale, keeping the same relative value. A new scale or resolution can be entered directly from the keyboard.

Output Pixel Type - This is the pixel type of the finished map. It can be 8 bit or 16 bit, or it can default to the system, e.g. if MapMaker is running on a 16 bit LSB system, the output map will have pixel type 16 bit LSB (provided the input data is 16 bit). There are two types of 16 bit pixel types, LSB (Least Significant Bit) used by the PC and ALPHA, and MSB (Most Significant Bit) used by SUN and Mac machines.

Resamp Method - At this time, only the nearest neighbor resampling method is implemented. The bilinear interpolation algorithm will be offered in future versions of MapMaker.

Bands - This field displays the list of image bands, delimited by commas, to be included in the finished map. MapMaker uses a numerical listing to identify bands (i.e. 1,2,3 ..etc.) but also accepts common band names if they are defined in the appropriate descriptor file (i.e. red, green, blue; see MAPMAKER VERSION 2.0 INSTALLATION AND CONFIGURATION MANUAL: ADDING A DATASET). Most datasets have only one band.

Format - This displays the output format of the finished map. They are as follows:


JPEG - the Joint Photographic Experts Group's format compresses an image in a lossy manner (i.e. some information may be lost).
GIF - CompuServe's Graphics Interchange Format allows lossless image compression.
RAW - raw image data (pixel values) without any added header or documentation.
PDS - raw image with a Planetary Data System header.
TIFF - Tagged Image File Format.
FITS - not implemented as of latest release.
ISIS - not implemented as of latest release.


Projection - MapMaker can create a map in three different projections: sinusoidal, simple cylindrical and mercator.

Stretch - This changes the density (dn) values of the output pixels. MapMaker can do this in several ways:


Min_Max - maps 1% of the image to light or dark saturation, and linearly spreads the rest of the data between the minimum and maximum pixel values.
Gaussian - maps 1% of the image to light or dark saturation, and places the rest of the data in a Gaussian curve (also called normal curve or bell curve).
Histogram Equalization - tries to create an image with a level histogram, i.e. the same number of pixels at each dn value.
Histogram Matching - this matches the image's histogram to the normal curve (see Gaussian above).
Byte Truncation - takes a 16 bit image and simply truncates the pixel values to create an 8 bit image.

There are two other stretch options in MapMaker, "NO STRETCH", which is self explanatory, and "AUTO", which performs the Min_Max stretch.


Limits - There are three ways to describe the map limits in mmedit. They are:


NSEW - give latitude and longitude values for North, South, East and West boundaries.
MinMax - give minimum and maximum latitude and longitude boundaries.
BoxArea - give center longitude and latitude, and a number of pixels for height and width (i.e. lines and samples, or rows and columns) of the end map.

Both NSEW and MinMax accept a "center lon" which is the center longitude of projection. This is only important if the "projection" is sinusoidal.


Grid - MapMaker can overlay a grid on a map. If a grid is selected, the following fields must be filled in:


Lat Reference - This will be the latitude of the first horizontal grid line.
Lat Frequency - This is the number of degrees latitude between horizontal grid lines.
Lon Reference - This will be the longitude of the first vertical grid line.
Lon Frequency - This is the number of degrees longitude between vertical grid lines.
Color - The grid will be displayed as either white or black.


Band_Sequence - Allows user to define band sequence in color RAW images. This field is optional and defaults to Sequential if not defined. The following keywords are supported:


Default_Sequence - This maps to Sequential
Interleaved_Pixel - This option is not yet supported, it will place the pixels in seqential order, e.g. RGBRGBRGBRGB....
Interleaved_Line - This places the color bands line by line, e.g.

RRRRRR...

GGGGGG...

BBBBBB...

RRRRRR...

GGGGGG...

BBBBBB...

...



Sequential - This places the bands sequentailly, e.g.

RRRRRR...

RRRRRR...

BBBBBB...

BBBBBB...

GGGGGG...

GGGGGG...

RUNNING MAPMAKER FROM THE COMMAND PROMPT

MapMaker is run from the command line one of three ways, two of which are very similar. As discussed earlier (see HOW TO RUN MAPMAKER in this document), typing "mmedit" followed by the options and the command file name at the command prompt launches MapMaker. A more direct route, bypassing mmedit, can be taken by typing "mmengine" followed by the options and the command file name. Mmengine is the coordinator that mmedit uses to manage MapMaker, and it can be accessed directly. For a full description of possible ways to run MapMaker using mmengine and it's components, read MAPMAKER APPLICATION DEVELOPMENT.

OPTIONS

This section lists some of the available options when running MapMaker from the command line, with a brief description of each. For a complete list of options, read MAPMAKER APPLICATION DEVELOPMENT: PART II: ADVANCED APPLICATION DEVELOPMENT.

-f  (filename)
This designates a command file for MapMaker's operation. In other words, the command file name that follows the -f option will be the command file that MapMaker uses to build a mosaic.


-c
Removes all files created during a run of MapMaker, leaving only the command file and the output mosaic. MapMaker creates several temporary files that are used in advanced applications. These files are removed automatically using the -c option.


-h
Creates a header file (.hdr) containing GIS information.


-i
Creates an information file (.inf) containing text information about the mosaic.


-l
Sends all output messages generated by MapMaker to a logfile (.log).


-s
Suppresses all screen messages. Does not affect the -l option, i.e. logfile is still created.


-t
Shortens the screen titles.


-v
Sends informational messages to stdout (usually the screen). This option is set by default so that MapMaker will send messages unless silenced by the -s option.

DATASETS SUPPORTED BY MAPMAKER

Currently there are several global planetary mosaics supported by MapMaker.

MARS
• Mosaicked Digital Image Model (MDIM series) including:
• Shaded Relief Digital Image Model
• Black and White Digital Image Model
• Color Digital Image Model
• Merged Digital Image Model (Merged Black and White Data with Color Data)
• Digital Terrain Model

VENUS
• Full Resolution Mosaicked Image Data

MOON
• 750 nm Digital Image Model

BUG REPORTING

If a bug is encountered while using this software, or if positive, helpful, happy suggestions come to mind, please contact one of the following people at the PDS Imaging Node:

Janet Barrett        e-mail: jbarrett@usgs.gov      phone: (520) 556-7103
Eric Eliason     e-mail: eeliason@usgs.gov    phone: (520) 556-7113

DISCLAIMER

Although this program has been used by the United States Geological Survey (USGS), no warranty, expressed or implied, is made by the USGS or the United States Government as to the accuracy and functioning of the program and related program material, nor shall the fact of the distribution constitute any such warranty, and no responsibility is assumed by the USGS in connection therewith.