2. Introduction

Most scientists are familiar with the sequence: raw data $\rightarrow$ processing $\rightarrow$ final illustration. In order to finalize papers for submission to scientific journals, prepare proposals, and create overheads and slides for various presentations, many scientists spend large amounts of time and money to create camera-ready figures. This process can be tedious and is often done manually, since available commercial or in-house software usually can do only part of the job. To expedite this process we introduce the Generic Mapping Tools (GMT for short), which is a free^2.1, software package that can be used to manipulate columns of tabular data, time-series, and gridded data sets, and display these data in a variety of forms ranging from simple x-y plots to maps and color, perspective, and shaded-relief illustrations. GMT uses the PostScript page description language [Adobe Systems Inc., 1990]. With PostScript, multiple plot files can easily be superimposed to create arbitrarily complex images in gray tones or 24-bit true color. Line drawings, bitmapped images, and text can be easily combined in one illustration. PostScript plot files are device-independent: The same file can be printed at 300 dots per inch (dpi) on an ordinary laserwriter or at 2470 dpi on a phototypesetter when ultimate quality is needed. GMT software is written as a set of UNIX tools^2.2and is totally self-contained and fully documented. The system is offered free of charge and is distributed over the computer network (Internet) [Wessel and Smith, 1991; 1995a,b; 1998].

The original version 1.0 of GMT was released in the summer of 1988 when the authors were graduate students at Lamont-Doherty Earth Observatory of Columbia University. During our tenure as graduate students, L-DEO changed its computing environment to a distributed network of UNIX workstations, and we wrote GMT to run in this environment. It became a success at L-DEO, and soon spread to numerous other institutions in the US, Canada, Europe, and Japan. The current version benefits from the many suggestions contributed by users of the earlier versions, and now includes more than 50 tools, 25 map projections, and many other new, more flexible features. GMT provides scientists with a variety of tools for data manipulation and display, including routines to sample, filter, compute spectral estimates, and determine trends in time series, grid or triangulate arbitrarily spaced data, perform mathematical operations (including filtering) on 2-D data sets both in the space and frequency domain, sample surfaces along arbitrary tracks or onto a new grid, calculate volumes, and find trend surfaces. The plotting programs will let the user make linear, log$_{10}$, and x$^a$-y$^b$ diagrams, polar and rectangular histograms, maps with filled continents and coastlines choosing from 25 common map projections, contour plots, mesh plots, monochrome or color images, and artificially illuminated shaded-relief and 3-D perspective illustrations.

GMT is written in the highly portable ANSI C programming language [Kernighan and Ritchie, 1988], is fully POSIX compliant [Lewine, 1991], has no Year 2000 problems, and may be used with any hardware running some flavor of UNIX, possibly with minor modifications. In writing GMT, we have followed the modular design philosophy of UNIX: The raw data $\rightarrow$ processing $\rightarrow$ final illustration flow is broken down to a series of elementary steps; each step is accomplished by a separate GMT or UNIX tool. This modular approach brings several benefits: (1) only a few programs are needed, (2) each program is small and easy to update and maintain, (3) each step is independent of the previous step and the data type and can therefore be used in a variety of applications, and (4) the programs can be chained together in shell scripts or with pipes, thereby creating a process tailored to do a user-specific task. The decoupling of the data retrieval step from the subsequent massage and plotting is particularly important, since each institution will typically have its own data base formats. To use GMT with custom data bases, one has only to write a data extraction tool which will put out data in a form readable by GMT (discussed below). After writing the extractor, all other GMT modules will work as they are.

GMT makes full use of the PostScript page description language, and can produce color illustrations if a color PostScript device is available. One does not necessarily have to have access to a top-of-the-line color printer to take advantage of the color capabilities offered by GMT: Several companies offer imaging services where the customer provides a PostScript plot file and gets color slides or hardcopies in return. Furthermore, general-purpose PostScript raster image processors (RIPs) are now becoming available, letting the user create raster images from PostScript and plot these bitmaps on raster devices like computer screens, dot-matrix printers, large format raster plotters, and film writers^2.3. Because the publication costs of color illustrations are high, GMT offers 90 common bit and hachure patterns, including many geologic map symbol types, as well as complete graytone shading operations. Additional bit and hachure patterns may also be designed by the user. With these tools, it is possible to generate publication-ready monochrome originals on a common laserwriter.

