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.

--help

List and description of GMT modules.

--new-script[=L]

Write a GMT modern mode script template to stdout. Optionally append the desired scripting language among bash, csh, or batch. Default is the main shell closest to your current shell (e.g., bash for zsh, csh for tcsh).

--new-glue=name

Write the C code glue needed when building third-party supplements as shared libraries. The name is the name of the shared library. Run gmt in the directory of the supplement and the glue code will be written to stdout. Including this C code when building the shared library means gmt can list available modules via the --show-modules, --help options. We recommend saving the code to gmt_name_glue.c.

--show-bindir

Show directory of executables and exit.

--show-citation

Show the citation for the latest GMT publication.

--show-classic

List classic module names on stdout and exit.

--show-cores

Show number of available cores.

--show-datadir

Show data directory/ies and exit.

--show-dataserver

Show URL of the remote GMT data server.

--show-doi

Show the DOI of the current release.

--show-modules

List modern module names on stdout and exit.

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

-B[p|s]parameters

Set map Frame and Axes parameters. The Frame parameters are specified by

-B[axes][+b][+gfill][+i[val]][+n][+olon/lat][+ttitle]

where axes selects which axes to plot. By default, all 4 map boundaries (or plot axes) are plotted (named W, E, S, N). To customize, append the codes for those you want (e.g., WSn). Upper case means plot and annotate while lower case just plots and ticks the specified axes. To just draw an axis without annotation and ticks you can use the l(eft), r(ight), b(ottom), t(opt) and (for 3-D) u(p) codes. If a 3-D basemap is selected with -p and -Jz, append Z, z, or u to control the appearance of the vertical axis. By default a single vertical axes will be plotted at the most suitable map corner. Override the default by appending any combination of corner ids 1234, where 1 represents the lower left corner and the order goes counter-clockwise. Append +b to draw the outline of the 3-D cube defined by -R; this modifier is also needed to display gridlines in the x-z, y-z planes. Note that for 3-D views the title, if given, will be suppressed. You can paint the interior of the canvas with +gfill. Use +i to annotate an internal meridian or parallel when the axis that normally would be drawn and annotated does not exist (e.g., azimuthal map with 360-degree range has no latitude axis, and a global Hammer map has no longitude axis); optionally append the parallel or meridian [0]. Append +n to have no frame and annotations at all [Default is controlled by the codes]. Optionally append +oplon/plat to draw oblique gridlines about specified pole [regular gridlines]. Ignored if gridlines are not requested (below) and disallowed for the oblique Mercator projection. To add a plot title, append +ttitle. The Frame setting is optional but can be invoked once to override the above defaults.

The Axes parameters are specified by

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

but you may also split this into two separate invocations for clarity, i.e.,

