3. Basic Concepts and Terms

GMT inherits the way of how the UNIX system manipulates data. For those who have some experience using Unix shell or cmd, GMT is easy to get started. If you never used anything like that, don’t worry about it. This section will introduce some essential concepts for using GMT, which makes you get into the swing of it.

In addition, we will also introduce file formats that are associated with GMT. If it’s your first time using geospatial data, there should be some terms worth to look up at any time.

3.1. UNIX environment

3.1.1. Terminal

Although all the system platforms adopt a graphic interface (desktop) as the default user interface, You still can use command-line tools to get control over your computer. The easiest way to do this is to open a built-in program on the desktop environment. The program is called cmd on Windows, or terminal on Mac or most Linux systems. In this tutorial, to “open the terminal (app)” means to control your computer using a command-line tool. On Windows XP or later versions, there are actually two terminals on a single platform: cmd and “PowerShell.” The latter enables the usage of Unix shell’s syntax. In this tutorial, we always put a prompt sign at every command you need to type on the terminal

$

The words after the $ symbol are what users actually type. If you got any questions on how to open the terminal on your system platform, please check up related textbooks and webpages for the detailed step-by-step.

3.1.2. Shell

Generally speaking, a shell refers to the interface between a user and a machine such as your PC. That means either the Desktop environment on Windows or the command console on other platforms counts. The way to interact with a computer varies from different shells. Let’s take the text-based shell for instance: a user needs to type a pre-defined command to make the computer work. GMT was initially designed and built on a famous command-line shell called sh, but now it has been developed and transplanted into other shells on other platforms, like the cmd on Windows. Nevertheless, GMT has remained its original style in terms of the syntax. It is recommended to learn the shell syntax together with the GMT commands. If you would like to learn more about the shell syntax, there are many textbooks or online sources that are comprehensive and well-written, like Ryans Tutorials. Getting some knowledge of shell would definitely make you more confident with GMT.

Tip

There’s a syntax worth mentioning here: the comment mark #. For example:

$ gmt grdinfo yourfile.grd     # view info of the file

The words following the # are the additional description of the command. In this tutorial, we will use the format to make our scripts easier for reading.

3.1.3. Scripts, aka Batch files

Whenever you press Enter on a command console, the computer starts to run the command you just put immediately. A user, however, can also opt to write down all the commands in a single text file, and type the name of the text file into the command line, then the computer would read the content and runs over all commands in order. On Windows, these files are called “batch files,” but they are also usually called “scripts” on Bourne shell or other related shells. They have the same function no matter the names they bear. In this tutorial, we choose to call them “scripts” regardless of platforms for the best readiness. You usually have many ways to get your script run, and there is also some difference among platforms in terms of processing details. I recommend the following several ways to do this.

  • Windows: change the file extension from .txt to .bat, and double-click the file. Windows will automatically open cmd and run it. You can also put the following line at the bottom of your file

    ...(your commands)
pause

    pause command prevents cmd from closing the command window after running the script. It makes you be able to check the progress of all the commands in your script before manually closing the window.

  • Unix-based system (Linux, Mac, etc.): there’s no regulation of file extension, but I usually prefer using .sh, .csh, or .bash, depending on which shell you are going to use. Take bash as an example; it is convenient to put this at the first line of the script (it’s called sheband):

    #!/bin/bash
...(starting your commands)

    And then change the file permission at the command prompt

    $ chmod +x yourscript.bash

    And now you can run your script by typing this:

    $ path_to_your_script/yourscript.bash

In this tutorial, all the GMT scripts are written in bash format. Although the GMT commands never change through platforms or shells, you still need to be aware of the syntax that varies with the shell. If you are using other shells than bash (like csh, tcsh, cmd, Power Shell…), you may have to modify the script a little bit so it adapts to another shell. This is especially true for operations like assigning variables, looping, reading and writing some files, and text-file processing.

For the PyGMT scripts in the tutorial… of course, they are written in Python!

3.2. Geospatial data

3.2.1. NetCDF

