Changelog

New Features in GMT 6.3

GMT 6.3 includes a new module, many new features, general code and documentation improvements, and numerous bug fixes! Here are the general updates included in 6.3:

  • Add new -B axis modifier +e to skip annotation(s) at end of an axis (#5873)

  • Allow for a fixed label offset (#5320)

  • Implement auto resolution for remote grids for plotting modules (#5753)

  • Simplify conversions between km and degrees (#5824)

New Modules in GMT 6.3

  • grdselect: Make selections or determine common regions from 2-D grids, images or 3-D cubes (#5929)

New Core Module Features in GMT 6.3

Supplement updates in GMT 6.3

Enhancements in GMT 6.3

  • Add v (vector) to custom symbol kit, plus handle azimuth vs angle (#5606)

  • Allow trailing comments in custom symbol files (#5610)

  • Let -d set starting column via modifier (#5966)

  • Let -fcol explicity set start of input trailing text (#5370)

  • Let multi-layer geotiff files be cut via gdal_translate (#5819)

Documentation updates in GMT 6.3

  • Add a GMT team page and update contributor recognition model (#5589)

  • Add deprecations section to ReST documentation (#5847)

  • Migrate remote dataset documentation to external site (#6021)

  • New gallery example 53 showing subplots and shading (#5336)

  • Improved animations in the gallery

  • Update formatting of usage messages across all modules

Deprecations in GMT 6.3

  • Clean up aspects of SVD function usage in GMT (#5725)

  • Complete -D parsing update (#5827)

  • Consolidate -A into -F for a more unified option (#5613)

  • Deprecate the ugly perspective -JG syntax and introduce a modern form (#5780)

  • greenspline: Update -C for writing intermediate grids (#5714)

  • Let gmt end better handle -A args (#5583)

  • Update -g synopsis, syntax, usage and docs (#5617)

New Features in GMT 6.2

GMT 6.2 includes a new module, new common option, general code and documentation improvements, and numerous bug fixes! Here are the general updates included in 6.2:

  1. Addition of GMT Themes (sets of GMT defaults), with a default modern theme for modern mode, and auto scaling options for many GMT defaults.

  2. New animation 13 of seismic waveforms.

  3. New animation 14 of earthquake focal mechanisms.

  4. Support for +aangle for y-axis as well as x-axis with the -B axes settings.

  5. General improvements to the automatic determination of frame attributes.

  6. New +ddivisor modifier to the -i option to simplify scaling of input values.

  7. Allow parsing of -Jz1:zzzzzz for vertical scale.

  8. New GMT configuration parameters MAP_FRAME_PERCENT, COLOR_SET, and COLOR_CPT.

  9. Add support for reading variable in NetCDF-4 groups.

  10. Allow specifying the reciprocal increment for generating 1d arrays.

  11. Allow LaTeX expressions in single-line titles and Cartesian axes labels, add support for multi-line plot titles, and add support for subtitles.

  12. Many general documentation improvements.

  13. Various improvements to the API in support of developments taking place in the external wrappers (Python, Julia, Matlab).

New Common Options in GMT 6.2:

  1. -w: Convert selected coordinate to repeating cycles.

New Modules in GMT 6.2:

  1. gmtbinstats: Bin spatial data and determine statistics per bin, with support for both hexagonal and rectangular tiling.

New Core Module Features in GMT 6.2:

  1. colorbar: New +x and +y modifiers to the -S option for setting axis label and unit; Support slanted annotations with -S.

  2. events: New -Z option to animate geodesy and seismology symbols; New -H option to enable text label boxes; Support plotting lines as series of closely spaced circles.

  3. gmtmath: New VPDF operator.

  4. gmtsplit: New name for previous module splitxyz.

  5. grd2xyz: New modifier for the -W option to set the length unit used.

  6. grdcut: New -F option to clip a grid based on a polygon.

  7. grdfft: New -Q option for no wavenumber operations.

  8. grdmath: New FISHER and VPDF operators.

  9. greenspline, grdinterpolate: Enable writing of 3-D netCDF data cubes.

  10. histogram: New -E option for custom bar widths and optional shift; New +b modifier to -C to set color based on the bin value.

  11. legend: New -M option to handle both hidden and given information.

  12. makecpt, grd2cpt: Simplify the addition of category labels to CPT files with -F.

  13. movie: New modifiers to -L and -P to enable drop-shadow and rounded rectangular boxes.

  14. plot, plot3d: New -H option to scale the symbol size as well as the symbol pen outline attributes; Support sequential auto-colors for polygon fills or line pens.

  15. rose: New -N option to draw the equivalent circular normal distribution.

  16. subplot: New -D option to accept previous default plot settings.

  17. ternary: Add support for drawing lines and polygons.

  18. text: New -S option to cast shade beneath a text box.

Supplement updates in GMT 6.2:

  1. coupe: Updated syntax for the -A option.

  2. coupe, meca, velo: New scaling option -H; allow variable transparency; allow adjusting symbol color via intensity; allow setting symbol color using colormaps.

  3. gmtgravmag3d: Add option to create geometric bodies (spheres, prisms, ellipsoids, etc.) and compute their effect.

  4. grdseamount: Add polynomial seamount shape.

Release of GMT 6.1.1

The GMT 6.1.1 release adds no new features but fixes a number of bugs that have been reported since the release of 6.1. As such, it is a stable and recommended upgrade for all 6.1 users. For new features in 6.1.x in general, please read the following sections.

New Features in GMT 6.1

GMT 6.1 may be a minor revision to 6.0 but packs quite a punch. For general changes, we mention

  1. Updated remote global data sets: Earth reliefs, crustal ages, land/ocean masks, and day/night imagery. The larger grid files (5x5 arc minutes and smaller resolutions) are now tiled and faster to download.

  2. Let gmt.history, gmt.conf, and gmt.cpt be hierarchical and maintained separately for figures, subplot panels, and insets in modern mode.

  3. Use a list of keywords (separate,anywhere,lon_horizontal,lat_horizontal, tick_extend,tick_normal,lat_parallel) instead of bit-sum for MAP_ANNOT_OBLIQUE.

  4. Let the macOS bundle be built with OpenMP support to accelerate some computational modules.

  5. Let GMT recognize MATLAB headers/comments via multiple IO_HEADER_MARKER characters.

  6. Let an explicitly signed grid cross size in GMTCASE_MAP_GRID_CROSS_SIZE_PRIMARY or MAP_GRID_CROSS_SIZE_SECONDARY mean centered (if positive) or asymmetrical (if negative) grid ticks.

  7. Add modifier +v for a vertical oblique Equator in -JO [horizontal].

  8. New -B modifier +i for placing internal frame annotations

  9. New -B modifier +f to turn on fancy geographic annotations.

  10. New polar projection (-JP) modifiers (+f|r|t|z) adds new capabilities for annotating azimuths, depths or radii.

  11. Revise verbosity default levels and their names and abbreviations.

  12. Add Web-Mercator as new sphere that can be selected.

  13. Explore adding long-format GMT options (e.g., --region=w/e/s/n).

  14. Allow both -i and -o to specify an open-ended list of columns to end of record.

  15. API improvements to support the GMT/MEX, PyGMT, and GMT.jl environments.

New Common Options in GMT 6.1:

  1. -l: Add automatic legend entries from the modules plot, plot3d, grdcontour and pscontour in modern mode.

  2. -q[i|o]: Select specific data rows to complement selection of data columns (via -i, -o).

New Modules in GMT 6.1:

  1. batch: Automate batch job processing by replicating a master script with job-specific parameters.

  2. grdmix: Blending and transforming grids and images, including manipulating transparency.

  3. grdinterpolate: Interpolate new 2-D grids or 1-D data series from a 3-D data cube.

  4. grdgdal: Execute GDAL raster programs (such as info, dem, grid, translate, rasterize or warp), from GMT.

New Core Module Features in GMT 6.1:

  1. begin: Ignore the user’s gmt.conf files normally included by using -C.

  2. colorbar: Option -S has been enhanced to handle bar appearance when -B is not used.

  3. gmtget: Options -D, -I, -N, and -Q handle download and query of remote data sets.

  4. gmtmath: New operators RGB2HSV and HSV2RGB for color manipulation.

  5. gmtregress: Let -A also be used to limit angles considered for LMS regressions.

  6. gmtspatial: New directive -Sb computes buffers around lines (via the optional GEOS library).

  7. gmtvector: Add vector operator -Tt that translates points by given distance in given direction.

  8. grd2kml: New option -W for adding contour overlays. Also rebuilt for global grids as well as to write PNG or JPG directly (depending on transparency) without going via PostScript conversion (only required if -W is used).

  9. grdcontour: Better handling of contour file that can now have unique angles and pens per contour.

  10. grdconvert: Enable scaling/translation services on output with -Z.

  11. grdfill: Implement minimum-curvature spline infill with -As.

  12. grdfilter: Let filter width optionally be a grid with variable widths.

  13. grdgradient: Add support for ambient light in -N, as in -E, and therefore via -I in grdimage and grdview.

  14. grdimage: Now -I may take a filename in addition to requests to derive intensities from it.

  15. grdinfo: Now -C also appends registration and grid type as last two output columns (0 = gridline, 1 = pixel registration; 0 = Cartesian, 1 = geographic).

  16. grdmath: New operators DAYNIGHT (for day/night terminator), BLEND (blend two grids using the weights from a third), DOT (dot product), and RGB2HSV, and HSV2RGB for color manipulations.

  17. grdtrack: Determine central peak in all crossections with -F (requires -C); let -E+c continue a track if next line is a direct continuation of previous line.

  18. grdview: Now -I may take a filename in addition to requests to derive intensities from it.

  19. pscontour: Better handling of contour file that can now have unique angles and pens per contour.

  20. movie: Add -E for an optional title sequence (with or without fading in/out), -K for fade in and fade out for main animation sequence, -Sb and -Sf can now take a PostScript layer instead of a script, and -P for adding one of six progress indicators.

  21. nearneighbor: Let -Nn call GDAL’s nearest neighbor algorithm.

  22. sample1d: Adds a smoothing cubic spline via -Fsp (for a fit parameter p), with optional weights (-W).

  23. surface: Let -D take a modifier +zvalue to set a constant breakline level.

Supplement updates in GMT 6.1:

  1. seis: Update all module syntax to GMT 6 standards and make their i/o more robust.

  2. potential: grdflexure adds new transfer functions now documented with equations.

New Features in GMT 6.0

GMT 6.0 is a major revision of GMT and its eco-system. At the top level, there are numerous changes:

  1. An entirely new and permanent address with a brand new website layout and organization: http://www.generic-mapping-tools.org.

  2. A new discussion forum at http://forum.generic-mapping-tools.org.

  3. A data server in Hawaii (oceania.generic-mapping-tools.org) with plans for new mirror servers around the world. This is where the remote files that start with @ come from.

  4. A new way to use GMT (modern mode) that eliminates many of the aspects of classic GMT that perplexes users. In modern mode, PostSCript is no longer the default graphics output format and most modules that had names starting with ps have had that prefix removed. In addition, a few modules have entirely different names in modern mode (psxy is plot, psxyz is plot3d, and psscale is colorbar).

  5. The default mode remains classic, the only mode previously available. All existing classic mode GMT 4 and 5 scripts will run as before.

Modern mode modules in GMT 6.0

GMT modern mode is supported by five new commands:

  1. begin starts a new GMT modern mode session.

  2. figure names a new GMT figure in the current session

  3. subplot starts, manages, and ends subplots in a figure.

  4. inset starts, manages and ends an inset in a figure or subplot.

  5. end ends a GMT modern mode session.

Here, gmt begin and gmt end begins and ends a modern mode session, hence it is not possible to get entangled in modern mode if you prefer to run classic mode scripts. There are three additional commands that are associated with modern mode; the first two also work in classic mode since they are typically not useful in scripts:

  1. docs gives browser access to any GMT module documentation.

  2. clear removes various session files or cached data files.

  3. movie simplifies the construction of animated sequences.

The entire cookbook, tutorial and gallery examples all use modern mode. In modern mode, the default graphics format is PDF and scripts can open up the plots in the default viewer automatically.

New modules in GMT 6.0

Apart from modern mode we have added a few modules that are accessible to all users:

  1. events makes a snapshot of all time-dependent events.

  2. earthtide (supplement) computes the solid Earth tides.

General improvements in GMT 6.0

While our focus has been almost exclusively on GMT modern mode, there is a range of new capabilities have been added to all of GMT; here is a summary of these changes:

  • The gmt driver has several new options to display the latest GMT citation, DOI, the current data server, and the ability to create a blank modern mode shell script or DOS batch template.

  • A new common option -l lets some modules (currently, only plot and plot3d) build an automatic legend. Most legends are now perfectly dimensions and aligned using the PostScript language.

  • We now consider untouched pixels when rendering PostScript to be opaque, hence automatic cropping to tightest bounding box will recognize areas painted white as different from opaque.

  • We have a much improved scheme for distinguishing between minus-signs and hyphens when typesetting text since these are different glyphs in various character sets.

  • Modern mode can produce any of several graphics formats. While the default is PDF, this can be changed via a new GMT defaults GMT_GRAPHICS_FORMAT. The conversion from PostScript to the desired format can be modified via another new GMT defaults setting PS_CONVERT.

  • We have relaxed the style syntax for pens so that the :phase part is optional, with a default of 0.

  • We have rearranged our supplements a bit: We have split meca to seis and geodesy and moved new module earthtide and existing module gpsgridder to the geodesy supplement. Also, dimfilter has moved to the core and we have remove the empty misc supplement.

  • In most modules that need to set up an equidistant 1-D array we now use the same machinery to parse options and created the arrays through a redesigned -T option. For details on array creation, see Generate 1D Array.

  • We have a new GMT common option -j that clarifies how to select flat Earth, great circle, and geodesic calculations and thus eliminates awkward, sign-based increments.

  • The GMT common option -r used to always set pixel-registration for grids but it can now take the optional directives g or p to specify the desired registration.

  • We now offer slanted annotations via the -B option, using the modifier +aangle. We have added auto-computed annotation and tick intervals for time-axes. There is also the frame specifications lrbtu that just draw the corresponding frames without ticking.

  • We offer a wide range of new color tables, including the scientific color maps from Fabio Crameri, and we now use Google’s turbo as the default GMT color table, and geo for topographic DEMs.

  • Modules that read data tables can now be given an ESRI shapefile directly.

  • GMT common options -X and -Y may now be specified using fractions of current plot’s dimensions.

  • When specifying master CPTs one can add the modifier +idz to ensure any automatically computed range is rounded into multiples of dz.

  • Let common option -a with no arguments place add all aspatial items to the input record.

  • We have added dashdot as a new shorthand style name.

  • Map regions can now be specified via -RISOcode using the 2-char ISO country codes, with modifiers to round the resulting exact regions into multiples of given increments. Under modern mode, new shorthand options -Re and -Ra will examine the data files given and determine the exact or approximate region, respectively.

Module enhancements in GMT 6.0

Several modules have obtained new options to extend their capabilities:

  • grdfilter now accepts the -r option to set grid node registration.

  • clip has a new option -Wpen to draw the clip path as well as setting up clipping.

  • plot takes a new modifier +s to -Sr to specify a rectangle via opposite diagonal corners. Users can now also specify a color indirectly via a CPT (i.e., -C) and a new -Zvalue option (instead of directly via -G). The wedge symbol (-Sw) has been greatly upgraded to offer windshield and spider-graph symbols. There is now also a new QR code symbol that will redirect to the GMT homepage. We also added a +h modifier for quoted lines when the user wants to hide the line. Finally, symbols -SE-, -SJ- and -SW can now all handle geographic units.

  • plot3d also allows users to specify a color indirectly via a CPT (i.e., -C) and a new -Zvalue option. The wedge symbol (-Sw) has been greatly upgraded to offer windshield symbols and spider-graph symbols. There is now also a new QR code symbol that will redirect to the GMT homepage.

  • text can now handle lack of input files when -F+c+t is used to give both a string and its placement.

  • In modern mode, both makecpt and grd2cpt require a new option -H to actually write the resulting CPT to standard output (by default they write a hidden CPT that modern mode modules know where to find automatically). makecpt also has a new option -S to create a symmetric color table given the range in a data file given via -T.

  • gmtmath has a new operator PHI that computes the golden ratio. We now allow -Cx and -Cy to represent -C0 and -C 1.

  • grdmath also has a new operator PHI that computes the golden ratio, as well as NODE and NODEP operators, and added more OpenMP support for operators LDISTG, PSI, TCRIT, PLM, and PLMg.

  • rose can now take -JX instead of -S so all plot modules take -J.

  • grdedit can now take -J and add meta-data to the grid header.

  • gmt2kml takes new option -E to extract altitudes stored in the Extended data property.

  • polar and meca can let beachball size scale with magnitude. These and other plotting tools in seis can now accept the 3-D projection setting via -p.

  • Both grdcontour and contour can now accept a list of comma-separated contours instead of always creating equidistant lists. Also, if no contours are specified we auto-compute a reasonable selection of 10 to 20 contours. We also added -Ln|N|p|P for selecting just negative or positive contours. Finally, we added modifier +z to -Q to exclude the zero-contour entirely.

  • mapproject has an enhanced option -W that can return reference point coordinates. Also, either -J+proj or -JEPSG:n can now be given.

  • grdproject also takes -J+*proj* or -JEPSG:n.

  • project has a new option -Z for generating the path of a specified ellipse.

  • dimfilter now writes an error analysis template to standard output via the -L option.

  • surface can now apply a data mask computed from the data distribution directly rather than having to make separate calls to grdmask and grdmath. Also, the -A option now has a directive m to select Flat Earth scaling via the mean latitude.

  • The block-modules blockmean, blockmedian, and blockmode have new options -A and -G which allow them to write one or more grids directly.

  • gmtinfo has a new option -a which allows it to report aspatial column names, and -Ib to output the boundary polygon for the data.

  • backtracker can now do reconstruction given individual hotspot drift histories. We also added -M for fractional stage rotations.

  • grdrotater has an option -A to override region of output grid.

  • polespotter has a new option -Cxfile.

  • psconvert has a new option -H for automatic sub-pixel rendering and scaling. Under modern mode we also have option -M for sandwiching a PostScript plot between two other plots.

  • We added modifiers +a and +i to option -Z in gmtselect.

  • grdcut has new option -ZN to strip off outside rows and cols that are all NaN.

  • grdinfo now accepts -o when -Cn is in effect.

  • Enable basemap -L to do Cartesian projection scales, even vertical.

  • Improve the vertical scale bar for wiggle as well.

  • gmtconvert has new option -W that attempts to convert trailing text to numbers, if possible. Append modifier +n to suppress NaN columns. We also added -Ncolumn[+a|d] to sort a table based on specified column. Finally, -EMstride is similar to -Em but it will always include the last point.

  • grdlandmask -E will trace nodes being positioned exactly on polygon border.

  • histogram can now run in reverse cumulative mode via -Qr.

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 in GMT 5.4

We have added a new module to the GMT core called ternary. This module allows for the construction of ternary diagram, currently restricted to symbols (i.e., a plot-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 in GMT 5.4

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 basemap and coast) 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 in GMT 5.4

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.

  • basemap has a new map-inset (-D) modifier +t that will translate the plot origin after determining the lower-left corner of the map inset.

  • histogram has a new -Z modifier +w that will accumulate weights provided in the 2nd input column instead of pure counts.

  • rose 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 in GMT 5.4

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].

  • rose now wants -L[wlabel,elabel,slabel,nlabel] to match the other labeling options.

  • text now expects -D[j|J]dx[/dy][+v[pen]].

  • plot 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 in GMT 5.3

We have added a new module to the GMT core called solar. 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 sac 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 in GMT 5.3

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, 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 insets, 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.

  • text 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.

  • rose can now control the attributes of vectors in a windrose diagram via -M.

  • plot 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 plot3d.

  • 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 GMT C API 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 in GMT 5.2

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 in GMT 5.2

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 in GMT 5.2

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 in GMT 5.2

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 in GMT 5.2

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 insets, 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 in GMT 5.2

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.

  • basemap 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.

  • coast 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[/height], 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.

  • contour adds a -Qcut option like grdcontour and consolidates the old -T, -Q options for an index file to a new -E option.

  • histogram added modifiers -Wwidth[+l|h|b] to allow for more control on what happens to points falling in the tails.

  • image 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.

  • legend 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.

  • colorbar 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.

  • plot 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).

  • plot3d also has the new -SE-diameter shorthand as well as the -N modifiers for handling periodic plot symbols. Like, plot 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 plot 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 standard output 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 standard output. 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 in GMT 5

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 coast). 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 plot -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 in GMT 5

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., coast) 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 in GMT 5

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 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 in GMT 5

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 in GMT 5

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 text 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 in GMT 5

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).

  • basemap has added a -D option to place a map-inset box.

  • clip has added an extended -C option to close different types of clip paths.

  • coast 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).

  • contour 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.

  • histogram now takes -D to place histogram count labels on top of each bar and -N to draw the equivalent normal distributions.

  • legend 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.

  • rose 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).

  • colorbar 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.

  • text 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.

  • plot and plot3d 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.