GMT Tutorial

2011/2012
Sebastian Rost

This is a brief tutorial to get you started with using the freeware Generic Mapping Tools (GMT).
Essentially GMT is a bunch of programs, that may be used one after another to append plots, add
more features, lines, data sets etc. We will use basic C-shells commands on a linux system, so files
that contain the commands we normally type. This tutorial is partly based on a course by Ed
Garnero from Arizona State University.
Setup
To run GMT on the School's computer system you probably have to add the correct search path to
your C-shell resource file.
Please check if your ~/.cshrc file contains the following line:
# for GMT4.1
set path = ( $path /nfs/see-fs-01_app1/GMT4.1/bin )

You can do this by opening this by opening this file using your favourite editor. E.g.:
nedit ~/.cshrc

If you made any changes to your ~/.cshrc file you have to reread it, so that the computer knows
about the changes. This takes only affect in the current konsole where you type the source
command.
source ~/.cshrc

If you now type a GMT command (e.g. psxy) you should get a help page that tells you how the
command works.
GMT manual and online resources
Here are some links related to GMT.
GMT's home page, from the author's of GMT, Generic Mapping Tools, by Wessel and Smith from
the University of Hawaii. Also download your own version here:
http://gmt.soest.hawaii.edu/
A former PhD student at Harvard has made an interactive version of GMT: Interactive Generic
Mapping Tools (iGMT). I am not working with this version and will not talk about it today, but it
might be an easy way to make simple maps quickly. GMT is more powerful than the interactive
version.
http://www.seismology.harvard.edu/~becker/igmt/
There are also extensive manual pages installed with GMT. You can access them by typing:

man gmtcommand
E.g.:
(earsro-see-gw-01.leeds.ac.uk)39% man psxy

Here are links to GMT plots.

Global Seafloor Topography as Measured & Estimated from gravity data derived from satellite
altimetry and shipboard depth soundings (US National Oceanic and Atmospheric Agency) :
http://www.ngdc.noaa.gov/mgg/image/global_topo_large.gif
Global Seafloor Topography from Satellite Altimetry:
http://www.ngdc.noaa.gov/mgg/image/seafloor.html
DIGITAL GLOBEs (from UC San Diego):
http://topex.ucsd.edu/marine_topo/globe.html
Land topography (from US Geological Survey):
http://edcdaac.usgs.gov/gtopo30/gtopo30.html
Image Formats
To display a graphics file a computer interprets the content of a file according to special rules that
are laid down in the special file format. Generally, there are two different file formats: raster and
vector. Raster is a one in which the image is divided into pixels or picture elements and each has a
color value (like a checkerboard). Vector files describe the image as a series of objects such as
points or lines or polygons.
Vector file formats
GMT makes postscript (PS) file plots; here is a nice discussion of how to program in Postscript and
how it works. Very interesting.
http://www.cs.indiana.edu/docproject/programming/postscript/postscript.html. In essence, posctript
is a graphics programming language.
Raster file formats
Raster files are used on the world wide web for example for display of images. The most common
formats are gif and jpeg or jpg, but there are also other (non-proprietary) formats such as PNG
It is possible to convert PS to other file formats using both Windows and UNIX command. A file in
jpeg format can be posted on the web or can be inserted into a MSWord document (or any other
word processing software).
Map making
Please copy the scripts from my GMT Tutorial from my webpage to a directory in your home
directory and copy the content of the following data directory into the same directory:
cp -r /nfs/see-fs-01_teaching/others/earsro/GMT_Tutorial/data .

Let's first start with a file named map_basic.csh. It creates a world map. The main contents of that file
(minus comment lines) follows :
#!/bin/csh
pscoast -R-180/180/-70/70 -JM0/14/7 -Ba60g30f15/a30g30f15WSen \
-X0.5 -Y2.0 -Dc -S100/100/200 -G100/205/100 -W1/0/255/0 \
-P -K >! map1.ps
awk '{print $7,$6}' < data/world_EQ.dat >! eq.xy
psxy eq.xy -R -JM -Sc0.075i -G255/0/0 -W2 -O >> map1.ps
gs -sDEVICE=x11 map1.ps

