Writing scripts to build maps with the Generic Mapping Tools (GMT 5.1.x)

In the last tutorial, we made a simple map, which is what we’ll call “one layer”. What I mean by that is that the entire map was created with one command, and it is just an outline of the eastern United States. In reality, we will want to develop complex maps, with many layers that pointing to and highlight interesting features, places, or anything else you can think of.

Maps with many layers need to be built “from the bottom up”, i.e. later layers will cover the underlying layers (not unlike Steno’s law of superposition!). This is done in the way you probably already figured out, command after command. It may be fine to build a basic map by entering a few commands into the terminal in a specific order, but it quickly becomes cumbersome when maps have many layers and you have to re-enter each command again and again if you want to change anything from an early layer.

For that reason, scripting with GMT is a must. Essentially, we will write a “program” that can be executed line by line by your computer to build the map — this way, each time you want to change something, all you have to do is re-run the program and the map will update! Before we get into the scripting I need to explain the manner in which layering is done with GMT.

GMT uses PostScript to build maps, which means that you need to explicitly state whether you are going to have more layers following the present command, and that you want to overlay the output, not overwrite it. For example take the following three theoretical commands that would, together, produce the theroetically desired map:

gmt commandone -K > output.ps
gmt commandtwo -K -O >> output.ps
gmt commandthr -O >> output.ps

In the first command, we initialize the file output.ps and tell the file that there is more PostScript coming (the -K does this). In the second line, we create some more output, overlay (-O >>) the output, and state that more output is to follow; note that the -O switch does not need to be directly adjacent to the >> but both are necessary to properly overlay PostScript. The third line, we again tell the output to be overlayed, but this time, omit the -K switch to finalize the PostScript file after overlaying. I remember the necessary switches for what I want to do by saying in my head that I want to Keep the PostScript file open for more output and/or Overlay the output.

So back to script building, this part will depend on your system, but if you are running on Ubuntu like me, you will need to write the script for a Bash shell. To make a script:

cd into a new directory, wherever you desire, I’m going to make a folder in my home directory called “firstscript”. In there, I’ll make a script called “firstscript.sh” and then open it to edit it.

cd ~/firstscript
mkdir firstscript
cd firstscript
touch firstscript.sh

Inside the script file, we have to tell the file what shell to execute the script with: make the first line of you script #!/bin/bash. Let’s use the simple command echo to print whatever text we want from the script. We can create comments, or lines of text not to be executed, by beginning the line with a pound sign (#). Insert a comment describing what this script will do above the echo line. This makes the script read:

#!/bin/bash
# this script prints some text
echo "Hello World!"

Now, save the file. We need to change permissions to make it an executable file. Do this with the terminal command chmod 755 firstscript.sh. Execute the file: ./firstscript.sh.

You should see your text, “Hello World!” show up in the terminal window. Let’s apply this
to the Generic Mapping Tools with a very basic example.

Below, you will see a script that makes a map with GMT. Copy and paste it into a new shell script you create, or grab it from here (note: make sure the file has executable permissions!).

Make note of the different -K, -O, and >> positions. I’m not going to detail what each switch and argument does here, but if you want more information check out the manual page for pscoast here.

Click here for the next tutorial

Updated: