GMT-SYSTEM


A generic data processing and display package

Webified manpage by Malcolm Reeves

TABLE OF CONTENTS


INTRODUCTION

The GMT-SYSTEM is a public domain software package that can be used to manipulate and display 2-dimensional (e.g., time-series or (x,y) series) or 3-dimensional data sets (e.g., (x,y,z) grids). The processing and display routines within the GMT- SYSTEM are completely general and will handle any (x,y) or (x,y,z) data as input. Most of the programs will produce some kind of output, which falls into four categories. Some of the programs may produce more than one of these types of output:

  1. 1-D Tables - For example, a (x,y) series may be fil- tered and the filtered values are output. These files are in the ASCII format and can be edited with any text editor.
  2. 2-D grdfiles - Programs that grid data will typically read (x,y,z) ASCII tables and create a 2-D equidistant table which is stored in a binary file format. These files are called grd-files and cannot be edited with ordinary text editors.
  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 through the programs themselves.
  4. Reports - Several programs read ASCII tables or binary grd-files and report statistics and other information. Such text is written to the standard error stream and can therefore be separated from ASCII table output.

GMT-SYSTEM PHILOSOPHY

The GMT-SYSTEM programs were designed to run under the UNIX operating system. UNIX is quite different from most earlier operating systems, and has proven to be a very pro- ductive tool for scientists and engineers worldwide. The UNIX philosophy is to let small, general-purpose programs work together in solving a problem, rather than designing large task-specific programs which are very time consuming to debug and maintain. We have written the GMT-SYSTEM in highly portable C as defined by Kernighan and Ritchie to be used with any hardware running UNIX and we have followed the modular design philosophy. For example, in order to plot a filtered marine bathymetry profile, we would first run one program to project the original (lon,lat,depth) data points onto a great circle, filter the data using another program, and use a third program to create the final plot. This modular approach brings several benefits:

The GMT-SYSTEM takes full advantage of Adobe's PostScript page description language Level 1 [Adobe Systems Incorporated]. With PostScript one can easily mix text, line-drawings, symbols, and bit-mapped graphics, a feature which is not possible with most other plotting systems. All the plotting programs in the GMT-SYSTEM software can produce color illustrations if there is a color PostScript device available. More and more color hardcopy devices have a PostScript interpreter built in, and many 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 proces- sors (RIPs) are becoming available, ranging from public domain products (Ghostscript), RIPs provided by the workstation manufacturers (e.g., xnews from SUN), to commercial third party products like Freedom of the Press, UltraScript, and Goscript.

GMT-SYSTEM OVERVIEW

The following is a summary of all the programs supplied with the GMT-SYSTEM and a very short description of their purpose. Detailed information about each program can be found in the separate manual pages.

blockmean
L2 (x,y,z) data filter/decimator
blockmedian
L1 (x,y,z) data filter/decimator
filter1d
Filter 1-D data sets (time series)
fitcircle
Finds the best-fitting great circle for a set of points
gmtdefaults
List the current default settings
grdfilter
Filter 2-D data sets in the space domain
grd2xyz
Conversion from 2-D gridded file to ASCII listing
grdclip
Limit the z-range in gridded data sets
grdcontour
Contouring of 2-D gridded data sets
grdcut
Cut a sub-region from a grd file
grdedit
Modify header information in a 2-D gridded file
grdfft
Perform all operations on grdfiles in the frequency domain
grdgradient
Compute directional gradient from grdfiles
grdhisteq
Histogram equalization for grdfiles
grdimage
Produce images from 2-D gridded data sets
grdinfo
Get information about grd files
grdmask
Reset nodes outside a clip path to a constant
grdmath
Mathematical operations on grdfiles
grdpaste
Paste together grdfiles along a common edge
grdproject
Project gridded data sets onto a new coordinate system
grdsample
Resample a 2-D gridded data set onto a new grid
grdtrend
Fits polynomial and Fourier trends to grdfiles
grdtrack
Sampling of 2-D data set along 1-D track
grdview
3-D perspective imaging of 2-D gridded data sets
mapproject
Transformation of coordinate systems
nearneighbor
Nearest-neighbor gridding scheme
project
Project data onto lines/great circles
psbasemap
Create a basemap
psclip
Use polygon files as clipping paths
pscoast
Plot coastlines and filled continents on maps
pshistogram
Plot a histogram
psmask
Create overlay to mask out regions on maps
psmegaplot
Create postersize plots from postscript files
psrose
Plot sector or rose diagrams
psscale
Plot grayscale or colorscale on maps
pstext
Plot textstrings on maps
pswiggle
Draw anomalies along track on maps
psxy
Plot symbols, polygons, and lines on maps
psxyz
Plot symbols, polygons, and line in 3-D
sample1d
Resampling of 1-D data sets
spectrum1d
Compute various spectral estimates from time-series
splitxyz
Split xyz-files into several segments
surface
A continuous curvature gridding algorithm
trend1d
Fits polynomial trends to y = f(x) series
trend2d
Fits polynomial trends to z = f(x,y) series
xyz2grd
Convert an ASCII xyz file to a 2-D grd file