• -B[p|s][x|y|z][+aangle|n|p][+f][+l|Llabel][+pprefix][+s|Sseclabel][+uunit]
• -B[p|s][x|y|z]intervals

  The first optional flag following -B selects p (rimary) [Default] or s (econdary) axes information (mostly used for time axes annotations but 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 [x|y|z] flags specify which axes you are providing information for. If none are given then we default to xy. If you wish to give different annotation intervals or labels for the various axes then you must repeat the B option for each axis (If a 3-D basemap is selected with -p and -Jz, use -Bz to give settings for the vertical axis.). To add a label to an axis, just append +llabel (Cartesian projections only). Use +L (or +S) to force a horizontal label for y-axes (useful for very short labels). For Cartesian axes you may specify an alternate via +s which is used for right or upper axis axis label (with any +l label used for left and bottom axes). If the axis annotation should have a leading text prefix (e.g., dollar sign for those plots of your net worth) you can append +pprefix. For geographic maps the addition of degree symbols, etc. is automatic (and controlled by the GMT default setting FORMAT_GEO_MAP). However, for other plots you can add specific units by adding +uunit. If any of these text strings contain spaces or special characters you will need to enclose them in quotes. Cartesian x-axes also allow for the optional +aangle, which will plot slanted annotations; angle is measured with respect to the horizontal and must be in the -90 <= angle <= 90 range only. Also, +an is a shorthand for normal (i.e., +a90) and +ap for parallel (i.e., +a0) annotations [Default]. For the y- and z-axes, arbitrary angles are not allowed but +an and +ap specify annotations normal [Default] and parallel to the axis, respectively. Note that these defaults can be changed via MAP_ANNOT_ORTHO. Geographic axes can take +f which will give fancy annotations with W|E|S|N suffices encoding the sign.

  The intervals specification is a concatenated string made up of substrings of the form

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

  The leading a is used to specify the annotation and major tick spacing [Default], f for minor tick spacing, and g for gridline spacing. stride is the desired stride interval. The optional phase shifts the annotation interval by that amount (positive or negative). The optional unit indicates the unit of the stride and are particularly important for time-axes as they can be any of the ones listed below:

For geographic axes d, m and s instead mean arc degrees, minutes and seconds, while for Cartesian axes no unit is given. All entities that are language-specific are under control of GMT_LANGUAGE. Alternatively, we can omit stride, thus setting xinfo, yinfo, or zinfo to a plots annotations at automatically determined intervals,

For custom annotations and intervals, let intervals be given as cintfile, where intfile contains any number of records with coord type [label]. Here, type is one or more letters from a|i, f, and g. For a|i you must supply a label that will be plotted at the coord location. For non-geographical projections: Give negative scale (in -Jx) or axis length (in -JX) to change the direction of increasing coordinates (i.e., to make the y-axis positive down). For log10 axes: Annotations can be specified in one of three ways:

For power axes: Annotations can be specified in one of two ways:

Finally, 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.

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.

-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 GDAL so it requires that GMT build is linked to that 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.

-Rxmin/xmax/ymin/ymax[+r][+uunit]

xmin, xmax, ymin, and ymax specify the region of interest. For geographic regions, these limits correspond to west, east, south, and north and you may specify them in decimal degrees or in [±]dd:mm[:ss.xxx][W|E|S|N] format. Append +r if lower left and upper right map coordinates are given instead of west/east/south/north. The two shorthands -Rg and -Rd stand for global domain (0/360 and -180/+180 in longitude respectively, with -90/+90 in latitude). Set geographic regions by specifying ISO country codes from the Digital Chart of the World using -Rcode1,code2,…[+e|r|R[incs]] instead: Append one or more comma-separated countries using the 2-character ISO 3166-1 alpha-2 convention. To select a state of a country (if available), append .state, e.g, US.TX for Texas. To specify a whole continent, prepend = to any of the continent codes AF (Africa), AN (Antarctica), AS (Asia), EU (Europe), OC (Oceania), NA (North America), or SA (South America). Use +r to modify the bounding box coordinates from the polygon(s): Append inc, xinc/yinc, or winc/einc/sinc/ninc to adjust the region to be a multiple of these steps [no adjustment]. Alternatively, use +R to extend the region outward by adding these increments instead, or +e which is like +r but it ensures that the bounding box extends by at least 0.25 times the increment [no extension]. Alternatively for grid creation, give -Rcodex0/y0/nx/ny, where code 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. This indicates which point on a rectangular region the x0/y0 coordinate refers to, and the grid dimensions nx and ny with grid spacings via -I is used to create the corresponding region. Alternatively, specify the name of an existing grid file and the -R settings (and grid spacing and registration, if applicable) are copied from the grid. When -R is used without any further arguments, the values from the last use of -R in a previous GMT command will be used. For calendar time coordinates you may either give (a) relative time (relative to the selected TIME_EPOCH and in the selected TIME_UNIT; append t to -JX|x), or (b) absolute time of the form [date]T[clock] (append T to -JX|x). At least one of date and clock must be present; the T is always required. The date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock string must be of the form hh:mm:ss[.xxx]. The use of delimiters and their type and positions must be exactly as indicated (however, input, output and plot formats are customizable; see gmt.conf). You can also use Cartesian projected coordinates compatible with the chosen projection. Append the length unit via the +u modifier, (e.g., -R-200/200/-300/300+uk for a 400 by 600 km rectangular area centered on the projection center (0, 0). These coordinates are internally converted to the corresponding geographic (longitude, latitude) coordinates for the lower left and upper right corners. This form is convenient when you want to specify a region directly in the projected units (e.g., UTM meters). For Cartesian data in radians you can also use [±][s]pi[f], for optional integer scales s and fractions f.

-U[label][+c][+jjust][+odx/dy]

Draw the GMT system time stamp on the plot. By appending +jjust [BL] and/or +odx/dy [-54p/-54p], the user may specify the justification of the stamp and where the stamp should fall on the page relative to lower left corner of the plot. For example, +jBL+o0/0 will align the lower left corner of the time stamp with the bottom left corner of the plot. Optionally, append a label, or give +c which will plot the module command string. 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).

-V[level]

Select verbose mode, which modulates the messages written to stderr. 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 [Default], t - Timings (report runtimes for time-intensive algorithms), i - Informational messages (same as -V only), c - Compatibility warnings, or d - Debugging messages.

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

Shift plot origin relative to the current origin by (xshift,yshift) and optionally append the length unit (c, i, or p). You can 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 shift), prepend f to shift the origin relative to the fixed lower left corner of the page, or prepend r [Default] to move the origin relative to its current location. For overlays the default (xshift,yshift) is (r0), otherwise it is (r72p). 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. Note that -X and -Y can also access the previous plot dimensions w and h and construct offsets that involves them. 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.

