gmt - The Generic Mapping Tools data processing and display software package
GMT is a collection of public-domain Unix tools that allows you to manipulate x,y and x,y,z data sets (filtering, trend fitting, gridding, projecting, etc.) and produce PostScript illustrations ranging from simple x-y plots, via contour maps, to artificially illuminated surfaces and 3-D perspective views in black/white or full color. Linear, log10, and power scaling is supported in addition to over 30 common map projections. The processing and display routines within GMT are completely general and will handle any (x,y) or (x,y,z) data as input.
gmt is the main program that can start any of the modules:
gmt module module-options
where module is the name of a GMT module and the options are those that pertain to that particular module. If no module is given then several other options are available:
GMT provides basic command-line completion (tab completion) for bash. The completion rules are either installed in /etc/bash_completion.d/gmt or <prefix>/share/tools/gmt_completion.bash. Depending on the distribution, you may still need to source the gmt completion file from ~/.bash_completion or ~/.bashrc. For more information see Section Command-line completion in the CookBook.
The following is a summary of all the programs supplied with GMT and a very short description of their purpose. Detailed information about each program can be found in the separate manual pages.
blockmean | |
blockmedian | |
blockmode | |
filter1d | |
fitcircle | |
gmt2kml | |
gmtconnect | |
gmtconvert | |
gmtdefaults | |
gmtget | |
gmtinfo | |
gmtmath | |
gmtselect | |
gmtset | |
gmtspatial | |
gmtsimplify | |
gmtvector | |
gmtwhich | |
grd2cpt | |
grd2rgb | |
grd2xyz | |
grdblend | |
grdclip | |
grdcontour | |
grdconvert | |
grdcut | |
grdedit | |
grdfft | |
grdfilter | |
grdgradient | |
grdhisteq | |
grdimage | |
grdinfo | |
grdlandmask | |
grdmask | |
grdmath | |
grdpaste | |
grdproject | |
grdraster | |
grdsample | |
grdtrack | |
grdtrend | |
grdvector | |
grdview | |
grdvolume | |
greenspline | |
kml2gmt | |
makecpt | |
mapproject | |
nearneighbor | |
project | |
psbasemap | |
psclip | |
pscoast | |
pscontour | |
psconvert | |
pshistogram | |
psimage | |
pslegend | |
psmask | |
psrose | |
psscale | |
pstext | |
pswiggle | |
psxy | |
psxyz | |
sample1d | |
spectrum1d | |
splitxyz | |
surface | |
trend1d | |
trend2d | |
triangulate | |
xyz2grd | |
Supplement gshhg: | |
gshhg | |
Supplement img: | |
img2grd | |
Supplement meca: | |
pscoupe | |
psmeca | |
pspolar | |
psvelo | |
Supplement mgd77: | |
mgd77convert | |
mgd77info | |
mgd77list | |
mgd77magref | |
mgd77manage | |
mgd77path | |
mgd77sniffer | |
mgd77track | |
Supplement potential: | |
gmtgravmag3d | |
gmtflexure | |
gravfft | |
grdflexure | |
grdgravmag3d | |
grdredpol | |
grdseamount | |
talwani2d | |
talwani3d | |
Supplement segy: | |
pssegy | |
pssegyz | |
segy2grd | |
Supplement sph: | |
sphdistance | |
sphinterpolate | |
sphtriangulate | |
Supplement spotter: | |
backtracker | |
grdpmodeler | |
grdrotater | |
grdspotter | |
hotspotter | |
originator | |
rotconverter | |
Supplement x2sys: | |
x2sys_binlist | |
x2sys_cross | |
x2sys_datalist | |
x2sys_get | |
x2sys_init | |
x2sys_list | |
x2sys_merge | |
x2sys_put | |
x2sys_report | |
x2sys_solve |
The gmt program can also load custom modules from shared libraries built as specified in the GMT API documentation. This way your modules can benefit form the GMT infrastructure and extend GMT in specific ways.
-B[p|s]parameters -Jparameters -Jz|Zparameters -K -O -P -Rwest/east/south/north[/zmin/zmax][r] -U[just/dx/dy/][c|label] -V[level] -Xx_offset -Yy_offset -a<flags> -b<binary> -d<nodata> -f<flags> -g<gaps> -h<headers> -i<flags> -n<flags> -o<flags> -p<flags> -r -s<flags> -t<transp> -x[[-]n] -:[i|o]
These are all the common GMT options that remain the same for all GMT programs. No space between the option flag and the associated arguments.
Set map Frame and Axes parameters. The Frame parameters are specified by
-B[axes][+b][+gfill][+n][+olon/lat][+ttitle]
where axes selects which axes to plot. By default, all 4 map boundaries (or plot axes) are plotted (named W, E, S, N). To customize, append the codes for those you want (e.g., WSn). Upper case means plot and annotate while lower case just plots the specified axes. If a 3-D basemap is selected with -p and -Jz, append Z or z to control the appearance of the vertical axis. By default a single vertical axes will be plotted at the most suitable map corner. Override the default by appending any combination of corner ids 1234, where 1 represents the lower left corner and the order goes counter-clockwise. Append +b to draw the outline of the 3-D cube defined by -R; this modifier is also needed to display gridlines in the x-z, y-z planes. Note that for 3-D views the title, if given, will be suppressed. You can paint the interior of the canvas with +gfill. Append +n to have no frame and annotations at all [Default is controlled by the codes]. Optionally append +oplon/plat to draw oblique gridlines about specified pole [regular gridlines]. Ignored if gridlines are not requested (below) and disallowed for the oblique Mercator projection. To add a plot title (+ttitle). The Frame setting is optional but can be invoked once to override the above defaults.
The Axes parameters are specified by
-B[p|s][x|y|z]intervals[+l|Llabel][+pprefix][+uunit]
but you may also split this into two separate invocations for clarity, i.e.,
-B[p|s][x|y|z][+llabel][+pprefix][+uunit]
-B[p|s][x|y|z]intervals
The first optional flag following -B selects p (rimary) [Default] or s (econdary) axes information (mostly used for time axes annotations). The [x|y|z] flags specify which axes you are providing information for. If none are given then we default to xy. If you wish to give different annotation intervals or labels for the various axes then you must repeat the B option for each axis (If a 3-D basemap is selected with -p and -Jz, use -Bz to give settings for the vertical axis.). To add a label to an axis, just append +llabel (Cartesian projections only). Use +L to force a horizontal label for y-axes (useful for very short labels). If the axis annotation should have a leading text prefix (e.g., dollar sign for those plots of your net worth) you can append +pprefix. For geographic maps the addition of degree symbols, etc. is automatic (and controlled by the GMT default setting FORMAT_GEO_MAP). However, for other plots you can add specific units by adding +uunit. If any of these text strings contain spaces or special UNIX characters you will need to enclose them in quotes. The intervals specification is a concatenated string made up of substrings of the form
[a|f|g]stride[+-phase][u].
The leading a is used to specify the annotation and major tick spacing [Default], f for minor tick spacing, and g for gridline spacing. stride is the desired stride interval. The optional phase shifts the annotation interval by that amount (positive or negative). The optional unit indicates the unit of the stride and can be any of
Note for geographic axes m and s instead mean arc minutes and arc seconds. All entities that are language-specific are under control by GMT_LANGUAGE. Alternatively, for linear maps, we can omit stride, thus setting xinfo, yinfo, or zinfo to a plots annotations at automatically determined intervals,
For custom annotations and intervals, let intervals be given as
cintfile, where intfile contains any number of
records with coord type [label]. Here, type is one or more
letters from a|i, f, and g. For
a|i you must supply a label that will be plotted at
the coord location.
For non-geographical projections: Give negative scale (in -Jx)
or axis length (in -JX) to change the direction of increasing
coordinates (i.e., to make the y-axis positive down).
For log10 axes: Annotations can be specified in one of three ways:
For power axes: Annotations can be specified in one of two ways:
These GMT parameters can affect the appearance of the map boundary: MAP_ANNOT_MIN_ANGLE, MAP_ANNOT_MIN_SPACING, FONT_ANNOT_PRIMARY, FONT_ANNOT_SECONDARY, MAP_ANNOT_OFFSET_PRIMARY, MAP_ANNOT_OFFSET_SECONDARY, MAP_ANNOT_ORTHO, MAP_FRAME_AXES, MAP_DEFAULT_PEN, MAP_FRAME_TYPE, FORMAT_GEO_MAP, MAP_FRAME_PEN, MAP_FRAME_WIDTH, MAP_GRID_CROSS_SIZE_PRIMARY, MAP_GRID_PEN_PRIMARY, MAP_GRID_CROSS_SIZE_SECONDARY, MAP_GRID_PEN_SECONDARY, FONT_TITLE, FONT_LABEL, MAP_LINE_STEP, MAP_ANNOT_OBLIQUE, FORMAT_CLOCK_MAP, FORMAT_DATE_MAP, FORMAT_TIME_PRIMARY_MAP, FORMAT_TIME_SECONDARY_MAP, GMT_LANGUAGE, TIME_WEEK_START, MAP_TICK_LENGTH_PRIMARY, and MAP_TICK_PEN_PRIMARY; see the gmt.conf man page for details.
-Jparameters
Select map projection. The following character determines the projection. If the character is upper case then the argument(s) supplied as scale(s) is interpreted to be the map width (or axis lengths), else the scale argument(s) is the map scale (see its definition for each projection). UNIT is cm, inch, or point, depending on the PROJ_LENGTH_UNIT setting in gmt.conf, but this can be overridden on the command line by appending c, i, or p to the scale or width values. Append h, +, or - to the given width if you instead want to set map height, the maximum dimension, or the minimum dimension, respectively [Default is w for width]. In case the central meridian is an optional parameter and it is being omitted, then the center of the longitude range given by the -R option is used. The default standard parallel is the equator. The ellipsoid used in the map projections is user-definable by editing the gmt.conf file in your home directory. 73 commonly used ellipsoids and spheroids are currently supported, and users may also specify their own custom ellipsoid parameters [Default is WGS-84]. Several GMT parameters can affect the projection: PROJ_ELLIPSOID, GMT_INTERPOLANT, PROJ_SCALE_FACTOR, and PROJ_LENGTH_UNIT; see the gmt.conf man page for details. Choose one of the following projections (The E or C after projection names stands for Equal-Area and Conformal, respectively):
CYLINDRICAL PROJECTIONS:
-Jclon0/lat0/scale or -JClon0/lat0/width (Cassini).
Give projection center lon0/lat0 and scale (1:xxxx or UNIT/degree).
-Jcyl_stere/[lon0/[lat0/]]scale or -JCyl_stere/[lon0/[lat0/]]width (Cylindrical Stereographic).
Give central meridian lon0 (optional), standard parallel lat0 (optional), and scale along parallel (1:xxxx or UNIT/degree). The standard parallel is typically one of these (but can be any value):
- 66.159467 - Miller’s modified Gall
- 55 - Kamenetskiy’s First
- 45 - Gall’s Stereographic
- 30 - Bolshoi Sovietskii Atlas Mira or Kamenetskiy’s Second
- 0 - Braun’s Cylindrical
-Jj[lon0/]scale or -JJ[lon0/]width (Miller Cylindrical Projection).
Give the central meridian lon0 (optional) and scale (1:xxxx or UNIT/degree).
-Jm[lon0/[lat0/]]scale or -JM[lon0/[lat0/]]width (Mercator [C])
Give central meridian lon0 (optional), standard parallel lat0 (optional), and scale along parallel (1:xxxx or UNIT/degree).
-Joparameters (Oblique Mercator [C]).
Typically used with -RLLx/LLy/URx/URyr or with projected coordinates. Specify one of:
- -Jo[a|A]lon0/lat0/azimuth/scale or -JO[a|A]lon0/lat0/azimuth/width
- Set projection center lon0/lat0, azimuth of oblique equator, and scale.
- -Jo[b|B]lon0/lat0/lon1/lat1/scale or -JO[b|B]lon0/lat0/lon1/lat1/scale
- Set projection center lon0/lat0, another point on the oblique equator lon1/lat1, and scale.
- -Joc|Clon0/lat0/lonp/latp/scale or -JOc|Clon0/lat0/lonp/latp/scale
- Set projection center lon0/lat0, pole of oblique projection lonp/latp, and scale. Give scale along oblique equator (1:xxxx or UNIT/degree). The upper-case A|B|C to removes enforcement of a northern hemisphere pole.
-Jq[lon0/[lat0/]]scale or -JQ[lon0/[lat0/]]width (Cylindrical Equidistant).
Give the central meridian lon0 (optional), standard parallel lat0 (optional), and scale (1:xxxx or UNIT/degree). The standard parallel is typically one of these (but can be any value):
- 61.7 - Grafarend and Niermann, minimum linear distortion
- 50.5 - Ronald Miller Equirectangular
- 43.5 - Ronald Miller, minimum continental distortion
- 42 - Grafarend and Niermann
- 37.5 - Ronald Miller, minimum overall distortion
- 0 - Plate Carree, Simple Cylindrical, Plain/Plane Chart
-Jtlon0/[lat0/]scale or -JTlon0/[lat0/]width (Transverse Mercator [C])
Give the central meridian lon0, central parallel lat0 (optional), and scale (1:xxxx or UNIT/degree).
-Juzone/scale or -JUzone/width (UTM - Universal Transverse Mercator [C]).
Give the UTM zone (A,B,1-60[C-X],Y,Z)) and scale (1:xxxx or UNIT/degree). Zones: If C-X not given, prepend - or + to enforce southern or northern hemisphere conventions [northern if south > 0].
-Jy[lon0/[lat0/]]scale or -JY[lon0/[lat0/]]width (Cylindrical Equal-Area [E]).
Give the central meridian lon0 (optional), standard parallel lat0 (optional), and scale (1:xxxx or UNIT/degree). The standard parallel is typically one of these (but can be any value):
- 50 - Balthasart
- 45 - Gall-Peters
- 37.0666 - Caster
- 37.4 - Trystan Edwards
- 37.5 - Hobo-Dyer
- 30 - Behrman
- 0 - Lambert (default)
CONIC PROJECTIONS:
- -Jblon0/lat0/lat1/lat2/scale or -JBlon0/lat0/lat1/lat2/width (Albers [E]).
- Give projection center lon0/lat0, two standard parallels lat1/lat2, and scale (1:xxxx or UNIT/degree).
- -Jdlon0/lat0/lat1/lat2/scale or -JDlon0/lat0/lat1/lat2/width (Conic Equidistant)
- Give projection center lon0/lat0, two standard parallels lat1/lat2, and scale (1:xxxx or UNIT/degree).
- -Jllon0/lat0/lat1/lat2/scale or -JLlon0/lat0/lat1/lat2/width (Lambert [C])
- Give origin lon0/lat0, two standard parallels lat1/lat2, and scale along these (1:xxxx or UNIT/degree).
- -Jpoly/[lon0/[lat0/]]scale or -JPoly/[lon0/[lat0/]]width ((American) Polyconic).
- Give the central meridian lon0 (optional), reference parallel lat0 (optional, default = equator), and scale along central meridian (1:xxxx or UNIT/degree).
AZIMUTHAL PROJECTIONS:
Except for polar aspects, -Rw/e/s/n will be reset to -Rg. Use -R<...>r for smaller regions.
- -Jalon0/lat0[/horizon]/scale or -JAlon0/lat0[/horizon]/width (Lambert [E]).
- lon0/lat0 specifies the projection center. horizon specifies the max distance from projection center (in degrees, <= 180, default 90). Give scale as 1:xxxx or radius/lat, where radius is distance in UNIT from origin to the oblique latitude lat.
- -Jelon0/lat0[/horizon]/scale or -JElon0/lat0[/horizon]/width (Azimuthal Equidistant).
- lon0/lat0 specifies the projection center. horizon specifies the max distance from projection center (in degrees, <= 180, default 180). Give scale as 1:xxxx or radius/lat, where radius is distance in UNIT from origin to the oblique latitude lat.
- -Jflon0/lat0[/horizon]/scale or -JFlon0/lat0[/horizon]/width (Gnomonic).
- lon0/lat0 specifies the projection center. horizon specifies the max distance from projection center (in degrees, < 90, default 60). Give scale as 1:xxxx or radius/lat, where radius is distance in UNIT from origin to the oblique latitude lat.
- -Jglon0/lat0[/horizon]/scale or -JGlon0/lat0[/horizon]/width (Orthographic).
- lon0/lat0 specifies the projection center. horizon specifies the max distance from projection center (in degrees, <= 90, default 90). Give scale as 1:xxxx or radius/lat, where radius is distance in UNIT from origin to the oblique latitude lat.
- -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale or -JGlon0/lat0/altitude/azimuth/tilt/twist/Width/Height/width (General Perspective).
- lon0/lat0 specifies the projection center. altitude is the height (in km) of the viewpoint above local sea level. If altitude is less than 10, then it is the distance from the center of the earth to the viewpoint in earth radii. If altitude has a suffix r then it is the radius from the center of the earth in kilometers. azimuth is measured to the east of north of view. tilt is the upward tilt of the plane of projection. If tilt is negative, then the viewpoint is centered on the horizon. Further, specify the clockwise twist, Width, and Height of the viewpoint in degrees. Give scale as 1:xxxx or radius/lat, where radius is distance in UNIT from origin to the oblique latitude lat.
- -Jslon0/lat0[/horizon]/scale or -JSlon0/lat0[/horizon]/width (General Stereographic [C]).
- lon0/lat0 specifies the projection center. horizon specifies the max distance from projection center (in degrees, < 180, default 90). Give scale as 1:xxxx (true at pole) or lat0/1:xxxx (true at standard parallel lat) or radius/lat (radius in UNIT from origin to the oblique latitude lat). Note if 1:xxxx is used then to specify horizon you must also specify the lat as +-90 to avoid ambiguity.
MISCELLANEOUS PROJECTIONS:
- -Jh[lon0/]scale or -JH[lon0/]width (Hammer [E]).
- Give the central meridian lon0 (optional) and scale along equator (1:xxxx or UNIT/degree).
- -Ji[lon0/]scale or -JI[lon0/]width (Sinusoidal [E]).
- Give the central meridian lon0 (optional) and scale along equator (1:xxxx or UNIT/degree).
- -Jkf[lon0/]scale or -JKf[lon0/]width (Eckert IV) [E]).
- Give the central meridian lon0 (optional) and scale along equator (1:xxxx or UNIT/degree).
- -Jk[s][lon0/]scale or -JK[s][lon0/]width (Eckert VI) [E]).
- Give the central meridian lon0 (optional) and scale along equator (1:xxxx or UNIT/degree).
- -Jn[lon0/]scale or -JN[lon0/]width (Robinson).
- Give the central meridian lon0 (optional) and scale along equator (1:xxxx or UNIT/degree).
- -Jr[lon0/]scale -JR[lon0/]width (Winkel Tripel).
- Give the central meridian lon0 (optional) and scale along equator (1:xxxx or UNIT/degree).
- -Jv[lon0/]scale or -JV[lon0/]width (Van der Grinten).
- Give the central meridian lon0 (optional) and scale along equator (1:xxxx or UNIT/degree).
- -Jw[lon0/]scale or -JW[lon0/]width (Mollweide [E]).
- Give the central meridian lon0 (optional) and scale along equator (1:xxxx or UNIT/degree).
NON-GEOGRAPHICAL PROJECTIONS:
-Jp[a]scale[/origin][r|z] or -JP[a]width[/origin][r|z] (Polar coordinates (theta,r))
Optionally insert a after -Jp [ or -JP] for azimuths CW from North instead of directions CCW from East [Default]. Optionally append /origin in degrees to indicate an angular offset [0]). Finally, append r if r is elevations in degrees (requires s >= 0 and n <= 90) or z if you want to annotate depth rather than radius [Default]. Give scale in UNIT/r-unit.
-Jxx-scale[/y-scale] or -JXwidth[/height] (Linear, log, and power scaling)
Give x-scale (1:xxxx or UNIT/x-unit) and/or y-scale (1:xxxx or UNIT/y-unit); or specify width and/or height in UNIT. y-scale=x-scale if not specified separately and using 1:xxxx implies that x-unit and y-unit are in meters. Use negative scale(s) to reverse the direction of an axis (e.g., to have y be positive down). Set height or width to 0 to have it recomputed based on the implied scale of the other axis. Optionally, append to x-scale, y-scale, width or height one of the following:
- d
- Data are geographical coordinates (in degrees).
- l
- Take log10 of values before scaling.
- ppower
- Raise values to power before scaling.
- t
- Input coordinates are time relative to TIME_EPOCH.
- T
- Input coordinates are absolute time.
Default axis lengths (see gmt.conf) can be invoked using -JXh (for landscape); -JXv (for portrait) will swap the x- and y-axis lengths. The default unit for this installation is either cm or inch, as defined in the file share/gmt.conf. However, you may change this by editing your gmt.conf file(s).
When -J is used without any further arguments, or just with the projection type, the arguments of the last used -J, or the last used -J with that projection type, will be used.
In case of perspective view p, a z-range (zmin, zmax) can be appended to indicate the third dimension. This needs to be done only when using the Jz option, not when using only the p option. In the latter case a perspective view of the plane is plotted, with no third dimension.
-X[a|c|f|r][x-shift[u]]
The attributes of text fonts as defined by font is a comma delimited list of size, fonttype and fill, each of which is optional. size is the font size (usually in points) but c or i can be added to indicate other units. fonttype is the name (case sensitive!) of the font or its equivalent numerical ID (e.g., Helvetica-Bold or 1). fill specifies the gray shade, color or pattern of the text (see Specifying Fill above). Optionally, you may append =pen to the fill value in order to draw a text outline. If you want to avoid that the outline partially obscures the text, append append =~pen instead; in that case only half the linewidth is plotted on the outside of the font only. If an outline is requested, you may optionally skip the text fill by setting it to -, in which case the full pen width is always used. If any of the font attributes is omitted their default or previous setting will be retained.
The 35 available fonts are:
The ASCII output formats of numerical data are controlled by parameters in your gmt.conf file. Longitude and latitude are formatted according to FORMAT_GEO_OUT, whereas other values are formatted according to FORMAT_FLOAT_OUT. Be aware that the format in effect can lead to loss of precision in the output, which can lead to various problems downstream. If you find the output is not written with enough precision, consider switching to binary output (-bo if available) or specify more decimals using the FORMAT_FLOAT_OUT setting.
By default GMT writes out grid as single precision floats in a COARDS-complaint netCDF file format. However, GMT is able to produce grid files in many other commonly used grid file formats and also facilitates so called “packing” of grids, writing out floating point data as 1- or 2-byte integers. To specify the precision, scale and offset, the user should add the suffix =id[/scale/offset[/nan]], where id is a two-letter identifier of the grid type and precision, and scale and offset are optional scale factor and offset to be applied to all grid values, and nan is the value used to indicate missing data. In case the two characters id is not provided, as in =/scale than a id=nf is assumed. When reading grids, the format is generally automatically recognized. If not, the same suffix can be added to input grid file names. See grdconvert and Section Grid file format specifications of the GMT Technical Reference and Cookbook for more information.
When reading a netCDF file that contains multiple grids, GMT will read, by default, the first 2-dimensional grid that can find in that file. To coax GMT into reading another multi-dimensional variable in the grid file, append ?varname to the file name, where varname is the name of the variable. Note that you may need to escape the special meaning of ? in your shell program by putting a backslash in front of it, or by placing the filename and suffix between quotes or double quotes. The ?varname suffix can also be used for output grids to specify a variable name different from the default: “z”. See grdconvert and Sections Modifiers for COARDS-compliant netCDF files and Grid file format specifications of the GMT Technical Reference and Cookbook for more information, particularly on how to read splices of 3-, 4-, or 5-dimensional grids.
Look up the individual man pages for more details and full syntax. Run gmt --help to list all GMT programs and to show all installation directories. For an explanation of the various GMT settings in this man page (like FORMAT_FLOAT_OUT), see the man page of the GMT configuration file gmt.conf. Information is also available on the GMT home page http://gmt.soest.hawaii.edu/