GENERAL FEATURES

This section explains a few features common to all the programs in the GMT- SYSTEM. It summarizes the philosophy behind the system. Some of the features described here may make more sense once you reach the cook-book section where we present actual examples of their use.

GMT-SYSTEM defaults

There are more than 50 parameters which can be adjusted individually to modify the appearance of plots or affect the manipulation of data. When a program is run, it will first try to open the file .gmtdefaults in the current directory. If not found it will try your home directory. If a file is found, the program will read the contents and set the default values to those provided in the file. By editing this file you can affect features such as pen thicknesses used for maps, fonts and font sizes used for annotations and labels, color of the pens, dots-per-inch resolution of the hardcopy device, what type of spline interpolant to use, and many other choices (A complete list of all the parameters and their default values can be found in the gmtdefaults manual pages). You may create your own .gmtdefaults files by running gmtdefaults and then modify those parameters you want to change. Note that any arguments given on the command line (see below) will take precedent over the default values. E.g., if your .gmtdefaults file has pen-thickness = 5 as default, the -W3 option will override the default and set the pen-thickness to 3. Users may choose to have different .gmtdefaults files for different projects in separate directories.

Command Line Arguments

Each program requires certain arguments specific to its operation. These are explained in the manual pages and in the usage messages. Most programs are "case-sensitive"; almost all options must start with an upper-case letter. We have tried to choose letters of the alphabet which stand for the argument so that they will be easy to remember. Each argument specification begins with a hyphen (except input file name; see below), followed by a letter, and sometimes a number or character string immediately after the letter. DO NOT space between the hyphen, letter, and number or string. DO space between options. Example:

          grdcontour -C5 -Jm1:500000 -A10 -V > map.ps

Standardized command line options

Most of the programs take many of the same arguments like those related to setting the data region, the map projection etc. These 10 options have the same meaning in all the programs (Some programs may not use all of them):

OptionMeaning
-B Defines tickmarks, annotations, and labels for basemaps and axes.
-J Selects a map projection or one of several non-map projections.
-K Allow more plot code to be appended to this plot later.
-O Allow this plot code to be appended to a existing plot.
-P Select Portrait plot orientation.
-R Define the min and max coordinates of the map/plot region.
-X Set the x-coordinate for the plot origin.
-Y Set the y-coordinate for the plot origin.
-# Specify number of plot copies.
-: Inform that input file is (y,x) rather than (x,y)

These options will be described in more detail in the manual pages.

Command Line History

The GMT-SYSTEM programs "remember" the standardized command line options given during their previous invocations and this provides a shorthand notation for complex options. For example, if a basemap was created with an oblique Mercator projection, specified as

          -Joc190/25.5/327/56/1:500000