The first line is used to let the computer know that there is a C-shell script coming and that is
should use the C-shell to interpret the commands. There are two GMT programs that are used in
this script pscoast and psxy. The other two programs, awk and gs are UNIX commands to read
certain parameters from a file (awk) and to display a postscript file (gs).
This script will draw a map (pscoast) and plots global seismicity (stored in the file
data/world_EQ.dat) as circles on this map (psxy). The command awk read only the latitude and
longitude of these earthquakes from the file.
The general GMT command structure is:
gmt_command (options) > outputfile
There are many, many options which is the real power of GMT. The first command (pscoast) is
used to plot the main coastlines on a map and contains the most important options:
-Rwest/east/south/north
-Jparameters
-Btickinfo
-X
-Y
-Dresolution
-Sfill
-Gfill
-Wpen
-P
-O
-K

specifies the region of interest

selects the map projection
specifies the tick marks on the map
shifts plot in X direction
shifts plot in Y direction
defines the map resolution
sets painting of 'wet' areas
set painting of 'dry' areas
defines which pen to use for drawing
selects portrait mode (default landscape)
tells GMT to add output to the same plot
tells GMT that more PS is koming

Let's play with this script. Open it in a text editor (e.g. vi or nedit).
You can change the area of interest by changing the west/east/south/north boundaries of the -R
parameter. Let's focus on Europe for a while. In the text editor change the area of interest to:
-R-15/20/30/65

and rerun the script (by typing the script name into the command line). You should now have a map
of Europe with very few earthquakes on it.

You will notice that the map looks slightly funny and that the map ticks marks are not really useful,
since there are too few. So let's change this:
Change the tick marks in pscoast to:
-Ba10g5f5/a10g5f5

and the projection in both pscoast and psxy to

-JM5i
This will produce a map more like the one you are used too. The tick mark changes made a closer
tick mark spacing for both the x and y direction (latitude and longitude).

Adding lines
You can add lines to this map using the same command psxy that is used to plot the points onto the
map. To draw a line you have to omit the symbol declaration -S of the command psxy.
You can add the lines by adding the following line to your code (see map_line.csh):
psxy -R -JM -Sc0.15i -G255/0/0 -W3/255/255/0 -L -O -K << END >> $outfile
-12.0 49.0
3.0 49.0
3.0 59.0
-12.0 59.0
END

This will draw a yellow rectangle around Great Britain and Ireland. You will note that the line,
although they should be straight show a slight curvature. This is due to the map projection, so the
process of getting something from a sphere to a plane map.
You can imagine that adding a large amount of line segments to the GMT script in this way is a bit
awkward. So alternatively you could write this line as:
psxy lines.dat -R -JM -Sc0.15i -G255/0/0 -W3/255/255/0 \
-L -O -K << END >> $outfile

Which opens the file lines.dat, which e.g. contains the line segments as:
-12.0
3.0
3.0
-12.0

49.0
49.0
59.0
59.0

Every line segments is in one line. So this plots a line from -12/49 to 3/49, then a line from 3/49 to
3/59, then one from 3/59 to -12/59. Since we added the option -L to the psxy command this polygon
will be closed (-L forces polygon to close). If you want different line segments that are not
connected (e.g. source-receiver great circle paths) you have to specify -M in psxy and have to
separate the segments:
>>
-12.0
3.0
>>
3.0
-12.0
>>

49.0
49.0
59.0
59.0

Adding text to GMT

The command to add text in GMT is pstext. It is quite flexible, but not interactive like in most
graphics programs. You pretty much need to do trial and error to get things where you want, sizes,
etc. You can add text by typing (see map_text.csh):
pstext
-19 50
5 26
5 67
stopit

-R -JM -N -G0/0/255 -D-0.5/0 -O << stopit >> $outfile

20 90 4 CM Latitude
20 0 4 CM Longitude
10 0 4 CM Groovy Map

