Easily install and use Generic Mapping Tools (GMT) on Mac OS X

There has been a long hiatus in my posts due to the time pressures of completing a PhD. So I hope to post somewhat more frequently with some tips and tricks that I have come across that might be useful to others.

One of the most important tools I have used in my studies, and my work, has been Generic Mapping Tools (GMT). GMT is a collection of open-source applications for plotting, processing and analyzing data – in geosciences, but also more generally. Essentially, if you use MS Excel (or similar) and like the idea of automating your data processing and plotting (without relying on somewhat dubious Macros), then GMT is something you should consider. If you use ArcGIS, QGIS or any other GIS tool, then GMT could be a partial or complete replacement for the plotting component of your work, or at least a great complementary tool. With GMT it becomes easy to create a workflow that will produce clean and “publication-quality” plots, that is easy to modify and share. GMT is also a community tool – with development led by Pål (Paul) Wessel, Walter H.F. Smith, Remko Scharroo, Joaquim F. Luis and Florian Wobbe (thanks guys!), and you can get all the information you need from the GMT website. You can also read an EoS article describing GMT, as well as watch video podcasts describing GMT through iTunes University.

Installing GMT used to be more complicated, but the development team has made it much easier to get started quickly. There’s a number of suggested ways of installing GMT, everything from compiling the latest code available from SVN, to pre-compiled binaries. From my experience, installing and using GMT is generally much easier on Unix-like systems (Mac OS X, Linux, etc.) than Windows. If you are on Windows, it may be easier to install Linux in a Virtual Machine than using Cygwin – but I would love to hear your experience in running GMT in Windows.

I have successfully compiled GMT from source, but it can be time-consuming to get all the dependencies – and so the workflow below, using package managers, is what I would recommend for Mac OS X users. Similar package managers exist for Linux. Let me know if you have a better way!

System setup

Users with a clean install of Mac OS X will need to install XCode and XCode command line tools. First, go to the App Store, and download and install XCode. Once it is ready (it can take a long time!), open XCode and accept any user agreement. In the Terminal type in xcode-select --install. Accept the XCode command line tools end-user license by typing sudo xcodebuild --license and following the instructions in the Terminal. You will only have to do this once.

Installing GMT4 and GMT5

The latest version of GMT is GMT5, but I recommend also having GMT4 on your system for backwards compatibility. The package manager I use is Macports (although Fink and Brew also likely have GMT). Package managers allow you to easily install software that might have complex dependencies. In this case, GMT depends on GDAL, GhostScript, NetCDF, GSHHG shorelines, and so on – which can be tedious to obtain and compile individually. The steps below will do everything in one go. To start, download and install Macports.

1. Launch the Terminal
2. Type in “sudo port selfupdate” to get Macports updated to the latest version
3. To install the latest version of GMT4 with all necessary bundles (including netCDF, gdal, ghostscript, gshhg, etc.) type in “sudo port install gmt4”
4. To install the latest version of GMT5 with all necessary bundles (including netCDF, gdal, ghostscript, gshhg, etc.) type in “sudo port install gmt5”.

Steps 3 to 4 can take some time (so make sure you have some time, and your laptop connected to mains power), but the whole process is automated. When you want to use GMT4, well just type in “psxy …”, “ps2raster …”, etc. When you want to use GMT5, type in “gmt psxy …”, “gmt ps2raster …”, etc., which allows you to use both GMT4 and GMT5 without using GMTSWITCH.

You will likely need to update your PATH variable. If you cannot launch GMT then you may need to add the default directory “/opt/local/lib/gmt4/bin/” and “/opt/local/lib/gmt4/bin/” to the PATH variable within “.bash_profile” or “.bashrc”. This link explains how to change the PATH variable using the Terminal.

Upgrading to new versions of GMT

Upgrading GMT using Macports is easy. In the Terminal, first run “sudo port selfupdate”. To upgrade all of your installed ports, type in “sudo port upgrade outdated”. If you want to just upgrade gmt, type in “sudo port upgrade gmt5”. For more info on common commands in Macports, check out this link.

Warning on netCDF

For those of you upgrading from GMT4 to GMT5, beware that the version of netCDF has changed. In GMT 4.5.8 or earlier, the default netCDF version was 3.x.x, while since GMT 4.5.8 the netCDF version was 4.x.x, meaning that the default type of GMT netCDF grids created has significantly changed. If you make a grid using a recent version of GMT4 (i.e. GMT 4.5.11) or GMT5, then that grid by default cannot be plotted or used by someone who is still working with GMT 4.5.8 or older. If you make grids that use the recent versions of netCDF, you can easily convert them to the “classic” and compatible grids, by running the following command:

“nccopy -k 1 $in_grid $out_grid -V”

The ‘nccopy’ application gets installed with GMT5, and is part of the netCDF bundle.

Final thoughts

GMT has been a critical piece of infrastructure for a lot of my work over the years, and will surely remain very important into the future. The frequent updates and a vibrant user community will ensure GMT remains relevant to a wide range of science data processing and plotting requirements. To close, here is a sample animation that I made using a combination of GPlates (plate tectonic reconstructions), GMT (plotting) and FFMPEG (for stitching frames into an animation – also available via Macports).