then the following psxy command to plot symbols only needs to state -Jo in order to activate the same projection. Previous commands are maintained in the files .gmtcommands, of which there will be one in each directory you run the programs from. This is handy if you create separate directories for separate projects since chances are that data manipulations and plotting for each project will share many of the same options. You can choose another .gmtcommands file by specifying +other_file where other_file is the full pathname to another gmtcommands file (which may have any name). Note than an option spelled out on the command line will always override the last entry in the .gmtcommands file and will, if execution is successful, replace this entry as the .gmtcommands entry.

Usage and Error Messages

Each program carries a usage message. If the program does not understand the arguments you enter, or if you enter the program name without any arguments, the program will write a usage message to standard error (your screen, unless you redirect it). This message explains in detail what the valid arguments are. If you enter the program name followed by a hyphen only you will get a shorter version which only shows the command line syntax and no detailed explanations. Most of the time you don't even need this manual or the man page; the program will tell you what to do! If an error occurs during the running of a program, the program will in some cases recognize this and give you an error message. Usually this will also terminate the run. The error messages generally begin with the name of the program in which the error occurred; if you have several programs piped together this tells you where the trouble is.

Stdin or File

Most of the programs which expect ASCII character input can read either standard input or input in one or several files. These programs will try to read stdin unless you type the filename(s) on the command line without the above hyphens. (If the program sees a hyphen, it reads the next character as an instruction; if an argument begins without a hyphen, it tries to open this argument as a filename). This feature allows you to connect programs with pipes if you like. If your input has one or more header records, you must use the -H option. The number of header records is one of the many parameters in the .gmtdefaults file, but can be overridden by -H<n_header_recs>.

Verbose Operation

Most of the programs take an optional -V argument which will run the program in the "verbose" mode. Verbose will write to standard error information about the progress of the operation you are running. Verbose reports things such as counts of points read, names of data files processed, convergence of iterative solutions, and the like. Since these messages are written to stderr, the verbose talk remains separate from your output.

Output

Most programs write their results to standard output. PostScript plot output is no exception. The exceptions are those which create binary netCDF grd-files such as surface. With UNIX, you can redirect standard output or pipe it into another process. Error messages, usage messages, and verbose comments are written to standard error in all cases. You can use UNIX to redirect stan- dard error as well, if you want to create a log file of what you are doing.

PostScript Features

PostScript is a command language for driving graphics devices such as laser printers. It is ASCII text which you can read and edit as you wish (assuming you have some knowledge of the syntax). We prefer this to binary metafile plot systems since such files cannot be modified after they have been created. The GMT-SYSTEM programs also write many comments to the plot file which make it easier for users to orient themselves should they need to edit the file (e.g., % Start of x-axis). All GMT-SYSTEM programs create PostScript code by calling the pslib plot library (The user may call these functions from his own plot programs. See the manual pages for pslib syntax). Although the GMT-SYSTEM programs can create very individualized plot code, there will always be cases not covered by these pro- grams. Some knowledge of PostScript will enable the user to add such features directly into the plot file.

Landscape and Portrait Orientations