-a[col=]name[,…]

Control how aspatial data are handled in GMT during input and output. Reading OGR/GMT-formatted files: To assign certain aspatial data items to GMT data columns, give 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 use as data input for column col. In addition, to assign an aspatial value to non-column data, you may specify col as D for distance, G for fill, I for ID, L for label, T for text, W for pen, and Z for value [e.g., used to look up color via a CPT]. If you skip the leading “col=” in the argument then we supply (and automatically increment) a column value starting at 2. Give just -a to select all aspatial items to be added to the input record. Writing OGR/GMT-formatted files: To write OGR/GMT-formatted files, give one or more comma-separated associations col=name[:type], with an optional data type from DOUBLE, FLOAT, INTEGER, CHAR, STRING, DATETIME, or LOGICAL [DOUBLE]. To extract information from GMT multisegment headers encoded in the -Ddistance, -Gfill, -IID, -Llabel, -Ttext, -Wpen, or -Zvalue settings, specify COL as D, G, I, L, T, W or Z, respectively; type will be set automatically. Finally, you must append +ggeometry, where geometry is either POINT, LINE, or POLY. Optionally, prepend M for multi-versions of these geometries. To force the clipping of features crossing the Dateline, use upper-case +G instead. See /cookbook/ogrgmt-format for details of the OGR/GMT file format.

-bi[ncols][type][w][+l|b]

Select native binary format for primary input (secondary inputs are always ASCII). Here, ncols is the number of data columns of given type, which must be one of c (int8_t, aka char), u (uint8_t, aka unsigned char), h (int16_t, 2-byte signed int), H (uint16_t, 2-byte unsigned int), i (int32_t, 4-byte signed int), I ((capital i) uint32_t, 4-byte unsigned int), l ((lower case el) int64_t, 8-byte signed int), L (uint64_t, 8-byte unsigned int), f (4-byte single-precision float), and d (8-byte double-precision float). In addition, use x to skip ncols bytes anywhere in the record. For records with mixed types, simply append additional comma-separated combinations of ncols type (no space). Append w to any item to force byte-swapping. Alternatively, append +l|b to indicate that the entire data file should be read as little- or big-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. If the input file is netCDF, no -b is needed; simply append ?var1/var2/… to the filename to specify the variables to be read.

-bo[ncols][type][w][+l|b]

Select native binary output. Here, ncols is the actual number of data columns of type type, which must be one of c, u, h, H, i, I (capital i), l (lower case ell), L, f, and d (see -bi). For a mixed-type output record, append additional comma-separated combinations of ncols type (no space). Append w to any item to force byte-swapping or +l|b for byte-swapping of the entire record. 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.

-c[row,col|index]

Used to advance to the selected subplot panel. Only allowed when in subplot mode. Available to all plot modules. If no arguments are given then we advance to the next panel in the selected order. If no -c is given and we just entered subplot mode then the first panel (top, left) is selected. Instead of row, col you may give the one-dimensional index which depends on the order you set via -A when the subplot was defined. Note: row, col, and index all start at 0.

-d[i|o]nodata

Control how user-coded missing data values are translated to official NaN values in GMT. For input data we replace any value that equals nodata with NaN. For output data we replace any NaN with the chosen nodata value. Use -di or -do to only affect input or output.

-dinodata

Examine all input columns and if any item equals nodata we interpret this value as a missing data item and substitute the value NaN.

-donodata

Examine all output columns and if any item equals NaN we substitute it with the chosen missing data value nodata.

-e[~]“pattern” | -e[~]/regexp/[i]

Only accept ASCII data records that contain the specified pattern. To reverse the search, i.e., to only accept data records that do not contain the specified pattern, use -e~. 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.

-f[i|o]colinfo

Specify the data types of input and/or output columns (time or geographical data). Specify i or o to make this apply only to input or output [Default applies to both]. Give one or more columns (or column ranges) separated by commas, or use -f multiple times (column ranges must be given in the format start[:inc]:stop, where inc defaults to 1 if not specified). Append T (absolute calendar time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), x (longitude), y (latitude), p[unit] (projected x,y map coordinates in given unit [meter]) or f (floating point) to each column or column range item. Shorthands -f[i|o]g means -f[i|o]0x,1y (geographic coordinates) and -f[i|o]c means -f[i|o]0:1f (Cartesian coordinates)

