Changes

New Features in GMT 5.4

Between 5.3 and 5.4 we continued to work on the underlying API needed to support the modules and especially the external interfaces we are building toward MATLAB, Julia and Python. We have introduced the use of static analyzers to fix any code irregularities and we continue to submit our builds to Coverity for similar reasons. We have also made an effort to standardize GMT non-common option usage across the suite. Nevertheless, there have been many user-level enhancements as well. Here is a summary of these changes in three key areas:

New modules

We have added a new module to the GMT core called psternary. This module allows for the construction of ternary diagram, currently restricted to symbols (i.e., a psxy-like experience but for ternary data). The mgd77 supplement has gained a new tool mgd77header for creating a valid MGD77-format header from basic metadata and information determined from the header-less data file.

General improvements

A range of new capabilities have been added to all of GMT; here is a summary of these changes:

  • We have added a new lower-case GMT common option. Programs that read ASCII data can use -e to only select data records that match a specified pattern or regular expression.
  • All modules can now read data via external URL addresses. This works by using libcurl to access an external file and save it to the users’ GMT cache directory. This directory can be specified via a new GMT defaults called DIR_CACHE (and defaults to the sub-directory cache under the $GMT_USERDIR directory [~/.gmt]). Subsequent use of the same URL will be read from the cache (except if explicitly removed by the user). An exception is CGI Get Commands which will be executed anew each time. Both the user directory and the cache directory will be created if they do not exist.
  • Any reference to Earth topographic/bathymetric relief files called earth_relief_res.grd will automatically obtain the grid from the GMT data server. The resolution res allows a choice among 13 command grid spacings: 60m, 30m, 20m, 15m, 10m, 06m, 05m, 04m, 03m, 02m, 01m, 30s, and 15s (with file sizes 111 kb, 376 kb, 782 kb, 1.3 Mb, 2.8 Mb, 7.5 Mb, 11 Mb, 16 Mb, 27 Mb, 58 Mb, 214 Mb, 778 Mb, and 2.6 Gb respectively). Once one of these have been downloaded any future reference will simply obtain the file from $GMT_USERDIR (except if explicitly removed by the user).
  • We are laying the groundwork for more dynamic documentation. At present, the examples on the man pages (with the exception of psbasemap and pscoast) cannot be run by cut and paste since they reference imaginary data sets. These will soon appear with filenames starting in @ (e.g., @hotspots.txt), and when such files are found on the command line it is interpreted to be a shorthand notation for the full URL to the GMT cache data server.
  • We have added four new color tables inspired by matplotlib to the collection. These CPTs are called plasma, magma, inferno, and viridis.
  • We have updated the online documentation of user-contributed custom symbols and restored the beautiful biological symbols for whales and dolphins created by Pablo Valdés during the GMT4 era. These are now complemented by new custom symbols for structural geology designed by José A. Álvarez-Gómez.
  • The PSL library no longer needs run-time files to configure the list of standard fonts and character encodings, reducing the number of configure files required.
  • The gmt.conf files produced by gmt set will only write parameters that differ from the GMT SI Standard settings. This means most gmt.conf files will just be a few lines.
  • We have deprecated the -ccopies option whose purpose was to modify the number of copies a printer would issue give a PostScript file. This is better controlled by your printer driver and most users now work with PDF files.
  • The -p option can now do a simple rotation about the z-axis (i.e., not a perspective view) for more advanced plotting.
  • The placement of color scales around a map can now be near-automatic, as the -DJ setting now has many default values (such as for bar length, width, offsets and orientation) based on which side you specified. If you use this option in concert with -B to turn off frame annotation on the side you place the scale bar then justification works exactly.
  • The -i option to select input columns can now handle repeat entries, e.g., -i0,2,2,4, which is useful when a column is needed as a coordinate and for symbol color or size.
  • The vector specifications now take one more modifier: +hshape allows vectors to quickly set the head shape normally specified via MAP_VECTOR_SHAPE. This is particularly useful when the symbol types are given via the input file.
  • The custom symbol macro language has been strengthened and now allows all angular quantities to be variables (i.e., provided from your data file as extra columns), the pen thickness can be specified as relative (and thus scale with the symbol size at run-time), and a symbol can internally switch colors between the pen and fill colors given on the command line.
  • We have reintroduced the old GMT4 polygon-vector for those who fell so hard in love with that symbol. By giving old-style vector specifications you will now get the old-style symbol. The new and superior vector symbols will require the use of the new (and standard) syntax.

Module enhancements

Several modules have obtained new options to extend their capabilities:

  • gmt has new session management option that lets you clear various files and cache directories via the new commands gmt clear all|history|conf|cache.
  • gmt2kml adds option -Fw for drawing wiggles along track.
  • gmtinfo adds option -F for reporting the number of tables, segments, records, headers, etc.
  • gmtmath will convert all plot dimensions given on the command line to the prevailing length unit set via PROJ_LENGTH_UNIT. This allows you to combine measurements like 12c, 4i, and 72p. The module also has a new SORT operator for sorting columns and RMSW for weighted root-mean-square.
  • gmtwhich -G will download a file from the internet (as discussed above) before reporting the path to the file (which will then be in the user’s cache directory).
  • grd2xyz can now write weights equal to the area each node represents via the -Wa option.
  • grdgradient can now take a grid of azimuths via the -A option.
  • grdimage and grdview can now auto-compute the intensities directly from the required input grid via -I, and this option now supports modifiers +a and +n for changing the options of the grdgradient call within the module.
  • grdinfo adds option -D to determine the regions of all the smaller-size grid tiles required to cover the larger area. It also take a new argument -Ii for reporting the exact region of an img grid. Finally, we now report area-weighted statistics for geographic grids, added -Lp for mode (maximum-likelihood) estimate of location and scale, and -La for requesting all of the statistical estimates.
  • grdmath has new operators TRIM, which will set all grid values that fall in the specified tails of the data distribution to NaN, NODE, which will create a grid with node indices 0 to (nx*ny)-1, and RMSW, which will compute the weighted root-mean-square.
  • makecpt and grd2cpt add option -Ws for producing wrapped (cyclic) CPT tables that repeat endlessly. New CPT keyword CYCLIC controls if the CPT is cyclic.
  • mapproject adds a new -Z option for temporal calculations based on distances and speeds, and has been redesigned to allow several outputs by combining the options -A, -G, -L, and -Z.
  • psbasemap has a new map-insert (-D) modifier +t that will translate the plot origin after determining the lower-left corner of the map insert.
  • pshistogram has a new -Z modifier +w that will accumulate weights provided in the 2nd input column instead of pure counts.
  • psrose adds option -Q for setting the confidence level used for a Rayleigh test for uniformity of direction. The -C option also takes a new modifier +wmodfile for storing mode direction to file.
  • gmt_shell_functions.sh adds numerous new functions to simplify the building of animation scripts, animated GIF and MP4 videos, launching groups of jobs across many cores, packaging KMLs into a single KMZ archive, and more.

