Provided by: gmt_6.4.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 standard output. 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 standard output. 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 standard output and exit.
--show-classic-core
List classic module names (core only) on standard output 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-dcw
Show the DCW data version used.
--show-doi
Show the DOI of the current release.
--show-gshhg
Show the GSHHG data version used.
--show-modules
List modern module names on standard output and exit.
--show-modules-core
List modern module names (core only) on standard output 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 -dnodata[+ccol] -eregexp -fflags -g‐
gaps -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 Using LaTeX Expressions in GMT 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 Using
LaTeX Expressions in GMT 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) │
└─────┴────────────────┴──────────────────────────┘
NOTE: If your axis is in radians you can use multiples or fractions of pi to set such
annotation intervals. The format is [s]pi[f], for an optional integer scale s and optional
integer fraction f. When GMT parses one of these forms we alert the labeling machinery to
look for certain combinations of pi, limited to npi, 3/2 pi (3pi2), and fractions 3/4
(3pi4), 2/3 (2pi3), 1/2 (1pi2), 1/3 (1pi3), and 1/4 (1pi4) in the interval given to the -B
axes settings. When an annotated value is within roundoff-error of these combinations we
typeset the label using the Greek letter \pi and required multiples or fractions.
NOTE: 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.
The -J option
Syntax
-Jparameters
Specify the projection. (See cookbook summary) (See projections table).
Description
Select map projection. The first character of parameters 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). The measurement unit (called UNIT below) 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 +dh, +du,
or +dl to the given width if you instead want to set the map height, the maximum (upper)
dimension, or the minimum (lower) dimension, respectively [Default is +dw 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 map projections is user-definable. 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 and append the required parameters (The E or C after projection names stands
for Equal-Area and Conformal, respectively):
CYLINDRICAL PROJECTIONS:
-Jc|Clon0/lat0/scale|width (Cassini).
Give projection center lon0/lat0 and either scale (with -Jc; as 1:xxxx or
plot-units/degree) or width (with -JC; in plot-units).
-Jcyl_stere|Cyl_stere/[lon0/[lat0/]]scale|width (Cylindrical Stereographic)
Give central meridian lon0 (optional), standard parallel lat0 (optional), and
either scale along parallel (with -Jcyl_stere; as 1:xxxx or plot-units/degree) or
width (with -JCyc_stere; in plot-units). 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|J[lon0/]scale|width (Miller Cylindrical Projection).
Give the central meridian lon0 (optional) and either scale (with -Jj; as 1:xxxx or
plot-units/degree) or width (with -JJ; in plot-units).
-Jm|M[lon0/[lat0/]]scale|width (Mercator [C])
Give central meridian lon0 (optional), standard parallel lat0 (optional), and
either scale along parallel (with -Jm; as 1:xxxx or plot-units/degree) or width
(with -JM; in plot-units).
-Joparameters[+v] (Oblique Mercator [C]).
Typically used with -RLLx/LLy/URx/URy+r or with projected coordinates. Specify one
of:
-Jo|O[a|A]lon0/lat0/azimuth/scale|width[+v]
Set projection center lon0/lat0, azimuth of oblique equator, and scale or
width
-Jo|O[b|B]lon0/lat0/lon1/lat1/scale|width[+v]
Set projection center lon0/lat0, another point on the oblique equator
lon1/lat1, and scale or width
-Jo|O[c|C]lon0/lat0/lonp/latp/scale|width[+v]
Set projection center lon0/lat0, pole of oblique projection lonp/latp, and
scale or width
Give scale along oblique equator (with -Ja|b|c; 1:xxxx or plot-units/degree) or
width (with -JA|B|C; in plot-units). Use upper-case A|B|C to remove enforcement of
a northern hemisphere pole. Append +v to let the oblique Equator align with the
y-axis [x-axis]. Note: If the region (-R) is given without the +r modifier then
the arguments are considered oblique degrees relative to the projection center and
not longitude/latitude bounds.
-Jq|Q[lon0/[lat0/]]scale|width (Cylindrical Equidistant).
Give the central meridian lon0 (optional), standard parallel lat0 (optional), and
either scale (with -Jq; as 1:xxxx or plot-units/degree) or width (with -JQ; in
plot-units) 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
-Jt|Tlon0/[lat0/]scale|width (Transverse Mercator [C])
Give the central meridian lon0, central parallel lat0 (optional), and either scale
(with -Jt; as 1:xxxx or plot-units/degree) or width (with -JT; in plot-units).
-Ju|Uzone/scale|width (UTM - Universal Transverse Mercator [C]).
Give the UTM zone (A,B,1-60[C-X],Y,Z)) and either scale (with -Ju; as 1:xxxx or
plot-units/degree) or width (with -JU; in plot-units). Zones: If C-X not given,
prepend - or + to enforce southern or northern hemisphere conventions [default is
northern if south > 0].
-Jy|Y[lon0/[lat0/]]scale|width (Cylindrical Equal-Area [E]).
Give the central meridian lon0 (optional), standard parallel lat0 (optional), and
either scale (with -Jy; as 1:xxxx or plot-units/degree) or width (with -JY; in
plot-units). The standard parallel is typically one of these (but can be any
value):
• 50 - Balthasart
• 45 - Gall
• 37.0666 - Caster
• 37.4 - Trystan Edwards
• 37.5 - Hobo-Dyer
• 30 - Behrman
• 0 - Lambert (default)
CONIC PROJECTIONS:
-Jb|Blon0/lat0/lat1/lat2/scale|width (Albers [E]).
Give projection center lon0/lat0, two standard parallels lat1/lat2, and either
scale (with -Jb; as 1:xxxx or plot-units/degree) or width (with -JB; in
plot-units).
-Jd|Dlon0/lat0/lat1/lat2/scale|width (Conic Equidistant)
Give projection center lon0/lat0, two standard parallels lat1/lat2, and either
scale (with -Jd; as 1:xxxx or plot-units/degree) or width (with -JD; in
plot-units).
-Jl|Llon0/lat0/lat1/lat2/scale|width (Lambert [C])
Give origin lon0/lat0, two standard parallels lat1/lat2, and scale along these
(with -Jl; as 1:xxxx or plot-units/degree) or width (with -JL; in plot-units).
-Jpoly|Poly/[lon0/[lat0/]]scale|width ((American) Polyconic).
Give the central meridian lon0 (optional), reference parallel lat0 (optional,
default = equator), and either scale along central meridian (with -Jpoly; as
1:xxxx or plot-units/degree) or width (with -JPoly; in plot-units).
AZIMUTHAL PROJECTIONS:
Except for polar aspects, -Rw/e/s/n will be reset to -Rg. Use
-Rxlleft/ylleft/xuright/yuright+r for smaller regions.
-Ja|Alon0/lat0[/horizon]scale|width (Lambert [E]).
lon0/lat0 specifies the projection center. horizon specifies the max distance
from projection center (in degrees, <= 180, default 90). Give either scale (with
-Ja; as 1:xxxx or radius/lat, where radius is distance in plot-units from origin
to the oblique latitude lat) or width (with -JA; in plot-units).
-Je|Elon0/lat0[/horizon]scale|width (Azimuthal Equidistant).
lon0/lat0 specifies the projection center. horizon specifies the max distance
from projection center (in degrees, <= 180, default 180). Give scale (with -Je;
as 1:xxxx or radius/lat, where radius is distance in plot-units from origin to
the oblique latitude lat) or width (with -JE; in plot-units).
-Jf|Flon0/lat0[/horizon]scale|width (Gnomonic).
lon0/lat0 specifies the projection center. horizon specifies the max distance
from projection center (in degrees, < 90, default 60). Give scale (with -Jf; as
1:xxxx or radius/lat, where radius is distance in plot-units from origin to the
oblique latitude lat) or width (with -JF; in plot-units).
-Jg|Glon0/lat0[/horizon]/scale|width (Orthographic).
lon0/lat0 specifies the projection center. horizon specifies the max distance
from projection center (in degrees, <= 90, default 90). Give scale (with -Jg; as
1:xxxx or radius/lat, where radius is distance in plot-units from origin to the
oblique latitude lat.
-Jg|Glon0/lat0/scale|width[+aazimuth][+ttilt][+vvwidth/vheight][+wtwist][+zaltitude[r|R]|g]
(General Perspective).
lon0/lat0 specifies the projection center. Give scale (with -Jg; as 1:xxxx
or radius/lat, where radius is distance in plot-units from origin to the
oblique latitude lat) or width (with -JG; in plot-units). Several optional
modifiers control the perspective:
• +a sets azimuth measured to the east of north of view [0].
• +t sets the upward tilt of the plane of projection. If tilt is negative, then
the viewpoint is centered on the horizon [0].
• +v sets a restricted view: vwidth and vheight ( in degrees) limits the view
from the viewpoint [unrestricted].
• +w sets the clockwise twist of the viewpoint (in degrees) [0].
• +z sets the altitude of the viewer above sea level in kilometers [infinity].
Alternatively append R if giving the distance of the viewer from the center of
the Earth in Earth radii, or r if giving the distance from the center of the
Earth in kilometers. Finally, give altitude as g to compute and use the
altitude for a geosynchronous orbit.
-Js|Slon0/lat0[/horizon]/scale|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 (with -Js; as
1:xxxx (true at pole) or lat/1:xxxx (true at standard parallel lat and requires
lat0 = ±90) or radius/lat (radius in plot-units 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.) or width (with -JS; in plot-units).
MISCELLANEOUS PROJECTIONS:
-Jh|H[lon0/]scale|width (Hammer [E]).
Give the central meridian lon0 (optional) and either scale along equator (with
-Jh; as 1:xxxx or plot-units/degree) or width (with -JH; in plot-units).
-Ji|I[lon0/]scale|width (Sinusoidal [E]).
Give the central meridian lon0 (optional) and either scale along equator (with
-Ji; as 1:xxxx or plot-units/degree) or width (with -JI; in plot-units).
-Jk|Kf[lon0/]scale|width (Eckert IV [E]).
Give the central meridian lon0 (optional) and either scale along equator (with
-Jk; as 1:xxxx or plot-units/degree) or width (with -JK; in plot-units).
-Jk|K[s][lon0/]scale|width (Eckert VI [E]).
Give the central meridian lon0 (optional) and either scale along equator (with
-Jk; as 1:xxxx or plot-units/degree) or width (with -JK; in plot-units).
-Jn|N[lon0/]scale|width (Robinson).
Give the central meridian lon0 (optional) and either scale along equator (with
-Jn; as 1:xxxx or plot-units/degree) or width (with -JN; in plot-units).
-Jr|R[lon0/]scale|width (Winkel Tripel).
Give the central meridian lon0 (optional) and either scale along equator (with
-Jr; as 1:xxxx or plot-units/degree) or width (with -JR; in plot-units).
-Jv|V[lon0/]scale|width (Van der Grinten).
Give the central meridian lon0 (optional) and either scale along equator (with
-Jv; as 1:xxxx or plot-units/degree) or width (with -JV; in plot-units).
-Jw|W[lon0/]scale|width (Mollweide [E]).
Give the central meridian lon0 (optional) and either scale along equator (with
-Jw; as 1:xxxx or plot-units/degree) or width (with -JW; in plot-units).
NON-GEOGRAPHICAL PROJECTIONS:
-Jp|Pscale|width[+a][+f[e|p|radius]][+kkind][+roffset][+torigin][+z[p|radius]]] (Polar
coordinates (theta, r))
Give scale (with -Jp; in plot-units/r-unit) or width (with -JP; in plot-units). The
following modifiers are supported by -Jp|P:
• +a to indicate that theta is azimuth CW from North instead of direction CCW from East
[Default is CCW from East].
• +f to flip the radial direction to point inwards, and append e to indicate that r
represents elevations in degrees (requires south >= 0 and north <= 90), p to select
current planetary radius (determined by PROJ_ELLIPSOID) as maximum radius [north], or
radius to specify a custom radius.
• +k sets the annotation kind to be longitudes (x) or latitudes (y) [Default is
unspecified angles].
• +roffset to include a radial offset in measurement units [default is 0].
• +torigin in degrees so that this angular value is aligned with the positive x-axis
(or the azimuth to be aligned with the positive y-axis if +a) [default is 0].
• +z to annotate depth rather than radius [default is radius]. Alternatively, if your r
data are actually depths then you can append p or radius to get radial annotations (r
= radius - z) instead.
-Jx|Xx-scale|width[l|ppower|T|t][/y-scale|height[l|ppower|T|t]][d|g] (Linear, log, and
power scaling)
Give x-scale (with -Jx; as 1:xxxx or plot-units/x-unit) and/or y-scale (1:xxxx or
plot-units/y-unit); or specify width and/or height (with -JX; in plot-units).
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 to indicate that data are geographical coordinates (in degrees).
• g to indicate that data are geographical coordinates
• l to take log10 of values before scaling.
• ppower to raise values to power before scaling.
• t to indicate that input coordinates are time relative to TIME_EPOCH.
• T to indicate that input coordinates are absolute time.
For mixed axes with only one geographic axis you may need to set -f as well.
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.
-Jz|Zparameters
Set z-axis scaling; same syntax as -Jx.
-Jproj|EPSG:n
Starting at GMT6 it is possible to use the PROJ library to do coordinate and datum
transforms. This is achieved via the GDAL library. It is, however, beyond the
scope of this manual to document the PROJ syntax (that is the syntax of the proj
and cs2cs programs) so users are referred to PROJ Applications for the details.
The usage of PROJ follows very closely the syntax of proj and cs2cs. The projection
parameters are encapsulated under the -J option. Because there are normally several
parameters defining a referencing system separated by spaces (in PROJ or GDAL) we
can either use double quotes as in -J“+proj=merc +ellps=WGS84 +units=m” or just
glue all parameters like in -J+proj=merc+ellps=WGS84+units=m.
Using EPSG codes is also possible (but need the setting of the GDAL_DATA
environment variable to point to the GDAL’s data sub-directory). For example
-JEPSG:4326 sets the WGS-84 system.
For mapproject and grdproject we can go directly from the referencing system A to B
without the intermediate step of converting to geographic coordinates. That is
obtained (like in cs2cs) by using the +to keyword. Example:
-JEPSG:4326+to+proj=aeqd+ellps=WGS84+units=m. A much awaited bonus is also that we
now do not need to set -R to do point coordinate conversions.
While for point and grid conversions done by mapproject and grdproject we can use
all PROJ projections, the situations is, however, rather more limited for mapping
purposes. Here, only the subset of the PROJ projections that can be mapped into
the GMT projections syntax is available to use. Another aspect that is not present
in PROJ, because it’s not a mapping library, is how to set the map scale or map
dimension. We introduced the two extensions +width=size and +scale=1:xxxx that work
exactly like the map width and scale in classical GMT. It is also allowed to
provide the scale (but NOT the width) by appending the string “/1:xxx” to the end
of the projection parameters.
The -R option
Syntax
-Rxmin/xmax/ymin/ymax[+r][+uunit]
Specify the region of interest. (See cookbook information).
Description
The -R option defines the map region or data domain of interest. It may be specified in
one of several ways (options 1 and 3 are shown in panels a) and b) respectively of the
Figure Map region):
1. -Rxmin/xmax/ymin/ymax. This is the standard way to specify Cartesian data domains and
geographic regions when using map projections where meridians and parallels are
rectilinear, where xmin, xmax, ymin, and ymax refer to the data limits.
2. -Rxmin/xmax/ymin/ymax+uunit. Append +uunit to the option 1 to specify a region in
projected units (e.g., UTM meters) where xmin/xmax/ymin/ymax are Cartesian projected
coordinates compatible with the chosen projection and unit is an allowable distance
unit [e]. The coordinates are relative to the standard longitude and latitude indicated
in the projection (-J). For projected regions centered on (0,0) you may use the
short-hand -Rhalfwidth[/halfheight]+uunit, where halfheight defaults to halfwidth if
not given. This short-hand requires the +u modifier.
3. -Rxlleft/ylleft/xuright/yuright+r. This form is useful for 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 modifier +r. This form guarantees a rectangular map even though lines
of equal longitude and latitude are not straight lines.
4. -Rg or -Rd. These forms can be used to quickly specify the global domain (0/360 for -Rg
and -180/+180 for -Rd in longitude, with -90/+90 in latitude).
5. -Rgridfile. This will copy the domain settings found for the grid in specified file.
Note that depending on the nature of the calling module, this mechanism will also set
grid spacing and possibly the grid registration (see Grid registration: The -r option).
6. -Rcode1,code2,…[+e|r|Rincs]. This indirectly supplies the region by consulting the DCW
(Digital Chart of the World) database and derives the bounding regions for one or more
countries given by the codes. Simply append one or more comma-separated countries using
either the two-character ISO 3166-1 alpha-2 convention (e.g., NO) or the full country
name (e.g., Norway). To select a state within a country (if available), append .state
(e.g, US.TX), or the full state name (e.g., Texas). To specify a whole continent, spell
out the full continent name (e.g., -RAfrica). Finally, append any DCW collection
abbreviations or full names for the extent of the collection or named region. All names
are case-insensitive. The following modifiers can be appended:
• +r to adjust the region boundaries to be multiples of the steps indicated by inc,
xinc/yinc, or winc/einc/sinc/ninc [default is no adjustment]. For example, -RFR+r1
will select the national bounding box of France rounded to nearest integer degree,
where inc can be positive to expand the region or negative to shrink the region.
• +R to adjust the region by adding the amounts specified by inc, xinc/yinc, or
winc/einc/sinc/ninc [default is no extension], where inc can be positive to expand
the region or negative to shrink the region.
• +e to adjust the region boundaries to be multiples of the steps indicated by inc,
xinc/yinc, or winc/einc/sinc/ninc, while ensuring that the bounding box is adjusted
by at least 0.25 times the increment [default is no adjustment], where inc can be
positive to expand the region or negative to shrink the region.
7. -Rjustifyx0/y0/nx/ny, where justify is a 2-character combination of L|C|R (for left,
center, or right) and T|M|B (for top, middle, or bottom) (e.g., BL for lower left). The
two character code justify indicates which point on a rectangular grid region the x0/y0
coordinates refer to and the grid dimensions nx and ny are used with grid spacings
given via -I to create the corresponding region. This method can be used when creating
grids. For example, -RCM25/25/50/50 specifies a 50x50 grid centered on 25,25.
8. -Rxmin/xmax/ymin/ymax/zmin/zmax. This method can be used for perspective views with the
-Jz and the -p option, where the z-range (zmin/zmax) is appended to the first method to
indicate the third dimension. This is not used for -p without -Jz, in which case a
perspective view of the place is plotted with no third dimension.
9. -Ra[uto] or -Re[xact]. Under modern mode, and for plotting modules only, you can
automatically determine the region from the data used. You can either get the exact
area using -Re [Default if no -R is given] or a slightly larger area sensibly rounded
outwards to the next multiple of increments that depend on the data range using -Ra.
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.
The -U option
Syntax
-U[label|+c][+jjust][+odx[/dy]]
Draw GMT time stamp logo on plot. (See cookbook information).
Description
The -U option draws the GMT system time stamp on the plot. The following modifiers are
supported:
• label to append the text string given in label (which must be surrounded by double
quotes if it contains spaces).
• +c to plot the current command string.
• +jjustify to specify the justification of the time stamp, where justify is a
two-character justification code that is a combination of a horizontal (L(eft),
C(enter), or R(ight)) and a vertical (T(op), M(iddle), or B(ottom)) code [default is
BL].
• +odx[/dy] to offset the anchor point for the time stamp by dx and optionally dy (if
different than dx).
The GMT parameters MAP_LOGO, MAP_LOGO_POS, FONT_LOGO and FORMAT_TIME_STAMP can affect the
appearance; see the gmt.conf man page for details. The time string will be in the locale
set by the environment variable TZ (generally local time).
The -V option
Syntax
-V[level]
Select verbosity level [w]. (See cookbook information).
Description
The -V option controls the verbosity mode, which determines which messages are sent to
standard error. Choose among 7 levels of verbosity; each level adds more messages:
• q - Quiet, not even fatal error messages are produced.
• e - Error messages only.
• w - Warnings (by default, same as running without -V)
• t - Timings (report runtimes for time-intensive algorithms).
• i - Informational messages (same as -V only).
• c - Compatibility warnings (if compiled with backward-compatibility).
• d - Debugging messages.
This option can also be set by specifying the default GMT_VERBOSE as quiet, error,
warning, timing, compat, information, or debug, in order of increased verbosity [default
is warning].
The -X -Y options
Syntax
-X[a|c|f|r][xshift]
Shift plot origin. (See cookbook information).
-Y[a|c|f|r][yshift]
Shift plot origin. (See cookbook information).
Description
The -X and -Y options shift the plot origin relative to the current origin by
(xshift,yshift). Optionally, append the length unit (c, i, or p). Default is (‐
MAP_ORIGIN_X, MAP_ORIGIN_Y) for new plots, which ensures that boundary annotations fit on
the page. Subsequent overlays will be co-registered with the previous plot unless the
origin is shifted using these options. The following modifiers are supported [default is
r]:
• Prepend a to shift the origin back to the original position after plotting.
• Prepend c to center the plot on the center of the paper (optionally add a shift).
• Prepend f to shift the origin relative to the fixed lower left.
• Prepend r to move the origin relative to its current location.
When -X or -Y are used without any further arguments, the values from the last use of that
option in a previous GMT command will be used. In modern mode, -X and -Y can also access
the previous plot bounding box dimensions w and h and construct offsets that involve them.
Thus, xshift can in general be [[±][f]w[/d]±]xoff, where optional signs, factor f and
divisor d can be used to compute an offset that may be adjusted further by ±off.
Similarly, yshift can in general be [[±][f]h[/d]±]yoff. For instance, to move the origin
up 2 cm beyond the height of the previous plot, use -Yh+2c. To move the origin half the
width to the right, use -Xw/2. Note: the previous plot bounding box refers to the last
object plotted, which may be an image, logo, legend, colorbar, etc.
The -a option
Syntax
-a[[col=]name][,…]
Control how aspatial data are handled in GMT during input and output.
Description
GMT relies on external tools to translate geospatial files such as shapefiles into a
format we can read. The tool ogr2ogr in the GDAL package can do such translations and
preserve the aspatial metadata via a new OGR/GMT format specification (See the cookbook
chapter The GMT Vector Data Format for OGR Compatibility). For this to be useful we need a
mechanism to associate certain metadata values with required input and output columns
expected by GMT programs. The -a option allows you to supply one or more comma-separated
associations col=name, where name is the name of an aspatial attribute field in a OGR/GMT
file and whose value we wish to as data input for column col. The given aspatial field
thus replaces any other value already set. Note: col = 0 is the first data column. Note:
If no aspatial attributes are needed then the -a option is not needed – GMT will still
process and read such data files.
OGR/GMT input with -a option
If you need to populate GMT data columns with (constant) values specified by aspatial
attributes, use -a and append any number of comma-separated col=name associations. For
example, -a2=depth will read the spatial x,y columns from the file and add a third (z)
column based on the value of the aspatial field called depth. You can also associate
aspatial fields with other settings such as labels, fill colors, pens, and values (for
looking-up colors) by letting the col value be one of D (for distance), G (for fill), I
(for ID), L (for label), T (for text), W (for pen), or Z (for value). This works
analogously to how standard multi-segment files can pass such options via its segment
headers (See the cookbook chapter GMT File Formats). Note: If the leading col= is omitted,
the column value is automatically incremented starting at 2.
OGR/GMT output with -a option
GMT table-writing tools can also output the OGR/GMT format directly. Specify if certain
GMT data columns with constant values should be stored as aspatial metadata using
col=name[:type], where you can optionally specify what data type it should be from the
options double, float, integer, char, string, logical, byte, or datetime [default is
double]. As for input, you can also use the special col entries of D (for distance), G
(for fill), I (for ID), L (for label), T (for text), W (for pen), or Z (for value) to have
values stored as options in segment headers be used as the source for the named aspatial
field. The type will be set automatically for these special col entries. Finally, for
output you must append +ggeometry, where geometry can be any of [M]POINT|LINE|POLY; where
M represents the multi-versions of these three geometries. Use upper-case +G to signal
that you want to split any line or polygon features that straddle the Dateline.
The -bi option
Syntax
-birecord[+b|l]
Select native binary format for primary table input (secondary inputs are always
ASCII).
Description
Select native binary record format for primary table input. The record is one or more
groups with format [ncols][type][w], where ncols is the number of consecutive data columns
of given type and type must be one of:
• c - int8_t (1-byte signed char)
• u - uint8_t (1-byte unsigned char)
• h - int16_t (2-byte signed int)
• H - uint16_t (2-byte unsigned int)
• i - int32_t (4-byte signed int)
• I - uint32_t (4-byte unsigned int)
• l - int64_t (8-byte signed int)
• L - uint64_t (8-byte unsigned int)
• f - 4-byte single-precision float
• d - 8-byte double-precision float [Default]
• x - use to skip ncols anywhere in the record
Force byte-swapping of a group by appending w at the end of the group. For records with
mixed types, append additional comma-separated groups (no space between groups). The
following modifiers are supported:
• +b|l to indicate that the entire data file should be read as big- or little-endian,
respectively.
The cumulative number of ncols may exceed the columns actually needed by the program. If
ncols is not specified we assume that type applies to all columns and that ncols is
implied by the expectation of the program. 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. Native binary files may have a header section, where the -h option can be used to
skip the first n bytes. If the input file is netCDF, no -b is needed; simply append
?var1/var2/… to the filename to specify the variables to be read (see GMT File Formats and
Modifiers for COARDS-compliant netCDF files for more information). Here is an example
that writes a binary file and reads it back with the first column 4 byte float, the second
column 8 byte int, and the third column 8 byte double.
echo 1.5 2 2.5 | gmt convert -bo1f,1l,1d > test.bin
gmt convert test.bin -bi1f,1l,1d
The -bo option
Syntax
-borecord[+b|l]
Select native binary format for table output.
Description
Select native binary format for table output. The record must be one or more groups with
format [ncols][type][w], where ncols is the number of consecutive data columns of given
type and type must be one of c, u, h, H, i, I, l, L, f, or d [Default] (see -bi types for
descriptions). Force byte-swapping of a group by appending w at the end of the group.
For a mixed-type output record, append additional comma-separated groups (no space between
groups) The following modifiers are supported:
• +b|l to indicate that the entire data file should be written as big- or
little-endian, respectively.
If ncols is not specified we assume that type applies to all columns and that ncols is
implied by the default output of the program. Note: NetCDF file output is not supported.
The -c option
Syntax
-c[row,col|index]
Advance to the selected subplot panel.
Description
The -c option can be used to either advance the focus of plotting to the next panel in the
sequence (either by row or by column as set by subplot’s -A option) or to specify directly
the row,col or 1-D index of the desired panel, when using subplot to assemble multiple
individual panels in a matrix layout. The -c option is only allowed when in subplot mode.
If no -c option is given for the first subplot then we default to row=col=index=0, i.e.,
the upper left panel. Note: row, col, and index all start at 0.
The -d option
Syntax
-di|onodata[+ccol]
Substitute specific values with NaN.
Description
The -d option allows user-coded missing data values to be translated to official NaN
values in GMT. Within GMT, any missing values are represented by the IEEE NaN value.
However, user data may occasionally denote missing data with an unlikely value (e.g.,
-99999). Since GMT cannot guess this special missing data value, you can use the -d option
to have such values replaced with NaNs. Similarly, the -d option can replace all NaNs with
the chosed nodata value should the GMT output need to conform to such a requirement.
For input only, use -dinodata to examine all input columns after the first two. If any
item equals nodata, the value is interpreted as a missing data item and is substituted
with the value NaN.
For output only, use -donodata to examine all output columns. If any item equals NaN, the
NaN value is substituted with the chosen missing data value nodata.
Use the +c modifier to override the starting column used for the examinations [2 for
input, 0 for output].
The -e option
Syntax
-e[~]“pattern” | -e[~]/regexp/[i]
Only accept ASCII data records that contain the specified pattern.
Description
The -e option offers a built-in pattern scanner that will only pass records that match the
given pattern or regular expressions, whereas modules that read ASCII tables will normally
process all the data records that are read. The test can also be inverted to only pass
data records that do not match the pattern, by using -e~. The test is not applied to
header or segment headers. Should your pattern happen to start with ~ you will need to
escape this character with a backslash [Default accepts all data records]. For matching
data records against extended regular expressions, please enclose the expression in
slashes. Append i for case-insensitive matching. To supply a list of such patterns, give
+ffile with one pattern per line. To give a single pattern starting with +f, escape it
with a backslash.
The -f option
Syntax
-f[i|o]colinfo
Specify the data types of input and/or output columns (time or geographical data).
Description
The -f option specifies what kind of data each input or output column contains when map
projections are not required. Optionally, append i or o to make this apply only to input
or output, respectively [Default applies to both]. Append a text string with information
about each column (or range of columns) separated by commas. Each group starts with the
column number (0 is the first column) followed by either x (longitude), y (latitude), T
(absolute calendar time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), d
(dimension) or s (trailing text). If several consecutive columns have the same format you
may specify a range of columns rather than a single column. Column ranges must be given in
the format start[:inc]:stop, where inc defaults to 1 if not specified. 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.
Note: You can also indicate that all items from the given column and to the end of the
record should be considered trailing text by giving the code s (for string). Only the last
group may set s. Note: Types T and s can only be used with ASCII data sets.
Three shorthand options for common selections are available. The shorthand -f[i|o]g means
-f[i|o]0x,1y (i.e., geographic coordinates), while -f[i|o]c means -f[i|o]0:1f (i.e.,
Cartesian coordinates). A special use of -f is to select -fp[unit], which requires -J -R
and lets you use projected map coordinates (e.g., UTM meters) as data input. Such
coordinates are automatically inverted to longitude, latitude during the data import.
Optionally, append a length unit (see table distance units) [default is meter]. For more
information, see Sections Input data formats and Output data formats.
The -g option
Syntax
-gx|y|z|d|X|Y|Dgap[u][+a][+ccol][+n|p]
Examine the spacing between consecutive data points in order to impose breaks in
the line.
Description
The -g option is used to detect gaps based on one or more criteria. Repeat the option to
specify multiple criteria. A criterion is specified using one of the x|y|z|d|X|Y|D
directives. The upper-case directives specify that the criterion should be applied to the
projected coordinates for modules that map data to map coordinates.
• x|X - define a gap when there is a large enough change in the x coordinates (upper case
to use projected coordinates).
• y|Y - define a gap when there is a large enough change in the y coordinates (upper case
to use projected coordinates).
• z - define a gap when there is a large enough change in the z data. Use +ccol to change
the z data column [Default col is 2 (i.e., 3rd column)].
• d|D - define a gap when there is a large enough distance between coordinates (upper case
to use projected coordinates).
A unit u may be appended to the specified gap:
• For geographic data (x|y|d), the unit may be arc d(egree), m(inute), and s(econd), or
(m)e(ter), f(eet), k(ilometer), M(iles), or n(autical miles) [Default is (m)e(ter)].
• For projected data (X|Y|D), the unit may be i(nch), c(entimeter), or p(oint) [Default
unit is set by PROJ_LENGTH_UNIT].
Append modifier +a to specify that all the criteria must be met [default imposes breaks if
any one criterion is met].
One of the following modifiers can be appended:
• +n - specify that the previous value minus the current column value must exceed gap for
a break to be imposed.
• +p - specify that the current value minus the previous value must exceed gap for a break
to be imposed.
Default imposes breaks based on the absolute value of the difference between the current
and previous value. Note: For x|y|z with time data the unit is instead controlled by
TIME_UNIT. Note: GMT has other mechanisms that can determine line segmentation, including
segments defined by multiple segment header records (see the cookbook chapter GMT File
Formats) or segments defined by NaN values when IO_NAN_RECORDS is set to pass [default
skips NaN values].
The -h option
Syntax
-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle]
Specify that input and/or output file(s) have n header records [default is 0].
Description
Specify that the primary input file(s) has n header record(s). The default number of
header records is set by IO_N_HEADER_RECS [default is 0]. Use -hi if only the primary
input data should have header records [Default will write out header records if the input
data have them]. For output you may control the writing of header records using -h[o] and
the optional modifiers:
• +d to remove existing header records.
• +c to add a header comment with column names to the output [default is no column names].
• +m to add a segment header segheader to the output after the header block [default is no
segment header].
• +r to add a remark comment to the output [default is no comment]. The remark string may
contain \n to indicate line-breaks.
• +t to add a title comment to the output [default is no title]. The title string may
contain \n to indicate line-breaks.
Note: Blank lines and lines starting with # are always skipped. To use another leading
character for indicating header records, set IO_HEADER_MARKER. With -h in effect the first
n records are taken verbatim as headers and not skipped even if any is starting with #.
Note: If used with native binary data (using -b) we interpret n to instead mean the number
of bytes to skip on input or pad on output.
The -i option
Syntax
-icols[+l][+ddivisor][+sscale|d|k][+ooffset][,…][,t[word]]
Select specific data columns for primary input, in arbitrary order.
Description
The -i option allows you to specify which input file physical data columns to use and in
what order. Specify individual columns or column ranges in the format start[:inc]:stop,
where inc defaults to 1 if not specified, separated by commas [Default reads all columns
in order, starting with the first column (i.e., column 0)]. Columns can be repeated. The
chosen data columns will be used as given and columns not listed will be skipped.
Optionally, append one of the following modifiers to any column or column range to
transform the input columns:
• +l to take the log10 of the input values.
• +d to divide the input values by the factor divisor [default is 1].
• +s to multiply the input values by the factor scale [default is 1]. Alternatively, give
d to convert km to degrees or k to convert degrees to km using PROJ_MEAN_RADIUS.
• +o to add the given offset to the input values [default is 0].
Note: The order of these optional transformations are (1) take log10, (2) scale or divide,
and (3) add offset. To read from a given column until the end of the record, leave off
stop when specifying the column range. Normally, any trailing text will be read but when
-i is used to specify specific input columns you must explicitly append the “column” t to
retain the trailing text internally. To only ingest a single word from the trailing text,
append the word number (first word is 0). If your trailing text columns start with a
valid number and you want to ensure the content from column col to the end of the record
will be considered trailing text, use -fcols. Finally, -in will simply read the numerical
input and skip any trailing text. Note: Using -i assumes there are as many numerical
columns as implied in -i, so if you have a mix of numerical and text columns we will forge
ahead and read those text columns (most likely returned as NaNs) and return your selection
as numerical values. The default (no -i provided) will examine the record and stop
conversions when the record switches to trailing text.
The -j option (spherical distance calculations)
Syntax
-je|f|g
Determine how spherical distances are calculated in modules that support this
[Default is -jg].
Description
GMT has different ways to compute distances on planetary bodies:
• -jg to perform great circle distance calculations, with parameters such as distance
increments or radii compared against calculated great circle distances [Default is -jg].
• -jf to select Flat Earth mode, which gives a more approximate but faster result.
• -je to select ellipsoidal (or geodesic) mode for the highest precision and slowest
calculation time.
Note: All spherical distance calculations depend on the current ellipsoid (‐
PROJ_ELLIPSOID), the definition of the mean radius (PROJ_MEAN_RADIUS), and the
specification of latitude type (PROJ_AUX_LATITUDE). Geodesic distance calculations is
also controlled by method (PROJ_GEODESIC).
The -l option
Syntax
-l[label][+Dpen][+Ggap][+Hheader][+L[code/]text][+Ncols][+Ssize[/height]][+V[pen]][+ffont][+gfill][+jjustify][+ooff][+ppen][+sscale][+wwidth]
Add a map legend entry to the session legend information file for the current plot.
Description
The -l option is used to automatically build the specfile that is read by the legend
module to create map or plot legends. This allows detailed and complicated legends that
mix a variety of items, such as symbols, free text, colorbars, scales, images, and more.
Yet, a simple legend will suffice for the vast majority of plots displaying symbols or
lines. Optionally, append a text label to describe the entry. The following modifiers are
supported to allow further changes to the legend that is built by legend (upper-case
modifiers reflect legend codes described in legend, which provides more details and
customization):
• +D to draw a horizontal line in the given pen before the legend entry is placed [default
is no line].
• +G to add the vertical space specified by gap [default is no extra space].
• +H to add the specified legend header [default is no header].
• +L to set a line text. Optionally, prepend a horizontal justification code L(eft),
C(enter), or R(ight) for text [default is C].
• +N to change the number of columns used to set the following legend items to cols
[default is 1].
• +S to override the size of the current symbol for the legend or set a height if plotting
a line or contour [default uses the same symbol as plotted].
• +V to start and +vpen to stop drawing vertical line from previous to current horizontal
line [default is no vertical line].
• +f to set the font used for the legend header [default is FONT_TITLE].
• +g to set the fill used for the legend frame [default is white].
• +j to set placement of the legend using the two-character justification code justify
[default is TR].
• +o to set the offset from legend frame to anchor point [default is 0.2c].
• +p to set the pen used for the legend frame [default is 1p].
• +s to resize all symbol and length sizes in the legend by scale [default is no scaling].
• +w to set legend frame width [default is auto].
Note: Default pen is given by MAP_DEFAULT_PEN. Note: +H, +g, +j, +o, +p, +w, and +s will
only take effect if appended to the very first -l option for a plot. The +N modifier, if
appended to the first -l option, affects the legend width (unless set via +w); otherwise
it just subdivides the available width among the specified columns. If legend is not
called explicitly we will call it implicitly when finishing the plot via end. Note: If
auto-coloring is used for pens or fills and -l is set then label may contain a C-format
for integers (e.g., %3.3d) or just # and we will use the sequence number with the format
to build the label entries. Alternatively, give a list of comma-separated labels, or give
no label if your segment headers contain label settings. Note: Due to this mechanism, if
your single label actually contains commas, you must replace these with the octal code for
a comma (\054).
The -n option
Syntax
-n[b|c|l|n][+a][+bg|p|n][+c][+tthreshold]
Select grid interpolation mode.
Description
The -n option controls parameters used for 2-D grids resampling [default is bicubic
interpolation with antialiasing and a threshold of 0.5, using geographic (if grid is known
to be geographic) or natural boundary conditions]. Append one of the following to select
the type of spline used:
• b to use B-spline smoothing.
• c to use bicubic interpolation.
• l to use bilinear interpolation.
• n to use nearest-neighbor value (for example to plot categorical data).
The following modifiers are supported:
• +a to switch off antialiasing (where supported) [default uses antialiasing].
• +b to override boundary conditions used, by appending g for geographic, p for periodic,
or n for natural boundary conditions. For the latter two you may append x or y to
specify just one direction, otherwise both are assumed.
• +c to clip the interpolated grid to input z-min/z-max [default may exceed limits].
• +t to control how close to nodes with NaNs the interpolation will go based on threshold.
A threshold of 1.0 requires all (4 or 16) nodes involved in interpolation to be non-NaN.
For example, 0.5 will interpolate about half way from a non-NaN value and 0.1 will go
about 90% of the way [default is 0.5].
The -o option
Syntax
-ocols[,…][,t[word]]
Select specific data columns for primary output, in arbitrary order.
Description
The -o option allows you to specify which output file physical data columns to use and in
what order. Specify individual columns or column ranges in the format start[:inc]:stop,
where inc defaults to 1 if not specified, separated by commas [Default writes all columns
in order, starting with the first column (i.e., column 0)]. Columns can be repeated. The
chosen data columns will be used as given and columns not listed will be skipped. To write
from a given column until the end of the record, leave off stop when specifying the column
range.
Normally, any trailing text in the internal records will be included in the output, but
when -o is used to specify specific columns you must explicitly append the extra “column”
t to include the trailing text on output. To only select a single word from the trailing
text, append the word number (first word is 0). Finally, -on will simply write the
numerical output only and skip any trailing text, while -ot will only output the trailing
text (or selected word). Note: If -i is also used then columns given to -o correspond to
the order after the -i selection has taken place and not the columns in the original
record.
The -p option
Syntax
-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]
Select perspective view and set the azimuth and elevation of the viewpoint.
Description
All plotting programs that normally produce a flat, two-dimensional illustration can be
told to view this flat illustration from a particular vantage point, resulting in a
perspective view. You can select perspective view with the -p option by setting the
azimuth (azim) of the viewpoint [Default is 180]. The following modifiers are supported:
• x|y|z to plot against the “wall” x = level (using x) or y = level (using y) or the
horizontal plain (using z) [default is z].
• /elev to set the elevation of the viewport [Default is 90].
• /zlevel to indicate the z-level at which all 2D material, like the plot frame, is
plotted (only valid when -p is used in consort with -Jz or -JZ) [Default is at the
bottom of the z-axis].
For frames used for animation, we fix the center of your data domain. Specify another
center using one of the following modifiers:
• +w to project lon0/lat0 (and z0 if applicable) to the center of the page size.
• +v to specify the coordinates of the projected 2-D view point as x0/y0.
When -p is used without any further arguments, the values from the last use of -p in a
previous GMT command will be used (in modern mode this also supplies the previous -Jz or
-JZ if doing a 3-D region). Alternatively, you can perform a simple rotation about the
z-axis by just giving the rotation angle. Optionally, use +v or +w to select another axis
location than the plot origin.
The -q option
Syntax
-q[i|o][~]rows|limits[+ccol][+a|t|s]
Select specific data rows to be read and/or written.
Description
The -q option is used to select specific data rows to be read (using -q or -qi) or written
(using -qo) [Default is all rows]. Specify individual rows or row ranges in the format
start[:inc]:stop, where inc defaults to 1 if not specified, separated by commas [Default
reads and writes all rows in order, starting with the first row (i.e., row 0)]. To read
(or write) from a given row until the end of the data, leave off stop. To select all the
rows not specified by the given ranges, prepend the selected rows with a leading ~. Append
one of the following modifiers to control how the rows are counted [Default is +a]:
• +a to count all rows in the data set.
• +t to reset the count at the start of each table.
• +s to reset the count at the start of each segment.
Alternatively, use +ccol to indicate that the arguments instead are min/max data limits
for the values in column col. With +ccol, only rows whose data for the given column col
are within the range(s) given by the min/max limits are read (with -qi) or written (with
-qo). Note: Because arguments may contain colons or be negative, you must specify min/max
instead of start[:inc]:stop. If min or max is not given we default to -infinity and +
infinity, respectively (e.g., -qo50/+c2 will only write records whose z-values (in 3rd
column) is ≥ 50 while -qo/50+c2 will only write records whose z-values is ≤ 50).
Note: Header records do not increase the row counters; only data records do.
The -r option (grid registration)
Syntax
-r[g|p]
Select gridline or pixel node registration.
Description
All 2-D grids in GMT have their nodes organized in one of two ways, known as gridline and
pixel registration. The GMT default is gridline registration (-rg); programs that allow
for the creation of grids can use the -r option (or -rp) to select pixel registration
instead.
Most observed data tend to be in gridline registration while processed data sometime may
be distributed in pixel registration. While you may convert between the two registrations
this conversion looses the Nyquist frequency and dampens the other high frequencies. It is
best to avoid any registration conversion if you can help it. Planning ahead may be
important. (Node registrations are defined in Section Grid registration: The -r option of
the GMT Technical Reference and Cookbook.)
The -s option
Syntax
-s[cols][+a][+r]
Suppress output of data records whose z-value(s) equal NaN.
Description
The -s option can be used to suppress output for records whose z-value equals NaN [default
outputs all records]. Optionally, supply a comma-separated list of all columns or column
ranges to consider for this NaN test [default only considers the third data column (i.e.,
cols = 2)]. Column ranges must be given in the format start[:inc]:stop, where inc defaults
to 1 if not specified. The following modifiers are supported:
• +r to reverse the suppression, i.e., only output the records whose z-value equals NaN.
• +a to suppress the output of the record if just one or more of the columns equal NaN
[default skips record only if values in all specified cols equal NaN]
The -t option
Syntax
-ttransp[/transp2][+f|s]
Set transparency level(s) for an overlay.
Description
The -t option allows you to change the transparency level for the current overlay by
appending the transp percentage in the 0-100 range [default is 0 (i.e., opaque)].
Normally, transp applies to both fill and stroke, but you can limit the transparency to
one of them by appending +f or +s for fill or stroke, respectively. Alternatively, append
/transp2 to set separate transparencies for fills and strokes.
Transparency may also be controlled on a feature by feature basis when setting color or
fill (see the cookbook section Specifying area fill attributes). Note: The modules plot,
plot3d, and text can all change transparency on a record-by-record basis if -t is given
without argument and the input file supplies variable transparencies as the last numerical
column value(s). Note: The transparency is only visible when PDF or raster format output
is selected because the PostScript language does not support transparency. Only the PNG
format selection adds a transparency layer in the image (for further processing).
The -w option
Syntax
-wy|a|w|d|h|m|s|cperiod[/phase][+ccol]
Convert input records to a cyclical coordinate.
Description
The -w option converts the input x-coordinate to a cyclical coordinate, or a different
input column if selected via the +c modifier. Temporal data (i.e., regular time series)
can be analyzed for periods via standard spectral analysis, such as offered by spectrum1d
and grdfft. However, it is often of interest to examine aspects of such periodicities in
the time domain. To enable such analyses we need to convert our monotonically increasing
time coordinates to periodic or cyclic coordinates so that data from many cycles can be
stacked, binned, displayed in histograms, etc. The conversion from input x, y, or z
coordinates to wrapped, periodic coordinates follows the simple equation
t' = (t - \tau) \;\mathrm{mod}\; T,
where t is the input coordinate, \tau is a phase-shift [Default is zero], and T is the
desired period for the modulus operator, yielding cyclic coordinates t'. GMT offers many
standard time cycles in prescribed units plus a custom cycle for other types of Cartesian
coordinates. The table below shows the values for units, phase and period that are
prescribed and only requires the user to specify the corresponding wrapping code
(y|a|w|d|h|m|s|cperiod[/phase]):
┌─────┬──────────────────┬──────────┬───────┬───────┐
│Code │ Purpose (unit) │ Period │ Phase │ Range │
├─────┼──────────────────┼──────────┼───────┼───────┤
│y │ Yearly cycle │ 1 year │ 0 │ 0–1 │
│ │ (normalized) │ │ │ │
├─────┼──────────────────┼──────────┼───────┼───────┤
│a │ Annual cycle │ 1 year │ 0 │ 0–12 │
│ │ (month) │ │ │ │
├─────┼──────────────────┼──────────┼───────┼───────┤
│w │ Weekly cycle │ 1 week │ 0 │ 0–7 │
│ │ (day) │ │ │ │
├─────┼──────────────────┼──────────┼───────┼───────┤
│d │ Daily cycle │ 1 day │ 0 │ 0–24 │
│ │ (hour) │ │ │ │
├─────┼──────────────────┼──────────┼───────┼───────┤
│h │ Hourly cycle │ 1 hour │ 0 │ 0–60 │
│ │ (minute) │ │ │ │
├─────┼──────────────────┼──────────┼───────┼───────┤
│m │ Minute cycle │ 1 minute │ 0 │ 0–60 │
│ │ (second) │ │ │ │
├─────┼──────────────────┼──────────┼───────┼───────┤
│s │ Second cycle │ 1 second │ 0 │ 0–1 │
│ │ (second) │ │ │ │
├─────┼──────────────────┼──────────┼───────┼───────┤
│c │ Custom cycle │ T │ \tau │ 0–1 │
│ │ (normalized) │ │ │ │
└─────┴──────────────────┴──────────┴───────┴───────┘
Optionally, append +ccol to select the input column with the coordinates to be wrapped,
[default col is 0, i.e., the first column]. If the custom cycle c is chosen then you must
also supply the period and optionally any phase [default is 0] in the same units of your
data (i.e., no units should be appended to -w).
Note: Coordinates for w in the range 0-1 correspond to the first day of the week [Monday]
but can be changed via TIME_WEEK_START. Note: If a temporal cycle is indicated then we
implicitly set -f to indicate absolute time (unless already set separately). See the
cookbook section Examining data cycles: The -w option for examples.
The -x option
Syntax
-x[[-]n]
Specify the number of active cores to be used in any OpenMP-enabled multi-threaded
algorithms.
Description
The -x option limits the number of cores to be used in any OpenMP-enabled multi-threaded
algorithms [default is to use all available cores]. Append n to only use n cores (if too
large it will be truncated to the maximum cores available). Finally, give a negative n to
select (all - n) cores (or at least 1 if n equals or exceeds all). The -x option is only
available to GMT modules compiled with OpenMP support, with the exception of movie and
batch which handle their own parallel execution.
The -: option
Syntax
-:[i|o]
Swap 1st and 2nd column on input and/or output.
Description The -: option swaps the 1st and 2nd column on input and output [default is no
swapping]. Append i to select input only or o to select output only [default affects
both]. This option is typically used to handle (latitude, longitude) files; see also Input
columns selection: The -i option. 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.
Module help and configuration
-^ or just -
Print a short message about the syntax of the command, then exit (Note: on Windows
just use -).
-+ or just +
Print an extensive usage (help) message, including the explanation of any
module-specific option (but not the GMT common options), then exit.
-? or no arguments
Print a complete usage (help) message, including the explanation of all options,
then exit.
--PAR=value
Temporarily override a GMT default setting; repeatable. See gmt.conf for
parameters.
Specifying Color
color The color of lines, areas and patterns can be specified by a valid color name, by a
gray shade (in the range 0-255), by a decimal color triplet RGB (r/g/b, each in the
range 0–255), by hue-saturation-value HSV (h-s-v, with ranges of 0-360, 0-1, 0-1),
by cyan/magenta/yellow/black CMYK (c/m/y/k, each in the range 0-1), or by a
hexadecimal color code (#rrggbb, as used in HTML). For a transparency effect,
append @transparency in the 0–100 percent range [Default is 0 (opaque)] Note:
Transparency effects are only visible when PDF or a raster graphics format is
selected. See Explanation of color codes in GMT for more information and a full
list of color names.
Specifying Fill
fill The attribute fill specifies the solid shade or solid color (see Specifying Color
above) or the pattern used for filling polygons. Patterns are specified as
ppattern, where pattern set the number of the built-in pattern (1-90) or the name
of a raster image file. The optional +rdpi sets the resolution of the image [300].
For 1-bit rasters: use upper case P for inverse video, or append +fcolor and/or
+bcolor to specify fore- and background colors (no color given means transparency).
See Predefined Bit and Hachure Patterns in GMT for information on individual
built-in patterns.
Specifying Fonts
font 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
=~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 (plus 4 optional Japanese fonts) are:
0. Helvetica
1. Helvetica-Bold
2. Helvetica-Oblique
3. Helvetica-BoldOblique
4. Times-Roman
5. Times-Bold
6. Times-Italic
7. Times-BoldItalic
8. Courier
9. Courier-Bold
10. Courier-Oblique
11. Courier-BoldOblique
12. Symbol
13. AvantGarde-Book
14. AvantGarde-BookOblique
15. AvantGarde-Demi
16. AvantGarde-DemiOblique
17. Bookman-Demi
18. Bookman-DemiItalic
19. Bookman-Light
20. Bookman-LightItalic
21. Helvetica-Narrow
22. Helvetica-Narrow-Bold
23. Helvetica-Narrow-Oblique
24. Helvetica-Narrow-BoldOblique
25. NewCenturySchlbk-Roman
26. NewCenturySchlbk-Italic
27. NewCenturySchlbk-Bold
28. NewCenturySchlbk-BoldItalic
29. Palatino-Roman
30. Palatino-Italic
31. Palatino-Bold
32. Palatino-BoldItalic
33. ZapfChancery-MediumItalic
34. ZapfDingbats
35. Ryumin-Light-EUC-H
36. Ryumin-Light-EUC-V
37. GothicBBB-Medium-EUC-H
38. GothicBBB-Medium-EUC-V
Specifying Pens
pen The attributes of lines and symbol outlines as defined by pen is a comma-delimited
list of width, color and style, each of which is optional. width can be indicated
as a measure (in points (this is the default), centimeters, or inches) or as faint,
default, thin[ner|nest], thick[er|est], fat[ter|test], or wide. color specifies a
gray shade or color (see Specifying Color above). style can be any of ‘solid’,
‘dashed’ ‘dotted’, ‘dashdot’, or ‘dotdash’, or a custom combination of dashes ‘-’
and dots ‘.’. If any of the attributes is omitted their default or previous setting
will be retained. See GMT Cookbook & Technical Reference Specifying pen attributes
for more information.
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
specifications 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 COARDS-compliant netCDF files and Grid file format
specifications 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
2022, The GMT Team