The Generic Mapping Tools Version 6

The Generic Mapping Tools (GMT) software is ubiquitous in the Earth and ocean sciences. As a cross‐platform tool producing high‐quality maps and figures, it is used by tens of thousands of scientists around the world. The basic syntax of GMT scripts has evolved very slowly since the 1990s, despite the fact that GMT is generally perceived to have a steep learning curve with many pitfalls for beginners and experienced users alike. Reducing these pitfalls means changing the interface, which would break compatibility with thousands of existing scripts. With the latest GMT version 6, we solve this conundrum by introducing a new “modern mode” to complement the interface used in previous versions, which GMT 6 now calls “classic mode.” GMT 6 defaults to classic mode and thus is a recommended upgrade for all GMT 5 users. Nonetheless, new users should take advantage of modern mode to make shorter scripts, quickly access commonly used global data sets, and take full advantage of the new tools to draw subplots, place insets, and create animations.


Introduction
The Generic Mapping Tools (GMT) have many tens of thousands of users worldwide. Most users around the world (approximately two thirds) use GMT under Windows (and with Ubuntu bash for Windows 10 gaining traction, this fraction may increase) followed by macOS and Linux, whereas in the United States the dominant operating system for GMT users appears to be macOS. GMT has been around for almost 30 years and it is embedded in many mission-critical workflows. GMT is widely used in marine geology and geophysics (e.g., Müller et al., 2016), solid earth geophysics (e.g., Ritsema et al., 2011), geodesy (e.g., McClusky et al., 2000, geodynamics (e.g., Steinberger et al., 2004), oceanography (e.g., Key et al., 2004), and planetary sciences (e.g., Smith et al., 1999). GMT is also a prerequisite foundation for other high-level tools used by the scientific community, including MB-System (Caress & Chayes, 1996) for multibeam bathymetry and backscatter processing and GMTSAR (Sandwell et al., 2011) for interferometric radar processing.
GMT version 1 was first released informally in 1988 at Lamont-Doherty Earth Observatory while the founders Paul Wessel and Walter Smith were still in graduate school. At that time, the tools spread slowly as visiting scientists and graduating students took copies of the software with them on magnetic tape. Most users became familiar with GMT in 1991 when version 2.4.1 was released and announced via an article in EOS (Wessel & Smith, 1991). Minor updates were released a few times each year, while every few years, major new versions were released, such as GMT 3 (Wessel & Smith, 1995, 1998) and GMT 4 (2004. It took almost 10 years for the next major release [version 5;Wessel et al., 2013], as it included a major migration to a C-language Application Program Interface (API).
With this article, we present and discuss the latest major release of GMT, version 6, which has been in development for 3 years. In many ways it is our most ambitious release as it seeks to strengthen GMT while retaining compatibility with the myriad of existing GMT scripts that have been written to date. At the same time, it seeks to break new ground in order to simplify how GMT can be used by new and experienced users alike. In order to accomplish these two goals GMT 6 now supports a "classic mode," which runs exactly like GMT 5 and so offers full backward compatibility, and a "modern mode," which allows new features and shorter and simpler scripts, so that GMT is now easier to learn. Our design challenge has been to make all of this seamless, backward compatible, and cross platform.

GMT Philosophy and Design
GMT began as a UNIX command-line tool set. GMT modules were designed to mimic UNIX programs which act as filters: Input is sent via standard input and output is returned via standard output. This design makes it easy to combine GMT (and other) processes by redirecting the output of one module as input to another. Output data may be composed by combining the results from several modules, using UNIX redirections to append various outputs to any one data file. GMT employed this design for drawing illustrations as well as analyzing and filtering data. Since plotting tasks were distributed across many modules, GMT modules needed to coordinate in order to produce a complex illustration. PostScript was GMT's graphics language from the beginning, and so GMT had to ensure that the final PostScript file, being an executable program with a particular syntax, was assembled in the correct order, regardless of how the GMT tools had been combined to create the illustration. This gave GMT the power of flexibility but also posed a challenge to users.
Individual GMT modules were coded as stand-alone executables, just like UNIX programs. However, the release of GMT 5 (Wessel et al., 2013) introduced three key changes: (1) We provided a fully documented API for building new tools and libraries on top of GMT modules and functions. The API contains basic functionality for handling GMT data objects (i.e., the input/output of data), manipulating module options, reporting of errors and warnings, and accessing any of the~120 modules. Unlike the previous GMT 4 version, these modules are no longer stand-alone programs but are implemented as high-level functions in the API. (2) We addressed issues with "namespace pollution", that is, how to manage lots of different program executables in a standard installation directory (such as /usr/bin) when there might be many other tools with exactly the same names. For instance, there are already other software packages that distribute programs called "surface" or "triangulate" and that means they are competing for installation in the same directory as GMT when software is installed via standard software package managers. By building just a single executable called gmt (that we use to access all modules) and by requiring users to run "gmt triangulate" instead of just "triangulate", we avoid this conflict. A few shell functions implement backward compatibility with older GMT 4 scripts that do not use the gmt executable. (3) We generalized the notion of input sources and output destinations. In addition to the familiar mechanism of passing file names or using standard input/output, developers using the API can specify the sources of input and/or the destinations of output in several different ways, including memory locations, file pointers to open files or standard streams, and file descriptors. The GMT modules themselves are unaware of these distinctions since this flexibility is implemented in the API input/output layer. Consequently, the new GMT API has made it possible for developers to build additional tools or external libraries on top of the core API ( Figure 1). This change allowed for rapid development of new and complex functionality, such as discipline-specific processing not presently available in the main GMT tool chest (e.g., Wessel et al., 2015).
At present, there are three lines of development using the GMT API: (1) The GMT/MATLAB Toolbox (Wessel & Luis, 2017) targets MATLAB users who want full access to GMT modules while working in the environments of MATLAB or Octave.
(2) The PyGMT library (Uieda & Wessel, 2017) allows Python programs to call GMT modules, including in interactive environments like the Jupyter notebook. (3) The GMT.jl package  similarly allows Julia users access to GMT from its environment.
The intertwined use of GMT, MATLAB, Python, and Julia encapsulates the modern working environments of major groups of scientists, especially those operating within the Earth, ocean and planetary sciences. While GMT continues to be predominantly used from a UNIX shell environment (such as Ubuntu bash for Windows 10, macOS, or a Linux flavor like Ubuntu or CentOS), we expect this to change as the interactive environments provided via notebooks continue to improve and grow market share.

Modern Versus Classic Mode
For almost three decades, GMT scripts written in new releases have looked remarkably similar to those written in earlier releases. The main option flags and the general workflow of adding overlays to existing PostScript files have remained unchanged, and thousands of GMT scripts written in c-shell, bash, DOS batch, and other environments exist and their maintainers expect them to run in the future. This requirement of backward compatibility has, to some extent, stifled our desire to make GMT easier and safer to use. The dilemma is captured in the rallying cry from many a frustrated GMT user: "Make things simpler but don't change anything!" Having run dozens of courses introducing GMT to students and scientists and helped thousands of practitioners via email or user forums over the years, we have a clear idea of what is difficult about learning GMT. Given its almost limitless capabilities, GMT has always had a fairly steep learning curve. The hardest aspects that have percolated to the top of the pitfalls list include the following: (1) GMT "cake baking": Handling the use of -O, -K, and -P to manage PostScript overlays; (2) The PostScript redirection: Creating a new file versus appending to an existing file; (3) Reusing the current region (-R) and projection (-J) in multistep scripts by repeating the empty -R -J settings for every command; (4) Converting the PostScript plot to more desirable graphic formats, such as PDF; and (5) Positioning multipart figures (e. g., a matrix layout) is a tedious and error-prone operation.
While pondering these facts, we also started to gain experience with the GMT/MATLAB Toolbox and the ongoing design of the PyGMT library. We were noticing that the resulting scripts looked too similar to the GMT shell command-line versions, setting users up for a continuation of the same pitfalls. We have decided that the best possible solution to this conundrum is to introduce different run modes that can be enabled by the user. Starting with GMT 6, we introduce a new operating mode for GMT named modern. In contrast to the classic (and only) mode available in earlier versions, modern mode was designed to eliminate some of the most challenging aspects of learning and using GMT. Depending on how a GMT script is started it will either be running in classic or modern mode. Classic mode is the GMT scripting style in use for decades and it will remain the default mode for command-line work. In contrast, modern mode imposes simpler rules that eliminate the possibility of the listed pitfalls; therefore, it promises to simplify scripting considerably across all interfaces. It also imposes a more rigid structure, and hence, not every single classic script may be represented using modern mode rules. Consequently, modern mode is slightly less flexible but much easier to use, and we expect it will serve the needs of almost all GMT users. We will strongly encourage new users to use modern mode.
To defeat the pitfalls listed above, here are the key design features of modern mode: 1. The -O, -K, and -P options are no longer needed nor available. 2. Plotting modules no longer write PostScript to standard output which users must redirect. Instead, they write to hidden temporary files. GMT 6 checks the status of these files to know whether it is creating a new illustration or appending to an existing one. 3. In modern mode, the entire workflow runs in a unique temporary directory where its settings and history are kept. Hence, numerous scripts can execute simultaneously without interfering with each other, and we can use the history information to automatically supply missing region (-R) and projection (-J) arguments. 4. When the workflow ends, the hidden PostScript files are automatically completed and converted to the chosen graphics format, which defaults to PDF for command-line work. In fact, more than one output format may be selected, for example, PDF and PNG. 5. Page size is now automatically determined regardless of map size and is properly cropped to fit from the initial (and maximum) canvas size of 32,767 × 32,767 points. 6. New modules figure, inset, and subplot automate the design and plotting of multiframe illustrations, while modules movie and events simplify animations. We will highlight these new modules in this paper.
An example comparing a simple script written in both classic and modern modes is shown in Figure 2. Note how the show option to gmt end will display the plot in the default viewer program for the user's operating system.
Not only does modern mode significantly reduce the greatest obstacles to GMT learning, it greatly simplifies scripting by eliminating needless repetition of options and output filenames. Modern mode is activated and deactivated by the new GMT modules begin and end, respectively. Since these are not part of

New Modules Under Modern Mode
While classic mode remains unchanged (except for new options to some modules), modern mode comes with a set of new modules. We have already introduced begin and end. The former starts a new GMT modern mode session, can name the final illustration (if a plot is produced), and set what types of graphic formats to use (default is PDF). The end module finalizes any illustrations before the session terminates. If your session needs to make several separate illustrations then the figure module handles the naming of such figures, graphics formats, and selects which figure is currently active. Making multipanel illustrations in GMT classic mode requires patience and layout calculations. In modern mode the subplot module simplifies this process.
The inset module allows you to partition a section of a panel to be used for an inset map. When you are finished with plotting the inset, the projection and region are reset to the main map. Finally, we introduce movie which simplifies the art of creating animations, and events which works with movie to plot the evolution of events (e.g., earthquakes).
In contrast to classic mode, modern mode does not necessarily produce PostScript output, hence many module names starting with "ps" become nonintuitive in modern mode. We have therefore renamed the plotting modules for modern mode only. For most, we have simply removed the leading "ps" (e.g., pscoast becomes coast), while three have a new name entirely (psxy becomes plot, psxyz becomes plot3d, and psscale becomes colorbar). If classic module names are used in a modern mode script, we issue a warning but allow the script to continue.

External Reference Data Sets
GMT version 5.4 prototyped the concept of remote files but GMT 6 completes it. This mechanism allows users to specify a special file name (identified by a leading @-symbol) which tells GMT to look for the corresponding file in the user's GMT data directory. If it is not found, the file will first be downloaded from one of the GMT data servers. As we introduced this mechanism, we added gridded Earth digital elevation models (DEMs) of different resolutions, ranging from the NASA-produced 1 arc sec SRTM (Shuttle Radar Topography Mission) 1 × 1 degree tiles (which are automatically downloaded as needed, then stitched together to make a new user grid) up to a smooth, 1 × 1 degree global elevation grid via the special @earth_-relief_xxy file names. Here, the leading two digits xx indicate the 2-digit grid resolution, whereas the final y flag is indicating the resolution unit (m or s for arc minute or arc second, respectively). Thus, @earth_re-lief_01m indicates a request for NOAA's 1 arc min ETOPO1 grid (Amante & Eakins, 2008). The very first time a user specifies this name the entire grid will automatically be downloaded to the user's GMT data Figure 2. Example of (left) classic and (right) modern mode scripts that make the same final plot map.pdf. Modern mode has default settings for projections, excludes -O -K -P options, remembers projections and regions once set, and automatically converts PostScript to the desired graphics format (which defaults to PDF).

10.1029/2019GC008515
Geochemistry, Geophysics, Geosystems directory on their computer, then read from there, while subsequent requests access the locally cached file directly. This is the simplest and most seamless way to access global data sets of which we are aware. We maintain a list with all of the server data files' MD5 hash codes and sizes so that GMT can check if a file has changed on the server and thus should be refreshed and overwrite the locally cached (and outdated) version on the user's computer. Currently served from the SOEST server at oceania. generic-mapping-tools.org, we expect to solicit mirrors on each continent to speed up data downloads. Of course, the required local data storage space depends on the grid resolution and (in the case of SRTMs) the region selected, but for the regular global grids (15 arc sec and higher) a few Gb of space is more than adequate.
Remote files enter into the discussion in two other ways as well. First, GMT documentation that shows examples of how to run a module will use the remote file mechanism to obtain the example data file from the GMT servers, meaning that users can copy and paste examples and they will run as expected without modifications. Second, users can also specify a full and valid URL to a data set and GMT will obtain this file and place it in the cache directory like the other remote files; this also applies to web queries.

GMT Modern Mode Examples
Since GMT classic mode has been around for 30 years, we do not need to demonstrate it here. Instead, we will show four examples of modern mode use, including three that explore the remote file concept.

Coastline Map of Chile
Because the two-character ISO country code can be used in specifying a region, we can easily make a map with a region that suits Chile using the CL country code. However, that would yield a tight bounding box, hence we round to the nearest multiple of 5°in longitude and latitude. The resulting script is gmt begin Fig_3 png gmt coast -RCL+r5 -JM15c+du -BWSne -B -Gbeige -Sblue -N1/1p gmt end show where we have limited automatic annotations (-B) to the westside and southside (-BWSne), added national borders (-N1), and painted ocean (-S) and land (-G) separately. Because height will be much longer than width, we indicate that the map dimension (15c) sets the maximum dimension (+du). The resulting PNG illustration is shown in Figure 3. At first sight, these three lines look like a step backward. In classic mode, such maps could be made with one line since there are no begin and end calls. For longer plot sequences, the benefits of modern mode simplicity outweigh the added work of starting and ending with begin and end.

Shaded DEM of Madagascar
To demonstrate the use of the remote file mechanism we will make a relief image for Madagascar, including a color table. Our illustration (Figure 4)   Geochemistry, Geophysics, Geosystems which produces both a PNG and a PDF plot. There are several features to notice here, some of which contrast with how a similar plot would be made in classic mode. First, we select the 1 arc min remote DEM [which is the ETOPO1 data; Amante & Eakins, 2008] and request the nearest 2°bounding box for Madagascar. We implicitly select the geo color table which will be scaled to fit the range of the grid inside the region. This scaled CPT is saved as a session current CPT and is available to subsequent modules that do not specify a CPT name, such as our colorbar command. Next, we compute artificial shading from that data grid with default settings for angle and intensity (-I+d). We then draw the coastline and default map boundary (-B), then begin a map inset to place a globe showing the location of Madagascar (the width of "?" means we wish to fit the plot in the space provided by the inset automatically), then end inset mode, place a colorbar centered on top (-DJTC), scaled to km (+Uk) and annotated accordingly, before we end the session.

Four Pacific Island DEMs
Next, we show a more complicated example using the new module subplot. We desire to show four Pacific island DEM images using the 1 arc sec SRTM data from NASA. Our script, resulting in the PDF in Figure 5 gmt grdimage @earth_relief_01s -R-10/10/-10/10+uk -JA138:39W/10:29S/? gmt subplot end gmt colorbar -Bx -By+lm -DJTC gmt end show Inside this GMT modern mode session, we create a layout for a 2 × 2 subplot group where each subplot is 8 × 8 cm, with 0.1-cm margins (-M) between neighboring subplots and their annotations. We turn on automatic labeling of each frame (-A) using the default lower-case letters in row-order with a white, outlined box behind each label. Because each Pacific island (Kauai, Easter, Tahiti, and Fatu Hiva) has separate regions, each grdimage call needs to set its unique region and projection center. We use the azimuthal projection to set the center of each map and then use the -R region to specify a square area in kilometers centered on that point. We scale the terra color table to cover the full range of the relief and use subplot set to move focus to the next subplot (row,col) in the sequence. After ending the subplot we place a colorbar centered on top of the 2 × 2 set of subplots using the outside top center justification (-DJTC).

Animation of Earthquakes
Finally, we demonstrate the ease with which to make animations by obtaining all magnitude 5 or above earthquake events for 2018 and creating a daily event movie with 365 frames. Our script, resulting both in a master PDF shown in Figure 6 as well as an MP4 movie available online (Wessel et al., 2019), consists

GMT Code and Documentation
The GMT source code has been managed using version control systems since the 1990s. However, we have gone through many different systems, from SCCS, CVS, subversion, and as of August 2018 we are using git. All GMT development can be accessed on our GitHub page (github.com/GenericMappingTools), and all aspects of GMT, with links to everything from source to documentation on GitHub is found at this site (www.generic-mapping-tools.org). This site also maintains information on where and how to install GMT and how to contribute to the GMT project.

Future and In-Progress Developments
Some aspects of GMT development are ongoing and not finalized for the GMT 6 release. We are in the process of strengthening our map projection code by relying on PROJ.4, a generic coordinate transformation library that includes cartographic projections as well as geodetic transformations. Although GMT has always had its own projection code, the fact is that PROJ.4 has become the de facto projection library used by almost all free and Open Source projects. Because of this and the facts that its syntax is known to more people, that it supports more projection transformations and that in its recent evolution (PROJ.4 version 6) has seen the addition of the time dimension, we decided to start adopting PROJ.4 as the future projection library in GMT. This decision does not add any new dependency as we access it via its implementation through GDAL. The transition is not yet fully implemented as it requires deeper adaptations of the GMT machinery to plot the map frames, but it already works well for vector transforms. On the other hand, GMT 6 tries to maintain, to the extent possible, the compatibility with previous versions so we will accept both the classical -J GMT syntax as well as the typical PROJ.4 strings. For example, to do a Lambert Conformal Conic projection of a geographic point, users can now run echo 4.897 52.371 | \ gmt mapproject -J+proj=lcc+ellps=WGS84+units=m+lat_1=20n+lat_2=60n Making projected images is also possible but so far, the available subset is restricted mostly to cylindrical projections. Our second example plots a part of Africa using the Mercator projection: Under the hood we are laying the groundwork for optional long-format options in GMT. This means that instead of typing -RUK -JM12c one can choose to write --region=UK --projection=mercator+width=12c. This enhancement will affect all options throughout GMT and will make scripting syntax much more readable. It will also simplify the external interface parsers since they can pass such high-level syntax directly to the GMT module.
We are also expecting to build a stronger coupling with GDAL for reading vector data. Currently, GMT can read shapefiles via a system call to ogr2ogr which produces a temporary GMT/OGR format file that GMT can read. However, like our bridge to GDAL for reading grids and images, we are interested in building a similar bridge for vector data.