API changes

We have introduced one change that breaks backwards compatibility for users of the API functions. We don’t do this lightly but given the API is still considered beta it was the best solution. Function GMT_Create_Data now requires the mode to be GMT_IS_OUTPUT (an new constant) if a dummy (empty) container should be created to hold the output of a module. We also added two new API functions GMT_Duplicate_Options and GMT_Free_Option to manage option lists, and added the new constants GMT_GRID_IS_CARTESIAN and GMT_GRID_IS_GEO so that external tools can communicate the nature of grid written in situations where there are no projections involved (hence GMT does not know a grid is geographic). Passing this constant will be required in MB-System.

Backwards-compatible syntax changes

We strive to keep the GMT user interface consistent. The common options help with that, but the module-specific options have often used very different forms to achieve similar goals. We have revised the syntax of numerous options across the modules to use the common modifier method. However, as no GMT users would be happy that their scripts no longer run, these changes are backwards compatible. Only the new syntax will be documented but old syntax will be accepted. Some options are used across GMT and will get a special mention first:

  • Many modules use -G to specify the fill (solid color or pattern). The pattern specification has now changed to be -Gp|Ppattern[+bcolor][+fcolor][+rdpi]
  • When specifying grids one can always add information such as grid type, scaling, offset, etc. This is now done using a cleaner syntax for grids: gridfile[=ID[+sscale][+ooffset][+ninvalid]].

Here is a list of modules with revised options:

  • grdcontour now expects -Z[+scale][+ooffset][+p].
  • In grdedit and xyz2grd, the mechanism to change a grid’s metadata is now done via modifiers to the -D option, such as +xxname, +ttitle, etc.
  • grdfft has changed to -E[+w[k]][+n].
  • grdgradient modifies the syntax of -E and -N by introducing modifiers, i.e., -E[m|s|p]azim/elev[+aambient][+ddiffuse][+pspecular][+sshine] and -N[e|t][amp][+ssigma][+ooffset].
  • grdtrend follows trend1d and now wants -Nmodel[+r].
  • mapproject introduces new and consistent syntax for -G and -L as -G[lon0/lat0][+a][+i][+u[+|-]unit][+v] and -Lline.xy[+u[+|-]unit][+p].
  • project expects -Ginc[/lat][+h].
  • psrose now wants -L[wlabel,elabel,slabel,nlabel] to match the other labeling options.
  • pstext now expects -D[j|J]dx[/dy][+v[pen]].
  • psxy expects -E[x|y|X|Y][+a][+cl|f][+n][+wcap][+ppen].
  • trend2d follows trend1d and now wants -Nmodel[+r].

New Features in GMT 5.3

Between 5.2 and 5.3 we spent much time working on the underlying API needed to support the modules and especially the external interfaces we are building toward MATLAB and Python. Nevertheless, there have been many user-level enhancements as well. Here is a summary of these changes in three key areas:

New modules

We have added a new module to the GMT core called pssolar. This module plots various day-light terminators and other sunlight parameters.

Two new modules have been added to the spotter supplement: The first is gmtpmodeler. Like grdpmodeler it evaluates plate tectonic model predictions but at given point locations locations instead of on a grid. The second is rotsmoother which smooths estimated rotations using quaternions.

Also, the meca supplement has gained a new tool pssac for the plotting of seismograms in SAC format.

Finally, we have added gpsgridder to the potential supplement. This tool is a Green’s function gridding module that grids vector data assumed to be coupled via an elastic model. The prime usage is for gridding GPS velocity components.

General improvements