NetCDF, or “Network Common Data Form,” is a data type developed by UCAR (University Corporation for Atmospheric Research). First released in 1989, the initial goal of NetCDF is to provide a standard for scientific data storage, as it’s convenient in terms of data sharing. In addition to data format, UCAR has also released a set of modules and libraries that enable users to access data with different environments or programming languages. NetCDF is the main file format GMT supports, commonly seen as the .nc extension, but sometimes .grd is also used for clarifying its data structure. NetCDF data are saved in binary value, with a text-based header (also usually called as “metadata”) for describing associated data. The advantage of NetCDF format is that the data have nothing to do with your system’s byte order, and that’s great news since you don’t have to worry that people can’t read your data correctly when you are sharing files with them. For more details, please go to the NetCDF website.

3.2.2. Geodetic datum

A geodetic datum is a set of parameters for describing the shape of the Earth. We need it to calculate the coordinates of any place on the Earth. The most common geodetic datum now is WGS84 (aka EPSG:4326), which is also adopted by GPS satellites.

In WGS84, the shape of the Earth is defined as an oblate spheroid with flattened poles. The center of the oblate spheroid is at Earth’s center of mass. This shape is often called the WGS84 reference ellipsoid. When calculating the surface coordinates, the latitude zero is set at the equator, and the longitude zero is a little bit away from the Royal Observatory in Greenwich.

In a nutshell, we use geodetic datum to set up coordinates (Latitude, Longitude, Height) at any location on the Earth. The default datum of GMT is WGS84, and you can also check the current datum by this command:

$ gmt defaults -D    # inside the block of Projection Parameters

WGS84 uses the difference between the surface and the geoid as the altitude of the surface. Currently, WGS84 adopts EGM96, a gravitational model, as the standard of geoid.

Attention

A geodetic datum doesn’t define the basis of vertical elevation. It means users have to determine how to measure the altitude of topography. There are two commonly used standards:

  1. Measure the vertical difference between topography and the reference ellipsoid. This is called Ellipsoidal Height.

  2. Measure the vertical difference between topography and sea surface (geoid). This is called Orthometric Height or Geoid Height. EGM96 is the most commonly used gravitational model for deriving geoid location.

Data based on WGS84 usually use Orthometric Height to represent elevation, but not all data follow this convention. If it is required to have a small uncertainty on elevation, like within 10 meters, it would be better to check which way the height was measured.

3.2.3. Projection and Projected Coordinate System

Unlike the curved surface of the Earth, most maps are flat. Moreover, it would be awkward to use Lat/Long for a regional map because 1 degree is usually around 110 km, which is way larger than the size of many cities and towns. Therefore, in many cases we would stretch and flatten the Earth’s surface using a specific projection (which is actually a set of geometric formulae). Any location on a map can thus be written as a 3-D coordinates (X, Y, Height). This way to represent geographical locations is called Projected Coordinate System.

We need both the shape of Earth (aka reference ellipsoid in the geodetic datum) and a projection to make a (projected) coordinate system. The most popular projection coordinate system is UTM, or Universal Transverse Mercator, which uses WGS84 ellipsoid. It cuts the Earth into 60 zones (except the polar region), and apply the Transverse Mercator projection to each zone with different coordinate origin.

For more introductions on projections and projected coordinate systems, ArcGIS online webpages provide good explanations over these topics.

Note

In addition to WGS84, there are other two widely-used sets of geodetic datum called TWD67 and TWD97 for regional maps of Taiwan. The corresponding projected coordinate systems are TWD67-TM2 and TWD97-TM2, respectively. Both two sets adopt a different reference ellipsoid from WGS84, but TWD87 has a greater offset, which often results in a distance of 0.1-1 km from WGS84 Lat/Long. TWD97, on the other hand, is relatively close to WGS84, with only a range of several tens of centimeters. 1

3.3. The new syntax mode in GMT 6