In general, a plot has an x-axis increasing from left to right and a y-axis increasing from bottom to top. If the paper is turned so that the long dimension of the paper is parallel to the x-axis then the plot is said to have Landscape orientation. If the long dimension of the paper parallels the y-axis the orientation is called Portrait. (Think of taking pictures with a camera and these words make sense). All the programs in the GMT-SYSTEM have the same default orientation, which is Landscape. Use -P to change to Portrait (Note that PAPER_WIDTH is a user-definable parameter, by default set to 8.5". For other paper dimensions you must change this value accordingly).

Overlay and Last Page Modes

A typical PostScript file has a beginning, a middle, and an end. The beginning defines certain features (e.g., macros, origin, orientation, scale, etc.) which will be needed to create the plot. The middle has the commands which actually do the plotting. The end tells the graphics device to put out the plot ("showpage" in PostScript) and reset the graphics state. Many of the illustrations in this cookbook are built up by appending PostScript files together. If you do this, the first file needs a "beginning" and no "end", the last an "end" but no "beginning", and the middle files need only a "middle". You can do this yourself in an editor, or you can do it automatically with the Overlay (-O) and Last Page (-K) options. Overlay indicates that this plot will be laid on top of an earlier one; therefore the "beginning" is not included in the output. The default is always no overlay, i.e. write out the "beginning". Last Page indicates that another plot will follow this one later (this is not the last page); therefore the "end" is not included in the output. The default is to output the "end". If you run only one plot program, ignore both the -O and -K options; they are only used when stacking plots.

Specifying Pen Attributes

A pen in the GMT-SYSTEM has three attributes: width, color, and texture. Most programs will accept pen attributes in the form of an option argument:

          -W<width>[/<color>][t<texture>][p]

Width is normally measured in units of the current device resolution (i.e., the value assigned to dpi in your .gmtdefaults file). THus, if dpi is set to 300 then this unit is 1/300th of an inch. Append a 'p' to specify pen width in points (1/72 of an inch). Note that a pen thickness of 5 will be of different physical width depending on your dpi setting, whereas a thickness of 5p will always be 5/72 of an inch. Minimum-thickness pens can be achieved by giving zero width, but the result is device-dependent. The color can be specified as a gray shade in the range 0-255 (going from black to white) or using the RGB system where you specify r/g/b, each ranging from 0-255. Here 0/0/0 is black and 255/255/255 is white. The texture attribute controls the appearance of the line. To get a dotted line, simply append "to" to the option argument; a dashed pen is requested with "ta". For exact specifications you may append t<string>:offset, where <string> is a series of integers separated by underscores. These numbers represent a pattern by stating the length of line segments and the gap between segments. The offset shifts the pattern along the line. For example, if you want a yellow line of width 2 that alternates between long dashes (20 units), a 10 unit gap, then a 5 unit dash, then another 10 unit gap, offset by 10 units, specify:

          -W2/255/255/0t20_10_5_10:10

Here, the units are specified in dpi units or points (see above).

Specifying Area Fill Attributes

Many plotting programs will allow the user to draw filled polygons or symbols. The fill may take two forms:

               -G<fill>
               -Gp<iconsize>/<pattern>

In the first case we may specify a gray shade (0-255) or a color (r/g/b in the 0- 255 range), similar to the pen color settings. The second form allows us to use a predefined bit-image pattern. <pattern> can either be a number in the range 1-32 or the name of a [Sun] icon file. The former will result in one of the 32 predefined patterns provided with the GMT-SYSTEM and can be inspected using the utility program pspatterns. The latter allows the user to create customized, repeating bit-patterns using the icon editor on a Sun workstation or by other means. The <iconsize> parameter sets the size of this 64 by 64 image on the page; the area fill is thus made up of a series of these "tiles". Specifying 0.0 will result in highest resolution obtainable on the designated hardcopy device. By specifying -GP instead of -Gp the image will be bit-reversed, i.e., white and black areas will be interchanged. The format of the bit pattern is outlined in Appendix D. The predefined patterns are shown after Appendix E. Note that under PostScript Level 1 the patterns are filled by using the polygon as a clip path. Complex clip paths may require more memory than the PostScript interpreter has been assigned. There is therefore the possibility that some PostScipt interpreters (especially those supplied with laserwriters) will run out of memory and abort. Should that occur we recommend that you use a regular grayshade fill instead of the patterns.

Color Palette Tables

Those programs which read 2-D gridded data sets and create colored images or shaded reliefs need to be told what colors to use and over what z-range each color applies. This is the purpose of the color palette file (cpt-file). The colors may be specified either in the RGB system or in the HSV system, and the parameter COLOR_MODEL in the .gmtdefaults file must be set accordingly. Using the RGB system, the format of the cpt-file is:

          z0   Rmin Gmin Bmin z1   Rmax Gmax Bmax
          z1   Rmin Gmin Bmin z2   Rmax Gmax Bmax        ...
          zn-2 Rmin Gmin Bmin zn-1 Rmax Gmax Bmax

Thus, for each "z-slice", defined as the interval between two boundaries (e.g., z0 to z1), the color can be constant (by letting Rmin = Rmax, Gmin = Gmax, and Bmin = Bmax) or a continuous, linear function of z. The background color (for z-values < z0) and foreground color (for z-values > zn-1) are defined in the .gmtdefaults file, but can be overridden by the statements

          F    Rback     Gback     Bback
          B    Rfore     Gfore     Bfore

which can be inserted into the beginning or end of the cpt-file. If you prefer the HSV system of hue-saturation-value, set the .gmtdefault parameter accordingly and replace red, green, blue with hue, saturation, value. Some programs like grdimage and grdview apply artificial illumination to achieve shaded relief maps. This is done by finding the directional gradient in the direction of the artificial 1 and scaling the gradients to have approximately a normal distribution on the interval <-1,+1>. These intensities are used to add "white" or "black" to the color as defined by the z-values and the cpt-file. An intensity of zero leaves the color unchanged. Higher values will brighten the color, lower values will darken it, all without changing the original hue of the color. The illumination is decoupled from the data grd-file in that a separate grdfile holding intensities in the <-1,+1> range must be provided. Such intensity files can be derived from the data grd-file using grdgradient and modified with grdhisteq, but could equally well be a separate data set. E.g., some side-scan sonar systems collect both bathymetry and backscatter intensities, and one may want to use the latter information to specify the illumination of the colors defined by the former.

Character Escape Sequences

For anotation labels or textstring plotted with pstext, GMT provides several escape sequences that allow the user to temporarily switch to the symbol font, turn on sub- or superscript, etc. within words. These conditions are toggled on/off by the escape sequence @x, where x can be one of several types. These espace sequences are recognized:

@~ Turns Symbol font on or off. @+ Turns superscript on or off. @- Turns subscript on or off. @# Turns Small Caps on or off. @\ Makes one composite character of next two characters. @@ Prints the @ sign itself.

A shorthand notation for a few special Scandinavian characters have also been added. For a list of these and full octal codes for additional accented characters used in several European languages, consult the Technical Reference and Cookbook.

Reminder: If you think it is appropriate, you may consider paying us back by including our EOS article and/or our Geophysics article on the gridding algorithm in surface in the reference lists of your future publications if you feel that your work has benefitted from the availability of GMT.

EXAMPLES

GMT-SYSTEM is extremely versatile, allowing the creation of almost any kind of 2D or 3D graphic. The following examples illustrate just a few of the numerous plot options available under GMT-SYSTEM.

NOTE: The reduced size images are reproduced as .gif bitmaps files. The output generated by GMT is high-resolution color postscript.

Example 1:
Contour maps of low order geiod using Hammer equal-area projection.
Example 2:
2D contour map of Hawaii geoid using oblique Mercator projection (COLOR).
Example 3:
Simple histogram of topographic elevations.
Example 4:
3D perspective mesh plot of Hawaiian topography and geoid (COLOR).
Example 5:
3D illuminated grayscale surface of Bessel function.
Example 6:
Simple rose diagram of fracture orientations.
Example 7:
Simple location map with mid-Atlantic ridge and earthquake locations.
Example 8:
3D perspective histogram plot using columns as 3D symbols.
Example 9:
Time series (seismic wiggle traces) plotted along geographic tracks.

REFERENCES

Wessel, P., and W. H. F. Smith, 1993, The GMT-SYSTEM v. 2.1.4 Technical Reference & Cookbook, SOEST/NOAA.

Wessel, P., and W. H. F. Smith, 1991, Free software helps map and display data, EOS Trans. AGU, 72, 441.

Adobe Systems Inc., 1990, PostScript language reference manual, 2nd edition, Addison-Wesley, (ISBN 0-201-18127-4)

Kernigan, B. W., and D. M. Ritchie, 1988, The C programming language, 2nd. edition, Prentice-Hall, (ISBN 0-13-110370-9)