-g[a]x|y|d|X|Y|D|[col]zgap[+n|p]

Examine the spacing between consecutive data points in order to impose breaks in the line. Append x|X or y|Y to define a gap when there is a large enough change in the x or y coordinates, respectively, or d|D for distance gaps; use upper case to calculate gaps from projected coordinates. For gap-testing on other columns use [col]z; if col is not prepended the it defaults to 2 (i.e., 3rd column). Append gap and optionally a unit u and modifiers +n or +p. Here, +n means previous minus current column value must exceed gap to be a gap and +p means current minus previous column value must exceed gap. Otherwise the absolute value of the difference must exceed gap. For geographic data (x|y|d), the unit u may be arc degree, minute, or second, or meter [Default], foot, kilometer, Mile, nautical mile, or survey foot. For projected data (X|Y|D), choose from inch, centimeter, or point [Default unit set by PROJ_LENGTH_UNIT]. Note: For x|y|z with time data the unit is instead controlled by TIME_UNIT. Repeat the option to specify multiple criteria, of which any can be met to produce a line break. Issue an additional -ga to indicate that all criteria must be met instead.

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle]

Primary input file(s) has n extra header record(s). If used, the default number of header records is IO_N_HEADER_RECS [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]. Blank lines and lines starting with # are always skipped; to use another leading character for indicating header records, please see IO_HEADER_MARKER. Note that with -h in effect the first n records are taken verbatim as headers and not skipped even if any is starting with #. For output you may request additional headers to be written via the option modifiers, and use +d to remove existing header records. Append +c to issue a header comment with column names to the output [none]. Append +m to add a new segment header with a segheader to the output after the header block [none]. Append +r to add a remark comment to the output [none]. Append +t to add a title comment to the output [none]. These optional remark and title strings may contain n to indicate line-breaks). If used with native binary data we interpret n to instead mean the number of bytes to skip on input or pad on output.

-icols[+l][+sscale][+ooffset][,…][,t[word]]

Select specific data columns for primary input, in arbitrary order. Columns not listed will be skipped. Give 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 (0)]. Columns may be repeated. To each column, optionally add any of the following: +l takes log10 of the input values first; +sscale, subsequently multiplies by a given scale factor [1]; +ooffset, finally adds a given offset [0]. To read from a given column until the end of the record, leave off stop. Normally, any trailing text is read but when -i is used you must explicitly add the column t to retain the text. To only ingest a single word from the trailing text, append the word number (first word is 0). Finally, -in will simply read the numerical input and skip any trailing text.

-je|f|g

Determine how spherical distances are calculated in modules that support this. By default (-jg), we perform great circle distance calculations and parameters such as distance increments or radii will be compared against calculated great circle distances. To simplify and speed up calculations you can select Flat Earth mode (-jf) which gives an approximate but faster result. Alternatively, you can select ellipsoidal (-je; or geodesic) mode for the highest precision (and slowest calculation time). 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).

-l[label][+Dpen][+Ggap][+Hheader][+L[code/]txt][+Ncols][+Ssize][+V[pen]][+ffont][+gfill][+jjust][+ooff][+ppen][+sscale][+wwidth]

Add a map legend entry to the session legend information file for the current plot. Optionally append a text label to describe the entry. Several modifiers allow further changes to the legend (to be built when legend is called): Use +D to draw a horizontal line before the legend entry is placed [no line], +G to add some vertical space [0], +H to add a legend header [no header], +L to set a line text; prepend a horizontal justification code L, C, or R [C], +N to change the number of columns used to set the following legend items [1], +S to override the size of the current symbol for the legend or set a length if plotting a line or contour [same as plotted], and +V to start and +vpen to stop drawing vertical line from previous to current horizontal line [no vertical line]. In addition, several lower-case modifiers can be set to affect the legend: Use +f to set the font used for the legend header [FONT_TITLE], +g to set the fill used for the legend frame [white], +j to set placement of the legend [TR], +o to set the offset from legend frame to anchor point [0.2c], +p to set the pen used for the legend frame [1p], +sscale to resize all symbol and length sizes in the legend, and +wwidth to set legend frame width [auto]. Default pen is given by MAP_DEFAULT_PEN. Note that +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. The upper-case modifiers reflect legend codes described in legend, which provide more details and customization. If legend is not called explicitly we will call it implicitly when finishing the plot via end.

-n[b|c|l|n][+a][+bBC][+c][+tthreshold]

