MapMaker Version 2.0 Installation and Configuration 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 "PDS Map-A-Planet".

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

• SYSTEM REQUIREMENTS : Details hardware required to support MapMaker software.
• INSTALLATION : Explains how to uncompress and set up the MapMaker directory structure.
• INITIAL CONFIGURATION : Explains how to properly configure the environment variables in the mminit.csh file.
• ADDING A DATASET : Shows steps necessary to make a new dataset available to an existing installation of MapMaker.
• BUG REPORTING : What to do if you discover a bug.
• DISCLAIMER : Legal warranty information.

SYSTEM REQUIREMENTS

MapMaker was developed and tested on a two 90Mhz processor Sun Sparc20 platform running Solaris 2.5.1 operating system. It has also been ported to a PC workstation running RedHat Linux version 6.1.

INSTALLATION

Uncompressing and Extracting

MapMaker 2.0 is distributed as a compressed tar file and must be uncompressed and extracted in the directory where it will reside. The following steps will install MapMaker:

     Step 1: Move the compressed tar file to where MapMaker will reside.
     Step 2: Uncompress MapMaker with the command appropriate to your operating system:

             SUN/Solaris:  uncompress MM2_0.solaris.tar.Z
             PC/Linux:     uncompress MM2_0.redhat.tar.Z

     Step 3: Extract MapMaker with the command appropriate to your operating system:

             SUN/Solaris:  tar -xvf MM2_0.solaris.tar
             PC/Linux:     tar -xvf MM2_0.redhat.tar

	mapmaker ---+-------  exec-------------+---- mmengine
			      |		       |---- mm0
			      |		       |---- mm1
			      |		       |---- mm2
			      |		       |---- mmedit
			      |		       |---- editcmd
			      |		       \---- mminit.csh
			      |		         
			      data ------------+---- dataset.idx
 			      |	               |---- locator files
			      |                |---- descriptor files
			      |                |---- PDS skeleton files
			      |                |---- template.pdt
			      |                \---- template.cmd
			      |
			      \----- docs -----\---- HTML docs 

INITIAL CONFIGURATION

After installation, the MapMaker environment variables must be properly configured. These environment variables are contained in the script mminit.csh (absolute path = /pathname/mapmaker/exec/mminit.csh where pathname is the directory that MapMaker was installed in). The following steps will set up the environment variables correctly:

Step 1: Locate the following section in the mminit.csh script:


setenv MMROOT /pathname/mapmaker



Change the area marked /pathname to reflect the absolute path where you installed the mapmaker directory. This variable allows MapMaker to access the files and executables to create a map.

Example: If MapMaker is installed in the following directory: /work2/test/user/, the configured script should read:



setenv MMROOT /work2/test/user/mapmaker



If your system will be accessing data sets using a jukebox, perform Step 2. If your system will be accessing data sets using a CD-ROM drive, perform Step 3. If the dataset will be saved to disk, see Step 3 of ADDING A DATASET.

JUKEBOX NOTE: MapMaker is written to use a jukebox running under a Hierarchical Management System (HMS). In this system, CD-ROMs are automatically mounted. If the user's jukebox is running under a system other than HMS, the following instructions may not provide access to the dataset CDs. The Linux version of MapMaker has not been tested with a jukebox device. There is no guarantee that you will be able to access a jukebox device using the Linux version of MapMaker.

Step 2: If data sets are located on a jukebox, find the following section of script:



setenv MMJUKEBOX /ftp/cdroms



Change the area marked /ftp/cdroms to reflect the absolute path where the jukebox is installed.

Example: If the jukebox can be found at /work2/local/jukebox, the configured script should read:



setenv MMJUKEBOX /work2/local/jukebox


Step 3: If data sets are accessed using a CD-ROM drive, locate the following section of script:


setenv MMCDROM /cdrom1



Change the area marked /cdrom1 to reflect the absolute path where the CD-ROM is mounted.

Example: If the CD-ROM can be found at /work2/local/cdrom, the configured script should read:



setenv MMCDROM /work2/local/cdrom



Environment variables have been provided to hold the mount and unmount commands for CD-ROM use. To set these variables, locate the following sections of script:



setenv MMCDMOUNT (Command to mount a CD)

setenv MMCDUMOUNT (Command to unmount a CD)



Change the area marked (Command to mount a CD) to the UNIX command required to mount a CD, and change the area marked (Command to unmount a CD) to the UNIX command required to unmount a CD. If the command to perform either action contains spaces, double quotes can be use to delineate the command. If your systems do not require mount and unmount commands, then change (Command to mount a CD) to NONE and change (Command to unmount a CD) to NONE.

Example: If the command to mount a CD-ROM is cdmount hsfs 1, the configured script should read:



setenv MMCDMOUNT "cdmount hsfs 1"


Example: If the command to unmount a CD-ROM is /usgs/local/bin/cdumount 1, the configured script should read:


setenv MMCDUMOUNT "/usgs/local/bin/cdumount 1"


Example: If your system does not require mount/unmount commands, the configured script should read:


setenv MMCDMOUNT NONE
setenv MMCDUMOUNT NONE

