The Generic Mapping Tools

PIC

Version 4.5.16

Technical Reference and Cookbook

by

Pl (Paul) Wessel

School of Ocean and Earth Science and Technology

University of Hawai’i at Mānoa

and

Walter H. F. Smith

Laboratory for Satellite Altimetry

NOAA/NESDIS/STAR

Jun 2016

PIC

Contents

Front page
List of Tables
List of Figures
Acknowledgments
The GMT Documentation Project
A Reminder
Copyright and Caveat Emptor!
Typographic conventions
1 Preface
 1.1 What is new in GMT 4.x?
  1.1.1 Overview of GMT 4.5.16 [June-25, 2017]
  1.1.2 Overview of GMT 4.5.15 [October-1, 2016]
  1.1.3 Overview of GMT 4.5.14 [Nov-1, 2015]
  1.1.4 Overview of GMT 4.5.13 [Jan-1, 2015]
  1.1.5 Overview of GMT 4.5.12 [Mar-1, 2014]
  1.1.6 Overview of GMT 4.5.11 [Nov-5, 2013]
  1.1.7 Overview of GMT 4.5.9 [Jan-1, 2013]
  1.1.8 Overview of GMT 4.5.8 [Apr-1, 2012]
  1.1.9 Overview of GMT 4.5.7 [Jul-15, 2011]
  1.1.10 Overview of GMT 4.5.6 [Mar-1, 2011]
  1.1.11 Overview of GMT 4.5.5 [Nov-1, 2010]
  1.1.12 Overview of GMT 4.5.4 [Nov-1, 2010]
  1.1.13 Overview of GMT 4.5.3 [Jul-15, 2010]
  1.1.14 Overview of GMT 4.5.2 [Jan-15, 2010]
  1.1.15 Overview of GMT 4.5.1 [Sept-20, 2009]
  1.1.16 Overview of GMT 4.5.0 [July-15, 2009]
  1.1.17 Overview of GMT 4.4.0 [Feb-15, 2009]
  1.1.18 Overview of GMT 4.3.1 [May-15, 2008]
  1.1.19 Overview of GMT 4.3.0 [May-1, 2008]
  1.1.20 Overview of GMT 4.2.1 [October-10, 2007]
  1.1.21 Overview of GMT 4.2.0 [April-1, 2007]
  1.1.22 Overview of GMT 4.1.4 [Nov-1, 2006]
  1.1.23 Overview of GMT 4.1.3 [June-1, 2006]
  1.1.24 Overview of GMT 4.1.2 [May-15, 2006]
  1.1.25 Overview of GMT 4.1.1 [Mar-1, 2006]
  1.1.26 Overview of GMT 4.1 [Jan-7, 2006]
  1.1.27 Overview of GMT 4.0 [Oct-10, 2004]
2 Introduction
3 GMT overview and quick reference
 3.1 GMT summary
 3.2 GMT quick reference
4 General features
 4.1 GMT units
 4.2 GMT defaults
  4.2.1 Overview and the .gmtdefaults4 file
  4.2.2 Changing GMT defaults
 4.3 Command line arguments
 4.4 Standardized command line options
  4.4.1 Data domain or map region: The -R option
  4.4.2 Coordinate transformations and map projections: The -J option
  4.4.3 Map frame and axes annotations: The -B option
  4.4.4 Header data records: The -H option
  4.4.5 Portrait plot orientation: The -P option
  4.4.6 Plot overlays: The -K-O options
  4.4.7 Timestamps on plots: The -U option
  4.4.8 Verbose feedback: The -V option
  4.4.9 Plot positioning and layout: The -X-Y options
  4.4.10 Binary table i/o: The -b option
  4.4.11 Number of Copies: The -c option
  4.4.12 Data type selection: The -f option
  4.4.13 Data gap detection: The -g option
  4.4.14 Multiple segment data: The -m option
  4.4.15 Lat/Lon or Lon/Lat?: The -: option
 4.5 Command line history
 4.6 Usage messages, syntax- and general error messages
 4.7 Standard input or file, header records
 4.8 Verbose operation
 4.9 Program output
 4.10 Input data formats
 4.11 Output data formats
 4.12 PostScript features
 4.13 Specifying pen attributes
 4.14 Specifying area fill attributes
 4.15 Color palette tables
  4.15.1 Categorical CPT files
  4.15.2 Regular CPT files
 4.16 Character escape sequences
 4.17 Grid file format specifications
 4.18 Options for COARDS-compliant netCDF files
 4.19 The NaN data value
 4.20 GMT environment parameters
5 GMT Coordinate Transformations
 5.1 Cartesian transformations
  5.1.1 Cartesian linear transformation (-Jx-JX)
  5.1.2 Cartesian logarithmic projection
  5.1.3 Cartesian power projection
 5.2 Linear projection with polar (θ,r) coordinates (-Jp -JP)