Select grid interpolation mode by adding b for B-spline smoothing, c for bicubic interpolation, l for bilinear interpolation, or n for nearest-neighbor value (for example to plot categorical data). Optionally, append +a to switch off antialiasing (where supported). Append +bBC to override the boundary conditions used, adding 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. Append +c to clip the interpolated grid to input z-min/max [Default may exceed limits]. Append +tthreshold to control how close to nodes with NaNs the interpolation will go. A threshold of 1.0 requires all (4 or 16) nodes involved in interpolation to be non-NaN. 0.5 will interpolate about half way from a non-NaN value; 0.1 will go about 90% of the way, etc. [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].

-ocols[,…][,t[word]]

Select specific data columns for primary output, in arbitrary order. Columns not listed will be skipped. Give columns (or column ranges in the format start[:inc]:stop, where inc defaults to 1 if not specified) separated by commas. Columns may be repeated. To write from a given column until the end the columns, leave off stop. [Default writes all columns in order]. Normally, any trailing text in the internal records will be written but when -o is used you must explicitly add the column t. To only output 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 and not the columns in the original record.

-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]

Select perspective view and set the azimuth and elevation of the viewpoint [180/90]. When -p is used in consort with -Jz or -JZ, a third value can be appended which indicates at which z-level all 2D material, like the plot frame, is plotted (in perspective). [Default is at the bottom of the z-axis]. Use -px or -py to plot against the “wall” x = level or y = level (default is on the horizontal plane, which is the same as using -pz). For frames used for animation, note we fix the center of your data domain. Specify another center using a particular world coordinate point with +wlon0/lat0[/z0]) which will project to the center of your page size, or specify the coordinates of the projected 2-D view point with +vx0/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.

-q[i|o][~]rows[+ccol][+a|f|s]

Select specific data rows to be read (-qi [Default]) or written (-qo) [all]. Give individual rows (or row ranges in the format start[:inc]:stop, where inc defaults to 1 if not specified) separated by commas [Default reads/writes all rows, starting with the first row (0)]. By default (+a) we count rows in the data set; append +f or +s to reset the count at the start of each file or segment, respectively. Alternatively, use +ccol to indicate that the arguments instead are min/max data limits for the values in column col. Note: Because arguments may contain colons or be negative, your must specify start/stop instead. To read (or write) from a given row until the end of the data, leave off stop. To reverse the tests, prepend ~ before giving your first range.

-qi[~]rows[+ccol][+a|f|s]

Select specific data rows to be read during input [all]. Give individual rows (or row ranges in the format start[:inc]:stop, where inc defaults to 1 if not specified) separated by commas [Default reads all rows, starting with the first row (0)]. By default (+a) we count rows in the data set; append +f or +s to reset the count at the start of each file or segment. Alternatively, use +ccol to indicate that the arguments instead are min/max data limits for the values in column col. Note: Because data limits may contain colons or be negative, your must specify start/stop instead. To read from a given row until the end of the data, leave off stop. To reverse the tests, prepend ~ before giving your first range.

-qo[~]rows[+ccol][+a|f|s]

Select specific data rows to be writing during output [all]. Give individual rows (or row ranges in the format start[:inc]:stop, where inc defaults to 1 if not specified) separated by commas [Default writes all rows, starting with the first row (0)]. By default (+a) we count rows in the data set; append +f or +s to reset the count at the start of each file or segment, respectively. Alternatively, use +ccol to indicate that the arguments instead are min/max data limits for the values in column col. Note: Because data limits may contain colons or be negative, your must specify start/stop instead. To write from a given row until the end of the data, leave off stop. To reverse the tests, prepend ~ before giving your first range.

-r[g|p]

Force gridline or pixel node registration [gridline]. Just -r sets pixel registration. If no -r is given then gridline registration is selected. (Node registrations are defined in Section option_nodereg of the GMT Technical Reference and Cookbook.)

-s[cols][+a][+r]

Suppress output of data records whose z-value(s) equal NaN [Default outputs all records]. By default, we only consider the third data column (cols = 2). However, you can append a comma-separated list of all columns or column ranges to include in the NaN test (column ranges must be given in the format start[:inc]:stop, where inc defaults to 1 if not specified). All the selected data columns must be NaN to skip the record. Append +a to skip the record if just one or more of the columns equal NaN. Append +r to reverse the decision, i.e., only output records that failed the test.

-t[transp]

Set transparency level for an overlay, in (0-100] percent range. [Default is 0, i.e., opaque]. Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing).

-x[[-]n]

Limit the number of cores to be used in any OpenMP-enabled multi-threaded algorithms. By default we try 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.

-:[i|o]

Swap 1st and 2nd column on input and/or 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 -icols[+l][+sscale][+ooffset][,…][,t[word]].

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

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