Once these changes have been made, MapMaker has been configured to work on the system. To use the configured environment, the mminit.csh script must be initialized every time a new user session is started. The UNIX "source" command accomplishes this (see MAPMAKER BASIC USERS MANUAL: HOW TO RUN MAPMAKER).

Example: The following command line will initialize the mminit.csh script:

source mminit.csh

ADDING A DATASET

Current Data Sets

To set up a dataset for MapMaker, the associated datafiles must be in place. MapMaker datafiles come in sets comprised of a descriptor file, its associated locator files, and a PDS skeleton file. These files reside in the mapmaker/data/ directory. The MapMaker installation package contains datafiles for several data sets. The actual cartographic data resides on CD-ROM sets that must be obtained, installed, and configured for MapMaker to use them. For information on obtaining dataset CD-ROMs, see "Where To Get a New Dataset" at the end of this section. Where and how CD-ROMs are installed is system dependent, whether accessed individually by a CD-ROM drive, installed on a jukebox, or saved directly to the hard drive, and is not within the scope of this document. To configure a system so that MapMaker can access the dataset CD-ROMs, see the INITIAL CONFIGURATION section earlier in this document. The following datasets' datafiles come with the MapMaker configuration package:

• Mars Black and White Digital Mosaic
• Mars Shaded Relief Mosaic
• Mars Digital Terrain Model Maps
• Venus Full Resolution Maps
• Lunar Global Basemap Mosaic

Descriptor File

The descriptor file has the dataset name as a filename with a ".des" extension. This file contains information about the dataset as a whole, including planetary information, pointers to label templates, and pointers to locator files.

Locator File

The locator file has the dataset name followed by the resolution as a filename with a ".loc" extension. The locator file contains a complete listing of the available images of a particular resolution and bandwidth. Each listing contains information on image latitude/longitude limits, resolution, offsets, size, etc. If a dataset has multiple resolutions or bandwidths it will have multiple locator files.

PDS Skeleton File

The PDS skeleton file has the dataset name as a filename with a ".pdt" extension. The PDS skeleton file is used to create maps with a Planetary Data System header. Each data set has a skeleton file containing pertinent mission information (e.g. mission name, spacecraft name, instrument name, etc.) as well as fields describing the image that are filled in at run time. MapMaker provides a generic skeleton label, template.pdt, that it will use when a skeleton label with the dataset name is not found.

To Add the Dataset

To add a dataset, perform the following steps:

Step 1: Ensure the appropriate descriptor, locator, and skeleton files are in the mapmaker/data directory.
Example: When installing the mars mdim dataset on a system where MapMaker is found in /usgs/mapmaker, the following files should be found in the /usgs/mapmaker/data directory:

mdim.des     mdim16.loc     mdim64.loc     mdim256.loc     mdim.pdt


Step 2: Ensure that the dataset.idx file found in the mapmaker/data directory contains a line describing the dataset in the following format:


(dataset name)     (descriptor file)     (text description)

(dataset name) should be replaced with a string in the format: planet_spacecraft_dataset.
(descriptor file) should be replaced with the name of the descriptor file.
(text description) should be a line of text, contained in double quotes, describing the dataset.

Example: If adding the mars mdim dataset, the dataset.idx file should contain the following line:


mars_viking_bw     mdim.des     "mars black and white basemaps"


Step 3: Ensure that the descriptor file INSTALLED_ON keyword reflects the hardware device that the dataset is installed on. There are three options that MapMaker will accept:


Jukebox
If the dataset is installed on a jukebox, the INSTALLED_ON keyword should be followed by JUKEBOX. MapMaker will follow the path provided in the mminit.csh script's $MMJUKEBOX environment variable to find the jukebox.


Example: INSTALLED_ON JUKEBOX


CD-ROM
If the dataset will be accessed using a CD-ROM drive, the INSTALLED_ON keyword should be followed by CDROM. MapMaker will follow the path provided in the mminit.csh script's $MMCDROM environment variable to find the drive, and use the commands held by $CDMOUNT and $CDUMOUNT to mount and unmount CDs.


Example: INSTALLED_ON CDROM


Hard Drive
There are two ways a dataset can be held on a hard drive. The hard drive can contain copies of the dataset CDs, or it can hold all image files directly.

If the hard drive contains the image files directly, the INSTALLED_ON keyword should be followed by HARDDRIVE and the path to the directory containing the image files.



Example: if the image files are contained in the directory /work/imagedata, the descriptor file line should be as follows:


INSTALLED_ON HARDDRIVE "/work/imagedata/"


If the hard drive contains a copy of the CD, the INSTALLED_ON keyword should be followed by HARDDRIVECD and the path to the directory containing the copy of the CD.


Example: if the copy of the CD is contained in the directory /work/imagedata, the descriptor file line should be as follows:


INSTALLED_ON HARDDRIVECD "/work/imagedata/"

Where To Get a New Dataset

There are several global planetary mosaic datasets supported by MapMaker. The CD-ROM sets that contain this data can be purchased by the general public from the National Space Science Data Center (NSSDC). The necessary dataset files can also be obtained by contacting the Planetary Data Systems Imaging Node. Users can also generate their own datasets (see MAPMAKER APPLICATION DEVELOPMENT: PART III: BUILDING A DATASET).

BUG REPORTING

This is the second release of the MapMaker software. 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:

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

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.