6 GMT Map Projections
 6.1 Conic projections
  6.1.1 Albers conic equal-area projection (-Jb-JB)
  6.1.2 Equidistant conic projection (-Jd-JD)
  6.1.3 Lambert conic conformal projection (-Jl-JL)
  6.1.4 (American) polyconic projection (-Jpoly-JPoly
 6.2 Azimuthal projections
  6.2.1 Lambert Azimuthal Equal-Area (-Ja-JA)
  6.2.2 Stereographic Equal-Angle projection (-Js-JS)
  6.2.3 Perspective projection (-Jg-JG)
  6.2.4 Orthographic projection (-Jg-JG)
  6.2.5 Azimuthal Equidistant projection (-Je-JE)
  6.2.6 Gnomonic projection (-Jf-JF)
 6.3 Cylindrical projections
  6.3.1 Mercator projection (-Jm-JM)
  6.3.2 Transverse Mercator projection (-Jt-JT)
  6.3.3 Universal Transverse Mercator (UTM) projection (-Ju-JU)
  6.3.4 Oblique Mercator projection (-Jo-JO)
  6.3.5 Cassini cylindrical projection (-Jc-JC)
  6.3.6 Cylindrical equidistant projection (-Jq-JQ)
  6.3.7 Cylindrical equal-area projections (-Jy-JY)
  6.3.8 Miller Cylindrical projection (-Jj-JJ)
  6.3.9 Cylindrical stereographic projections (-Jcyl_stere-JCyl_stere)
 6.4 Miscellaneous projections
  6.4.1 Hammer projection (-Jh-JH)
  6.4.2 Mollweide projection (-Jw-JW)
  6.4.3 Winkel Tripel projection (-Jr-JR)
  6.4.4 Robinson projection (-Jn-JN)
  6.4.5 Eckert IV and VI projection (-Jk-JK)
  6.4.6 Sinusoidal projection (-Ji-JI)
  6.4.7 Van der Grinten projection (-Jv-JV)
7 Creating GMT Graphics
 7.1 The making of contour maps
 7.2 Image presentations
 7.3 Spectral estimation and xy-plots
 7.4 A 3-D perspective mesh plot
 7.5 A 3-D illuminated surface in black and white
 7.6 Plotting of histograms
 7.7 A simple location map
 7.8 A 3-D histogram
 7.9 Plotting time-series along tracks
 7.10 A geographical bar graph plot
 7.11 Making a 3-D RGB color cube
 7.12 Optimal triangulation of data
 7.13 Plotting of vector fields
 7.14 Gridding of data and trend surfaces
 7.15 Gridding, contouring, and masking of unconstrained areas
 7.16 Gridding of data, continued
 7.17 Images clipped by coastlines
 7.18 Volumes and Spatial Selections
 7.19 Color patterns on maps
 7.20 Custom plot symbols
 7.21 Time-series of RedHat stock price
 7.22 World-wide seismicity the last 7 days
 7.23 All great-circle paths lead to Rome
 7.24 Data selection based on geospatial criteria
 7.25 Global distribution of antipodes
 7.26 General vertical perspective projection
 7.27 Plotting Sandwell/Smith Mercator img grids
 7.28 Mixing UTM and geographic data sets
 7.29 Gridding spherical surface data using splines
 7.30 Trigonometric functions plotted in graph mode
8 Creating GMT Animations
 8.1 Animation of the sine function
 8.2 Examining DEMs using variable illumination
 8.3 Orbiting a static map
 8.4 Flying over topography
9 Mailing lists, updates, and bug reports
A GMT supplemental packages
 A.1 dbase: gridded data extractor
 A.2 gshhg: GSHHG data extractor
 A.3 imgsrc: gridded altimetry extractor
 A.4 meca: seismology and geodesy symbols
 A.5 mex: Matlab/Octave–GMT interface
 A.6 mgd77: MGD77 extractor and plotting tools
 A.7 mgg: GMT-MGD77 extractor and plotting tools
 A.8 misc: Miscellaneous tools
 A.9 segyprogs: plotting SEGY seismic data
 A.10 sph: spherical triangulation and gridding
 A.11 spotter: backtracking and hotspotting
 A.12 x2sys: track crossover error estimation
 A.13 x_system: track crossover error estimation
 A.14 xgrid: visual editor for grid files
B GMT file formats
 B.1 Table data
  B.1.1 ASCII tables
  B.1.2 Binary tables
  B.1.3 NetCDF tables
 B.2 Grid files
  B.2.1 NetCDF files
  B.2.2 Gridline and Pixel node registration
  B.2.3 Boundary Conditions for operations on grids
  B.2.4 Native binary grid files
 B.3 Sun raster files
C Including GMT graphics into your documents
 C.1 Making GMT Encapsulated PostScript Files
 C.2 Converting GMT PostScript to PDF or raster images
  C.2.1 When converting or viewing PostScript goes awry
  C.2.2 Using ps2raster
 C.3 Examples
  C.3.1 GMT graphics in LATEX
  C.3.2 GMT graphics in PowerPoint
 C.4 Concluding remarks
D Availability of GMT and related code
 D.1 Source distribution
 D.2 Pre-compiled Executables
E Predefined bit and hachure patterns in GMT
F Chart of octal codes for characters
G PostScript fonts used by GMT
H Problems with display of GMT PostScript
 H.1 PostScript driver bugs
 H.2 Resolution and dots per inch
 H.3 European characters
 H.4 Hints
I Color Space: The final frontier
 I.1 RGB color system
 I.2 HSV color system
 I.3 The color cube
 I.4 Color interpolation
 I.5 Artificial illumination
 I.6 Thinking in RGB or HSV
 I.7 CMYK color system
J Filtering of data in GMT
K The GMT High-Resolution Coastline Data
 K.1 Selecting the right data
 K.2 Format required by GMT
 K.3 The long and winding road
 K.4 The Five Resolutions
  K.4.1 The crude resolution (-Dc)
  K.4.2 The low resolution (-Dl)
  K.4.3 The intermediate resolution (-Di)
  K.4.4 The high resolution (-Dh)
  K.4.5 The full resolution (-Df)
L GMT on non-UNIX platforms
 L.1 Introduction
 L.2 Cygwin and GMT
 L.3 SFU and GMT
 L.4 DJGPP and GMT
 L.5 WIN32 and GMT
 L.6 OS/2 and GMT
 L.7 Mac OS and GMT
M Of colors and color legends
 M.1 Built-in color palette tables
 M.2 Labeled and non-equidistant color legends
N Custom Plot Symbols
O Annotation of Contours and “Quoted Lines”
 O.1 Label Placement
 O.2 Label Attributes
 O.3 Examples of Contour Label Placement
  O.3.1 Equidistant labels
  O.3.2 Fixed number of labels
  O.3.3 Prescribed label placements
  O.3.4 Label placement at simple line intersections
  O.3.5 Label placement at general line intersections
 O.4 Examples of Label Attributes
  O.4.1 Label placement by along-track distances, 1
  O.4.2 Label placement by along-track distances, 2
  O.4.3 Using a different data set for labels
 O.5 Putting it all together
P Special Operations
 P.1 Running GMT in isolation mode
 P.2 Using both GMT 3 and 4

List of Tables

4.1 The 17 standardized GMT command line switches.
4.2 Interval type codes.
4.3 Interval unit codes.
4.4 GMT predefined pen widths.
4.5 A few examples of pen specifications.
4.6 A few examples of fill specifications.
4.7 GMT text escape sequences.
4.8 Shortcuts for some European characters.
4.9 GMT grid file formats.
6.1 Standard parallels for some cylindrical equidistant projections.
6.2 Standard parallels for some cylindrical equal-area projections.
6.3 Standard parallels for some cylindrical equal-area projections.
B.1 Attributes of default GMT grid file in COARDS-compliant netCDF format.
B.2 GMT grid file header record. TYPE can be char, short, int, float, or double.
B.3 Structure of a Sun raster file.
B.4 Sun macro definitions relevant to raster files.

List of Figures

The four horsemen of the GMT apocalypse: Remko Scharroo, Paul Wessel, Walter H.F. Smith, and Joaquim Luis at the GMT Developer Summit in Honolulu, Hawaii during February 14–18, 2011.
4.1 Some GMT parameters that affect plot appearance.
4.2 More GMT parameters that affect plot appearance.
4.3 Even more GMT parameters that affect plot appearance.
4.4 The plot region can be specified in two different ways. (a) Extreme values for each dimension, or (b) coordinates of lower left and upper right corners.
4.5 The 30+ map projections and coordinate transformations available in GMT.
4.6 Geographic map border using separate selections for annotation, frame, and grid intervals. Formatting of the annotation is controlled by the parameter PLOT_DEGREE_FORMAT in your .gmtdefaults4 file.
4.7 Geographic map border with both primary (P) and secondary (S) components.
4.8 Linear Cartesian projection axis. Long tickmarks accompany annotations, shorter ticks indicate frame interval. The axis label is optional. We used -R0/12/0/1 -JX3/0.4 -Ba4f2g1:Frequency::,%:.
4.9 Logarithmic projection axis using separate values for annotation, frame, and grid intervals. (top) Here, we have chosen to annotate the actual values. Interval = 1 means every whole power of 10, 2 means 1, 2, 5 times powers of 10, and 3 means every 0.1 times powers of 10. We used -R1/1000/0/1 -JX3l/0.4 -Ba1f2g3. (middle) Here, we have chosen to annotate log10 of the actual values, with -Ba1f2g3l. (bottom) We annotate every power of 10 using log10 of the actual values as exponents, with -Ba1f2g3p.
4.10 Exponential or power projection axis. (top) Using an exponent of 0.5 yields a x axis. Here, intervals refer to actual data values, in -R0/100/0/1 -JX3p0.5/0.4 -Ba20f10g5. (bottom) Here, intervals refer to projected values, although the annotation uses the corresponding unprojected values, as in -Ba3f2g1p.
4.11 Cartesian time axis, example 1.
4.12 Cartesian time axis, example 2.
4.13 Cartesian time axis, example 3.
4.14 Cartesian time axis, example 4.
4.15 Cartesian time axis, example 5.
4.16 Cartesian time axis, example 6.
4.17 Cartesian time axis, example 7.
4.18 Users can specify Landscape [Default] or Portrait (-P) orientation.
4.19 A final PostScript file consists of any number of individual pieces.
4.20 The -U option makes it easy to “date” a plot.
4.21 Plot origin can be translated freely with -X -Y.
5.1 Linear transformation of Cartesian coordinates.
5.2 Linear transformation of map coordinates.
5.3 Linear transformation of calendar coordinates.
5.4 Logarithmic transformation of x-coordinates.
5.5 Exponential or power transformation of x-coordinates.
5.6 Polar (Cylindrical) transformation of (θ,r) coordinates.
6.1 Albers equal-area conic map projection
6.2 Equidistant conic map projection
6.3 Lambert conformal conic map projection
6.4 (American) polyconic projection
6.5 Rectangular map using the Lambert azimuthal equal-area projection.
6.6 Hemisphere map using the Lambert azimuthal equal-area projection.
6.7 Equal-Area (Schmidt) and Equal-Angle (Wulff) stereo nets.
6.8 Polar stereographic conformal projection.
6.9 Polar stereographic conformal projection with rectangular borders.
6.10 General stereographic conformal projection with rectangular borders.
6.11 View from the Space Shuttle in Perspective projection.
6.12 Hemisphere map using the Orthographic projection.
6.13 World map using the equidistant azimuthal projection.
6.14 Gnomonic azimuthal projection.
6.15 Simple Mercator map.
6.16 Rectangular Transverse Mercator map.
6.17 A global transverse Mercator map.
6.18 Universal Transverse Mercator zone layout.
6.19 Oblique Mercator map using -Joc. We make it clear which direction is North by adding a star rose with the -T option.
6.20 Cassini map over Sardinia.
6.21 World map using the Plate Carre projection.
6.22 World map using the Behrman cylindrical equal-area projection.
6.23 World map using the Miller cylindrical projection.
6.24 World map using Gall’s stereographic projection.
6.25 World map using the Hammer projection.
6.26 World map using the Mollweide projection.
6.27 World map using the Winkel Tripel projection.
6.28 World map using the Robinson projection.
6.29 World map using the Eckert IV projection.
6.30 World map using the Eckert VI projection.
6.31 World map using the Sinusoidal projection.
6.32 World map using the Interrupted Sinusoidal projection.
6.33 World map using the Van der Grinten projection.
7.1 Contour maps of gridded data.
7.2 Color images from gridded data.
7.3 Spectral estimation and xy-plots.
7.4 3-D perspective mesh plot (left) and colored version (right).
7.5 3-D illuminated surface.
7.6 Two kinds of histograms.
7.7 A typical location map.
7.8 A 3-D histogram.
7.9 Time-series as “wiggles” along a track.
7.10 Geographical bar graph.
7.11 The RGB color cube.
7.12 Optimal triangulation of data.
7.13 Display of vector fields in GMT.
7.14 Gridding of data and trend surfaces.
7.15 Gridding, contouring, and masking of data.
7.16 More ways to grid data.
7.17 Clipping of images using coastlines.
7.18 Volumes and geo-spatial selections.
7.19 Using color patterns and additional PostScript material in illustrations.
7.20 Using custom symbols in GMT.
7.21 Time-series of RedHat stock price since IPO.
7.22 World-wide seismicity the last 7 days.
7.23 All great-circle paths lead to Rome.
7.24 Data selection based on geospatial criteria.
7.25 Global distribution of antipodes.
7.26 General vertical perspective projection.
7.27 Plotting Sandwell/Smith Mercator img grids.
7.28 Mixing UTM and geographic data sets requires knowledge of the map region domain in both UTM and lon/lat coordinates and consistent use of the same map scale.
7.29 Gridding of spherical surface data using Green’s function splines.
7.30 Trigonometric functions plotted in graph mode.
8.1 Animation of a simple sine function.
8.2 Animation of a DEM using variable illumination.
8.3 Orbiting a static map.
8.4 Flying over topography.
B.1 Gridline registration of data nodes.
B.2 Pixel registration of data nodes.
C.1 Examples of rendered images in a PowerPoint presentation.
C.2 PowerPoint’s “Format Picture” dialogue to set scale and rotation.
F.1 Octal codes and corresponding symbols for StandardEncoding (left) and ISOLatin1Encoding (right) fonts.
F.2 Octal codes and corresponding symbols for Symbol (left) and ZapfDingbats (right) fonts.
G.1 The standard 35 PostScript fonts recognized by GMT.
I.1 Chartreuse in GIMP. (a) Sliders indicate how the color is altered when changing the H, S, V, R, G, or B levels. (b) For a constant hue (here 90) value increases to the right and saturation increases up, so the “pure” color is on the top right.
I.2 The 555 unique color names that can be used in GMT. Lower, upper, or mixed case, as well as the british spelling of “grey” are allowed. A4, Letter, and Tabloid sized versions of this RGB chart can be found in the GMT documentation directory.
I.3 The HSV color space.
I.4 When interpolating colors, the color system matters. The polar palette on the left needs to be interpolated in RGB, otherwise hue will change between blue (240) and white (0). The rainbow palette should be interpolated in HSV, since only hue should change between magenta (300) and red (0). Diamonds indicate which colors are defined in the palettes; they are fixed, the rest is interpolated.
J.1 Impulse responses for GMT filters.
J.2 Transfer functions for 1-D GMT filters.
J.3 Transfer functions for 2-D (radial) GMT filters.
K.1 Map using the crude resolution coastline data.
K.2 Map using the low resolution coastline data.
K.3 Map using the intermediate resolution coastline data. We have added a compass rose just because we have the power to do so.
K.4 Map using the high resolution coastline data.
K.5 Map using the full resolution coastline data.
M.1 The standard 22 cpt files supported by GMT.
M.2 The many forms of color legends created by psscale.
N.1 Custom plot symbols supported by GMT.
O.1 Equidistant contour label placement with -Gd, the only algorithm available in previous GMT versions.
O.2 Placing one label per contour that exceed 1 inch in length, centered on the segment with -Gn.
O.3 Four labels are positioned on the points along the contours that are closest to the locations given in the file fix.d in the -Gf option.
O.4 Labels are placed at the intersections between contours and the great circle specified in the -GL option.
O.5 Labels are placed at the intersections between contours and the multi-segment lines specified in the -GX option.
O.6 Labels attributes are controlled with the arguments to the -Sq option.
O.7 Another label attribute example.
O.8 Labels based on another data set (here bathymetry) while the placement is based on distances.
O.9 Tsunami travel times from the Canary Islands to places in the Atlantic, in particular New York. Should a catastrophic landslide occur it is possible that New York will experience a large tsunami about 8 hours after the event.
P.1 Example created in isolation mode

Acknowledgments

The Generic Mapping Tools (GMT) could not have been designed without the generous support of several people. We gratefully acknowledge A. B. Watts and the late W. F. Haxby for supporting our efforts on the original version 1.0 while we were their graduate students at Lamont-Doherty Earth Observatory. Doug Shearer and Roger Davis patiently answered many questions over e-mail. The subroutine gauss was written and supplied by Bill Menke. Further development of versions 2.0–2.1 at SOEST would not have been possible without the support from the HIGP/SOEST Post-Doctoral Fellowship program to Paul Wessel. Walter H. F. Smith gratefully acknowledges the generous support of the C. H. and I. M. Green Foundation for Earth Sciences at the Institute of Geophysics and Planetary Physics, Scripps Institution of Oceanography, University of California at San Diego. GMT series 3.x, 4.x, and 5.x owe their existence to grants EAR-93-02272, OCE-95-29431, OCE-00-82552, OCE-04-52126, and OCE-1029874 from the National Science Foundation, which we gratefully acknowledge.

We would also like to acknowledge the feedback we have received from many of the users of earlier versions. Many of these suggestions have been implemented, and the bug reports have been useful in providing more robust programs. Specifically, we would like to thank Michael Barck, Manfred Brands, Stephan Eickschen, Ben Horner-Johnson, John Kuhn, Angel Li, John Lillibridge, Andrew Macrae, Alex Madon, Greg Neumann, Lloyd Parkes, Ameet Raval, Georg Schwarz, Richard Signell, Peter Schimidt, Dirk Stoecker, Eduardo Surez, Mikhail Tchernychev, Malte Thoma, David Townsend, Garry Vaughan, William Weibel, Florian Wobbe, and many others, including their advice on how to make GMT portable to a wide range of platforms. John Lillibridge provided the original example 11; Hanno von Lom helped resolve early problems with DLL libraries for Win32; Lloyd Parkes enabled indexed color images in PostScript; Kurt Schwehr maintains the Fink packages; Wayne Wilson implemented the full general perspective projection; and William Yip helped translate GMT to POSIX ANSI C and incorporate netCDF 3. The SOEST RCF staff (Ross Ishida, Pat Townsend, and Sharon Stahl) provided valuable help on Linux, web, and CGI script issues.

Honolulu, HI, College Park, MD, Cornish, NH, and Faro, Portugal, Jun 2016


PIC

Figure 1: The four horsemen of the GMT apocalypse: Remko Scharroo, Paul Wessel, Walter H.F. Smith, and Joaquim Luis at the GMT Developer Summit in Honolulu, Hawaii during February 14–18, 2011.

The GMT Documentation Project

Starting with GMT version 3.2, all GMT documentation was converted from Microsoft Word to LATEX files. This step was taken for a number of reasons:

  1. Having all the documentation source available in ASCII format makes it easier to access by several GMT developers working on different platforms in different countries.
  2. GMT scripts can now be included directly into the text so that the documentation is automatically up-to-date when scripts are modified.
  3. All figures are generated on the fly and included as GMT EPS files which thus are always up-to-date.
  4. It is easy to convert the LATEX files to other formats, such as HTML, SGML, PostScript, and PDF.
  5. The whole task of assembling the pieces, be it generating figures or extracting text portions from the master archive under subversion control, is automated by a makefile.
  6. Only free software are used to maintain the GMT Documentation.

Please post a New Issue from GMT home page if you find errors or inconsistencies in the documentation.

A Reminder

If you feel it is appropriate, you may consider paying us back by citing our EOS articles on GMT (and perhaps also our Geophysics article on the GMT program surface) when you publish papers containing results or illustrations obtained using GMT. The EOS articles on GMT are

The article in Geophysics on surface is

GMT includes some code supplied by others, in particular the Triangle code used for Delaunay triangulation. Its author, Jonathan Shewchuk, says

“If you use Triangle, and especially if you use it to accomplish real work, I would like very much to hear from you. A short letter or email (to jrs@cs.cmu.edu) describing how you use Triangle will mean a lot to me. The more people I know are using this program, the more easily I can justify spending time on improvements and on the three-dimensional successor to Triangle, which in turn will benefit you.”

A few GMT users take the time to write us letters, telling us of the difference GMT is making in their work. We appreciate receiving these letters. On days when we wonder why we ever released GMT we pull these letters out and read them. Seriously, as financial support for GMT depends on how well we can “sell” the idea to funding agencies and our superiors, letter-writing is one area where GMT users can affect such decisions by supporting the GMT project.

Copyright and Caveat Emptor!

Copyright 1991 – 2017 by Paul Wessel and Walter H. F. Smith

The Generic Mapping Tools (GMT) is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation.

The GMT package is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file LICENSE.TXT in the GMT directory or the GNU General Public License for more details.

Permission is granted to make and distribute verbatim copies of this manual provided that the copyright notice and these paragraphs are preserved on all copies. The GMT package may be included in a bundled distribution of software for which a reasonable fee may be charged.

The Generic Mapping Tools (GMT) does not come with any warranties, nor is it guaranteed to work on your computer. The user assumes full responsibility for the use of this system. In particular, the School of Ocean and Earth Science and Technology, the National Oceanic and Atmospheric Administration, the National Science Foundation, Paul Wessel, Walter H. F. Smith, or any other individuals involved in the design and maintenance of GMT are NOT responsible for any damage that may follow from correct or incorrect use of these programs.

Typographic conventions

In reading this documentation, the following provides a summary of the typographic conventions used in this document.

  1. User input and GMT or UNIX commands are indicated by using the typewriter type style, e.g., chmod +x job03.sh.
  2. The names of GMT programs are indicated by the bold, sans serif type style, e.g., we plot text with pstext.
  3. The names of other programs are indicated by the bold, slanted type style, e.g., grep.
  4. File names are indicated by the underline type style, e.g., gmt.h.

Chapter 1
Preface

While GMT has served the map-making and data processing needs of scientists since 19881, the current global use was heralded by the first official release in EOS Trans. AGU in the fall of 1991. Since then, GMT has grown to become a standard tool for many users, particularly in the Earth and Ocean Sciences. Development has at times been rapid, and numerous releases have seen the light of day since the early versions. For a detailed history of the changes from release to release, see file ChangeLog in the main GMT directory. For a nightly snapshot of ongoing activity, see the online ChangeLog page.

The success of GMT is to a large degree due to the input of the user community. In fact, most of the capabilities and options in GMT programs originated as user requests. We would like to hear from you should you have any suggestions for future enhancements and modification. Please send your comments to the user forum on the GMT home page.

1.1 What is new in GMT 4.x?

GMT 4.x will continue to see corrections of legacy bugs and problems, but no new features will be added. Therefore, the GMT 4.x releases are mostly bug-fixes as all development is now focussed on GMT 5; this new series, released Nov-5, 2013, is distinguished by being completely restructured to allow developers access to high-level GMT modules from a variety of programming environments. Below is a brief history of the development milestones in the 4.x series. We expect to maintain the GMT 4 series for some time until GMT 5 has reached a stable state and work on GMT 6 has began.

1.1.1 Overview of GMT 4.5.16 [June-25, 2017]

We have corrected a few bugs and other issues for individual programs in the mgd77 supplement:

mgd77/mgd77.c
: Fix format order search. Issue #1039. Set the priority of formats to match GMT5: MGD77+ first, then MGD77T, MGD77, and plain text table.
mgd77/mgd77convert.c
: Specify new search order if extension not given.
mgd77/mgd77header.c
: Added -Mt and removed unused code. Removed unrelated options from careless copy/paste via mgd77/mgd77list.c.
mgd77/mgd77info.c
: Specify new search order if extension not given.
mgd77/mgd77list.c
: Clarified usage of E77 bits in source and docs Did not use bitflags set with -Af correctly.
mgd77/mgd77path.c
: Specify new search order if extension not given.
mgd77/mgd77sniffer.c
: Replace wrong use of common options -B, -K, -P with options -M, -E, and -Z, respectively.
mgd77/mgd77track.c
: Failed to reduce time by time_inc before plotting marker. Specify new search order if extension not given.

1.1.2 Overview of GMT 4.5.15 [October-1, 2016]

We fixed some old compiler-flags that prevented compilation under recent version of Solaris and removed some copyrighted Numerical Recipes code in the meca supplement that were not even used. In addition, we made a few bug corrections for individual programs:

gmt_map.c
: Did not compute correct length of clip path for azimuth-elevation projection.
pscontour.c
: Would crash if no contours were requested.
grdtrack.c
: The -Z option did not deactivate -: for output.
surface.c
: Critical bug in which the test to determine if a Cartesian data point is “close” to a node would find most points to be close and bypass the Briggs scheme.
mgd77/mgd77list.c
: Can only use logical field tests on observed data columns.
sph/sphinterpolate.c
: Fix the vertical flipping under -Q0 mode.

1.1.3 Overview of GMT 4.5.14 [Nov-1, 2015]

Another bug-fix release with a few bug corrections for individual programs:

gmt_plot.c
: Fix issue # 662 with graph arrows for negative scales. Flipping the n/s sides array when lon and -y axes fixes issue #520.
gmt_support.c
: Fix bug in jump near Dateline in gmt_inonout_sphpol_count, affecting inside/outside spherical cases, reported in message-2219.
meca/psmeca.c
: Was unable to read any value x and y coordinates.
share/cpt/GMT_wysiwyg.cpt
: Fix typo in blue for high end [Issue #689].

1.1.4 Overview of GMT 4.5.13 [Jan-1, 2015]

Another bug-fix release. The default coastline version is now at 2.3.4. Below is the list of bug corrections for individual programs:

gmt_bcr.c
: Fixed problem with points slightly outside region causing an access violation; see issue #620.
gmt_map.c
: The map region clip path for -JE/-Je was hardwired to a full circle and did not care about -R setting. When -R...r and -JE/-Je was given the search for enclosing geographic boundaries failed when either the S or N pole was the projection’s antipole. Rect clipping with -Rw/s/e/nr could introduce stray lines when dataset has features about 180 degrees away from the user’s area. Could run into trouble clipping polygons for non-periodic maps. Added more checks in GMT_wesn_clip.
gmt_plot.c
: Left a PSL variable undefined when grdimage plotted a grid with x = longitude and y = Cartesian.
gmtmath.c
: Fix the order of when input files and -C interact.
gmtselect.c
: The -Fpolygon option might miss points because the io-machinery would sometimes set the min/max longitudes found incorrectly. The -Z option needed to pass records with NaNs.
grdfilter.c
: Fix y-shifts when -I sets smaller output spacing (issue #616).
grdmath.c
: Fix bug in grdmath’s KM2DEG operator.
psxy.c
: Fixed wrap-around issue in fault lines.
psxyz.c
: Fixed wrap-around issue in fault lines.
sample1d.c
: Fix resampling for decreasing t values.
mgd77/mgd77sniffer.c
: Needed to check that grid values used in decimate function also were within reasonable range.
x2sys/x2sys_solve.c
: Fix problems that arise when a track has less crossovers than model parameters.

1.1.5 Overview of GMT 4.5.12 [Mar-1, 2014]

Unbeknownst to many software developers, Apple changed the behavior of strcpy in Mavericks in an effort to strengthen the security of user codes. This caused ps2raster.c to crash for OS X users when it in the past had worked fine. The problem was easily corrected but meant that all those who had just upgraded to Mavericks were in a bind. This update corrects this problem, as well as several bugs. We also had to revert the behavior of the grdmath operator SDIST to again return km instead of degrees since it cannot do degrees for geodesics. By doing km it is now aligned with what PDIST and LDIST return for geographic data, and matches the behavior in GMT5. Some scripts had to be modified to handle the new behavior. If you use SDIST you may wish to check your usage. To assist users wanting spherical degrees we have added the two conversion operators KM2DEG and DEG2KM that can be used if the ELLIPSOID setting is Sphere. Finally, since GSHHG 2.3.0 has now been released we set that as the default coastline version. Below is the list of bug corrections for individual library files or programs:

gmt_grdio.c
: When building the grid command string it could exceed its maximum length if the argument became exactly the max length of the array; then the final extra zero character would be added and exceed array length. This was a rare occurrence. Thanks to Joachim Saul for pointing it out.
gmt_map.c
: Protect against longitude wrap in the Haversine and Rudoe formulae for distances. Prevent integer overflow when calculating image array size.
gmt_plot.c
: Grid crosses clipped by map boundary were badly reoriented.
gmt_proj.c
: GMT_eckert4 and GMT_eckert6 did not increment iteration counter and could in rare situations get stuck in an infinite loop.
gmt_support.c
: Allow GMT_crossover to deal with global wrapped data.
gmt_vector.c
: Add protection against introduced longitude-jumps produced by resampling in GMT_fix_up_path.
grdlandmask.c
: Failed to fill in some partial bins with no actual coastlines going through, in particular when crossing Greenwich.
grdmath.c
: Operator SDIST used spherical calculations for geodesics and ellipsoidal calculations great circles (we want the opposite). Now returning distances in km.
grdvector.c
: The new testing of -I arguments failed for some grids. Vector direction did not adjust when negative scales were used in -JX or -Jx.
ps2raster.c
: Did not check if source and destination given to strcpy were the same; this was always undefined behavior that now triggers an exit. Also added better check on the return code from the system calls in case gs or gdal_translate return with an error. Finally, make sure that image references in KML files do not carry a directory name.
pscoast.c
: The processing of -I and -N levels and pens could get out of sync so that the wrong pen was used for the specified feature.
pslib.c
: Take superscripts and subscripts into account when determining dimensions of text box. Also auto-widen paragraph width if the widest word actually is wider that chosen paragraph width.
psxy.c
: Vector direction did not adjust when negative scales were used in -JX or -Jx.
psxyz.c
: Vector direction did not adjust when negative scales were used in -JX or -Jx.
mgd77/mgd77header.c
: Fix selection of 10x10 degree identifiers.
misc/gmt2kml.c
: Make sure the default style IDs are unique for each process.
x2sys/x2sys.c
: Mishandled the assignment of segment number for each record.

1.1.6 Overview of GMT 4.5.11 [Nov-5, 2013]

Note: Due to a few technical issues we had an aborted update to 4.5.10 that was briefly released, then retracted; hence the 4.5.11-numbered version. GMT 4.5.11 is another service release with bug-fixes only. The only non-bug change was adding the latest dimensions for recent Sandwell/Smith img files that go up to 85, and adding definition file dat.def for mgd77 ASCII DAT format to the x2sys supplement. We also had to modify the –S option in pscontour.c to address a bug. This GMT release also coincides with the latest GSHHG release version 2.2.4 which adds a few missing lakes to California and fixes an error in the Baffin Island coastline and removes skinny spikes from numerous features. Below is the list of bug corrections for individual library files or programs:

gmt_customio.c
: The magic recognition of native bit grids failed due to bad math. Wrote wrong number of bytes per record for odd-width Sun rasterfiles.
gmt_grdio.c
: Would restrict grid region in grdimage.c despite doing a global map with azimuthal projections.
gmt_io.c
: Formats for degree annotations using colons should never end in a trailing colon. Could not properly decode yyodd (no delimiter) time coordinates like 12Oct24. The GMT_import_table function checked for greenwich before assigning the input data.
gmt_init.c
: Shifted JD origin by one day (24 Nov, instead of 25 Nov).
gmt_map.c
: The oblique Mercator would get the pole on the wrong hemisphere. When -Jx is used with longitudes we must use the wesn clipping and outside functions, not the Cartesian ones. Fixed clipping problem in GMT_wesn_clip for regions larger than 180 but less than 360. GMT_grdproject_init did not handle increments that had been specified as units, e.g., -D30e.
gmt_plot.c
: Did not check for map-jumping in GMT_plot_rectangle (psxy -SJ).
gmt_proj.c
: Inverse -JR blew up at origin; now added a check. Needed to allow for minor round-off when determining if a point is beyond the horizon for -JG general perspective projection.
blockmean.c
: Did not use data near west column nodes that were off by 360 for gridline registered grids.
blockmedian.c
: Did not use data near west column nodes that were off by 360 for gridline registered grids.
blockmode.c
: Did not use data near west column nodes that were off by 360 for gridline registered grids.
filter1d.c
: Susceptible to round-off when determining t of first and last output point when -T was not given.
gmtmath.c
: The MIN and MAX operators ignored NaNs, but result should be NaN if one of the operands equal NaN. Wrong index order in rarely used SVD part of LSQFIT.
gmtset.c
: Did not write values to .gmtdefaults4 if BASEMAP_TYPE was graph or inside.
grdfft.c
: Fix normalization for std.dev of power estimate in -E.
grdimage.c
: Fix bug represented by the globalgrid.sh test script for mix of -R selections and pixel/gridline choices.
grdblend.c
: Despite geographic grids there were no check to shift a grid region by 360 to match specified output region.
grdlandmask.c
: Did not set output as geographic after using -Jx1d.
grdmath.c
: The MIN and MAX operators ignored NaNs, but result should be NaN if one of the operands equal NaN. The XOR operator was incorrect, it is now clarified to be 0 if A == NaN and B == NaN, NaN if B == NaN, else A. Fix bug in CURV operator.
grdsample.c
: When given a -Rg grid and giving -Rg on command line, the output region became -360/0 instead of the expected 0/360.
grdtrend.c
: We messed up an interior parameter array in the 2009-10-14 fix in 4.5.2. This affected robust fits and grids with NaNs.
grdvector.c
: Did not reject vectors on far side of orthographic maps. Enforce that -Idx/dy must be multiples of grid dx/dy and abort if they are not. Before we would crash, hang, etc.
greenspline.c
: The normalization for 2-D with geographic data suffered from not checking that longitudes may be off by 360. Needed -f in order to select -f0T input, plus it made assumptions about getting lon,lat despite not being selected. When -T was used the number of z-layers (1) was not initialized.
nearneighbor.c
: Clarify how -N works, what the defaults are, and let the minimum number of sectors default to 50% of sectors instead of a hard-wired 2.
pscontour.c
: Added -St to skip triangles whose 3 vertices are outside domain; in contrast, -S or -Sp skips all points outside domain before triangularization.
psmask.c
: Multiple, ancient bugs fixed: properly mark used edges, fix memory allocations, not report clipping if -D is used, starting point for a contour was not offset by 1/2 pixel. Was off by one in the grid index calculation.
pstext.c
: The line in -D...v was plotted on top rather than beneath box.
xyz2grd.c
: For -E, must read data as double so can properly compare with the nodata_value read as double.
meca/psvelo.cc
: Called get_trans at north pole and tried to find a point further north. Did not honor the -N setting.
mgd77/mgd77list.cc
: The azimuth written was back-azimuth, not forward. Picked id = time_column when set was 1 (custom), causing the first custom data column to be formatted as time (this is for the netCDF format files).
sph/sphdistance.c
: Make sure we visit replicated columns for gridline registered grids.

1.1.7 Overview of GMT 4.5.9 [Jan-1, 2013]

Predominantly a bug-fix release, we also have made some changes to GSHHS. First, GSHHS is now called GSHHG, the “Global Self-consistent Hierarchical High-resolution Geography”, since GSHHG contains both shorelines as well as political boundaries and rivers. GSHHG, being required by both GMT 4 and 5, is now released separately from GMT. Second, we have made some minor changes to a few islands that have shown to be offset with respect to modern data (Tahiti, Moorea, and Mehetia in South Pacific and Agalega Islands in the Indian Ocean). Third, we have removed the item known as “Sandy Island” in the Corel Sea since available satellite data show no evidence of land in this area. Finally, we have purged 48 duplicates of very small islands (mostly in the Red Sea, Persian Gulf, and the Cook-Austral archipelago) where inaccurate WDBII versions and accurate WVS versions of the same features had survived our initial processing. This GMT release thus coincides with the latest GSHHG release version 2.2.2. We also fixed a typo in the MJD date in the gmtdefaults.txt documentation and updated the CM4 coefficient files for the mgd77 supplement.

Below is the list of bug corrections for individual programs:

gmt_grdio.c
: For -R...r the adjusted w/e/s/n for a grid could have excessive e/n values, leading to extra work and large intermediate grids.
gmt_map.c
: With -R...r and -JE, pscoast could end up trying to paint a block that is outside the rectangular region yet whose projection completely contains the region. Clipping function could shift the w/e boundaries by an extra 360, thus finding nothing inside in some pscoast tiles.
gmt_shore.c
: Will now look for either “.nc” or “.cdf” GSHHG files; needed since GSHHG is now stand-alone. Also look in given dir directory if compiled in via configure with-gshhg-dir=dir.
gmt_support.c
: Improved contour orientation function for grdcontour -F, thanks to Thomas Hottendorff. Resolved case of crossings at perfect saddles.
gmtmath.c
: Operators UPPER and LOWER did not assign output to rows that contain NaN.
grdfilter.c
: For -D4 we must set scale based on max |lat| in input grid.
grdproject.c
: The north coordinate would get reset to 2 when -C was used, thus creating wrong map setup calls.
project.c
: Had to backport changes implemented in GMT 5 to make the -C-T-G combination work properly.
pslib.c
: Typo in array index in European letter shorthands for German double-s; thanks to David Lachapelle.
psxy.c
: Would hang for -Jx...d due to wrong meter-per-degree variable.
meca/psvelo.c
: Bug in parsing the -A arguments.
mgd77/mgd77.c
: Copied 4 rather than 2 characters into day field, causing overflow and SEGV.
mgd77/mgd77magerf.c
: The -A+ttime option did not parse ISO calendar items.
misc/dimfilter.c
: Initialized a max value to -DBL_MIN instead of -DBL_MAX.
spotter/backtracker.c
: First and last point in a path was not converted back from geocentric coordinates.
spotter/libspotter.c
: Did not check for time reversals among total reconstruction rotations.
spotter/originator.c
: Bad format statement would wreck the 5th output column when run in default mode.
x2sys/x2sys_cross.c
: Did not convert time to seconds before calculating speed. Disallowed the distance gap check if time was present.

1.1.8 Overview of GMT 4.5.8 [Apr-1, 2012]

Another bug-fix release, except for the mgd77 supplement where we now have added support for the new MGD77T tab-delimited format introduced by NGDC, and for ps2raster.c under Windows where the Ghostscript executable path is now fetched from the registry. In case that fails, we fall back to the old “get it from the path” mechanism. One common bug shared by several programs was the failure to consult FIELD_DELIMITER and/or D_FORMAT for ASCII output formatting. Below is the list of bug corrections for individual programs:

gmt_customio.c
: Change nx and ny to “unsigned short int” type in surfer6 header. Note that original format specification by Golden Software clearly say they are “short int” but this change shouldn’t break anything and will allow dealing with larger grid sizes.
gmt_grdio.c
: The opening of files for rec-by-rec grid reading had a mixed if-test that inadvertently could take us to the wrong else clause.
gmt_map.c
: -R0/360/... and -JMlon/lat would not set global_map properly, giving NaNs as scale.
gmt_plot.c
: Fixed the corner caps in linear basemap frames. In function GMT_xy_axis, string[GMT_CALSTRING_LENGTH] was used to hold labels that could be longer, leading to memory corruption.
gmt_proj.c
: For -JE, both projection center and its antipode gave x = y = 0. Now, antipode (which maps to a circle) results in NaN, NaN. Determine whether conic projections are north or south polar by looking at the selected region, not just the central point.
gmt_support.c
: Function GMT_crossover was susceptible to longitude wrapping. Function GMT_getfill got confused when a Windows path C:/etc was given as an pattern file (mixed up with :F and :B mechanism). In GMT_hold_contour_sub, a variable called closed (which could be a flag 0-3) was used as a 0/1 variable. Added variable is_closed = 0|1. Fixed error in reading colors of patterns in -G options. GMT_inonout_sphpol_count did not properly handle line segments that were exactly vertical in all cases, leading to errors as to a point being inside or outside a spherical polygon.
grdcut.c
: Now recognizes any region to be a global grid as long as nx*dx == 360. The -Z option would give incorrect region for pixel grids; print warning if output grid equals input grid (i.e., no change).
grdfilter.c
: Now recognizes any region to be a global grid as long as nx*dx == 360.
grdimage.c
: Now recognizes any region to be a global grid as long as nx*dx == 360.
grdinfo.c
: Now recognizes any region to be a global grid as long as nx*dx == 360.
grdlandmask.c
: Now recognizes any -R as a global grid as long as nx*dx == 360.
grdview.c
: Contouring could suffer from the same round-off issues that affected grdcontour (and fixed back in 2004). Now the same fix is applied here. Also let -S default to 0 as stated in man page; this matches the default in grdcontour. Also, when nodes are adjusted to avoid matching a contour value exactly (during contouring), the same adjustment must be made later when those nodes are used to determine how to stitch together polygons for fill.
minmax.c
: Avoid infinite loop if a record has different number of fields than expected.
nearneighbor.c
: Now recognizes any region to be a global grid as long as nx*dx == 360.
project.c
: For -Ginc -bo we failed to write any output.
xyz2grd.c
: On Windows it never actually opened the input data file, so a crash resulted down the road. Only require two input columns when using -An.
meca/pscoupe.c
: Could not read from stdin because of the cross dll boundaries on Windows, must use GMT_stdin instead of stdin.
meca/pspolar.c
: Could not read from stdin because of the cross dll boundaries on Windows, must use GMT_stdin instead of stdin.
meca/psvelo.c
: Did not show -A in the synopsis. Could not read from stdin because of the cross dll boundaries on Windows, must use GMT_stdin instead of stdin.
mgd77/mgd77.c
: Fix memory allocation bug in MGD77_Read_Header_Sequence where it was reading MGD77_RECORD_LENGTH records into a shorter MGD77_HEADER_LENGTH longer variable.
mgd77/mgd77list.c
: Confused the meaning of the -F shorthands mgd77 and all. Now handle all stored and derived quantities needed to reproduce original data files.
mgd77/mgd77track.c
: Did not set GMT’s time system to Unix before dealing with dates. Now done centrally by MGD77_Init.
x2sys/x2sys_cross.c
: A memset call used wrong size if 64-bit, thus not resetting some boolean values causing crossovers to be missed.

1.1.9 Overview of GMT 4.5.7 [Jul-15, 2011]

This is another bug-fix release, including an update to GSHHS (now at 2.2.0) which fixes a truncation error for the polygon areas (which only affected users of the gshhs supplement and not GMT itself). The supplement tool gshhs now has a few more options to allow better feature extraction for GSHHS users. Below is the list of bug corrections:

gmt_agc.c
: Did not do proper indexing for complex data. Had wrong size for array floatvalue.
gmt_grdio.c
: Failed to create proper old-style v3 netcdf file if selected for as output format in grdblend. Did not account for the doubling of a grid array for complex data when scaling data after read. This made grdfft give odd results when grids with a scale other than 1 was read. Bug was first introduced in GMT 3.0 in 1995, making it a bug with seniority!
gmt_map.c
: The GMT_wesn_search did not handle periodic longitudes well, now replaced with proper quadrant checking as in minmax. GMT_wesn_clip needed to adjust longitudes to fit the given domain. Clip path for van Grinten was wrong for global maps.
gmt_mgg_header2.c
: Did not implement complex arrays at all.
gmt_plot.c
: Force arcs to be clockwise in GMT_pie and GMT_matharc.
gmt_support.c
: Hardwired DEG_TO_KM with Earth’s mean radius meant wrong distance results for other planets. Now using the current ELLIPSOID values.
pslib.c
: Did not restore to current font size after a sub- or super-script if a font size change had previously taken place. Also did not recompute sub- or super-script sizes after a font size change. [Thanx to Christian Sperber for noticing].
grdcontour.c
: Could crash if -C -A give no contours and we freed a non-allocated array. [Thanx to Walter Harms].
grdblend.c
: Now mentions which formats are supported and polices the process.
grdedit.c
: The -N option did not consider replicate w/e points for gridline-registered grids.
grdfilter.c
: The -Nr option did not work as it skipped assigning the NaN. Convolution weights were y-transposed so gave wrong results at/near the poles for spherical filtering. Also, some nodes were duplicated in the convolution, resulting in inconsistent values at the S or N pole. Now gives consistent values at poles and along shared E/W cols.
grdimage.c
: When image is grayscale and -Q is used then image must be converted to 24-bit and we set NaN color to a non-gray value.
grdlandmask.c
: Did not correctly truncate nodes for GSHHS bins with no data.
grdproject.c
: Output header had wrong units when non-inch settings were in effect.
grdview.c
: Removed grdview_init_setup because it yields unpredictable results and prevents lineup of different 3D plots.
mapproject.c
: Kept treating x,y as lon,lat when -G[lon/lat/]c (c for Cartesian) were given.
nearneighbor.c
: The -N1 selection did not reset the minimum sector setting to 1. For global region in longitudes, cannot extend w/e limits as we do for Cartesian and region-limited areas.
project.c
: The -G-T combination failed to produce great circles.
pscontour.c
: Got wrong contour level when some segments along edges were skipped.
pstext.c
: Option -L was missing from the synopsis. The -A option resets the text angle but also needed to reset justification.
xyz2grd.c
: Fixed bug when reading a file using -E option on Windows.
triangulate.c
: Did not check that input file could be found before trying to compute stuff and crash [Thanks to Orion Poplawski].
spotter/grdrotater.c
: Ensure that output grid xmin/xmax honors the current OUTPUT_DEGREE_FORMAT range settings. Could end up with w=e=0 in some cases.

1.1.10 Overview of GMT 4.5.6 [Mar-1, 2011]

This is another bug-fix release, including an update to GSHHS which fixes error is the Germany-Poland border and a few “spiky” islands. Therefore, this version requires the new GSHHS 2.1.1 release. We also patched some errors in the “jet” color table. Below is the list of bug corrections:

gmt_init.c
: On Windows: Look for HOMEPATH after HOME for setting GMT_HOMEDIR. Processing of mathangle symbol (-Sm[bfl]) confused the unit detector. The symbol-parsing for psxy and psxyz did not properly set the column types when no symbol size was given. This affected symbols that require angles (-Sw, -SE, -SJ) when unit was SI. The -: option messed up the column type arrays; should only swap x,y data columns, not type columns.
gmt_cdf.c
: Apply netcdf fix for open/fill; thanks to Sebastian Heimann.
gmt_grdio.c
: Increase the size of the string array in GMT_grd_get_units to avoid “Buffer overrun” that occurred with long description strings.
gmt_io.c
: When ASCII mode, also need to save/restore any netcdf i/o settings.
gmt_map.c
: Fixed bug in Haversine equation for duplicate point. For van Grinten: errors in left/right-circle functions. We have a safety valve for preventing a painful slow search around the map perimeter. The search is appropriate for maps but not for mapproject results. The limit was for 200 inch wide maps == 14400p. A user ran pscoast with 14401p and was caught. Now check for 400 inch and also check current page size (PAPER_MEDIA). If map width vastly outsizes the paper size then it is probably a projection job.
gmt_nc.c
: Apply netcdf fix for open/fill; thanks to Sebastian Heimann.
gmt_plot.c
: A colored TICK_PEN would also color annotations. Tried to free an unallocated array in GMT_draw_custom_symbol.
gmt_support.c
: GMT_cspline should initialize c[0] = c[n-1] = 0.0 in case it is called repeatedly [this is not the case in GMT]. When calculating how far to place an annotation from the tick mark we must check if a fancy frame width exceeds the tick length. GMT_inonout_sphpol_count failed to detect crossings if a polygon had vertical line-segments with same longitude as the point we were testing.
pslib.c
: Add check for incomplete escape sequences..
gmtselect.c
: Due to resampling of parallels in -N, some points exactly on a coast bin parallel could fail the test due to roundoff. Fixed by not resampling coastlines since it is a Cartesian test.
grd2xyz.c
: Extended -Ef mode to write floats (patch by Pierre Cazenave).
grdclip.c
: Now complains if no -S option was given.
grdfilter.c
: Allow -D2 and -D3 to handle periodic and polar boundary conditions.
grdlandmask.c
: Same as entry for gmtselect.c.
grdmask.c
: Must skip “polygons” with less than 3 points. Also, the resampling distance for spherical data was wrong, now 0.1 degrees.
grdproject.c
: Not providing -R was not working anymore. Test if hemisphere sign is provided when doing -Ju and no -R. Now assign proper x/y units.
grdtrack.c
: Message about -L being obsolete should only come when no modifier is given; else it is valid for BC setting.
ps2raster.c
: Bug fix after last -F option update. Must pass the optional -C args when calculating BB. Added -dSAFER as well, + fix -F option [F. Wobbe]. For some reason -W was not forcing -A. Now it does it again.
pscontour.c
: Did not find some contours following triangle edges.
pslegend.c
: Need to keep the original -R-J around for proper calls.
psscale.c
: Now patterns have constant orientation regardless of using horizontal or vertical bar.
nearneighbor.c
: Changed default to a more reasonable -N4/2.
splitxyz.c
: Did not list -Q in the synopsis.
surface.c
: Bug if using seconds (c) in search radius (got minutes).
triangulate.c
: Did not use projected coordinates when -R-J was given.
xyz2grd.c
: Do not tolerate NaNs in x,y and give error (e.g., if junk is given). Failed if -Evalue was given and the ESRI grid already had a nodata-value line. Now will process this line, if present. The value given on the command line will override any setting found in the file. Also made string-checks case-insensitive.
meca/utilmeca.c
: Patch to fix incorrect plotting of moment tensors with big isotropic components. Thanks to Jeremy Pesicek. Fix bug affecting the plot of P and T axis.
mex/grdwrite.c
: Round-off could lead to false detection of a non-equally spaced grid.
misc/gmt2kml.c
: Options -N+ and -D would crash under Windows (usual DLL hell).
spotter/backtracker.c
: For -W, now report full-length major/minor axes and not SEMI-axes (docs said major/minor but code did semi.)
spotter/grdrotater.c
: Did not handle the rotation of an entire global grid since the polygon outline interfered with the domain.
spotter/rotconverter.c
: Forgot to skip args when -N or -S was used.
x2sys/x2sys.c
: Minor bug in x2sys binary reading of floats.
x2sys/x2sys_datalist.c
: When geographic data and -R it failed to consider periodic longitudes.
x2sys/x2sys_get.c
: The -N option did not work properly, and the reported Y|N flags reflected the entire track on not just the portion inside the region. Man page updated to clarify what is returned.
x2sys/x2sys_init.c
: Did not write both of -Nd-Ns to the tag file. Crashed if -D was not given [should imply -DTAG].

1.1.11 Overview of GMT 4.5.5 [Nov-1, 2010]

This is again mostly a bug-fix release, and coincides with the availability of GMT 5.0.0α. Due to a few issues we had an aborted update to 4.5.4 that was never announced; hence the 4.5.5-numbered version. A few minor improvements have been added:

  1. The spotter supplement now converts geodetic latitudes to geocentric before doing spherical rotations and recovers geodetic coordinates for output (this new behavior can be bypassed by setting ELLIPSOID to Sphere). Thanks to L. M. Matias for pointing this out.
  2. We have added time-axes support for the Hawaiian language (Thanks to Kāwika Trang).

Here is the list of bug corrections:

configure
: Now sets correct mex extensions for 64-bit operating systems.
gmt_init.c
: The -B labels would not tolerate use of the text escape sequence @: (for changing font size).
gmt_map.c
: Did not check if nodes were beyond the horizon in GMT_grd_project. Also did not initialize output grid to NaNs before filling.
gmt_plot.c
: Bug in fault symbol psxy -Sfrc fixed (thanks to J. Robert). Also, GMT_map_latline and GMT_map_lonline functions tried to draw two-point lines when in fact no points were defined.
gmtdefaults.c
: The -D options would crash under Windows.
grdmask.c
: The -Ap|m options were ignored since the mode was not checked.
grdpaste.c
: Lacked -fg so could not paste 352/360 and 0/8 in longitudes.
grdtrack.c
: Did not ensure that given -R was adjusted to fit grid spacing.
mapproject.c
: Did not show/explain the option of appending + to -L. Corrected synopsis, usage, and man page. Did not reset azimuth to NaN at start of new segment.
minmax.c
: With -I, could end up returning -R355/0/... since 360 became 0.
nearneighbor.c
: Did not check if -S had not been set.
psbasemap.c
: The -L option had trouble parsing if there were + signs within the label string.
pscoast.c
: The -L option had trouble parsing if there were + signs within the label string.
ps2raster.c
: Made tolerant of \r-only line-endings which caused trouble before. The -A- option did not reset -A for -W.
psimage.c
: The justify text variable must be 3-char longs to hold trailing 0. This caused SEGV on some systems.
psmask.c
: Did not warn if clipping levels were not restored in last overlay.
pstext.c
: Added missing description of -A option.
.html]psxy[z].c
: Units given in -S without sizes (e.g., -Sci) would be ignored and overridden by MEASURE_UNIT. The -Ap|m options were ignored since the mode was not checked.
mgd77/mgd77manage.c
: The -F option had no break statement to prevent fall-through.
mgd77/mgd77track.c
: Had inactive code to write segment header to output.
mgd77/mgd77list.c
: The -G option was not listed in synopsis or usage, only in the man pages. Also -Fall+ and -Fmgd77+ did not append the auxiliary columns properly.
mgd77/mgd77magref.c
: The -D option failed on numeric arguments.
misc/gmtstitch.c
: Could crash if -C was used.
misc/gmt2kml.c
: Did not parse -D“description” for points. Only append running number when a segment has more than one point, else just use segment label.
spotter/rotconverter.c
: Complained of “bad option” when a rotation with a negative longitude was given on the command line, e.g., -135/35/-2.5. Would sometimes issue a rotation twice (for the same time).
sph/Makefile
: Did not have LDFLAGS in link statement.

Also, Appendix F had missing shading for two items in the Standard+ table, and example 23 placed the city names at an angle of 1 degree rather than horizontally.

1.1.12 Overview of GMT 4.5.4 [Nov-1, 2010]

A few minor technical issues in the distribution led us to make a few changes and increment the version to 4.5.5.

1.1.13 Overview of GMT 4.5.3 [Jul-15, 2010]

This is mostly a bug-fix release, including more corrections to the political boundaries distributed via the GSHHS netCDF files (these affect the Syria-Israel, Israel-Jordan, Moldova-Ukraine, and the Eritrea-Ethiopia borders) as well as missing river-lake metadata in the GSHHS distribution. Therefore, this version requires the new GSHHS 2.1.0 release.

Here is the list of bug corrections:

configure
: Fixed reversed use off –enable-flock.
gmt_init.c
: Chop off any eventual EOLs characters that might be in argv strings as it will happen when it was created by a shell command. We need this so that native Windows binaries can be used in Cygwin.
gmt_io.c
: GMT_is_a_blank_line saw “t” instead of TAB as whitespace. Added GMT_io.skip_duplicates [FALSE] to control if consecutive records with identical x,y should be skipped. This is needed by programs that uses GMT_sph_inonout, which does not expect to find duplicates vertices. GMT_fgets now checks for input record truncation and handles this gracefully (gives warning and winds to next record).
gmt_map.c
: Tried to free memory when nothing had been allocated. GMT_wesn_clip function would clip polygons even though there were no restrictions on longitudes (w/e = 360).
gmt_plot.c
: Parallels that should be straight (e.g., in -JI) would sometimes appear with jump gaps. Fixed bug in GMT_plot_map_scale that could lead to endless loops when using scales to 100 km or any exact power of 10. Error was limited to 64-bit.
gmt2rgb
: Option -G was freeing the output name before it was even allocated.
grdcontour.c
: The L or H color for first min/max annotation was not set. Placement of H and L annotations improved by using centroids.
grdmask.c
: Did not handle periodic longitude input when -fg was used.
grdview.c
: Fixed bug in parsing of -W[m|c|f] option when color starts with [m|c|f]. Check that topo and illumination file have the same size, otherwise it would crash.
greenspline.c
: Must insist that one of [-R-I], -N, or -T is specified.
mapproject.c:
: Applied scaling to -Cdx/dy when -Fk was used, despite docs saying -C is in meters when -F is used. Fixed, and clarified docs/man to say with -F, -C is always in meters.
nearneighbor.c:
: Did not handle periodic longitude input when -fg was used.
ps2raster.c:
: Now checks that all PS files begin with %!PS. End matter did not get parsed when there is no %%Orientation.
pshistogram.c:
: Fixed incorrect bin count when a datapoint equaled xmax.
pslegend.c:
: Uninitialized text string could put garbage in script.
psmask.c:
: Did not handle periodic longitude input when -fg was used.
psxy.c:
: For -Svs, the 2nd set of coordinates did not obey -:. The -Sw|W symbols did not handle the azimuth/direction conversions properly. Added better handling of dimensions with units passed via columns in the data file.
psxyz.c:
: For -Svs, the 2nd set of coordinates did not obey -:. The -Sw|W symbols did not handle the azimuth/direction conversions properly. Added better handling of dimensions with units passed via columns in the data file.
surface.c:
: Did not handle periodic longitude input when -fg was used.
meca/psmeca.c
: Removed out of place and repeated line to compute size in -a option.
meca/submeca.c
: Replaced calls to d_atan2 by d_atan2d since the code expects angles in degrees.
mgd77/mgd77.c
: Incorrectly added track list =tracks.lis as another track name after correctly including all the listed tracks. No harm done other than an annoying “Cannot find track =tracks” message.
mgd77/mgd77magref.c
: Fix bug in -A option when using const time in calendar format.
mgg/mgd77togmt.c
: Now has proper synopsis.
misc/kml2gmt.c
: Did not anticipate optional attributes for tags like <PlaceMark >, etc.
sph/sphtriangulate.c
: Incorrect items for cols 3–4 for -N.
x2sys/x2sys.c
: Need to include the “.” when checking if a suffix is present in a filename. Reading of data formats .gmt and custom returned all columns and not just the requested columns, causing errors upstream.
x2sys/x2sys_datalist.c
: Check to see if both lon and lat had been requested only checked for longitude (twice).
x2sys/x2sys_list.c
: Implemented -S[+] to print info relevant to both cruises.

Here is a list of the recent enhancement to various programs; these were introduced to correct mistakes or overcome limitations:

  1. gmtmath.c has added function SQR (square).
  2. grdgradient.c now lets -S work alone without requiring -G.
  3. grdmath.c] has added function SQR (square).
  4. pswiggle.c -Dxgap now allows gaps to be in projected distances.
  5. mgd77/mgd77.c was updated for 11th generation IGRF – IGRF2010.
  6. x2sys/x2sys_get.c needed –L+[list] so internal crossovers can be added.
  7. GMT_nighttime.cpt color table donated by Andreas Trawoeger.
  8. GMT_paired.cpt qualitative color table by Cynthia Brewer.

1.1.14 Overview of GMT 4.5.2 [Jan-15, 2010]

This is mostly another bug-fix release, including one that required us to add more meta-data to the GSHHS coastline netCDF files. Therefore, this version requires GSHHS 2.0.2 or higher. As was the case for 4.5.1, note that the GSHHS polygons themselves have not changed (still at version 2.0). We also added in the relatively recent Nunavut province boundary in Canada. However, some enhancements were added as well, most notably a new graph frame mode for linear projections (to add arrow heads to math axes) and a new symbol in psxy.c (to draw a circular arrow used to indicate angles); these capabilities are demonstrated in a new (and final) example 30. Finally, we fixed the long-standing problem of psxy -SE requesting major and minor axes but actually treating them as if they are semi-axes. We now consistently expect and use major and minor axes; you may thus notice a scaling of two if you continue to give semi-major/minor axes. Here is the list of bug corrections:

configure
: Fixed bug with –rpath.
gmt_customio.c
: Fixed bug resulting from releasing the pointer to from_gdalread structure before its members were freed.
gmt_gdalread.c
: Force computation of min/max since metadata info may be wrong.
gmt_grdio.c
: GMT_read_img did not apply swab if little-endian architecture.
gmt_io.c
: GMT_access did not check for NULL filename.
gmt_init.c
: Now guards against getting a negative hash value, which happened when text was Russian language codes from ru.d. If GMT_DATADIR was set to a list of colon-separated dirs then init failed since we tried to check access as if GMT_DATADIR was always a single entity (as in the past). Opened file with fopen but closed with GMT_fclose. Bug in the parsing of -Jglon/lat/radius/lat. Both .gmtdefaults4 and .gmtcommands4 were assumed to be in UNIX format. Now we properly chop off Windows or Unix end-of-line characters.
gmt_mgg_header2
: Opened file with GMT_fopen but closed with fclose.
gmt_plot.c
: qsort of GMT_LONGs was passed int arrays. The calculation of the actual plot width of a map scale did not account for the effect of a 3-D view angle.
gmt_shore.c
: Changes to accommodate new GSHHS2.0.2 netCDF files which needed more metadata to properly compute the level of tile corners after features where dropped due to size, etc.
gmt_support.c
: Increase the size of the variable that contains the path to a CPT file and the pathname to BUFSIZ bytes.
gmtconvert.c
: The -S option failed for actual matches; the 2009/5/26 change screwed that up. Now fixed and tested.
grdcontour.c
: The -Q option should only apply to closed contours, and -T failed to find an inside point for some oblique projections.
grdgradient.c
: Now, -Lg will imply -fg to properly set geographic units. Fixed bug where the gradient at the south pole was not replicated to x = east.
grdlandmask.c
: Round-off and bug caused missing nodes for -F with -Rd.
grdtrack.c
: The -Z option gave z-values a longitude formatting, including 360-degree wrapping.
mapproject.c
: The -S option failed after recent i/o makeover.
pslib.c
: Ellipse was wrongly dimensioned by semi-major and semi-minor axes, instead of major and minor axes. Also, memory never got freed by ps_free.
psrose.c
: Needed to set scale to 1 so the bounding box calculations would be correct for EPS output.
psscale.c
: The -Bg now correctly produces gridlines using GRID_PEN_PRIMARY.
psxy.c
: Incorrectly drew tips at plot boundary when clipping the error bars.
psxyz.c
: Fixed bug in distance sorting (also made much simpler).
imgsrc/img2google
: One gmtmath call did not have the required -Q.
mgd77/mgd77sniffer.c
: SEGV when an array index was allowed to become -1.
misc/gmt2kml.c
: Removed rogue newline before writing coordinates and an additional > in a tag.
misc/gmtstitch.c
: NULL segment headers were passed to strcpy() to give SEGV; also fixed output message when -C was used and only one segment was present.
misc/kml2gmt.c
: Mix of fopen and GMT_fclose not good under Windoze.
sph/sphinterpolate.c
: Bad index on line 317 went outside array limit. Also did not initialize the grid header properly.
sph/sphdistance.c
: Did not initialize the grid header properly.
spotter/backtracker.c
: When -L is set, -mo must be turned on automatically even if -m is not set.
spotter/grdrotater.c
: Bug in node index resulted in no longitudinal variation in the rotated grid.
x2sys/x2sys_init.c
: Did not accept -m, only the now obsolete -M.
x2sys/x2sys_datalist.c
: Did not retrieve the correct data columns when -F was used.
x2sys/x2sys_list.c
: Weights were not written out when names were selected as well, as in -Fncw.

Here is a list of the recent enhancement to various programs:

  1. fitcircle.c will let -S optionally take a fixed latitude instead of finding the best-fitting latitude [Default].
  2. gmtdefaults.c has new BASEMAP_TYPE = graph option for linear projections that wish to have their axes extended 7.5%, ending in arrow heads.
  3. grd2xyz.c has a new option -N which can be used to replace NaNs with another value on output.
  4. psxy.c now has a new symbol -Sm option for math angle, which lets user draw a circular arc with optional curved arrow heads at neither, one, or both ends.
  5. psxyz.c also has the new symbol -Sm option but does not draw the curved arrow heads yet.
  6. mgd77/mgd77manage.c adds attribute array of TZ corrections for the few cruises that stored TZ and local time instead of UTC time.
  7. spotter/rotconverter.c has new option -E to reduce stage pole opening angles by fact [0.5] (e.g., to get half-spreading rates).
  8. x2sys/x2sys.c now lets x2sys programs automatically strip off extensions for tracks given via list files. Also, various lists can contain header records.
  9. x2sys/x2sys_get.c has new option -E to select extensions on output, and -Q[i|e] to be used with -L. Finally, -D now only lists track names.
  10. x2sys/x2sys_solve.c has new option -Z to remove smallest dist/time for -Ed|t.

1.1.15 Overview of GMT 4.5.1 [Sept-20, 2009]

This is almost entirely a bug-fix release where we address several 64-bit incompatibilities and rebuild the netcdf GSHHS library to include some attributes from GSHHS that were needed by new options in pscoast and other programs. Note that the GSHHS polygons have not changed (still at version 2.0), but we had to update the derived netcdf repackaging used by GMT to 2.0.1. However, some enhancements were added as well, most significantly support for the polyconic projection (-JPoly), experimental support for grid and image imports via GDAL (requires –enable-gdal during configure and properly installed GDAL libraries and include files), and allowing -JXwidth/height to recompute a height given as zero based on the width (or vice versa) and the aspect ratio of the region.

Here is the list of bug corrections:

configure.ac
: Now use –enable-flock to enable file locking, instead of –disable-flock to disable if. Use –enable-64 to force 64-bit compilation, use –disable-64 to force 32-bit compilation; otherwise use default. Switch -DGMT_QSORT is now on only for OS X prior to Snow Leopard as the latter has a correctly working 64-bit qsort function.
gmt_customio.c
: Made surfer grid header i/o 64-bit compliant.
gmt_map.c
: Changed GMT_truncate from being a pointer function (PFL) to a regular function that simply calls GMT_truncate_x or GMT_truncate_tm depending on whether projection is TM. This to avoid problems with calling GMT_truncate with constant argument -1 in 64-bit machines and thus producing wrapped pscoast maps.
gmt_shore.c
: The -A+r|+l option was premature as more info in the GSHHS netcdf files were needed to properly skip features. Now working with the revision GSHHS 2.0.1.
gmt_support.c
: The routine that checks if a points is inside or outside a polar cap had trouble when a point’s longitude exactly equalled one of the polygon points since round-off could cause our test to fail. Fixed bug in x_inc variable as function of latitude. GMT_log_array recoded to avoid 64-bit error (last value was not included).
grdcontour.c
: The -L option was not used in limiting contours.
minmax.c
: The -EH option did not work.
psmask.c
: With -D, the internal di, dj constants were set way too large.
pswiggle.c
: With -Jxscaled, distances were not scaled correctly so -D failed.
mgd77/mgd77magref.c
: Got wrong time as time initialization had changed but not implemented in this program.
mgd77/mgd77sniffer.c
: Bug in -I option; needed to set bitpattern for bad faa.
misc/gmt2kml.c
: Option -T did not handle spaces in titles and folder names. Under Windows, the output got scrambled due to DLL hell.
spotter/backtracker.c
: Failed in 64-bit mode due to variable mismatches.
x2sys/x2sys_get.c
: The -L option failed if list contained file extensions.
x2sys/x2sys_solve.c
: Did not allocate array for storing weights.

Here is a list of the recent enhancement to various programs:

  1. gmt_customio.c now has optional GDAL read-only interface as format 22 (code gd).
  2. gmtset.c has new default TRANSPARENCY = stroke/fill that can change the PDF transparency for stroked and filled items [Note: Only supported by Adobe Distiller].
  3. pslib.c has added option to reduce all color to gray scale via PS_COLOR = gray.
  4. grdimage.c has optional support that allow single-band image import via GDAL.
  5. misc/nc2xy.c now has -bo option.
  6. mgd77/mgd77magref.c can combine IGRF and CM4 computations.

1.1.16 Overview of GMT 4.5.0 [July-15, 2009]

This is another significant update of the official distribution and hence it has a mix of bug fixes and program enhancements. We have added a new supplement (sph) which offers interpolation, triangulation (Delaunay and Voronoi), and distance calculations on a spherical surface. The hard work is done by the original effort of Robert Renka who developed the Fortran-77 SSRFPACK and STRIPACK libraries; these are here supplied via a f2c-assisted translation. The imgsrc supplement has a new Bourne script img2google, which simplifies making Google Earth tiles from Sandwell and Smith bathymetry. The mgd77 supplement has a new program mgd77magref, which is used to evaluate either the CM4 comprehensive geomagnetic model, a more sophisticated alternative to IGRF, or the IGRF. The misc supplement has received two new tools (gmt2kml and kml2gmt) that simplify the presentation of GMT data in Google Earth, and one (dimfilter) that offers directional spatial filtering of grids. The x2sys supplement has a new tool (x2sys_merge) to merge updated COEs table into a main COE table database. Finally, ps2raster.c has evolved further and can now be used to create simple KML files for Google Earth.

A major new enhancement is the global option -g, which is used to determine if excessive spacing between data points (“gaps”, to be defined in a variety of ways) should be used to segment an otherwise continuous line. We expect to enable -g in several programs during the next revision; at the moment it is available in gmtconvert, mapproject, psxy and psxyz. Given that all the lower-case GMT options deal with low-level data i/o settings we have decided to rename the -M option (which controls the presence of multiple segment headers) to -m; this allows us to promote this ubiquitous option to global status (i.e., has the same meaning in all GMT programs). Use of -M will remain valid for the rest of GMT 4.x but results in a warning about the new usage. Related to this is the introduction of a new parameter (NAN_RECORDS) that determines if NaNs in key columns (such as longitude, latitude) should constitute a line break or bad data to be skipped.

We have revised how ellipsoids are specified. When importing an ellipsoid file, we allow a,b,f as ellipsoid parameters, where b or f could both be zero. If file does not exist, attempt to read name as a[/[b=|f=]f], meaning semi-major axis, b=semi-minor axis, f = flattening, or inverse flattening. We have also added parameters for the TOPEX ellipsoid and for the Moon and planets (IAU2000).

This release of GMT coincides with the release 2.0 of GSHHS, the coastline data used by GMT. In addition to general improvements to the data, we have expanded the -A option that controls the limits on what features to extract. New modifiers allow users to exclude “river-lakes” and any feature whose area is less than a fraction of the original full resolution feature.

Finally, our configure script continues to evolve and now better supports installation on 64-bit systems and can automatically detect if and where netCDF exists on your system.

Here is the list of bug corrections:

gmt_customio.c
: In GMT_ras_read_grd_info, wrong size was passed to fread.
gmt_grdio.c
: Fixed bug in GMT_grd_setregion: longitudes were limited inward instead of outward. Caused white-space left and right in grdimage.
gmt_init.c
: No longer remove supposedly empty .gmtcommands4 file. Could have been written to by piped GMT command. Now create/write only when new matter is to be written.
gmt_io.c
: When only -mi is set there should be no multisegment headers on output. yet there was no if-test to check for that.
gmt_map.c
: Fixed serious bug in GMT_az_backaz_flatearth: incorrectly converted degrees to radians. Fixed bug in GMT_get_rotate_pole: called GMT_rotate_pole_forward with radians instead of degrees. Incorrectly attempted to free array only used when antialias is on. Fixed inability to determine projection pole when central meridian and western boundary are the same (Albers, Conic equidistant). Incorrectly used central longitude to set default midpoint for 3-D maps using the -E...+ mechanism when data were not geographic. Numerous bug fixes related to UTM: Did not report bad zone for < A or > Z; Zones A+B reached till 84S instead of 80S; Zone J wrongly produced value for Zone K; Zones U+W were not recognized; Now also equates Zone O to Zone P (already equated Zone I to J).
gmt_mgg_header2.c
: There was no support for (a) floating point grids and (b) swapping happened based on machine byte order and not based on actual file byte order.
gmt_nc.c
: Argument [layer] was not stripped from varname and would end up in output grid. Set zmin/zmax to NaN when info not in header.
gmt_plot.c
: Crashed when using time labels in 3D plot.
gmt_proj.c
: Fixed bug in longitude computation when standard parallel is on Southern Hemisphere.
gmt_support.c
: Exceeded array bounds in GMT_read_cpt for hsv conversion. The 3-D view -E option used in many programs (such as psxyz) could not handle exponential notations. Determining of a color scale is continuous should be based on HSV (not RGB) values when read as HSV. The modifier :radius[unit] to the -G option in grdcontour for the placement of contour labels is now +rradius[unit] since the colon interfered with ddd:mm:ss coordinates. Given -I601+/601+ the y-increment was not processed correctly. Fixed bug when x_inc in km, m, etc, the value was ignored (always 1).
blockmean.c
: Gave bogus usage about number of input columns when -E is set but -E only affects output. Same for blockmedian.c and blockmode.c.
gmtconvert.c
: With -S, did not report the number of output segments.
gmtmath.c
: Tried to free memory that was not allocated.
grdfilter.c
: Toggle -T was not processed correctly if -Rgridfile was given.
grdgradient.c
: For geographic grids, make sure N and S pole only has a single value on output.
greenspline.c
: Calculation of nz layers was off by one, leaving out the penultimate layer.
grdimage.c
: We now make sure the NaN color is unique when -Q is used.
grdmath.c
: The PDIST operator did not handle binary input files (as LDIST does).
ps2raster.c
: Exceeded memory allocation for out_file. Now in static memory.
psclip.c
: Produce at least “S V” when the clippath is empty.
pscoast.c
: Produce at least “S V” when the clippath is empty.
psscale.c
: When using -A with a vertical color bar, the annotations where left- in stead of right-aligned. When using -A on horizontal bar, the last tick mark would not appear.
gshhs/gshhs.c
: Checked wrong variable to test if a file was given on the command line.
meca/util_meca.c
: Needed to convert the output from d_atan2 to degrees.
mgd77/mgd77.c
: Was failing to read Windows terminated ASCII files. Fixed bug in MGD77_igrf10syn routine (mistake done while cleaning the f2c version) that resulted in altitude always being on Earth surface when geocentric coordinates were used. Do not use any GMT i/o-functions to access ascii files on creation/writing so that it can work under Windows as well. Converting files from netCDF to MGD77 where time = NaN gave junk records.
mgd77/mgd77list.c
: Used GMT_LONG in memset for an array allocated as int. Used wrong time for IGRF calculation; worst case situation was off by 1 year.
mgd77/mgd77manage.c
: The -D option would remove original attributes. Now both original and revised attributes are carried in memory. This problem also affected mgd77convert -FC if used on a file after mgd77manage -D had been run. Used wrong time for IGRF calculation; worst case situation was off by 1 year. Now uses GMT_read_img to handle *.img files; earlier the inline code would fail on the new extended img files.
mgd77/mgd77sniffer.c
: Did not reset the E77 structure between cruises.
misc/gmtstitch.c
: Did not read standard input if no files were given. Now honors -V properly.
x2sys/x2sys.c
: Wrong array argument passed for correction aux values.
x2sys/x2sys_cross.c
: Removed the -F option which was not honored anyway.
x2sys/x2sys_init.c
: Now properly copies the *.def file to the TAG dir.
x2sys/x2sys_datalist.c
: Only ASCII output had corrections (-L) applied.
x2sys/x2sys_put.c
: Fixed -D option (was falling in a endless loop).

Here is a list of the recent enhancement to various programs:

  1. gmt_init.c has added support for enhanced -E option for 3-D perspective views which allows the specification of a fixed point (needed for new Default setting NAN_RECORDS = skip|pass [skip]. If “pass” we treat let the programs handle the NaNs; for some programs the NaNs in input record will act as indicators of data gaps for continuous lines. If “skip” we report them as bad records. In both cases the records are skipped. Allow negative integer interval (-n) for annotating log axis; this means annotate every n’th power of 10.
  2. gmt_nc.c will properly handle netCDF that have LatLon = 0, 1: flip x and y.
  3. gmt_shore.c Added support for the +ppercent modifier to limit features whose area is less percent of the corresponding full-resolution polygon.
  4. gmt_support.c enables GMT_intpol to handle NaNs by treating them as segment boundaries. Rely on Shewchuk’s triangle function to get Voronoi output.
  5. blockmedian.c now returns the quantile(x), quantile(y) location when -T is used. Added -Eb to get box-and-whisker output (0. 25, 50, 75, and 100% quantiles).
  6. gmtconvert.c now allows -S~pattern which reports segments whose header does NOT contain pattern. Should pattern actually start with ~ we escape it with \~pattern.
  7. gmtselect.c can now handle dateTclock strings in -Z when used with data whose 3rd column contains time.
  8. gmtmath.c added MOD function (remainder after floored division, Knuth style). This is in contrast to FMOD which gives the remainder after (horror) truncated division.
  9. gmtselect.c Same upgrade to -A option as pscoast.
  10. grdcut.c has new option -Z which is used to determine a rectangular subregion so that the rejected area have values entirely outside the given z-range.
  11. grdfft.c now also has a Butterworth band-pass filter.
  12. grdinfo.c will now use plain text (and not code) to report the file format used. Add option -L0 to actually scan data to determine zmin and zmax.
  13. grdlandmask.c Same upgrade to -A option as pscoast.
  14. grdmath.c added MOD function (remainder after floored division).
  15. ps2raster.c takes -W+k to create a simple KML file for Google Earth. Several other modifiers help to populate the KML file.
  16. psclip.c has a new option -T that turns on map region clipping without any input data files; it is a shorthand for -N/dev/null.
  17. pscoast.c has enhanced -C[l|r/]it fill offers to paint river-lakes separately from lakes. The -A option can be used to exclude river-lakes or lakes for level 2. -W now allows different pens for the 4 levels of shorelines.
  18. pglegend.c allows S record not to have text. Until now, when left empty would use whatever text was set to in previous record. The > record no longer needed before T; T, L, S, H alignment harmonized; I, M, B spacing improved; -B option added.
  19. psxy.c added -g to break lines into segments based on gap criteria; added -T to be a shorthand for reading no input, where we used /dev/null before.
  20. psxyz.c added -g to break lines into segments based on gap criteria.
  21. triangulate.c has new option -Q to generate Voronoi polygon edges.
  22. mgd77/mgd77convert.c allows users to give file.ext on command line.
  23. mgd77/mgd77list.c can now take -DA and -DB which, in the presence of time = NaN, will not output such records [-Da|b will]. Also clarified the ranges implied by -D and -S. Added -Fytime which gives decimal absolute year for time output. Modifier -At added which attempts to create fake cruise times based on header information and distance along track.
  24. mgd77/mgd77manage.c added -AE to ignore the verification status and process e77 anyway.
  25. mgd77/mgd77path.c added -P- to just list the IDs and not the full paths.
  26. mgd77/mgd77track.c added -Gt|dgap to recognize gaps in tracks based on distance or time between successive points.
  27. mgg/mgd77togmt.c added new -T and -W options to store total field and account for the magnetometer tow distance. Also tries to get info from header file.
  28. misc/gmtstitch.c has enhanced -T option to eliminate connections when the 2nd closest pair is too close. Also added -C option to simply separate the open from the closed polygons (no stitching). Added -L option to write out segment-link information.
  29. x2sys/x2sys_list.c can now accept list of weights for each track and output the composite weight for each crossover.
  30. x2sys/x2sys_solve.c has option -W means an extra column with crossover weight.

1.1.17 Overview of GMT 4.4.0 [Feb-15, 2009]

This is a significant update of the official distribution and hence has a mix of bug fixes and program enhancements. We have added a new program (greenspline.c) which offers interpolation and gridding in 1–3 dimensions using Green’s functions of various splines. Also, the misc supplement has a new tool (gmtdp.c) which offers line-reduction using the Douglas-Peucker algorithm we used for the various shoreline resolutions. The mex supplement has a new Matlab/Octave function (imgread.m) to directly read Sandwell/Smith *.img files. The x2sys supplement has three new programs: x2sys_list.c can extract a subset of crossovers from the list produced by x2sys_cross.c, x2sys_report.c reports statistics of crossovers, whereas x2sys_solve.c will determine systematic trends from a set of crossover errors. These programs are intended to replace the old x_system tools x_list.c, x_report.c and x_solve_dc_drift.c. We have also temporarily added GMT_qsort which is a 64-bit compliant version of qsort. The latter is broken under OS X 64-bit and is thus substituted on that platform only for 64-bit compilations until Apple fixes the problem. Finally ps2raster.c can now be used to create geotiff images if gdal is installed on your system. Here is the list of bug corrections:

gmt_customio.c
: Fixed sub-region access in Surfer format. This bug would manifest itself mainly when doing a grdcut with a N-S sub-region.
gmt_init.c
: Modified special checks for FreeBSD by also considering _AMD64_. -JXh was misinterpreted whereas -JXv was OK.
gmt_io.c
: Did not properly apply PLOT_DEGREE_FORMAT=ddd.x for decimal degrees.
gmt_map.c
: Determining where parallels and meridians intersected the map boundary was susceptible to roundoff for very small regions. Added improved clipping for geographic polygons using the Sutherland and Hodgman algorithm when there are no map jumps in longitude. Fixes problem with tiny strips of “land” along map perimeter for some projections.
gmt_math.h
: Check for macro definitions for system math functions.
gmt_plot.c
: Wrongly checked for map jumps for non-periodic map boundaries. Bug in GMT_fill_polygon that affected polygon outline. 3D text box was computed incorrectly. Could exceeded array size in GMT_epsinfo.
gmt_proj.c
: Fixed bug in Lambert conformal conic projection for southern hemisphere.
gmt_support.c
: Function GMT_get_arc did not check for division by zero. The -Gxfile:radius[unit] option in grdcontour.c passed the entire argument as the file name. Function GMT_polygon_is_open did not test for empty polygons (n = 0). Avoid interpolating hue (converted from RGB) over more than 180 degrees. Changed GMT_rgb_to_hsv to integer logic to avoid errors on some compilers. As a result: much shorter code as well.
gmt_vector.c
: Function GMT_resample_path would add 360 to points along meridians.
pslib.c
: ps_polygon can only split line when rgb[0] == -1 not < 0 since -3 now means to use a fill pattern. Redefined PostScriptcode for circle which needed a stroke (S) first, otherwise a line would be drawn from the previous symbol. Updated PSL_prologue.ps version. Image placement now in integers. Ensures that placement is consistent with e.g. box drawn with the same coordinates. Does not produce colormap with number of pixels and colors is the same.
gmtmath.c
: The D2DT2 operator whose boundary condition yields 0 should yield NaN if one or more of the nearby nodes are NaN.
grdblend.c
: A side-effect of the 2007-02-01 fix was that when the file is re-opened the row range is reset. Now the possible offset is computed during initialization but applied when the file is finally opened for reading. Better treatment of longitude periodicity if -fg is selected. E.g., if -Rg is used and a grid is -30/30 in longitude the output grid will consider 0-30 and 330-360 correctly
grdfilter.c
: -D5 did not initialize xscale so filter search box was set to region width which typically is much larger. The bug did not affect the results but unnecessarily increased runtime. Complained if -R was used and xmin was less than grid xmin for a full 360-range grid.
grdimage.c
: Failed to determine boundary of projected grid with enough precision.
grdmath.c
: Some 2nd-order derivatives whose boundary condition yields 0 should yield NaN if one or more of the nearby nodes are NaN.
grdreformat.c
: Since there is no longer a share/conf/gmt_formats.conf the usage message crashed. Did not initialize grid header structure and could get netCDF error “Named variable does not exist in file”. This could also occur in grd2cpt.c, grdedit.c, grdtrack.c, grdvector.c, grdview.c, and grdvolume.c.
psbasemap.c
: The syntax for the -L option had to change since one could not easily use the :label: specification if the coordinates were given in dd:mm[:ss] format. A new syntax has been implemented where one or more +?[args] strings are appended after the required parameters (see man page). Erroneously suggested that 3-D base was plotted at z=0, instead of at the bottom end of the z-axis.
pscoast.c
: The -Q option incorrectly required -J. Also, see revised -L as for psbasemap.c.
pslegend.c
: Now use Unix remove function to delete script after completion; this avoids a Windows problem.
psmask.c
: Fixed a bug for -D-file which did not write multi-segment headers.
psscale.c
: Logarithmic scale did not function properly when scale bar was vertical. When -I and -Li was used we did not draw box outlines. Did not check if -D was not given, and had wrong test for -E. Added -Aa and -Al options to move only the annotations or label to the other side of the color bar. Now requires -Ac to keep writing the vertical labels as columns.
pstext.c
: We incorrectly removed blank lines but those mark new paragraphs when in -M mode.
psxyz.c
: Did not pick up y-size for column from input data file.
xyz2grd.c
: For -E under Windows we used fscanf with a pointer from GMT DLL which would fail for mysterious reasons.
meca/psmeca.c
: Fixed bugs that would give strange beach balls for some input.
meca/pscoupe.c
: Fixed bugs that would give strange beach balls for some input.
misc/gmtstitch.c
: Check to see if format was set was wrong.
mgd77/mgd77.c
: Index array error resulting in wrong IGRF start and stop years was fixed. Now applies recalculation of fields requested by E77 flags as part of reading netcdf mgd77+ files. However, if the original anomaly was NaN then we leave it as is.
mgd77/mgd77sniffer.c
: Bitwise assignment error was deactivating other fields when depth field was missing from a cruise. Another bitwise error was overwriting E77 nav flags when navigation was found on land Updated sample grid function to handle longitudes for img files.
mgd77/mgd77track.c
: Missing newline after last source line.
spotter/backtracker.c
: The -W option always assumed the reverse rotation, i.e., from hotspot to seamount. Now obeys the -D option.
x2sys/x2sys_get.c
: Now handles -R with longitude periodicity correctly.
xgrid/xGridEdit.c
: Needed GMT_io_init to get all pieces needed to read grids.

Here is a list of the recent enhancement to various programs:

  1. gmt_init.c has added support for enhanced -E option for 3-D perspective views which allows the specification of a fixed point (needed for creating animations). Updated all programs to use the new option and added updated man page and synopsis to all programs. Now, -R may take the name of an existing grid file. Then, the grid domain is used to set -R as well as the grid increment (and registration) for those programs that have such options.
  2. gmt_map.c also has added support for enhanced -E option for 3-D perspective views.
  3. gmtmath.c has added new operators NOT and INRANGE.
  4. grd2cpt.c can now accept multiple grid files at once.
  5. grdfilter.c has new options -Np to honor any NaNs found so output can be NaN, -Nr to replace output node with NaN if input node is NaN, and -Ni to ignore NaNs [Default].
  6. mapproject.c has extended the -A option by making the fixed point optional; if not given we compute azimuths between successive data points.
  7. minmax.c has optional /col that may be added to -Tdz to select another column [third]. Added -S to leave space for error bars. Useful with -I and subsequent psxy -E.
  8. pscoast.c has a new modifier + to the -D option, which determines the next lower resolution should the selected one not be available. This enhancement also affects both gmtselect.c and grdlandmask.c.
  9. psimage.c has new -Gt option, with assignment of color to be made transparent.
  10. pslegend.c lets N (number of columns) also affect the printing of labels. Can now use rectangle among the symbols.
  11. psmask.c now has modifiers +nn_points and +q to the -D option to limit the minimum number of points a polygon must have and, to suppress PostScript output, respectively.
  12. pstext.c has enhanced -Z+ option expects z-level values in 3rd column.
  13. pslib.c internals now measure paper size in double precision points instead of truncating to nearest integer. To remain backwards compatible for pslib.c users we now initialize all plotting in GMT with ps_plotinit_hires instead of ps_plotinit. Allow transparency when plotting 8-bit images (as well as 24-bit). We now use a new implementation of ps_textdim to ensure proper alignment of texts and the optional surrounding boxes. Finally, wehave simplified the PostScript code for symbols and removed some limitations on plotting by officially moving to PostScript language level 2.
  14. ps2raster.c now will scan for the optional comment %%HiResBoundingBox which takes precedence over the values in %%BoundingBox. New format -TG turns on transparency for PNG output, and -Tb selects Microsoft BMP output. Formats b, g, j, and t accept modifier “-” to produce grayscale images. Added -Cgs-command to pass one or more custom switches directly to ghostscript, and -Q[g|t]bits to set the level of anti-aliasing for graphics and text, respectively. We also added a new option -F to force a specified output file name. Finally, added -W to help create world files and geotiff output. To simplify boundary annotations for such plots (which must be inside the map region) we added the new choice inside for the BASEMAP_TYPE default parameter.
  15. psxy.c has new option -Iintens to modulate fill color via a fixed illumination value.
  16. psxyz.c has the same new option -Iintens.
  17. xyz2grd.c has new format (A) for -Z which allows more than one floating point value per input record. Cannot be used if the z-values are in dateTclock or ddd:mm:ss format.
  18. mgd77/mgd77track.c has enhanced -A option to place cruise ID equidistantly (distance or time) along the track.
  19. spotter/backtracker.c has new option -e to specify a single fixed total reconstruction rotation that will be applied to all input points.
  20. x2sys/x2sys.c internals now has automatic swabbing of index files, if required. Can now handle netCDF 1-D COARDS files.
  21. x2sys/x2sys_init.c Now, the distance and speed unit settings (-C, -N) are set here and kept with the TAG for use in other x2sys programs.
  22. x2sys/x2sys_datalist.c now has [experimental] support for using a correction table and can compute auxiliary data such as distance and azimuth.

Finally, we have added three new examples to demonstrate plotting of *.img grids, mixing UTM grids and geographic projections, and using greenspline.c for gridding on a spherical surface.

1.1.18 Overview of GMT 4.3.1 [May-15, 2008]

This quick update only 2 weeks after the release of version 4.3.0 was prompted by the discovery of three serious bugs; two of which were quite old but had caused no harm until tested under Fedora 9. The third critical bug prevented the wholesale reading and writing of GRD98 format grids. In addition a few minor bugs were discovered; this is the list of all corrections:

gmt_io.c
: GMT_nc_input would not read all data columns when no variable names were given.
gmt_mgg_header2.c
: Passed two of the arguments to fread in the wrong order. Prior to version 4.2.0 the return code (which indicated an error) was not checked yet the read did return the correct data. With better error checking this latent bug now caused a refusal to read any GRD98 grid.
gmt_support.c
: Allow a little more slop in determining whether primary tick is at same location as secondary tick.
gmtselect.c
: Did not like a variable number of input columns. Now OK if both input and output is ASCII and there are at least 2 (3 with -Z) input columns present.
grd2xyz.c
: For option -E, the test for xinc == yinc was susceptible to round-off.
project.c
: Now explicitly initializes the pointers in the data structure to NULL since realloc does not initialize new memory (yet almost all implementations of realloc appear to have done so anyway, masking the memory bug).
psxy.c
: The -D option erroneously gave an error despite being used properly.
psxyz.c
: Similar problem as described for project.
xyz2grd.c
: The -S option incorrectly insisted that -G must be used.

In addition, many of the supplements did not work properly under Windows due to internal problems with the DLL. Finally, one enhancement snuck in before the decision to issue this update was made:

  1. gmt_init.c was enhanced so that the media size Custom_WxH can use W and H in inch, cm, or m by appending i, c, or m to each dimension [Default remains points].

1.1.19 Overview of GMT 4.3.0 [May-1, 2008]

Changes are once again a mix of structural improvements, bug fixes, and a few enhancements. The coastline files (now GSHHS 1.10) have seen minor modifications, the mex supplement now offers support for Octave, all source code is now fully 64-bit compliant, we have added an isolation mode option (if GMT_TMPDIR is defined, write temporary and hidden files to that directory), and the configure/make setup has been further improved (such as honoring CFLAGS and LDFLAGS set by user). Colors may now be specified as hexadecimal codes (e.g., #ff0000 for red), and projections can be specified by name (similar to Proj4). Finally, binary table data can now be COARDS-compliant netCDF files. As for documentation, we have now switched from C shell to Bourne shell (although the csh examples are still distributed).

The following lists specific enhancements or new program options:

  1. gmt_grdio.c is modified so the grid i/o supports the GMT_[DATA|IMG|GRID]DIR environment settings.
  2. gmt_init.c was enhanced so -U can now interpret a justification (e.g., just/dx/dy on the command line or by setting UNIX_TIME_POS) and we introduced a new default parameter UNIX_TIME_FORMAT which controls the formatting of the timestamp.
  3. gmt_io.c now implements -b[i|o]c[var1/...] option to indicate input is netCDF.
  4. gmtmath recognizes new constants TMIN, TMAX, TINC, and N.
  5. grdimage uses -N to not clip image at map boundary.
  6. grdview now uses -Wf to change the facade pen from its default value.
  7. grdmath recognizes new constants XMIN, XMAX, XINC, NX, and similarly YMIN, YMAX, YINC, NY.
  8. mapproject -G+ will compute distances between coordinates in first 4 columns.
  9. ps2raster has new option -D to specify alternative output directory and -V to report progress.
  10. psrose has new option -F to disable the plotting of the scale bar.
  11. psxyz has new option -D to match option set in psxy.
  12. mgd77/mgd77list added -Ga|brec to limit output to a certain record range.
  13. spotter/hotspotter added -S to normalize output to percent of CVA maximum.
  14. spotter/grdspotter is a new program, like hotspotter, but using gridded data as input.

A long list of bugs has been squashed since the last release, the most important are listed below:

gmt_grdio.c
: Fixed 3 bugs in GMT_decode_grd_h_info that caused problems parsing -D option. Explicitly exclude = sign from becoming separator.
gmt_io.c
: Now skips blank lines that has leading whitespace.
gmt_init.c
: c for seconds was not recognized as TIME_UNIT (expected s, which is kept for backwards compatibility). -B processing of labels used an internal string that was too short, which could lead to label truncation. Fixed “Holiday-bug” in GMT_parse_J_option introduced 2007-12-21. GMT_str_tolower could run out of bounds. Probably only affected 32-bit compilers. GMT_is_a_blank_line is now used wherever ascii input is processed.
gmt_map.c
: Fixed bug in radial clipping. The radial clipping would sometimes add arcs using the arc that exceeds 180 degrees. Added new rectangular clip function using Sutherland/Hodgman algorithm in order to fix incorrect results in grdlandmask. Minor bug in 4th term in conformal to geodetic lat. Round-off could mess mapping of west/east to xmin/xmax. Now has a safety valve for checking that this does not occur.
gmt_plot.c
: 3-D basemap axis did not use LABEL_OFFSET.
gmt_proj.c
: Fixed bug in azimuthal equal area projection that had the horizon shifted from where it ought to be. Avoid error in GMT_lamb_sph when lat is 90 degrees. Clip path for general perspective projection was not closed. For -JS: Would set slice to NaN if central meridian was not Greenwich. For -JR: Longitudes beyond 180 were set to 180.
gmt_stat.c
: Bug in GMT_median would sometime give subtle mistakes, most noticeable when only a few values were passed to the function. Traced to the use of size_t variables in expressions that could yield a negative value. Fixed minor issues in GMT_PvQv function.
gmt_support.c
: Made GMT_polygon_is_open tolerant of round-off and if polygon is not open set last to exactly equal first point. GMT_get_annot_label did not properly honor the ddd.xx setting. Now implements annotation for Gnomonic maps. In GMT_contour, would occasionally not check internal crossings for some interior contours.
pslib.c
: Bug in ps_shorten_path lead to SEGV when path resulted in a single point. Fixed error in applying pstext’s -Djdx/dy shift in paragraph mode (-M). Redefine rect symbol to be less prone to round-off. Used internal point_code before it was initialized. This caused PAGE_COLOR not to work (wrote <NUL > rather than C).
gmtmath.c
: Implemented Welford (1962) algorithm in KURT, SKEW and STD operators for more precise one-pass computation of mean and sum of squares.
gmtselect.c
: The -:o option failed to reverse output order.
grd2xyz.c
: Do not abort when -R exceeds grid; simply output common region. For gridline oriented grids: -E returned xll and yll one cell too large. Now writing [xy]llcenter properly.
grdblend.c
: Did not pick up node registration before calculating output grid size.
grdedit.c
: Adjust z_min and z_max when changing add_offset or scale_factor.
grdgradient.c
: With -D and -S the slopes were not set to NaN if data were NaN.
grdinfo.c
: Implemented Welford (1962) algorithm for more precise one-pass computation of mean and sum of squares. zmin==zmax no longer forces -M option.
grdmask.c
: Tiny bug for determining which hemisphere (N/S) unlikely to have had any effect. Needed to allow for some slop when comparing shrink to 0.0 since sometimes the result of acos is 1e-14 or thereabouts.
grdmath.c
: Implemented Welford (1962) algorithm in KURT, SKEW and STD operators for more precise one-pass computation of mean and sum of squares.
grdview.c
: The facade (-N) outline was drawn with contour pen. The -Qc option failed to set the “build image” flag and produced garbage surface tiles. Also, -T[s] produced polygons that were not checked for wrapping at a periodic map boundary. Clarified that -T cannot take -JZ|z.
minmax.c
: Could get confused when longitudes crossed dateline or Greenwich, and OUTPUT_DEGREE_FORMAT could interfere with result.
pscontour.c
: -T option was susceptible to infinite loop if bad record was found.
pshistogram.c
: The -R option was processed separately and did not understand time coordinates. Bug in -F option failed to center bins.
psmask.c
: The -D option used the wrong output file name.
psscale.c
: Inverted vertical scale, when using filled rectangles: Colors remained in the original order. Inverted vertical or horizontal scale, when using rectangles with gradients: Size of rectangles followed original order, not inverted. In reverse mode, -Eb was plotting foreground triangle, -Ef background triangle.
pstext.c
: Parsing of -C complained about % sign.
psxy.c
: If first symbol in list with size was not circle, it got rejected. When sizes of -Sr or -Sj were read from list, they were always assumed to be in inches. Drawing arrows with -SvS and time-coordinates did not work as 2nd time coordinate did not get processed properly.
psxyz.c
: If first symbol in list with size was not circle, it got rejected. When sizes of -Sr or -Sj were read from list, they were always assumed to be in inches.
sample1d.c
: Calendar time knots did not get properly interpreted with -N.
mgg/mgd77togmt.c
: Did not initialize the MGG_SHAREDIR path.
mgd77/mgd77.c
: Wrong header order written if mgd77convert ... -Tt was used.
mgd77/mgd77info.c
: Could get confused when longitudes crossed dateline or Greenwich, and OUTPUT_DEGREE_FORMAT could interfere with result.
mgd77/mgd77sniffer.c
: Numerous fixes and enhancements; see ChangeLog.
x2sys/x2sys.c
: Error in determining which columns had been requested.
x2sys/x2sys_binlist.c
: Could create bad bins because of incorrect reallocation of memory.
x2sys/x2sys_get.c
: The -L option did not honor any -F or -N settings.
x2sys/x2sys_put.c
: Wrong test when replacing older track info lead to data base loss.
x2sys/x2sys_cross.c
: Used wrong data column order and computed speed when there is no time.

1.1.20 Overview of GMT 4.2.1 [October-10, 2007]

Changes in GMT 4.2.1 once again address many structural issues as well as numerous bug fixes. System-wide changes include a revamping of the entire configure/make setup for both regular installations and CVS users, an improvement to how the BCR 2-D interpolations for images and grids are done by adding B-spline and nearest neighbor as optional interpolants, introduction of a new PostScript Level 2 pattern machinery in pslib.c, an updated GSHHS coastline version (which also includes Australia internal state boundaries, fixes to the Yemeni and Lebanese borders, and more river lines), and general improvements and corrections to the documentation, such as placing all man pages in section 1 (except pslib which goes in section 3). Starting with GMT 4.2.1 we will also begin naming the coastline-related archives by the GSHHS prefix and use the actual GSHHS version number (now 1.9).

Individual programs have also seen some new options or enhancements:

  1. gmtselect has enhancement -Lp to limit points beyond a line’s endpoints.
  2. grdfilter has new option -D5 to allow direct filtering of Mercator grids (img).
  3. grdmask has an enhanced -A option; append m or p to design a mask polygon by first following a meridian, then a parallel, or vice versa.
  4. gmtmath has several new operators, such as PLMg (geophysical normalization and suitable for high degree and order), FACT, SKEW, KURT, PQUANT, EULER, PSI, PV, QV, COT, COTD, ACOT, SEC, SECD, ASEC, CSC, CSCD, and ACSC.
  5. grdmath has the same new operator as gmtmath, plus YLMg and CBAZ.
  6. grdproject now considers -R an optional setting.
  7. mapproject has an enhanced -G- option where increments rather than cumulative distances are returned. Also, for UTM projections with -C, the -R option is now optional provided the UTM zone is properly specified.
  8. ps2raster has now a new -P option for forcing portrait orientation.
  9. pshistogram has now a new -C option for using a cpt file to paint the bars.
  10. pstext will now accept the @_, @: and @; escape sequences for underline, font size change, and font color change regardless of mode.
  11. psrose has a new option -L to control the labels.
  12. psxy has an enhanced -A option; append m or p to draw a line by first following a meridian, then a parallel, or vice versa. Can now plot a notched box-and-whisker symbol, and we added +ndx/dy to nudge placement of quoted line labels. Encanced-E.../[-|+]pen where + means apply cpt color (-C) to symbol and bar - means apply to bar only (no fill). Likewise, -W[+|-]pen controls if -C sets outline (-) or both fill and outline (+).
  13. psxyz hass enhanced -W[+|-]pen that controls if -C sets outline (-) or both fill and outline (+).
  14. sample1d now accepts -Fn for no interpolation (returns nearest value).
  15. Two additional color maps have been added: panoply mimics the default colormap in the netCDF viewing program Panoply; cyclic provides a full spectrum of 360 degrees in hue.
  16. originator (spotter supplement) has new option -Q to specify constant r/t for (x,y,z) data only.

Below is a list of previous problems that we have identified and corrected in the current release:

gmt_agc_io.c
: Failed when nx and/or ny was multiple of 40 + 1.
gmt_custom_io.c
: Surfer grid start at lower, not upper left.
gmt_io.c
: Combinations of OUTPUT_DEGREE_FORMAT=ddd:mm:ss.xxxF and -: would add W|E to lat and S|N to lon for formatted output. Blank lines were not recognized under cygwin/SFU. When no delimiters are used for input date format (e.g., yyyymmdd) then yyyy must be 4 characters and we must use %4d. Leading zeros are required if year < 1000.
gmt_init.c
: For quoted lines, the :Lh modifier did not reset label if a segment header had no label specified. Also, label would include the leading n a multi-word label. Now, UTM zones may be A,B,Y,Z or 1-60 with modifiers C-X (except I and O). Parsing of psxy’s -Sf incorrectly scaled a count to inches. Suffices h|+|- in -J were mistaken for units.
gmt_map.c
: KM_PER_DEG was not reset in GMT_set_spherical. This may have caused errors in scaling when ELLIPSOID was not set to Sphere. GMT_distances function did not work with correct pointer. Great circle intersection did not select correct vector sign so points 180 degrees from a line could pass as close in gmtselect. Removed restriction that east and west limits can not be both negative. This fixed the remaining Hexagone problem.
gmt_nc.c
: The attribute actual_range was erroneously stored in grid units in stead of actual units. The difference is only relevant when storing scaled integers. A backward compatibility for grids written with previous versions is built in. Also the GMT version number is added to the global attributes and text attributes are truncated to their proper length.
gmt_plot.c
: Failed to activate ddd.mm.xxx format for maps. Oblique tickmarks sometimes were missing for latitudes.
gmt_proj.c
: -JS inverse did not apply quadrant check.
gmt_support.c
: ddd:mm.xx (2 or more x) failed to format properly. Needed to reverse z_low and z_high values as well as rgb values when reversing color maps.
gmt_vector.c
: Function GMT_fix_up_path: Intermediate longitudes now wrapped based on segment, not on map extent.“greenwich” argument became superfluous and was removed. Argument “step” was found to be in degrees, not in inches as some calling programs assumed.
filter1d.c
: For -Fffile, set filter width to DBL_MAX until filter is read.
grd2cpt.c
: -E flag did not work unless -T was used.
grd2xyz.c
: Did not switch to binary i/o mode when -Z specified binary output (Windows bug only).
grdblend.c
: Now works with Windows DLL by using the GMT i/o functions.
grdcontour.c
: -Avalue would turn off the expected default transparency.
grdcut.c
: Domain check failed for geographic 360-degree grid with -fg.
grdedit.c
: Disallow -T for Surfer grids since they don’t support both kinds of node registration. -N did not take into account if -fg was given.
grdfilter.c
: -Inx+/ny+ was not propagated to the output grid setup.
grdimage.c
: Removed -T option; no more polygon drawing (use grdview). -Smax_radius changed to -S[-]b|c|l|n[/threshold] to take advantage of new and improved projection function GMT_grd_project.
grdlandmask.c
: Failed to set rightmost, empty bin if 360-periodicity in effect; also needed to set repeating right column to left column.
grdmask.c
: For -S..k, did not properly account for latitude effect on dx. SEGV error when GMT_fix_up_path returned f ewer points than originally allocated and the n_alloc variable was not reduced accordingly.
grdmath.c
: When M=0, set Imaginary component of YLM to 0 (was same as real).
grdproject.c
: -Smax_radius changed to -S[-]b|c|l|n[/threshold] to take advantage of new and improved projection function GMT_grd_project.
grdreformat.c
: Could not determine format of output file automatically since file does not yet exist (must append file-type code).
grdsample.c
: -Qvalue changed to -Q[-]b|c|l|n[/threshold] to take advantage of new BCR code.
makecpt.c
: Colormaps with non-equidistant intervals can now be reversed properly.
project.c
: Wrong azimuth for -N and -G generating lines.
pslegend.c
: Usage message did not explain the -L option. Added @ECHO OFF to avoid commands being echoed into the PostScript output under Windows. The color change (C) macro messed up -Xa and -Ya absolute settings.
psbasemap.c
: Check that -L is used with geographic coordinates only.
psimage.c
: The -I option had become always active.
pslib.c
: Now no text is written if font size equals 0.
psscale.c
: Annotations did not work properly if -Q and -B1p were used together.
psxyz.c
: Fixed bug in painting outline of text symbols.
xyz2grd.c
: -E did not process pixel grids properly.

A few bug-fixes applies to the supplements as well:

gshhstograss.c
: Removed use of getopt so even the lamest systems can compile it (incuding Windows).
img2mercgrd.c
: Fixed AND vs OR logic in lat bounds check when -D was set. Used wrong origin when -C was used. Now relative to lon = lat = 0.
DLL
: The meca supplements now work with Windows DLL by using the GMT i/o functions.
utilmeca.c
: Make sure that checks on floating point numbers work well, even in case of small round off errors. Thanks to Peter Lombard.
mgd77manage.c
: -Qvalue changed to -Q[-]b|c|l|n[/threshold] to take advantage of new BCR code. Added E77 status attribute to MGD77+ files.
mgd77sniffer.c
: Same. Adjusted anomaly recalculation code so that cruises with m=1 and b=0 are reported to be same as expected. Repaired 8 memory leaks. Fixed two regression bugs, one in grid comparisons in which not all data were copied into the regression arrays and the other in faa recomputation regression where eot was being applied twice. Added code to check if regression is outside a specified percent (-P). Updated e77 messages and moved along-track grid offset errors to e77 header rather than having its own error class.
gmtdigitize.c
: Must use separate x and y-scales if -Jx is specified. Wrong coordinates used to calculate rms misfit.
originator.c Now lists option -L in both usage and man page.
x2sys.c x2sys_set_system did not initialize structures properly.
x2sys_cross.c Skip duplicate files with a warning. Distance calculations were bogus (see gmt_map.c), and wrong number of arguments passed to readfile function pointer.

Finally, as far as CVS users are concerned, the old "gurumake" system has gone. To compile from CVS, users need to use a GNU compatible make program. A combination of GNUmakefile and makefile files make sure that those components not in the tarballs are created from scratch. Type make in the GMT directory to get a list of targets.

1.1.21 Overview of GMT 4.2.0 [April-1, 2007]

Changes in GMT 4.2.0 address many structural issues as well as many bug fixes. We have consolidated user initialization files in the  /.gmt directory, continued to replace tiling with bitmaps, and have performed a myriad of under-the-hood changes. One imporant and more visible new feature is the fact that grdimage and pscoast now can use the general perspective projection with arbitrary elevation (-JG has been enhanced to handle the extra arguments required – see the new example 26 for details). Also, the coastline files have been updated to use GSHHS version 1.5 which fixes minor inconsistencies in the coastline database. We have also corrected issues that made the Windows DLL explode in 4.1.4. Finally, a few enhancements have been made to these programs:

  1. NGDC’s GRD98 format has been updated to handle both gridline and pixel node registrations.
  2. We have relaxed the restriction on latitude for -JA, -JS for polar aspects; now more than one hemisphere may be displayed. Better warning/error messages.
  3. gmtconvert has an enhanced -E option; append f or l to only get first or last record per segment.
  4. gmtmath -T can now have + appended to indicate number of points instead of increment.
  5. grdcontour has a new option -F to orient dumped contours. Can now append :radius to the -G option in order to specify a minimum spacing (measured in the x/y plane) between contour labels.
  6. grdinfo has an enhanced -I option. With no arguments we return the grid’s -Idx/dy string whereas -I- will return the grid’s -Rw/e/s/n string.
  7. grdmath has new option -M for using map units in gradients and new D2DXY operator. Also added SBAZ for back-azimuths and now allow ELLIPSOID to control if great circles or geodesics should be used (Sphere selects great circles)
  8. psrose has new -D option to center the sector bins (like pshistogram -C).
  9. psxy understand -W- and -W+ in multisegment headers which will turn off outline or reset to default, respectively. Similarly, -G- and -G+ will turn off fill or reset to default (with -M). Also added new option -SB for horizontal bar (-Sb is vertical).
  10. psxyz also has -SB for horizontal bar (-Sb is vertical).
  11. sample1d now allows absolute time in -S option.
  12. imgsrc/img2mercgrd can take -C to let the Mercator x/y use the global origin of img file.
  13. Because of its popularity, ease of use, and importance to many user how otherwise would not know about its existence, ps2raster is moved from the supplementary misc directory to the main set of GMT programs.

Below is a list of previous problems that we have identified and corrected in the current release:

gmt_init.c
: Fixed unit problem with-Jx1:xxxxx. Erroneously added degree symbol to both coordinates in case of -JX..d/.. (single d). Now properly adds only degree symbol on specified axis. Did not change time-system when only TIME_UNIT was specified. Failed to properly parse a single PAR=ARG (one word) argument given to gmtset.
gmt_io.c
: Did not terminate a calendar string after copying it.
gmt_plot.c
: The logic to check for seconds annotations failed if inc <1 arc second. Did not set the contour annotation font before writing labels.
gmt_support.c
: Parsing old-style pens did not set offset to 0 when no texture was given. Fixed IFACT size in the old Brenner FORTRAN FFT – bug undetected since GMT 1! Contouring of grids with NaNs need to check both vertical AND horizontal interior gridcell boundaries for possible crossings. The label machinery for ddd:mm:ss.xx used the wrong parameter to check for fractional seconds annotation (the .xxx part).
gmt_time_systems.h
: J2000 epoch was 1.0 Jan 2000, instead of 1.5 Jan 2000.
filter1d
: The -T option can now parse datestrings for the min/max fields.
gmtmath
: Fixed memory allocation bug for files with more than BUFSIZ records. Now works correctly with multisegment headers. Multisegment headers now written to the output file and not always to stdout. Option -C now works (used to deselect all columns). Fixed LSQFIT (used wrong columns when some were skipped).
grdcontour
: Interior contours were not smoothed unless NaNs were involved. Also the labeling of closed highs/lows were insensitive to pixel versus gridline grids and could get the wrong result. -C need to check for“.cpt” at END of file name. Fixed contour label angle specifications were always ignored.
grdfft
: -D and -I options could have junk in the parameter arrays if given more than once.
grdimage
: -JX with a negative scale/length and -Edpi failed to flip the image.
grdinfo
: Would not take both -L1 and -L2.
grdview
: Plot no mesh when -T is used.
mapproject
: -L option did not allocate enough output memory for extra columns.
pscoast
: Did not list -Z in synopsis/usage.
pscontour
: For 3-D views, -E projected contours (-W) twice and mesh lines (-L) not at all. Fixed contour label angles were always ignored.
pslib.c
: Only issue setdash PostScript commands if texture has changed. ps_clipoff needed to reset memory of last pen width/color/pattern. ps_color_tiles used wrong node registration.
psrose
: Failed to skip pie-slice filling when no fill was selected. -C lead to SEGV as it tried to read from a non-existent file.
psxy
: When used with -S but no -W or -G given, only set default -W if -M not used. Erroneously turned symbol outlines on if just -C was given. Incorrectly suggested that -Svs needs 5 instead of 4 columns. -Sf option was parsed to require 3 instead of 2 coordinates.
psxyz
: -Svs could fail to plot by confusing y-coordinate and y-size. Also need 6 rather than 5 input columns. Bar width has only half of what was requested
splitxyz
: Reported headings in radians instead of degrees.
trend2d
: Failed to pass the new variable with column choices. Also did not accept z as an output choice.

A few bug-fixes applies to the supplements as well:

gshhs.c
: Had && instead of & in bit-arithmetic that reported level.
mgd77manage
: Failed to enforce that a new column abbreviation must be in lower case.
x2sys_cross
: Failed to check for crossovers falling exacly on data nodes.

1.1.22 Overview of GMT 4.1.4 [Nov-1, 2006]

Changes in GMT 4.1.4 are again relatively minor and predominantly bug fixes. One imporant new feature is that GMT can now automatically recognize the format of the grid file given to a program. The use of the “=id” mechanism is now only needed when writing an output file in a grid format other than the netCDF default or when reading using custom scaline and translation is required. We have also added a new user directory pointed to by GMT_USERDIR (default directory is ~/.gmt) where items such as .gmtdefaults4 will be looked for. Additionally, a few enhancements have been made to overcome limitations in the previous versions:

  1. grd2cpt has a new option -T for the creation of tables symmetric about zero.
  2. grdblend will accept negative weights which are taken to mean that the sense of tapering should be reversed.
  3. grdedit has a new option -E to transpose the entire grid.
  4. grdmath has a new option -N to turn off strict domain match checking when multiple grid files are involved.
  5. grdreformat now supports the -f option.
  6. nearneighbor will now optionally accept a min_sectors argument appended to the -N option.
  7. pshistogram’s option -I can now accept a modifier O to output all bin data even if y = 0.
  8. psscale will now invert the color scale if a negative length is provided, and -I will now work with colormaps with non-constant interval and with gaps (-L).
  9. psxy and psxyz have a new option -Sj|J that plots a rotatable rectangle but otherwise behaves similarly to -Se|E.
  10. ps2raster has many improvements; added EPS output; high-quality PDF output. Also removed -dDOINTERPOLATE option which caused inversion of colour map and had no benefits.

Below is a list of previous problems (a few accidently introduced in GMT 4.1.3) that we have identified and corrected in the current release:

gmt_agc.c
: AGC grids use 0 to represent NaNs – this was not implemented yet.
gmt_calclock.c
: Proper rounding of time when converting to dates.
gmt_support.c
: Fixed bug in -I when modifier = was used.
gmt_init.c
: Fixed bug not recognizing PAGE_ORIENTATION as well as a bug that prevented proper writing of PAGE_ORIENTATION in defaults. Added a check so gmtset will not crash if VALUE is not given. Finally, let GMT_HOMEDIR default to C: under Windows if HOME is not set.
gmt_io.c
: GMT_scanf_argtime now returns RELTIME (not ABSTIME) when relative time is found.
gmt_grdio.c
: Set [xy]_units also in GMT_update_grd_info. Fixed time-scaling bug on input (was always seconds). Make units check case-insensitive. Check for toggled lat/lon coordinates.
gmt_nc.c
: Made sure no garbage remains under Cygwin when using strncpy. Check if x- and y-coordinates have constant step sizes; issue warning if not.
gmt_plot.c
: Bugs related to annotations with -JPa and its z modifier fixed. Log gridlines did not work for 3-D view. 3-D axis label would sometimes get misplaced due to round-off. 3-D map scale did not project correctly. Duplicate title could appear if -JX was used and one axis was geographic (d). Needed to add secondary font to list to be encoded.
pslib.c
: Fixed memory management in LZW compression (memory leak). Improved EPS conformance.
filter1d
: Robust option used extreme rather than median to determine the outliers.
gmtconvert
: Did not have -L listed in synopsis.
grdblend
: Now skip grids that are entirely outside the region of interest.
grdcontour
: Crashed if -M and -D were used with no file name specified. The -W[+][c|a] option was susceptible to misinterpreting things like -Wcyan as contour pen with color yan.
grdcut
: Require geographical instead of global in order to shift by 360 degrees.
grdfilter
: Should not wrap over pole unless grid extends all the way to the pole.
grdinfo
: When -C was used there was no linefeed at the end.
grdsample
: -T did not ignore -R (as per manual), resulting in changed cell size. -F did not use gridline node registration as default, rather that of the input grid. When using pixel node registration, number of cells would be one too large. -L worked only in very limited case: going from x=[-180;180] to x=[0;360]. Now supports any periodicity in X and Y (as per manual). -F again forces pixel node registration. Default is same as input. More consistency with manual.
grdtrack
: The -Z option failed to be set for some input configurations.
grdvector
: Added -f option.
grdview
: The -W[c|m] option was susceptible to misinterpreting things like -Wcyan as contour pen with color yan.
grdvolume
: Three bugs squashed: gridcell oriented grids now get proper area and volume, including edges; only one cell per NaN is excluded; when -C and -L are combined, the volume is properly corrected for the baseline height.
pscoast
: -N and -I reset pens to default settings after initially changing them. Did not change output mode to binary (Windows only) if -M and -b were set. Both -Gc and -Sc needed to check that no letter is following the c modifier.
pscontour
: The -D dump option wrote projected instead of original coordinates.
psimage
: -Gcolorname (e.g., -Gblack) will now be interpreted as foreground color, e.g. -Gfblack.
pslegend
: Did not replace octagons with polygon form when pattern was requested. Did not consider if absolute coordinates were given in -X and -Y. Passed the wrong character code when M was chosen with a plain scale modifier.
psscale
: A vertical bar with a label placed along it was mis-justified.
pstext
: Default for -G is now BASEMAP_FRAME_RGB as for other map annotations. The box option -W[fill][o|O|c|C][pen]] is now -W[fill,][o|O|c|C][pen]], i.e., we now use a comma to separate the fill and pen (done since fill may be a name containing o|c); parsing is backwards compatible.
psxyz
: -C for symbols did not pick up color fill.
trend2d
: Processing of -F happened after checking.
xyz2grd
: Had -Az as default rather than no -A. Fixed bad header parsing when -E was selected.

A few bug-fixes applies to the supplements as well:

grdraster
: Only do 360-degree wrapping if working on a geographic grid.
mgd77list
: Did not process time when -Am2|4 was set and time was not requested as output. Also, did not process time when -Am2|4 was set and time was not requested as output.
x2sys.c
: Did not look in current dir for *.def files.

1.1.23 Overview of GMT 4.1.3 [June-1, 2006]

Changes in GMT 4.1.3 are relatively minor and predominantly bug fixes. However, a few enhancements have been made to overcome limitations in the previous versions:

  1. Added the Hughes 1980 ellipsoid for projection support for DMSP SSM/I grid products.
  2. grdfft has an extended -F option to allow for either Gaussian- or cosine-tapered filtering.
  3. psscale now has a -Q option so that logarithmic color scales and annotations can be handled properly.
  4. makecpt and grd2cpt have a new -M option to allow the background, foreground, and NaN-colors to be assigned using the GMT defaults instead of the settings in the master CPT file.
  5. mgd77list in the mgd77 supplement has new option -Q to specify limits on speed and azimuths for output records.

Below is a list of previous problems (some accidentily introduced in GMT 4.1.2) that we have identified and corrected in the current release:

gmt_grdio.c
: Bug in GMT_grd_shift for gridline-registered grids; this function is used in grdedit to rotate grids of 360-degree longitudinal extent. Also added better testing for subsets of global (0-360) grids.
gmt_init.c
: GMT_PS_init was called after –PAR=val had been decoded, resetting the PostScript-related parameters to their default settings.
gmt_support.c
: GMT_set_xy_domain padded region for pixel instead of gridline node registration, which could cause SEGV in xyz2grd if (x,y) was less than half the grid-spacing outside region.
blockmean
: The -C option got reversed in 4.1.2 - now fixed.
blockmedian
: The -C option got reversed in 4.1.2 - now fixed.
grdcontour
: The -C option with a non-cpt file failed to read due to lack of proper if-test.
grdedit
: The -S option was backwards and tested w-e=360; should be e-w=360.
grdimage
: Fixed bug introduced by GMT_get_inc in 4.1.2. Internal projected grid never took node_offset from input grid.
grdmask
: Polygons with zig-zag shape would sometimes cause a node exactly on a polygon vertex to be considered inside. Radius was reset to 0 after -Sradius was assigned.
grdvector
: The -A option was not properly initiated.
psbasemap
: The -L option did not properly parse the optional :label:<just> part.
pslegend
: If the M (for map scale) was used, the -R and -J options would be reset. Also prevented the undoing of -X and -Y at the end of the program.

1.1.24 Overview of GMT 4.1.2 [May-15, 2006]

On the surface, changes in GMT 4.1.2 are relatively minor. Most of the work has involved realignment of code and parsing of arguments to simplify the upcoming port to GMT 5; a brief listing of more visible changes include

  1. Coastline files have been updated to use GSHHS version 1.4 which fixes minor inconsistencies in the coastline database.
  2. All coastline files are now stored in a new subdirectory coast under the share directory, and the tar archives for coastlines now have their own version numbers as they do not change as frequently as the source code. Current coastline version number is 4.1.
  3. The archives have been reorganized so that GMT_share.* contains all files needed at runtime whereas the standard coastline files are in the new GMT_coast.* archive. The GMT_progs.* archive has been renamed GMT_src.*.
  4. CPT files can now have z-values that are date-time strings.
  5. Optionally append z to the -Jp projection to annotate depths (i.e., “north-y”) rather than radius.
  6. Two new tools added to the misc supplement for digitizing lines (gmtdigitize) and to stitch digitized lines into continuous lines or polygons (gmtstitch).
  7. Extended -M option to take optional modifiers i or o for input or output.
  8. Added support for custom grd format AGC from Atlantic Geoscience Center, assigned the code af [21].

A few programs or options have received minor updates and new features, such as

blockmean
: Added -E for reporting standard deviation, min, and max values per block.
blockmedian
: Added -E for reporting L1 scale, min, and max values per block. Also added -T to specify a particular quartile [Default q = 0.5 = median].
blockmode
: Added -E for reporting LMS scale, min, and max values per block.
configure
: Added explicit options to bypass the installation of supplements that require Matlab (–disable-mex) and X11 (–disable-xgrid).
gmtconvert
: Added -D option to write segments to individual output files.
gmtdefaults
: Support for new default PS_VERBOSE which controls the writing of comments to PostScript files. COLOR_MODEL can now accept a prefix “+” which forces color interpolation in the selected system (RGB or HSV only). Default remains RGB. PS_COLOR has been extended to accept HSV as well (only applies to polygon, symbol, pen, and text colors, not images.). New parameter POLAR_CAP which controls the number of gridlines that converge on the poles for azimuthal and some other projections. Added new default HISTORY [TRUE] which controls whether or not we maintain a common command option history via .gmtcommands4 files.
gmtmath
: Added option -M to indicate the program can now handle multisegment files. Added CPOISS for cumulative Poisson distribution.
grdmath
: Added CPOISS for cumulative Poisson distribution.
minmax
: -D made obsolete by improved range checking for longitudes (but available for backwards compatibility).
psscale
: Enhanced -I option for asymmetrical intensity ranges from low to high.
psxy
: Added -SW for wedges defined by azimuths rather than directions. Polygons of large longitudinal extent now clip correctly.
splitxyz
: New option -Q to specify the output columns and their order.

Below is a list of previous problems that we have identified and corrected in the current release:

gmt_plot.c
: The 3-D perspective plotting of text was not scaled correctly.
gmt_support.c
: Parsing of -L option used in psbasemap and pscoast failed to get correct unit when ddd:mm:ss syntax was used for the position. Corner boundary conditions for grids (needed by grdtrack, grdsample, grdview, and grdgradient) had the wrong sign.
gmt2rgb
: Did not check name template properly, and did not initialize region.
gmtselect
: Option -F insisted on using spherical testing for Cartesian x,y data.
grd2xyz
: The -E option had the y-direction reversed.
grdfilter
: Needed the -f option to process -Rddd:mm syntax.
grdimage
: Would hang in stdin if -C not given when one grid is plotted.
grdmask
: Did not explicitly close polygons before using them. Test for polar caps applied to the opposite pole.
grdmath
: Command INSIDE for Cartesian data had bug (passed y where x was expected).
grdsample
: Failed when -I was specified.
grdview
: Bug in plotting north facade (-N). Also tried to free unallocated memory if -G was used.
project
: Cartesian projections gave incorrect results for p,w,r,s. Removed 0–360 restriction on azimuth. Option -G was susceptible to round-off and thus sometimes reissued the final point.
psxy
: -SV and -SE for -JX did not convert azimuths to directions. The -Sq option would get confused when distances between successive labels were smaller than the line’s point spacing.
mgd77/mgd77manage
: Did not properly close the file after ingesting E77 information.
pslib.c
: ps_load_raster did not use open mode rb and hence failed under Windows.
xyz2grd
: The -E option had the y-direction reversed.

A few bug-fixes applies to the supplements as well:

x2sys_get
: -N did not work properly (now fixed and tested).

1.1.25 Overview of GMT 4.1.1 [Mar-1, 2006]

Changes in GMT 4.1.1 are mostly minor; a brief listing include

  1. gmt_nc.c: Introduced handling of 4-D COARDS compliant grids (See Chapter 4 for details).
  2. mgd77/mngd77sniffer: New tool for along-track quality control checking of MGD77 files.
  3. spotter/grdrotater: New tool that rotates grids given a specified finite rotation.
  4. Jonathan Shewchuk’s triangulation routines are now stored with the rest of the source in the GMT_progs.tar|zip archives. (However, because his copyright is not GPL, installing it is still an option).

A few programs or options have received minor updates and new features, such as

grdedit
: Added option -T to toggle between gridline and pixel node registrations (header only).
grdgradient
: Implemented variation on Lambertian illumination.
grdmask
: Now takes -Sradius[c|m|k|K] as is done in nearneighbor.
gmtmath
: If file is STDIN we read data from stdin and put the contents on the stack. Also added -F to select which columns to use for output [all].
grdtrack
: Can now sample Sandwell/Smith IMG grids directly.
psmask
: -Now takes -Sradius[c|m|k|K] as is done in nearneighbor. Can now plot tiles regardless of projection and use patterns.
pstext
: -D[...]vpen can now be used with or without -M.
psxyz
: -SO|U imitate -So|u but without the 3-D color shading.
mgd77.c
: Added mechanism to search directories for files (mgd77 supplement).
mgd77list
: Activated -X option and associated machinery for applying data corrections (mgd77 supplement).

Inevitably, when new features are added, new bugs come along with them. Below is a list of problems that we have identified and corrected in the current release:.

configure.in
: Extracting VERSION from gmt_version.h, not gmt.h.
gmt_init.c
: BASEMAP_FRAME_RGB overrode any changes to grid pens etc. Now only does so if prefixed by ’+’.
gmt_calclock.c
: Did not allow -B0 for time-axis.
gmt_map.c
: -JX...d now plots with WESN or degrees:minutes as per PLOT_DEGREE_FORMAT. Map clip paths for -JElon/90 were no good. Under certain circumstances, GMT_non_zero_winding might be passed a polygon that was not closed, resulting in an error. -JQ would give garbage if central lon was way outside -R.
gmt_plot.c
: -JX...d now plots with WESN or degrees:minutes as per PLOT_DEGREE_FORMAT.
gmt_grdio.c
: Changed logic to avoid false “scale==0” warning on Windows. GMT_open_grd (used in grdblend) reset scale to NaN. Initialize header information at start of GMT_read_grd_info.
gmt_support.c
: Initialize [xyz]_unit with more appropriate values. Got wrong conversion for dx in meters to degrees.
gmt_grd.h
: Improved definition of GMT_x_to_i macro should reduce bugs
pslib.c
: ps_polygon: if outline == -9 just fill and no clip. Fixed two bugs concerning the /MaskColor operator.
ISO-8859-9.ps
: Added /dotlessi per Onur Tan.
blockm*
: Now correctly deals with periodic longitude data.
grdcontour
: Fixed several issues at grid limits and inappropriate scaling of grid dimensions..
grdfilter
: Used -1 as index flag instead of INT_MIN.
grdimage
: Fixed several issues at grid limits and inappropriate scaling of grid dimensions.
grdmask
: Only let you change the value for outside nodes.
grdmath.man
: Did not list -f option. Operators LT, LE, EQ, GE, GT returned TRUE if NaNs were involved Now NaN is returned if any of the two operands is a NaN.
grdreformat
: Update grd.command before writing grid
grdvector
: Did not place vectors correctly for pixel-pregistered grids.
grdview
: Skipped nodes outside boundary but they might be needed to draw a tile.
pscoast
: With -JE and -Gr/g/b, the painting of the antipodal bin would incorrectly turn off clipping, messing up the rest of the plot. Now pass -9 to GMT_fill which means just fill and no end of clipping.
xyz2grd
: For geographic grids with 360 range and gridline node registration, the west and east bin did not get replicated properly. Now considers data inside the first and last tiles which might stick outside w/e/s/n.

A few bug-fixes applies to the supplements as well:

x2sys_cross
: Several problems fixed.

1.1.26 Overview of GMT 4.1 [Jan-7, 2006]

Most changes in GMT 4.1 are improvements “under the hood”. The most significant of these are

  1. Addition of ability to both read and write netCDF files that are COARDS compliant. This means that GMT, for the first time, is able to read netCDF files created by applications other than itself, and that other applications capable of reading COARDS-compliant netCDF grids can directly import data from GMT. We have added the new parameter GRID_FORMAT to the GMT defaults with “nf” as default. Users who, against our recommendation, prefer to maintain the old non-COARDS compliant format as their default grid format can instead select “cf”. Support for extracting 2-D slices from 3-D netCDF grids has also been added.
  2. An overhaul of how the pslib library encodes PostScript images, resulting in vastly smaller files when certain conditions are met, and general shrinking overall by enabling RLE or LZW compression. We have also added hooks for setting three new PostScript parameters via gmtdefaults settings: PS_LINE_CAP, PS_LINE_JOIN, and PS_MITER_LIMIT. See gmtdefaults for details.
  3. Improved alignment of strings ending in “1” in the PostScript output.
  4. Adjustments to how native GMT grid headers are read and written in order to be fully 64-bit safe. GMT now runs in full 64-bit mode on platforms that supports it (e.g., Mac OS X G5).
  5. Making GMT tread-safe by replacing strtok with our own GMT_strtok function.
  6. Implemented full inverse Winkel map projection based on a new algorithm by Ipbuker, 2002, Cartography & Geographical Information Science, 29, 37-42.
  7. Extended the options that is used to specify grid spacing (usually -Ixinc/yinc) to allow for specifying nx/ny instead (by appending +). Also, append ! to adjust the range so it fits exactly the given increment [by default the range is kept fixed and sloppy increments are adjusted accordingly]. Append e|k|i|n for increments in meter, km, miles or nautical miles, respectively. These increments are converted to degrees longitude (at the middle latitude) and degrees latitude.
  8. The polar r,θ projection -Jp now takes an optional suffix r that reverses the radial coordinates (useful when r is elevation as used by sky plots.)
  9. The misc supplement has two new items: ps2raster uses ghostscript to fascilitate the rasterization of PostScript files, while nc2xy allows extraction of data columns from COARDS-compliant netCDF files.
  10. The mgd77 supplement has two new items: mgd77convert translates between different MGD77 formats (including a new netCDF-based format), while mgd77manage assists in the management of trackline data sets.
  11. We now have improved PDF layout and navigation (thanks to Misha Tchernychev).
  12. The HTML versions of all manual pages are now generated with groff, and has active links for GMT Default parameters as they are references in the documentation.

Many programs or options have received minor updates and new features, such as

-b
: Ability to specify byte-swapping for native binary input and output tables by using upper case S|D. This is useful if you have binary tables created on a little-endian machine (e.g., Linux PC) and need to read them on a big-endian machine (e.g., most RISC-chip machines from Sun, HP, Apple).
filter1d
: Allow NaNs in all but the “independent data” column.
grdcontour
: Label option +ap[u|d] for always having labels be readable up or down hills.
gmtconvert
: New -N option suppresses output records when all fields are NaNs.
gmtmath
: Added TN function for evaluating Chebyshev polynomials; new constant Tn was added to easily select normalized T (gives coordinates from -1 to + 1 suitable for evaluating Legendre and Chebyshev polynomials). Finally, we added CORRCOEFF for calculation of correlation coefficients, and -I to reverse the output by printing the last row first.
grd2cpt
: New option -D sets the back- and foreground colors to the colors at the limits of the cpt file.
grd2xyz
: Added -E for ESRI interchange ASCII grid dump.
grdfilter
: Geographic boundary conditions are now in effect if -D4 is selected.
grdgradient
: Added option -E for Lambertian or Peuckeer illumination.
grdmath
: Allow -bi to be used with input files for commands PDIST, LDIST, and INSIDE. When spherical calculations are selected we now use the ELLIPSOID setting to determine if distance calculations should be along geodesics or great circles. Also added TN function for evaluating Chebyshev polynomials; new constants Xn and Yn was added to easily select normalized X and Y. Finally, we added CORRCOEFF for calculation of correlation coefficients.
grdraster
: Optionally select a data set by giving a text pattern instead of data ID number. This makes it easier to specify a certain data set (i.e., “ETOPO2”) than having to remember its arbitrary numerical ID. Also, native grids with GMT headers can also be placed in the database by appending Hnbytes to the corresponding grdraster.info entry, where nbytes is the size of the header that should be skipped (use 892 for GMT headers).
makecpt
: New option -D sets the back- and foreground colors to the colors at the limits of the cpt file.
mapproject
: -L now outputs both the minimum distance and the coordinates of the nearest point on the line.
pscoast
: Added -Z for 3-D map z-level (as in psbasemap and others).
pshistogram
: New option -Tcol lets user select any column to be used, starting with 0 (first). The old -2 option is retired (but remains accessible for backwards compatibility).
psimage
: Now support inclusion of EPS images.
pslegend
: Added layout option B for inserting color bars via psscale.
psscale
: Now supports an optional ;label at end of each line in cpt files. If present this label will replace the default annotations when option -L is used.
psxyz
: Added -Q to disable sorting of points based on distance.
sample1d
: Allow NaNs in all but the “independent data” column.
xyz2grd
: Added -E for ESRI interchange ASCII grid digest.

Inevitably, when new features are added, new bugs come along with them. Below is a list of problems that we have identified and corrected in the current release:

install_gmt
: No longer test netcdf installation since that can fail even when install was successful [e.g., under Mac OS X Tiger].
gmt.h
: GMT_swab4 used unsigned long instead of unsigned int which could cause 64-bit problems.
gmt_time_system.h
: Fixed MJD offsets by subtracting 10 days.
gmt_calclock.c
: time to hr,min,sec was vulnerable to round-off when optimized. Also, hh:mm data (without trailing :ss) would loose the minutes (hh:mm:ss was OK).
gmt_grdio.c
: Bug in scale/offset for grdblend’s row-by-row i/o.
gmt_init.c
: Would eat number with leading plus sign without checking if it actually was a +gmtdefaults file instruction; thus gmtmath could not see numbers such as +13.5. Command line argument –BASEMAP_FRAME_RGB=color was not passed through to tick-, grid- and annotation-properties. GMT_end now frees memory used for hashing. Did not use custom ellipsoid to set DEG2M parameter so we got large errors for planets with significantly different radii.
gmt_io.c
: Bug in reading yyyy[/]jjj data fixed. GMT_lines_init had trouble if 2000 segments had no data at all. It also allocated 2000 points for each segment but never deallocated the unused portions, thus running up memory fast. GMT_write_segmentheader wrote nothing if input was binary and output is ASCII. Fixed a few memory leaks.
gmt_map.c
: Azimuth to angle calculation for linear projections now properly handle different scales in x and y. The calculation was also vulnerable to bad wrap-around, giving strange directions for vectors in psxy. Geodesic distance calculation could get wrong quadrant.
gmt_plot.c
: 360 polar basemaps could lack outline. Direction for map roses were inaccurate. Circle and θ-r boundaries did not allocate enough memory for arrays. Would plot both -180 and +180 annotations for periodic maps.
gmt_shore.c
: Must explicitly close polygons since inside/outside test in other programs expects it.
gmt_support.c
: Trouble extracting subregions of grid with east = 0. Cartesian LDIST failed when mininum distance was requested (only done via grdmath). Color names got truncated to 16 characters. Improved workings of GMT_sample_cpt in support of makecpt. Fixed more memory leaks. Bad LF/CR removal for coastline.conf dir.
filter1d
: -Ff with even number of coefficients sometimes skip a coefficient.
gmtconvert
: Missed first multisegment output header if input file was ASCII.
gmtmath
: No longer have to say -Ca if there is only one input column. Did not understand dateTclock as command line data.
gmtselect
: If -M is on and a portion of a segment is skipped, we must reissue the multisegment header when segment resumes. Now handles both Cartesian and spherical polygons correctly.
grd2xyz
: Sloppy -R resulted in bad x,y values and sometimes allocation error.
grdfilter
: Convolution filters now use correct area normalization.
grdgradient
: If -M is used with grids that include poles, ignore the poles when normalizing the slopes.
grdimage
: Cannot use -R to extract subset when -J is oblique. Reverse log-axes did not work.
grdmask
: Now handles both Cartesian and spherical correctly.
grdmath
: Wrong sign in D2DY2, and bogus value at y = ymin. Now handles both Cartesian and spherical polygons correctly. Constants given on command line can now be absolute time, geographic coordinates, or regular floating-point numbers.
grdtrack
: Would fail to skip first two columns for ASCII input if dd:mm:ss format was used.
grdview
: Cannot use -R to extract subset when -J is oblique.
grdvolume
: -Clow/high/delta did not check for low < high, etc.
pscoast
: Recursive painting could get tricked when boundaries were curved.
pslegend
: Did not pass +gmtdefaults and –PAR=val onto system calls.
psscale
: Vertical annotations w/custom D_FORMAT were not aligned. Now uses more optimal means to display the color bar, leading to smaller PostScript files. -E did not flip sides when a negative width was used.
psxy
: -Sp is now a true point, but can also take an optional size. Pentagon symbol had wrong normalization scale. If a fixed symbol size was given in -S, with the symbol type supplied from file, we would not scale symbols correctly if upper case symbols were given.
psxyz
: Wrong index used in assigning color from cpt and in updating vector lengths. If a fixed symbol size was given in -S, with the symbol type supplied from file, we would not scale symbols correctly if upper case symbols were given
spectrum1d
: Bugs in error expressions for admittance, gain, and phase have been corrected.
x2sys & mgd77 supplements
: Made DOS-format (CR/LF) tolerant. Both supplements are now undergoing rapid development.

1.1.27 Overview of GMT 4.0 [Oct-10, 2004]

GMT 4 represents a major overhaul of the package, hence the major version number increment. There are four categories of changes that have been implemented:

Time-series support.
GMT can now read and write time-series data where the time coordinates are of the form dateTclock2. The formats used for date and clock are under the user’s control. Both Gregorian and ISO calendars are supported. Frame annotation for time-series are now supported via the -B option; there are many new modifiers reflecting the vast number of ways one may want to annotate time axes, including support for primary and secondary annotation levels and the day- and month-names in numerous languages (send us the information we need if your language is not supported). The capability to handle time (in -R, -J, -B, i/o, and plotting) required considerable changes “under the hood”, including the introduction of numerous new gmtdefaults parameters to make the time series support as “generic” as we need it to be.
New Tools.
Three new tools have been added:
  1. gmt2rgb: Makes red, green, and blue component grid files from an image (to be used with new options for false color imaging or image draping by grdimage or grdview).
  2. grdblend: Blends several partially over-lapping grid files into one combined grid. Output grid is written one row at the time so truly enormous grids can be created.
  3. pslegend: Designs and plots elaborate legends on maps.
New Program Options.
Many programs have received additional options or features that enhances their usefulness:
General enhancements.
These affect most of the programs:

Chapter 2
Introduction

Most scientists are familiar with the sequence: raw data processing final illustration. In order to finalize papers for submission to scientific journals, prepare proposals, and create overheads and slides for various presentations, many scientists spend large amounts of time and money to create camera-ready figures. This process can be tedious and is often done manually, since available commercial or in-house software usually can do only part of the job. To expedite this process we introduce the Generic Mapping Tools (GMT for short), which is a free4, software package that can be used to manipulate columns of tabular data, time-series, and gridded data sets, and display these data in a variety of forms ranging from simple x-y plots to maps and color, perspective, and shaded-relief illustrations. GMT uses the PostScript page description language [Adobe Systems Inc., 1990]. With PostScript, multiple plot files can easily be superimposed to create arbitrarily complex images in gray tones or 24-bit true color. Line drawings, bitmapped images, and text can be easily combined in one illustration. PostScript plot files are device-independent: The same file can be printed at 300 dots per inch (dpi) on an ordinary laserwriter or at 2470 dpi on a phototypesetter when ultimate quality is needed. GMT software is written as a set of UNIX tools5 and is totally self-contained and fully documented. The system is offered free of charge and is distributed over the computer network (Internet) [Wessel and Smith, 1991; 1995a,b; 1998].

The original version 1.0 of GMT was released in the summer of 1988 when the authors were graduate students at Lamont-Doherty Earth Observatory of Columbia University. During our tenure as graduate students, L-DEO changed its computing environment to a distributed network of UNIX workstations, and we wrote GMT to run in this environment. It became a success at L-DEO, and soon spread to numerous other institutions in the US, Canada, Europe, and Japan. The current version benefits from the many suggestions contributed by users of the earlier versions, and now includes more than 50 tools, more than 30 projections, and many other new, more flexible features. GMT provides scientists with a variety of tools for data manipulation and display, including routines to sample, filter, compute spectral estimates, and determine trends in time series, grid or triangulate arbitrarily spaced data, perform mathematical operations (including filtering) on 2-D data sets both in the space and frequency domain, sample surfaces along arbitrary tracks or onto a new grid, calculate volumes, and find trend surfaces. The plotting programs will let the user make linear, log10, and xayb diagrams, polar and rectangular histograms, maps with filled continents and coastlines choosing from many common map projections, contour plots, mesh plots, monochrome or color images, and artificially illuminated shaded-relief and 3-D perspective illustrations.

GMT is written in the highly portable ANSI C programming language [Kernighan and Ritchie, 1988], is fully POSIX compliant [Lewine, 1991], has no Year 2000 problems, and may be used with any hardware running some flavor of UNIX, possibly with minor modifications. In writing GMT, we have followed the modular design philosophy of UNIX: The raw data processing final illustration flow is broken down to a series of elementary steps; each step is accomplished by a separate GMT or UNIX tool. This modular approach brings several benefits: (1) only a few programs are needed, (2) each program is small and easy to update and maintain, (3) each step is independent of the previous step and the data type and can therefore be used in a variety of applications, and (4) the programs can be chained together in shell scripts or with pipes, thereby creating a process tailored to do a user-specific task. The decoupling of the data retrieval step from the subsequent massage and plotting is particularly important, since each institution will typically have its own data base formats. To use GMT with custom data bases, one has only to write a data extraction tool which will put out data in a form readable by GMT (discussed below). After writing the extractor, all other GMT modules will work as they are.

GMT makes full use of the PostScript page description language, and can produce color illustrations if a color PostScript device is available. One does not necessarily have to have access to a top-of-the-line color printer to take advantage of the color capabilities offered by GMT: Several companies offer imaging services where the customer provides a PostScript plot file and gets color slides or hardcopies in return. Furthermore, general-purpose PostScript raster image processors (RIPs) are now becoming available, letting the user create raster images from PostScript and plot these bitmaps on raster devices like computer screens, dot-matrix printers, large format raster plotters, and film writers6. Because the publication costs of color illustrations are high, GMT offers 90 common bit and hachure patterns, including many geologic map symbol types, as well as complete graytone shading operations. Additional bit and hachure patterns may also be designed by the user. With these tools, it is possible to generate publication-ready monochrome originals on a common laserwriter.

GMT is thoroughly documented and comes with a technical reference and cookbook which explains the purpose of the package and its many features, and provides numerous examples to help new users quickly become familiar with the operation and philosophy of the system. The cookbook contains the shell scripts that were used for each example; PostScript files of each illustration are also provided. All programs have individual manual pages which can be installed as part of the on-line documentation under the UNIX man utility or as web pages. In addition, the programs offer friendly help messages which make them essentially self-teaching – if a user enters invalid or ambiguous command arguments, the program will print a warning to the screen with a synopsis of the valid arguments. All the documentation is available for web browsing and may be installed at the user’s site.

The processing and display routines within GMT are completely general and will handle any (x,y) or (x,y,z) data as input. For many purposes the (x,y) coordinates will be (longitude, latitude) but in most cases they could equally well be any other variables (e.g., wavelength, power spectral density). Since the GMT plot tools will map these (x,y) coordinates to positions on a plot or map using a variety of transformations (linear, log-log, and several map projections), they can be used with any data that are given by two or three coordinates. In order to simplify and standardize input and output, GMT uses two file formats only. Arbitrary sequences of (x,y) or (x,y,z) data are read from multi-column ASCII tables, i.e., each file consists of several records, in which each coordinate is confined to a separate column7. This format is straightforward and allows the user to perform almost any simple (or complicated) reformatting or processing task using standard UNIX utilities such as cut, paste, grep, sed and awk. Two-dimensional data that have been sampled on an equidistant grid are read and written by GMT in a binary grid file using the functions provided with the netCDF library (a free, public-domain software library available separately from UCAR, the University Corporation of Atmospheric Research [Treinish and Gough, 1987]). This XDR (External Data Representation) based format is architecture independent, which allows the user to transfer the binary data files from one computer system to another8. GMT contains programs that will read ASCII (x,y,z) files and produce grid files. One such program, surface, includes new modifications to the gridding algorithm developed by Smith and Wessel [1990] using continuous splines in tension.

Most of the programs will produce some form of output, which falls into four categories. Several of the programs may produce more than one of these types of output:

  1. 1-D ASCII Tables — For example, a (x,y) series may be filtered and the filtered values output. ASCII output is written to the standard output stream.
  2. 2-D binary (netCDF or user-defined) grid files – Programs that grid ASCII (x,y,z) data or operate on existing grid files produce this type of output.
  3. PostScript – The plotting programs all use the PostScript page description language to define plots. These commands are stored as ASCII text and can be edited should you want to customize the plot beyond the options available in the programs themselves.
  4. Reports – Several GMT programs read input files and report statistics and other information. Nearly all programs have an optional “verbose” operation, which reports on the progress of computation. All programs feature usage messages, which prompt the user if incorrect commands have been given. Such text is written to the standard error stream and can therefore be separated from ASCII table output.

GMT is available over the Internet at no charge. To obtain a copy, visit the GMT home page gmt.soest.hawaii.edu, and select DOWNLOAD. This page contains all the information you need to obtain GMT for your platform. We also maintain two electronic mailing lists you may subscribe to in order to stay informed about bug fixes and upgrades (See Chapter 7).

For those without net-access that need to obtain GMT: Geoware (http://www.geoware-online.com) makes and distributes CD-R and DVD-R media with the GMT package, compatible supplements, and several Gb of useful Earth and ocean science data sets. For more information send e-mail to geoware@geoware-online.com.

GMT has served a multitude of scientists very well, and their responses have prompted us to develop these programs even further. It is our hope that the new version will satisfy these users and attract new users as well. We present this system to the community in order to promote sharing of research software among investigators in the US and abroad.

References

  1. Kernighan, B. W., and D. M. Ritchie, The C programming language, 2nd edition, p. 272, Prentice-Hall, Englewood Cliffs, New Jersey, 1988.
  2. Adobe Systems Inc., PostScript Language Reference Manual, 2nd edition, p. 764, Addison-Wesley, Reading, Massachusetts, 1990.
  3. Lewine, D., POSIX programmer’s guide, 1st edition, p. 607, O’Reilly & Associates, Sebastopol, California, 1991.
  4. Treinish, L. A., and M. L. Gough, A software package for the data-independent management of multidimensional data, EOS trans. AGU, 68, 633–635, 1987.
  5. Smith, W. H. F., and P. Wessel, Gridding with continuous curvature splines in tension, Geophysics, 55, 293–305, 1990.
  6. Wessel, P., and W. H. F. Smith, New, improved version of Generic Mapping Tools released, EOS trans. AGU, 79, 579, 1998.
  7. Wessel, P., and W. H. F. Smith, New version of the Generic Mapping Tools released, EOS trans. AGU, 76, 329, 1995a.
  8. Wessel, P., and W. H. F. Smith, New version of the Generic Mapping Tools released, EOS electronic supplement, http://www.agu.org/eos_elec/95154e.html, 1995b.
  9. Wessel, P., and W. H. F. Smith, Free software helps map and display data, EOS trans. AGU, 72, 441 & 445–446, 1991.

Chapter 3
GMT overview and quick reference

3.1 GMT summary

The following is a summary of all the programs supplied with GMT and a very short description of their purpose. For more details, see the individual UNIX manual pages or the online web documentation. For a listing sorted by program purpose, see Section 3.2.

blockmean L2 (x,y,z) table data filter/decimator

blockmedian L1 (x,y,z) table data filter/decimator

blockmode Mode estimate (x,y,z) table data filter/decimator

filter1d Filter 1-D table data sets (time series)

fitcircle Finds the best-fitting great or small circle for a set of points

gmt2rgb Convert Sun raster or grid file to red, green, blue component grids

gmtconvert Convert data tables from one format to another

gmtdefaults List the current default settings

gmtmath Mathematical operations on table data

gmtselect Select subsets of table data based on multiple spatial criteria

gmtset Change selected parameters in current .gmtdefaults4 file

grd2cpt Make color palette table from a grid files

grd2xyz Conversion from 2-D grid file to table data

grdblend Blend several partially over-lapping grid files onto one grid

grdclip Limit the z-range in gridded data sets

grdcontour Contouring of 2-D gridded data sets

grdcut Cut a sub-region from a grid file

grdedit Modify header information in a 2-D grid file

grdfft Perform operations on grid files in the frequency domain

grdfilter Filter 2-D gridded data sets in the space domain

grdgradient Compute directional gradient from grid files

grdhisteq Histogram equalization for grid files

grdimage Produce images from 2-D gridded data sets

grdinfo Get information about grid files

grdlandmask Create masking grid files from shoreline data base

grdmask Reset grid nodes in/outside a clip path to constants

grdmath Mathematical operations on grid files

grdpaste Paste together grid files along a common edge

grdproject Project gridded data sets onto a new coordinate system

grdreformat Converts grid files into other grid formats

grdsample Resample a 2-D gridded data set onto a new grid

grdtrack Sampling of 2-D gridded data set along 1-D track

grdtrend Fits polynomial trends to grid files

grdvector Plotting of 2-D gridded vector fields

grdview 3-D perspective imaging of 2-D gridded data sets

grdvolume Calculate volumes under a surface within specified contour

greenspline Interpolation using Green’s functions for splines in 1–3 dimensions

makecpt Make color palette tables

mapproject Transformation of coordinate systems for table data

minmax Report extreme values in table data files

nearneighbor Nearest-neighbor gridding scheme

project Project table data onto lines or great circles

ps2raster Crop and convert PostScript files to raster images, EPS, and PDF

psbasemap Create a basemap plot

psclip Use polygon files to define clipping paths

pscoast Plot (and fill) coastlines, borders, and rivers on maps

pscontour Contour or image raw table data by triangulation

pshistogram Plot a histogram

psimage Plot Sun raster files on a map

pslegend Plot a legend on a map

psmask Create overlay to mask out regions on maps

psrose Plot sector or rose diagrams

psscale Plot gray scale or color scale on maps

pstext Plot text strings on maps

pswiggle Draw table data time-series along track on maps

psxy Plot symbols, polygons, and lines on maps

psxyz Plot symbols, polygons, and lines in 3-D

sample1d Resampling of 1-D table data sets

spectrum1d Compute various spectral estimates from time-series

splitxyz Split xyz files into several segments

surface A continuous curvature gridding algorithm

trend1d Fits polynomial or Fourier trends to y = f(x) series

trend2d Fits polynomial trends to z = f(x,y) series

triangulate Perform optimal Delauney triangulation and gridding

xyz2grd Convert an equidistant table xyz file to a 2-D grid file

3.2 GMT quick reference

Instead of an alphabetical listing, this section contains a summary sorted by program purpose. Also included is a quick summary of the standard command line options and a breakdown of the -J option for each of the over 30 projections available in GMT.

FILTERING OF 1-D AND 2-D DATA


blockmean L 2 estimate (x,y,z) data filters/decimators


blockmedianL1 estimate (x,y,z) data filters/decimators


blockmode Mode estimate (x,y,z) data filters/decimators


filter1d Filter 1-D data (time series)


grdfilter Filter 2-D data in space domain


PLOTTING OF 1-D and 2-D DATA


grdcontour Contouring of 2-D gridded data


grdimage Produce images from 2-D gridded data


grdvector Plot vector fields from 2-D gridded data


grdview 3-D perspective imaging of 2-D gridded data


psbasemap Create a basemap frame


psclip Use polygon files as clipping paths


pscoast Plot coastlines, filled continents, rivers, and political borders


pscontour Direct contouring or imaging of xyz data by triangulation


pshistogramPlot a histogram


psimage Plot Sun raster files on a map


pslegend Plot a legend on a map


psmask Create overlay to mask specified regions of a map


psrose Plot sector or rose diagrams


psscale Plot gray scale or color scale


pstext Plot text strings


pswiggle Draw anomalies along track


psxy Plot symbols, polygons, and lines in 2-D


psxyz Plot symbols, polygons, and lines in 3-D


GRIDDING OF (X,Y,Z) TABLE DATA


greenspline Interpolation using Green’s functions for splines in 1–3 dimensions


nearneighborNearest-neighbor gridding scheme


surface Continuous curvature gridding algorithm


triangulate Perform optimal Delauney triangulation on xyz data


SAMPLING OF 1-D AND 2-D DATA


grdsample Resample a 2-D gridded data onto new grid


grdtrack Sampling of 2-D data along 1-D track


sample1d Resampling of 1-D data


PROJECTION AND MAP-TRANSFORMATION


grdproject Transform gridded data to a new coordinate system


mapproject Transform table data to a new coordinate system


project Project data onto lines or great circles


INFORMATION


gmtdefaults List the current default settings


gmtset Command-line editing of parameters in the .gmtdefaults4 file


grdinfo Get information about the content of grid files


minmax Report extreme values in table data files


MISCELLANEOUS


gmtmath Reverse Polish Notation (RPN) calculator for table data


makecpt Create GMT color palette tables


spectrum1d Compute spectral estimates from time-series


triangulate Perform optimal Delauney triangulation on xyz data


CONVERT OR EXTRACT SUBSETS OF DATA


gmt2rgb Convert Sun raster or grid file to red, green, blue component grids


gmtconvert Convert table data from one format to another


gmtselect Select table data subsets based on multiple spatial criteria


grd2xyz Convert 2-D gridded data to table data


grdcut Cut a sub-region from a grid file


grdblend Blend several partially over-lapping grid files onto one grid


grdpaste Paste together grid files along common edge


grdreformat Convert from one grid format to another


splitxyz Split (x,y,z) table data into several segments


xyz2grd Convert table data to 2-D grid file


DETERMINE TRENDS IN 1-D AND 2-D DATA


fitcircle Finds best-fitting great or small circles


grdtrend Fits polynomial trends to grid files (z = f(x,y))


trend1d Fits polynomial or Fourier trends to y = f(x) series


trend2d Fits polynomial trends to z = f(x,y) series


OTHER OPERATIONS ON 2-D GRIDS


grd2cpt Make color palette table from grid file


grdclip Limit the z–range in gridded data sets


grdedit Modify grid header information


grdfft Operate on grid files in frequency domain


grdgradient Compute directional gradients from grid files


grdhisteq Histogram equalization for grid files


grdlandmask Creates mask grid file from coastline database


grdmask Set grid nodes in/outside a clip path to constants


grdmath Reverse Polish Notation (RPN) calculator for grid files


grdvolume Calculate volume under a surface within a contour


MANIPULATING GMT POSTSCRIPT FILES


ps2raster Crop and convert PostScript files to raster images, EPS and PDF


STANDARDIZED COMMAND LINE OPTIONS WITH OLD PROJECTION CODES


-B[p|s]xinfo[/yinfo[/zinfo]][WESNZwesnz+][:.title:] Tickmarks. Each info is
  [t]stride[phase][u][l|p][:"label":][:="prefix":][:,"unit":], where l and p apply to log10 axes only,
  and type t = {a, A, f, g, i, I}; unit u = {c, C, d, D, h, H, K, k, m, M, o, O, r, R, u, U, y, Y}
  The leading p|s selects primary [Default] or secondary axis items


-H[i][n_headers] ASCII [input] tables have header record[s]


-J (upper case for width, lower case for scale) Map projection


  -JAlon0/lat0[/horizon]/width Lambert azimuthal equal area


  -JBlon0/lat0/lat1/lat2/width Albers conic equal area


  -JClon0/lat0/width Cassini cylindrical


  -JCyl_stere/[lon0/[lat0/]]width Cylindrical stereographic


  -JDlon0/lat0/lat1/lat2/width Equidistant conic


  -JElon0/lat0[/horizon]/width Azimuthal equidistant


  -JFlon0/lat0[/horizon]/width Azimuthal gnomonic


  -JGlon0/lat0[/horizon]/width Azimuthal orthographic


  -JGlon0/lat0/alt/azim/tilt/twist/W/H/width General perspective


  -JH[lon0/]width Hammer equal area


  -JI[lon0/]width Sinusoidal equal area


  -JJ[lon0/]width Miller cylindrical


  -JKf[lon0/]width Eckert IV equal area


  -JKs[lon0/]width Eckert VI equal area


  -JLlon0/lat0/lat1/lat2/width Lambert conic conformal


  -JM[lon0/[lat0/]]width Mercator cylindrical


  -JN[lon0/]width Robinson


  -JOalon0/lat0/azim/width Oblique Mercator, 1: origin and azimuth


  -JOblon0/lat0/lon1/lat1/width Oblique Mercator, 2: two points


  -JOclon0/lat0/lonp/latp/width Oblique Mercator, 3: origin and pole


  -JP[a]width[/origin] Polar [azimuthal] (θ,r) (or cylindrical)


  -JPoly[lon0/[lat0/]]width (American) polyconic


  -JQ[lon0/[lat0/]]width Equidistant cylindrical


  -JR[lon0/]width Winkel Tripel


  -JSlon0/lat0/[/horizon]/width General stereographic


  -JTlon0/[lat0/]width Transverse Mercator


  -JUzone/width Universal Transverse Mercator (UTM)


  -JV[lon0/]width Van der Grinten


  -JW[lon0/]width Mollweide


  -JXwidth[l|pexp|T|t][/height[l|pexp|T|t]][d]Linear, log10, xayb, and time


  -JYlon0/lat0/width Cylindrical equal area


-K Append more PS later


-O This is an overlay plot


-P Select Portrait orientation


-Rwest/east/south/north[/zmin/zmax][r] Specify Region of interest


-U[[just]/dx/dy/][label] Plot time-stamp on plot


-V Run in verbose mode


-X[a|c|r]off [u] Shift plot origin in x-direction


-Y[a|c|r]off [u] Shift plot origin in y-direction


-b[i|o][c|s|S|d|D][ncol] Select binary input or output


-ccopies Set number of plot copies [1]


-f[i|o]colinfo Set formatting of ASCII input or output


-g[+]x|X|y|Y|d|Dgap[u] Segment data by detecting gaps


-m[i|o]flag Set multi-segment data mode


-:[i|o] Expect y/x input rather than x/y


STANDARDIZED COMMAND LINE OPTIONS (WITH Proj4 PROJECTION CODES)


-B[p|s]xinfo[/yinfo[/zinfo]][WESNZwesnz+][:.title:] Tickmarks. Each info is
  [t]stride[phase][u][l|p][:"label":][:="prefix":][:,"unit":], where l and p apply to log10 axes only,
  and type t = {a, A, f, g, i, I}; unit u = {c, C, d, D, h, H, K, k, m, M, o, O, r, R, u, U, y, Y}
  The leading p|s selects primary [Default] or secondary axis items


-H[i][n_headers] ASCII [input] tables have header record[s]


-J (upper case for width, lower case for scale) Map projection


  -Jaea/lon0/lat0/lat1/lat2/scale Albers conic equal area


  -Jaeqd/lon0/lat0[/horizon]/scale Azimuthal equidistant


  -Jcass/lon0/lat0/scale Cassini cylindrical


  -Jcea/lon0/lat0/scale Cylindrical equal area


  -Jcyl_stere/[lon0/[lat0/]]scale Cylindrical stereographic


  -Jeqc/[lon0/[lat0/]]scale Equidistant cylindrical


  -Jeqdc/lon0/lat0/lat1/lat2/scale Equidistant conic


  -Jgnom/lon0/lat0[/horizon]/scale Azimuthal gnomonic


  -Jhammer/[lon0/]scale Hammer equal area


  -Jeck4/[lon0/]scale Eckert IV equal area


  -Jeck6/[lon0/]scale Eckert VI equal area


  -Jlaea/lon0/lat0[/horizon]/scale Lambert azimuthal equal area


  -Jlcc/lon0/lat0/lat1/lat2/scale Lambert conic conformal


  -Jmerc/[lon0/[lat0/]]scale Mercator cylindrical


  -Jmill/[lon0/]scale Miller cylindrical


  -Jmoll/[lon0/]scale Mollweide


  -Jnsper/lon0/lat0/alt/azim/tilt/twist/W/H/scale General perspective


  -Jomerc/lon0/lat0/azim/scale Oblique Mercator, 1: origin and azimuth


  -Jomerc/lon0/lat0/lon1/lat1/scale Oblique Mercator, 2: two points


  -Jomercp/lon0/lat0/lonp/latp/scale Oblique Mercator, 3: origin and pole


  -Jortho/lon0/lat0[/horizon]/scale Azimuthal orthographic


  -Jpolar/[a]scale[/origin] Polar [azimuthal] (θ,r) (or cylindrical)


  -Jpoly[lon0/[lat0/]]width (American) polyconic


  -Jrobin/[lon0/]scale Robinson


  -Jsinu/[lon0/]scale Sinusoidal equal area


  -Jstere/lon0/lat0/[/horizon]/scale General stereographic


  -Jtmerc/lon0/[lat0/]scale Transverse Mercator


  -Jutm/zone/scale Universal Transverse Mercator (UTM)


  -Jvandg/[lon0/]scale Van der Grinten


  -Jwintri/[lon0/]scale Winkel Tripel


  -Jxy/xscale[l|pexp|T|t][/yscale[l|pexp|T|t]][d]Linear, log10, xayb, and time


-K Append more PS later


-O This is an overlay plot


-P Select Portrait orientation


-Rwest/east/south/north[/zmin/zmax][r] Specify Region of interest


-U[[just]/dx/dy/][label] Plot time-stamp on plot


-V Run in verbose mode


-X[a|c|r]off [u] Shift plot origin in x-direction


-Y[a|c|r]off [u] Shift plot origin in y-direction


-b[i|o][c|s|S|d|D][ncol] Select binary input or output


-ccopies Set number of plot copies [1]


-f[i|o]colinfo Set formatting of ASCII input or output


-g[+]x|X|y|Y|d|Dgap[u] Segment data by detecting gaps


-m[i|o]flag Set multi-segment data mode


-:[i|o] Expect y/x input rather than x/y


Chapter 4
General features

This section explains features common to all the programs in GMT and summarizes the philosophy behind the system. Some of the features described here may make more sense once you reach the cook-book section where we present actual examples of their use.

4.1 GMT units

GMT programs can accept dimensional quantities in cm, inch, meter, or point (1/72 of an inch)9. There are two ways to ensure that GMT understands which unit you intend to use.

  1. Append the desired unit to the dimension you supply. This way is explicit and clearly communicates what you intend, e.g., -X4c means the length being passed to the -X switch is 4 cm.
  2. Set the parameter MEASURE_UNIT to the desired unit. Then, all dimensions without explicit unit will be interpreted accordingly.

The latter method is less secure as other users may have a different unit set and your script may not work as intended. We therefore recommend you always supply the desired unit explicitly.

4.2 GMT defaults

4.2.1 Overview and the .gmtdefaults4 file


PIC

Figure 4.1: Some GMT parameters that affect plot appearance.

There are about 100 parameters which can be adjusted individually to modify the appearance of plots or affect the manipulation of data. When a program is run, it initializes all parameters to the GMT defaults10, then tries to open the file .gmtdefaults4 in the current directory11. If not found, it will look for that file in a sub-directory /̃.gmt of your home directory, and finally in your home directory itself. If successful, the program will read the contents and set the default values to those provided in the file. By editing this file you can affect features such as pen thicknesses used for maps, fonts and font sizes used for annotations and labels, color of the pens, dots-per-inch resolution of the hardcopy device, what type of spline interpolant to use, and many other choices (A complete list of all the parameters and their default values can be found in the gmtdefaults manual pages). Figures 4.2.1, 4.2, and 4.3 show the parameters that affect plots). You may create your own .gmtdefaults4 files by running gmtdefaults and then modify those parameters you want to change. If you want to use the parameter settings in another file you can do so by specifying +<defaultfile> on the command line. This makes it easy to maintain several distinct parameter settings, corresponding perhaps to the unique styles required by different journals or simply reflecting font changes necessary to make readable overheads and slides. Note that any arguments given on the command line (see below) will take precedent over the default values. E.g., if your .gmtdefaults4 file has x offset = 1i as default, the -X1.5i option will override the default and set the offset to 1.5 inches.

There are at least two good reasons why the GMT default options are placed in a separate parameter file:

  1. It would not be practical to allow for command-line syntax covering so many options, many of which are rarely or never changed (such as the ellipsoid used for map projections).
  2. It is convenient to keep separate .gmtdefaults4 files for specific projects, so that one may achieve a special effect simply by running GMT commands in the directory whose .gmtdefaults4 file has the desired settings. For example, when making final illustrations for a journal article one must often standardize on font sizes and font types, etc. Keeping all those settings in a separate .gmtdefaults4 file simplifies this process and will allow you to generate those illustrations with the same settings later on. Likewise, GMT scripts that make figures for PowerPoint presentations often use a different color scheme and font size than output intended for laser printers. Organizing these various scenarios into separate .gmtdefaults4 files will minimize headaches associated with micro-editing of illustrations.
    PIC
    Figure 4.2: More GMT parameters that affect plot appearance.

4.2.2 Changing GMT defaults

As mentioned, GMT programs will attempt to open a file named .gmtdefaults4. At times it may be desirable to override that default. There are several ways in which this can be accomplished.

  1. Supply another filename using the +filename syntax, i.e., on the same command line as the GMT command we append the name of the alternate .gmtdefaults4 file with the plus sign as a prefix. Because any changes only apply to that one command you would have to append the alternate file to every command in your script. This is tedious but may be an option for situations when you cannot write in the current directory (e.g., some CGI scripts).
  2. A perhaps less tedious method is to start each script by making a copy of the current .gmtdefaults4, then copy the desired .gmtdefaults4 file to the current directory, and finally undo the changes at the end of the script. Possible side effects include premature ending of the script due to user error or bugs which means the final resetting does not take place (unless you write your script very carefully.)
  3. To permanently change some of the GMT parameters on the fly inside a script the gmtset utility can be used. E.g., to change the primary annotation font to 12 point Times-Bold we run

    gmtset ANNOT_FONT_PRIMARY Times-Bold ANNOT_FONT_SIZE_PRIMARY 12

    These changes will remain in effect until they are overridden.

  4. If all you want to achieve is to change a few parameters during the execution of a single command but otherwise leave the environment intact, consider passing the parameter changes on the command line via the ––PAR=value mechanism. For instance, to temporarily set the output format for floating points to have lots of decimals, say, for map projection coordinate output, append ––D_FORMAT=%.12lg to the command in question.
  5. Finally, since version 4.2.2 GMT provides to possibility to override the settings only during the running of a single script, reverting to the original settings after the script is run, as if the script was run in “isolation”. The isolation mode is discussed in Section P.1.

In addition to those parameters that directly affect the plot there are numerous parameters than modify units, scales, etc. For a complete listing, see the gmtdefaults man pages. We suggest that you go through all the available parameters at least once so that you know what is available to change via one of the described mechanisms.


PIC

Figure 4.3: Even more GMT parameters that affect plot appearance.

Note: All examples presented in this document started by copying the file .gmtdefaults4.doc from the directory doc/scripts to .gmtdefaults4. As a result the commands gmtset of other scripts were overall, reverting to a “virgin” of parameters set in .gmtdefaults4.doc. The graphs in Chapter 7 were created using .gmtdefaults4.doc from the directory examples after which the graphs were scaled down by 50%.

4.3 Command line arguments

Each program requires certain arguments specific to its operation. These are explained in the manual pages and in the usage messages. Most programs are “case-sensitive”; almost all options must start with an upper-case letter. We have tried to choose letters of the alphabet which stand for the argument so that they will be easy to remember. Each argument specification begins with a hyphen (except input file names; see below), followed by a letter, and sometimes a number or character string immediately after the letter. Do not space between the hyphen, letter, and number or string. Do space between options. Example:

pscoast -R0/20/0/20 -Ggray -JM6i -Wthin -B5 -V -P > map.ps

4.4 Standardized command line options

Most of the programs take many of the same arguments like those related to setting the data region, the map projection, etc. The 17 switches in Table 4.1 have the same meaning in all the programs (although some programs may not use all of them). These options will be described here as well as in the manual pages, as is vital that you understand how to use these options. We will present these options in order of importance (some are use a lot more than others).




Option
Meaning


-B Defines tickmarks, annotations, and labels for basemaps and axes


-H Specifies that input/output tables have header record(s)


-J Selects a map projection or coordinate transformation


-K Allows more plot code to be appended to this plot later


-O Allows this plot code to be appended to an existing plot


-P Selects Portrait plot orientation [Default is landscape]


-R Defines the extent of the map/plot region


-U Plots a time-stamp, by default in the lower left corner of page


-V Selects verbose operation; reporting on progress


-X Sets the x-coordinate for the plot origin on the page


-Y Sets the y-coordinate for the plot origin on the page


-b Selects binary input and/or output


-c Specifies the number of plot copies


-f Specifies the data format on a per column basis


-g Identify data gaps based on supplied criteria


-m Specifies data in multiple segment format


-: Assumes input geographic data are (lat,lon) and not (lon,lat)



Table 4.1: The 17 standardized GMT command line switches.

4.4.1 Data domain or map region: The -R option


PIC

Figure 4.4: The plot region can be specified in two different ways. (a) Extreme values for each dimension, or (b) coordinates of lower left and upper right corners.

The -R option defines the map region or data domain of interest. It may be specified in one of three ways (Figure 4.4):

  1. -Rxmin/xmax/ymin/ymax. This is the standard way to specify Cartesian data domains and geographical regions when using map projections where meridians and parallels are rectilinear.
  2. -Rxlleft/ylleft/xuright/yurightr. This form is used with map projections that are oblique, making meridians and parallels poor choices for map boundaries. Here, we instead specify the lower left corner and upper right corner geographic coordinates, followed by the suffix r.
  3. -Rgridfile. This will copy the domain settings found for the grid in specified file. Note that depending on the nature of the calling program, this mechanism will also set grid spacing and possibly the grid registration (see Appendix B.2.2).

For rectilinear projections the first two forms give identical results. Depending on the selected map projection (or the kind of expected input data), the boundary coordinates may take on three different formats:

Geographic coordinates:
These are longitudes and latitudes and may be given in decimal degrees (e.g., -123.45417) or in the []ddd[:mm[:ss[.xxx]]][W|E|S|N] format (e.g., 123:27:15W). Note that -Rg and -Rd are shorthands for “global domain” -R0/360/-90/90 and -R-180/180/-90/90, respectively.

When used in conjunction with the Cartesian Linear Transformation (-Jx or -JX) —which can be used to map floating point data, geographical coordinates, as well as time coordinates— it is prudent to indicate that you are using geographical coordinates in one of the following ways:

Calendar time coordinates:
These are absolute time coordinates referring to a Gregorian or ISO calendar. The general format is [date]T[clock], where date must be in the yyyy[-mm[-dd]] (year, month, day-of-month) or yyyy[-jjj] (year and day-of-year) for Gregorian calendars and yyyy[-Www[-d]] (year, week, and day-of-week) for the ISO calendar. If no date is given we assume the current day. Following the [optional] date string we require the T flag.

The optional clock string is a 24-hour clock in hh[:mm[:ss[.xxx]]] format. If no clock is given it implies 00:00:00, i.e., the start of the specified day. Note that not all of the specified entities need be present in the data. All calendar date-clock strings are internally represented as double precision seconds since proleptic Gregorian date Mon Jan 1 00:00:00 0001. Proleptic means we assume that the modern calendar can be extrapolated forward and backward; a year zero is used, and Gregory’s reforms12 are extrapolated backward. Note that this is not historical.

Relative time coordinates:
These are coordinates which count seconds, hours, days or years relative to a given epoch. A combination of the parameters TIME_EPOCH and TIME_UNIT define the epoch and time unit. The parameter TIME_SYSTEM provides a few shorthands for common combinations of epoch and unit, like j2000 for days since noon of 1 Jan 2000. Denote relative time coordinates by appending the optional lower case t after the value. When it is otherwise apparent that the coordinate is relative time (for example by using the -f switch), the t can be omitted.
Other coordinates:
These are simply any coordinates that are not related to geographic or calendar time or relative time and are expected to be simple floating point values such as []xxx.xxx[E|e|D|d[]xx], i.e., regular or exponential notations, with the enhancement to understand FORTRAN double precision output which may use D instead of E for exponents. These values are simply converted as they are to internal representation.13

4.4.2 Coordinate transformations and map projections: The -J option

This option selects the coordinate transformation or map projection. The general format is

Since GMT version 4.3.0, there is an alternative way to specify the projections: use the same abbreviation as in the mapping package Proj4. The options thus either look like:


PIC

Figure 4.5: The 30+ map projections and coordinate transformations available in GMT.

The projections available in GMT are presented in Figure 4.5. For details on all GMT projections and the required parameters, see the psbasemap man page. We will also show examples of every projection in the next Chapters, and a quick summary of projection syntax was given in Chapter 3.

4.4.3 Map frame and axes annotations: The -B option

This is by far the most complicated option in GMT, but most examples of its usage are actually quite simple. Given as -B[p|s]xinfo[/yinfo[/zinfo]][:."title string":][W|w][E|e][S|s][N|n][Z|z[+]], this switch specifies map boundaries (or plot axes) to be plotted by using the selected information. The optional flag following -B selects p(rimary) [Default] or s(econdary) axes information (mostly used for time axes annotations; see examples below). The components xinfo, yinfo and zinfo are of the form

info[:"axis label":][:="prefix":][:,"unit label":]

where info is one or more concatenated substrings of the form [t]stride[phase][u]. The t flag sets the axis item of interest; the available items are listed in Table 4.2. By default, all 4 map boundaries (or plot axes) are plotted (denoted W, E, S, N). To change this selection, append the codes for those you want (e.g., WSn). Upper case (e.g., W) will annotate in addition to draw axis/tick-marks. The title, if given, will appear centered above the plot14. Unit label or prefix may start with a leading – to suppress the space between it and the annotation. Normally, equidistant annotations occur at multiples of stride; you can phase-shift this by appending phase.




FlagDescription


a Annotation tick spacing


f Frame tick spacing


g Grid tick spacing



Table 4.2: Interval type codes.

Note that the appearance of certain time annotations (month-, week-, and day-names) may be affected by the TIME_LANGUAGE, TIME_FORMAT_PRIMARY, and TIME_FORMAT_SECONDARY settings.

The unit flag u can take on one of 18 codes; these are listed in Table 4.3. Almost all of these units are time-axis specific. However, the m and c units will be interpreted as arc minutes and arc seconds, respectively, when a map projection is in effect.





FlagUnit Description



Y year Plot using all 4 digits



y year Plot using last 2 digits



O month Format annotation using PLOT_DATE_FORMAT



o month Plot as 2-digit integer (1–12)



U ISO week Format annotation using PLOT_DATE_FORMAT



u ISO week Plot as 2-digit integer (1–53)



r Gregorian week7-day stride from start of week (see TIME_WEEK_START)



K ISO weekday Plot name of weekday in selected language



k weekday Plot number of day in the week (1-7) (see TIME_WEEK_START)



D date Format annotation using PLOT_DATE_FORMAT



d day Plot day of month (1–31) or day of year (1–366)
(see PLOT_DATE_FORMAT



R day Same as d; annotations aligned with week (see TIME_WEEK_START)



H hour Format annotation using PLOT_CLOCK_FORMAT



h hour Plot as 2-digit integer (0–24)



M minute Format annotation using PLOT_CLOCK_FORMAT



m minute Plot as 2-digit integer (0–60)



C seconds Format annotation using PLOT_CLOCK_FORMAT



c seconds Plot as 2-digit integer (0–60)




Table 4.3: Interval unit codes.

There may be two levels of annotations. Here, “primary” refers to the annotation that is closest to the axis (this is the primary annotation), while “secondary” refers to the secondary annotation that is plotted further from the axis. The examples below will clarify what is meant. Note that the terms “primary” and “secondary” do not reflect any hierarchical order of units: The “primary” annotation interval is usually smaller (e.g., days) while the “secondary” annotation interval typically is larger (e.g., months).

Geographic basemaps

Geographic basemaps may differ from regular plot axis in that some projections support a “fancy” form of axis and is selected by the BASEMAP_TYPE setting. The annotations will be formatted according to the PLOT_DEGREE_FORMAT template and DEGREE_SYMBOL setting. A simple example of part of a basemap is shown in Figure 4.6.


PIC

Figure 4.6: Geographic map border using separate selections for annotation, frame, and grid intervals. Formatting of the annotation is controlled by the parameter PLOT_DEGREE_FORMAT in your .gmtdefaults4 file.

The machinery for primary and secondary annotations introduced for time-series axes can also be utilized for geographic basemaps. This may be used to separate degree annotations from minutes- and seconds-annotations. For a more complicated basemap example using several sets of intervals, including different intervals and pen attributes for grid lines and grid crosses, see Figure 4.7.


PIC

Figure 4.7: Geographic map border with both primary (P) and secondary (S) components.

Cartesian linear axes

For non-geographic axes, the BASEMAP_TYPE setting is implicitly set to plain. Other than that, cartesian linear axes are very similar to geographic axes. The annotation format may be controlled with the D_FORMAT parameter. By default, it is set to “%g”, which is a C language format statement for floating point numbers15, and with this setting the various axis routines will automatically determine how many decimal points should be used by inspecting the stride settings. If D_FORMAT is set to another format it will be used directly (.e.g, “%.2f” for a fixed, two decimals format). Note that for these axes you may use the unit setting to add a unit string to each annotation (see Figure 4.8).


PIC

Figure 4.8: Linear Cartesian projection axis. Long tickmarks accompany annotations, shorter ticks indicate frame interval. The axis label is optional. We used -R0/12/0/1 -JX3/0.4 -Ba4f2g1:Frequency::,%:.

Cartesian log10 axes

Due to the logarithmic nature of annotation spacings, the stride parameter takes on specific meanings. The following concerns are specific to log axes:

  1. stride must be 1, 2, 3, or a negative integer -n. Annotations/ticks will then occur at 1, 1–2–5, or 1,2,3,4,...,9, respectively, for each magnitude range. For -n the annotations will take place every n’th magnitude.
  2. Append l to stride. Then, log10 of the annotation is plotted at every integer log10 value (e.g., x = 100 will be annotated as “2”) [Default annotates x as is].
  3. Append p to stride. Then, annotations appear as 10 raised to log10 of the value (e.g., 10-5).

PIC

Figure 4.9: Logarithmic projection axis using separate values for annotation, frame, and grid intervals. (top) Here, we have chosen to annotate the actual values. Interval = 1 means every whole power of 10, 2 means 1, 2, 5 times powers of 10, and 3 means every 0.1 times powers of 10. We used -R1/1000/0/1 -JX3l/0.4 -Ba1f2g3. (middle) Here, we have chosen to annotate log10 of the actual values, with -Ba1f2g3l. (bottom) We annotate every power of 10 using log10 of the actual values as exponents, with -Ba1f2g3p.

Cartesian exponential axes

Normally, stride will be used to create equidistant (in the user’s unit) annotations or ticks, but because of the exponential nature of the axis, such annotations may converge on each other at one end of the axis. To avoid this problem, you can append p to stride, and the annotation interval is expected to be in transformed units, yet the annotation itself will be plotted as un-transformed units. E.g., if stride = 1 and power = 0.5 (i.e., sqrt), then equidistant annotations labeled 1, 4, 9, ... will appear.


PIC

Figure 4.10: Exponential or power projection axis. (top) Using an exponent of 0.5 yields a x axis. Here, intervals refer to actual data values, in -R0/100/0/1 -JX3p0.5/0.4 -Ba20f10g5. (bottom) Here, intervals refer to projected values, although the annotation uses the corresponding unprojected values, as in -Ba3f2g1p.

Cartesian time axes

What sets time axis apart from the other kinds of plot axes is the numerous ways in which we may want to tick and annotate the axis. Not only do we have both primary and secondary annotation items but we also have interval annotations versus tickmark annotations, numerous time units, and several ways in which to modify the plot. We will demonstrate this flexibility with a series of examples. While all our examples will only show a single x-axis, time-axis is supported for all axes.

Our first example shows a time period of almost two months in Spring 2000. We want to annotate the month intervals as well as the date at the start of each week:

_________________________________________________________________________________

gmtset PLOT_DATE_FORMAT -o ANNOT_FONT_SIZE_PRIMARY +9p  
psbasemap -R2000-4-1T/2000-5-25T/0/1 -JX5/0.2 -Bpa7Rf1d -Bsa1OS -P > GMT_-B_time1.ps
__________________________________________________________________________________________________

These commands result in Figure 4.11. Note the leading hyphen in the PLOT_DATE_FORMAT removes leading zeros from calendar items (e.g., 02 becomes 2).


PIC

Figure 4.11: Cartesian time axis, example 1.

The next example shows two different ways to annotate an axis portraying 2 days in July 1969:

_________________________________________________________________________________

gmtset PLOT_DATE_FORMAT ~o dd~ PLOT_CLOCK_FORMAT hh:mm ANNOT_FONT_SIZE_PRIMARY +9p  
psbasemap -R1969-7-21T/1969-7-23T/0/1 -JX5/0.2 -Bpa6Hf1h -Bsa1KS -P -K > GMT_-B_time2.ps  
psbasemap -R -J -Bpa6Hf1h -Bsa1DS -O -Y0.65i >> GMT_-B_time2.ps
__________________________________________________________________________________________________

The lower example (Figure 4.12) chooses to annotate the weekdays (by specifying a1K) while the upper example choses dates (by specifying a1D). Note how the clock format only selects hours and minutes (no seconds) and the date format selects a month name, followed by one space and a two-digit day-of-month number.


PIC

Figure 4.12: Cartesian time axis, example 2.

The third example presents two years, annotating both the years and every 3rd month.

_________________________________________________________________________________

gmtset PLOT_DATE_FORMAT o TIME_FORMAT_PRIMARY Character ANNOT_FONT_SIZE_PRIMARY +9p  
psbasemap -R1997T/1999T/0/1 -JX5/0.2 -Bpa3Of1o -Bsa1YS -P > GMT_-B_time3.ps
__________________________________________________________________________________________________

Note that while the year annotation is centered on the 1-year interval, the month annotations must be centered on the corresponding month and not the 3-month interval. The PLOT_DATE_FORMAT selects month name only and TIME_FORMAT_PRIMARY selects the 1-character, upper case abbreviation of month names using the current language (selected by TIME_LANGUAGE).


PIC

Figure 4.13: Cartesian time axis, example 3.

The fourth example (Figure 4.14) only shows a few hours of a day, using relative time by specifying t in the -R option while the TIME_UNIT is d (for days). We select both primary and secondary annotations, ask for a 12-hour clock, and let time go from right to left:

_________________________________________________________________________________

gmtset PLOT_CLOCK_FORMAT -hham ANNOT_FONT_SIZE_PRIMARY +9p  
psbasemap -R0.2t/0.35t/0/1 -JX-5/0.2 -Bpa15mf5m -Bsa1HS -P > GMT_-B_time4.ps
__________________________________________________________________________________________________

PIC

Figure 4.14: Cartesian time axis, example 4.

The fifth example shows a few weeks of time (Figure 4.15). The lower axis shows ISO weeks with week numbers and abbreviated names of the weekdays. The upper uses Gregorian weeks (which start at the day chosen by TIME_WEEK_START); they do not have numbers. ______________________________________________________________________________

gmtset PLOT_DATE_FORMAT u TIME_FORMAT_PRIMARY Character TIME_FORMAT_SECONDARY full \  
        ANNOT_FONT_SIZE_PRIMARY +9p  
psbasemap -R1969-7-21T/1969-8-9T/0/1 -JX5/0.2 -Bpa1K -Bsa1US -P -K > GMT_-B_time5.ps  
gmtset PLOT_DATE_FORMAT o TIME_WEEK_START Sunday TIME_FORMAT_SECONDARY Chararacter  
psbasemap -R -J -Bpa3Kf1k -Bsa1rS -O -Y0.65i >> GMT_-B_time5.ps
__________________________________________________________________________________________________

PIC

Figure 4.15: Cartesian time axis, example 5.

Our sixth example shows the first five months of 1996, and we have annotated each month with an abbreviated, upper case name and 2-digit year. Only the primary axes information is specified. ______

gmtset PLOT_DATE_FORMAT ~o yy~ TIME_FORMAT_PRIMARY Abbreviated  
psbasemap -R1996T/1996-6T/0/1 -JX5/0.2 -Ba1Of1dS -P > GMT_-B_time6.ps
__________________________________________________________________________________________________

PIC

Figure 4.16: Cartesian time axis, example 6.

Our seventh and final example illustrates annotation of year-days. Unless we specify the formatting with a leading hyphen in PLOT_DATE_FORMAT we get 3-digit integer days. Note that in order to have the two years annotated we need to allow for the annotation of small fractional intervals; normally such truncated interval must be at least half of a full interval. ______________________________________________________________________________________________________________________

gmtset PLOT_DATE_FORMAT jjj TIME_INTERVAL_FRACTION 0.05 ANNOT_FONT_SIZE_PRIMARY +9p  
psbasemap -R2000-12-15T/2001-1-15T/0/1 -JX5/0.2 -Bpa5Df1d -Bsa1YS -P > GMT_-B_time7.ps
__________________________________________________________________________________________________

PIC

Figure 4.17: Cartesian time axis, example 7.

4.4.4 Header data records: The -H option

The -H[i][n_recs] option lets GMT know that input file(s) have one [Default] or more header records. If there are more than one header record you must specify the number after the -H option, e.g., -H4. The default number of header records if -H is used is one of the many parameters in the .gmtdefaults4 file (N_HEADER_RECS), but can be overridden by -Hn_header_recs. Note that blank lines and records that be start with the character # are automatically skipped. Normally, programs that both read and write tables will output the header records that are found on input. Use -Hi to suppress the writing of header records.

4.4.5 Portrait plot orientation: The -P option


PIC

Figure 4.18: Users can specify Landscape [Default] or Portrait (-P) orientation.

-P selects Portrait plotting mode16. In general, a plot has an x-axis increasing from left to right and a y-axis increasing from bottom to top. If the paper is turned so that the long dimension of the paper is parallel to the x-axis then the plot is said to have Landscape orientation. If the long dimension of the paper parallels the y-axis the orientation is called Portrait (think of taking pictures with a camera and these words make sense). The default Landscape orientation is obtained by translating the origin in the x-direction (by the width of the chosen paper PAPER_MEDIA) and then rotating the coordinate system counterclockwise by 90. By default the PAPER_MEDIA is set to Letter (or A4 if SI is chosen); this value must be changed when using different media, such as 11" x 17" or large format plotters (Figure 4.18).

4.4.6 Plot overlays: The -K-O options


PIC

Figure 4.19: A final PostScript file consists of any number of individual pieces.

The -K and -O options control the generation of PostScript code for multiple overlay plots. All PostScript files must have a header (for initializations), a body (drawing the figure), and a trailer (printing it out) (see Figure 4.19). Thus, when overlaying several GMT plots we must make sure that the first plot call omits the trailer, that all intermediate calls omit both header and trailer, and that the final overlay omits the header. -K omits the trailer which implies that more PostScript code will be appended later [Default terminates the plot system]. -O selects Overlay plot mode and omits the header information [Default initializes a new plot system]. Most unexpected results for multiple overlay plots can be traced to the incorrect use of these options. If you run only one plot program, ignore both the -O and -K options; they are only used when stacking plots.

4.4.7 Timestamps on plots: The -U option

-U draws UNIX System time stamp. Optionally, append an arbitrary text string (surrounded by double quotes), or the code c, which will plot the current command string (Figure 4.20).


PIC

Figure 4.20: The -U option makes it easy to “date” a plot.

4.4.8 Verbose feedback: The -V option

-V selects verbose mode, which will send progress reports to stderr [Default runs “silently”]. The interpretation of this option can be toggled by changing the default VERBOSE.

4.4.9 Plot positioning and layout: The -X-Y options


PIC

Figure 4.21: Plot origin can be translated freely with -X-Y.

-X and -Y shift origin of plot by (xoff ,yoff ) inches (Default is (X_ORIGIN, Y_ORIGIN) for new plots17 and (0,0) for overlays (-O)). By default, all translations are relative to the previous origin (see Figure 4.21). Supply offset as c to center the plot in that direction relative to the page margin. Absolute translations (i.e., relative to a fixed point (0,0) at the lower left corner of the paper) can be achieve by prepending “a” to the offsets. Subsequent overlays will be co-registered with the previous plot unless the origin is shifted using these options. The offsets are measured in the current coordinates system (which can be rotated using the initial -P option; subsequent -P options for overlays are ignored).

4.4.10 Binary table i/o: The -b option

All GMT programs that accept table data input may read ASCII, native binary, or netCDF data. When using native binary data the user must be aware of the fact that GMT has no way of determining the actual number of columns in the file. You must therefore pass that information to GMT via the binary -bi[s]n option, where n is the actual number of data columns (s indicates single (4 bytes) rather than double (8 bytes) precision). If uppercase S (or D) are used it implies that byte-swapping should be performed just prior to writing (for output) or immediately after reading (for input). Note that n may be larger than m, the number of columns that the GMT program requires to do its task. If n is not given then it defaults to m. If n < m an error is generated.

Because of its meta data, reading netCDF tables (i.e., netCDF files containing 1-dimensional arrays) is quite a bit less complex than reading native binary files. When feeding netCDF tables to programs like psxy, the program will automatically recognize the format and read whatever amount of columns are needed for that program. To steer which columns are to be read, the user can either append the suffix ?var1/var2/... to the netCDF file name or add the option -bicvar1/var2/..., where var1, var2, etc. are the names of the variables to be processed. The latter option is particularly practical when more than one file is read: the -bic option will apply to all files.

Currently, netCDF tables can only be input, not output. For more information, see Appendix B.

4.4.11 Number of Copies: The -c option

The -c option specifies the number of plot copies [Default is 1]. This value is embedded in the PostScript file and will make a printer issue the chosen number of copies without respooling.

4.4.12 Data type selection: The -f option

When map projections are not required we must explicitly state what kind of data each input or output column contains. This is accomplished with the -f option. Following an optional i (for input only) or o (for output only), we append a text string with information about each column (or range of columns) separated by commas. Each string starts with the column number (0 is first column) followed by either x (longitude), y (latitude), T (absolute calendar time) or t (relative time). If several consecutive columns have the same format you may specify a range of columns rather than a single column, i.e., 0-4 for the first 5 columns. For example, if our input file has geographic coordinates (latitude, longitude) with absolute calendar coordinates in the columns 3 and 4, we would specify fi0y,1x,3-4T. All other columns are assumed to have the default, floating point format and need not be set individually. The shorthand -f[i|o]g means -f[i|o]0x,1y (geographic coordinates). For more information, see Sections 4.10 and 4.11.

4.4.13 Data gap detection: The -g option

GMT has several mechanisms that can determine line segmentation. Typically, data segments are separated by multiple segment header records (see section 4.4.14 on -m below). However, if key data columns contain a NaN we may also use that information to break lines into multiple segments. This behavior is modified by the parameter NAN_RECORDS which by default is set to skip, meaning such records are considered bad and simply skipped. If you wish such records to indicate a segment boundary then set this parameter to pass. Finally, you may wish to indicate gaps based on the data values themselves. The -g option is used to detect gaps based on one or more criteria (use -g+ if all the criteria must be met; otherwise only one of the specified criteria needs to be met to signify a data gap). Gaps can be based on excessive jumps in the x- or y-coordinates (-gx or -gy), or on the distance between points (-gd). Append the gap distance and optionally a unit for actual distances. For geographic data the optional unit may be meter [Default], kilometer, miles, or nautical miles. For programs that maps data to map coordinates you can optionally specify these criteria to apply to the projected coordinates (by using upper-case -gX, -gY or-gD). In that case, choose from inch, centimeter, meter, or points. [Default unit is controlled by MEASURE_UNIT]. Note: For -gx or -gy with time data the unit is instead controlled by TIME_UNIT.

4.4.14 Multiple segment data: The -m option

The -m option states that the input and output table data will contain special records that marks the start of new line (or polygon) segments. These records are identified by their first character, which can be specified as an argument to -m [The default is >]. Append the modifiers i or o if the option should only apply to input or output, respectively. For binary data a multiple segment header is identified as a data record where all fields equal NaN. See section 4.4.14 and Appendix B for more details.

4.4.15 Lat/Lon or Lon/Lat?: The -: option

For geographical data, the first column is expected to contain longitudes and the second to contain latitudes. To reverse this expectation you must apply the -: option. Optionally, append i or o to restrict the effect to input or output only. Note that command line arguments that may take geographic coordinates (e.g., -R) always expect longitude before latitude. Also, geographical grids are expected to have the longitude as first (minor) dimension.

4.5 Command line history

GMT programs “remember” the standardized command line options (See Section 4.4) given during their previous invocations and this provides a shorthand notation for complex options. For example, if a basemap was created with an oblique Mercator projection, specified as

-Joc170W/25:30S/33W/56:20N/1:500000

then a subsequent psxy command to plot symbols only needs to state -Jo in order to activate the same projection. In contrast, note that -J by itself will pick the most recently used projection. Previous commands are maintained in the file .gmtcommands4, of which there will be one in each directory you run the programs from. This is handy if you create separate directories for separate projects since chances are that data manipulations and plotting for each project will share many of the same options. Note that an option spelled out on the command line will always override the last entry in the .gmtcommands4 file and, if execution is successful, will replace this entry as the previous option argument in the .gmtcommands4 file. If you call several GMT modules piped together then GMT cannot guarantee that the .gmtcommands4 file is processed in the intended order from left to right. The only guarantee is that the file will not be clobbered since GMT uses advisory file locking. The uncertainty in processing order makes the use of shorthands in pipes unreliable. We therefore recommend that you only use shorthands in single process command lines, and spell out the full command option when using chains of commands connected with pipes.

4.6 Usage messages, syntax- and general error messages

Each program carries a usage message. If you enter the program name without any arguments, the program will write the complete usage message to standard error (your screen, unless you redirect it). This message explains in detail what all the valid arguments are. If you enter the program name followed by a hyphen (–) only you will get a shorter version which only shows the command line syntax and no detailed explanations. If you incorrectly specify an option or omit a required option, the program will produce syntax errors and explain what the correct syntax for these options should be. If an error occurs during the running of a program, the program will in some cases recognize this and give you an error message. Usually this will also terminate the run. The error messages generally begin with the name of the program in which the error occurred; if you have several programs piped together this tells you where the trouble is.

4.7 Standard input or file, header records

Most of the programs which expect table data input can read either standard input or input in one or several files. These programs will try to read stdin unless you type the filename(s) on the command line without the above hyphens. (If the program sees a hyphen, it reads the next character as an instruction; if an argument begins without a hyphen, it tries to open this argument as a filename). This feature allows you to connect programs with pipes if you like. If your input is ASCII and has one or more header records, you must use the -H option (see Section 4.4.4). For binary table data no headers are allowed. ASCII files may in many cases also contain sub-headers separating data segments. These are called “multi-segment files” and requires a special option (typically -m); see Appendix B for complete documentation.

If filenames are given for reading, GMT programs will first look for them in the current directory. If the file is not found, the programs will look in two other directories pointed to by environmental parameters (if set). These are GMT_DATADIR and GMT_USERDIR, and they may be set by the user to point to directories that contain data sets of general use. Normally, the first directory (or directories: add multiple paths by separating them with colons (semi-colons under Windows)) will hold data sets of a general nature (tables, grids), although a particular use is to make available large grids accessible via the supplemental programs grdraster or img2grd; see Appendix A for information about these supplemental programs. The second directory may hold miscellaneous data sets more specific to the user; this directory also stores GMT defaults and other configuration files. Data sets that the user finds are often needed may be placed in these directories, thus eliminating the need to specify a full path to the file. Program output is always written to the current directory unless a full path has been specified.

4.8 Verbose operation

Most of the programs take an optional -V argument which will run the program in the “verbose” mode (see Section 4.4.8). Verbose will write to standard error information about the progress of the operation you are running. Verbose reports things such as counts of points read, names of data files processed, convergence of iterative solutions, and the like. Since these messages are written to stderr, the verbose talk remains separate from your data output.

4.9 Program output

Most programs write their results, including PostScript plots, to standard output. The exceptions are those which may create binary netCDF grid files such as surface (due to the design of netCDF a filename must be provided; however, alternative binary output formats allowing piping are available; see Section 4.17). With UNIX you can redirect standard output to a file or pipe it into another process. Error messages, usage messages, and verbose comments are written to standard error in all cases. You can use UNIX to redirect standard error as well, if you want to create a log file of what you are doing.

4.10 Input data formats

Most of the time, GMT will know what kind of x and y coordinates it is reading because you have selected a particular coordinate transformation or map projection. However, there may be times when you must explicitly specify what you are providing as input using the -f switch. When binary input data are expected (-bi) they must all be floating point numbers, however for ASCII input there are numerous ways to encode data coordinates (which may be separated by white-space or commas). Valid input data are generally of the same form as the arguments to the -R option (see Section 4.4.1), with additional flexibility for calendar data. Geographical coordinates, for example, can be given in decimal degrees (e.g., -123.45417) or in the []ddd[:mm[:ss[.xxx]]][W|E|S|N] format (e.g., 123:27:15W).

Because of the widespread use of incompatible and ambiguous formats, the processing of input date components is guided by the template INPUT_DATE_FORMAT in your .gmtdefaults4 file; it is by default set to yyyy-mm-dd. Y2K-challenged input data such as 29/05/89 can be processed by setting INPUT_DATE_FORMAT to dd/mm/yy. A complete description of possible formats is given in the gmtdefaults man page. The clock string is more standardized but issues like 12- or 24-hour clocks complicate matters as well as the presence or absence of delimiters between fields. Thus, the processing of input clock coordinates is guided by the template INPUT_CLOCK_FORMAT which defaults to hh:mm:ss.xxx.

GMT programs that require a map projection argument will implicitly know what kind of data to expect, and the input processing is done accordingly. However, some programs that simply report on minimum and maximum values or just do a reformatting of the data will in general not know what to expect, and furthermore there is no way for the programs to know what kind of data other columns (beyond the leading x and y columns) contain. In such instances we must explicitly tell GMT that we are feeding it data in the specific geographic or calendar formats (floating point data are assumed by default). We specify the data type via the -f option (which sets both input and output formats; use -fi and -fo to set input and output separately). For instance, to specify that the the first two columns are longitude and latitude, and that the third column (e.g., z) is absolute calendar time, we add -fi0x,1y,2T to the command line. For more details, see the man page for the program you need to use.

4.11 Output data formats

The numerical output from GMT programs can be binary (when -bo is used) or ASCII [Default]. In the latter case the issue of formatting becomes important. GMT provides extensive machinery for allowing just about any imaginable format to be used on output. Analogous to the processing of input data, several templates guide the formatting process. These are OUTPUT_DATE_FORMAT and OUTPUT_CLOCK_FORMAT for calendar-time coordinates, OUTPUT_DEGREE_FORMAT for geographical coordinates, and D_FORMAT for generic floating point data. In addition, the user have control over how columns are separated via the FIELD_SEPARATOR parameter. Thus, as an example, it is possible to create limited FORTRAN-style card records by setting D_FORMAT to %7.3lf and FIELD_SEPARATOR to none [Default is tab].

4.12 PostScript features

PostScript is a command language for driving graphics devices such as laser printers. It is ASCII text which you can read and edit as you wish (assuming you have some knowledge of the syntax). We prefer this to binary metafile plot systems since such files cannot easily be modified after they have been created. GMT programs also write many comments to the plot file which make it easier for users to orient themselves should they need to edit the file (e.g., % Start of x-axis). All GMT programs create PostScript code by calling the pslib plot library (The user may call these functions from his/her own C or FORTRAN plot programs. See the manual pages for pslib syntax). Although GMT programs can create very individualized plot code, there will always be cases not covered by these programs. Some knowledge of PostScript will enable the user to add such features directly into the plot file. By default, GMT will produce freeform PostScript output with embedded printer directives. To produce Encapsulated PostScript (EPS) that can be imported into graphics programs such as IslandDraw, CorelDraw, Illustrator or Freehand for further embellishment, change the PAPER_MEDIA setting in the .gmtdefaults4 file. See Appendix C and the gmtdefaults man page for more details.

4.13 Specifying pen attributes

A pen in GMT has three attributes: width, color, and texture. Most programs will accept pen attributes in the form of an option argument, with commas separating the given attributes, e.g.,

-W[width[c|i|p|m]],[color],[texture[c|i|p|m]]

Width is by default measured in units of the current device resolution (i.e., the value assigned to the parameter DOTS_PR_INCH in your .gmtdefaults4 file). Thus, if the dpi is set to 300 this unit is 1/300th of an inch. Append c, i, p, or m to specify pen width in cm, inch, points (1/72 of an inch), or meters, respectively. Note that a pen thickness of 5 will be of different physical width depending on your dpi setting, whereas a thickness of 5p will always be 5/72 of an inch. Minimum-thickness pens can be achieved by giving zero width, but the result is device-dependent. Finally, a few predefined pen names can be used: default, faint, and {thin, thick, fat}[er|est], and obese. Table 4.4 shows this list and the corresponding pen widths.






Pen name
Width
Pen name
Width




faint 0 thicker 1.5p




default 0.25pthickest 2p




thinnest 0.25pfat 3p




thinner 0.50pfatter 6p




thin 0.75pfattest 12p




thick 1.0p obese 18p





Table 4.4: GMT predefined pen widths.

The color can be specified in five different ways:
  1. Gray. Specify a gray shade in the range 0–255 (linearly going from black [0] to white [255]).
  2. RGB. Specify r/g/b, each ranging from 0–255. Here 0/0/0 is black, 255/255/255 is white, 255/0/0 is red, etc.
  3. HSV. Specify hue-saturation-value, with the former in the 0–360 degree range while the latter two take on the range 0–118.
  4. CMYK. Specify cyan/magenta/yellow/black, each ranging from 0–100%.
  5. Name. Specify one of 663 valid color names. Use man gmtcolors to list all valid names. A very small yet versatile subset consists of the 29 choices white, black, and [light|dark]{red, orange, yellow, green, cyan, blue, magenta, gray|grey, brown}. The color names are case-insensitive, so mixed upper and lower case can be used (like DarkGreen).
The texture attribute controls the appearance of the line. A “.” yields a dotted line, whereas a dashed pen is requested with “-”. Also combinations of dots and dashes, like “.-” for a dot-dashed line, are allowed. The lengths of dots and dashes are scaled relative to the pen width (dots has a length that equals the pen width while dashes are 8 times as long; gaps between segments are 4 times the pen width). For more detailed attributes including exact dimensions you may specify string:offset, where string is a series of numbers separated by underscores. These numbers represent a pattern by indicating the length of line segments and the gap between segments. The offset phase-shifts the pattern from the beginning the line. For example, if you want a yellow line of width 0.1 cm that alternates between long dashes (4 points), an 8 point gap, then a 5 point dash, then another 8 point gap, with pattern offset by 2 points from the origin, specify -W0.1c,yellow,4_8_5_8:2p. In general, the texture units can be specified in dpi units, cm, inch, points, or meters (see width discussion above).

Table 4.5 contains additional examples of pen specifications suitable for, say, psxy.




Pen example
Comment


-W0.5p Solid black line, 0.5 point thick


-Wgreen Solid green line with default width


-Wthin,red,- Dashed, thin red line


-Wfat,. Fat dotted line [black]


-W0.1c,120-1-1 Green (in h-s-v) pen, 1 mm thick


-Wfaint,100/0/0/0,..-Very thin, cyan (in c/m/y/k), dot-dot-dashed line



Table 4.5: A few examples of pen specifications.

4.14 Specifying area fill attributes

Many plotting programs will allow the user to draw filled polygons or symbols. The fill specification may take two forms:

-Gfill

-Gpdpi/pattern[:Bcolor[Fcolor]]

fill:
In the first case we may specify a gray shade (0–255), RGB color (r/g/b all in the 0–255 range or in hexadecimal #rrggbb), HSV color (hue-saturation-value in the 0–360, 0–1, 0–1 range), CMYK color (cyan/magenta/yellow/black, each ranging from 0–100%), or a valid color name; in that respect it is similar to specifying the pen color settings (see pen color discussion under Section 4.13).
pattern:
The second form allows us to use a predefined bit-image pattern. pattern can either be a number in the range 1–90 or the name of a 1-, 8-, or 24-bit Sun raster file. The former will result in one of the 90 predefined 64 x 64 bit-patterns provided with GMT and reproduced in Appendix E. The latter allows the user to create customized, repeating images using standard Sun raster files19. The dpi parameter sets the resolution of this image on the page; the area fill is thus made up of a series of these “tiles”. Specifying dpi as 0 will result in highest resolution obtainable given the present dpi setting in .gmtdefaults4. By specifying upper case -GP instead of -Gp the image will be bit-reversed, i.e., white and black areas will be interchanged (only applies to 1-bit images or predefined bit-image patterns). For these patterns and other 1-bit images one may specify alternative background and foreground colors (by appending :Bcolor[Fcolor]) that will replace the default white and black pixels, respectively. Setting one of the fore- or background colors to – yields a transparent image where only the back- or foreground pixels will be painted.

Due to PostScript implementation limitations the raster images used with -G must be less than 146 x 146 pixels in size; for larger images see psimage. The format of Sun raster files is outlined in Appendix B. Note that under PostScript Level 1 the patterns are filled by using the polygon as a clip path. Complex clip paths may require more memory than the PostScript interpreter has been assigned. There is therefore the possibility that some PostScript interpreters (especially those supplied with older laserwriters) will run out of memory and abort. Should that occur we recommend that you use a regular grayshade fill instead of the patterns. Installing more memory in your printer may or may not solve the problem!

Table 4.6 contains a few examples of fill specifications.




Fill example
Comment


-G128 Solid gray


-G127/255/0 Chartreuse, R/G/B-style


-G#00ff00 Green, hexadecimal RGB code


-G25-0.86-0.82 Chocolate, h-s-v – style


-GDarkOliveGreen1One of the named colors


-Gp300/7 Simple diagonal hachure pattern in b/w at 300 dpi


-Gp300/7:Bred Same, but with red lines on white


-Gp300/7:BredF- Now the gaps between red lines are transparent


-Gp100/marble.ras Using user image of marble as the fill at 100 dpi



Table 4.6: A few examples of fill specifications.

4.15 Color palette tables

Several programs, such as those which read 2-D gridded data sets and create colored images or shaded reliefs, need to be told what colors to use and over what z-range each color applies. This is the purpose of the color palette table (cpt-file). These files may also be used by psxy and psxyz to plot color-filled symbols. For most applications, you will simply create a cpt-file using the tool makecpt which will take an existing color table and resample it to fit your chosen data range, or use grd2cpt to build a cpt-file based on the data distribution in one or more given grid files. However, in some situations you will need to make a cpt-file by hand or using text tools like awk or perl.

Color palette tables (CPT) comes in two flavors: (1) Those designed to work with categorical data (e.g., data where interpolation of values is undefined) and (2) those designed for regular, continuously-varying data.

4.15.1 Categorical CPT files

Note: This is an experimental component and is only available if you compile GMT with -DGMT_CPT2. Categorical data are information on which normal numerical operations are not defined. As an example, consider various land classifications (desert, forest, glacier, etc.) and it is clear that even if we assigned a numerical value to these categories (e.g., desert = 1, forest = 2, etc) it would be meaningless to compute average values (what would 1.5 mean?). For such data a special format of the CPT files are provided. Here, each category is assigned a unique key, a color or pattern, and an optional label (usually the category name). Keys must be monotonically increasing but do not need to be consecutive. The format is

key1filllabel
keyn filllabel

The fill information follows the format given in Section 4.14. While not always applicable to categorical data, the background color (for key-values < key1), foreground color (for key-values > keyn), and not-a-number (NaN) color (for key-values = NaN) are all defined in the .gmtdefaults4 file, but can be overridden by the statements

BRbackGbackBback
F RforeGforeBfore
N RnanGnanBnan

4.15.2 Regular CPT files

Here, the colors may be specified either in the RGB- (red, green, blue), CMYK- (cyan, magenta, yellow, black), or in the HSV-system (hue, saturation, value, and here the comment # COLOR_MODEL = HSV must be present in the cpt file since there are no other way to distinguish between HSV and RGB). Color names can also be used. Using the RGB system20, the format of the cpt-file is:

z0RminGminBminz1RmaxGmaxBmax[A][;label]
zn-2 RminGminBminzn-1RmaxGmaxBmax[A][;label]

Thus, for each “z-slice”, defined as the interval between two boundaries (e.g., z0 to z1), the color can be constant (by letting Rmin = Rmax, Gmin = Gmax, and Bmin = Bmax) or a continuous, linear function of z. The optional flag A is used to indicate annotation of the color scale when plotted using psscale. The optional code A may be L, U, or B to select annotation of the lower, upper, or both limits of the particular z-slice. However, the standard -B option can be used by psscale to affect annotation and ticking of color scales. The optional semicolon followed by a text label will make psscale, when used with the -L option, place the supplied label instead of formatted z-values.

As for categorical tables, the background color (for z-values < z0), foreground color (for z-values > zn-1), and not-a-number (NaN) color (for z-values = NaN) are all defined in the .gmtdefaults4 file, but can be overridden by the statements

BRbackGbackBback
F RforeGforeBfore
N RnanGnanBnan

which can be inserted into the beginning or end of the cpt-file. If you prefer the HSV system, set the .gmtdefaults4 parameter accordingly and replace red, green, blue with hue, saturation, value. Color palette tables that contain grayshades only may replace the r/g/b triplets with a single grayshade in the 0–255 range. For CMYK, give four values in the 0–100 range. Both the min and max color specifications in one z-slice must use the same color system, i.e., you cannot mix “red” and 0/255/100 on the same line.

A few programs (i.e., those that plot polygons such as grdview, psscale, and psxy) can accept pattern fills instead of grayshades. You must specify the pattern as in Section 4.14 (no leading -G of course), and only the first (low z) is used (we cannot interpolate between patterns). Finally, some programs let you skip features whose z-slice in the cptfile has grayshades set to –. As an example, consider

30 p200/1680
80 100
100200 0 0 2002552550
200yellow 300green

where slice 30 < z < 80 is painted with pattern # 16 at 200 dpi, slice 80 < z < 100 is skipped, slice 100 < z < 200 is painted in a range of dark red to yellow, whereas the slice 200 < z < 300 will linearly yield colors from yellow to green, depending on the actual value of z.

Some programs like grdimage and grdview apply artificial illumination to achieve shaded relief maps. This is typically done by finding the directional gradient in the direction of the artificial light source and scaling the gradients to have approximately a normal distribution on the interval [-1,+1]. These intensities are used to add “white” or “black” to the color as defined by the z-values and the cpt-file. An intensity of zero leaves the color unchanged. Higher values will brighten the color, lower values will darken it, all without changing the original hue of the color (see Appendix I for more details). The illumination is decoupled from the data grid file in that a separate grid file holding intensities in the [-1,+1] range must be provided. Such intensity files can be derived from the data grid using grdgradient and modified with grdhisteq, but could equally well be a separate data set. E.g., some side-scan sonar systems collect both bathymetry and backscatter intensities, and one may want to use the latter information to specify the illumination of the colors defined by the former. Similarly, one could portray magnetic anomalies superimposed on topography by using the former for colors and the latter for shading.

4.16 Character escape sequences

For annotation labels or text strings plotted with pstext, GMT provides several escape sequences that allow the user to temporarily switch to the symbol font, turn on sub- or superscript, etc., within words. These conditions are toggled on/off by the escape sequence @x, where x can be one of several types. The escape sequences recognized in GMT are listed in Table 4.7. Only one level of sub- or superscript is supported. Note that under Windows the percent symbol indicates a batch variable, hence you must use two percent-signs for each one required in the escape sequence for font switching.




Code
Effect


Turns symbol font on or off


@+ Turns superscript on or off


@- Turns subscript on or off


@# Turns small caps on or off


@_ Turns underline on or off


@%fontno%Switches to another font; @%% resets to previous font


@:size: Switches to another font size; @:: resets to previous size


@;color; Switches to another font color; @;; resets to previous color


@! Creates one composite character of the next two characters


@@ Prints the @ sign itself



Table 4.7: GMT text escape sequences.

Shorthand notation for a few special European characters has also been added (Table 4.8):






CodeEffectCodeEffect




@E @e




@O @o




@A @a




@C @c




@N @n




@U @u




@s





Table 4.8: Shortcuts for some European characters.

PostScript fonts used in GMT may be re-encoded to include several accented characters used in many European languages. To access these, you must specify the full octal code \xxx allowed for your choice of character encodings determined by the CHAR_ENCODING setting described in the gmtdefaults man page. Only the special characters belonging to a particular encoding will be available. Many characters not directly available by using single octal codes may be constructed with the composite character mechanism @!.

Some examples of escape sequences and embedded octal codes in GMT strings using the Standard+ encoding:

2@~p@~r@+2@+h@-0@- E\363tv\363s = 2πr2h0 Etvs

10@+-3 @Angstr@om = 10-3 ngstrm

Se@nor Gar@con = Seor Garon

M@!\305anoa stra@se = Manoa strae

A@\#cceleration@\# (ms@+-2@+) = ACCELERATION (MS-2)

The option in pstext to draw a rectangle surrounding the text will not work for strings with escape sequences. A chart of characters and their octal codes is given in Appendix F.

4.17 Grid file format specifications

GMT has the ability to read and write grids using more than one grid file format (see Table 4.9 for supported format and their IDs). For reading, GMT will automatically determine the format of grid files, while for writing you will normally have to append =ID to the filename if you want GMT to use a different format than the default.

By default, GMT will create new grid files using the nf format; however, this behavior can be overridden by setting the GRID_FORMAT defaults parameter to any of the other recognized values (or by appending =ID).

GMT can also read netCDF grid files produced by other software packages, provided the grid files satisfy the COARDS and Hadley Centre conventions for netCDF grids. Thus, products created under those conventions (provided the grid is 2-, 3-, 4-, or 5-dimensional) can be read directly by GMT and the netCDF grids written by GMT can be read by other programs that conform to those conventions. Three such programs are ncview, Panoply and ncBrowse; others can be found on the netCDF website.

In addition, users with some C-programming experience may add their own read/write functions and link them with the GMT library to extend the number of predefined formats. Technical information on this topic can be found in the source file gmt_customio.c. Users who are considering this approach should contact the GMT team.




ID
GMT 4 netCDF standard formats




nb GMT netCDF format (byte) (COARDS-compliant)


ns GMT netCDF format (short) (COARDS-compliant)


ni GMT netCDF format (int) (COARDS-compliant)


nf GMT netCDF format (float) (COARDS-compliant)


nd GMT netCDF format (double) (COARDS-compliant)




ID
GMT 3 netCDF legacy formats




cb GMT netCDF format (byte) (depreciated)


cs GMT netCDF format (short) (depreciated)


ci GMT netCDF format (int) (depreciated)


cf GMT netCDF format (float) (depreciated)


cd GMT netCDF format (double) (depreciated)




ID
GMT native binary formats




bmGMT native, C-binary format (bit-mask)


bb GMT native, C-binary format (byte)


bs GMT native, C-binary format (short)


bi GMT native, C-binary format (int)


bf GMT native, C-binary format (float)


bd GMT native, C-binary format (double)




ID
Miscellaneous grid formats




rb SUN raster file format (8-bit standard)


rf GEODAS grid format GRD98 (NGDC)


sf Golden Software Surfer format 6 (float)


sd Golden Software Surfer format 7 (double)


af Atlantic Geoscience Center AGC (float)


gd Read-only via GDAL [EXPERIMENTAL] (float)



Table 4.9: GMT grid file formats.

Because some formats have limitations on the range of values they can store it is sometimes necessary to provide more than simply the name of the file and its ID on the command line. For instance, a native short integer file may use a unique value to signify an empty node or NaN, and the data may need translation and scaling prior to use. Therefore, all GMT programs that read or write grid files will decode the given filename as follows:

name[=ID[/scale/offset[/nan]]]

where everything in brackets is optional. If you are reading a grid then no options are needed: just continue to pass the name of the grid file. However, if you write another format you must append the =ID string, where ID is the format code listed above. In addition, should you want to (1) multiply the data by a scale factor, and (2) add a constant offset you must append the /scale/offset modifier. Finally, if you need to indicate that a certain data value should be interpreted as a NaN (not-a-number) you must append the /nan suffix to the scaling string (it cannot go by itself; note the nesting of the brackets!).

Some of the grid formats allow writing to standard output and reading from standard input which means you can connect GMT programs that operate on grid files with pipes, thereby speeding up execution and eliminating the need for large, intermediate grid files. You specify standard input/output by leaving out the filename entirely. That means the “filename” will begin with “=ID ” since no GMT netCDF format allow piping (due to the design of netCDF).

Everything looks clearer after a few examples:

  1. To write a native binary float grid file, specify the name as my_file.f4=bf.
  2. To read a native short integer grid file, multiply the data by 10 and then add 32000, but first let values that equal 32767 be set to NaN, use the filename my_file.i2=bs/10/32000/32767.
  3. To read a Golden Software “surfer” format 6 grid file, just pass the file name, e.g., my_surferfile.grd.
  4. To read a 8-bit standard Sun raster file (with values in the 0–255 range) and convert it to a 1 range, give the name as rasterfile=rb/7.84313725e-3/-1 (i.e., 1/127.5).
  5. To write a native binary short integer grid file to standard output after subtracting 32000 and dividing its values by 10, give filename as =bs/0.1/-3200.

Programs that both read and/or write more than one grid file may specify different formats and/or scaling for the files involved. The only restriction with the embedded grid specification mechanism is that no grid files may actually use the “=” character as part of their name (presumably, a small sacrifice).

One can also define special file suffixes to imply a specific file format; this approach represents a more intuitive and user-friendly way to specify the various file formats. The user may create a file called .gmt_io in the current directory, home directory or in the directory /̃.gmt and define any number of custom formats. The following is an example of a .gmt_io file:

# GMT i/o shorthand file

# It can have any number of comment lines like this one anywhere

# suffix format_id scale offset NaN Comments

grd nf - - - Default format

b bf - - - Native binary floats

i2 bs - - 32767 2-byte integers with NaN value

ras rb - - - Sun raster files

byte bb - - 255 Native binary 1-byte grids

bit bm - - - Native binary 0 or 1 grids

mask bm - - 0 Native binary 1 or NaN masks

faa bs 0.1 - 32767 Native binary gravity in 0.1 mGal

These suffices can be anything that makes sense to the user. To activate this mechanism, set parameter GRIDFILE_SHORTHAND to TRUE in your .gmtdefaults4 file. Then, using the filename stuff.i2 is equivalent to saying stuff.i2=bs/1/0/32767, and the filename wet.mask means wet.mask=bm/1/0/0. For a file intended for masking, i.e., the nodes are either 1 or NaN, the bit or mask format file may be as small as 1/32 the size of the corresponding grid float format file.

4.18 Options for COARDS-compliant netCDF files

When the netCDF file contains more than one 2-dimensional variable, GMT programs will load the first such variable in the file and ignore all others. Alternatively, the user can select the required variable by adding the suffix “?varname” to the file name. For example, to get information on the variable “slp” in file file.nc, use:

grdinfo ~file.nc?slp~

Since COARDS-compliant netCDF files are the default, the additional suffix “=nf” can be omitted.

In case the named variable is 3-dimensional, GMT will load the first (bottom) layer. If another layer is required, either add “[index]” or “(level)”, where index is the index of the third (depth) variable (starting at 0 for the first layer) and level is the numerical value of the third (depth) variable associated with the requested layer. To indicate the second layer of the 3-D variable “slp” use as file name: file.nc?slp[1].

When you supply the numerical value for the third variable using “(level)”, GMT will pick the layer closest to that value. No interpolation is performed.

Note that the question mark, brackets and parentheses have special meanings on Unix-based platforms. Therefore, you will need to either escape these characters, by placing a backslash in front of them, or place the whole file name plus modifiers between single quotes or double quotes.

A similar approach is followed for loading 4-dimensional grids. Consider a 4-dimensional grid with the following variables:

lat(lat): 0, 1, 2, 3, 4, 5, 6, 7, 8, 9  
lon(lon): 0, 1, 2, 3, 4, 5, 6, 7, 8, 9  
depth(depth): 0, 10, 20, 30, 40, 50, 60, 70, 80, 90  
time(time): 0, 12, 24, 36, 48  
pressure(time,depth,lat,lon): (5000 values)

To get information on the 10×10 grid of pressure at depth 10 and at time 24, one would use:

grdinfo ~file.nc?pressure[2,1]~

or (only in case the coordinates increase linearly):

grdinfo ~file.nc?pressure(24,10)~

The COARDS conventions set restrictions on the names that can be used for the units of the variables and coordinates. For example, the units of longitude and latitude are “degrees_east” and “degrees_north”, respectively. Here is an example of the header of a COARDS compliant netCDF file (to be obtained using ncdump):

netcdf M2_fes2004 {  
dimensions:  
        lon = 2881 ;  
        lat = 1441 ;  
variables:  
        float lon(lon) ;  
                lon:long_name = ~longitude~ ;  
                lon:units = ~degrees_east~ ;  
                lon:actual_range = 0., 360. ;  
        float lat(lat) ;  
                lat:long_name = ~latitude~ ;  
                lat:units = ~degrees_north~ ;  
                lat:actual_range = -90., 90. ;  
        short amp(lat, lon) ;  
                amp:long_name = ~amplitude~ ;  
                amp:unit = ~m~ ;  
                amp:scale_factor = 0.0001 ;  
                amp:add_offset = 3. ;  
                amp:_FillValue = -32768s ;  
        short pha(lat, lon) ;  
                pha:long_name = ~phase~ ;  
                pha:unit = ~degrees~ ;  
                pha:scale_factor = 0.01 ;  
                pha:_FillValue = -32768s ;

This file contains two grids, which can be plotted separately using the names M2_fes2004.nc?amp and M2_fes2004.nc?pha. The attributes long_name and unit for each variable are combined in GMT to a single unit string. For example, after reading the grid y_unit equals latitude [degrees_north]. The same method can be used in reverse to set the proper variable names and units when writing a grid. However, when the coordinates are set properly as geographical or time axes, GMT will take care of this. The user is, however, still responsible for setting the variable name and unit of the z-coordinate. The default is simply “z”.

4.19 The NaN data value

For a variety of data processing and plotting tasks there is a need to acknowledge that a data point is missing or unassigned. In the “old days” such information was passed by letting a value like -9999.99 take on the special meaning of “this is not really a value, it is missing”. The problem with this scheme is that -9999.99 (or any other floating point value) may be a perfectly reasonable data value and in such a scenario would be skipped. The solution adopted in GMT is to use the IEEE concept Not-a-Number (NaN) for this purpose. Mathematically, a NaN is what you get if you do an undefined mathematical operation like 00; in ASCII data files they appear as the textstring NaN. This value is internally stored with a particular bit pattern defined by IEEE so that special action can be taken when it is encountered by programs. In particular, a library function called isnan is used to test if a floating point is a NaN. GMT uses these tests extensively to determine if a value is suitable for plotting or processing (if a NaN is used in a calculation the result would become NaN as well). Data points whose values equal NaN are not normally plotted (or plotted with the special NaN color given in .gmtdefaults4). Several tools such as xyz2grd, gmtmath, and grdmath can convert user data to NaN and vice versa, thus facilitating arbitrary masking and clipping of data sets. Note that a few computers do not have native IEEE hardware support. At this point, this applies to some of the older Cray super-computers. Users on such machines may have to adopt the old ‘-9999.99” scheme to achieve the desired results.

Data records that contain NaN values for the x or y columns (or the z column for cases when 3-D Cartesian data are expected) are usually skipped during reading. However, the presence of these bad records can be interpreted in two different ways, and this behavior is controlled by the NAN_RECORDS defaults parameter. The default setting (gap) considers such records to indicate a gap in an otherwise continuous series of points (e.g., a line), and programs can act upon this information, e.g., not to draw a line across the gap or to break the line into separate segments. The alternative setting (bad) makes no such interpretation and simply reports back how many bad records were skipped during reading.

4.20 GMT environment parameters

GMT relies on several environment parameters, in particular to find data files and program settings.

$GMT_SHAREDIR
points to the GMT share directory where all run-time support files such as coastlines, custom symbols, PostScript macros, color tables, and much more reside. If this parameter is not set it defaults to the share sub-directory selected during the GMT install process (e.g., your answer to question C.9 on the web install form). If no selection was made the ultimate default is the share directory under the GMT installation directory.
$GMT_DATADIR
points to one or more directory where large and/or widely used data files can be placed. All GMT programs look in this directories when a file is specified on the command line and it is not present in the current directory. This allows maintainers to consolidate large data files and to simplify scripting that use these files since the absolute path need not be specified. Separate multiple directories with colons; under Windows you use semi-colons.
$GMT_USERDIR
points to a directory where the user may place custom configuration files (e.g., an alternate coastline.conf file, preferred default settings in .gmtdefaults4, custom symbols and color palettes, and shorthands for gridfile extensions via .gmt_io). Users may also place their own data files in this directory as GMT programs will search for files given on the command line in both $GMT_DATADIR and $GMT_USERDIR.
$GMT_TMPDIR
is where GMT will write its state parameters via the three files .gmtcommands4, .gmtdefaults4 and .gmt_bb_info. If not set then these files are written to the current directory. See Appendix P for more on the use of $GMT_TMPDIR.

Chapter 5
GMT Coordinate Transformations

GMT programs read real-world coordinates and convert them to positions on a plot. This is achieved by selecting one of several coordinate transformations or projections. We distinguish between three sets of such conversions:

The next chapter will be dedicated to GMT map projections in its entirety. Meanwhile, the present chapter will summarize the properties of the Cartesian and Polar coordinate transformations available in GMT, list which parameters define them, and demonstrate how they are used to create simple plot axes. We will mostly be using psbasemap (and occasionally psxy) to demonstrate the various transformations. Our illustrations may differ from those you reproduce with the same commands because of different settings in our .gmtdefaults4 file.) Finally, note that while we will specify dimensions in inches (by appending i), you may want to use cm (c), meters (m), or points (p) as unit instead (see the gmtdefaults man page).

5.1 Cartesian transformations

GMT Cartesian coordinate transformations come in three flavors:

These transformations convert input coordinates (x,y) to locations (x,y) on a plot. There is no coupling between x and y (i.e., x = f(x) and y = f(y)); it is a one-dimensional projection. Hence, we may use separate transformations for the x- and y-axes (and z-axes for 3-D plots). Below, we will use the expression u = f(u), where u is either x or y (or z for 3-D plots). The coefficients in f(u) depend on the desired plot size (or scale), the chosen (x,y) domain, and the nature of f itself.

Two subsets of linear will be discussed separately; these are a polar (cylindrical) projection and a linear projection applied to geographic coordinates (with a 360 periodicity in the x-coordinate). We will show examples of all of these projections using dummy data sets created with gmtmath, a “Reverse Polish Notation” (RPN) calculator that operates on or creates table data:

_________________________________________________________________________________

5.1.1 Cartesian linear transformation (-Jx-JX)

There are in fact three different uses of the Cartesian linear transformation, each associated with specific command line options. The different manifestations result from specific properties of three kinds of data:

  1. Regular floating point coordinates
  2. Geographic coordinates
  3. Calendar time coordinates

Regular floating point coordinates

Selection of the Cartesian linear transformation with regular floating point coordinates will result in a simple linear scaling u = au+b of the input coordinates. The projection is defined by stating

If the y-scale or y-axis length is different from that of the x-axis (which is most often the case), separate the two scales (or lengths) by a slash, e.g., -Jx0.1i/0.5i or -JX8i/5i. Thus, our y = x data sets will plot as shown in Figure 5.1.


PIC

Figure 5.1: Linear transformation of Cartesian coordinates.

The complete commands given to produce this plot were

_________________________________________________________________________________

psxy -R0/100/0/10 -JX3i/1.5i -Ba20f10g10/a2f1g2WSne -Wthick,- -P -K sqrt.d > GMT_linear.ps  
psxy -R -J -St0.075i -Glightgray -W -O sqrt.d10 >> GMT_linear.ps
__________________________________________________________________________________________________

Normally, the user’s x-values will increase to the right and the y-values will increase upwards. It should be noted that in many situations it is desirable to have the direction of positive coordinates be reversed. For example, when plotting depth on the y-axis it makes more sense to have the positive direction downwards. All that is required to reverse the sense of positive direction is to supply a negative scale (or axis length). Finally, sometimes it is convenient to specify the width (or height) of a map and let the other dimension be computed based on the implied scale and the range of the other axis. To do this, simply specify the length to be recomputed as 0.

Geographic coordinates

PIC

Figure 5.2: Linear transformation of map coordinates.

While the Cartesian linear projection is primarily designed for regular floating point x,y data, it is sometimes necessary to plot geographical data in a linear projection. This poses a problem since longitudes have a 360 periodicity. GMT therefore needs to be informed that it has been given geographical coordinates even though a linear transformation has been chosen. We do so by adding a g (for geographical) or d (for degrees) directly after -R or by appending a g or d to the end of the -Jx (or -JX) option. As an example, we want to plot a crude world map centered on 125E. Our command will be

_________________________________________________________________________________

gmtset GRID_CROSS_SIZE_PRIMARY 0.1i BASEMAP_TYPE FANCY PLOT_DEGREE_FORMAT ddd:mm:ssF  
pscoast -Rg-55/305/-90/90 -Jx0.014i -B60g30f15/30g30f15WSen -Dc -A1000 -Glightgray -Wthinnest -P \  
        > GMT_linear_d.ps
__________________________________________________________________________________________________

with the result reproduced in Figure 5.2.

Calendar time coordinates

PIC

Figure 5.3: Linear transformation of calendar coordinates.

Several particular issues arise when we seek to make linear plots using calendar date/time as the input coordinates. As far as setting up the coordinate transformation we must indicate whether our input data have absolute time coordinates or relative time coordinates. For the former we append T after the axis scale (or width), while for the latter we append t at the end of the -Jx (or -JX) option. However, other command line arguments (like the -R option) may already specify whether the time coordinate is absolute or relative. An absolute time entry must be given as [date]T[clock] (with date given as yyyy[-mm[-dd]], yyyy[-jjj], or yyyy[-Www[-d]], and clock using the hh[:mm[:ss[.xxx]]] 24-hour clock format) whereas the relative time is simply given as the units of time since the epoch followed by t (see TIME_UNIT and TIME_EPOCH for information on specifying the time unit and the epoch). As a simple example, we will make a plot of a school week calendar (Figure 5.3).

_________________________________________________________________________________

gmtset PLOT_DATE_FORMAT o TIME_WEEK_START Sunday PLOT_CLOCK_FORMAT -hham TIME_FORMAT_PRIMARY full  
psbasemap -R2001-9-24T/2001-09-29T/T06:59:59/T15:00:01 -JX4i/-2i -Ba1Kf1kg1d/a1Hg1hWsNe -P > GMT_linear_cal.ps
__________________________________________________________________________________________________

When the coordinate ranges provided by the -R option and the projection type given by -JX (including the optional d, g, t or T) conflict, GMT will warn the users about it. In general, the options provided with -JX will prevail.

5.1.2 Cartesian logarithmic projection


PIC

Figure 5.4: Logarithmic transformation of x-coordinates.

The log10 transformation is simply u = alog10(u)+b and is selected by appending an l (lower case L) immediately following the scale (or axis length) value. Hence, to produce a plot in which the x-axis is logarithmic (the y-axis remains linear, i.e., a semi-log plot), try

_________________________________________________________________________________

psxy -R1/100/0/10 -Jx1.5il/0.15i -B2g3/a2f1g2WSne -Wthick,- -P -K -H sqrt.d > GMT_log.ps  
psxy -R -J -Ss0.075i -Gblack -W -O -H sqrt.d10 >> GMT_log.ps
__________________________________________________________________________________________________

Note that if x- and y-scaling are different and a log10-log10 plot is desired, the l must be appended twice: Once after the x-scale (before the /) and once after the y-scale.

5.1.3 Cartesian power projection


PIC

Figure 5.5: Exponential or power transformation of x-coordinates.

This projection uses u = aub+c and allows us to explore exponential relationships like xp versus yq. While p and q can be any values, we will select p = 0.5 and q = 1 which means we will plot x versus x. We indicate this scaling by appending a p (lower case P) followed by the desired exponent, in our case 0.5. Since q = 1 we do not need to specify p1 since it is identical to the linear transformation. Thus our command becomes

_________________________________________________________________________________

psxy -R0/100/0/10 -Jx0.3ip0.5/0.15i -Ba1p/a2f1WSne -Wthick -P -K sqrt.d > GMT_pow.ps  
psxy -R -J -Sc0.075i -Gwhite -W -O sqrt.d10 >> GMT_pow.ps
_________________________________________________________________________________________________

5.2 Linear projection with polar (θ,r) coordinates (-Jp -JP)


PIC

Figure 5.6: Polar (Cylindrical) transformation of (θ,r) coordinates.

This transformation converts polar coordinates (angle θ and radius r) to positions on a plot. Now x = f(θ,r) and y = g(θ,r), hence it is similar to a regular map projection because x and y are coupled and x (i.e., θ) has a 360 periodicity. With input and output points both in the plane it is a two-dimensional projection. The transformation comes in two flavors:

  1. Normally, θ is understood to be directions counter-clockwise from the horizontal axis, but we may choose to specify an angular offset [whose default value is zero]. We will call this offset θ0. Then, x = f(θ,r) = arcos(θ -θ0)+b and y = g(θ,r) = arsin(θ -θ0)+c.
  2. Alternatively, θ can be interpreted to be azimuths clockwise from the vertical axis, yet we may again choose to specify the angular offset [whose default value is zero]. Then, x = f(θ,r) = arcos(90-(θ -θ0))+b and y = g(θ,r) = arsin(90-(θ -θ0))+c.

Consequently, the polar transformation is defined by providing

As an example of this projection we will create a gridded data set in polar coordinates z(θ,r) = r2 cos4θ using grdmath, a RPN calculator that operates on or creates grid files.

_________________________________________________________________________________

grdmath -R0/360/2/4 -I6/0.1 X 4 MUL PI MUL 180 DIV COS Y 2 POW MUL = $$.nc  
grdcontour $$.nc -JP3i -B30Ns -P -C2 -S4 --PLOT_DEGREE_FORMAT=+ddd > GMT_polar.ps  
rm -f $$.nc
__________________________________________________________________________________________________

We used grdcontour to make a contour map of this data. Because the data file only contains values with 2 r 4, a donut shaped plot appears in Figure 5.6

Chapter 6
GMT Map Projections

GMT implements more than 30 different projections. They all project the input coordinates longitude and latitude to positions on a map. In general, x = f(x,y,z) and y = g(x,y,z), where z is implicitly given as the radial vector length to the (x,y) point on the chosen ellipsoid. The functions f and g can be quite nasty and we will refrain from presenting details in this document. The interested read is referred to Snyder [1987]21. We will mostly be using the pscoast command to demonstrate each of the projections.