There are many changes to GMT, mostly under the hood, but also changes that affect users directly. We have added four new examples and one new animation to highlight recently added capabilities. There have been many bug fixes as well. For specific enhancements, we have:

  • All GMT-distributed color palette tables (CPTs, now a total of 44) are dynamic and many have a hinge and a default range. What this means is that the range of all CPTs have been normalized to 0-1, expect that those with a hinge are normalized to -1/+1, with 0 being the normalized hinge location. CPTs with a hinge are interpolated separately on either side of the hinge, since a hinge typically signifies a dramatic color change (e.g., at sea-level) and we do not want that color change to be shifted to some other z-value when an asymmetrical range is being requested. In situations where no range is specified then some CPTs will have a default range and that will be substituted instead. The tools makecpt and grd2cpt now displays more meta-data about the various CPTs, including values for hinge, range, and the color-model used.
  • We have consolidated how map embellishments are specified. This group includes map scales, color bars, legends, map roses, map inserts, image overlays, the GMT logo, and a background panel. A new section in the Cookbook is dedicated to these items and how they are specified. Common to all is the concept of a reference point relative to which the item is justified and offset.
  • We continue to extend support for OpenMP in GMT. New modules that are OpenMP-enabled are grdgradient, grdlandmask, and sph2grd.
  • blockmean, blockmedian and blockmode have a new modifier +s to the -W option. When used we expect 1-sigma uncertainties instead of weights and compute weight = 1/sigma.
  • filter1d: can now compute high-pass filtered output via a new +h modifier to the filter settings, similar to existing capability in grdfilter.
  • gmtconvert has a new option (-F) for line segmentation and network configuration. Also, the -D option has a new modifier +o that sets the origin used for the numbering of tables and segments.
  • gmtinfo has a new option -L for finding the common bounds across multiple files or segments. Also, the -T option has been modified (while still being backwards compatible) to allow dz to be optional, with modifiers +s forcing a symmetric range and +a offering alpha-trimming of the tails before estimating the range.
  • gmtmath has gained new operators VAR, RMS, DENAN, as well as the weighted statistical operators LMSSCLW, MADW, MEANW, MEDIANW, MODEW, PQUANTW, STDW, and VARW. Finally, we added a SORT operator that lets you sort an entire table in ascending or descending order based on the values in a selected column.
  • gmtselect has a new option -G for selecting based on a mask grid. Points falling in bins whose grid nodes are non-zero are selected (or not if -Ig)
  • gmtspatial has two new modifiers for the -Q option that allow output segments to be limited based on the segment length (or area for polygons) as well as sorting the output in ascending or descending order.
  • grd2cpt existing -F option now takes a new modifier +c for writing a discrete palette using the categorical format.
  • grdedit can now reset text items in the header via -D by specifying ‘-‘. Also, new -C option can be used to reset the command history in the header.
  • grdfft has a new modifier to the -E option that allows for more control of the power normalization for radial spectra.
  • grdmath also has the new operators VAR, RMS, DENAN, as well as the weighted statistical operators LMSSCLW, MADW, MEANW, MEDIANW, MODEW, PQUANTW, STDW, and VARW. In addition it gains a new AREA operator which computes the gridcell area (in km2 if the grid is geographic). Finally, operators MEAN, MEDIAN, etc., when working on a geographic grid, will weight the result using the AREA function for proper spherical statistics.
  • grdvolume can now accept -Crcval which will evaluate the volume between cval and the grid’s minimum value.
  • greenspline now offers a new -E option that evaluates the model fit at the input data locations and optionally saves the model misfits to a secondary output file.
  • makecpt can also let you build either a discrete or continuous custom color palette table from a comma-separated list of colors and z-values provided via a file, an equidistant setup, or comma-separated list. The -F option now takes a new modifier +c for writing a discrete palette using the categorical format.
  • pstext has new modifiers to its -F option that allows users to generate automatic labels such as record numbers of formatting of a third data column into a textual representation. We also allow any baseline angles to be interpreted as orientations, i.e., they will be modified to fall in the -90/+90 range when -F...+A is set.
  • psrose can now control the attributes of vectors in a windrose diagram via -M.
  • psxy have seen numerous enhancements. New features include decorated lines, which are similar to quoted lines except we place symbols rather than text along the line. Users also gain new controls over the plotting of lines, including the ability to add vector heads to the line endings, to trim back lines by specified amounts, and to request a Bezier spline interpolation in PostScript (see enhanced -W option). A new option (-F) for line segmentation and networks have also been added. Various geographic symbols (such as ellipses; -SE, rotatable rectangles -SJ; and geo-vectors -S=) can now take size in geographic dimensions, including a new geo-wedge symbol. We also offer one more type of fault-slip symbol, using curved arrow heads. Also the arrow head selections now include inward-pointing arrows. Custom symbols may now simply be a preexisting EPS figure. Many of these enhancements are also available in psxyz.
  • The spotter supplement now comes with the latest rotation files from EarthByte, U. of Sydney.

The API

We have spend most of our time strengthening the API, in particular in support of the GMT/MATLAB toolbox. A few new API functions have been added since the initial release, including GMT_Get_Pixel, GMT_Set_Index, GMT_Open_VirtualFile, GMT_Close_VirtualFile, GMT_Read_VirtualFile, GMT_Read_Group, and GMT_Convert_Data; see the API Introduction for details.

New Features in GMT 5.2

While the GMT 5.1-series has seen bug-fixes since its release, new features were only added to the 5.2-series. All in all, almost 200 new features (a combination of new programs, new options, and enhancements) have been implemented. Here is a summary of these changes in six key areas:

New modules

There are two new modules in the core system:

gmtlogo is modeled after the shell script with the same name but is now a regular C module that can be used to add the GMT logo to maps and posters.

gmtregress determines linear regressions for data sets using a variety of misfit norms and regression modes.

Four new modules have also been added to the potential supplement:

gmtflexure:
Compute the elastic flexural response to a 2-D (line) load.
grdflexure:
Compute the flexural response to a 3-D (grid) load, using a variety or rheological models (elastic, viscoelastic, firmoviscous).
talwani2d:
Compute a profile of the free-air gravity, geoid or vertical gravity gradient anomaly over a 2-D body given as cross-sectional polygons.
talwani3d:
Compute a grid or profile of the free-air gravity, geoid or vertical gravity gradient anomaly over a 3-D body given as horizontal polygonal slices.

In addition, two established modules have been given more suitable names (however, the old names are still recognized):

grdconvert
Converts between different grid formats. Previously known as grdreformat (this name is recognized when GMT is running in compatibility mode).
psconvert
Converts from PostScript to PDF, SVG, or various raster image formats. Previously known as ps2raster (this name is recognized when GMT is running in compatibility mode).

Finally, we have renamed our PostScript Light (PSL) library from psl to PostScriptLight to avoid package name conflicts. This library will eventually become decoupled from GMT and end up as a required prerequisite.

New common options

We have added two new lower-case GMT common options:

  • Programs that need to specify which values should represent “no data” can now use -d[i|o]nodata. For instance, this option replaces the old -N in grd2xyz and xyz2grd (but is backwards compatible).
  • Some modules are now using OpenMP to spread computations over all available cores (only available if compiled with OpenMP support). Those modules will offer the new option -x[[-]n] to reduce how many cores to assign to the task. The modules that currently have this option are greenspline, grdmask, grdmath, grdfilter, grdsample, sph2grd, the potential supplement’s grdgravmag3d, talwani2d and talwani3d, and the x2sys supplement’s x2sys_solve. This list will grow longer with time.

New default parameters

