Introduction to Generic Mapping Tools (GMT):

mini-course modules (Page 1 of 2)
by Andrew Newman
Advanced Topics:
Generic Mapping Tools (hereafter GMT) are a package containing numerous command-line programs useful for generating a wide range of figures. As the name suggests, the tools are particularly well adapted to creating maps and other geo-referenced plots, yet the programs are also useful for creating useful professional figures of almost any type of data.

Before taking this course it is recommended that you have some familiarity with the UNIX command-line and shell scripts (see this Introduction to UNIX if necessary).

This course is broken up into two sections:

Introduction:

  • Getting GMT: GMT is freely available software that is made to work on most all unix platforms, including Mac OS X, and windows under cygwin/X. If you are interested in installing GMT on your own machine, or would like more information about the program, please go check out the official website. To install the program, you will likely also need a C compiler and at least 100 Mb of space.

    Your SHELL environment: I have recently began writing all of my scripts in the 'BASH' shell environment since it has become the dominant and default environment on most UNIX-based operating systems including Linux, MacOS X and cygwin. Unfortunately, the GMT Tutorial that we will be using, has all scripts written in the 'CSH' shell environment, thus there will be some differences in the way variables are called and some data I/O and redirection. In general, BASH is a simpler environment and will take only a little work to get used to.

  • Setting up environment: On the GT:Geophysics lab machines, your GMT environment should already be correctly identified through the system's /etc/bash.bashrc.local, however you should check that this is the case.


    Make sure that:
    1. $GMTHOME environmental variable is set. To test, type: 
      % echo $GMTHOME
/usr/local/geophysics/gmt/GMT4.1.3 # if you get this response and can see
                                   # the corresponding directory, you are fine.
      If this doesn't show anything then you will need to have 
       export GMTHOME=/usr/local/geophysics/gmt/GMT4.1.3
      set in your .bashrc.

    2. $GMTHOME is in your 'executable' and 'man' paths. To test, type: 
      % echo $PATH
.:/home/anewman/bin:/home/anewman/bin/GPS:/home/anewman/bin/SEISMIC:/home/anewman/FE/abaqus/bin:
/usr/local/geophysics/abaqus/Commands:/opt/intel/fce/9.1.031/bin:/usr/local/bin:/usr/local/geoph
ysics/gmt/netcdf/bin:/usr/local/geophysics/bin:/usr/local/geophysics/gmt/GMT4.1.3/bin:/usr/local
/geophysics/CPS/PROGRAMS.330/bin:/opt/bin:/usr/X11R6/bin:/bin:/opt/gnome/bin:/opt/kde3/bin:/usr/
lib/jvm/jre/bin
# check if the $GMTHOME path followed by '/bin' is here
% echo $MANPATH
/home/anewman/man:/opt/intel/fce/9.1.031/man:/usr/local/geophysics/gmt/netcdf/man:/usr/local/geo
physics/man:/usr/local/geophysics/gmt/GMT4.1.3/man:/opt/man:/usr/local/man:/usr/share/man:/usr/X
11R6/man:/opt/gnome/share/man
# again, check if the $GMTHOME path followed by '/man' is here
      If the correct path's are not listed then you will again need to add them in your .bashrc. See me for details.


  • Manuals: Local copies of the online man pages, tutorial and cookbook are all available here:

  • Viewing Output: GMT creates vector graphics using the postscript document and programming language. While, postscript is not a very common data format in windows (for viewing), it has long been used by UNIX operating systems, and most networked printers. Postscript is very similar to Adobe's "Portable Document Format (pdf)" and there are a variety of tools available on all platforms for converting them to pdfs. Generally, within UNIX, we keep the images as postscript, and demark the files with the extension '.ps'. In order to view these files, you need to use a program such as gs or gv. On Windows and Macs, you can also open these files in Adobe Illustrator, or convert them to PDF with adobe distiller (both programs cost $$). Alternatively, if you have cygwin installed on your windows machine, you can convert these figures to PDF using 'ps2pdf' just as you can in linux.

  • Further help: Further help can be found by searching and reading the GMT listserv archive. If this doesn't answer your problem, you can always sign up and post a question, and hope that someone has a useful answer.

Our First GMT Script:

    While GMT programs can be called on the command line, just like most other UNIX programs, it is generally, much more beneficial to put the collection of commands in a script. Doing so will allow you to recreate and modify figures rather quickly as the need arrises.
  • Script naming: As a convention, I normally name my GMT scripts with the '.gmt' extension. While, this is not required, it would be very beneficial if you were to decide on a naming convention and stick with it.

  • For our first plot, lets make a simple map of the USA. I usually set up variables at the beginning of my script so that I can call use them over and over again. Try to recreate USA.gmt 
    #!/bin/bash
# GMT script to plot the USA
# AVN
# Last modified Mon Oct 23 16:46:24 EDT 2006

## DECLARE YOUR VARIABLES HERE ##
#################################
  SCALE=18                  # make plot 15 cm across
  LONMIN=-133. ; LONMAX=-60. # Longitude range of plots
  LATMIN=20.  ; LATMAX=55. # Latitude range of plots
  OUTFILE=$0.ps                 # Output file
#################################

# CREATE A LETTER SIZE BOUNDING BOX
gmtset PAPER_MEDIA letter PLOT_DEGREE_FORMAT D
###########################################################
pscoast -R$LONMIN/$LONMAX/$LATMIN/$LATMAX -JM$SCALE -B10a20WSen -Dl -Na -A1000 -W2 -Y10 -X2 -P > $OUTFILE

exit 0
  • Run Script: After making the file executable using 'chmod', run the script by simply typing: 
    % USA.gmt   # if there is no output to the shell, then the program likely worked
  • View results: using either 'gs' or 'gv' we can view the newly created postscript file by typing: 
    % gv USA.gmt.ps   # type 'q' on gv window to quit
# or 
% gs USA.gmt.ps   # type 'quit' on GS> prompt within shell window to quit
    This can also be added to the gmt script to bring the plot up automatically.
  • Files created: While it may appear that only a new postscript file was created, using the '-a' flag with 'ls' will reveal that an additional two files were created.
    • .gmtcommands4: This file contains a list of gmt command modifiers (flags and arguments) that can be used the next time a GMT program is called. This is only useful for a few of the most common flags, including B, J, R, X, Y. This may be better explained in the online documentation.

    • .gmtdefaults4: This file is read and potentially modified or recreated every time a GMT command is run. The file contains a bunch of information that describes how you want your output to look. In the above example, we explicitly stated that we wanted the figure to go on letter sized paper and that our degrees are marked with floating point degrees (decimal degrees with as many zeroes as necessary).
      Note that often if your figure is of the wrong size or otherwise misbehaving in odd ways, it may be because of a different locally set .gmtdefaults4 file. You can put a copy of this file in your home directory, which the program should read before creating a figure.

Script Modification:

    The rest of this will be done in class. I plan on showing you other conventions that I use to make GMT scripting easier, as well as working with you on a couple of the examples in the online tutorial.
Advanced Topics:
Home | anewmangatech.edu | Updated: Mon Nov 13 12:30:39 EST 2006