GMT 6 is released in 2019 and is the latest version of GMT. It is also the version this tutorial is based on. It introduces a brand new system of syntax, called the Modern Mode, to highlight the difference from the old syntax GMT 5 was using (called the Classic Mode). In the modern mode, GMT saves its PostScript-formated map into a temporary file, and directly generate a vector PDF or an image PNG/JPG to the user. This way greatly reduces the complexity of a GMT script. I have listed some major differences between the modern mode and the classic mode here: 2

  • GMT commands no longer use UNIX’s redirecting symbol > to save a map to a .ps file.

  • Users don’t need to use -O and -K to “connect” multiple GMT commands anymore.

  • Because you can now directly specify many different map formats, it saves your time from converting your final maps.

  • The map size is no longer fixed to the paper size. Instead, GMT now automatically crops the map to the plotting area. Thus, you don’t need the -P option anymore.

  • Many commands starting with ps have changed their names. Most of them just have the ps removed, but few of them have a completely new name now. For example, psxy in GMT 4-5 is plot in GMT 6.

  • In the modern mode, you have to use gmt begin and gmt end to wrap the other plotting commands. You cannot find these two commands in the classic mode.

  • Now you don’t need to repeatedly list map extent -R and projection -J in each GMT command.

  • There is a new command called subplot to expedite the task to make multi-frame maps.

To make the backward compatibility, in GMT 6 you can use either modern mode or classic mode to write your script. Because there are many advantages of the new syntax, for this tutorial I use the modern mode syntax to create maps. However, I will also provide a link to the script using the classical mode and the associated instruction in some chapters for your reference.

If you are already using GMT 5, then you might want to update to GMT 6 right now because the new version supports almost all GMT 5 syntax (as the classic mode).

If you are already using GMT 4, the following cases show the difference between GMT 4 and GMT 6 (classic mode) in terms of commands:

$ pscoast options...       # pscoast command in GMT 4
$ gmt coast options...     # In GMT 6, it is replaced by the coast command, which is a module of the main gmt command.
$ gmtset options...        # gmtset command in GMT 4
$ gmt set options...       # In GMT 6, it is also replaced by the set command, which is a module of the main gmt command.

However, when installing GMT 6 the system would ask you if you want to generate shortcuts for all the gmt modules. If you choose Yes, then you can use the GMT 4 syntax in GMT 6 (i.e., GMT can make system understand the old GMT commands such as pscoast).

3.4. The working environment of PyGMT

3.4.1. Python and PyGMT

Python is the most popular programming language at the present time. If you are interested in learning Python, there is a lot of onboarding resources available online. Thanks to its popularity, there has been an idea in the GMT user community: it would be great if we could access GMT through Python. GMT is based on the C programming language, which means you have to use an API (Application Programming Interface) to access the GMT library in Python. The GMT’s API is essentially some code, and it is analogous to the adapter for different cables. In other words, the API makes the GMT library understand the control commands from Python. PyGMT uses such an API, sends tasks to GMT, and converts the return values (data, map, etc.) into some Python-compatible formats. We also call this kind of software package a wrapper library.

3.4.2. The PyGMT syntax

PyGMT treats a map as an object and executes all the plotting commands through the object’s methods. For example, you have to use this way to run the coast command in GMT 6:

import pygmt                # First off, you have to import the PyGMT module!
fig = pygmt.Figure()        # Make a map object
fig.coast(options...)
# Finally, use fig.show() to show the map on the screen, or use fig.savefig(...) to save to disk

GMT uses the UNIX-style “flags” to assign various options of the coast command, for example, -R and -J. In PyGMT, These flags are all changed to a more meaningful name and are passed into the object method as an argument. For example, -R is renamed as region, and -J corresponds to projection. Here are some more translations from Make Your First Map:

# When using GMT... (in a shell script)
gmt coast -R... -J... -W... -G... -B...
# When using PyGMT... (in a python script)
fig.coast(region=..., projection=..., shorelines=..., land=..., frame=...)

In the PyGMT user manual, you can check the more detailed parameter list and their aliases.

3.4.3. Jupyter Notebook and Binder

This tutorial uses two different formats for PyGMT scripts. In addition to the traditional pain text rendered as HTML, I also provide them as Jupyter Notebooks as well as their Binder links. The Binder link will lead you to a server that installs a PyGMT environment for you, and you can run, modify, and try these PyGMT scripts using your web browser. I currently use the service from MyBinder.org which uses the cloud computing resources at Amazon Web Services so that everyone can try PyGMT without installing it. Feel free to give it a try!

1

Taiwan datums, OSGeo Wiki.

2

Wessel, P., Luis, J., Uieda, L., Scharroo, R., Wobbe, F., Smith, W. H. F., and Tian, D. (2019). The Generic Mapping Tools Version 6. Geochemistry, Geophysics, Geosystems, 20. doi.org/10.1029/2019GC008515.