GMT is thoroughly documented and comes with a technical reference and cookbook which explains the purpose of the package and its many features, and provides numerous examples to help new users quickly become familiar with the operation and philosophy of the system. The cookbook contains the shell scripts that were used for each example; PostScript files of each illustration are also provided. All programs have individual manual pages which can be installed as part of the on-line documentation under the UNIX man utility or as web pages. In addition, the programs offer friendly help messages which make them essentially self-teaching - if a user enters invalid or ambiguous command arguments, the program will print a warning to the screen with a synopsis of the valid arguments. All the documentation is avaliable for web browsing and may be installed at the user's site.

The processing and display routines within GMT are completely general and will handle any (x,y) or (x,y,z) data as input. For many purposes the (x,y) coordinates will be (longitude, latitude) but in most cases they could equally well be any other variables (e.g., wavelength, power spectral density). Since the GMT plot tools will map these (x,y) coordinates to positions on a plot or map using a variety of transformations (linear, log-log, and several map projections), they can be used with any data that are given by two or three coordinates. In order to simplify and standardize input and output, GMT uses two file formats only. Arbitrary sequences of (x,y) or (x,y,z) data are read from multi-column ASCII tables, i.e., each file consists of several records, in which each coordinate is confined to a separate column^2.4. This format is straightforward and allows the user to perform almost any simple (or complicated) reformatting or processing task using standard UNIX utilities such as cut, paste, grep, sed and awk. Two-dimensional data that have been sampled on an equidistant grid are read and written by GMT in a binary ``grdfile'' using the functions provided with the netCDF library (a free, public-domain software library available separately from UCAR, the University Corporation of Atmospheric Research [Treinish and Gough, 1987]). This XDR (External Data Representation) based format is architecture independent, which allows the user to transfer the binary data files from one computer system to another^2.5. GMT contains programs that will read ASCII (x,y,z) files and produce gridded files. One such program, surface, includes new modifications to the gridding algorithm developed by Smith and Wessel [1990] using continuous splines in tension.

Most of the programs will produce some form of output, which falls into four categories. Several of the programs may produce more than one of these types of output:

1. 1-D ASCII Tables -- For example, a ($x,y$) series may be filtered and the filtered values output. ASCII output is written to the standard output stream.

2. 2-D binary (netCDF or user-defined) ``grdfiles'' - Programs that grid ASCII ($x,y,z$) data or operate on existing grdfiles produce this type of output.

3. PostScript - The plotting programs all use the PostScript page description language to define plots. These commands are stored as ASCII text and can be edited should you want to customize the plot beyond the options available in the programs themselves.

4. Reports - Several GMT programs read input files and report statistics and other information. Nearly all programs have an optional ``verbose'' operation, which reports on the progress of computation. All programs feature usage messages, which prompt the user if incorrect commands have been given. Such text is written to the standard error stream and can therefore be separated from ASCII table output.

GMT is available over the Internet at no charge. To obtain a copy, read the relevant information on the GMT home page gmt.soest.hawaii.edu, or email listproc@hawaii.edu a note containing the single message

information gmt-group

The listserver will mail you back a shell-script that you may run to obtain all necessary programs, libraries, and support data. After you obtain the GMT archive, you will find that it contains information on how to install GMT on your hardware platform and how to obtain additional files that you may need or want. The archive also contains a license agreement and registration file. We also maintain two electronic mailing lists you may subscribe to in order to stay informed about bug fixes and upgrades (See Chapter 7).

For those without net-access that need to obtain GMT: Geoware (http://www.geoware-online.com) makes and distributes CD-Rs with the GMT package, compatible supplements, and several Gb of useful data sets. For more information send e-mail to geoware@geoware-online.com.

GMT has served a multitude of scientists very well, and their responses have prompted us to develop these programs even further. It is our hope that the new version will satisfy these users and attract new users as well. We present this system to the community in order to promote sharing of research software among investigators in the US and abroad.