MapMaker Application Development
Contents
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:
MapMaker can additionally operate as a stand-alone program. The "mmedit" interface allows a user to specify a
map to be produced by MapMaker.
Introduction to Application Development
One of MapMaker's powerful attributes is its ability to act as a cartographic work horse behind
applications that use planetary global maps organized in PDS format. In particular, MapMaker works well
behind web applications because of its relative speed and versatility. However, the learning curve for
understanding MapMaker's basic features for use in application development can be a steep one. As a result,
this manual was written to provide detailed information about MapMaker's more advanced features as they
apply to a variety of applications. It is intended as a guide for software and web page developers to aid in
application development, using MapMaker as a cartographic engine.
This document is split into three main parts. Part 1 demonstrates the basic techniques of application
development. Part 2 discusses these techniques, providing greater detail and demonstrating more
advanced techniques. Part 3 provides information for building a dataset usable by MapMaker.
Numerous examples pave the way to understand the material.
Part I: Basic Application Development
As a beginning developer of MapMaker applications, you may want to use MapMaker's simplest features, including use of default or pre-configured environments
and processing parameters. In addition, a simple application may make only one call to MapMaker for
creating a map from start to finish rather than using complicated
modular designs. Finally, you will most likely want to
tell MapMaker to remove intermediate processing files, leaving behind only input and requested output
files.
Four Steps to Application Development
Every application that uses MapMaker requires a four step process:
- Setting up the environment for MapMaker
- Creating input files that define the image to be created.
- Calling MapMaker executable modules to create the image map.
- Reading and processing output files
Step 1: Setting Up the Environment
In the simplest applications, the mminit.csh script can set up a default environment for normal operation,
just as it does for command line usage. For example, the mmedit application (a basic cmd file editor)
uses this technique. Little has to be known about the environment by the application developer.
The only requirement is that the mminit.csh script be "sourced" within a c-shell, as follows:
The drawback to this is that applications have to be configured exactly the same as MapMaker's general user
system. This may work for most applications. However, for some applications, a tailored environment is
best (see Advanced Application Development).
Step 2: Creating Input Files
For simple applications, only one input file is needed: the cmd file. The cmd file must take the form of
a text file containing keyword-field entries (also called parameters) that provide all the information needed
to make a map. The following can be used as a template:
MAPMAKER VERSION MM1
DATA_SET_NAME MARS_VIKING_BW
RESOLUTION 2
LIMITS
MINMAX
MIN_LON -180.00
MAX_LON 180.00
MIN_LAT -90.00
MAX_LAT 90.00
CENTER_LON_MM 0.00
FORMAT GIF
PROJECTION SINU
This example will create a GIF formatted image from the Mars Black and White MDIM CDs. The image produced
will be a global coverage in the Sinusoidal Equal-Area map projection at 2 pixels per degree.
By using this file as a template, you could make a variety of images by changing a few parameters. First,
by changing RESOLUTION you could increase the size of the image while still covering the same area. All
values given in resolution use pixels per degree units. You can use kilometers per pixel units by replacing
RESOLUTION with SCALE. Second, by changing FORMAT you can output an image map in the following format types:
GIF, JPEG, PDS, RAW and TIFF. ISIS cubes may be supported in future releases. Third, by changing
PROJECTION from SINU to MERC or SIMP, you can output in the Mercator or Simple Cylindrical map projection
respectively rather than Sinusoidal Equal-Area. Finally, by changing MIN_LON, MAX_LON, MIN_LAT, MAX_LAT and
CENTER_LON_MM, you could change the area of coverage.
The required elements of the cmd file are: version, dataset name, resolution, limits, and type of cartographic
limits along with its parameters. Format (defaults to JPEG in web mode and PDS in normal mode) and projection
(defaults to Sinusoidal Equal-Area) are not required but are common keywords as well. Other less common
keywords are not included in this example. Default values will be listed in the processing messages. A full
list of keywords and their usage appears in the Advanced Application
Development section of this document.
Step 3: Calling MapMaker Executable Modules
The mmengine executable should be used to create maps from the simplest applications to the most advanced
modular applications. Though there are many command line arguments that MapMaker executables accept,
the most commonly used ones are:
-f (filename)
This command line option allows the user to provide a command file name. All input and output files will use
this name with a variety of different extensions depending on the type of file. If no '-f' is
specified, the default, "noname", will be used.
-c
This option tells MapMaker to operate in clean mode. This forces MapMaker to clean up all its intermediate
work files, leaving behind only the input and requested output files.
-v, -s and -l
These options are used together to direct output messages. First, the '-v' tells MapMaker to operate in
verbose mode, sending all output messages to standard output, normally the screen. This is also the default
operation mode. Second, the '-s' tells MapMaker to operate in silent mode, the opposite of verbose mode.
This suppresses all output to the screen. Last, the '-l' option tells MapMaker to log all output to a log
file, which has a '.log' extension. This option can be used together with '-v' to duplicate output to the
log file or '-s' to redirect output to the log file.
Examples:
mmengine
In this, the simplest of examples, no command line arguments are given. As a result, MapMaker expects to find a file
called "noname.cmd" and, if the file were to take the form as shown in Step 2: Creating Input Files, it will create
a file called "noname.gif". All output messages will be sent directly to the screen and no clean-up of intermediate work
files will take place.
mmengine -f myfile
This is another simple example of a MapMaker call. This example expects a command file called "myfile.cmd" and,
if the file were to take the form shown in Step 2: Creating Input Files, it will output an image called "myfile.gif."
All output messages will be sent directly to the screen and no clean-up will take place.
mmengine -cslf myfile
In this example, the '-c' sets MapMaker to self cleaning, the '-s' sets MapMaker to silent mode, the '-l'
will send all output messages to a log file, and the '-f' sets the input and output filenames to "myfile".
As a result, using the command file, again from Step 2: Creating Input Files, an output file called "myfile.gif" will
be created along with a file named "myfile.log" which will contain all information about the process. During
the process, no output would go directly to the screen (useful for web applications). After completion, only
the cmd file and final output files will remain; all other intermediate work files will be automatically
cleaned off the system.
Step 4: Reading and Evaluating Output Files
In application development, there are two types of files one can use: communication files and output imagery.
In simple applications, the only communication that needs to take place is error checking -- to see if an
image was successfully generated. For output images, the most useful image formats, at least for web page
development, are GIF and JPEG.
For communication in a simple application, the most useful output file generated by MapMaker is the error
file. This file is generated by every MapMaker executable and is used for exit status
reporting. Upon exit, each executable writes its exit status to filename.err (where "filename" comes from
the command filename). The following convention is used:
exit status = 0 No errors, normal operation
exit status != 0 Error occurred.
When a non-zero status is returned, indicating an error, a descriptive error message follows on the next line.
Applications commonly use the error file to monitor the status of MapMaker modules. When the application is
in control, it can check the contents of the error file to determine if MapMaker was successful.
Example:
int ErrChk(char * errorname)
{
FILE * errFP; /*points to .err*/
int tmp; /*holds exit value scanned from file*/
/*Check to see errorname is a valid error file name*/
if(strlen(errorname) > 4)
{
/*Open error file*/
if(!(errFP = fopen(errorname,"r")))
{
printf("ERROR: Unable to open %s.\n",errorname);
printf("Exiting mmedit\n");
exit(0);
}
/*Scan exit status and assign to tmp*/
fscanf(errFP,"%d",&tmp);
/*Close error file*/
if(fclose(errFP) != 0)
{
printf("ERROR: Unable to close %s\n",errorname);
printf("Exiting mmedit\n");
exit(0);
}
}
/*Set tmp to 0 if errorname was not valid*/
else
tmp = 0;
return tmp;
}
This function checks the contents of filename.err and returns the error code to the calling routine.
In using output imagery, GIF and JPEG are the best output formats for use by web applications. In
HTML, these formats can be used for simple image display with a web browser. GIF or JPEG images can
be specified using the FORMAT parameter:
or
Using a CGI Perl script to output HTML in a World Wide Web application, image creation and display steps
are shown below:
system ("$MMEXEC/mmengine -f $filename");
...
print "<IMG SRC = /$mmwork/$filename.jpg BORDER = 0>"
With this simple technique, MapMaker can easily be integrated with CGI applications.
Part II: Advanced Application Development
MapMaker has advanced features to give greater control of map generation to an application.
These features include:
- A modular design that allows on-the-fly decisionmaking during map creation.
- Separate information files tailored for GIS applications, web applications, and so on.
- Allowing tailored environments for each application.
- Command file overrides on the command line.
- Allowing users or applications to provide a PDS label template for customized labels for output images in
PDS format.
- Allowing for user created datasets that act as input to MapMaker.
Four Steps to Application Development -- Revisited
Like basic application development, advanced application development also has the same basic four steps:
- Setting up the environment.
- Creating input files.
- Calling MapMaker executable modules.
- Reading and evaluating output files.
Step 1: Setting Up the Environment
MapMaker needs certain environment variables set in order for it to work properly. As described for simple
application usage, the mminit.csh script works well for defining the environment variables. Thus, to the
general MapMaker user, the mminit.csh script often appears as a "piece of magic" that makes MapMaker work.
This "magic", however, must be de-mystified for the software developer to make a tailored environment for
more advanced MapMaker applications.
To understand the system environment, its basic functions and layout must be explored. The function of the
environment is to define the location of the MapMaker executable modules, data files, CD-ROM drive, jukebox,
and so on. The layout of the environment consists of four general parts, listed individually below.
Part A: Setting Environment Variable Checksum
setenv MMCHECKSUM mapmaker
This command sets an environment variable that MapMaker evaluates to ensure the environment was properly set.
This environment variable must always take this form. If MapMaker does not find this variable or cannot
evaluate it to the keyword "mapmaker," it will exit with the following fatal error message:
---------------------------------------------------------------------------------------------
FATAL ERROR!
MapMaker has not been properly initialized. In order for MapMaker to run, it
needs certain environment variables set. These should be set by sourcing the
initialization script, mminit.csh, that can be found in MapMaker's /exec
directory. To automate the process, this can be set up in a user's .cshrc file.
----------------------------------------------------------------------------------------------
Part B: Setting Environment to Use Executable and Data Files
The next four environment variables point to the MapMaker root directory, executable directory, data
directory, and work directory, respectively:
setenv MMROOT (Path to where MapMaker is installed)
setenv MMEXEC $MMROOT/exec
setenv MMDATA $MMROOT/data
setenv MMWORK (Path to work files)
There are two optional environment variables listed above: $MMROOT and $MMWORK. $MMROOT is not actually
used internally by MapMaker, but is only used to set up $MMEXEC and $MMDATA. In addition, $MMWORK is
unique to web applications and usually is not found in the mminit.csh script. It is only used with the
'-w' option, indicating to MapMaker that a web application is using the system.
Examples:
setenv MMROOT /ThisPlace/httpd/htdocs/mapmaker
setenv MMEXEC $MMROOT/exec
setenv MMDATA $MMROOT/data
setenv MMWORK $MMROOT/work
This is a typical web page example. It assumes that MapMaker has been installed in the
"/ThisPlace/httpd/htdocs/mapmaker" path with an additional work directory added to that path. The work
directory has to have both read and write privileges to allow for web access.
setenv MMEXEC /ThisPlace/mapmaker/exec
setenv MMDATA /ThisPlace/myapp/data
In this example, the application has its own data directory with MapMaker executables in a different
directory structure. In addition, no work directory is given, meaning that it is unlikely that a web
application is being used. When using the '-w' option without defining $MMWORK, all work space
is assumed to be the current set directory where the application is executed. One might use this
example in a c-shell script application that uses its own datasets but always wishes to use the same
executables as other applications, meaning that only one MapMaker installation has to exist on the
system.
Part C: Setting Environment to Use the CD-ROM and Jukebox
Four environment variables are used to describe the CD-ROM to MapMaker. The first gives the path of
the CD-ROM drive:
setenv MMCDROM (Path to CD-ROM)
The next two provide tailored commands for mounting and unmounting CD-ROMS:
setenv MMCDMOUNT (Command to mount a CD-ROM or NONE)
setenv MMCDUMOUNT (Command to dismount a CD-ROM or NONE)
This can be a tricky operation to configure as mounting and unmounting devices often requires root
privileges. Fortunately, Solaris systems include a volume manager that automates the process. As a result,
these environment variables should be set to NONE on a Solaris system. On other UNIX platforms you may
need to use the mount and umount commands. Consult your system administrator if you need help setting
up these commands.
The last command gives the jukebox an environment variable to provide a path to MapMaker:
setenv MMJUKEBOX (Path to Jukebox)
This command, however, does not have mount or unmount commands as this operation is automated by the
jukebox software. MapMaker software has been tested on Solaris using Tracer's HyperROM software with a
Pioneer 5004RM jukebox:
The MapMaker software has not been tested using a jukebox on a Linux system. It is not guaranteed that
you will get reasonable results from MapMaker if your datasets are stored on a jukebox device.
By using tailored environment techniques, the CD-ROM and jukebox variables can be used to mount, unmount
and read image data off of devices other than CD-ROMs or jukeboxes. Examples of these include zip-disks,
optical drives, and so on. User manuals for such devices should be consulted to find out mount commands,
paths, etc. It should be noted, however, as MapMaker was designed for use with jukeboxes and CD-ROMs,
there is no guarantee that it will work with other devices.
Example:
setenv MMCDROM /cdrom
setenv MMCDMOUNT NONE
setenv MMCDUMOUNT NONE
setenv MMJUKEBOX /cdroms
This is a typical Solaris configuration setting the CD-ROM path to "/cdrom" and giving no mount and
unmount commands.
Part D: Setting a Path to the Executable Modules
In order to use MapMaker executables without providing an explicit path to them, the executable path
can be added to the $path variable as follows:
if ($?path) then
set path = ($path $MMEXEC)
else
set path=($MMEXEC)
endif
Other Types of Scripts
All the environment examples shown so far have been C-shell script examples. By using tailored
environments, other shells and script formats may be used.
Web Based CGI Perl Example:
$ENV{"MMCHECKSUM"} = "mapmaker";
$ENV{"MMEXEC"} = "/www/httpd/htdocs/mapmaker/exec";
$ENV{"MMDATA"} = "/www/httpd/htdocs/mapmaker/data";
$ENV{"MMWORK"} = "/www/httpd/htdocs/mapmaker/work";
$ENV{"MMJUKEBOX"} = "/ftp/cdroms";
$ENV{"MMCDROM"} = "/cdrom";
$ENV{"MMCDMOUNT"} = "NONE";
$ENV{"MMCDUMOUNT"} = "NONE";
In this Perl segment, a CGI sets the environment variables needed for MapMaker to operate properly.
The $path variable is not set to the executable directory, so the path to the MapMaker engine call
must be explicit:
system ("$MMEXEC/mmengine -wf $filename");
Step 2: Creating Input Files
MapMaker accepts two possible input files provided by an application: the command file and PDS label template.
The command file is required and describes to MapMaker the image map to be generated. The PDS
label template is optional and provides a template which MapMaker can use to make PDS labels. The
template is used when outputting images in the PDS format.
Command File
The Command File (cmd) contains all the information MapMaker needs to make a map, from cartographic limits
to enhancement options. It uses keyword-field parameters to specify the information that MapMaker needs.
There are required and optional keywords. The following are all the keywords MapMaker accepts:
Required Keywords
These keywords are required for MapMaker to make any map. If left out, MapMaker will issue an error message
and exit.
MAPMAKER VERSION MM1
This is required in all cmd files to provide a standard.
Future releases of MapMaker may result in changes
to the format of the cmd file. However, the older standard will still be compatible by using this line.
This will insure that little to no changes have to occur to update applications when using newer versions
of MapMaker.
DATA_SET_NAME
This holds the name of the dataset from which the image map is made. The name must appear in the dataset.idx
file located in the mapmaker/data directory or an error will result.
LIMITS
One of three methods of providing cartographic limits must be given. They are mutually
exclusive and an error will result if more than one is given. The three types of limits follow:
MINMAX
This provides cartographic limits in terms of minimum and maximum latitude and longitude. When used, MapMaker
will create the map using the following keywords:
MIN_LON -- This gives minimum longitude limit.
MAX_LON -- This gives maximum longitude limit.
MAX_LAT -- This gives maximum latitude limit.
MIN_LAT -- This gives minimum latitude limit.
CENTER_LON_MM -- This gives center longitude of projection.
NSEW
This provides the cartographic limits in terms of north, south, east and west latitude and longitude. When
used, MapMaker will create the map using the following keywords:
WEST_LON -- This gives west longitude limit.
EAST_LON -- This gives east longitude limit.
NORTH_LAT -- This gives north latitude limit.
SOUTH_LAT -- This gives south latitude limit.
CENTER_LON_NSEW -- This gives center longitude of projection.
LINE_SAMP
This provides the cartographic limits in terms of an image size in lines and samples with a center latitude
and longitude. The area of the map will be NL (number of lines) vertical by NS (number of samples)
horizontal. With this form, MapMaker will create the map using the following keywords:
NL -- This gives number of lines of the map.
NS -- This gives number of samples of the map.
CENTER_POS_LON -- This gives center longitude of the map.
CENTER_POS_LAT -- This gives center latitude of the map.
SCALE or RESOLUTION
SCALE and RESOLUTION both describe map distance in relationship to ground distance. SCALE is a floating
point number representing kilometers per pixel while RESOLUTION also is a floating point number specifying
pixels per degree. Only one or the other can be given in the cmd file. If both are given, an error
will result.
Optional Keywords
The following keywords are optional. If not provided, MapMaker uses defaults and issues a warning message.
PIXEL_TYPE
This should contain one of the following keywords to describe the output pixel type:
BIT8 -- Eight bit output.
LSB16 -- Sixteen bit data with the least significant byte first (PC).
MSB16 -- Sixteen bit data with the most significant byte first (Mac
and Sun).
DEFAULT -- Causes the output image to be created in
the format of the machine MapMaker is run on.
The following may be implemented in the future as needed but are not supported yet:
LSW32 -- Thirty-two bit data with the least significant word first.
MSW32 -- Thirty-two bit data with the most significant word first.
RESAMP_METHOD
This provides the resampling method used to make the map and may contain one of the following:
NN or NEAREST_NEIGHBOR -- Use the nearest neighbor algorithm to make maps.
Nearest neighbor is the fastest of the algorithms
but not as accurate as bilinear interpolation.
BI or BILIN_INTERP -- Use the bilinear interpolation algorithm to make
maps. It is not supported at this time and will
result in an error.
BANDS_SELECTED
This parameter specifies the selected spectral bands to include in the output image. It may contain a
list of band names or numbers delimited by commas.
FORMAT
This contains the format of the output file. It can be one of the following:
GIF -- CompuServe Graphic Interchange Format
JPEG -- Joint Photographic Experts Group format
TIFF -- Tagged Image File Format
ISIS * -- Integrated Software for Imaging Spectrometers
PDS -- Planetary Data System format
RAW -- Unlabeled raw format
* NOTE: This MapMaker release does not support this option. It will be included in future releases.
PROJECTION
This contains the map projection of the output image. It can be one of the following:
SINU -- Sinusoidal Equal-Area
SIMP -- Simple Cylindrical
MERC -- Mercator
GRID
This provides the ability to add a grid to the output image. If the keyword NONE is given, then
no grid is added. Otherwise, four floating point numbers and an integer are required. They take the
following form:
(lat ref), (lat freq), (lon ref), (lon freq), (gray value)
Lat reference is a floating point reference for latitude grid lines. It is the latitude of the first
horizontal grid line. The reference does not need to lie in the image limits and needs to be in the
range -90 to 90 degrees.
Lat frequency is the frequency of the grid lines in latitude. It is the latitudinal distance between
grid lines.
Lon reference is a floating point reference for longitude grid lines. It is the longitude of the first
vertical grid line. The reference does not need to lie in the image limits and needs to be in the range
-540 to 540 degrees.
Lon frequency is the frequency of the grid lines in longitude. It is the longitudinal
distance between grid lines.
Gray value is an integer value between 0 and the highest value possible for the output pixel type, which
is 255 for 8 bit and 65535 for 16 bit. Zero is NULL and will appear black, and the high value is
saturation and will appear white. Color data will use the same value for all bands, making a gray value
rather than a color.
Example:
GRID 0, 5, 60, 20, 255
This will make a grid using 0 latitude as the reference grid line and making lines every 5 degrees
thereafter, using 60 as the reference longitude line and making lines every 20 degrees thereafter, and
using 255 as the grid grayscale color. If this were given in the cmd file for an 8 bit RGB color image
between 25 and 45 latitude and -50 and 50 longitude, there would be white (saturated) grid lines at the
latitudes 25, 30, 35, 40 and 45 and longitudes -40, -20, 0, 20 and 40. The fact that the longitude
reference lies outside the image limits makes no difference. It still works as the theoretical reference
position.
STRETCH
This performs a contrast stretch on grayscale images. The supported keywords are as follows:
NONE -- No stretch.
AUTO -- Stretch defaults to MIN_MAX.
MIN_MAX -- A linear stretch saturating 0.5% at each end of
the histogram.
EQU -- Histogram equalization.
MATCH * -- Histogram matching
GAUSS -- Gaussian stretch.
TRUNC -- Truncation of 16 bit data to 8 bit data.
* NOTE: This "matches" to a Gaussian curve, producing a result similar to GAUSS at this time. In the
future, any histogram curve may be matched.
BAND_SEQUENCE
This allows the user to define the band order of RAW color images. The following are supported:
Default_Sequence --Maps to Sequential
Interleaved_Pixel* --Interleaves the pixels,
i.e. RGBRGBRGB...
Interleaved_Line --Interleaved by line,
i.e. RRRRRRR...
GGGGGG....
BBBBBBB...
RRRRRRR...
GGGGGG...
...
Sequential --Bands are placed sequentially,
i.e. RRRRRR...
RRRRRR...
GGGGG...
GGGGG...
BBBBBB...
BBBBBB...
* NOTE: This MapMaker release does not support this option. It will be included in future releases.
PDS Label Template
MapMaker supports the generation of PDS labeled images. Each data set requires a PDS label template
that MapMaker uses to build PDS labels for a requested image. In addition, MapMaker allows a user or
software package to supply its own template, provided it follows MapMaker's system of
"fill-in-the-blanks." The "blanks" in this case are lower case keywords preceded by a 'mm:' which
MapMaker replaces with actual PDS label information. This document will not describe the PDS label
standards. For more information consult the Planetary Science Data Dictionary [2] and other PDS
documents [3] available for download at the URL:
Listed below are all the MapMaker replaceable keywords and their associated PDS label keyword:
MAPMAKER KEYWORD PDS LABEL KEYWORD
mm:time PRODUCT_CREATION_TIME
mm:bands BANDS
mm:product_id PRODUCT_ID
mm:version DATA_SET_ID
mm:north_lat MAXIMUM_LATITUDE
mm:south_lat MINIMUM_LATITUDE
mm:west_lon EASTERNMOST_LONGITUDE
mm:east_lon WESTERNMOST_LONGITUDE
mm:center_lon CENTER_LONGITUDE
mm:center_lat CENTER_LATITUDE
mm:lines LINES
mm:last_line_pixel LINE_LAST_PIXEL
mm:samples LINE_SAMPLES
mm:last_samp_pixel SAMPLE_LAST_PIXEL
mm:resolution MAP_RESOLUTION
mm:scale MAP_SCALE
mm:line_offset LINE_PROJECTION_OFFSET
mm:sample_offset SAMPLE_PROJECTION_OFFSET
mm:radius_0 A_AXIS_RADIUS
mm:radius_90 B_AXIS_RADIUS
mm:radius_polar C_AXIS_RADIUS
mm:pixel_type SAMPLE_TYPE
mm:filters FILTER_NAME
mm:outbytes SAMPLE_BITS
mm:bitmask SAMPLE_BIT_MASK
mm:pos_lon POSITIVE_LONGITUDE_DIRECTION
mm:projection MAP_PROJECTION_TYPE
mm:record_bytes RECORD_BYTES
mm:file_records FILE_RECORDS
mm:label_records LABEL_RECORDS
mm:image ^IMAGE
To use a PDS label template, a text file containing PDS labels with some or all of the MapMaker keywords
listed above must be provided. The '-T' option can then be specified on the command line to tell
MapMaker which template to use. If the '-T' option is used, then the label template specified on the
command line will take precedence over the template that is listed in the dataset descriptor file in
the mapmaker/data directory. When using the '-T' option, the template must reside in the work directory
alongside the cmd file and have a '.pdt' extension. The MapMaker distribution comes with a set of PDS
label templates for datasets currently supported by MapMaker.
Example:
OBJECT = IMAGE
BANDS = mm:bands
BAND_STORAGE_TYPE = BAND_SEQUENTIAL
LINES = mm:lines
LINE_SAMPLES = mm:samples
SAMPLE_TYPE = mm:pixel_type
SAMPLE_BITS = mm:outbytes
SAMPLE_BIT_MASK = mm:bitmask
END_OBJECT = IMAGE
This example demonstrates what a template might look like, showing only the IMAGE object.
It should also be noted that MapMaker replaceable keywords need not be the only item in the PDS label value
field. In the Clementine example below, the PDS value field appears as
"CLEM1-L-U-5-DIM-MAPMAKERmm:version-V1.1":
DATA_SET_ID = "CLEM1-L-U-5-DIM-MAPMAKERmm:version-V1.1"
The "mm:version" appears in the middle of the field. It is only that area that would be replaced. The
final output would be:
DATA_SET_ID = "CLEM1-L-U-5-DIM-MAPMAKER2.0-V1.1"
There are three types of PDS templates that MapMaker uses. The first is the user or application defined template
as discussed above. The second type, a dataset defined template, resides in the mapmaker/data directory and
is pointed to by the des file. In general, a user or application should not have to alter or replace a dataset
defined template except when creating a new dataset from scratch (discussed in the last section of this document).
Finally, it should be noted that if neither a user defined template nor a dataset template is provided,
MapMaker will use a generic template in the data directory called "template.pdt." This also does not need
to be altered or replaced in any way.
Step 3: Calling MapMaker Executable Modules
All calls generally go through the MapMaker engine, mmengine, which evaluates command line options and passes
them on to the various modules. Each module then evaluates the command file and data files and processes
the image. In the simplest of cases, a single call to the engine will run all the modules making the
requested image. However, for more advanced applications, modules can be used one at a time, allowing the
calling application to make on-the-fly decisions about the image, re-running any module if necessary, and making
changes as needed. This type of usage is referred to as modular MapMaker usage.
MapMaker Executables
mmengine
This executable coordinates MapMaker modules into one action. In the simple case, it sequentially runs all
three modules. However, the engine can run any combination of modules, allowing for flexible modular action
and on-the-fly decisionmaking.
mm0
This module compiles a list of tiles, CDs and information about the output image. With modular usage, the
calling application can look at the information and make decisions whether or not to continue or re-run
MapMaker, making a more ideal image with respect to size and run time. This module must be run before
mm1 can be used.
mm1
This module takes the information compiled by mm0 to create an intermediate image map, one for each band
of the output image, and compiles histogram information for further processing by mm2. This module usually
will not be re-run without first re-running mm0. It must, however, be run before mm2 can be run.
mm2
This module is the finishing module that takes the intermediate images and histogram information from mm1
and performs any enhancement options and conversion to image format. In modular applications, this module
can be run over and over again, making subtle changes such as grid alterations, using different kinds of
contrast stretches, creating different types of output images, and so on.
Command Line Options
MapMaker operation is controlled through use of command line options. Command line options do not control
the actual characteristics of the output image (except when using the '-o' option listed below). They
instead control the actual operation and coordination of the MapMaker processing by indicating which
modules should be executed, which mode to execute them in, and so on. A list of all command line options
follows:
-f (filename)
This is the most common option and designates a filename for operation. Leaving out this option defaults
the filename to "noname." Use of the '.cmd' file extension is optional as shown in the examples below:
mmengine -f myfile -- These two examples will
mmengine -f myfile.cmd -- do exactly the same thing.
-012
These options tell the engine which module to execute. Option '-0' tells MapMaker to run mm0, '-1' runs
mm1, and '-2' runs mm2. Any combination can be used together (though using '-02' makes very little sense).
MapMaker runs all three steps when options are not specified. Also, order does not matter; a command line
of '-12' will perform the same action as one of '-21'.
-c
This option indicates to MapMaker that it should clean (remove intermediate work files). The files
remaining will be the input files provided to MapMaker and the requested output files from MapMaker.
One should not use this option while performing modular operations because processing files will be removed,
making it impossible to re-run modules.
-d or -D
These options are used only in debugging MapMaker. They send diagnostic messages to output. If '-d' is
used, the diagnostic messages are sent to stderr and stdout. If '-D' is used, they are sent to a file. In
practice, the general user and application developer should never use these options. They are listed here
for the sake of completeness of the documentation.
-h
This will tell MapMaker to create a hdr file during mm2 execution. The hdr file has an '.hdr' extension
and allows MapMaker images to be imported into common commercial GIS packages. It should be noted that
the hdr standard is not well maintained by all software packages. MapMaker uses only the simplest hdr
files possible to ensure the least amount of problems during importation to a GIS application. Because
of lack of standards in the hdr formats, importation to GIS applications cannot be guaranteed.
-i
This creates an info file during module mm0 execution, which contains text information about the image,
including tiles to process, image size and so on. The info file is a text file that is easily read by
users but not as easily parsed by a computer.
-l
This sends all output messages from MapMaker to a log file, a text file with a '.log' extension.
-s
This puts MapMaker into a silent operation mode, as opposed to verbose operation mode. In this mode,
all screen messages are suppressed. When used together with '-l' (log file mode), all messages are sent
to a log file rather than to the screen, an ideal situation for many applications.
-t
This outputs a shorter title screen when starting a MapMaker module. This is simply to reduce screen
or log file output while still producing a graphically pleasing system.
-T
This option indicates that the user or application will be providing a PDS template file for PDS label
creation. The PDS template file, which must have a '.pdt' extension, must contain MapMaker replaceable
keywords for PDS label generation.
-v
This puts MapMaker into a verbose mode (default operation mode), as opposed to silent operation mode.
It is still provided to insure downward compatibility with previous versions of MapMaker which did not have
verbose as the default. In verbose mode, all output messages are sent to stdout.
-w
This sets MapMaker to web mode. In this mode, MapMaker operates silently, as it would using '-s' option.
In addition, it creates a web file containing image information easily usable by a web based CGI script.
Finally, it requires that all work files, including cmd files, information files, raw work images and output
files, be found in a directory pointed to by the $MMWORK environment variable. These actions are conducive
for the web CGI environment.
-o
Overrides are a fast easy way to override parameters given in the cmd file. The field following the '-o'
should contain a list of commands to override. MapMaker operation will act as though the command appeared
in the cmd file the way it appears on the command line. The override line cannot contain any spaces.
Therefore, an equal sign is the best way to separate command and field, and colons are the best way to
separate commands. For example:
mmengine -f myfile -o format=gif:stretch=auto
This is the proper way to issue an override. In this case, MapMaker
will read the "myfile.cmd" file and override the format and stretch
parameters found therein with 'gif' and 'auto' respectively.
mmengine -f myfile -o format gif
This is illegal because the format command and its field, gif,
are separated by a space.
mmengine -f myfile -o format=gif stretch=auto
This is illegal because format and stretch commands are
delimited by a space.
All operating systems have a command line size limit varying from system to system. Any command line
exceeding this size usually gives undesirable results (the most common being truncation). As a result,
in the MapMaker system, overrides are not a preferred way of passing cmd file parameters. Overrides are
simply a way to "override" cmd file parameters and should not be used to act as a cmd file.
This option is most commonly used in modular applications where a web browse image, similar to the final
image, needs to be created. In this type of usage, mm2 could be run several times, making subtle changes
to the output image.
Command Line Examples
mmengine -Thilcf myfile
This example runs all three modules of MapMaker. The cmd file expected is "myfile.cmd." In addition,
as a result of the '-Thilc' options, it expects a PDS label template file named "myfile.pdt," creates a
hdr file for GIS applications named "myfile.hdr", creates an info file about the image named "myfile.inf,"
logs all the output messages to a log file called "myfile.log" while still outputting the same messages
to the screen, and cleans all the work files after operation.
Modular Command Line Examples
In the modular example shown below, it is assumed that a web CGI is calling MapMaker. Each processing
step is taken individually to make decisions on-the-fly about the image. The last step is run twice
-- once to make a GIF formatted browse image, one of the formats that web applications can display,
and once to make the final output image for download.
mmengine -0wlf myfile
This modular example runs only the mm0 module of MapMaker. The '-w' option specifies web mode, forcing
it to be silent (similar to using a '-s') and outputting a web information file called "myfile.web." Also
in web mode, the cmd file, work files and final output images are placed in a directory pointed to by the
$MMWORK environment variable. In addition, the '-l' logs all output messages to a log file called
"myfile.log."
With these options, a web CGI application can read the web file containing vital information about the
output image to be created. This allows the CGI to decide whether or not to continue or abort due to
excessive image size or processing time. If it decides to continue, it can then employ the next step
as shown below. If not, it can re-run this example until a suitable image is created. Using this
technique, no further processing needs to take place if the image attempt is abortive, saving valuable
time and space in real time web applications.
mmengine -1wlf myfile
This example runs the next module, mm1, in succession to the previous example's module, mm0. It processes
all the tiles into work images while still using web mode and logging all output messages to the same log
file. Generally, this is the most time consuming step. Once this step has been finished the next two
examples can run module mm2.
mmengine -2wlf myfile -o format=gif:stretch=auto
This next example takes the work images created by module mm1 and creates an output image. By using the
'-o' option to override the cmd file, it creates a GIF formatted image with an auto stretch, overriding
what is indicated in the cmd file. This is often used this way to make a browse image for web applications
so that a user can preview the image before creating the final image. The next example could be employed
to make the final image.
mmengine -2wlf myfile
This example creates the exact image indicated by the cmd file. Upon completion, information about every
processing step is outputted to the log file.
By using these modular steps to process the image, decisions about whether to continue or abort are made by
pausing after mm0 for evaluation. Next, mm1 creates the work images in preparation for mm2. Finally,
successive runs of mm2 make subtle variations of the image for browsing before final image processing.
This is one of the most common modular applications but by no means the only one.
Step 4: Reading and Evaluating Output Files
MapMaker performs communication between various modules and the calling application by using files.
In doing this, a large number of files can accumulate in the work area.
In the simplest case, only a small set of files need to be evaluated by the calling application. For
these cases, a clean option ('-c') should be employed to automatically remove unneeded work files at the
completion of MapMaker. In more advanced modular usage, however, other files may also need to be evaluated
to make on-the-fly decisionmaking. In either case, some file clean up is required by the calling
application.
Files Created or Written to by All Executables
filename.log
A log file created when using the '-l' option. It contains a log of all output messages. These are the
same messages sent to the screen when using verbose mode ('-v'). The following is an example:
------------------------------------------------------------
Welcome to MapMaker Version v2.0
Module: Coordinator Engine(mmengine)
Command Line: mmengine -lf thisfile
Description:
This engine coordinates all three modules into one action.
------------------------------------------------------------
------------------------------------------------------------
Start MapMaker Version v2.0, Module: CD and File Locator
------------------------------------------------------------
Stack Locator List:
PUSH FILE:/mexxxxxx/me00n045.img|W 9.0|E 0.0|N 7.5|S -7.5|
PUSH CD: Volume vo_2001
------------------------------------------------------------
End MapMaker Version v2.0, Module: CD and File Locator
------------------------------------------------------------
------------------------------------------------------------
Start MapMaker Version v2.0, Module: Ist Pass(mm1)
------------------------------------------------------------
Processing Tiles:
Simulating CD Volume vo_2001 from hard drive.
TILE:/mexxxxxx/me00n045.img|W 9.0|E 0.0|N 7.5|S -7.5|
------------------------------------------------------------
End MapMaker Version v2.0, Module: Ist Pass(mm1)
------------------------------------------------------------
------------------------------------------------------------
Start MapMaker Version v2.0, Module: IInd Pass(mm2)
------------------------------------------------------------
Preparing tasks for image processing.
Output image stats: Width(ns): 162, Height(nl): 160
Format: JPEG
Performing image creation pass.
------------------------------------------------------------
FATAL ERROR!
MapMaker could not open the './thisfile.jpg' file for write.
This file is the final output image built by MapMaker. Either
the protection or ownership of this file prevents it from being
written over, or the protection of the working directory prevents
MapMaker from writing to it.
------------------------------------------------------------
------------------------------------------------------------
The mm2 module terminated with an error! The mmengine module must abort.
------------------------------------------------------------
In this example, the log file holds information about a MapMaker run. By looking at the log file it can
be seen that modules mm0 and mm1 both run well but mm2 was prematurely terminated with an error.
filename.cln
This is a clean file that is only used when invoking the '-c' option. It contains a list of all unneeded
files for MapMaker to remove after operation. It is only used in the internal operation on MapMaker.
This is one of the files that MapMaker cleans when using the '-c' option.
filename.err
The error file is always created by MapMaker and holds error information about a MapMaker run. If an
error occurs, a non-zero value is reported on the first line. On the second line, FORCED, MESSAGE or
PROMPT will appear depending upon the error type. The third and fourth lines will hold information used
internally to MapMaker, the remainder will be a message stating the nature of the error. If no error
occurs, only 0 will be placed in the file as the ID.
The following is an example of an error file:
527
FORCED
CMDPARAM
FILE_OPEN
MapMaker could not open the './thisfile.cmd' file for
read. This file must reside in the working directory.
Its name is passed in with the '-f' parameter. Check to
make sure the file exists and that the protection and
ownership is such that MapMaker can use it.
In this example, the error code is 527 and the type is FORCED. CMDPARAM and FILE_OPEN are for internal MapMaker
use and a lengthy message describes the error.
Files Created by mmengine
filename.DCO
This is a diagnostic file that MapMaker creates when using the '-d' option. It contains debugging information
and is listed here only for completeness of the documentation.
Files Created by mm0
filename.stk
This stack file contains a stacked, binary list of tiles and CDs for processing. It is used only in the internal
operation of MapMaker. This file is cleaned when using the '-c' option.
filename.inf
The info file, created by invoking the '-i' option, contains information about the output image readable by a user.
It contains the following headings:
- "File Data" describes the output file including name, size and format.
- "Cartographic Data" contains all relevant cartographic information including limits, type of projection and map
distance in relation to ground distance.
- "Image Data" contains information such as size, x and y dimensions, center of the image and pixel type.
- "Enhancements" lists enhancement options such as stretch type.
- "Dataset Data" lists information about the tiles processed including the number of tiles and CDs processed
and list of tile and CD names.
An example of an information file follows:
INFORMATION FILE
****************************
FILE DATA
--------------------
Filename = all.gif
Filesize = 2332800 bytes
Format = GIF
CARTOGRAPHIC DATA
--------------------
North Latitude = 90.0000
South Latitude = -90.0000
East Longitude = -180.0000
West Longitude = 180.0000
Center Longitude of Projection = 0.0000
Projection = Sinusoidal
Resolution = 6.0000
Scale = 9.8710
IMAGE DATA
--------------------
Pixels = 2332800
Lines = 1080
Samples = 2160
Image Center = 0.0000 Lon, 0.0000 Lat
Pixel Type = 8 bit
ENHANCEMENTS
--------------------
Stretch = histogram matching
DATASET DATA
--------------------
Dataset name = mdim.des
Number of CDs = 1
Number of tiles = 2
CDs and tiles used:
vo_2001
/mexxxxxx/me68s225.img
/mexxxxxx/me00n225.img
filename.web
This is the web information file, created by using the '-w' option. This contains text information about
the created image easily used by web pages in a parseable text format, in the order:
number of lines
number of samples
north latitude
south latitude
east longitude
west longitude
It can be easily parsed by a CGI Perl script by using the following lines:
open(WEBFILE, "$WBPATH.web");
read(WEBFILE, $WF, 80);
close(WEBFILE);
($line,$samp,$nlat,$slat,$elon,$wlon) = split(/\n/, $WF);
In this example, a Perl script opens the web file at $WBPATH, reads the file into $WF, closes the file,
and splits the information in $WF by '\n' into $line, $samp, $nlat, $slat, $elon and $wlon. Those variables
are then usable for decisionmaking in the rest of the script.
filename.DCD
This is a diagnostic file that MapMaker creates when using the '-d' option. It holds debugging information
and is listed here only for completeness of this documentation.
Files Created by mm1
filename.tm0 filename.tm1 filename.tm2 ...
These files are temporary raw work image files -- one for each band -- that MapMaker creates from data set
input files. These are only used in the internal operation of MapMaker and are cleaned when invoking the
'-c' option.
filename.hi0 filename.hi1 filename.hi2 ...
These are histogram files -- also one for each band -- containing information relative to the corresponding
temporary raw work files listed above. These are only used in the internal operation of MapMaker and are
cleaned when invoking the '-c' option.
filename.DIS
This is a diagnostic file that MapMaker creates when using the '-d' option. It holds debugging information
and is listed here only for completeness of this documentation.
Files Created by mm2
nrows 400
ncols 400
totalrowbytes 400
ulxmap 100.125 Longitude (positive west direction)
ulymap 50.125 Latitude
xdim 0.250000
ydim 0.250000
filename.pds filename.raw filename.gif filename.jpg
filename.tif
The list shown above indicates the output images that can be created by MapMaker. They are Planetary
Data System, unlabeled raw, CompuServe Graphics Interchange Format, Joint Photographic Experts Group,
and Tagged Image File formats respectively.
filename.cub
This is a future output file created by MapMaker. At this time, it is not implemented.
This is the Integrated Software for Imaging Spectrometers format.
filename.DII
This is a diagnostic file that MapMaker creates when using the '-d' option. It hold debugging information
and is listed here only for completeness of this documentation
Part III: Building a Dataset
Building a cartographic dataset from remote sensing imagery is a difficult, time-consuming task that is
beyond the scope of this document. Digital cartographic techniques are described in [4], [6], [7], [9].
Before MapMaker can use these data, they must conform to several specific MapMaker rules. Demonstrating
these rules is the subject of this section.
In creating a dataset, first, the image data must conform to certain key characteristics. In addition,
a six part hierarchical data structure must be built using three types of files. If employed properly, a
useable dataset results.
A dataset must adhere to the following requirements:
- Sinusoidal Equal-Area projected.
- Attached PDS labels.
- Uncompressed.
- Eight or sixteen bit integer samples.
- At least one loc file.
- A des file.
- An entry in the "dataset.idx" file.
Creating Input Tiles
MapMaker input images generally use a tiling scheme to represent a contiguous area on the planet.
A tile typically makes up between 2 to 10 degrees latitude and longitude sections of the planet and ranges
from 500 to 3000 pixels in width and length. There are, however, rare cases when a "tile" represents the
entire globe. Nevertheless, it should be noted that exceeding these specifications will cause MapMaker to
operate much slower. Also, each tile should overlap just slightly to prevent seams of uncovered area along
tile boundaries. In addition, all tiles must adhere to the requirements outlined in the following section:
Sinusoidal Equal-Area Projection
The following is an excerpt reproduced from [5]. Though written about the Mars MDIM and DTM datasets,
it applies to all MapMaker compliant datasets:
In [the Sinusoidal Equal-Area] projection, parallels of latitude are straight lines, with constant
distances between equal latitude intervals. Lines of constant longitude on either side of the projection
meridian are curved since longitude intervals decrease with the cosine of latitude to account for their
convergence toward the poles. This projection offers a number of advantages for storing and managing global
digital data; in particular, it is computationally simple, and data are stored in a compact form.
For these reasons, MapMaker input tiles must be in the Sinusoidal Equal-Area projection.
PDS Labels
MapMaker supports NASA produced cartographic products in PDS format. PDS label standards can be found
in the Planetary Science Data Dictionary [2] and other PDS documents [3] available for download at:
Compression
All input files must be uncompressed. So MapMaker can operate optimally, the designers of MapMaker make
processing time and speed a priority over input tile storage space.
Sample Size
MapMaker supports 8 and 16 bit sampled images. The internals to MapMaker, however, have been designed in
such a way that if 32 bit image technology becomes a standard it can be easily implemented in future
releases. In addition, when using 16 bit images, MapMaker supports both MSB (most significant byte first)
and LSB (least significant byte first) sample types.
Creating Data Files
Some issues must be explored to understand how data files are created. First, to create data files one
must understand the data hierarchy that MapMaker uses to find individual pieces of information needed to
process an input tile. Once understood, the actual data files can be created for a dataset.
Six Level Data Hierarchy
MapMaker uses a six level data pyramid hierarchy to store information about a dataset.
The hierarchy organizes all the information from general to specific so that MapMaker can access the
information it needs. At the top level, the "dataset.idx" contains a list of all the datasets that
MapMaker recognizes. Second, the des file contains all information about a single dataset as a whole.
Third, two lines in the des file list all the loc files for that dataset. Fourth, each individual loc
file contains information about all the tiles at one resolution for that dataset. Fifth, each line in
the loc files holds all the information about an individual input image. Finally, each line in the loc
file has individual fields with individual pieces of information that MapMaker needs to process the tiles.
Working backwards through the hierarchy, data files can be created -- first, loc files, and second, the
des file. Once the data files are created, the dataset can be added to the dataset.idx, finishing the
process.
All Data Sets 1 dataset.idx
One Data Set -2- des file
All Input Tiles for Data Set --3-- all loc files
Tiles at One Resolution ---4--- one loc file
One Input Tile ----5---- loc file line
Pieces of Tile Information -----6----- loc file fields
Loc Files
At the foundation of the hierarchical data structure, a series of files provides information at the tile
level. These files are called loc files, named for the '.loc' extension (loc stands for "locator" in that
the files are used to locate tiles). Loc files represent a good portion of the data hierarchy, as seen
below.
Starting at level six of the hierarchy, fourteen attributes are listed about an input image. These are:
- Input File Path on CD
- North Latitude Limit
- South Latitude Limit
- West Longitude Limit
- East Longitude Limit
- Center Longitude
- Number of Lines
- Number of Samples
- Map Resolution
- CD Name
- X Projection Offset
- Y Projection Offset
- Map Scale
- Bands in Input File
At level five, the attributes are organized as one unit in a loc file record in the same order as above.
An example follows (though shown on three lines here because of document line constraints, in actuality,
in the loc file, it would only appear on one line):
"/MG88NXXX/MG88N135.IMG" 90.00000 87.50000 180.00000
89.73051 135.00000 160 252 64 "VO_2001" 5760.00000
125.62400 0.92541 (1) [CR][LF]
In this example, some non-intuitive loc file line issues can be explored. Most fields are quite intuitive
and, in fact, can be extracted directly from the PDS labels for the image. The few non-intuitive points
are discussed below.
The first non-intuitive point is an issue with upper and lower case. On UNIX systems, all the filenames
on CDs appear in lower case. For instance, the input filename for this example is "mg88n135.img" which lies
nested one directory down on the CD. The directory is "mg88nxxx" and the CD name is "vo_2001." However,
it should be noted that on the loc file line, the filenames and CD names appear in upper case. The reason
for this is that originally these entries were produced on a VAX system. The VAX is not case sensitive
and filenames appear in upper case. This convention has carried over, and in MapMaker, all file names
and paths from loc files are internally converted to lower case before using them.
Second, the last field, "Bands in Input File," is not intuitive. The field lists all the bands as they
appear in the input file. In this example, only one band, the first band of the data set, appears in the
input file. In other examples, a different number might appear, indicating that a different band lies in
the file. For future releases, several bands can appear delimited by commas. For example, "(1,2,3)" would
indicate that first, second and third bands appear in the input file. This is not completely implemented
at this time but will be for the multi-banded Clementine release.
Finally, the last characters on the line are ASCII values for carriage return (13 or 0x0D) and line feed
(10 or 0x0A). On some machines, such as Suns, only a line feed is required to indicate a new line. On
other machines, such as Macs, only a carriage return is required. On others, such as PCs, both are required.
In order to cover all possibilities, MapMaker uses the PC standard. This will produce odd, out of place
characters at the beginning or end of the line on machines that only require one or the other. MapMaker
has taken this into account and will always parse the line correctly, regardless of what machine it runs
on, so long as both ASCII values appear.
At level four of the hierarchy, all lines at one resolution are compiled into a single loc file as one unit.
Though resolution appears as a field on a loc file line, all should be the same in the file:
RESOLUTION
\/
"/MG88NXXX/MG88N135.IMG" ... 160 252 64 "VO_2001" ...
"/MG88NXXX/MG88N045.IMG" ... 160 252 64 "VO_2001" ...
"/MG88NXXX/MG88N315.IMG" ... 160 252 64 "VO_2001" ...
"/MG88NXXX/MG88N225.IMG" ... 160 252 64 "VO_2001" ...
"/MG85NXXX/MG85N160.IMG" ... 320 336 64 "VO_2001" ...
"/MG85NXXX/MG85N120.IMG" ... 320 336 64 "VO_2001" ...
At level three, all of the loc files for a dataset represent the entire set of input files that make up the dataset:
-rwxr--r-- 1 user group 1547 Aug 1 16:07 mdim16.loc
-rwxr--r-- 1 user group 254163 Aug 1 16:07 mdim64.loc
-rwxr--r-- 1 user group 260847 Aug 1 16:07 mdim256.loc
In this example, the Mars MDIM dataset is represented by three loc files: one for 16 pixels per degree, one
for 64 pixels per degree and one for 256 pixels per degree. These are listed in the des file, as shown below.
The Des File
The des file, at the level two hierarchical position, contains information about the dataset as a whole,
including planetary information, pointers to label templates, pointers to loc files, band names, etc. Des
files are named for the '.des' extension (des stands for "description" or "descriptor," in that they "describe"
the dataset). Like many MapMaker data files, this file also contains a series of keyword-field parameters
containing the information. A full list of these follows:
INSTALLED_ON
This keyword is used by MapMaker to indicate where to find input images. It varies slightly in usage depending
on which of the four field keywords are being used: JUKEBOX, CDROM, HARDDRIVE, or HARDDRIVECD. First, when
using the JUKEBOX keyword, MapMaker assumes that the input images are on CD-ROMs installed in a jukebox.
MapMaker uses the $MMJUKEBOX environment variable to find the CD-ROM volume names to use as the root for each CD.
Second, if using the CDROM keyword, MapMaker assumes that input images are on CD-ROMs that will need to be
mounted on the CD-ROM drive, one at a time, as requested by MapMaker. The $MMCDROM environment variable
points to the CD-ROM directory. Finally, HARDDRIVE and HARDDRIVECD are very similar. Both the HARDDRIVE and
HARDDRIVECD keywords give a pathname to a location on a hard drive where the input images can be found. The only
difference between HARDDRIVE and HARDDRIVECD is that the HARDDRIVECD pathname points to a directory containing an
exact copy of a CD (starting with the CD volume name) and the HARDDRIVE pathname points to a directory containing
the input images (without the CD directory structure).
Examples:
INSTALLED_ON CDROM -- Mount CDs on the CD-ROM drive, issuing mount requests.
INSTALLED_ON JUKEBOX -- Mount CDs on the Jukebox. CD mounting is automated.
INSTALLED_ON HARDDRIVECD "/mars/" -- Look in the "/mars/" directory for a copy of the CD.
INSTALLED_ON HARDDRIVE "/mars/" -- Look in the "/mars/" directory for input images.
BAND_NAMES and NUM_OF_BANDS
These two keywords together describe the spectral band layout. NUM_OF_BANDS holds the number of bands in
the dataset, while BAND_NAMES gives specific information about the bands.
BAND_NAMES has a series of records with a variable number of fields. In every record, the first field
is always band number. The following fields list all the possible names that can be used with the
BANDS_SELECTED keyword in the cmd file, delimited by commas. The first name should always be the one that
can appear in PDS labels under FILTER_NAME. In addition, record by record, band numbers must be listed
in ascending order or an error message will be issued. Finally, if the dataset only contains one band,
BAND_NAMES can be omitted entirely:
Examples:
BAND_NAMES 1 red,r
2 synthetic_green,green,grn,g
3 violet,blue,b,vio
NUM_OF_BANDS 3
This example has three bands: red, green and blue. Only the names "RED," "SYNTHETIC_GREEN," and "VIOLET."
will appear in PDS labels when using the "mm:filters" option. However, in the cmd file, any of the names or
band numbers listed can be used with the BANDS_SELECTED keyword. If the BAND_NAMES keyword is omitted from
the des file, only band numbers from 1 to NUM_OF_BANDS can be used.
NUM_OF_BANDS 1
In this example, the dataset only has one band. No names appear. The result: only '1' can be used
in the BANDS_SELECTED field of the cmd file.
LOC_FILE and RESOLUTIONS
These two keywords organize the level three data hierarchy. LOC_FILE lists all the loc files from lowest to
highest resolution. RESOLUTIONS lists all the associated resolutions. For both keywords, all fields are
delimited by commas.
Example:
| LOC_FILE | "mdim16.loc" , | "mdim64.loc" , | "mdim256.loc"
| | RESOLUTIONS | 16, | 64, | 256
|
In this example from the Mars MDIM dataset, three loc files are listed for 16, 64 and 256 pixels per degree,
respectively. All these together organize the level three data hierarchy for the MDIM dataset.
RADIUS
This keyword has three fields: equatorial radius at 0 degrees, equatorial radius at 90 degrees, and polar
radius.
Example:
| ! | 0 degrees | 90 degrees | Polar
| | RADIUS | 3393.4, | 3393.4, | 3375.73
|
OFFSET_ADJ_MULT and OFFSET_ADJ_ADD
Because of inconsistencies in the way projection offsets are listed for different datasets, MapMaker provides
a way of adjusting them to what it prefers. There are two types of adjustments: additive and
multiplicative. In addition to integers, NONE can be used with either keyword. Setting the OFFSET_ADJ_MULT
keyword to NONE is equivalent to setting it to 1. Setting the OFFSET_ADJ_ADD keyword to NONE is equivalent to
setting it to 0. The two keywords are used internally as follows:
AdjustedOffset = OffsetAdjustAdd + (OffsetAdjustMult * UnadjustedOffset)
Note: Order of operations is very important. The multiplicative adjustment must be applied before the
additive adjustment.
Examples:
OFFSET_ADJ_MULT -1
OFFSET_ADJ_ADD 1
This example is what one might see in des files for the Clementine or Venus F-Map data sets. The projection
offsets are adjusted in both additive and multiplicative ways. Using the equation above one would have:
AdjustedOffset = 1 + (-1 * UnadjustedOffset)
OFFSET_ADJ_MULT -1
OFFSET_ADJ_ADD NONE
This example is what one might see in the vast variety of Mars Viking datasets, such as MDIM, DTM and
Shaded Relief. Here, only a multiplicative adjustment is used. The additive adjustment of NONE is equivalent
to 0. Using the equation above one would have:
AdjustedOffset = 0 + (-1 * UnadjustedOffset)
POS_LON
This keyword contains the cartographic positive longitude direction for the dataset. It can contain one of
the following: EAST or WEST.
PIXEL_TYPE
This contains the input tile pixel type. It may be one of the following keywords: BIT8, MSB16, or LSB16.
Thirty-two bit types may be supported in the future as needed.
PDS_TEMPLATE
This contains a PDS label template filename for this dataset. If omitted it will use the generic template,
"template.pdt," found in the data directory, in its place.
Des File Example
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! KEYWORDS THAT NEED TO BE CONFIGURED BEFORE USING DATASET !
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
INSTALLED_ON HARDDRIVE "/mars/color_mdim/"
BAND_NAMES 1 red, r
2 synthetic_green, green, grn, g
3 violet, blue, b, vio
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! KEYWORDS THAT DO NOT NEED TO BE CONFIGURED !
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
NUM_OF_BANDS 3
LOC_FILE "merged.loc"
RESOLUTIONS 64
RADIUS 3393.4, 3393.4, 3375.73
OFFSET_ADJ_MULT -1
OFFSET_ADJ_ADD none
POS_LON WEST
PIXEL_TYPE BIT8
PDS_TEMPLATE "merged.pdt"
The Dataset Index File
At the very top of the hierarchy, the "dataset.idx" file organizes all the datasets useable by MapMaker.
Just like the other data files, it is found in the data directory. It organizes the datasets by
maintaining the following information about each one: data set name, des file name, and a brief description.
Data set name is the name that can be used in the cmd file with the DATA_SET_NAME keyword. The naming
convention used is planet_mission_dataset. The des file is the name of the associated des file as it
appears in the data directory. The brief description is a one line sentence that describes the dataset.
When adding a new dataset, the file should be edited adding a new line with the information listed above.
The following is an example of a "dataset.idx" file:
mars_viking_sr sr.des "mars black and white basemap"
mars_viking_bw mdim.des "mars black and white basemap"
mars_viking_color color.des "mars color basemaps"
mars_viking_merged merged.des "mars merged color basemap"
mars_viking_dtm dtm.des "mars digital terrain model"
venus_magellan_fmap fmap.des "venus full resolution map"
moon_clementine_bw clem.des "moon black and white basemap"
As shown above, there are several important key points to creating a dataset. The data must adhere to
required characteristics. Once converted, hierarchical data files can be created.
If these two parts are properly implemented, then a usable dataset should result.
References
[1] ESRI. 1994. "Image Integration." ArcScan and Image Integration. pp65 - 73. Redlands: Environmental
Systems Research Institute, Inc.
[2] JPL. 1996. Planetary Data System Data Dictionary. JPL D-7116. Rev D. Pasadena: Jet Propulsion
Laboratories.
[3] JPL. 1992, Planetary Data System Standards Reference. JPL Document D-7669. Pasadena: Jet Propulsion
Laboratories.
[4] Batson, R. M. 1987. "Digital Cartography of the Planets: New Methods, Its Status, and Its Future."
Photogrammetric Engineering and Remote Sensing, Vol. 53, No. 9, pp. 1211-1218.
[5] Batson, R.M. and Eliason, E. M. 1995. "Digital Maps of Mars." Photogrammetric Engineering and Remote
Sensing, Vol. 61, No. 12, pp.1499-1507.
[6] Edwards, E. 1997. "Geometric Processing of Digital Images of the Planets." Photogrammetric Engineering
and Remote Sensing, Vol. 53, No 9, pp 1219-1222.
[7] Eliason, E. M., Batson, R. M. and Manley, A. 1991. Mars Mosaicked Digital Image Model (MDIM) and Digital
Terrain Model (DTM). Flagstaff: Branch of Astrogeology, United States Geological Survey
[8] Eliason, E. M., LaVoie, S. K., Soderblom, L. A. 1996. "The Imaging Node at the Planetary Data System."
Planet Space Sci. Vol. 44, No. 1, pp23-37.
[9] Syder, J.P. 1982. "Map Projections Used by the U.S. Geological Survey." Geological Survey Bulletin 1532,
U.S. Government Printing Office, 313 p.
[10] Primary Authors; McEwen, A., Robinson M., Eliason, E., Isbell, C., Lee, E., Becker, T. 1997. Clementine
Basemap Mosaic, NASA and PDS Volumes CL_3001 through CL_3015 distributed by the Planetary Data System.
Last modified November 1, 2000.