GMT(1)

📦
version 6.6.0 · 7 versions
, in ubuntu resolute

💖 NAME 💖

gmt — the Generic Mapping Tools data processing and display software package. it's giving legend behavior, no cap 🫶

🌸 INTRODUCTION 🌸

GMT is a whole collection of freely available command-line tools under the GNU LGPL, and bestie, it lets you 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, \log_{10}, and power scaling is supported, plus 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. iconic, honestly. ✨

🦋 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). 💀 choose wisely bestie
  • 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. main character energy fr fr 👑
  • 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. Appending the optional directive show automatically opens the illustration in the default viewer. 🌈

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. cite ur queen 💜
  • --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-date — Show GMT binary building date and exit.
  • --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 Technical Reference.

not me forgetting to source the completion file and then tab-tab-tabbing into the void 😭

👑 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. ur own modules?? slay 🫶

⭐ 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 -ggaps -hheaders -iflags -jflags -l‐
flags -nflags -oflags -pflags -qflags -rreg -sflags -ttransp -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. (yes bestie, zero spaces, we're not doing that) 💅

🔥 The -B option 🔥

Syntax

-B[p|s]parameters

Set map boundary frame and axes attributes. (See technical reference).

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 directives and 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|z code (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.
  • +g fill 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. 🎨
  • +x fill to paint the yz plane with a color specified by fill [default is no fill].
  • +y fill to paint the xz plane with a color specified by fill [default is no fill].
  • +z fill 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]. 😭 the struggle is real
  • +o lon/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. Note: One cannot specify oblique gridlines for non-geographic projections as well as the oblique Mercator projection. 🚫
okay bestie that's the frame settings, and yes there is more coming — do not close the tab 💖
  • +n — no frame, no annotations, nothing. Zero. Nada. [default is controlled by axes]
  • +ttitle — places the string in title centered right above the plot frame. [default is no title]
  • +ssubtitle — needs +ttitle to even exist (it's giving very dependent), and it drops subtitle just beneath the title. [default is no subtitle]
💡 ok bestie listen: both +ttitle and +ssubtitle can go over multiple lines — just break them up with the markers @^ or <break>. And if you wanna sneak LaTeX into a single-line title or subtitle, wrap the expression in @[ markers (or alternatively <math> ... </math>) — but heads up, that requires latex and dvips to be installed. More deets live in the Using LaTeX Expressions in GMT chapter.

✨ Axes settings ✨

The Axes settings arrive looking like this:

-B[p|s][x|y|z]intervals[+aangle|n|p][+f][+llabel][+pprefix][+uunit]

but you can also split it into two separate invocations if that's clearer for you, 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][00|000]intervals
-B0

So here are all the directives and modifiers you can tack onto -B to control those Axes settings:

  • p|s — decides 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 they're available for geographic axes too. Real talk: primary = the annotations closest to the axis, secondary = the ones further away. So primary annotation-, tick-, and gridline-intervals must be shorter than their secondary counterparts. And the terms "primary" and "secondary" do not imply any hierarchical order of units — the "primary" annotation interval is usually smaller (think days) while the "secondary" one is typically larger (think months).
  • x|y|z — sets which axes the modifiers apply to [default is xy]. If you want different annotation intervals or labels for the various axes, you have to repeat the B option once per axis. For a 3-D plot with the -p and -Jz options in play, -Bz can be used to give settings for the vertical axis.
  • +e — skips 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: fancy annotations with W|E|S|N suffixes encoding the sign. Cute and informative.
  • +l|+Llabel — for Cartesian plots only: add a label to an axis. +l uses the default label orientation; +L forces a horizontal label for y-axes, which is a lifesaver for very short labels.
  • +s|Sseclabel — for Cartesian plots only: 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, again, is perfect for very short labels.
  • +pprefix — for Cartesian plots only: 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 Cartesian plots only: 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 Cartesian plots only: plot slanted annotations, where angle is measured with respect to the horizontal and must be in the range -90 <= angle <= 90. +an is shorthand for normal (i.e., +a90) [Default for y-axis] and +ap is shorthand for parallel (i.e., +a0) annotations [Default for x-axis]. These defaults can be changed via MAP_ANNOT_ORTHO.
  • 0 — this suppresses all annotations and tick marks. Super useful when you want a map with no annotations, no grid, no ticks, but you still want a frame plotted using a line set by MAP_FRAME_PEN.
  • 00 — plots a frame with annotations, ticks, etc., but uses a zero-width line to draw the frame (0-width lines are lines that stay very thin no matter the zoom level).
  • 000 — plots annotations, ticks and grid lines (as you chose) but does not plot the frame lines. Note: this effect is only visible with png and pdf formats and is not guaranteed to work when you select only a subset of the axes (e.g., -B000ya30g30 is not working well).
  • intervals — defines the intervals for annotations and major tick spacing, minor tick spacing, and/or grid line spacing. Head to Intervals Specification for the formatting that goes with this modifier.
🎀 NOTE: to include LaTeX code as part of a label, enclose the expression with @[ markers (or alternatively <math> ... </math>). This 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 one long string containing everything passed to -B. Which means 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 a negative scale (in -Jx) or axis length (in -JX) to flip the direction of increasing coordinates (i.e., to make the y-axis positive down).

🦋 Intervals specification 🦋

The intervals specification is a concatenated string built out of substrings that look like

[a|f|g][stride][phase][unit]

The choice of a|f|g sets the axis item of interest — they're all detailed in the Table interval types below. Optionally, append phase to shift the annotations by that amount (positive or negative, and yes, the sign is 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.

Here's the interval types table, in list form because tables are not the vibe:

  • 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 whenever stride is not provided after a|f|g. That's genuinely so helpful for automated plots where the region isn't always the same, making it hard to figure out the right stride in advance. For example, -Bafg will select all three spacings automatically for both axes. For longitude–latitude plots, this keeps the spacing the same on both axes. You can also use -Bxafg -Byafg to auto-select them separately. But note: 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 lines 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, listed in the Table Units below. Almost all of these units are time-axis specific. However — plot twist — the d, m, and s units will be interpreted as arc degrees, minutes, and arc seconds respectively when a map projection is in effect.

The Table Units, again as a list:

  • 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 technical reference) (See projections table).

Description

okay bestie, buckle UP, because now we pick the actual projection and this is where GMT really gets to show off 💅

Select map projection. The very first character of the parameters you pass is what decides which projection you're getting. And here's the little twist that trips people up: if that character is upper case, then the argument(s) you supplied as scale(s) get read as the map width (or axis lengths, depending) — otherwise your scale argument is read as the actual map scale (and each projection defines what "scale" even means for it, so peep the deets below).

The measurement unit — we're calling it UNIT down here — is cm, inch, or point, and it depends on the PROJ_LENGTH_UNIT setting in gmt.conf. But you can absolutely override that on the command line by appending c, i, or p to your scale or width values. Want a different dimension than width? Append +dh, +du, or +dl to the given width to set the map height, the maximum (upper) dimension, or the minimum (lower) dimension, respectively. [Default is +dw for width, iykyk.]

If the central meridian is an optional parameter and you just... don't give it, then the center of the longitude range from your -R option gets used instead. And the default standard parallel is the equator, periodt.

Oh and the ellipsoid? fully user-definable. There are 73 commonly used ellipsoids and spheroids supported rn, and you can also roll your own custom ellipsoid parameters. [Default is WGS-84.] ✨

A few GMT parameters can mess with your projection too: PROJ_ELLIPSOID, GMT_INTERPOLANT, PROJ_SCALE_FACTOR, and PROJ_LENGTH_UNIT — go read the gmt.conf man page for the details, bestie.

So: choose one of the following projections and append the required parameters. (And just so you're not confused — the E or C after projection names stands for Equal-Area and Conformal, respectively.)

🌸 CYLINDRICAL PROJECTIONS 🌸

  • -Jc|Clon0/lat0/scale|width — Cassini. Give the projection center lon0/lat0 and either the scale (with -Jc; as 1:xxxx or plot-units/degree) or the width (with -JC; in plot-units).
  • -Jcyl_stere|Cyl_stere/[lon0/[lat0/]]scale|width — Cylindrical Stereographic. Give the central meridian lon0 (optional), the standard parallel lat0 (optional), and either the scale along the parallel (with -Jcyl_stere; as 1:xxxx or plot-units/degree) or the width (with -JCyc_stere; in plot-units). The standard parallel is typically one of these cuties (but it can honestly 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 the scale (with -Jj; as 1:xxxx or plot-units/degree) or the width (with -JJ; in plot-units).
  • -Jm|M[lon0/[lat0/]]scale|width — Mercator [C]. Give the central meridian lon0 (optional), the standard parallel lat0 (optional), and either the scale along the parallel (with -Jm; as 1:xxxx or plot-units/degree) or the 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 the projection center lon0/lat0, the azimuth of the oblique equator, and the scale or width
    • -Jo|O[b|B]lon0/lat0/lon1/lat1/scale|width[+v] — set the projection center lon0/lat0, another point on the oblique equator lon1/lat1, and the scale or width
    • -Jo|O[c|C]lon0/lat0/lonp/latp/scale|width[+v] — set the projection center lon0/lat0, the pole of the oblique projection lonp/latp, and the scale or width

Give the scale along the oblique equator (with -Jo as 1:xxxx or plot-units/degree) or the width (with -JO in plot-units). Use upper-case A|B|C to remove the enforcement of a northern hemisphere pole. Append +v to let the oblique Equator align with the y-axis [default is the 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. Don't get caught slippin' on that one 💀
  • -Jq|Q[lon0/[lat0/]]scale|width — Cylindrical Equidistant. Give the central meridian lon0 (optional), the standard parallel lat0 (optional), and either the scale (with -Jq; as 1:xxxx or plot-units/degree) or the width (with -JQ; in plot-units). The standard parallel is typically one of these (but again, any value works):
    • 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, the central parallel lat0 (optional), and either the scale (with -Jt; as 1:xxxx or plot-units/degree) or the width (with -JT; in plot-units).
  • -Ju|Uzone/scale|width — UTM, a.k.a. Universal Transverse Mercator [C]. Give the UTM zone (A,B,1-60[C-X],Y,Z)) and either the scale (with -Ju; as 1:xxxx or plot-units/degree) or the width (with -JU; in plot-units). Zones: if C-X isn't 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), the standard parallel lat0 (optional), and either the scale (with -Jy; as 1:xxxx or plot-units/degree) or the width (with -JY; in plot-units). The standard parallel is typically one of these (you know the drill, any value is legal):
    • 50 — Balthasart
    • 45 — Gall
    • 37.0666 — Caster
    • 37.4 — Trystan Edwards
    • 37.5 — Hobo-Dyer
    • 30 — Behrman
    • 0 — Lambert (this is the default 🫶)

🎀 CONIC PROJECTIONS 🎀

  • -Jb|Blon0/lat0/lat1/lat2/scale|width — Albers [E]. Give the projection center lon0/lat0, two standard parallels lat1/lat2, and either the scale (with -Jb; as 1:xxxx or plot-units/degree) or the width (with -JB; in plot-units).
  • -Jd|Dlon0/lat0/lat1/lat2/scale|width — Conic Equidistant. Give the projection center lon0/lat0, two standard parallels lat1/lat2, and either the scale (with -Jd; as 1:xxxx or plot-units/degree) or the width (with -JD; in plot-units).
  • -Jl|Llon0/lat0/lat1/lat2/scale|width — Lambert [C]. Give the origin lon0/lat0, two standard parallels lat1/lat2, and the scale along these (with -Jl; as 1:xxxx or plot-units/degree) or the width (with -JL; in plot-units).
  • -Jpoly|Poly/[lon0/[lat0/]]scale|width — (American) Polyconic. Give the central meridian lon0 (optional), the reference parallel lat0 (optional, default = equator), and either the scale along the central meridian (with -Jpoly; as 1:xxxx or plot-units/degree) or the width (with -JPoly; in plot-units).

🦋 AZIMUTHAL PROJECTIONS 🦋

Heads up bestie: except for polar aspects, -Rw/e/s/n will get reset to -Rg. For smaller regions, use -Rxlleft/ylleft/xuright/yuright+r instead.

  • -Ja|Alon0/lat0[/horizon]scale|width — Lambert [E]. lon0/lat0 specifies the projection center. horizon specifies the max distance from the projection center (in degrees, <= 180, default 90). Give either the scale (with -Ja; as 1:xxxx or radius/lat, where radius is the distance in plot-units from the origin to the oblique latitude lat) or the 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 the projection center (in degrees, <= 180, default 180). Give the scale (with -Je; as 1:xxxx or radius/lat, where radius is the distance in plot-units from the origin to the oblique latitude lat) or the 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 the projection center (in degrees, < 90, default 60). Give the scale (with -Jf; as 1:xxxx or radius/lat, where radius is the distance in plot-units from the origin to the oblique latitude lat) or the 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 the projection center (in degrees, <= 90, default 90). Give the scale (with -Jg; as 1:xxxx or radius/lat, where radius is the distance in plot-units from the 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 the scale (with -Jg; as 1:xxxx or radius/lat, where radius is the distance in plot-units from the origin to the oblique latitude lat) or the width (with -JG; in plot-units). Several optional modifiers control the perspective:
    • +a sets the azimuth measured to the east of north of view [default 0].
    • +t sets the upward tilt of the plane of projection. If tilt is negative, then the viewpoint is centered on the horizon [default 0].
    • +v sets a restricted view: vwidth and vheight (in degrees) limits the view from the viewpoint [default is unrestricted].
    • +w sets the clockwise twist of the viewpoint (in degrees) [default 0].
    • +z sets the altitude of the viewer above sea level in kilometers [default is 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 the 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 the projection center (in degrees, < 180, default 90). Give the 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 the 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. (Yeah, that whole clause lives inside the parens, it's giving nested-parentheses chaos but we move.)

Or give the width (with -JS; in plot-units).

🌈 MISCELLANEOUS PROJECTIONS 🌈

  • -Jh|H[lon0/]scale|width — Hammer [E] 🔨✨. Drop in the central meridian lon0 (optional, she's chill like that) and then EITHER the scale along the equator (that's lowercase -Jh; write it as 1:xxxx or plot-units/degree) OR the width (that's uppercase -JH; in plot-units).
  • -Ji|I[lon0/]scale|width — Sinusoidal [E] 🌊. Same deal: central meridian lon0 is optional, then either the scale along the equator (lowercase -Ji; as 1:xxxx or plot-units/degree) or the width (uppercase -JI; in plot-units).
  • -Jk|Kf[lon0/]scale|width — Eckert IV [E] 🍀. Central meridian lon0 (optional) + either scale along equator (lowercase -Jk; as 1:xxxx or plot-units/degree) or width (uppercase -JK; in plot-units).
  • -Jk|K[s][lon0/]scale|width — Eckert VI [E] 🍀🍀. Yes bestie, same letter, extra flavor — there's an optional s in there. Give the central meridian lon0 (optional) and either the scale along equator (lowercase -Jk; as 1:xxxx or plot-units/degree) or the width (uppercase -JK; in plot-units).
  • -Jn|N[lon0/]scale|width — Robinson 🌍. Central meridian lon0 (optional), plus either scale along equator (lowercase -Jn; as 1:xxxx or plot-units/degree) or width (uppercase -JN; in plot-units).
  • -Jr|R[lon0/]scale|width — Winkel Tripel 🌐. Central meridian lon0 (optional) and either the scale along equator (lowercase -Jr; as 1:xxxx or plot-units/degree) or the width (uppercase -JR; in plot-units).
  • -Jv|V[lon0/]scale|width — Van der Grinten 💫. Central meridian lon0 (optional) and either scale along equator (lowercase -Jv; as 1:xxxx or plot-units/degree) or width (uppercase -JV; in plot-units).
  • -Jw|W[lon0/]scale|width — Mollweide [E] 🥚. Central meridian lon0 (optional), then either the scale along equator (lowercase -Jw; as 1:xxxx or plot-units/degree) or the width (uppercase -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 — says theta is azimuth CW from North instead of direction CCW from East [Default is CCW from East].
  • +f — flips the radial direction so it points inwards 💘. Append e to say that r represents elevations in degrees (this requires south >= 0 and north <= 90), append p to select the current planetary radius (determined by PROJ_ELLIPSOID) as the maximum radius [default is north], or append radius to specify a custom radius.
  • +kkind — sets the annotation kind to be longitudes (x) or latitudes (y) [Default is unspecified angles].
  • +roffset — includes 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 — annotates 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 it's 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 (like, to have y be positive down, iykyk 🔄). 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 \log_{10} 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. (Memory queen behavior 💅)

  • -Jz|Zparameters — Set z-axis scaling; same syntax as -Jx. No cap, z is just x but vertical ✨
  • -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. 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 😭 iconic.

While for point and grid conversions done by mapproject and grdproject we can use all PROJ projections, the situation 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 technical reference).

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). Whole planet, one flag, slay 🌏
  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., -RNO) or the full country name (e.g., -RNorway). To select a state within a country (if available), append .state (e.g, -RUS.TX). 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 — okay so justify here is a two-character glow-up: it's a combo of L|C|R (left, center, right) and T|M|B (top, middle, bottom) — so like BL for lower left, bestie. 💅 That two-char code tells you which point on a rectangular grid region the x0/y0 coordinates are pointing at, and then the grid dimensions nx and ny get paired up with the grid spacings you hand over via -I to build the region. This method is your girl when you're creating grids. For example, -RCM25/25/50/50 specifies a 50x50 grid centered on 25,25. Slay. ✨
  8. -Rxmin/xmax/ymin/ymax/zmin/zmax — this one is for perspective views, specifically with -Jz and the -p option, where the z-range (zmin/zmax) gets appended to the first method to indicate the third dimension. Important: this is not used for -p without -Jz — in that case a perspective view of the place is plotted with no third dimension. Periodt.
  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. Okay noted. 🦋

🌸 The -U option 🌸

Syntax

-U[label|+c][+jjustify][+odx[/dy]][+ttext]

Draw GMT time stamp logo on plot. (See technical reference).

Description

The -U option draws the GMT system time stamp on the plot. You may provide an optional label text string written to the right side of the time stamp (and it must be surrounded by double quotes if it contains spaces, no cap).

Several modifiers are supported:

  • +c — Plot the current command string. 👑
  • +j — Append 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].
  • +o — Give dx[/dy] to offset the anchor point for the time stamp by dx and optionally dy (if different than dx).
  • +t — Replace the UNIX time stamp with a custom text instead (< 64 characters). Place multi-word text in quotes and let +t be the last modifier used. 💖

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

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

✨ The -X -Y options ✨

Syntax

-X[a|c|f|r][xshift]

Shift plot origin. (See technical reference).

-Y[a|c|f|r][yshift]

Shift plot origin. (See technical reference).

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 directives are supported [default is r]:

  • a — Prepend to shift the origin back to the original position after plotting.
  • c — Prepend to center the plot on the center of the paper (optionally add a shift) (classic mode only).
  • f — Prepend to shift the origin relative to the fixed lower left (classic mode only).
  • r — Prepend to move the origin relative to its current location.
Note: Directives c and f are only available in classic mode. 🚨

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 way that everything just stacks up? iconic. 🔥

🦋 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. Notes: (1) col = 0 is the first data column. (2) 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 — 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 the native binary format for table output 💾. Your record has to be one or more groups shaped like [ncols][type][w], where ncols is how many consecutive data columns share that type, and type has to be one of c, u, h, H, i, I, l, L, f, or d [that last one is the Default] — peep the -bi types for what each of those actually means. Wanna force byte-swapping on a group? Just slap a w at the end of it. And for a mixed-type output record, keep appending extra comma-separated groups (no space between them, bestie, the commas are doing all the work). These modifiers are in the building:

  • +b | +l — says the entire data file should be written big-endian or little-endian respectively. Pick your fighter.

If you don't specify ncols, we just assume type applies to all the columns and that ncols is implied by whatever the program's default output is. And a heads up: NetCDF file output is not supported 🙅‍♀️.

The -c option 🎯

Syntax

-c[row,col|index]

Description

So -c either moves the plotting focus to the next panel in the sequence (by row or by column, whichever subplot's -A option set up), or you can straight up name the row,col or the 1-D index of the panel you want. This is for when you're using subplot to build a matrix layout out of a bunch of individual panels. Heads up though: -c is only allowed when you're in subplot mode. And if you don't give a -c for the very first subplot, we default to row=col=index=0, aka the upper left panel, the main character spot 👑. Note: row, col, and index all start at 0, no cap.

The -d option 🕳️

Syntax

-di|onodata[+ccol]

Description

The -d option lets your hand-rolled missing-data values get translated into official GMT NaN values. Inside GMT, every missing value is represented by the IEEE NaN. But sometimes user data decides to denote missing data with some wild unlikely number (looking at you, -99999) 🙈. GMT genuinely cannot guess what your special missing value is, so -d is how you tell it: replace these with NaNs. And it works both ways — -d can also swap all the NaNs out for your chosen nodata value, if your GMT output needs to conform to that kind of requirement.

  • For input only, use -dinodata to examine all input columns after the first two. If any item equals nodata, that value gets interpreted as a missing data item and substituted with NaN.
  • For output only, use -donodata to examine all output columns. If any item equals NaN, that NaN gets substituted with the chosen missing data value, nodata.

Use the +c modifier to override the starting column used for these examinations — [2 for input, 0 for output].

The -e option 🔍

Syntax

-e[~]"pattern" | -e[~]/regexp/[i]

Description

The -e option is a built-in pattern scanner that only lets through records matching the pattern or regular expression you gave — whereas modules that read ASCII tables would normally just chomp through all the data records. You can also flip the whole test with -e~ to only pass records that do not match. The test doesn't get applied to header or segment headers, jsyk. And if your pattern happens to start with ~, you're gonna have to escape that character with a backslash [Default accepts all data records, no notes]. For matching against extended regular expressions, wrap the expression in slashes. Append i for case-insensitive matching, as a treat. Wanna hand over a whole list of patterns? Give +ffile with one pattern per line. And if you need a single pattern that starts with +f, escape it with a backslash. Note: -e is not allowed if -b selects binary input. Periodt.

The -f option 🧭

Syntax

-f[i|o]colinfo

Description

The -f option says what kind of data each input or output column holds — for when you don't need map projections. Optionally append i or o to make it apply only to input or only to output respectively [Default applies to both]. Then append a text string with info about each column (or range of columns), separated by commas. Each group kicks off with the column number (0 is the first column) followed by one of:

  • x — longitude
  • y — latitude
  • T — absolute calendar time
  • t — relative time in the chosen TIME_UNIT since TIME_EPOCH
  • d — dimension
  • s — trailing text

If a bunch of consecutive columns share the same format, you can specify a range instead of naming one at a time. Column ranges have to be written as start[:inc]:stop, where inc defaults to 1 if you don't say. So like, if our input file has geographic coordinates (latitude, longitude) with absolute calendar coordinates sitting in columns 3 and 4, we'd write fi0y,1x,3:4T. Every other column just gets assumed to be the default (floating point) format and doesn't need to be set individually. Notes: (1) You can also say that all items from a given column through to the end of the record count as trailing text by giving the code s (for string). Only the last group is allowed to set s. (2) Types T and s can only be used with ASCII data sets.

There are three shorthand options for common selections, and they are iconic:

  • -f[i|o]g means -f[i|o]0x,1y (i.e., geographic coordinates)
  • -f[i|o]c means -f[i|o]0:1f (i.e., Cartesian coordinates)

A first special use of -f is to select -fp[unit], which requires -J and -R and lets you feed projected map coordinates (like UTM meters) in as data input. Those coordinates get automatically inverted back to longitude, latitude during the data import — so convenient. Optionally append a length unit (see the table distance units) [default is meter]. The second special case is -fa. We use this when reading a file whose first column is plain text (and NO date or time) followed by numeric records. Normally a file like that would just give you a "Selection led to no output columns" error 😭 because the file got interpreted as being made only of text (i.,e., no numbers). Or even worse, only part of the file gets read. The -fa option forces that first column to be ignored (output as NaN) and the remaining records get parsed normally. You can add -i1: to fully drop that first column while reading. For more info, see the Sections Input data formats and Output data formats.

The -g option ✂️

Syntax

-gx|y|z|d|X|Y|Dgap[u][+a][+ccol][+n|p]

Description

The -g option detects gaps based on one or more criteria. Repeat the option to specify multiple criteria. Each criterion uses one of the x|y|z|d|X|Y|D directives. The upper-case directives mean the criterion should be applied to the projected coordinates, for modules that map data to map coordinates.

  • x|X — define a gap when there's a big enough change in the x coordinates (upper case to use projected coordinates).
  • y|Y — define a gap when there's a big enough change in the y coordinates (upper case to use projected coordinates).
  • z — define a gap when there's a big enough change in the z data. Use +ccol to change the z data column [Default col is 2, i.e., the 3rd column].
  • d|D — define a gap when there's a big 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 these 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. Notes: (1) For x|y|z with time data, the unit is instead controlled by TIME_UNIT. (2) 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]

Description

Say 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 can control the writing of header records with -h[o] plus these optional modifiers:

  • +d — remove existing header records.
  • +c — add a header comment with column names to the output [default is no column names].
  • +m — add a segment header segheader to the output after the header block [default is no segment header].
  • +r — add a remark comment to the output [default is no comment]. The remark string may contain \n to indicate line-breaks.
  • +t — add a title comment to the output [default is no title]. The title string may contain \n to indicate line-breaks.

Notes: (1) 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 of them starts with #. (2) 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. Yeah. Bytes. It's giving chaos but it's fine 💀.

The -i option 🎛️

Syntax

-icols[+l][+ddivisor][+sscale|d|k][+ooffset][,...][,t[word]]

Description

The -i option lets you specify which input file physical data columns to use, and in what order. Name 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, live your truth. The chosen data columns get used as given, and columns you didn't list get skipped. Optionally append one of these modifiers to any column or column range to transform the input columns:

  • +l — take \log_{10} of the input values.
  • +d — divide the input values by the factor divisor [default is 1].

okay so the -i transformation modifiers are giving:

  • +s — 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 — Add the given offset to the input values [default is 0]. 💅
Notes: (1) The order of these optional transformations are (1) take \log_{10}, (2) scale or divide, and (3) add offset. Do not repeat operations: -i+d9+o8+o2+s3+d4 will be treated as -i+o2+d4. 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. (2) 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. Choose from these directives:

  • g — Perform great circle distance calculations, with parameters such as distance increments or radii compared against calculated great circle distances [Default is -jg]. 🌍
  • f — Select Flat Earth mode, which gives a more approximate but faster result. 🏃
  • e — Select ellipsoidal (or geodesic) mode for the highest precision and slowest calculation time. 🐢
Note: (1) 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). (2) Coordinate transformations that can use ellipsoidal or spherical forms will first consult -j if given.

🎀 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 — Draw a horizontal line in the given pen before the legend entry is placed [default is no line].
  • +G — Add the vertical space specified by gap [default is no extra space].
  • +H — Add the specified legend header [default is no header].
  • +L — Set a line text. Optionally, prepend a horizontal justification code L(eft), C(enter), or R(ight) for text [default is C].
  • +N — Change the number of columns used to set the following legend items to cols [default is 1].
  • +S — 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 — Start and +vpen to stop drawing vertical line from previous to current horizontal line [default is no vertical line].
  • +f — Set the font used for the legend header [default is FONT_TITLE].
  • +g — Set the fill used for the legend frame [default is white].
  • +j — Set placement of the legend using the two-character justification code justify [default is TR].
  • +o — Set the offset from legend frame to anchor point [default is 0.2c].
  • +p — Set the pen used for the legend frame [default is 1p].
  • +s — Resize all symbol and length sizes in the legend by scale [default is no scaling].
  • +w — Set legend frame width [default is auto].
Notes: (1) Default pen is given by MAP_DEFAULT_PEN. (2) +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. (3) 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.(4) 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 — Use B-spline smoothing.
  • c — Use bicubic interpolation.
  • l — Use bilinear interpolation.
  • n — Use nearest-neighbor value (for example to plot categorical data).

The following modifiers are supported:

  • +a — Switch off antialiasing (where supported) [default uses antialiasing].
  • +b — 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. For more information see Boundary Conditions for operations on grids.
  • +c — Clip the interpolated grid to input z-min/z-max [default may exceed limits].
  • +t — 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[+l][+ddivisor][+sscale|d|k][+ooffset][,...][,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. This is especially useful when table output is generated by modules that derive its output from gridded data sets. 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. Optionally, append one of the following modifiers to any column or column range to transform the output columns:

  • +l — Take \log_{10} of the output values.
  • +d — Divide the output values by the factor divisor [default is 1].
  • +s — Multiply the output 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 — Add the given offset to the output values [default is 0].
Notes: (1) The order of these optional transformations are (1) take \log_{10}, (2) scale or divide, and (3) add offset. Do not repeat operations: -o+d9+o8+o2+s3+d4 will be treated as -o+o2+d4. 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). 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, -on will simply write the numerical output only and skip any trailing text, while -ot will only output the trailing text (or selected word). (2) Using -o assumes there are as many numerical columns as implied in -o.

🔥 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 directives 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 — Project lon0/lat0 (and z0 if applicable) to the center of the page size.
  • +v — Specify the coordinates of the projected 2-D view point as x0/y0.

Okay bestie, so when -p gets used with absolutely no extra args, 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 you're 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 — Count all rows in the data set.
  • +t — Reset the count at the start of each table.
  • +s — 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.)

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 output columns or column ranges to consider for this NaN test [default only considers the third output 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 — Reverse the suppression, i.e., only output the records whose z-value equals NaN.
  • +a — 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). Notes: (1) 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). (2) 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]):

  • y — Yearly cycle (normalized); Period: 1 year; Phase: 0; Range: 0–1
  • a — Annual cycle (month); Period: 1 year; Phase: 0; Range: 0–12
  • w — Weekly cycle (day); Period: 1 week; Phase: 0; Range: 0–7
  • d — Daily cycle (hour); Period: 1 day; Phase: 0; Range: 0–24
  • h — Hourly cycle (minute); Period: 1 hour; Phase: 0; Range: 0–60
  • m — Minute cycle (second); Period: 1 minute; Phase: 0; Range: 0–60
  • s — Second cycle (second); Period: 1 second; Phase: 0; Range: 0–1
  • c — Custom cycle (normalized); Period: T; Phase: \tau; Range: 0–1

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

Notes: (1) 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. (2) 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 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). Note: The -x option is only available to GMT modules compiled with OpenMP or Glib threads support, with the exception of movie and batch which handle their own parallel execution separately.

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 — this attribute is how you tell GMT what to fill a polygon with: a solid shade, a solid color (peep Specifying Color above bestie), or a pattern. Patterns get written as ppattern, where pattern is either the number of a built-in pattern (1-90) or the name of a raster image file. The optional +rdpi sets the resolution of that image, and the default is 300. For 1-bit rasters: use an upper case P to get inverse video, or tack on +fcolor and/or +bcolor to set the foreground and background colors — and if you give no color at all, that literally means transparency. For the tea on every individual built-in pattern, go look at Predefined Bit and Hachure Patterns in GMT. 🎀

✨ Specifying Fonts ✨

The attributes of text fonts, as defined by font, is a comma delimited list of size, fonttype and fill — every single one of them optional. 💅

  • size is the font size (usually in points), but you can add c or i to it to indicate other units.
  • fonttype is the name of the font (case sensitive!! watch that shift key bestie) or its equivalent numerical ID, like 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 the outline partially obscuring the text, append =~pen instead — in that case only half the linewidth is plotted, on the outside of the font only. And 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:

  1. Helvetica
  2. Helvetica-Bold
  3. Helvetica-Oblique
  4. Helvetica-BoldOblique
  5. Times-Roman
  6. Times-Bold
  7. Times-Italic
  8. Times-BoldItalic
  9. Courier
  10. Courier-Bold
  11. Courier-Oblique
  12. Courier-BoldOblique
  13. Symbol
  14. AvantGarde-Book
  15. AvantGarde-BookOblique
  16. AvantGarde-Demi
  17. AvantGarde-DemiOblique
  18. Bookman-Demi
  19. Bookman-DemiItalic
  20. Bookman-Light
  21. Bookman-LightItalic
  22. Helvetica-Narrow
  23. Helvetica-Narrow-Bold
  24. Helvetica-Narrow-Oblique
  25. Helvetica-Narrow-BoldOblique
  26. NewCenturySchlbk-Roman
  27. NewCenturySchlbk-Italic
  28. NewCenturySchlbk-Bold
  29. NewCenturySchlbk-BoldItalic
  30. Palatino-Roman
  31. Palatino-Italic
  32. Palatino-Bold
  33. Palatino-BoldItalic
  34. ZapfChancery-MediumItalic
  35. ZapfDingbats
  36. Ryumin-Light-EUC-H
  37. Ryumin-Light-EUC-V
  38. GothicBBB-Medium-EUC-H
  39. GothicBBB-Medium-EUC-V

💜 Specifying Pens 💜

The attributes of lines and symbol outlines, as defined by pen, is a comma-delimited list of width, color and style — again, each one of them optional, we love a flexible icon. ✨

  • width can be given as a measure (in points — that's the default — or centimeters, or inches) or as one of 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 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. But bestie, GMT is able to produce and read grid files in many other commonly used grid file formats, and it 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 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 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 set 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

2025, The GMT Team

and that's a wrap on the whole entire page bestie!! 🎉 this was version 6.6, dated Jul 23, 2025 — aka GMT(1) — so if your local copy says something else, go read that one instead, no cap. now go make some absolutely iconic maps, you ate fr fr 💅✨🌈

📦 where this page comes from