There are 3 lines of text instruction, and they are of the format:
x y s a f j text string
where
x = x location of the text string
y = y location of the text string
s = size of text in points
a = angle of text, in degrees counter clock wise
f = font number (type in a terminal window "pstext -L" to see the font options)
j = justification (BL = bottom left, TR= top right, CM=center middle, etc)
text string = the text to be displayed.
Adding more information
It is easy to add more information to these plots. E.g. you might be interested in the source depth of
the earthquakes we plotted in the beginning. This information is actually contained in the data file
we read in the beginning. So how do we get it out of the file and into the plot.
The best way to visualize this is by color-coding the depth. So an event with a different depth will
have a different color.
To do this we need a colorscale first. The program that produces color scales is makecpt. To create
a color scale for the earthquake depths from 0 to 700 km with a 50 km tick mark spacing of the
color and a continuous colorscale (-Z) using the prepared rainbow colorscale (to see other preprepared colorscale type makecpt) you add (script map_depth.csh):
makecpt -Crainbow -T0/700/50 -Z >! color.cpt

The color scale will be written to the file color.cpt and can then be used to color the depth of the
earthquakes:
awk '{print $7,$6,$8}' < data/world_EQ.dat >! eq.xy
psxy eq.xy -R -JM -Sc0.075i -Ccolor.cpt -W2 -O >> map1.ps

The awk command write the depth in the third column of eq.xy. psxy then reads the data
(lat,lon,dep) from eq.xy and uses the colofile color.cpt to add the depth information as color.

Multiple Plots
You might want to plot an overview map of your study are and a more detailed map including
sample point or whatever. To do this you need several plots in one page.
Let's draw a globe on the left had side of a page (using a new map projection). Check out the script
globe1.csh:
#! /bin/csh
set output = globe.ps
#----------------------------------------------------------------------# run the GMT program "pscoast" to make coastlines, and do it on a globe
# and let's center it on lat=-10.5 lon=-81 deg, and the size: R=1.0 inch.
#----------------------------------------------------------------------pscoast -R0/360/-90/90 -Jg-80/-10/0.7/0 -G60/210/160 \
-S225/250/225 -Dc -Bg30 -W3/0/0/0 -Y8.0 -P >! $output
#----------------------------------------------------------------------# run ghostscript to plot our postscript output file
#----------------------------------------------------------------------gs -sDEVICE=x11 $output

Again if you want to add something later to this plot you'll need to add a -K to the last previous
postscript generating command. You can add as many things to the plot as you like, but all of the
lines (except the last one needs a -K). If you have a -K on the last postscript producing command,
you will be able to look at the ps-file, but it will not print!!!
Let's add a box around a specific region on our little globe (globe2.csh). Copy the following into
the globe1.csh file using the text editor, right before the last 4 lines that plot the result:
#----------------------------------------------------------------------# run the GMT program "psxy" that will add a box around some region
# NOTE: we have added a "-:" flag in psxy below. This corresponds to
# input where X and Y values are in opposite columns (e.g, Lat,Lon
# instead of Lon,Lat)
#----------------------------------------------------------------------psxy -R -Jg -: -W6/0/0/0 -O << END >> $output
20 -100
20 -60
-10 -60
-10 -100
20 -100
END

For

this to work, we have to now modify that last previous postscript-making command (the pscoast
command). We have to add a -K so that our postscript output is aware of follow up plotting tasks.
Now let's add a cartesian projection plot with this box we just made as the bounds of an additional
plot (globe3.csh), on the same page. We shift this plot by 2 inches in the x direaction (-X2.0) and -2
in the Y direction (-Y-2.0) to move it away from the previous plot. Since we give a new projection
and a new area, it will plot a new plot. The output still goes to the same output file:

#----------------------------------------------------------------------# NEW PLOT!!!!

# run pscoast to make the zoom cartesian map, off to the lower right
#----------------------------------------------------------------------pscoast -R-100/-60/-10/20 -JX4i/3id -G60/210/160 -Dc \
-Ba10f10g10WSen -W4/0/0/100 -O -X2.0 -Y-2.0 >> $output

Contouring in GMT
GMT has several tools to work with gridded datasets. It uses a special format to read in gridded
data, but it can also read in standard xyz data. The main programs to use wit a gridded (spatial) data
are:
grdcontour

Contouring of 2-D gridded datasets

grdview

3-D perspective imaging of 2-D gridded datasets

grd2xyz

Conversion from 2-D gridded file to table data

xyz2grd

Convert and equidistant table xyz file to a 2-D gridded file

grd2cpt

Generate a GMT color palette table from a gridded file

grdvector

Plotting of 2-D gridded vector fields

grdimage

Produce images from 2-D gridded file

