Provided by: gmt_6.3.0+dfsg-2build1_amd64 
NAME
gmt - The Generic Mapping Tools data processing and display software package
INTRODUCTION
GMT is a collection of freely available command-line tools under the GNU LGPL that allows you to
manipulate x,y and x,y,z data sets (filtering, trend fitting, gridding, projecting, etc.) and produce
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.
SYNOPSIS
gmt is the main program that can start any of the modules:
gmt module module-options
Starts a given GMT module with the module-options that pertain to that particular module. A few
special commands are also available:
gmt clear items
Deletes current defaults, or the cache, data or sessions directories. Choose between defaults
(deletes the current gmt.conf file used for the current modern session), cache (deletes the user’s
cache directory and all of its content), data (deletes the user’s data download directory and all
of its content), or all (does all of the above).
gmt begin [session-prefix] [format] [options]
Initializes a new GMT session under modern mode [Default is classic mode]. All work is performed
in a temporary work directory. The optional session-prefix assigns a name to the session, and
this may be used as figure name for single-figure sessions [gmtsession]. Likewise, the optional
format can be used to override the default graphics format [PDF].
gmt figure prefix [format(s)] [options]
Specifies the desired name, output format(s) and any custom arguments that should be passed to
psconvert when producing this figure. All subsequent plotting will be directed to this current
figure until another gmt figure command is issued or the session ends. The prefix is used to
build final figure names when extensions are automatically appended. The format setting is a
comma-separated list of desired extensions (e.g., pdf,png).
gmt inset [arguments]
Allows users to place a map inset by temporarily changing where plotting takes place as well as
the region and projection, then resets to previous stage.
gmt subplot [arguments]
Allows users to create a matrix of panels with automatic labeling and advancement.
gmt end [show]
Terminates a GMT modern mode session and automatically converts the registered illustration(s) to
their specified formats, then eliminates the temporary work directory. The figures are placed in
the current directory.
For information on any module, load the module documentation in your browser via gmt docs, e.g.:
gmt docs grdimage
If no module is given then several other options are available:
--help List and description of GMT modules.
--new-script[=L]
Write a GMT modern mode script template to stdout. Optionally append the desired scripting
language among bash, csh, or batch. Default is the main shell closest to your current shell
(e.g., bash for zsh, csh for tcsh).
--new-glue=name
Write the C code glue needed when building third-party supplements as shared libraries. The name
is the name of the shared library. Run gmt in the directory of the supplement and the glue code
will be written to stdout. Including this C code when building the shared library means gmt can
list available modules via the --show-modules, --help options. We recommend saving the code to
gmt_name_glue.c.
--show-bindir
Show directory of executables and exit.
--show-citation
Show the citation for the latest GMT publication.
--show-classic
List classic module names on stdout and exit.
--show-classic-core
List classic module names (core only) on stdout and exit.
--show-cores
Show number of available cores.
--show-datadir
Show data directory/ies and exit.
--show-dataserver
Show URL of the remote GMT data server.
--show-doi
Show the DOI of the current release.
--show-modules
List modern module names on stdout and exit.
--show-modules-core
List modern module names (core only) on stdout and exit.
--show-library
Show the path of the shared GMT library.
--show-plugindir
Show plugin directory and exit.
--show-sharedir
Show share directory and exit.
--show-userdir
Show full path of user’s ~/.gmt dir and exit.
--version
Print version and exit.
= Check if that module exist and if so the program will exit with status of 0; otherwise the status
of exit will be non-zero.
COMMAND-LINE COMPLETION
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.
GMT MODULES
Run gmt --help to print the list of all core and supplementals modules within GMT, and a very short
description of their purpose. Detailed information about each program can be found in the separate
manual pages.
CUSTOM MODULES
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 from the GMT infrastructure and extend GMT in specific
ways.
THE COMMON GMT OPTIONS
-B[p|s]parameters -Jparameters -Jz|Zparameters -Rwest/east/south/north[/zmin/zmax][+r][+uunit] -U[stamp]
-V[level] -X[a|c|f|r][xshift] -Y[a|c|f|r][yshift] -aflags -bbinary -crow,col|index -d[+ccol]nodata -e‐
regexp -fflags -ggaps -hheaders -iflags -jflags -lflags -nflags -oflags -pflags -qflags -rreg -sflags -t‐
transp -x[[-]n] -:[i|o]
DESCRIPTION
These are all the common GMT options that remain the same for all GMT modules. No space between the
option flag and the associated arguments.
The -B option
Syntax
-B[p|s]parameters
Set map boundary frame and axes attributes. (See cookbook information).
Description
This is potentially the most complicated option in GMT, but most examples of its usage are actually quite
simple. We distinguish between two sets of information: Frame settings and Axes settings. These are set
separately by their own -B invocations; hence multiple -B specifications may be specified. The Frame
settings cover things such as which axes should be plotted, canvas fill, plot title (and subtitle), and
what type of gridlines be drawn, whereas the Axes settings deal with annotation, tick, and gridline
intervals, axes labels, and annotation units.
Frame settings
The Frame settings are specified by
-B[axes][+b][+gfill][+i[val]][+n][+olon/lat][+ssubtitle][+ttitle][+w[pen]][+xfill][+yfill][+zfill]
The frame setting is optional but can be invoked once to override the defaults. The following modifiers
can be appended to -B to control the Frame settings:
• axes to set which of the axes should be drawn and possibly annotated using a combination of the codes
listed below [default is theme dependent]. Borders omitted from the set of codes will not be drawn.
For example, WSn denotes that the “western” (left) and “southern” (bottom) axes should be drawn with
tick-marks and annotations by using W and S; that the “northern” (top) edge of the plot should be drawn
with tick-marks and without annotations by using n; and that the “eastern” (right) axes should not be
drawn by not including one of E|e|r.
• West, East, South, North, and/or (for 3-D plots) Z indicate axes that should be drawn with both
tick-marks and annotations.
• west, east, south, north, and/or (for 3-D plots) z indicate axes that should be drawn with
tick-marks but without annotations.
• l(eft), r(ight), b(ottom), t(op) and/or (for 3-D plots) u(p) indicate axes that should be drawn
without tick-marks or annotations.
• Z|zcode (for 3-D plots) where code is any combination of the corner ids 1, 2, 3, 4. By default, a
single vertical axes will be plotted for 3-D plots at the most suitable map corner. code can be used to
override this, where 1 represents the south-western (lower-left) corner, 2 the south-eastern
(lower-right), 3 the north-eastern (upper-right), and 4 the north-western (upper-left) corner.
• +w[pen] (for 3-D plots) to draw the outlines of the x-z and y-z planes [default is no outlines].
Optionally, append pen to specify different pen attributes [default is MAP_GRID_PEN_PRIMARY].
• +b (for 3-D plots) to draw the foreground lines of the 3-D cube defined by -R.
• +gfill to paint the interior of the canvas with a color specified by fill [default is no fill]. This
also sets fill for the two back-walls in 3-D plots.
• +xfill to paint the yz plane with a color specified by fill [default is no fill].
• +yfill to paint the xz plane with a color specified by fill [default is no fill].
• +zfill to paint the xy plane with a color specified by fill [default is no fill].
• +i[val] to annotate an internal meridian or parallel when the axis that normally would be drawn and
annotated does not exist (e.g., for an azimuthal map with 360-degree range that has no latitude axis or
a global Hammer map that has no longitude axis). val gives the meridian or parallel that should be
annotated [default is 0].
• +olon/lat to produce oblique gridlines about another pole specified by lon/lat [default references to
the North pole]. +o is ignored if no gridlines are requested.
• +n to have no frame and annotations at all [default is contolled by axes].
• +ttitle to place the string given in title centered above the plot frame [default is no title].
• +ssubtitle (requires +ttitle) to place the string given in subtitle beneath the title [default is no
subtitle].
Note: Both +ttitle and +ssubtitle may be set over multiple lines by breaking them up using the markers @^
or <break>. To include LaTeX code as part of a single-line title or subtitle, enclose the expression
with @[ markers (or alternatively <math> … </math>) (requires latex and dvips to be installed). See the
/cookbook/gmt-latex chapter for more details.
Axes settings
The Axes settings are specified by
-B[p|s][x|y|z]intervals[+aangle|n|p][+f][+llabel][+pprefix][+uunit]
but you may also split this into two separate invocations for clarity, i.e.,
-B[p|s][x|y|z][+aangle|n|p][+e[l|u]][+f][+l|Llabel][+pprefix][+s|Sseclabel][+uunit]
-B[p|s][x|y|z]intervals
The following modifiers can be appended to -B to control the Axes settings:
• p|s to set whether the modifiers apply to the p(rimary) or s(econdary) axes [Default is p]. These
settings are mostly used for time axes annotations but are available for geographic axes as well. Note:
Primary refers to annotations closest to the axis and secondary to annotations further away. Hence,
primary annotation-, tick-, and gridline-intervals must be shorter than their secondary counterparts.
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).
• x|y|z to set which axes the modifiers apply to [default is 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.
For a 3-D plot with the -p and -Jz options used, -Bz can be used to provide settings for the vertical
axis.
• +e to give skip annotations that fall exactly at the ends of the axis. Append l or u to only skip the
lower or upper annotation, respectively.
• +f (for geographic axes only) to give fancy annotations with W|E|S|N suffices encoding the sign.
• +l|+Llabel (for Cartesian plots only) to add a label to an axis. +l uses the default label orientation;
+L forces a horizontal label for y-axes, which is useful for very short labels.
• +s|Sseclabel (for Cartesion plots only) to specify an alternate label for the right or upper axes. +s
uses the default label orientation; +S forces a horizontal label for y-axes, which is useful for very
short labels.
• +pprefix (for Cartesion plots only) to define a leading text prefix for the axis annotation (e.g.,
dollar sign for plots related to money). For geographic maps the addition of degree symbols, etc. is
automatic and controlled by FORMAT_GEO_MAP.
• +uunit (for Cartesion plots only) to append specific units to the annotations. For geographic maps the
addition of degree symbols, etc. is automatic and controlled by FORMAT_GEO_MAP.
• +aangle (for Cartesion plots only) to plot slanted annotations, where angle is measured with respect to
the horizontal and must be in the -90 <= angle <= 90 range. +an can be used as a shorthand for normal
(i.e., +a90) [Default for y-axis] and +ap for parallel (i.e., +a0) annotations [Default for x-axis].
These defaults can be changed via MAP_ANNOT_ORTHO.
• intervals to define the intervals for annotations and major tick spacing, minor tick spacing, and/or
grid line spacing. See Intervals Specification for the formatting associated with this modifier.
NOTE: To include LaTeX code as part of a label, enclose the expression with @[ markers (or alternatively
<math> … </math>). (requires latex and dvips to be installed). See the /cookbook/gmt-latex chapter for
more details.
NOTE: If any labels, prefixes, or units contain spaces or special characters you will need to enclose
them in quotes.
NOTE: Text items such as title, subtitle, label and seclabel are seen by GMT as part of a long string
containing everything passed to -B. Therefore, they cannot contain substrings that look like other
modifiers. If you need to embed such sequences (e.g., +t“Solving a+b=c”) you need to replace those +
symbols with their octal equivalent \053, (e.g., +t“Solving a\053b=c”).
NOTE: 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).
Intervals specification
The intervals specification is a concatenated string made up of substrings of the form
[a|f|g][stride][phase][unit].
The choice of a|f|g sets the axis item of interest, which are detailed in the Table interval types.
Optionally, append phase to shift the annotations by that amount (positive or negative with the sign
being required). Optionally, append unit to specify the units of stride, where unit is one of the 18
supported unit codes. For custom annotations and intervals, intervals can be given as cintfile, where
intfile contains any number of records with coord type [label]. See the section Custom axes for more
details.
┌──────┬───────────────────────────────────┐
│ Flag │ Description │
├──────┼───────────────────────────────────┤
│ a │ Annotation and major tick spacing │
├──────┼───────────────────────────────────┤
│ f │ Minor tick spacing │
├──────┼───────────────────────────────────┤
│ g │ Grid line spacing │
└──────┴───────────────────────────────────┘
NOTE: The appearance of certain time annotations (month-, week-, and day-names) may be affected by the
GMT_LANGUAGE, FORMAT_TIME_PRIMARY_MAP, and FORMAT_TIME_SECONDARY_MAP settings.
Automatic intervals: GMT will auto-select the spacing between the annotations and major ticks, minor
ticks, and grid lines if stride is not provided after a|f|g. This can be useful for automated plots where
the region may not always be the same, making it difficult to determine the appropriate stride in
advance. For example, -Bafg will select all three spacings automatically for both axes. In case of
longitude–latitude plots, this will keep the spacing the same on both axes. You can also use -Bxafg
-Byafg to auto-select them separately. Note that given the myriad ways of specifying time-axis
annotations, the automatic selections may need to be overridden with manual settings to achieve exactly
what you need. When stride is omitted after g, the grid line are spaced the same as the minor ticks;
unless g is used in consort with a, in which case the grid lines are spaced the same as the annotations.
Stride units: The unit flag can take on one of 18 codes which are listed in Table Units. Almost all of
these units are time-axis specific. However, the d, m, and s units will be interpreted as arc degrees,
minutes, and arc seconds respectively when a map projection is in effect.
────────────────────────────────────────────────────────
Flag Unit Description
────────────────────────────────────────────────────────
Y year Plot using all 4 digits
────────────────────────────────────────────────────────
y year Plot using last 2 digits
────────────────────────────────────────────────────────
O month Format annotation using
FORMAT_DATE_MAP
────────────────────────────────────────────────────────
o month Plot as 2-digit integer
(1–12)
────────────────────────────────────────────────────────
U ISO week Format annotation using
FORMAT_DATE_MAP
────────────────────────────────────────────────────────
u ISO week Plot as 2-digit integer
(1–53)
────────────────────────────────────────────────────────
r Gregorian week 7-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
FORMAT_DATE_MAP
────────────────────────────────────────────────────────
d day Plot day of month (1–31) or
day of year (1–366) (see
FORMAT_DATE_MAP)
────────────────────────────────────────────────────────
R day Same as d; annotations
aligned with week (see
TIME_WEEK_START)
────────────────────────────────────────────────────────
H hour Format annotation using
FORMAT_CLOCK_MAP
────────────────────────────────────────────────────────
h hour Plot as 2-digit integer
(0–24)
────────────────────────────────────────────────────────
M minute Format annotation using
FORMAT_CLOCK_MAP
────────────────────────────────────────────────────────
m minute Plot as 2-digit integer
(0–60)
────────────────────────────────────────────────────────
S seconds Format annotation using
FORMAT_CLOCK_MAP
────────────────────────────────────────────────────────
s seconds Plot as 2-digit integer
(0–60)
┌──────┬────────────────┬──────────────────────────────┐
│ │ │ │
--
ASCII FORMAT PRECISION
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, absolute time is under the control of
FORMAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point values are formatted according to
FORMAT_FLOAT_OUT. Be aware that the format in effect can lead to loss of precision in ASCII 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.
GRID FILE FORMATS
By default GMT writes out grids as single precision floats in a COARDS-complaint netCDF file format.
However, GMT is able to produce and read 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][+ddivisor][+ninvalid][+ooffset][+sscale], where ID is a two-letter identifier of the grid type and
precision, and the scale (or divisor), offset and invalid are the arguments of optional modifiers to be
applied to all grid values, Here, invalid is the value used to indicate missing data. In case the ID is
not provided, as in +sscale, then a ID=nf is assumed. When reading grids, the format is generally
automatically recognized from almost all of those formats that GMT and GDAL combined offer. If not, the
same suffix can be added to input grid file names. If reading an image as a grid you can select the band
via +b. See grdconvert and Section grid-file-format of the GMT Technical Reference and Cookbook for more
information regarding GDAL settings.
When reading a netCDF file that contains multiple grids, GMT will read, by default, the first
2-dimensional grid that it 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-CF and grid-file-format of the GMT Technical Reference and Cookbook
for more information, particularly on how to read slices of 3-, 4-, or 5-dimensional grids.
When writing a netCDF file, the grid is stored by default with the variable name “z”. To specify another
variable name varname, append ?varname to the file name. 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.
CLASSIC MODE OPTIONS
These options are only used in classic mode and are listed here just for reference.
-K More PostScript code will be appended later [Default terminates the plot system]. Required for all
but the last plot command when building multi-layer plots.
-O Selects Overlay plot mode [Default initializes a new plot system]. Required for all but the first
plot command when building multi-layer plots.
-P Select “Portrait” plot orientation [Default is “Landscape”; see gmt.conf or gmtset to change the
PS_PAGE_ORIENTATION parameter, or supply --PS_PAGE_ORIENTATION=orientation on the command line].
MORE INFORMATION SOURCES
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 documentation site https://docs.generic-mapping-tools.org/
DEPRECATIONS
• 6.3.0: Update -g syntax. #5617
• 6.3.0: Update -JG syntax to use modifiers. #5780
SEE ALSO
docs
COPYRIGHT
2021, The GMT Team.
6.3 Nov 18, 2021 GMT(1)