There have been a few changes to the GMT Defaults parameters. All changes are backwards compatible:

  • FORMAT_FLOAT_MAP now allows the use %’g to get comma-separated groupings when integer values are plotted.
  • FORMAT_FLOAT_OUT can now accept a space-separated list of formats as shorthand for first few columns. On output it will show the formats in effect for multiple columns.
  • GMT_LANGUAGE has replaced the old parameter TIME_LANGUAGE. Related to this, the files share/time/*.d have been moved and renamed to share/localization/*.txt and now include a new section or cardinal points letter codes.
  • IO_SEGMENT_BINARY is a new parameter that controls how binary records with just NaNs should or should not be interpreted as segment headers.
  • PROJ_GEODESIC was added to control which geodesic calculation should be used. Choose among Vincenty [Default], Andoyer (fast approximate geodesics), and Rudoe (from GMT4).
  • TIME_REPORT now has defaults for absolute or elapsed time stamps.

Updated common options

Two of the established GMT common options have seen minor improvements:

  • Implemented modifier -B+n to not draw the frame at all.
  • Allow oblique Mercator projections to select projection poles in the southern hemisphere by using upper-case selectors A|B|C.
  • Added a forth way to specify the region for a new grid via the new -R[L|C|R][T|M|B]x0/y0/nx/ny syntax where you specify an reference point and number of points in the two dimensions (requires -I to use the increments). The optional justification keys specify how the reference point relate to the grid region.

General improvements

Several changes have affects across GMT; these are:

  • Added optional multi-threading capabilities to several modules, such as greenspline, grdfilter, grdmask, grdsample, the potential supplement’s grdgravmag3d, talwani2d and talwani3d and x2sys’s x2sys_solve.
  • Optional prerequisite LAPACK means SVD decomposition in greenspline is now very fast, as is true for the regular Gauss-Jordan solution via a new multi-processor enabled algorithm.
  • Allow comma-separated colors instead of CPTs in options that are used to pass a CPT (typically this means the -C option).
  • Faster netCDF reading for COARDS table data (i.e., not grids).
  • When importing grids via GDAL the projection info is preserved and stored as netCDF metadata. This will allow third party programs like GDAL and QGIS to recognize the projection info of GMT created grids. Same thing happens when creating grids with grdproject.
  • Tools using GSHHG can now access information for both Antarctica data sets (ice-front and grounding line).
  • Tools that specify pens may now explicitly choose “solid” as an attribute, and we added “dashed” and “dotted” as alternatives to the shorthands “-” and ”.”.
  • Added three alternative vector head choices (terminal, square and circle) in addition to the default “arrow” style. We have also added the option for trimming the beginning and/or end point location of a vector, and you may now place the vector head at the mid-point of the vector instead at the ends.
  • All eight map embellishment features (map scale, color bar, direction rose, magnetic rose, GMT logo, raster images, map inserts, and map legends) now use a uniform mechanism for specifying placement, justification, and attributes and is supported by a new section in the documentation.
  • Typesetting simultaneous sub- and super-scripts has improved (i.e., when a symbol should have both a subscript and and a superscript).
  • The custom symbol macro codes now allow for an unspecified symbol code (?), which means the desired code will be given as last item on each data record. Such custom symbols must be specified with uppercase -SK.

Program-specific improvements

Finally, here is a list of enhancements to individual modules. Any changes to existing syntax will be backwards compatible:

  • fitcircle now has a new option -F that allows output to be in the form of coordinates only (no text report) and you may choose which items to return by appending suitable flags.
  • gmt now has a –show-cores option that reports the available cores.
  • gmtconvert adds a -C option that can be used to eliminate segments on output based on the number of records it contains. We also added a -F option to create line segments from an input data sets using a variety of connectivity modes.
  • gmtmath adds a long list of new operators. We have the operator BPDF for binomial probability distribution and BCDF for the cumulative binomial distribution function. Due to confusion with other probability distributions we have introduced a series of new operator names (but honor backwards compatibility). Listing the pdf and cdf for each distribution, these are TPDF and TCDF for the Student t-distribution, FPDF and FCDF for the F-distribution, CHI2PDF and CHI2CDF for the Chi-squared distribution, EPDF and ECDF for the exponential distribution (as well as ECRIT), PPDF and PCDF for the Poisson distribution, LPDF and LCDF for the Laplace distribution (as well as LCRIT), RPDF and RCDF for the Rayleigh distribution (as well as RCRIT), WPDF and WCDF for the Weibull distribution (as well as WCRIT), and ZPDF and ZCDF for the Normal distribution. We added ROLL for cyclic shifts of the stack, and DENAN as a more intuitive operator for removing NaNs, as well as new constants TRANGE, TROW, F_EPS and D_EPS, and we have renamed the normalized coordinates from Tn to TNORM (but this is backwards compatible). We added operator POINT which reads a data table and places the mean x and mean y on the stack. Finally, we added new hyperbolic and inverse hyperbolic functions COTH and ACOTH, SECH and ASECH, and CSCH and ACSCH.
  • gmtspatial now lets you specify Flat Earth or Geodesic distance calculations for line lengths via -Q.
  • grdblend relaxes the -W restriction on only one output grid and adds the new mode -Wz to write the weight*zsum grid.
  • grdedit enhances the -E option to allow for 90-degree rotations or flips of grid, as well as a new -G to enable writing of the result to a new output file [Default updates the existing file]. The -J option saves the georeferencing info as metadata in netCDF grids.
  • grdfilter now includes histogram mode filtering to complement mode (LMS) filtering.
  • grdgradient adds -Da to compute the aspect (down-slope) direction [up-slope].
  • grdinfo reports the projection info of netCDF grids when that is stored in a grid’s metadata in WKT format.
  • grdmath adds numerous new operators, such as ARC and WRAP for angular operators, BPDF for binomial probability distribution and BCDF for the cumulative binomial distribution function. Due to confusion with other probability distributions we have introduced a series of new operator names (but accept backwards compatibility). Listing the pdf and cdf for each distribution, these are TPDF and TCDF for the Student t-distribution, FPDF and FCDF for the F-distribution, CHI2PDF and CHI2CDF for the Chi-squared distribution, EPDF and ECDF for the exponential distribution (as well as ECRIT), PPDF and PCDF for the Poisson distribution, LPDF and LCDF for the Laplace distribution (as well as LCRIT), RPDF and RCDF for the Rayleigh distribution (as well as RCRIT), WPDF and WCDF for the Weibull distribution (as well as WCRIT), and ZPDF and ZCDF for the Normal distribution. We added LDISTG (for distances to GSHHG), CDIST2 and SDIST2 (to complement LDIST2 and PDIST2), and ROLL for cyclic shifts of the stack, and DENAN as a more intuitive operator for removing NaNs, while LDIST1 has been renamed to LDISTC. We also add new constants XRANGE, YRANGE, XCOL, YROW and F_EPS, and we have renamed the normalized coordinates from Xn to XNORM and Yn to YNORM (but this is backwards compatible). Finally, we added new hyperbolic and inverse hyperbolic functions COTH and ACOTH, SECH and ASECH, and CSCH and ACSCH.
  • grdtrack add the modifier -G+llist to pass a list of grids.
  • grdview implements the Waterfall plot mode via -Qmx|y.
  • kml2gmt acquires a -F option to control which geometry to output.
  • makecpt takes -E to determine range from an input data table.
  • mapproject can be used in conjunction with the 3-D projection options to compute 3-D projected coordinates. We also added -W to simply output the projected dimensions of the plot without reading input data.
  • psbasemap now takes -A to save the plot domain polygon in geographical coordinates. The -L option for map scale and -T for map roses have been revised (backwards compatible) and a new uniform -F option to specify background panel and its many settings was added.
  • pscoast can accept multiple -E settings to color several features independently. We also have the modifiers +AS to only plot Antarctica, +ag to use shelf ice grounding line for Antarctica coastline, and +ai to use ice/water front for Antarctica coastline [Default]. As above, the -L option for map scale and -T option for map roses have been revised (backwards compatible) and a new uniform -F option to specify background panel and its many settings was added.
  • psconvert (apart from the name change) has several new features, such as reporting dimensions of the plot when -A and -V are used, scaling the output plots via -A+s[m]width[u][/height[u]], paint and outline the bounding box via -A modifiers gfill and +ppen, and -Z for removing the PostScript file on exit. In addition, we have added SVG as a new output vector graphics format and now handle transparency even if non-PDF output formats are requested.
  • pscontour adds a -Qcut option like grdcontour and consolidates the old -T, -Q options for an index file to a new -E option.
  • pshistogram added modifiers -Wwidth[+l|h|b] to allow for more control on what happens to points falling in the tails.
  • psimage added a new uniform -D option to specify location of the image and new uniform -F option to specify background panel and its many settings.
  • pslegend has many enhancements for specifying varying cell widths and color, as well as a new uniform -D option to specify location of legend and new uniform -F option to specify background panel and its many settings.
  • psscale new uniform -D option to specify location of the scale. We have retired the -T option in favor of the new uniform -F option to specify background panel and its many settings.
  • psxy has seen considerable enhancements. We added two new quoted line (-Sq) modifiers: S|s for treating input as consecutive two-point line segments that should be individually quoted, and +x[first,last] for automating cross-section labeling. We added a new symbol (-S~) for decorated lines. These are very similar to quoted lines but instead place specified symbols along lines. We expanded -N to handle periodic, repeating symbols near the boundary, added a new modifier + to -E for asymmetrical error bars, and provided the shorthand -SE-diameter for degenerated ellipses (i.e., circles). The -L option has been enhanced to create envelope polygons around y(x), say for confidence envelopes (modifiers +b|d|D), and to complete a closed polygon by adding selected corners (modifiers +xl|r|x0 or +yb|t|y0). The -A-option now has new modifiers x|y for creating stair-case curves. The slip-vector symbol can now optionally accept a vector-head angle [30]. The custom symbols definition tests can now compare two input variables. We also added a -F option to draw line segments from an input data sets using a variety of connectivity modes. Finally, for drawing lines there are new line attribute modifiers available via the pen setting -W such as drawing with a Bezier spline (+s), trimming the segments from the ends before plotting (+ooffset), or adding vector heads at the ends of the lines (+v).
  • psxyz also has the new -SE-diameter shorthand as well as the -N modifiers for handling periodic plot symbols. Like, psxy it gets the same improvements to quoted lines and adds decorated lines as a new symbol. Likewise, the -L option has been enhanced to create envelope polygons around y(x), say for confidence envelopes (modifiers +b|d|D), and to complete a closed polygon by adding selected corners (modifiers +xl|r|x0 or +yb|t|y0). The slip-vector symbol can now optionally accept a vector-head angle [30]. Finally, to match psxy we have added the option -T for specifying no data input.
  • sample1d spline selection option -F can now accept the optional modifiers +1 or +2 which will compute the first or second derivatives of the spline, respectively.
  • spectrum1d can now turn off single-output data to stdout via -T or turn off multi-file output via -N.
  • sphdistance can now also perform a nearest-neighbor gridding where all grid nodes inside a Voronoi polygon is set to the same value as the Voronoi node value, via -Ez.
  • trend1d can now fit mixed polynomial and Fourier series models, as well as allowing models with just some terms in a polynomial or a Fourier series, including plain cosine or sine series terms. Modifiers have been added to specify data origin and fundamental period instead of defaulting to the data mid-point and data range, respectively.

A few supplement modules have new features as well:

  • mgd77track adds the -Gngap option to decimate the trackline coordinates by only plotting every gap point.
  • gravfft adds -Wwd to change observation level.
  • grdgravmag3d adds -H to compute magnetic anomaly.
  • grdpmodeler can now output more than one model prediction into several grids or as a record written to stdout. Also gains the -N option used by other spotter tools to extend the model duration.

New Features in GMT 5

GMT 5 represents a new branch of GMT development that mostly preserves the capabilities of the previous versions while adding over 200 new features to an already extensive bag of tricks. Our PostScript library PSL has seen a complete rewrite as well and produce shorter and more compact PostScript. However, the big news is aimed for developers who wish to leverage GMT in their own applications. We have completely revamped the code base so that high-level GMT functionality is now accessible via GMT “modules”. These are high-level functions named after their corresponding programs (e.g., GMT_grdimage) that contains all of the functionality of that program within the function. While currently callable from C/C++ only (with some support for F77), we are making progress on the Matlab interface as well and there are plans to start on the Python version. Developers should consult the GMT API documentation for more details.

We recommend that users of GMT 4 consider learning the new rules and defaults since eventually (in some years) GMT 4 will be obsolete. To ease the transition to GMT 5 you may run it in compatibility mode, thus allowing the use of many obsolete default names and command switches (you will receive a warning instead). This is discussed below.

Below are six key areas of improvements in GMT 5.

New programs

First, a few new programs have been added and some have been promoted (and possibly renamed) from earlier supplements:

gmt
This is the only program executable that is distributed with GMT 5. To avoid problems with namespace conflicts (e.g., there are other, non-GMT programs with generic names like triangulate, surface, etc.) all GMT 5 modules are launched from the gmt executable via “gmt module” calls (e.g, gmt pscoast). For backwards compatibility (see below) we also offer symbolic links with the old executable names that simply point to the gmt program, which then can start the correct module. Any module whose name starts with “gmt” can be abbreviated, e.g., “gmt gmtconvert” may be called as “gmt convert”.
gmt2kml
A psxy -like tool to produce KML overlays for Google Earth. Previously found in the misc supplement.
gmtconnect
Connect individual lines whose end points match within given tolerance. Previously known as gmtstitch in the misc supplement (this name is recognized when GMT is running in compatibility mode).
gmtget
Return the values of the specified GMT defaults. Previously only implemented as a shell script and thus not available on all platforms.
gmtinfo
Report information about data tables. Previously known by the name minmax (this name is still recognized when GMT is running in compatibility mode).
gmtsimplify
A line-reduction tool for coastlines and similar lines. Previously found in the misc supplement under the name gmtdp (this name is recognized when GMT is running in compatibility mode).
gmtspatial
Perform various geospatial operations on lines and polygons.
gmtvector
Perform basic vector manipulation in 2-D and 3-D.
gmtwhich
Return the full path to specified data files.
grdraster
Extracts subsets from large global grids. Previously found in the dbase supplement.
kml2gmt
Extract GMT data tables from Google Earth KML files. Previously found in the misc supplement.
sph2grd
Compute grid from list of spherical harmonic coefficients [We will add its natural complement grd2sph at a later date].
sphdistance
Make grid of distances to nearest points on a sphere. Previously found in the sph supplement.
sphinterpolate
Spherical gridding in tension of data on a sphere. Previously found in the sph supplement.
sphtriangulate
Delaunay or Voronoi construction of spherical lon,lat data. Previously found in the sph supplement.

We have also added a new supplement called potential that contains these five modules:

gmtgravmag3d:
Compute the gravity/magnetic anomaly of a body by the method of Okabe.
gmtflexure:
Compute the flexure of a 2-D load using variable plate thickness and restoring force.
gravfft:
Compute gravitational attraction of 3-D surfaces and a little more by the method of Parker.
grdgravmag3d:
Computes the gravity effect of one (or two) grids by the method of Okabe.
grdredpol:
Compute the Continuous Reduction To the Pole, also known as differential RTP.
grdseamount:
Compute synthetic seamount (Gaussian or cone, circular or elliptical) bathymetry.

Finally, the spotter supplement has added one new module:

grdpmodeler:
Evaluate a plate model on a geographic grid.

New common options

First we discuss changes that have been implemented by a series of new lower-case GMT common options:

  • Programs that read data tables can now process the aspatial metadata in OGR/GMT files with the new -a option. These can be produced by ogr2ogr (a GDAL tool) when selecting the -f “GMT” output format. See Chapter The GMT Vector Data Format for OGR Compatibility for an explanation of the OGR/GMT file format. Because all GIS information is encoded via GMT comment lines these files can also be used in GMT 4 (the GIS metadata is simply skipped).
  • Programs that read or write data tables can specify a custom binary format using the enhanced -b option.
  • Programs that read data tables can control which columns to read and in what order (and optionally supply scaling relations) with the new -i option
  • Programs that read grids can use new common option -n to control grid interpolation settings and boundary conditions.
  • Programs that write data tables can control which columns to write and in what order (and optionally supply scaling relations) with the new -o option.
  • All plot programs can take a new -p option for perspective view from infinity. In GMT 4, only some programs could do this (e.g., pscoast) and it took a program-specific option, typically -E and sometimes an option -Z would be needed as well. This information is now all passed via -p and applies across all GMT plotting programs.
  • Programs that read data tables can control how records with NaNs are handled with the new -s option.
  • All plot programs can take a new -t option to modify the PDF transparency level for that layer. However, as PostScript has no provision for transparency you can only see the effect if you convert it to PDF.

Updated common options

Some of the established GMT common options have seen significant improvements; these include:

  • The completely revised -B option can now handle irregular and custom annotations (see Section Custom axes). It also has a new automatic mode which will select optimal intervals given data range and plot size. The 3-D base maps can now have horizontal gridlines on xz and yz back walls.
  • The -R option may now accept a leading unit which implies the given coordinates are projected map coordinates and should be replaced with the corresponding geographic coordinates given the specified map projection. For linear projections such units imply a simple unit conversion for the given coordinates (e.g., km to meter).
  • Introduced -fp[unit] which allows data input to be in projected values, e.g., UTM coordinates while -Ju is given.

While just giving - (the hyphen) as argument presents just the synopsis of the command line arguments, we now also support giving + which in addition will list the explanations for all options that are not among the GMT common set.

New default parameters

Most of the GMT default parameters have changed names in order to group parameters into logical groups and to use more consistent naming. However, under compatibility mode (see below) the old names are still recognized. New capabilities have been implemented by introducing new GMT default settings:

  • DIR_DCW specifies where to look for the optional Digital Charts of the World database (for country coloring or selections).
  • DIR_GSHHG specifies where to look for the required Global Self-consistent Hierarchical High-resolution Geography database.
  • GMT_COMPATIBILITY can be set to 4 to allow backwards compatibility with GMT 4 command-line syntax or 5 to impose strict GMT5 syntax checking.
  • IO_NC4_CHUNK_SIZE is used to set the default chunk size for the lat and lon dimension of the z variable of netCDF version 4 files.
  • IO_NC4_DEFLATION_LEVEL is used to set the compression level for netCDF4 files upon output.
  • IO_SEGMENT_MARKER can be used to change the character that GMT uses to identify new segment header records [>].
  • MAP_ANNOT_ORTHO controls whether axes annotations for Cartesian plots are horizontal or orthogonal to the individual axes.
  • GMT_FFT controls which algorithms to use for Fourier transforms.
  • GMT_TRIANGULATE controls which algorithm to use for Delaunay triangulation.
  • Great circle distance approximations can now be fine-tuned via new GMT default parameters PROJ_MEAN_RADIUS and PROJ_AUX_LATITUDE. Geodesics are now even more accurate by using the Vincenty [1975] algorithm instead of Rudoe’s method.
  • GMT_EXTRAPOLATE_VAL controls what splines should do if requested to extrapolate beyond the given data domain.
  • PS_TRANSPARENCY allows users to modify how transparency will be processed when converted to PDF [Normal].

A few parameters have been introduced in GMT 5 in the past and have been removed again. Among these are:

  • DIR_USER: was supposed to set the directory in which the user configuration files, or data are stored, but this creates problems, because it needs to be known already before it is potentially set in DIR_USER/gmt.conf. The environment variable $GMT_USERDIR is used for this instead.
  • DIR_TMP: was supposed to indicate the directory in which to store temporary files. But needs to be known without gmt.conf file as well. So the environment variable $GMT_TMPDIR is used instead.

General improvements

Other wide-ranging changes have been implemented in different ways, such as

  • All programs now use consistent, standardized choices for plot dimension units (cm, inch, or point; we no longer consider meter a plot length unit), and actual distances (choose spherical arc lengths in degree, minute, and second [was c], or distances in meter [Default], foot [new], km, Mile [was sometimes i or m], nautical mile, and survey foot [new]).
  • Programs that read data tables can now process multi-segment tables automatically. This means programs that did not have this capability (e.g., filter1d) can now all operate on the segments separately; consequently, there is no longer a -m option.
  • While we support the scaling of z-values in grids via the filename convention name[=ID[+sscale][+ooffset][+nnan] mechanism, there are times when we wish to scale the x,y domain as well. Users can now append +uunit to their gridfile names, where unit is one of non-arc units listed in Table distunits. This will convert your Cartesian x and y coordinates from the given unit to meters. We also support the inverse option +Uunit, which can be used to convert your grid coordinates from meters to the specified unit.
  • CPTs also support the +u|Uunit mechanism. Here, the scaling applies to the z values. By appending these modifiers to your CPT names you can avoid having two CPTs (one for meter and one for km) since only one is needed.
  • Programs that read grids can now directly handle Arc/Info float binary files (GRIDFLOAT) and ESRI .hdr formats.
  • Programs that read grids now set boundary conditions to aid further processing. If a subset then the boundary conditions are taken from the surrounding grid values.
  • All text can now optionally be filled with patterns and/or drawn with outline pens. In the past, only pstext could plot outline fonts via -Spen. Now, any text can be an outline text by manipulating the corresponding FONT defaults (e.g., FONT_TITLE).
  • All color or fill specifications may append @transparency to change the PDF transparency level for that item. See -t for limitations on how to visualize this transparency.
  • GMT now ships with 36 standard color palette tables (CPT), up from 24.

Program-specific improvements

Finally, here is a list of numerous enhancements to individual programs:

  • blockmean added -Ep for error propagation and -Sn to report the number of data points per block.
  • blockmedian added -Er[-] to return as last column the record number that gave the median value. For ties, we return the record number of the higher data value unless -Er- is given (return lower). Added -Es to read and output source id for median value.
  • blockmode added -Er[-] but for modal value. Added -Es to read and output source id for modal value.
  • gmtconvert now has optional PCRE (regular expression) support, as well as a new option to select a subset of segments specified by segment running numbers (-Q) and improved options to extract a subset of records (-E) and support for a list of search strings via -S+fpatternfile.
  • gmtinfo has new option -A to select what group to report on (all input, per file, or per segment). Also, use -If to report an extended region optimized for fastest results in FFTs. and -Is to report an extended region optimized for fastest results in surface. Finally, new option -D[inc] to align regions found via -I with the center of the data.
  • gmtmath with -Nncol and input files will add extra blank columns, if needed. A new option -E sets the minimum eigenvalue used by operators LSQFIT and SVDFIT. Option -L applies operators on a per-segment basis instead of accumulating operations across the entire file. Many new operators have been added (BITAND, BITLEFT, BITNOT, BITOR, BITRIGHT, BITTEST, BITXOR, DIFF, IFELSE, ISFINITE, SVDFIT, TAPER). Finally, we have implemented user macros for long or commonly used expressions, as well as ability to store and recall using named variables.
  • gmtselect Takes -E to indicate if points exactly on a polygon boundary are inside or outside, and -Z can now be extended to apply to other columns than the third.
  • grd2cpt takes -F to specify output color model and -G to truncate incoming CPT to be limited to a given range.
  • grd2xyz takes -C to write row, col instead of x,y. Append f to start at 1, else start at 0. Alternatively, use -Ci to write just the two columns index and z, where index is the 1-D indexing that GMT uses when referring to grid nodes.
  • grdblend can now take list of grids on the command line and blend, and now has more blend choices (see -C). Grids no longer have to have same registration or spacing.
  • grdclip has new option -Si to set all data >= low and <= high to the between value, and -Sr to set all data == old to the new value.
  • grdcontour can specify a single contour with -C+contour and -A+contour.
  • grdcut can use -S to specify an origin and radius and cut the corresponding rectangular area, and -N to extend the region if the new -R domain exceeds existing boundaries.
  • grdfft can now accept two grids and let -E compute the cross-spectra. The -N option allows for many new and special settings, including ability to control data mirroring, detrending, tapering, and output of intermediate results.
  • grdfilter can now do spherical filtering (with wrap around longitudes and over poles) for non-global grids. We have also begun implementing Open MP threads to speed up calculations on multi-core machines. We have added rectangular filtering and automatic resampling to input resolution for high-pass filters. There is also -Ffweightgrd which reads the gridfile weightgrd for a custom Cartesian grid convolution. The weightgrd must have odd dimensions. Similarly added -Foopgrd for operators (via coefficients in the grdfile opgrd) whose weight sum is zero (hence we do not sum and divide the convolution by the weight sum).
  • grdgradient now has -Em that gives results close to ESRI’s “hillshade”’” (but faster).
  • grdinfo now has modifier -Tsdz which returns a symmetrical range about zero. Also, if -Ib is given then the grid’s bounding box polygon is written.
  • grdimage with GDAL support can write a raster image directly to a raster file (-A) and may plot raster images as well (-Dr). It also automatically assigns a color table if none is given and can use any of the 36 GMT color tables and scale them to fit the grid range.
  • grdmask has new option -Ni|I|p|P to set inside of polygons to the polygon IDs. These may come from OGR aspatial values, segment head -LID, or a running number, starting at a specified origin [0]. Now correctly handles polygons with perimeters and holes. Added z as possible radius value in -S which means read radii from 3rd input column.
  • grdmath added many new operators such as BITAND, BITLEFT, BITNOT, BITOR, BITRIGHT, BITTEST, BITXOR, DEG2KM, IFELSE, ISFINITE, KM2DEG, and TAPER. Finally, we have implemented user macros for long or commonly used expressions, as well as ability to store and recall using named variables.
  • grdtrack has many new options. The -A option controls how the input track is resampled when -C is selected, the new -C, -D options automatically create an equidistant set of cross-sectional profiles given input line segments; one or more grids can then be sampled at these locations. The -E option allows users to quickly specify tracks for sampling without needed input tracks. Also added -S which stack cross-profiles generated with -C. The -N will not skip points that are outside the grid domain but return NaN as sampled value. Finally, -T will return the nearest non-NaN node if the initial location only finds a NaN value.
  • grdvector can now take -Siscale to give the reciprocal scale, i.e., cm/ unit or km/unit. Also, the vector heads in GMT have completely been overhauled and includes geo-vector heads that follow great or small circles.
  • grdview will automatically assigns a color table if none is given and can use any of the 36 GMT color tables and scale them to fit the grid range.
  • grdvolume can let -S accept more distance units than just km. It also has a modified -T[c|h] for ORS estimates based on max curvature or height. -Cr to compute the outside volume between two contours (for instances, the volume of water from a bathymetry grid).
  • greenspline has an improved -C option to control how many eigenvalues are used in the fitting, and -Sl adds a linear (or bilinear) spline.
  • makecpt has a new -F option to specify output color representation, e.g., to output the CPT in h-s-v format despite originally being given in r/g/b, and -G to truncate incoming CPT to be limited to a given range. It also adds Di to match the bottom/top values in the input CPT.
  • mapproject has a new -N option to do geodetic/geocentric conversions; it combines with -I for inverse conversions. Also, we have extended -A to accept -Ao| O to compute line orientations (-90/90). In -G, prepend - to the unit for (fast) flat Earth or + for (slow) geodesic calculations.
  • project has added -G...[+] so if + is appended we get a segment header with information about the pole for the circle. Optionally, append /colat in -G for a small circle path.
  • psconvert has added a -TF option to create multi-page PDF files. There is also modification to -A to add user-specified margins, and it automatically detects if transparent elements have been included (and a detour via PDF might be needed).
  • psbasemap has added a -D option to place a map-insert box.
  • psclip has added an extended -C option to close different types of clip paths.
  • pscoast has added a new option -E which lets users specify one or more countries to paint, fill, extract, or use as plot domain (requires DCW to be installed).
  • pscontour is now similar to grdcontour in the options it takes, e.g., -C in particular. In GMT 4, the program could only read a CPT and not take a specific contour interval.
  • pshistogram now takes -D to place histogram count labels on top of each bar and -N to draw the equivalent normal distributions.
  • pslegend no longer uses system calls to do the plotting. The modified -D allows for minor offsets, while -F offers more control over the frame and fill.
  • psrose has added -Wvpen to specify pen for vector (specified in -C). Added -Zu to set all radii to unity (i.e., for analysis of angles only).
  • psscale has a new option -T that paints a rectangle behind the color bar. The +n modifier to -E draws a rectangle with NaN color and adds a label. The -G option will truncate incoming CPT to be limited to the specified z-range. Modification -Np indicates a preference to use polygons to draw the color bar.
  • pstext can take simplified input via new option -F to set fixed font (including size), angle, and justification. If these parameters are fixed for all the text strings then the input can simply be x y text. It also has enhanced -DJ option to shorten diagonal offsets by \sqrt{2} to maintain the same radial distance from point to annotation. Change all text to upper or lower case with -Q.
  • psxy and psxyz both support the revised custom symbol macro language which has been expanded considerably to allow for complicated, multi-parameter symbols; see Chapter Custom Plot Symbols for details. Finally, we allow the base for bars and columns optionally to be read from data file by not specifying the base value.
  • sample1d offers -A to control resampling of spatial curves (with -I).
  • spectrum1d has added -L to control removal of trend, mean value or mid value.
  • surface has added -r to create pixel-registered grids and knows about periodicity in longitude (given -fg). There is also -D to supply a “sort” break line.
  • triangulate now offers -S to write triangle polygons and can handle 2-column input if -Z is given. Can also write triangle edges as line with -M.
  • xyz2grd now also offers -Af (first value encountered), -Am (mean, the default), -Ar (rms), and -As (last value encountered).

Several supplements have new features as well:

  • img2grd used to be a shell script but is now a C program and can be used on all platforms.
  • mgd77convert added -C option to assemble *.mgd77 files from *.h77/*.a77 pairs.
  • The spotter programs can now read GPlates rotation files directly as well as write this format. Also, rotconverter can extract plate circuit rotations on-the-fly from the GPlates rotation file.

Note: GMT 5 only produces PostScript and no longer has a setting for Encapsulated PostScript (EPS). We made this decision since (a) our EPS determination was always very approximate (no consideration of font metrics, etc.) and quite often wrong, and (b) psconvert handles it exactly. Hence, users who need EPS plots should simply process their PostScript files via psconvert.