There are more examples to calculate gradient, filter gridded data and work with grid files. For
more information check the GMT webapge!
The first example is similar to example 1 on the GMT webpage and plots contour lines of the global
geoid. It uses the gridded dataset in the file osu91a1f_16.grd
Here is the example (also in the file countour1.csh):
#!/bin/csh
# FILE: c.contour0
# Purpose: Make a contour map based on the data in the file osu91a1f_16.grd
# GMT progs: pscoast, grdcontour
#
# this is a stripped down version of the GMT example 1 on the web
# define the output filename
set outfile = contour0.ps
# plot the coast, color the land (-G) w/ light gray
pscoast -R-180/180/-90/90 -JH0/6i -X1.25i -Y5.5i -Bg30 \
-Dc -G200 -P -K >!$outfile
# contour the geoid data set. The -C flag is for contour interval
grdcontour data/osu91a1f_16.grd -R -JH -C10 -O >> $outfile
# plot the output file
gs -sDEVICE=x11 $outfile

You see we used the known pscoast to command to plot the coastlines. On top of the coastline map
7

we plot the contour lines of the geoid. The -C flag is used to define the contour interval.
In this plot it is very complicated to see the value for the contour lines. Therefore let's annotate the
contour lines by changing the grdcontour command:
grdcontour -R osu91a1f_16.grd -JH -C10 -A30f12 -G4i -O >> $outfile

The flag -A annotates the contour lines and -G hardwires the annotation spacing.
To make this figure more readable it would be good to use some color for the gridlines. Let's say we
plot negative values as red and positive values as blue. We will use grdcontour twice and limit the
contour range. The script then looks something like this (countour2.csh):
#!/bin/csh
# FILE: contour2.csh
# Purpose: Make COLORED contour map based on data in the file osu91a1f_16.grd
# PLOT 2 COLORS: one for + one for # GMT progs: pscoast, grdcontour
#
# define the output filename
set outfile = contour2.ps
# plot the coast, this time in color the land (-G)
pscoast -R-180/180/-90/90 -JH0/6i -X1.25i -Y5.5i -K -Bg30 -Dc \
-G200/255/200 -S200/200/255 -P >! $outfile
# contour the geoid data set. The -C flag is for contour interval
# annotate the contour (-A) and hardwire annotation spacings (-G)
# additionally: use grdcontour twice: one for red and one for blue lines (-W)
# limit contour range of each statement, so we only plot minus values for red
lines,
# plus geoid values for blue lines (-L)
grdcontour -R data/osu91a1f_16.grd -JH -C10 -A50f12 -G4i -L-1000/-1 \
-W1/255/0/0 -O -K >> $outfile
grdcontour -R data/osu91a1f_16.grd -JH -C10 -A50f12 -G4i -L-1/1000 \
-W1/0/0/255 -O >> $outfile
# plot the output file
gs $outfile

If you want to make the contours even clearer you can add another line for the zero geoid values.
This is done by another grdcontour call with a very small range of contours.
grdcontour data/osu91a1f_16.grd -R -JH -C15 -A30f12 -G3i -L-1/1 -W5/0/0/0 \
-T -O -K >> $outfile

Plotting spatial data

Finally, if you want to plot a smoothed version of the geoid rather than contour lines you will use
grdimage (you could also use grdview in a similar context).
The file is gridimage1.csh:
#!/bin/csh
set outfile = gridded2.ps
# make the colorscale for the plot
grd2cpt data/osu91a1f_16.grd -Cpolar >! colortable2.cpt
# make a basemap box, w/ date, etc
psbasemap -R0/6.5/0/5 -Y2.0i -X0.25i-Jx1i -B0 -P -U"GMT's grdimage command" \
-K >! $outfile
# make a gridded (smoothed) image. Use colors defined in "colortable2.cpt"
grdimage data/osu91a1f_16.grd -R-180/180/-90/90 -JH0/6i -X0.25i -Y1.0i \
-Ccolortable2.cpt -P -O -K >> $outfile
# add a coast on top of that:
pscoast -R -JH -Bg30 -Dc -W5 -O >> $outfile
gs $outfile

It is important to remember that GMT plots things on top of each other. So if you call the pscoast
before the grdimage the coastlines will be covered with the geoid values. The grd2cpt works
similar to the makecpt we had before. In this case we use a colorscale (polar) that runs from blue
over white to red.