GMT 2010

GMT(1) Generic Mapping Tools GMT(1)
NAME
GMT − The Generic Mapping Tools data processing and display software package
INTRODUCTION
GMT is a collection of public-domain Unix tools that allows you to manipulate x,y and x,y,z data sets (fil-
tering, trend fitting, gridding, projecting, etc.) and produce PostScript illustrations ranging from simple x-y
plots, via contour maps, to artificially illuminated surfaces and 3-D perspective views in black/white or full
color. Linear, log10, and power scaling is supported in addition to 25 common map projections. The pro-
cessing and display routines within GMT are completely general and will handle any (x,y) or (x,y,z) data as
input.
SYNOPSIS
GMT is also a wrapper script that can start any of the programs:
GMT module module-options
where module is the name of a GMT program and the options are those that pertain to that particular pro-
gram.
GMT OVERVIEW
The following is a summary of all the programs supplied with GMT and a very short description of their
purpose. Detailed information about each program can be found in the separate manual pages.
blockmean L2 (x,y,z) data filter/decimator

blockmedian L1 (x,y,z) data filter/decimator
blockmode Mode (x,y,z) data filter/decimator
filter1d Filter 1-D data sets (time series)
fitcircle Finds the best-fitting great circle to a set of points
gmt2rgb Convert Sun rasterfile or grid to r, g, b grids
gmtconvert Convert between ASCII and binary 1-D tables
gmtdefaults List the current default settings
gmtmath Mathematical operations on data tables
gmtset Set individual default parameters
gmtselect Extract data subsets based on spatial criteria
grdfilter Filter 2-D data sets in the space domain
grd2cpt Make a color palette table from grid files
grd2xyz Conversion from 2-D grid file to table data
grdblend Blend several partially over-lapping grid files onto one grid
grdclip Limit the z-range in gridded data
grdcontour Contouring of 2-D gridded data
grdcut Cut a sub-region from a grid file
grdedit Modify header information in a 2-D grid file
grdfft Operate on grid files in the wavenumber (or frequency) domain
grdgradient Compute directional gradient from grid files
grdhisteq Histogram equalization for grid files
grdimage Produce images from 2-D gridded data
grdinfo Get information about grid files
grdlandmask Create mask grid file from shoreline data base
grdmask Reset nodes outside a clip path to a constant
grdmath Mathematical operations on grid files
grdpaste Paste together grid files along a common edge
grdproject Project gridded data onto a new coordinate system
grdreformat Converting between different grid file formats
grdsample Resample a 2-D gridded data set onto a new grid
grdtrend Fits polynomial trends to grid files
grdtrack Sampling of 2-D data set along 1-D track
GMT 4.5.14 1 Nov 2015 1

GMT(1) Generic Mapping Tools GMT(1)
grdvector Plot vector fields from grid files

grdview 3-D perspective imaging of 2-D gridded data
grdvolume Volume calculations from 2-D gridded data
greenspline Interpolation using Green’s functions for splines in 1-3 dimensions
makecpt Make color palette tables
mapproject Forward or inverse map projections of table data
minmax Find extreme values in data tables
nearneighbor Nearest-neighbor gridding scheme
project Project data onto lines/great circles
ps2raster Crop and convert PostScript files to raster images, EPS, and PDF
psbasemap Create a basemap plot
psclip Use polygon files to define clipping paths
pscoast Plot coastlines and filled continents on maps
pscontour Contour xyz-data by triangulation
pshistogram Plot a histogram
psimage Plot images (EPS or Sun raster files) on maps
pslegend Plot legend on maps
psmask Create overlay to mask out regions on maps
psrose Plot sector or rose diagrams
psscale Plot gray scale or color scale on maps
pstext Plot text strings on maps
pswiggle Draw time-series along track on maps
psxy Plot symbols, polygons, and lines on maps
psxyz Plot symbols, polygons, and lines in 3-D
sample1d Resampling of 1-D table data sets
spectrum1d Compute various spectral estimates from time-series
splitxyz Split xyz-files into several segments
surface A continuous curvature gridding algorithm
trend1d Fits polynomial or Fourier trends to y = f(x) data
trend2d Fits polynomial trends to z = f(x,y) data
triangulate Perform optimal Delaunay triangulation and gridding
xyz2grd Convert equidistant xyz data to a 2-D grid file
SEE ALSO
Look up the individual man pages for more details and full syntax. Run GMT without options to list all
GMT programs and to show all installation directories. Information is also available on the GMT home
page gmt.soest.hawaii.edu
REFERENCES
Wessel, P., and W. H. F. Smith, 2015, The Generic Mapping Tools (GMT) version 4.5.14 Technical Refer-
ence & Cookbook, SOEST/NOAA.
Wessel, P., and W. H. F. Smith, 1998, New, Improved Version of Generic Mapping Tools Released, EOS
Trans., AGU, 79 (47), p. 579.
Wessel, P., and W. H. F. Smith, 1995, New Version of the Generic Mapping Tools Released, EOS Trans.,
AGU, 76 (33), p. 329.
Wessel, P., and W. H. F. Smith, 1995, New Version of the Generic Mapping Tools Released,
http://www.agu.org/eos_elec/95154e.html, Copyright 1995 by the American Geophysical Union.
Wessel, P., and W. H. F. Smith, 1991, Free Software Helps Map and Display Data, EOS Trans., AGU, 72
(41), p. 441.
GMT 4.5.14 1 Nov 2015 2

BLOCKMEAN(1) Generic Mapping Tools BLOCKMEAN(1)
NAME
blockmean − filter to block average (x,y,z) data by L2 norm
SYNOPSIS
blockmean [ xyz[w]file(s) ] −Ixinc[unit][=|+][/yinc[unit][=|+]] −Rxmin/xmax/ymin/ymax[r] [ −C ] [ −E ] [
−F ] [ −H[i][nrec] ] [ −S[w|z] ] [ −V ] [ −W[io] ] [ −:[i|o] ] [ −b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]col-
info ]
DESCRIPTION
blockmean reads arbitrarily located (x,y,z) triples [or optionally weighted quadruples (x,y,z,w)] from stan-
dard input [or xyz[w]file(s)] and writes to standard output a mean position and value for every non-empty
block in a grid region defined by the −R and −I arguments. Either blockmean, blockmedian, or block-
mode should be used as a pre-processor before running surface to avoid aliasing short wavelengths. These
routines are also generally useful for decimating or averaging (x,y,z) data. You can modify the precision of
the output format by editing the D_FORMAT parameter in your .gmtdefaults4 file, or you may choose
binary input and/or output using single or double precision storage.
xyz[w]file(s)
3 [or 4] column ASCII file(s) [or binary, see −b] holding (x,y,z[,w]) data values. [w] is an optional
weight for the data. If no file is specified, blockmean will read from standard input.
−I x_inc [and optionally y_inc] is the grid spacing. Optionally, append a suffix modifier. Geographi-
cal (degrees) coordinates: Append m to indicate arc minutes or c to indicate arc seconds. If one
of the units e, k, i, or n is appended instead, the increment is assumed to be given in meter, km,
miles, or nautical miles, respectively, and will be converted to the equivalent degrees longitude at
the middle latitude of the region (the conversion depends on ELLIPSOID). If /y_inc is given but
set to 0 it will be reset equal to x_inc; otherwise it will be converted to degrees latitude. All coor-
dinates: If = is appended then the corresponding max x (east) or y (north) may be slightly adjusted
to fit exactly the given increment [by default the increment may be adjusted slightly to fit the given
domain]. Finally, instead of giving an increment you may specify the number of nodes desired by
appending + to the supplied integer argument; the increment is then recalculated from the number
of nodes and the domain. The resulting increment value depends on whether you have selected a
gridline-registered or pixel-registered grid; see Appendix B for details. Note: if −Rgrdfile is used
then grid spacing has already been initialized; use −I to override the values.
−R 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 w/e/s/n. The two shorthands −Rg and −Rd stand for global domain (0/360 and
-180/+180 in longitude respectively, with -90/+90 in latitude). Alternatively, specify the name of
an existing grid file and the −R settings (and grid spacing, if applicable) are copied from the grid.
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 gmtdefaults).
OPTIONS
−C Use the center of the block as the output location [Default uses the mean location].
−E Provide Extended report which includes s (the standard deviation of the mean), l, the lowest value,
and h, the high value for each block. Output order becomes x,y,z,s,l,h[,w]. [Default outputs
x,y,z[,w]. See −W for w output.
−F Force pixel node registration [Default is gridline registration]. (Node registrations are defined in
GMT Cookbook Appendix B on grid file formats.) Each block is the locus of points nearest the
grid value location. For example, with −R 10/15/10/15 and and −I 1: with the −F option 10 <=
GMT 4.5.14 1 Nov 2015 1

BLOCKMEAN(1) Generic Mapping Tools BLOCKMEAN(1)
(x,y) < 11 is one of 25 blocks; without it 9.5 <= (x,y) < 10.5 is one of 36 blocks.
−H Input file(s) has header record(s). If used, the default number of header records is
N_HEADER_RECS. Use −Hi if only 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. Not used with binary data.
−S Use −Sz to report the sum of all z-values inside a block, or −Sw to report the sum of weights
[Default reports mean value]. If −Sw is selected and no weights are supplied (i.e., no −W given),
then the weight sum will equal the number of points inside each block.
−V Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].
−W Weighted modifier[s]. Unweighted input and output has 3 columns x,y,z; Weighted i/o has 4 col-
umns x,y,z,w. Weights can be used in input to construct weighted mean values in blocks. Weight
sums can be reported in output for later combining several runs, etc. Use −W for weighted i/o,
−Wi for weighted inputonly, −Wo for weighted output only. [Default uses unweighted i/o].
−: Toggles between (longitude,latitude) and (latitude,longitude) input and/or output. [Default is (lon-
gitude,latitude)]. Append i to select input only or o to select output only. [Default affects both].
−bi Selects binary input. Append s for single precision [Default is d (double)]. Uppercase S or D will
force byte-swapping. Optionally, append ncol, the number of columns in your binary input file if
it exceeds the columns needed by the program. Or append c if the input file is netCDF. Optionally,
append var1/var2/... to specify the variables to be read. [Default is 3 (or 4 if −Wi is set)].
−bo Selects binary output. Append s for single precision [Default is d (double)]. Uppercase S or D
will force byte-swapping. Optionally, append ncol, the number of desired columns in your binary
output file. [Default is 3 (or 4 if −Wo is set)]. −E adds 3 additional columns.
−f Special formatting 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. Append T (absolute calendar time), t (relative time in cho-
sen TIME_UNIT since TIME_EPOCH), x (longitude), y (latitude), or f (floating point) to each
column or column range item. Shorthand −f[i|o]g means −f[i|o]0x,1y (geographic coordinates).
ASCII FORMAT PRECISION
The ASCII output formats of numerical data are controlled by parameters in your .gmtdefaults4 file. Lon-
gitude and latitude are formatted according to OUTPUT_DEGREE_FORMAT, whereas other values are
formatted according to D_FORMAT. Be aware that the format in effect can lead to loss of precision in the
output, which can lead to various problems downstream. If you find the output is not written with enough
precision, consider switching to binary output (−bo if available) or specify more decimals using the
D_FORMAT setting.
EXAMPLES
To find 5 by 5 minute block mean values from the ASCII data in hawaii.xyg, run
blockmean hawaii.xyg −R 198/208/18/25 −I 5m > hawaii_5x5.xyg

SEE ALSO
blockmedian(1), blockmode(1), gmtdefaults(1), GMT (1), nearneighbor(1), surface(1), triangulate(1)
GMT 4.5.14 1 Nov 2015 2

BLOCKMEDIAN(1) Generic Mapping Tools BLOCKMEDIAN(1)
NAME
blockmedian − filter to block average (x,y,z) data by L1 norm.
SYNOPSIS
blockmedian [ xyz[w]file(s) ] −Ixinc[unit][=|+][/yinc[unit][=|+]] −Rxmin/xmax/ymin/ymax[r] [ −C ] [
−E[b] ] [ −F ] [ −H[i][nrec] ] [ −Q ] [ −Tquantile ] [ −V ] [ −W[io] ] [ −:[i|o] ] [
−b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ]
DESCRIPTION
blockmedian reads arbitrarily located (x,y,z) triples [or optionally weighted quadruples (x,y,z,w)] from stan-
dard input [or xyz[w]file(s)] and writes to standard output a median position and value for every non-empty
block in a grid region defined by the −R and −I arguments. Either blockmean, blockmedian, or block-
mode should be used as a pre-processor before running surface to avoid aliasing short wavelengths. These
routines are also generally useful for decimating or averaging (x,y,z) data. You can modify the precision of
the output format by editing the D_FORMAT parameter in your .gmtdefaults4 file, or you may choose
binary input and/or output using single or double precision storage.
xyz[w]file(s)
weight for the data. If no file is specified, blockmedian will read from standard input.
OPTIONS
−C Use the center of the block as the output location [Default uses the median x and median y as loca-
tion (but see −Q)]..
−E Provide Extended report which includes s (the L1 scale of the median), l, the lowest value, and h,
the high value for each block. Output order becomes x,y,z,s,l,h[,w]. [Default outputs x,y,z[,w]. For
box-and-whisker calculation, use −Eb which will output x,y,z,l,q25,q75,h[,w], where q25 and q75
are the 25% and 75% quantiles, respectively. See −W for w output.
GMT 4.5.14 1 Nov 2015 1

−Q (Quicker) Finds median z and (x, y) at that the median z [Default finds median x, median y inde-
pendent of z]. Also see −C.
−T Sets the quantile of the distribution to be returned [Default is 0.5 which returns the median z].
Here, 0 < quantile < 1.
D_FORMAT setting.
EXAMPLES
To find 5 by 5 minute block medians from the double precision binary data in hawaii_b.xyg and output an
ASCII table, run
blockmedian hawaii_b.xyg −R 198/208/18/25 −I 5m −bi 3 > hawaii_5x5.xyg
To compute the shape of a data distribution per bin via a box-and-whisker diagram we need the 0%, 25%,
50%, 75%, and 100% quantiles. To do so on a global 5 by 5 degree basis from the ASCII table depths.xyz
and send output to an ASCII table, run
blockmedian depths.xyz −Rg −I 5 −F −Eb > depths_5x5.txt
GMT 4.5.14 1 Nov 2015 2

SEE ALSO
blockmean(1), blockmode(1), GMT (1), gmtdefaults(1), nearneighbor(1), surface(1), triangulate(1)
GMT 4.5.14 1 Nov 2015 3

BLOCKMODE(1) Generic Mapping Tools BLOCKMODE(1)
NAME
blockmode − filter to block average (x,y,z) data by mode estimation.
SYNOPSIS
blockmode [ xyz[w]file(s) ] −Ixinc[unit][=|+][/yinc[unit][=|+]] −Rxmin/xmax/ymin/ymax[r] [ −C ] [ −E ] [
−F ] [ −H[i][nrec] ] [ −Q ] [ −V ] [ −W[io] ] [ −:[i|o] ] [ −b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ]
DESCRIPTION
blockmode reads arbitrarily located (x,y,z) triples [or optionally weighted quadruples (x,y,z,w)] from stan-
dard input [or xyz[w]file(s)] and writes to standard output mode estimates of position and value for every
non-empty block in a grid region defined by the −R and −I arguments. Either blockmean, blockmedian,
or blockmode should be used as a pre-processor before running surface to avoid aliasing short
wavelengths. These routines are also generally useful for decimating or averaging (x,y,z) data. You can
modify the precision of the output format by editing the D_FORMAT parameter in your .gmtdefaults4 file,
or you may choose binary input and/or output using single or double precision storage.
xyz[w]file(s)
weight for the data. If no file is specified, blockmode will read from standard input.
OPTIONS
−C Use the center of the block as the output location [Default uses the modal xy location (but see
−Q)]. −C overrides −Q.
−E Provide Extended report which includes s (the L1 scale of the mode), l, the lowest value, and h,
the high value for each block. Output order becomes x,y,z,s,l,h[,w]. [Default outputs x,y,z[,w]. See
−W for w output.
GMT 4.5.14 1 Nov 2015 1

BLOCKMODE(1) Generic Mapping Tools BLOCKMODE(1)
−Q (Quicker) Finds mode z and mean (x, y) [Default finds mode x, mode y, mode z].
D_FORMAT setting.
EXAMPLES
To find 5 by 5 minute block mode estimates from the double precision binary data in hawaii_b.xyg and out-
put an ASCII table, run:
blockmode hawaii_b.xyg −R 198/208/18/25 −I 5m −bi 3 > hawaii_5x5.xyg

SEE ALSO
blockmean(1), blockmedian(1), GMT (1), gmtdefaults(1), nearneighbor(1), surface(1), triangulate(1)
GMT 4.5.14 1 Nov 2015 2

FILTER1D(1) Generic Mapping Tools FILTER1D(1)
NAME
filter1d − Time domain filtering of 1-D time series
SYNOPSIS
filter1d [ infile ] −F<type><width>[mode] [ −Dincrement ] [ −E ] [ −H[i][nrec] ] [ −Iignore_val ] [
−Llack_width ] [ −Nn_cols/t_col ] [ −Qq_factor ] [ −Ssymmetry_factor ] [ −Tstart/stop/int ] [ −V ] [
DESCRIPTION
filter1d is a general time domain filter for multiple column time series data. The user specifies the number
of columns of input and which column is the time. (See −N option below). The fastest operation occurs
when the input time series are equally spaced and have no gaps or outliers and the special options are not
needed. filter1d has options -L, -Q, and -S for unevenly sampled data with gaps.
infile Multi-column ASCII (or binary, see −b) file holding data values to be filtered.
−F Sets the filter type. Choose among convolution and non-convolution filters. Append the filter
code followed by the full filter width in same units as time column. Available convolution filters
are:
(b) Boxcar: All weights are equal.
(c) Cosine Arch: Weights follow a cosine arch curve.
(g) Gaussian: Weights are given by the Gaussian function.
(f) Custom: Instead of width give name of a one-column file with your own weight coefficients.
Non-convolution filters are:
(m) Median: Returns median value.
(p) Maximum likelihood probability (a mode estimator): Return modal value. If more than one
mode is found we return their average value. Append - or + to the filter width if you rather want to
return the smallest or largest of the modal values.
(l) Lower: Return the minimum of all values.
(L) Lower: Return minimum of all positive values only.
(u) Upper: Return maximum of all values.
(U) Upper: Return maximum or all negative values only.
Upper case type B, C, G, M, P, F will use robust filter versions: i.e., replace outliers (2.5 L1 scale
off median) with median during filtering.
In the case of L|U it is possible that no data passes the initial sign test; in that case the filter will
return 0.0.
OPTIONS
−D increment is used when series is NOT equidistantly sampled. Then increment will be the abscissae
resolution, i.e., all abscissae will be rounded off to a multiple of increment. Alternatively, resam-
ple data with sample1d.
−E Include Ends of time series in output. Default loses half the filter-width of data at each end.
skipped.
−I To ignore values; If an input value equals ignore_val it will be set to NaN.
−L Checks for Lack of data condition. If input data has a gap exceeding width then no output will be
given at that point [Default does not check Lack].
−N Sets number of columns in input and which column contains the independent variable (time). The
left-most column is # 0, the right-most is # (n_cols - 1). [Default is n_cols = 2, t_col = 0; i.e., file
has t, f(t) pairs].
−Q assess Quality of output value by checking mean weight in convolution. Enter q_factor between 0
and 1. If mean weight < q_factor, output is suppressed at this point [Default does not check Qual-
ity].
GMT 4.5.14 1 Nov 2015 1

FILTER1D(1) Generic Mapping Tools FILTER1D(1)
−S Checks symmetry of data about window center. Enter a factor between 0 and 1. If ( (abs(n_left -
n_right)) / (n_left + n_right) ) > factor, then no output will be given at this point [Default does not
check Symmetry].
−T Make evenly spaced timesteps from start to stop by int [Default uses input times].
append var1/var2/... to specify the variables to be read.
output file. [Default is same as input].
D_FORMAT setting.
EXAMPLES
To filter the data set in the file cruise.gmtd containing evenly spaced gravity, magnetics, topography, and
distance (in m) with a 10 km Gaussian filter, removing outliers, and output a filtered value every 2 km
between 0 and 100 km:
filter1d cruise.gmtd −T 0/1.0e5/2000 −FG 10000 −N 4/3 −V > filtered_cruise.gmtd
Data along track often have uneven sampling and gaps which we do not want to interpolate using sam-
ple1d. To find the median depth in a 50 km window every 25 km along the track of cruise v3312, stored in
v3312.dt, checking for gaps of 10km and asymmetry of 0.3:
filter1d v3312.dt −FM 50 −T 0/100000/25 −L 10 −S 0.3 > v3312_filt.dt

SEE ALSO
GMT (1), sample1d(1)
GMT 4.5.14 1 Nov 2015 2

FITCIRCLE(1) Generic Mapping Tools FITCIRCLE(1)
NAME
fitcircle − find mean position and pole of best-fit great [or small] circle to points on a sphere.
SYNOPSIS
fitcircle [ xyfile ] −Lnorm [ −H[i][nrec] ] [ −S[lat] ] [ −V ] [ −:[i|o] ] [ −bi[s|S|d|D[ncol]|c[var1/...]] ] [
−f[i|o]colinfo ]
DESCRIPTION
fitcircle reads lon,lat [or lat,lon] values from the first two columns on standard input [or xyfile]. These are
converted to Cartesian three-vectors on the unit sphere. Then two locations are found: the mean of the
input positions, and the pole to the great circle which best fits the input positions. The user may choose one
or both of two possible solutions to this problem. The first is called −L1 and the second is called −L2.
When the data are closely grouped along a great circle both solutions are similar. If the data have large dis-
persion, the pole to the great circle will be less well determined than the mean. Compare both solutions as
a qualitative check.
The −L1 solution is so called because it approximates the minimization of the sum of absolute values of
cosines of angular distances. This solution finds the mean position as the Fisher average of the data, and
the pole position as the Fisher average of the cross-products between the mean and the data. Averaging
cross-products gives weight to points in proportion to their distance from the mean, analogous to the "lever-
age" of distant points in linear regression in the plane.
The −L2 solution is so called because it approximates the minimization of the sum of squares of cosines of
angular distances. It creates a 3 by 3 matrix of sums of squares of components of the data vectors. The
eigenvectors of this matrix give the mean and pole locations. This method may be more subject to roundoff
errors when there are thousands of data. The pole is given by the eigenvector corresponding to the smallest
eigenvalue; it is the least-well represented factor in the data and is not easily estimated by either method.
−L Specify the desired norm as 1 or 2, or use −L or −L3 to see both solutions.
OPTIONS
xyfile ASCII [or binary, see −b] file containing lon,lat [lat,lon] values in the first 2 columns. If no file is
specified, fitcircle will read from standard input.
skipped.
−S Attempt to fit a small circle instead of a great circle. The pole will be constrained to lie on the
great circle connecting the pole of the best-fit great circle and the mean location of the data.
Optionally append the desired fixed latitude of the small circle [Default will determine the lati-
tude].
append var1/var2/... to specify the variables to be read. [Default is 2 input columns].
GMT 4.5.14 1 Nov 2015 1

FITCIRCLE(1) Generic Mapping Tools FITCIRCLE(1)

D_FORMAT setting.
EXAMPLES
Suppose you have lon,lat,grav data along a twisty ship track in the file ship.xyg. You want to project this
data onto a great circle and resample it in distance, in order to filter it or check its spectrum. Do the follow-
ing:
fitcircle ship.xyg −L 2
project ship.xyg −Cox/oy −Tpx/py −S −F pz | sample1d −S−100 −I 1 > output.pg
Here, ox/oy is the lon/lat of the mean from fitcircle, and px/py is the lon/lat of the pole. The file output.pg
has distance, gravity data sampled every 1 km along the great circle which best fits ship.xyg
SEE ALSO
GMT (1), project(1), sample1d(1)
GMT 4.5.14 1 Nov 2015 2

GMT2RGB(1) Generic Mapping Tools GMT2RGB(1)
NAME
gmt2rgb − Converting a grid file, a raw, or a Sun raster file to r/g/b grids
SYNOPSIS
gmt2rgb infile −Gtemplate [ −Ccptfile ] [ −F ] [ −Ixinc[m|c][/yinc[m|c]] ] [ −Llayer ] [
−Rxmin/xmax/ymin/ymax[r] ] [ −V ] [ −Wwidth/height[/n_bytes] ]
DESCRIPTION
gmt2rgb reads one of three types of input files: (1) A Sun 8-, 24-, or 32-bit raster file; we the write out the
red, green, and blue components (0-255 range) to separate grid files. Since the raster file header is limited
you may use the −R, −F, −I options to set a complete header record [Default is simply based on the number
of rows and columns]. (2) A binary 2-D grid file; we then convert the z-values to red, green, blue via the
provided cpt file. Optionally, only write out one of the r, g, b, layers. (3) A RGB or RGBA raw raster file.
Since raw rasterfiles have no header, you have to give the image dimensions via the −W option.
infile The (1) Sun raster file, (2) 2-D binary grid file, or (3) raw raster file to be converted.
−G Provide an output name template for the three output grids. The template should be a regular grid
file name except it must contain the string %c which on output will be replaced by r, g, or b.
OPTIONS
−C name of the color palette table (for 2-D binary input grid only).
GMT Cookbook Appendix B on grid file formats.)
−L Output only the specified layer (r, g, or b). [Default outputs all 3 layers].
−W Sets the size of the raw raster file. By default an RGB file (which has 3 bytes/pixel) is assumed.
For RGBA files use n_bytes = 4. Use −W for guessing the image size of a RGB raw file, and
−W=/=/4 if the raw image is of the RGBA type. Notice that this might be a bit slow because the
GMT 4.5.14 1 Nov 2015 1

GMT2RGB(1) Generic Mapping Tools GMT2RGB(1)
guessing algorithm makes uses of FFTs.

EXAMPLES
To use the color palette topo.cpt to create r, g, b component grids from hawaii_grv.grd file, use
gmt2rgb hawaii_grv.grd −C topo.cpt −G hawaii_grv_%c.grd
To output the red component from the Sun raster radiation.ras file, use
gmt2rgb radiation.ras −L r −G comp_%c.grd

SEE ALSO
gmtdefaults(1), GMT (1), grdedit(1), grdimage(1), grdmath(1), grdview(1)
GMT 4.5.14 1 Nov 2015 2

GMT_SHELL_FUNCTIONS.SH(1) Generic Mapping Tools GMT_SHELL_FUNCTIONS.SH(1)
NAME
gmt_shell_functions.sh − Practical functions to be used in GMT bourne shell scripts
SYNOPSIS
gmt_init_tmpdir
gmt_remove_tmpdir
gmt_clean_up [prefix]
gmt_message message
gmt_abort message
gmt_nrecords file(s)
gmt_nfields string
gmt_get_field string
gmt_get_region file(s) [options]
gmt_get_gridregion file [options]
gmt_get_map_width −R −J
gmt_get_map_height −R −J
gmt_set_psfile file
gmt_set_framename prefix framenumber
gmt_set_framenext framenumber
DESCRIPTION
gmt_shell_functions.sh provides a set of functions to Bourne (again) shell scripts in support of GMT. The
calling shell script should include the following line, before the functions can be used:
. gmt_shell_functions.sh
Once included in a shell script, gmt_shell_functions.sh allows GMT users to do some scripting more eas-
ily than otherwise. The functions made available are:
gmt_init_tmpdir
Creates a temporary directory in /tmp or (when defined) in the directory specified by the environ-
ment variable TMPDIR. The name of the temporary directory is returned as environment variable
GMT_TMPDIR. This function also causes GMT to run in ‘isolation mode’, i.e., all temporary
files will be created in GMT_TMPDIR and the .gmtdefaults file will not be adjusted.
gmt_remove_tmpdir
Removes the temporary directory and unsets the GMT_TMPDIR environment variable.
gmt_cleanup
Remove all files and directories in which the current process number is part of the file name. If the
optional prefix is given then we also delete all files and directories that begins with the given pre-
fix.
gmt_message
Send a message to standard error.
gmt_abort
Send a message to standard error and exit the shell.
gmt_nrecords
Returns the total number of lines in file(s)
gmt_nfields
Returns the number of fields or words in string
gmt_get_field
Returns the given field in a string. Must pass string between double quotes to preserve it as one
item.
GMT 4.5.14 1 Nov 2015 1

GMT_SHELL_FUNCTIONS.SH(1) Generic Mapping Tools GMT_SHELL_FUNCTIONS.SH(1)
gmt_get_region
Returns the region in the form w/e/s/n based on the data in table file(s). Optionally add -Idx/dy to
round off the answer.
gmt_get_gridregion
Returns the region in the form w/e/s/n based on the header of a grid file. Optionally add -Idx/dy to
round off the answer.
gmt_map_width
Expects the user to give the desired -R −J settings and returns the map width in the current mea-
surement unit.
gmt_map_height
Expects the user to give the desired -R −J settings and returns the map height in the current mea-
surement unit.
gmt_set_psfile
Create the output PostScript file name based on the base name of a given file (usually the script
name $0).
gmt_set_framename
Returns a lexically ordered filename stem (i.e., no extension) given the file prefix and the current
frame number, using a width of 6 for the integer including leading zeros. Useful when creating
animations and lexically sorted filenames are required.
gmt_set_framenext
Accepts the current frame integer counter and returns the next integer counter.
NOTES
1. These functions only work in the bourne shell (sh) and their derivatives (like ash, bash, ksh and zsh).
These functions do not work in the C shell (csh) or their derivatives (like tcsh), and cannot be used in DOS
batch scripts either.
2. gmt_shell_functions.sh were first introduced in GMT version 4.2.2 and have since been regularly
expanded with other practical scripting short-cuts. If you want to suggest other functions, please do so by
mailing to the GMT user forum on gmt.soest.hawaii.edu.
SEE ALSO
GMT (1), sh(1), bash(1), minmax(1), grdinfo(1)
GMT 4.5.14 1 Nov 2015 2

GMTCOLORS(5) Generic Mapping Tools GMTCOLORS(5)
NAME
gmtcolors − Explanation of color codes in GMT
DESCRIPTION
Colors can be specified in GMT as arguments to commands, generally as part of the −G or −W options to
select polygon fill or outline pen. Colors are also used in color pallette tables (cpt files) that help convert
numerical values to colors.
GMT allows several ways to represent a color:
Colorname
Specify one of the named colors below. All names are case-insensitive.
R/G/B Specify Red, Green, and Blue levels. Each value is separated by a slash and is in the range from 0
(dark) to 255 (light). This representation is used to color monitors.
#RRGGBB
Specify Red, Green, and Blue levels in the way that it is done in HTML. Use two characters for
each color channel, ranging from 00 (dark) to FF (light). Upper and lower case are allowed.
Graylevel
For shades of gray, R = G = B, and only one number needs to be used. This representation is pop-
ular with black and white printers.
H-S-V Specify Hue in the range 0 to 360 (degrees), S saturation between 0 (not saturated) and 1 (fully
saturated), and value V between 0 (dark) and 1 (light). Number are separated by hyphens. This
representation can be helpful when hue varies a lot.
C/M/Y/K
Specify Cyan, Magenta, Yellow, and blacK. Each number is in the range from 0 (no paint) to 1
(maximum paint). This representation is used by most color printers.
LIST OF COLORS
The following list contains the named colors that can be used in GMT and their equivalent color codes.
R G B Name
255 250 250 snow
248 248 255 ghostwhite
255 250 240 floralwhite
255 245 238 seashell
253 245 230 oldlace
250 240 230 linen
250 235 215 antiquewhite
255 239 213 papayawhip
255 235 205 blanchedalmond
255 228 196 bisque
255 218 185 peachpuff
255 222 173 navajowhite
255 228 181 moccasin
255 250 205 lemonchiffon
255 248 220 cornsilk
255 255 240 ivory
240 255 240 honeydew
245 255 250 mintcream
240 255 255 azure
240 248 255 aliceblue
230 230 250 lavender
255 240 245 lavenderblush
255 228 225 mistyrose
25 25 112 midnightblue
GMT 4.5.14 1 Nov 2015 1

0 0 128 navy
0 0 128 navyblue
100 149 237 cornflowerblue
72 61 139 darkslateblue
106 90 205 slateblue
123 104 238 mediumslateblue
132 112 255 lightslateblue
0 0 205 mediumblue
65 105 225 royalblue
0 0 255 blue
0 0 139 darkblue
30 144 255 dodgerblue
70 130 180 steelblue
0 191 255 deepskyblue
135 206 235 skyblue
135 206 250 lightskyblue
119 136 153 lightslategray
119 136 153 lightslategrey
112 128 144 slategray
112 128 144 slategrey
176 196 222 lightsteelblue
173 216 230 lightblue
224 255 255 lightcyan
176 224 230 powderblue
175 238 238 paleturquoise
95 158 160 cadetblue
0 206 209 darkturquoise
72 209 204 mediumturquoise
64 224 208 turquoise
0 255 255 cyan
0 139 139 darkcyan
47 79 79 darkslategray
47 79 79 darkslategrey
102 205 170 mediumaquamarine
127 255 212 aquamarine
0 100 0 darkgreen
144 238 144 lightgreen
143 188 143 darkseagreen
46 139 87 seagreen
60 179 113 mediumseagreen
32 178 170 lightseagreen
152 251 152 palegreen
0 255 127 springgreen
124 252 0 lawngreen
0 255 0 green
127 255 0 chartreuse
0 250 154 mediumspringgreen
173 255 47 greenyellow
50 205 50 limegreen
154 205 50 yellowgreen
34 139 34 forestgreen
107 142 35 olivedrab
85 107 47 darkolivegreen
189 183 107 darkkhaki
GMT 4.5.14 1 Nov 2015 2

240 230 140 khaki

238 232 170 palegoldenrod
238 221 130 lightgoldenrod
255 255 224 lightyellow
250 250 210 lightgoldenrodyellow
255 255 0 yellow
128 128 0 darkyellow
255 215 0 gold
218 165 32 goldenrod
184 134 11 darkgoldenrod
188 143 143 rosybrown
205 92 92 indianred
139 69 19 saddlebrown
160 82 45 sienna
205 133 63 peru
222 184 135 burlywood
245 245 220 beige
245 222 179 wheat
244 164 96 sandybrown
210 180 140 tan
210 105 30 chocolate
178 34 34 firebrick
235 190 85 lightbrown
165 42 42 brown
120 60 30 darkbrown
233 150 122 darksalmon
250 128 114 salmon
255 160 122 lightsalmon
255 192 128 lightorange
255 165 0 orange
255 140 0 darkorange
255 127 80 coral
240 128 128 lightcoral
255 99 71 tomato
255 69 0 orangered
255 0 0 red
255 128 128 lightred
139 0 0 darkred
255 20 147 deeppink
255 105 180 hotpink
255 192 203 pink
255 182 193 lightpink
219 112 147 palevioletred
176 48 96 maroon
199 21 133 mediumvioletred
208 32 144 violetred
139 0 139 darkmagenta
255 0 255 magenta
255 128 255 lightmagenta
238 130 238 violet
218 112 214 orchid
221 160 221 plum
186 85 211 mediumorchid
153 50 204 darkorchid
GMT 4.5.14 1 Nov 2015 3

148 0 211 darkviolet

138 43 226 blueviolet
160 32 240 purple
147 112 219 mediumpurple
216 191 216 thistle
0 0 0 black
105 105 105 dimgray
105 105 105 dimgrey
169 169 169 darkgray
169 169 169 darkgrey
190 190 190 gray
190 190 190 grey
211 211 211 lightgrey
211 211 211 lightgray
220 220 220 gainsboro
245 245 245 whitesmoke
255 255 255 white
255 250 250 snow1
238 233 233 snow2
205 201 201 snow3
139 137 137 snow4
255 245 238 seashell1
238 229 222 seashell2
205 197 191 seashell3
139 134 130 seashell4
255 239 219 antiquewhite1
255 228 196 bisque1
238 213 183 bisque2
205 183 158 bisque3
139 125 107 bisque4
255 218 185 peachpuff1
255 222 173 navajowhite1
255 250 205 lemonchiffon1
255 248 220 cornsilk1
238 232 205 cornsilk2
205 200 177 cornsilk3
139 136 120 cornsilk4
255 255 240 ivory1
238 238 224 ivory2
205 205 193 ivory3
139 139 131 ivory4
240 255 240 honeydew1
GMT 4.5.14 1 Nov 2015 4

224 238 224 honeydew2

193 205 193 honeydew3
131 139 131 honeydew4
255 240 245 lavenderblush1
255 228 225 mistyrose1
240 255 255 azure1
224 238 238 azure2
193 205 205 azure3
131 139 139 azure4
131 111 255 slateblue1
72 118 255 royalblue1
0 0 255 blue1
0 0 238 blue2
0 0 205 blue3
0 0 139 blue4
30 144 255 dodgerblue1
99 184 255 steelblue1
0 191 255 deepskyblue1
135 206 255 skyblue1
126 192 238 skyblue2
108 166 205 skyblue3
74 112 139 skyblue4
176 226 255 lightskyblue1
198 226 255 slategray1
202 225 255 lightsteelblue1
GMT 4.5.14 1 Nov 2015 5


191 239 255 lightblue1
224 255 255 lightcyan1
187 255 255 paleturquoise1
152 245 255 cadetblue1
0 245 255 turquoise1
0 255 255 cyan1
0 238 238 cyan2
0 205 205 cyan3
0 139 139 cyan4
151 255 255 darkslategray1
127 255 212 aquamarine1
193 255 193 darkseagreen1
84 255 159 seagreen1
46 139 87 seagreen4
154 255 154 palegreen1
0 255 127 springgreen1
0 255 0 green1
0 238 0 green2
0 205 0 green3
0 139 0 green4
127 255 0 chartreuse1
GMT 4.5.14 1 Nov 2015 6


192 255 62 olivedrab1
202 255 112 darkolivegreen1
255 246 143 khaki1
238 230 133 khaki2
205 198 115 khaki3
139 134 78 khaki4
255 236 139 lightgoldenrod1
255 255 224 lightyellow1
255 255 0 yellow1
238 238 0 yellow2
205 205 0 yellow3
139 139 0 yellow4
255 215 0 gold1
238 201 0 gold2
205 173 0 gold3
139 117 0 gold4
255 193 37 goldenrod1
255 185 15 darkgoldenrod1
255 193 193 rosybrown1
255 106 106 indianred1
255 130 71 sienna1
238 121 66 sienna2
205 104 57 sienna3
139 71 38 sienna4
255 211 155 burlywood1
GMT 4.5.14 1 Nov 2015 7


255 231 186 wheat1
238 216 174 wheat2
205 186 150 wheat3
139 126 102 wheat4
255 165 79 tan1
238 154 73 tan2
205 133 63 tan3
139 90 43 tan4
255 127 36 chocolate1
255 48 48 firebrick1
255 64 64 brown1
238 59 59 brown2
205 51 51 brown3
139 35 35 brown4
255 140 105 salmon1
238 130 98 salmon2
205 112 84 salmon3
139 76 57 salmon4
255 160 122 lightsalmon1
255 165 0 orange1
238 154 0 orange2
205 133 0 orange3
139 90 0 orange4
255 127 0 darkorange1
255 114 86 coral1
238 106 80 coral2
205 91 69 coral3
139 62 47 coral4
255 99 71 tomato1
238 92 66 tomato2
205 79 57 tomato3
139 54 38 tomato4
255 69 0 orangered1
238 64 0 orangered2
205 55 0 orangered3
139 37 0 orangered4
255 0 0 red1
238 0 0 red2
205 0 0 red3
139 0 0 red4
255 20 147 deeppink1
GMT 4.5.14 1 Nov 2015 8


139 10 80 deeppink4
255 110 180 hotpink1
238 106 167 hotpink2
205 96 144 hotpink3
139 58 98 hotpink4
255 181 197 pink1
238 169 184 pink2
205 145 158 pink3
139 99 108 pink4
255 174 185 lightpink1
255 130 171 palevioletred1
255 52 179 maroon1
238 48 167 maroon2
205 41 144 maroon3
139 28 98 maroon4
255 62 150 violetred1
255 0 255 magenta1
238 0 238 magenta2
205 0 205 magenta3
139 0 139 magenta4
255 131 250 orchid1
238 122 233 orchid2
205 105 201 orchid3
139 71 137 orchid4
255 187 255 plum1
238 174 238 plum2
205 150 205 plum3
139 102 139 plum4
224 102 255 mediumorchid1
191 62 255 darkorchid1
155 48 255 purple1
145 44 238 purple2
125 38 205 purple3
85 26 139 purple4
171 130 255 mediumpurple1
GMT 4.5.14 1 Nov 2015 9

255 225 255 thistle1
238 210 238 thistle2
205 181 205 thistle3
139 123 139 thistle4
0 0 0 gray0
0 0 0 grey0
3 3 3 gray1
3 3 3 grey1
5 5 5 gray2
5 5 5 grey2
8 8 8 gray3
8 8 8 grey3
10 10 10 gray4
10 10 10 grey4
13 13 13 gray5
13 13 13 grey5
15 15 15 gray6
15 15 15 grey6
18 18 18 gray7
18 18 18 grey7
20 20 20 gray8
20 20 20 grey8
23 23 23 gray9
23 23 23 grey9
26 26 26 gray10
26 26 26 grey10
28 28 28 gray11
28 28 28 grey11
31 31 31 gray12
31 31 31 grey12
33 33 33 gray13
33 33 33 grey13
36 36 36 gray14
36 36 36 grey14
38 38 38 gray15
38 38 38 grey15
41 41 41 gray16
41 41 41 grey16
43 43 43 gray17
43 43 43 grey17
46 46 46 gray18
46 46 46 grey18
48 48 48 gray19
48 48 48 grey19
51 51 51 gray20
51 51 51 grey20
54 54 54 gray21
54 54 54 grey21
56 56 56 gray22
56 56 56 grey22
59 59 59 gray23
59 59 59 grey23
61 61 61 gray24
GMT 4.5.14 1 Nov 2015 10

61 61 61 grey24
64 64 64 gray25
64 64 64 grey25
66 66 66 gray26
66 66 66 grey26
69 69 69 gray27
69 69 69 grey27
71 71 71 gray28
71 71 71 grey28
74 74 74 gray29
74 74 74 grey29
77 77 77 gray30
77 77 77 grey30
79 79 79 gray31
79 79 79 grey31
82 82 82 gray32
82 82 82 grey32
84 84 84 gray33
84 84 84 grey33
87 87 87 gray34
87 87 87 grey34
89 89 89 gray35
89 89 89 grey35
92 92 92 gray36
92 92 92 grey36
94 94 94 gray37
94 94 94 grey37
97 97 97 gray38
97 97 97 grey38
99 99 99 gray39
99 99 99 grey39
102 102 102 gray40
102 102 102 grey40
105 105 105 gray41
105 105 105 grey41
107 107 107 gray42
107 107 107 grey42
110 110 110 gray43
110 110 110 grey43
112 112 112 gray44
112 112 112 grey44
115 115 115 gray45
115 115 115 grey45
117 117 117 gray46
117 117 117 grey46
120 120 120 gray47
120 120 120 grey47
122 122 122 gray48
122 122 122 grey48
125 125 125 gray49
125 125 125 grey49
127 127 127 gray50
127 127 127 grey50
130 130 130 gray51
GMT 4.5.14 1 Nov 2015 11

130 130 130 grey51

133 133 133 gray52
133 133 133 grey52
135 135 135 gray53
135 135 135 grey53
138 138 138 gray54
138 138 138 grey54
140 140 140 gray55
140 140 140 grey55
143 143 143 gray56
143 143 143 grey56
145 145 145 gray57
145 145 145 grey57
148 148 148 gray58
148 148 148 grey58
150 150 150 gray59
150 150 150 grey59
153 153 153 gray60
153 153 153 grey60
156 156 156 gray61
156 156 156 grey61
158 158 158 gray62
158 158 158 grey62
161 161 161 gray63
161 161 161 grey63
163 163 163 gray64
163 163 163 grey64
166 166 166 gray65
166 166 166 grey65
168 168 168 gray66
168 168 168 grey66
171 171 171 gray67
171 171 171 grey67
173 173 173 gray68
173 173 173 grey68
176 176 176 gray69
176 176 176 grey69
179 179 179 gray70
179 179 179 grey70
181 181 181 gray71
181 181 181 grey71
184 184 184 gray72
184 184 184 grey72
186 186 186 gray73
186 186 186 grey73
189 189 189 gray74
189 189 189 grey74
191 191 191 gray75
191 191 191 grey75
194 194 194 gray76
194 194 194 grey76
196 196 196 gray77
196 196 196 grey77
199 199 199 gray78
GMT 4.5.14 1 Nov 2015 12

199 199 199 grey78

201 201 201 gray79
201 201 201 grey79
204 204 204 gray80
204 204 204 grey80
207 207 207 gray81
207 207 207 grey81
209 209 209 gray82
209 209 209 grey82
212 212 212 gray83
212 212 212 grey83
214 214 214 gray84
214 214 214 grey84
217 217 217 gray85
217 217 217 grey85
219 219 219 gray86
219 219 219 grey86
222 222 222 gray87
222 222 222 grey87
224 224 224 gray88
224 224 224 grey88
227 227 227 gray89
227 227 227 grey89
229 229 229 gray90
229 229 229 grey90
232 232 232 gray91
232 232 232 grey91
235 235 235 gray92
235 235 235 grey92
237 237 237 gray93
237 237 237 grey93
240 240 240 gray94
240 240 240 grey94
242 242 242 gray95
242 242 242 grey95
245 245 245 gray96
245 245 245 grey96
247 247 247 gray97
247 247 247 grey97
250 250 250 gray98
250 250 250 grey98
252 252 252 gray99
252 252 252 grey99
255 255 255 gray100
255 255 255 grey100
FURTHER INFORMATION
For more information on the use of color, read Appendix I of the GMT TECHNICAL REFERENCE
AND COOKBOOK.
SEE ALSO
gmtdefaults(1), gmtlogo(1), grdcontour(1), grdvector(1), grdview(1), psbasemap(1), pscoast(1), pscon-
tour(1), pshistogram(1), psimage(1), pslegend(1), psmask(1), psrose(1), pstext(1), pswiggle(1), psxy(1),
psxyz(1)
GMT 4.5.14 1 Nov 2015 13

GMTCONVERT(1) Generic Mapping Tools GMTCONVERT(1)
NAME
gmtconvert − Converts, Pastes, and/or Extracts columns from ASCII and binary 1-D tables
SYNOPSIS
gmtconvert [ inputfiles ] [ −A ] [ −D[template] ] [ −E[f|l] ] [ −Fcols ] [ −H[i][nrec] ] [ −L ] [ −I ] [ −N ] [
−S[˜]"search string" ] [ −V ] [ −:[i|o] ] [ −b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ] [
−g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] ] [ −m[i|o][flag] ]
DESCRIPTION
gmtconvert reads its standard input [or inputfiles] and writes out the desired information to standard out-
put. It can do a combination of three things: (1) convert between binary and ASCII data tables, (2) paste
corresponding records from multiple files into a single file, (3) extract a subset of the columns, (4) only
extract segments whose header matches a text pattern search, (5) just list all multisegment headers and no
data records, and (6) extract first and last data record for each segment. Input (and hence output) may have
multiple subheaders if −m is selected, and ASCII tables may have regular headers as well.
datafile(s)
ASCII (or binary, see −bi) file(s) holding a number of data columns.
OPTIONS
−A The records from the input files should be pasted horizontally, not appended vertically. [Default
processes one file at the time]. Note for binary input, all the files you want to paste must have the
same number of columns (as set with −bi).
−D For multiple segment data, dump each segment to a separate output file [Default writes a multiple
segment file to stdout]. Append a format template for the individual file names; this template
must contain a C format specifier that can format an integer argument (the segment number); this
is usually %d but could be %8.8d which gives leading zeros, etc. [Default is gmtconvert_seg-
ment_%d.d].
−E Only extract the first and last record for each segment of interest [Default extracts all records].
Optionally, append f or l to only extract the first or last record of each segment, respectively.
−F Give a comma-separated list of desired columns or ranges (0 is first column) [Default outputs all
columns].
skipped.
−I Invert the order of rows, i.e., output the final records in reverse order, starting with the last and
ending up with the first input row [Default goes forward].
−L Only output a listing of all multisegment header records and no data records (requires −m and
ASCII data).
−N Do not write records that only contain NaNs in every field [Default writes all records].
−S Only output those segments whose header record contains the specified text string. To reverse the
search, i.e., to output segments whose headers do not contain the specified pattern, use −S˜.
Should your pattern happen to start with ˜ you need to escape this character with a backslash
[Default output all segments].
GMT 4.5.14 1 Nov 2015 1

−g 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. Regarding optional signs: -ve means previous
minus current column value must exceed |gap to be a gap, +ve means current minus previous col-
umn value must exceed gap, and no sign means the absolute value of the difference must exceed
gap. For geographic data (x|y|d), the unit u may be meter [Default], kilometer, miles, or nautical
miles. For projected data (X|Y|D), choose from inch, centimeter, meter, or points [Default unit set
by MEASURE_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.
−m Multiple segment file(s). Segments are separated by a special record. For ASCII files the first
character must be flag [Default is ’>’]. For binary files all fields must be NaN and −b must set the
number of output columns explicitly. By default the −m setting applies to both input and output.
Use −mi and −mo to give separate settings to input and output.
D_FORMAT setting.
EXAMPLES
To convert the binary file test.b (single precision) with 4 columns to ASCII:
gmtconvert test.b −bis 4 > test.dat
To convert the multiple segment ASCII table test.d to a double precision binary file:
gmtconvert test.d −m −bo > test.b
You have an ASCII table with 6 columns and you want to plot column 5 versus column 0. Try
gmtconvert table.d −F 5,0 | psxy ...
If the file instead is the binary file results.b which has 9 single-precision values per record, we extract the
last column and columns 4-6 and write ASCII with the command
gmtconvert results.b −F 8,4-6 -bi9s | psxy ...
You want to plot the 2nd column of a 2-column file left.d versus the first column of a file right.d:
gmtconvert left.d right.d −A −F 1,2 | psxy ...
GMT 4.5.14 1 Nov 2015 2

To extract all segments in the file big_file.d whose headers contain the string "RIDGE AXIS", try
gmtconvert big_file.d −m −S"RIDGE AXIS" > subset.d

SEE ALSO
GMT (1), minmax(1)
GMT 4.5.14 1 Nov 2015 3

GMTDEFAULTS(1) Generic Mapping Tools GMTDEFAULTS(1)
NAME
gmtdefaults − To list current GMT defaults
SYNOPSIS
gmtdefaults −D[u|s] | −L
DESCRIPTION
gmtdefaults lists the GMT parameter defaults if the option −D is used. There are three ways to change
some of the settings: (1) Use the command gmtset, (2) use any texteditor to edit the file .gmtdefaults4 in
your home, ˜/.gmt or current directory (if you do not have this file, run gmtdefaults -D > ˜/.gmtdefaults4 to
get one with the system default settings), or (3) override any parameter by specifying one or more
−−PARAMETER=value statements on the commandline of any GMT command (PARAMETER and
VALUE are any combination listed below). The first two options are permanent changes until explicitly
changed back, while the last option is ephemeral and only applies to the single GMT command that
received the override. GMT can provide default values in US or SI units. This choice is determined by the
contents of the gmt_setup.conf file in GMT’s share directory.
−D Print the system GMT defaults to standard output. Append u for US defaults or s for SI defaults.
[−D alone gives current choice in gmt_setup.conf].
−L Print the user’s currently active defaults to standard output.
Your currently active defaults come from the .gmtdefaults4 file in the current working directory, if
present; else from the .gmtdefaults4 file in your home directory, if present; else from the file
˜/.gmt/.gmtdefaults4, if present; else from the system defaults set at the time GMT was compiled.
GMT PARAMETERS
The following is a list of the parameters that are user-definable in GMT. The parameter names are always
given in UPPER CASE. The parameter values are case-insensitive unless otherwise noted. The system
defaults are given in brackets [ for SI (and US) ]. Those marked * can be set on the command line as well
(the corresponding option is given in parentheses). Note that default distances and lengths below are given
in both cm or inch; the chosen default depends on your choice of default unit (see MEASURE_UNIT).
You can explicitly specify the unit used for distances and lengths by appending c (cm), i (inch), m (meter),
or p (points). When no unit is indicated the value will be assumed to be in the unit set by MEA-
SURE_UNIT. Note that the printer resolution DOTS_PR_INCH is always the number of dots or pixels
per inch. Several parameters take only TRUE or FALSE.
ANNOT_FONT_PRIMARY
Font used for upper annotations, etc. [Helvetica]. Specify either the font number or the font name
(case sensitive!). The 35 available fonts are:
0 Helvetica
1 Helvetica-Bold
2 Helvetica-Oblique
3 Helvetica-BoldOblique
4 Times-Roman
5 Times-Bold
6 Times-Italic
7 Times-BoldItalic
8 Courier
9 Courier-Bold
10 Courier-Oblique
11 Courier-BoldOblique
12 Symbol
13 AvantGarde-Book
14 AvantGarde-BookOblique
15 AvantGarde-Demi
16 AvantGarde-DemiOblique
GMT 4.5.14 1 Nov 2015 1

17 Bookman-Demi
18 Bookman-DemiItalic
19 Bookman-Light
20 Bookman-LightItalic
21 Helvetica-Narrow
22 Helvetica-Narrow-Bold
23 Helvetica-Narrow-Oblique
24 Helvetica-Narrow-BoldOblique
25 NewCenturySchlbk-Roman
26 NewCenturySchlbk-Italic
27 NewCenturySchlbk-Bold
28 NewCenturySchlbk-BoldItalic
29 Palatino-Roman
30 Palatino-Italic
31 Palatino-Bold
32 Palatino-BoldItalic
33 ZapfChancery-MediumItalic
34 ZapfDingbats
ANNOT_FONT_SIZE_PRIMARY
Font size (> 0) for map annotations [14p].
ANNOT_FONT_SECONDARY
Font to use for time axis secondary annotations. See ANNOT_FONT_PRIMARY for available
fonts [Helvetica].
ANNOT_FONT_SIZE_SECONDARY
Font size (> 0) for time axis secondary annotations [16p].
ANNOT_MIN_ANGLE
If the angle between the map boundary and the annotation baseline is less than this minimum
value (in degrees), the annotation is not plotted (this may occur for certain oblique projections.)
Give a value in the range 0−90. [20]
ANNOT_MIN_SPACING
If an annotation would be plotted less than this minimum distance from its closest neighbor, the
annotation is not plotted (this may occur for certain oblique projections.) [0]
ANNOT_OFFSET_PRIMARY
Distance from end of tickmark to start of annotation [0.2c (or 0.075i)]. A negative offset will
place the annotation inside the map border.
ANNOT_OFFSET_SECONDARY
Distance from base of primary annotation to the top of the secondary annotation [0.2c (or 0.075i)]
(Only applies to time axes with both primary and secondary annotations).
BASEMAP_AXES
Sets which axes to draw and annotate. Case sensitive: Upper case means both draw and annotate,
lower case means draw axis only. [WESN].
BASEMAP_FRAME_RGB
Color used to draw map boundaries and annotations. Give a red/green/blue triplet, with each ele-
ment in the 0−255 range. Prepend ’+’ to replicate this color to the tick-, grid-, and frame-pens.
[0/0/0] (black).
BASEMAP_TYPE
Choose between inside, graph, plain and fancy (thick boundary, alternating black/white frame;
append + for rounded corners) [fancy]. For some map projections (e.g., Oblique Mercator), plain
is the only option even if fancy is set as default. In general, fancy only applies to situations where
the projected x and y directions parallel the lon and lat directions (e.g., rectangular projections,
GMT 4.5.14 1 Nov 2015 2

polar projections). For situations where all boundary ticks and annotations must be inside the
maps (e.g., for preparing geotiffs), chose inside. Finally, graph is used for linear projections only
and will extend the axis by 7.5% and add arrow heads.
CHAR_ENCODING
Names the eight bit character set being used for text in files and in command line parameters. This
allows GMT to ensure that the PostScript output generates the correct characters on the plot..
Choose from Standard, Standard+, ISOLatin1, ISOLatin1+, and ISO-8859-x (where x is in the
ranges 1-10 or 13-15). See Appendix F for details [ISOLatin1+ (or Standard+)].
COLOR_BACKGROUND
Color used for the background of images (i.e., when z < lowest colortable entry). Give a
red/green/blue triplet, with each element in the 0−255 range. [0/0/0] (black)
COLOR_FOREGROUND
Color used for the foreground of images (i.e., when z > highest colortable entry). Give a
red/green/blue triplet, with each element in the 0−255 range. [255/255/255] (white)
COLOR_IMAGE
Selects which operator to use when rendering bit-mapped color images. Due to the lack of the
colorimage operator in some PostScript implementations, as well as some PostScript editors
inability to handle color gradations, GMT offers two different options:
adobe (Adobe’s colorimage definition) [Default].

tiles (Plot image as many individual rectangles).
COLOR_MODEL
Selects if color palette files contain RGB values (r,g,b in 0-255 range), HSV values (h in 0-360, s,v
in 0-1 range), or CMYK values (c,m,y,k in 0-1 range). A COLOR_MODEL setting in the color
palette file will override this setting. Internally, color interpolation takes place directly on the
RGB values which can give unexpected hues, whereas interpolation directly on the HSV values
better preserves the hues. Prepend the prefix "+" to force interpolation in the selected color system
(does not apply to the CMYK system). For this additional option, the defaults take precedence
over the color palette file [rgb].
COLOR_NAN
Color used for the non-defined areas of images (i.e., where z == NaN). Give a red/green/blue
triplet, with each element in the 0−255 range. [128/128/128] (gray)
D_FORMAT
Output format (C language printf syntax) to be used when printing double precision floating point
numbers. For geographic coordinates, see OUTPUT_DEGREE_FORMAT. [%.12g].
DEGREE_SYMBOL
Determines what symbol is used to plot the degree symbol on geographic map annotations.
Choose between ring, degree, colon, or none [ring].
DOTS_PR_INCH
Resolution of the plotting device (dpi). Note that in order to be as compact as possible, GMT
PostScript output uses integer formats only so the resolution should be set depending on what out-
put device you are using. E.g, using 300 and sending the output to a Linotype 300 phototypesetter
(2470 dpi) will not take advantage of the extra resolution (i.e., positioning on the page and line
thicknesses are still only done in steps of 1/300 inch; of course, text will look smoother) [300].
ELLIPSOID
The (case sensitive) name of the ellipsoid used for the map projections [WGS-84]. Choose
among:
WGS-84 : World Geodetic System [Default] (1984)

OSU91A : Ohio State University (1991)
GMT 4.5.14 1 Nov 2015 3

OSU86F : Ohio State University (1986)

Engelis : Goddard Earth Models (1985)
SGS-85 : Soviet Geodetic System (1985)
TOPEX : Used commonly for altimetry (1990)
MERIT-83 : United States Naval Observatory (1983)
GRS-80 : International Geodetic Reference System (1980)
Hughes-1980 : Hughes Aircraft Company for DMSP SSM/I grid products (1980)
Lerch : For geoid modelling (1979)
ATS77 : Average Terrestrial System, Canada Maritime provinces (1977)
IAG-75 : International Association of Geodesy (1975)
Indonesian : Applies to Indonesia (1974)
WGS-72 : World Geodetic System (1972)
NWL-10D : Naval Weapons Lab (Same as WGS-72) (1972)
South-American : Applies to South America (1969)
Fischer-1968 : Used by NASA for Mercury program (1968)
Modified-Mercury-1968 : Same as Fischer-1968 (1968)
GRS-67 : International Geodetic Reference System (1967)
International-1967 : Worldwide use (1967)
NWL-9D : Naval Weapons Lab (Same as WGS-66) (1966)
Australian : Applies to Australia (1965)
APL4.9 : Appl. Physics (1965)
Kaula : From satellite tracking (1961)
Hough : Applies to the Marshall Islands (1960)
Fischer-1960 : Used by NASA for Mercury program (1960)
Mercury-1960 : Same as Fischer-1960 (1960)
Modified-Fischer-1960 : Applies to Singapore (1960)
Fischer-1960-SouthAsia : Same as Modified-Fischer-1960 (1960)
Krassovsky : Used in the (now former) Soviet Union (1940)
War-Office : Developed by G. T. McCaw (1926)
International-1924 : Worldwide use (1924)
Hayford-1909 : Same as the International 1924 (1909)
Helmert-1906 : Applies to Egypt (1906)
Clarke-1880 : Applies to most of Africa, France (1880)
Clarke-1880-Arc1950 : Modified Clarke-1880 for Arc 1950 (1880)
Clarke-1880-IGN : Modified Clarke-1880 for IGN (1880)
Clarke-1880-Jamaica : Modified Clarke-1880 for Jamaica (1880)
Clarke-1880-Merchich : Modified Clarke-1880 for Merchich (1880)
Clarke-1880-Palestine : Modified Clarke-1880 for Palestine (1880)
Andrae : Applies to Denmark and Iceland (1876)
Clarke-1866 : Applies to North America, the Philippines (1866)
Clarke-1866-Michigan : Modified Clarke-1866 for Michigan (1866)
Struve : Friedrich Georg Wilhelm Struve (1860)
Clarke-1858 : Clarke’s early ellipsoid (1858)
Airy : Applies to Great Britain (1830)
Airy-Ireland : Applies to Ireland in 1965 (1830)
Modified-Airy : Same as Airy-Ireland (1830)
Bessel : Applies to Central Europe, Chile, Indonesia (1841)
Bessel-Schwazeck : Applies to Namibia (1841)
Bessel-Namibia : Same as Bessel-Schwazeck (1841)
Bessel-NGO1948 : Modified Bessel for NGO 1948 (1841)
Everest-1830 : India, Burma, Pakistan, Afghanistan, Thailand (1830)
Everest-1830-Kalianpur : Modified Everest for Kalianpur (1956) (1830)
GMT 4.5.14 1 Nov 2015 4

Everest-1830-Kertau : Modified Everest for Kertau, Malaysia & Singapore (1830)

Everest-1830-Timbalai : Modified Everest for Timbalai, Sabah Sarawak (1830)
Everest-1830-Pakistan : Modified Everest for Pakistan (1830)
Walbeck : First least squares solution by Finnish astronomer (1819)
Plessis : Old ellipsoid used in France (1817)
Delambre : Applies to Belgium (1810)
CPM : Comm. des Poids et Mesures, France (1799)
Maupertius : Really old ellipsoid used in France (1738)
Sphere : The mean radius in WGS-84 (for spherical/plate tectonics applications) (1984)
Moon : Moon (IAU2000) (2000)
Mercury : Mercury (IAU2000) (2000)
Venus : Venus (IAU2000) (2000)
Mars : Mars (IAU2000) (2000)
Jupiter : Jupiter (IAU2000) (2000)
Saturn : Saturn (IAU2000) (2000)
Uranus : Uranus (IAU2000) (2000)
Neptune : Neptune (IAU2000) (2000)
Pluto : Pluto (IAU2000) (2000)
Note that for some global projections, GMT may use a spherical approximation of the ellipsoid
chosen, setting the flattening to zero, and using a mean radius. A warning will be given when this
happens. If a different ellipsoid name than those mentioned here is given, GMT will attempt to
parse the name to extract the semi-major axis (a in m) and the flattening. Formats allowed are:
a implies a zero flattening

a,inv_f where inv_f is the inverse flattening
a,b=b where b is the semi-minor axis (in m)
a,f=f where f is the flattening
This way a custom ellipsoid (e.g., those used for other planets) may be used. Further note that
coordinate transformations in mapproject can also specify specific datums; see the mapproject
man page for further details and how to view ellipsoid and datum parameters.
FIELD_DELIMITER
This setting determines what character will separate ASCII output data columns written by GMT.
Choose from tab, space, comma, and none [tab].
FRAME_PEN
Pen attributes used to draw plain map frame in dpi units or points (append p) [1.25p].
FRAME_WIDTH
Width (> 0) of map borders for fancy map frame [0.2c (or 0.075i)].
GLOBAL_X_SCALE
Global x-scale (> 0) to apply to plot-coordinates before plotting. Normally used to shrink the
entire output down to fit a specific height/width [1.0].
GLOBAL_Y_SCALE
Same, but for y-coordinates [1.0].
GRID_CROSS_SIZE_PRIMARY
Size (>= 0) of grid cross at lon-lat intersections. 0 means draw continuous gridlines instead [0].
GRID_CROSS_SIZE_SECONDARY
Size (>= 0) of grid cross at secondary lon-lat intersections. 0 means draw continuous gridlines
instead [0].
GMT 4.5.14 1 Nov 2015 5

GRID_PEN_PRIMARY
Pen attributes used to draw grid lines in dpi units or points (append p) [0.25p].
GRID_PEN_SECONDARY
Pen attributes used to draw grid lines in dpi units or points (append p) [0.5p].
GRIDFILE_FORMAT
Default file format for grids, with optional scale, offset and invalid value, written as ff/scale/off-
set/invalid. The 2-letter format indicator can be one of [bcnsr][bsifd]. The first letter indicates
native GMT binary, old format netCDF, COARDS-compliant netCDF, Surfer format or Sun
Raster format. The second letter stands for byte, short, int, float and double, respectively. When
/invalid is omitted the appropriate value for the given format is used (NaN or largest negative).
When /scale/offset is omitted, /1.0/0.0 is used. [nf].
GRIDFILE_SHORTHAND
If TRUE, all grid file names are examined to see if they use the file extension shorthand discussed
in Section 4.17 of the GMT Technical Reference and Cookbook. If FALSE, no filename expan-
sion is done [FALSE].
HEADER_FONT
Font to use when plotting headers. See ANNOT_FONT_PRIMARY for available fonts [Hel-
vetica].
HEADER_FONT_SIZE
Font size (> 0) for header [36p].
HEADER_OFFSET
Distance from top of axis annotations (or axis label, if present) to base of plot header [0.5c (or
0.1875i)].
HISTORY
If TRUE, passes the history of past common command options via the hidden .gmtcommands4 file
[TRUE].
HSV_MAX_SATURATION
Maximum saturation (0−1) assigned for most positive intensity value [0.1].
HSV_MIN_SATURATION
Minimum saturation (0−1) assigned for most negative intensity value [1.0].
HSV_MAX_VALUE
Maximum value (0−1) assigned for most positive intensity value [1.0].
HSV_MIN_VALUE
Minimum value (0−1) assigned for most negative intensity value [0.3].
INPUT_CLOCK_FORMAT
Formatting template that indicates how an input clock string is formatted. This template is then
used to guide the reading of clock strings in data fields. To properly decode 12-hour clocks,
append am or pm (or upper case) to match your data records. As examples, try hh:mm,
hh:mm:ssAM, etc. [hh:mm:ss].
INPUT_DATE_FORMAT
Formatting template that indicates how an input date string is formatted. This template is then
used to guide the reading of date strings in data fields. You may specify either Gregorian calendar
format or ISO week calendar format. Gregorian calendar: Use any combination of yyyy (or yy for
2-digit years; if so see Y2K_OFFSET_YEAR), mm (or o for abbreviated month name in the cur-
rent time language), and dd, with or without delimiters. For day-of-year data, use jjj instead of
mm and/or dd. Examples can be ddmmyyyy, yy-mm-dd, dd-o-yyyy, yyyy/dd/mm, yyyy-jjj, etc.
ISO Calendar: Expected template is yyyy[-]W[-]ww[-]d, where ww is ISO week and d is ISO
week day. Either template must be consistent, e.g., you cannot specify months if you don’t specify
years. Examples are yyyyWwwd, yyyy-Www, etc. [yyyy-mm-dd].
GMT 4.5.14 1 Nov 2015 6

INTERPOLANT
Determines if linear (linear), Akima’s spline (akima), natural cubic spline (cubic) or no interpola-
tion (none) should be used for 1-D interpolations in various programs [akima].
IO_HEADER
(* −H) Specifies whether input/output ASCII files have header record(s) or not [FALSE].
LABEL_FONT
Font to use when plotting labels below axes. See ANNOT_FONT_PRIMARY for available fonts
[Helvetica].
LABEL_FONT_SIZE
Font size (> 0) for labels [24p].
LABEL_OFFSET
Distance from base of axis annotations to the top of the axis label [0.3c (or 0.1125i)].
LINE_STEP
Determines the maximum length (> 0) of individual straight line-segments when drawing arcuate
lines [0.025c (or 0.01i)]
MAP_SCALE_FACTOR
Changes the default map scale factor used for the Polar Stereographic [0.9996], UTM [0.9996],
and Transverse Mercator [1] projections in order to minimize areal distortion. Provide a new
scale-factor or leave as default.
MAP_SCALE_HEIGHT
Sets the height (> 0) on the map of the map scale bars drawn by various programs [0.2c (or
0.075i)].
MEASURE_UNIT
Sets the unit length. Choose between cm, inch, m, and point. [cm]. Note that, in GMT, one point
is defined as 1/72 inch (the PostScript definition), while it is often defined as 1/72.27 inch in the
typesetting industry. There is no universal definition.
N_COPIES
(* −c) Number of plot copies to make [1].
N_HEADER_RECS
Specifies how many header records to expect if −H is turned on [1].
NAN_RECORDS
Determines what happens when input records containing NaNs for x or y (and in some cases z) are
read. Choose between skip, which will simply report how many bad records were skipped, and
pass [Default], which will pass these records on to the calling programs. For most programs this
will result in output records with NaNs as well, but some will interpret these NaN records to indi-
cate gaps in a series; programs may then use that information to detect segmentation (if applica-
ble).
OBLIQUE_ANNOTATION
This integer is a sum of 6 bit flags (most of which only are relevant for oblique projections): If bit
1 is set (1), annotations will occur wherever a gridline crosses the map boundaries, else longitudes
will be annotated on the lower and upper boundaries only, and latitudes will be annotated on the
left and right boundaries only. If bit 2 is set (2), then longitude annotations will be plotted hori-
zontally. If bit 3 is set (4), then latitude annotations will be plotted horizontally. If bit 4 is set (8),
then oblique tickmarks are extended to give a projection equal to the specified tick_length. If bit 5
is set (16), tickmarks will be drawn normal to the border regardless of gridline angle. If bit 6 is set
(32), then latitude annotations will be plotted parallel to the border. To set a combination of these,
add up the values in parentheses. [1].
GMT 4.5.14 1 Nov 2015 7

OUTPUT_CLOCK_FORMAT
Formatting template that indicates how an output clock string is to be formatted. This template is
then used to guide the writing of clock strings in data fields. To use a floating point format for the
smallest unit (e.g., seconds), append .xxx, where the number of x indicates the desired precision.
If no floating point is indicated then the smallest specified unit will be rounded off to nearest inte-
ger. For 12-hour clocks, append am, AM, a.m., or A.M. (GMT will replace a|A with p|P for pm).
If your template starts with a leading hyphen (-) then each integer item (y,m,d) will be printed
without leading zeros (default uses fixed width formats). As examples, try hh:mm, hh.mm.ss,
hh:mm:ss.xxxx, hha.m., etc. [hh:mm:ss].
OUTPUT_DATE_FORMAT
Formatting template that indicates how an output date string is to be formatted. This template is
then used to guide the writing of date strings in data fields. You may specify either Gregorian cal-
endar format or ISO week calendar format. Gregorian calendar: Use any combination of yyyy (or
yy for 2-digit years; if so see Y2K_OFFSET_YEAR), mm (or o for abbreviated month name in
the current time language), and dd, with or without delimiters. For day-of-year data, use jjj instead
of mm and/or dd. As examples, try yy/mm/dd, yyyy=jjj, dd-o-yyyy, dd-mm-yy, yy-mm, etc. ISO
Calendar: Expected template is yyyy[-]W[-]ww[-]d, where ww is ISO week and d is ISO week
day. Either template must be consistant, e.g., you cannot specify months if you don’t specify
years. As examples, try yyyyWww, yy-W-ww-d, etc. If your template starts with a leading hyphen
(-) then each integer item (y,m,d) will be printed without leading zeros (default uses fixed width
formats) [yyyy-mm-dd].
OUTPUT_DEGREE_FORMAT
Formatting template that indicates how an output geographical coordinate is to be formatted. This
template is then used to guide the writing of geographical coordinates in data fields. The template
is in general of the form [+|-]D or [+|-]ddd[:mm[:ss]][.xxx][F]. By default, longitudes will be
reported in the -180/+180 range. The various terms have the following purpose:
+ Output longitude in the 0 to 360 range [-180/+180]

- Output longitude in the -360 to 0 range [-180/+180]
D Use D_FORMAT for floating point degrees.
ddd Fixed format integer degrees
: delimiter used
mm Fixed format integer arc minutes
ss Fixed format integer arc seconds
F Encode sign using WESN suffix
The default is +D.

PAGE_COLOR
Sets the color of the imaging background, i.e., the paper. Give a red/green/blue triplet, with each
element in the 0−255 range. [255/255/255] (white).
PAPER_MEDIA
Sets the physical format of the current plot paper [A4 (or Letter)]. The following formats (and
their widths and heights in points) are recognized (Additional site-specific formats may be speci-
fied in the gmt_custom_media.conf file in $GMT_SHAREDIR/conf or ˜/.gmt; see that file for
details):
Media width height

A0 2380 3368
A1 1684 2380
A2 1190 1684
A3 842 1190
A4 595 842
A5 421 595
GMT 4.5.14 1 Nov 2015 8

A6 297 421
A7 210 297
A8 148 210
A9 105 148
A10 74 105
B0 2836 4008
B1 2004 2836
B2 1418 2004
B3 1002 1418
B4 709 1002
B5 501 709
archA 648 864
archB 864 1296
archC 1296 1728
archD 1728 2592
archE 2592 3456
flsa 612 936
halfletter 396 612
statement 396 612
note 540 720
letter 612 792
legal 612 1008
11x17 792 1224
tabloid 792 1224
ledger 1224 792
For a completely custom format (e.g., for large format plotters) you may also specify Cus-
tom_WxH, where W and H are in points unless you append a unit to each dimension (c, i, m or p
[Default]). To force the printer to request a manual paper feed, append ’-’ to the media name, e.g.,
A3- will require the user to insert a A3 paper into the printer’s manual feed slot. To indicate you
are making an EPS file, append ’+’ to the media name. Then, GMT will attempt to issue a tight
bounding box [Default Bounding Box is the paper dimension].
PAGE_ORIENTATION
(* −P) Sets the orientation of the page. Choose portrait or landscape [landscape].
PLOT_CLOCK_FORMAT
Formatting template that indicates how an output clock string is to be plotted. This template is
then used to guide the formatting of clock strings in plot annotations. See OUT-
PUT_CLOCK_FORMAT for details. [hh:mm:ss].
PLOT_DATE_FORMAT
Formatting template that indicates how an output date string is to be plotted. This template is then
used to guide the plotting of date strings in data fields. See OUTPUT_DATE_FORMAT for
details. In addition, you may use a single o instead of mm (to plot month name) and u instead of
W[-]ww to plot "Week ##". Both of these text strings will be affected by the TIME_LAN-
GUAGE, TIME_FORMAT_PRIMARY and TIME_FORMAT_SECONDARY setting. [yyyy-
mm-dd].
PLOT_DEGREE_FORMAT
Formatting template that indicates how an output geographical coordinate is to be plotted. This
template is then used to guide the plotting of geographical coordinates in data fields. See OUT-
PUT_DEGREE_FORMAT for details. In addition, you can append A which plots the absolute
value of the coordinate. The default is ddd:mm:ss. Not all items may be plotted as this depends
on the annotation interval.
GMT 4.5.14 1 Nov 2015 9

POLAR_CAP
Controls the appearance of gridlines near the poles for all azimuthal projections and a few others
in which the geographic poles are plotted as points (Lambert Conic, Hammer, Mollweide, Sinu-
soidal, and van der Grinten). Specify either none (in which case there is no special handling) or
pc_lat/pc_dlon. In that case, normal gridlines are only drawn between the latitudes
-pc_lat/+pc_lat, and above those latitudes the gridlines are spaced at the (presumably coarser)
pc_dlon interval; the two domains are separated by a small circle drawn at the pc_lat latitude
[85/90]. Note for r-theta (polar) projection where r = 0 is at the center of the plot the meaning of
the cap is reversed, i.e., the default 85/90 will draw a r = 5 radius circle at the center of the map
with less frequent radial lines there.
PS_COLOR
Determines whether PostScript output should use RGB, HSV, CMYK, or GRAY when specifying
color [rgb]. Note if HSV is selected it does not apply to images which in that case uses RGB.
When selecting GRAY, all colors will be converted to gray scale using YIQ (television) conver-
sion.
PS_IMAGE_COMPRESS
Determines if PostScript images are compressed using the Run-Length Encoding scheme (rle),
Lempel-Ziv-Welch compression (lzw), or not at all (none) [lzw].
PS_IMAGE_FORMAT
Determines whether images created in PostScript should use ASCII or binary format. The latter
takes up less space and executes faster but may choke some printers, especially those off serial
ports. Select ascii or bin [ascii].
PS_LINE_CAP
Determines how the ends of a line segment will be drawn. Choose among a butt cap (default)
where there is no projection beyond the end of the path, a round cap where a semicircular arc with
diameter equal to the linewidth is drawn around the end points, and square cap where a half square
of size equal to the linewidth extends beyond the end of the path [butt].
PS_LINE_JOIN
Determines what happens at kinks in line segments. Choose among a miter join where the outer
edges of the strokes for the two segments are extended until they meet at an angle (as in a picture
frame; if the angle is too acute, a bevel join is used instead, with threshold set by
PS_MITER_LIMIT), round join where a circular arc is used to fill in the cracks at the kinks, and
bevel join which is a miter join that is cut off so kinks are triangular in shape [miter].
PS_MITER_LIMIT
Sets the threshold angle in degrees (integer in 0-180 range) used for mitered joins only. When the
angle between joining line segments is smaller than the threshold the corner will be bevelled
instead of mitered. The default threshold is 35 degrees. Setting the threshold angle to 0 implies
the PostScript default of about 11 degrees. Setting the threshold angle to 180 causes all joins to be
beveled.
PS_VERBOSE
If TRUE we will issue comments in the PostScript file that explain the logic of operations. These
are useful if you need to edit the file and make changes; otherwise you can set it to FALSE which
yields a somewhat slimmer PostScript file [FALSE].
TICK_LENGTH
The length of a tickmark. Normally, tickmarks are drawn on the outside of the map boundaries.
To select interior tickmarks, use a negative tick_length [0.2c (or 0.075i)].
TICK_PEN
Pen attributes to be used for tickmarks in dpi units or points (append p) [0.5p].
GMT 4.5.14 1 Nov 2015 10

TIME_EPOCH
Specifies the value of the calendar and clock at the origin (zero point) of relative time units (see
TIME_UNIT). It is a string of the form yyyy-mm-ddT[hh:mm:ss] (Gregorian) or yyyy-Www-
ddT[hh:mm:ss] (ISO) Default is 2000-01-01T12:00:00, the epoch of the J2000 system.
TIME_FORMAT_PRIMARY
Controls how primary month-, week-, and weekday-names are formatted. Choose among full,
abbreviated, and character. If the leading f, a, or c are replaced with F, A, and C the entire annota-
tion will be in upper case.
TIME_FORMAT_SECONDARY
Controls how secondary month-, week-, and weekday-names are formatted. Choose among full,
abbreviated, and character. If the leading f, a, or c are replaced with F, A, and C the entire annota-
tion will be in upper case.
TIME_INTERVAL_FRACTION
Determines if partial intervals at the start and end of an axis should be annotated. If the range of
the partial interval exceeds the specified fraction of the normal interval stride we will place the
annotation centered on the partial interval [0.5].
TIME_IS_INTERVAL
Used when input calendar data should be truncated and adjusted to the middle of the relevant inter-
val. In the following discussion, the unit u can be one of these time units: (y year, o month, u ISO
week, d day, h hour, m minute, and c second). TIME_IS_INTERVAL can have any of the fol-
lowing three values: (1) OFF [Default]. No adjustment, time is decoded as given. (2) +nu. Acti-
vate interval adjustment for input by truncate to previous whole number of n units and then center
time on the following interval. (3) -nu. Same, but center time on the previous interval. For exam-
ple, with TIME_IS_INTERVAL = +1o, an input data string like 1999-12 will be interpreted to
mean 1999-12-15T12:00:00.0 (exactly middle of December), while if TIME_IS_INTERVAL =
OFF then that date is interpreted to mean 1999-12-01T00:00:00.0 (start of December) [OFF].
TIME_LANGUAGE
Language to use when plotting calendar items such as months and days. Select from:
BR Brazilian Portuguese
CN1 Simplified Chinese
CN2 Traditional Chinese
DE German
DK Danish
EH Basque
ES Spanish
FI Finnish
FR French
GR Greek
HI Hawaiian
HU Hungarian
IE Irish
IL Hebrew
IS Icelandic
IT Italian
JP Japanese
NL Dutch
NO Norwegian
PL Polish
PT Portuguese
RU Russian
SE Swedish
SG Scottish Gaelic
GMT 4.5.14 1 Nov 2015 11

TO Tongan
TR Turkish
UK British English
US US English
If your language is not supported, please examine the $GMT_SHAREDIR/time/us.d file and
make a similar file. Please submit it to the GMT Developers for official inclusion. Custom lan-
guage files can be placed in directories $GMT_SHAREDIR/time or ˜/.gmt.
TIME_SYSTEM
Shorthand for a combination of TIME_EPOCH and TIME_UNIT, specifying which time epoch
the relative time refers to and what the units are. Choose from one of the preset systems below
(epoch and units are indicated):
JD -4713-11-25T12:00:00 d (Julian Date)
MJD 1858-11-17T00:00:00 d (Modified Julian Date)
J2000 2000-01-01T12:00:00 d (Astronomical time)
S1985 1985-01-01T00:00:00 c (Altimetric time)
UNIX 1970-01-01T00:00:00 c (UNIX time)
RD0001 0001-01-01T00:00:00 c
RATA 0000-12-31T00:00:00 d
This parameter is not stored in the .gmtdefaults4 file but is translated to the respective values of
TIME_EPOCH and TIME_UNIT.
TIME_UNIT
Specifies the units of relative time data since epoch (see TIME_EPOCH). Choose y (year -
assumes all years are 365.2425 days), o (month - assumes all months are of equal length y/12), d
(day), h (hour), m (minute), or c (second) [d].
TIME_WEEK_START
When weeks are indicated on time axes, this parameter determines the first day of the week for
Gregorian calendars. (The ISO weekly calendar always begins weeks with Monday.) [Monday
(or Sunday)].
TRANSPARENCY
Makes printed material transparent. Specify transparency in percent: 0 is opaque (normal overlay
plotting), 100 is fully transparent (i.e., nothing will show). Use either as a pair (stroke/fill) to set
the transparency of stroked material (lines) or filled material (polygons) separately, or use a single
number to set both to the same value [0].
Warning: Most printers and PostScript viewers can not print or will not show transparency. They
will simply ignore your attempt to create transparency and will plot any material as opaque.
Ghostscript and all its derivatives like ps2raster, Apple’s Preview and the CUPS printing system
are among those programs incapable of dealing with transparency. If you want to view transparent
material you need to use Acrobat Distiller to create a PDF file. Note that the settings of Acrobat
Distiller need to be changed to make transparency effective: change /AllowTransparency to true in
the .joboptions file.
UNIX_TIME
(* −U) Specifies if a UNIX system time stamp should be plotted at the lower left corner of the plot
[FALSE].
UNIX_TIME_POS
(* −U) Sets the justification and the position of the UNIX time stamp box relative to the current
plots lower left corner of the plot [BL/-2c/-2c (or BL/-0.75i/-0.75i)].
UNIX_TIME_FORMAT
Defines the format of the time information in the UNIX time stamp. This format is parsed by the C
function strftime, so that virtually any text can be used (even not containing any time information)
[%Y %b %d %H:%M:%S].
GMT 4.5.14 1 Nov 2015 12

VECTOR_SHAPE
Determines the shape of the head of a vector. Normally (i.e., for vector_shape = 0), the head will
be triangular, but can be changed to an arrow (1) or an open V (2). Intermediate settings give
something in between. Negative values (up to -2) are allowed as well [0].
VERBOSE
(* −V) Determines if GMT programs should display run-time information or run silently
[FALSE].
X_AXIS_LENGTH
Sets the default length (> 0) of the x-axis [25c (or 9i)].
X_ORIGIN
(* −X) Sets the x-coordinate of the origin on the paper for a new plot [2.5c (or 1i)]. For an over-
lay, the default offset is 0.
XY_TOGGLE
(* −:) Set if the first two columns of input and output files contain (latitude,longitude) or (y,x)
rather than the expected (longitude,latitude) or (x,y). FALSE means we have (x,y) both on input
and output. TRUE means both input and output should be (y,x). IN means only input has (y,x),
while OUT means only output should be (y,x). [FALSE].
Y_AXIS_LENGTH
Sets the default length (> 0) of the y-axis [15c (or 6i)].
Y_ORIGIN
(* −Y) Sets the y-coordinate of the origin on the paper for a new plot [2.5c (or 1i)]. For an over-
lay, the default offset is 0.
Y_AXIS_TYPE
Determines if the annotations for a y-axis (for linear projections) should be plotted horizontally
(hor_text) or vertically (ver_text) [hor_text].
Y2K_OFFSET_YEAR
When 2-digit years are used to represent 4-digit years (see various DATE_FORMATs),
Y2K_OFFSET_YEAR gives the first year in a 100-year sequence. For example, if Y2K_OFF-
SET_YEAR is 1729, then numbers 29 through 99 correspond to 1729 through 1799, while num-
bers 00 through 28 correspond to 1800 through 1828. [1950].
SPECIFYING PENS
pen The attributes of lines and symbol outlines as defined by pen is a comma delimetered list of width,
color and texture, each of which is optional. width can be indicated as a measure (points, centime-
ters, inches) or as faint, thin[ner|nest], thick[er|est], fat[ter|test], or obese. color specifies a gray
shade or color (see SPECIFYING COLOR below). texture is a combination of dashes ‘-’ and dots
‘.’.
SPECIFYING FILL
fill The attribute fill specifies the solid shade or solid color (see SPECIFYING COLOR below) or the
pattern used for filling polygons. Patterns are specified as pdpi/pattern, where pattern gives the
number of the built-in pattern (1-90) or the name of a Sun 1-, 8-, or 24-bit raster file. The dpi sets
the resolution of the image. For 1-bit rasters: use Pdpi/pattern for inverse video, or append
:Fcolor[B[color]] to specify fore- and background colors (use color = - for transparency). See
GMT Cookbook & Technical Reference Appendix E for information on individual patterns.
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 code (r/g/b, each in range 0−255; h-s-v, ranges 0−360, 0−1,
0−1; or c/m/y/k, each in range 0−1); or by a hexadecimal color code (#rrggbb, as used in HTML).
See the gmtcolors manpage for more information and a full list of color names.
GMT 4.5.14 1 Nov 2015 13

EXAMPLES
To get a copy of the GMT parameter defaults in your home directory, run
gmtdefaults −D > ˜/.gmtdefaults4
You may now change the settings by editing this file using a text editor of your choice, or use gmtset to
change specified parameters on the command line.
BUGS
If you have typographical errors in your .gmtdefaults4 file(s), a warning message will be issued, and the
GMT defaults for the affected parameters will be used.
SEE ALSO
GMT (1), gmtcolors(5), gmtget(1), gmtset(1)
GMT 4.5.14 1 Nov 2015 14

GMTGET(1) Generic Mapping Tools GMTGET(1)
NAME
gmtget − To list a single GMT parameter
SYNOPSIS
gmtget PARAMETER
DESCRIPTION
gmtget will list the value of a single GMT default parameter.
EXAMPLE
To list the value of the parameter PS_VERBOSE:
gmtget PS_VERBOSE
SEE ALSO
GMT (1), gmtdefaults(1), gmtset(1)
GMT 4.5.14 1 Nov 2015 1

GMTLOGO(1) Generic Mapping Tools GMTLOGO(1)
NAME
gmtlogo − Adding a GMT graphics logo overlay to an illustration
SYNOPSIS
gmtlogo dx dy scale [ −Gfill ] [ −W[pen] ] >> plot.ps
DESCRIPTION
This scrips appends the GMT logo to an "open" PostScript file. The logo is 2 times scale wide and scale
high and will be positioned with the lower left corner at the position (dx,dy) relative to the current plot ori-
gin.
OPTIONS
−G Select color or pattern for filling the underlying box [Default is no fill]. (See SPECIFYING FILL
below).
−W Set pen attributes for the outline of the box [Default is no outline]. (See SPECIFYING PENS
below).
SPECIFYING PENS
‘.’.
SPECIFYING FILL
SPECIFYING COLOR
SEE ALSO
GMT (1), gmtcolors(5), psimage(1)
GMT 4.5.14 1 Nov 2015 1

GMTMATH(1) Generic Mapping Tools GMTMATH(1)
NAME
gmtmath − Reverse Polish Notation calculator for data tables
SYNOPSIS
gmtmath [ −At_f(t).d ] [ −Ccols ] [ −Fcols ] [ −H[i][nrec] ] [ −I ] [ −Nn_col/t_col ] [ −Q ] [ −S[f|l] ] [
−Tt_min/t_max/t_inc[+]|tfile ] [ −V ] [ −b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ] [ −m[i|o][flag] ]
operand [ operand ] OPERATOR [ operand ] OPERATOR ... = [ outfile ]
DESCRIPTION
gmtmath will perform operations like add, subtract, multiply, and divide on one or more table data files or
constants using Reverse Polish Notation (RPN) syntax (e.g., Hewlett-Packard calculator-style). Arbitrarily
complicated expressions may therefore be evaluated; the final result is written to an output file [or standard
output]. When two data tables are on the stack, each element in file A is modified by the corresponding
element in file B. However, some operators only require one operand (see below). If no data tables are
used in the expression then options −T, −N can be set (and optionally −b to indicate the data domain). If
STDIN is given, <stdin> will be read and placed on the stack as if a file with that content had been given on
the command line. By default, all columns except the "time" column are operated on, but this can be
changed (see −C).
operand
If operand can be opened as a file it will be read as an ASCII (or binary, see −bi) table data file. If
not a file, it is interpreted as a numerical constant or a special symbol (see below). The special
argument STDIN means that stdin will be read and placed on the stack; STDIN can appear more
than once if necessary.
outfile The name of a table data file that will hold the final result. If not given then the output is sent to
stdout.
OPERATORS
Choose among the following 131 operators. "args" are the number of input and output arguments.
Operator args Returns
ABS 11 abs (A).

ACOS 11 acos (A).
ACOSH 11 acosh (A).
ACOT 11 acot (A).
ACSC 11 acsc (A).
ADD 21 A + B.
AND 21 NaN if A and B == NaN, B if A == NaN, else A.
ASEC 11 asec (A).
ASIN 11 asin (A).
ASINH 11 asinh (A).
ATAN 11 atan (A).
ATAN2 21 atan2 (A, B).
ATANH 11 atanh (A).
BEI 11 bei (A).
BER 11 ber (A).
CEIL 11 ceil (A) (smallest integer >= A).
CHICRIT 21 Critical value for chi-squared-distribution, with alpha = A and n = B.
CHIDIST 21 chi-squared-distribution P(chi2,n), with chi2 = A and n = B.
COL 11 Places column A on the stack.
CORRCOEFF 21 Correlation coefficient r(A, B).
COS 11 cos (A) (A in radians).
COSD 11 cos (A) (A in degrees).
COSH 11 cosh (A).
COT 11 cot (A) (A in radians).
GMT 4.5.14 1 Nov 2015 1

COTD 11 cot (A) (A in degrees).

CPOISS 21 Cumulative Poisson distribution F(x,lambda), with x = A and lambda =
B.
CSC 11 csc (A) (A in radians).
CSCD 11 csc (A) (A in degrees).
D2DT2 11 dˆ2(A)/dtˆ2 2nd derivative.
D2R 11 Converts Degrees to Radians.
DDT 11 d(A)/dt Central 1st derivative.
DILOG 11 dilog (A).
DIV 21 A / B.
DUP 12 Places duplicate of A on the stack.
EQ 21 1 if A == B, else 0.
ERF 11 Error function erf (A).
ERFC 11 Complementary Error function erfc (A).
ERFINV 11 Inverse error function of A.
EXCH 22 Exchanges A and B on the stack.
EXP 11 exp (A).
FACT 11 A! (A factorial).
FCRIT 31 Critical value for F-distribution, with alpha = A, n1 = B, and n2 = C.
FDIST 31 F-distribution Q(F,n1,n2), with F = A, n1 = B, and n2 = C.
FLIPUD 11 Reverse order of each column.
FLOOR 11 floor (A) (greatest integer <= A).
FMOD 21 A % B (remainder after truncated division).
GE 21 1 if A >= B, else 0.
GT 21 1 if A > B, else 0.
HYPOT 21 hypot (A, B) = sqrt (A*A + B*B).
I0 11 Modified Bessel function of A (1st kind, order 0).
IN 21 Modified Bessel function of A (1st kind, order B).
INRANGE 31 1 if B <= A <= C, else 0.
INT 11 Numerically integrate A.
INV 11 1 / A.
ISNAN 11 1 if A == NaN, else 0.
J0 11 Bessel function of A (1st kind, order 0).
JN 21 Bessel function of A (1st kind, order B).
K0 11 Modified Kelvin function of A (2nd kind, order 0).
K1 11 Modified Bessel function of A (2nd kind, order 1).
KEI 11 kei (A).
KER 11 ker (A).
KN 21 Modified Bessel function of A (2nd kind, order B).
KURT 11 Kurtosis of A.
LE 21 1 if A <= B, else 0.
LMSSCL 11 LMS scale estimate (LMS STD) of A.
LOG 11 log (A) (natural log).
LOG10 11 log10 (A) (base 10).
LOG1P 11 log (1+A) (accurate for small A).
LOG2 11 log2 (A) (base 2).
LOWER 11 The lowest (minimum) value of A.
LRAND 21 Laplace random noise with mean A and std. deviation B.
LSQFIT 10 Let current table be [A | b]; return least squares solution x = A \ b.
LT 21 1 if A < B, else 0.
MAD 11 Median Absolute Deviation (L1 STD) of A.
MAX 21 Maximum of A and B.
GMT 4.5.14 1 Nov 2015 2

MEAN 11 Mean value of A.

MED 11 Median value of A.
MIN 21 Minimum of A and B.
MOD 21 A mod B (remainder after floored division).
MODE 11 Mode value (Least Median of Squares) of A.
MUL 21 A * B.
NAN 21 NaN if A == B, else A.
NEG 11 -A.
NEQ 21 1 if A != B, else 0.
NOT 11 NaN if A == NaN, 1 if A == 0, else 0.
NRAND 21 Normal, random values with mean A and std. deviation B.
OR 21 NaN if A or B == NaN, else A.
PLM 31 Associated Legendre polynomial P(A) degree B order C.
PLMg 3 1 Normalized associated Legendre polynomial P(A) degree B order C
(geophysical convention).
POP 10 Delete top element from the stack.
POW 21 A ˆ B.
PQUANT 21 The B’th Quantile (0-100%) of A.
PSI 11 Psi (or Digamma) of A.
PV 31 Legendre function Pv(A) of degree v = real(B) + imag(C).
QV 31 Legendre function Qv(A) of degree v = real(B) + imag(C).
R2 21 R2 = Aˆ2 + Bˆ2.
R2D 11 Convert Radians to Degrees.
RAND 21 Uniform random values between A and B.
RINT 11 rint (A) (nearest integer).
ROOTS 21 Treats col A as f(t) = 0 and returns its roots.
ROTT 21 Rotate A by the (constant) shift B in the t-direction.
SEC 11 sec (A) (A in radians).
SECD 11 sec (A) (A in degrees).
SIGN 11 sign (+1 or -1) of A.
SIN 11 sin (A) (A in radians).
SINC 11 sinc (A) (sin (pi*A)/(pi*A)).
SIND 11 sin (A) (A in degrees).
SINH 11 sinh (A).
SKEW 11 Skewness of A.
SQR 11 Aˆ2.
SQRT 11 sqrt (A).
STD 11 Standard deviation of A.
STEP 11 Heaviside step function H(A).
STEPT 11 Heaviside step function H(t-A).
SUB 21 A - B.
SUM 11 Cumulative sum of A.
TAN 11 tan (A) (A in radians).
TAND 11 tan (A) (A in degrees).
TANH 11 tanh (A).
TCRIT 21 Critical value for Student’s t-distribution, with alpha = A and n = B.
TDIST 21 Student’s t-distribution A(t,n), with t = A, and n = B.
TN 21 Chebyshev polynomial Tn(-1<A<+1) of degree B.
UPPER 11 The highest (maximum) value of A.
XOR 21 B if A == NaN, else A.
Y0 11 Bessel function of A (2nd kind, order 0).
YN 21 Bessel function of A (2nd kind, order B).
ZCRIT 11 Critical value for the normal-distribution, with alpha = A.
GMT 4.5.14 1 Nov 2015 3

ZDIST 11 Cumulative normal-distribution C(x), with x = A.

SYMBOLS
The following symbols have special meaning:
PI 3.1415926...
E 2.7182818...
EULER 0.5772156...
TMIN Minimum t value
TMAX Maximum t value
TINC t increment
N The number of records
T Table with t-coordinates
OPTIONS
−A Requires −N and will partially initialize a table with values from the given file containing t and f(t)
only. The t is placed in column t_col while f(t) goes into column n_col - 1 (see −N).
−C Select the columns that will be operated on until next occurrence of −C. List columns separated
by commas; ranges like 1,3-5,7 are allowed. −C (no arguments) resets the default action of using
all columns except time column (see −N). −Ca selects all columns, including time column, while
−Cr reverses (toggles) the current choices.
−F Give a comma-separated list of desired columns or ranges that should be part of the output (0 is
first column) [Default outputs all columns].
skipped.
−I Reverses the output row sequence from ascending time to descending [ascending].
−N Select the number of columns and the column number that contains the "time" variable. Columns
are numbered starting at 0 [2/0].
−Q Quick mode for scalar calculation. Shorthand for −Ca −N 1/0 −T 0/0/1.
−S Only report the first or last row of the results [Default is all rows]. This is useful if you have com-
puted a statistic (say the MODE) and only want to report a single number instead of numerous
records with identical values. Append l to get the last row and f to get the first row only [Default].
−T Required when no input files are given. Sets the t-coordinates of the first and last point and the
equidistant sampling interval for the "time" column (see −N). Append + if you are specifying the
number of equidistant points instead. If there is no time column (only data columns), give −T
with no arguments; this also implies −Ca. Alternatively, give the name of a file whose first col-
umn contains the desired t-coordinates which may be irregular.
output file. [Default is same as input, but see −F]
GMT 4.5.14 1 Nov 2015 4


D_FORMAT setting.
NOTES ON OPERATORS
(1) The operators PLM and PLMg calculate the associated Legendre polynomial of degree L and order M
in x which must satisfy -1 <= x <= +1 and 0 <= M <= L. x, L, and M are the three arguments preceding the
operator. PLM is not normalized and includes the Condon-Shortley phase (-1)ˆM. PLMg is normalized in
the way that is most commonly used in geophysics. The C-S phase can be added by using -M as argument.
PLM will overflow at higher degrees, whereas PLMg is stable until ultra high degrees (at least 3000).
(2) Files that have the same names as some operators, e.g., ADD, SIGN, =, etc. should be identified by
prepending the current directory (i.e., ./LOG).
(3) The stack depth limit is hard-wired to 100.
(4) All functions expecting a positive radius (e.g., LOG, KEI, etc.) are passed the absolute value of their
argument.
(5) The DDT and D2DT2 functions only work on regularly spaced data.
(6) All derivatives are based on central finite differences, with natural boundary conditions.
(7) ROOTS must be the last operator on the stack, only followed by =.
EXAMPLES
To take the square root of the content of the second data column being piped through gmtmath by process1
and pipe it through a 3rd process, use
process1 | gmtmath STDIN SQRT = | process3
To take log10 of the average of 2 data files, use
gmtmath file1.d file2.d ADD 0.5 MUL LOG10 = file3.d
Given the file samples.d, which holds seafloor ages in m.y. and seafloor depth in m, use the relation
depth(in m) = 2500 + 350 * sqrt (age) to print the depth anomalies:
gmtmath samples.d T SQRT 350 MUL 2500 ADD SUB = | lpr
To take the average of columns 1 and 4-6 in the three data sets sizes.1, sizes.2, and sizes.3, use
gmtmath −C 1,4-6 sizes.1 sizes.2 ADD sizes.3 ADD 3 DIV = ave.d
To take the 1-column data set ages.d and calculate the modal value and assign it to a variable, try
set mode_age = ‘gmtmath −S −T ages.d MODE =‘
To evaluate the dilog(x) function for coordinates given in the file t.d:
gmtmath −T t.d T DILOG = dilog.d
GMT 4.5.14 1 Nov 2015 5

To use gmtmath as a RPN Hewlett-Packard calculator on scalars (i.e., no input files) and calculate arbitrary
expressions, use the −Q option. As an example, we will calculate the value of Kei (((1 + 1.75)/2.2) + cos
(60)) and store the result in the shell variable z:
set z = ‘gmtmath −Q 1 1.75 ADD 2.2 DIV 60 COSD ADD KEI =‘
To use gmtmath as a general least squares equation solver, imagine that the current table is the augmented
matrix [ A | b ] and you want the least squares solution x to the matrix equation A * x = b. The operator
LSQFIT does this; it is your job to populate the matrix correctly first. The −A option will facilitate this.
Suppose you have a 2-column file ty.d with t and b(t) and you would like to fit a the model y(t) = a + b*t +
c*H(t-t0), where H is the Heaviside step function for a given t0 = 1.55. Then, you need a 4-column aug-
mented table loaded with t in column 1 and your observed y(t) in column 3. The calculation becomes
gmtmath −N 4/1 −A ty.d -C0 1 ADD −C2 1.55 STEPT ADD −Ca LSQFIT = solution.d
Note we use the −C option to select which columns we are working on, then make active all the columns
we need (here all of them, with −Ca) before calling LSQFIT. The second and fourth columns (col num-
bers 1 and 3) are preloaded with t and y(t), respectively, the other columns are zero. If you already have a
precalculated table with the augmented matrix [ A | b ] in a file (say lsqsys.d), the least squares solution is
simply
gmtmath −T lsqsys.d LSQFIT = solution.d

REFERENCES
Abramowitz, M., and I. A. Stegun, 1964, Handbook of Mathematical Functions, Applied Mathematics
Series, vol. 55, Dover, New York.
Holmes, S. A., and W. E. Featherstone, 2002, A unified approach to the Clenshaw summation and the
recursive computation of very high degree and order normalised associated Legendre functions. Journal of
Geodesy, 76, 279-299.
Press, W. H., S. A. Teukolsky, W. T. Vetterling, and B. P. Flannery, 1992, Numerical Recipes, 2nd edition,
Cambridge Univ., New York.
Spanier, J., and K. B. Oldman, 1987, An Atlas of Functions, Hemisphere Publishing Corp.
SEE ALSO
GMT (1), grdmath(1)
GMT 4.5.14 1 Nov 2015 6

GMTSELECT(1) Generic Mapping Tools GMTSELECT(1)
NAME
gmtselect − Select data subsets based on multiple spatial criteria
SYNOPSIS
gmtselect [ infiles ] [ −Amin_area[/min_level/max_level][+r|l][ppercent] ] [ −C[f]dist/ptfile ] [ −Dresolu-
tion[+] ] [ −Fpolygonfile ] [ −H[i][nrec] ] [ −I[cflrsz] ] [ −Jparameters ] [ −L[p]dist/linefile ] [ −Nmaskval-
ues[o] ] [ −Rwest/east/south/north[r] ] [ −V ] [ −Zmin/max] ] [ −:[i|o] ] [ −b[i|o][s|S|d|D[ncol]|c[var1/...]] ]
[ −f[i|o]colinfo ] [ −m[i|o][flag] ]
DESCRIPTION
gmtselect is a filter that reads (longitude, latitude) positions from the first 2 columns of infiles [or standard
input] and uses a combination of 1-6 criteria to pass or reject the records. Records can be selected based on
whether or not they are 1) inside a rectangular region (−R [and −J]), 2) within dist km of any point in ptfile,
3) within dist km of any line in linefile, 4) inside one of the polygons in the polygonfile, 5) inside geograph-
ical features (based on coastlines), or 6) has z-values within a given range. The sense of the tests can be
reversed for each of these 6 criteria by using the −I option. See option −: on how to read (latitude,longi-
tude) files.
infiles ASCII (or binary, see −b) data file(s) to be operated on. If not given, standard input is read.
OPTIONS
No space between the option flag and the associated arguments.
−A Features with an area smaller than min_area in kmˆ2 or of hierarchical level that is lower than
min_level or higher than max_level will not be plotted [Default is 0/0/4 (all features)]. Level 2
(lakes) contains regular lakes and wide river bodies which we normally include as lakes; append
+r to just get river-lakes or +l to just get regular lakes (requires GSHHS 2.0.1 or higher). Finally,
append +ppercent to exclude polygons whose percentage area of the corresponding full-resolution
feature is less than percent (requires GSHHS 2.0 or higher). See GSHHS INFORMATION below
for more details. Ignored unless −N is set.
−C Pass all records whose location is within dist of any of the points in the ASCII file ptfile. If dist is
zero then the 3rd column of ptfile must have each point’s individual radius of influence. Distances
are Cartesian and in user units; specify −fg to indicate spherical distances in km. Use −Cf to indi-
cate you want flat Earth distances (quicker but approximate) rather than geodesic distances (slower
but exact). If ELLIPSOID is spherical then geodesics become great circles (faster to compute
than geodesic). Alternatively, if −R and −J are used then geographic coordinates are projected to
map coordinates (in cm, inch, m, or points, as determined by MEASURE_UNIT) before Carte-
sian distances are compared to dist.
−D Ignored unless −N is set. Selects the resolution of the coastline data set to use ((f)ull, (h)igh,
(i)ntermediate, (l)ow, or (c)rude). The resolution drops off by ˜80% between data sets. [Default is
l]. Append + to automatically select a lower resolution should the one requested not be available
[abort if not found]. Note that because the coastlines differ in details it is not guaranteed that a
point will remain inside [or outside] when a different resolution is selected.
−F Pass all records whose location is within one of the closed polygons in the multiple-segment file
polygonfile. For spherical polygons (lon, lat), make sure no consecutive points are separated by
180 degrees or more in longitude. Note that polygonfile must be in ASCII regardless of whether
−b is used.
skipped.
−I Reverses the sense of the test for each of the criteria specified:
c select records NOT inside any point’s circle of influence.
f select records NOT inside any of the polygons.
l select records NOT within the specified distance of any line.
GMT 4.5.14 1 Nov 2015 1

r select records NOT inside the specified rectangular region.

s select records NOT considered inside as specified by −N (and −A, −D).
z select records NOT within the range specified by −Z.
−J Selects the map projection. Scale is UNIT/degree, 1:xxxxx, or width in UNIT (upper case modi-
fier). UNIT is cm, inch, or m, depending on the MEASURE_UNIT setting in .gmtdefaults4, but
this can be overridden on the command line by appending c, i, or m to the scale/width value.
When central meridian is optional, default is center of longitude range on −R option. Default stan-
dard parallel is the equator. For map height, max dimension, or min dimension, append h, +, or -
to the width, respectively.
More details can be found in the psbasemap man pages.
CYLINDRICAL PROJECTIONS:
−Jclon0/lat0/scale (Cassini)
−Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
−Jj[lon0/]scale (Miller)
−Jm[lon0/[lat0/]]scale (Mercator)
−Jmlon0/lat0/scale (Mercator - Give meridian and standard parallel)
−Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and azimuth)
−Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
−Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and pole)
−Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
−Jtlon0/[lat0/]scale (TM - Transverse Mercator)
−Juzone/scale (UTM - Universal Transverse Mercator)
−Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)
CONIC PROJECTIONS:
−Jblon0/lat0/lat1/lat2/scale (Albers)
−Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
−Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
−Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)
AZIMUTHAL PROJECTIONS:
−Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)

−Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
−Jflon0/lat0[/horizon]/scale (Gnomonic)
−Jglon0/lat0[/horizon]/scale (Orthographic)
−Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale (General Perspective).
−Jslon0/lat0[/horizon]/scale (General Stereographic)
MISCELLANEOUS PROJECTIONS:
−Jh[lon0/]scale (Hammer)
−Ji[lon0/]scale (Sinusoidal)
−Jkf[lon0/]scale (Eckert IV)
−Jk[s][lon0/]scale (Eckert VI)
−Jn[lon0/]scale (Robinson)
−Jr[lon0/]scale (Winkel Tripel)
−Jv[lon0/]scale (Van der Grinten)
−Jw[lon0/]scale (Mollweide)
NON-GEOGRAPHICAL PROJECTIONS:
GMT 4.5.14 1 Nov 2015 2

−Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))

−Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log, and power scaling)
−L Pass all records whose location is within dist of any of the line segments in the ASCII multiple-
segment file linefile. If dist is zero then the 2nd column of each sub-header in the ptfile must have
each lines’s individual distance value. Distances are Cartesian and in user units; specify −fg to
indicate spherical distances in km. If ELLIPSOID is spherical then geodesics become great cir-
cles (faster to compute than geodesic). Alternatively, if −R and −J are used then geographic coor-
dinates are projected to map coordinates (in cm, inch, m, or points, as determined by MEA-
SURE_UNIT) before Cartesian distances are compared to dist. Use −Lp to ensure only points
whose orthogonal projections onto the nearest line-segment fall within the segments endpoints
[Default considers points "beyond" the line’s endpoints.
−N Pass all records whose location is inside specified geographical features. Specify if records should
be skipped (s) or kept (k) using 1 of 2 formats:
−Nwet/dry.
−Nocean/land/lake/island/pond.
Append o to let points exactly on feature boundaries be considered outside the feature [Default is
inside]. [Default is s/k/s/k/s (i.e., s/k), which passes all points on dry land].
output and plot formats are customizable; see gmtdefaults). If no map projection is supplied we
implicitly set −Jx 1. Note: only supply −J when your −R is indicating a rectangular region in the
projected coordinates (i.e., an oblique projection).
−Z Pass all records whose 3rd column (z) lies within the given range, or is NaN. Input file must have
at least three columns. To indicate no limit on min or max, specify a hyphen (-). If your 3rd col-
umn is absolute time then remember to supply −f 2T.
GMT 4.5.14 1 Nov 2015 3

Use −mi and −mo to give separate settings to input and output. The −m option make sure that
segment headers in the input files are copied to output, but it has no effect on the data selection.
Selection is always done point by point, not by segment.
D_FORMAT setting.
This note applies to ASCII output only in combination with binary or netCDF input or the −: option. See
also the note below.
NOTE ON PROCESSING ASCII INPUT RECORDS
Unless you are using the −: option, selected ASCII input records are copied verbatim to output. That
means that options like −foT and settings like D_FORMAT and OUTPUT_DEGREE_FORMAT will not
have any effect on the output. On the other hand, it allows selecting records with diverse content, including
character strings, quoted or not, comments, and other non-numerical content.
NOTE ON DISTANCES
If options −C or −L are selected then distances are Cartesian and in user units; use −fg to imply spherical
distances in km and geographical (lon, lat) coordinates. Alternatively, specify −R and −J to measure pro-
jected Cartesian distances in map units (cm, inch, m, or points, as determined by MEASURE_UNIT).
This program has evolved over the years. Originally, the −R and −J were mandatory in order to handle
geographic data, but now there is full support for spherical calculations. Thus, −J should only be used if
you want the tests to be applied on projected data and not the original coordinates. If −J is used the dis-
tances given via −C and −L are projected distances.
EXAMPLES
To extract the subset of data set that is within 300 km of any of the points in pts.d but more than 100 km
away from the lines in lines.d, run
gmtselect lonlatfile −fg −C 300/pts.d −L 100/lines.d −Il > subset
Here, you must specify −fg so the program knows you are processing geographical data (otherwise 300
would be interpreted as Cartesian distance in x-y units instead of km).
To keep all points in data.d within the specified region, except the points on land (as determined by the
high-resolution coastlines), use
gmtselect data.d −R 120/121/22/24 −Dh −Nk/s > subset
To return all points in quakes.d that are inside the spherical polygon lonlatpath.d, try
gmtselect quakes.d −F lonlatpath.d −fg > subset1
To return all points in stations.d that are within 5 cm of the point in origin.d for a certain projection, try
gmtselect stations.d −F origin.d −R 20/50/-10/20 −JM 20c > subset2

GSHHS INFORMATION
The coastline database is GSHHS which is compiled from two sources: World Vector Shorelines (WVS)
and CIA World Data Bank II (WDBII). In particular, all level-1 polygons (ocean-land boundary) are
GMT 4.5.14 1 Nov 2015 4

derived from the more accurate WVS while all higher level polygons (level 2-4, representing land/lake,
lake/island-in-lake, and island-in-lake/lake-in-island-in-lake boundaries) are taken from WDBII. Much
processing has taken place to convert WVS and WDBII data into usable form for GMT: assembling closed
polygons from line segments, checking for duplicates, and correcting for crossings between polygons. The
area of each polygon has been determined so that the user may choose not to draw features smaller than a
minimum area (see −A); one may also limit the highest hierarchical level of polygons to be included (4 is
the maximum). The 4 lower-resolution databases were derived from the full resolution database using the
Douglas-Peucker line-simplification algorithm. The classification of rivers and borders follow that of the
WDBII. See the GMT Cookbook and Technical Reference Appendix K for further details.
SEE ALSO
gmtdefaults(1), GMT (1), grdlandmask(1), pscoast(1)
GMT 4.5.14 1 Nov 2015 5

GMTSET(1) Generic Mapping Tools GMTSET(1)
NAME
gmtset − To change individual GMT default parameters
SYNOPSIS
gmtset [ −Gdefaultsfile ] PARAMETER1 [=] value1 PARAMETER2 [=] value2 PARAMETER3 [=]
value3 ...
DESCRIPTION
gmtset will adjust individual GMT defaults settings in the current directory’s .gmtdefaults4 file. If no such
file exists one will be created. The main purpose of gmtset is temporarily to change certain parameters
inside a shell script, e.g., set the dots-per-inch to 600, run the script, and reset to 300 dpi. Optionally, you
can specify one or more temporary changes directly on any GMT command line with the syntax
−−PARAMETER=value; such changes are only in effect for that command and do not permanently
change the default settings on disk.
PARAMETER value
Provide one or several pairs of parameter/value combinations that you want to modify. For a com-
plete listing of available parameters and their meaning, see the gmtdefaults man page.
OPTIONS
−G Name of specific .gmtdefaults4 file to modify [Default looks first in current directory, then in your
home directory, then in ˜/.gmt and finally in the system defaults].
EXAMPLES
To change the dpi to 600, set annotation font to Helvetica, and select grid-crosses of size 0.1 inch, and set
annotation offset to 0.2 cm:
gmtset DOTS_PR_INCH 600 ANNOT_FONT_PRIMARY Helvetica GRID_CROSS_SIZE_PRI-

MARY 0.1i ANNOT_OFFSET_PRIMARY 0.2c
SEE ALSO
GMT (1), gmtdefaults(1), gmtget(1)
GMT 4.5.14 1 Nov 2015 1

GRD2CPT(1) Generic Mapping Tools GRD2CPT(1)
NAME
grd2cpt − Make a color palette table from grid files
SYNOPSIS
grd2cpt grdfiles [ −Ccptmaster ] [ −D ] [ −Enlevels ] [ −I ] [ −Lminlimit/maxlimit ] [ −M ] [ −N ] [ −Q[i|o]
] [ −Rwest/east/south/north[r] ] [ −Szstart/zstop/zinc ] [ −T-|+|_|= ] [ −V ] [ −Z ]
DESCRIPTION
grd2cpt reads one or more grid files and writes a color palette (cpt) file to standard output. The cpt file is
based on an existing master cpt file of your choice, and the mapping from data value to colors is through
the data’s cumulative distribution function (CDF), so that the colors are histogram equalized. Thus if the
grid(s) and the resulting cpt file are used in grdimage with a linear projection, the colors will be uniformly
distributed in area on the plot. Let z be the data values in the grid. Define CDF(Z) = (# of z < Z) / (# of z
in grid). (NaNs are ignored). These z-values are then normalized to the master cpt file and colors are sam-
pled at the desired intervals.
The color palette includes three additional colors beyond the range of z-values. These are the background
color (B) assigned to values lower than the lowest z-value, the foreground color (F) assigned to values
higher than the highest z-value, and the NaN color (N) painted whereever values are undefined.
If the master cpt file includes B, F, and N entries, these will be copied into the new master file. If not, the
parameters COLOR_BACKGROUND, COLOR_FOREGROUND, and COLOR_NAN from the .gmt-
defaults4 file or the command line will be used. This default behavior can be overruled using the options
−D, −M or −N.
The color model (RGB, HSV or CMYK) of the palette created by makecpt will be the same as specified in
the header of the master cpt file. When there is no COLOR_MODEL entry in the master cpt file, the
COLOR_MODEL specified in the .gmtdefaults4 file or on the command line will be used.
grdfiles Names of one or more 2-D binary grid files used to derive the color palette table. All grids need to
have the same size and dimensions. (See GRID FILE FORMATS below).
OPTIONS
−C Selects the master color table to use in the interpolation. Choose among the built-in tables (type
grd2cpt to see the list) or give the name of an existing cpt file [Default gives a rainbow cpt file].
−D Select the colors for lowest and highest z-values in the output cpt file as the back- and foreground
colors that will be written to the cpt file [Default uses the colors specified in the master file, or
those defined by the parameters COLOR_BACKGROUND, COLOR_FOREGROUND, and
COLOR_NAN].
−E Create a linear color table by dividing the grid z-range into nlevels equidistant slices.
−I Reverses the sense of color progression in the master cpt file. Also exchanges the foreground and
background colors, including those specified by the parameters COLOR_BACKGROUND and
COLOR_FOREGROUND.
−L Limit range of cpt file to minlimit/maxlimit, and don’t count data outside range when estimating
CDF(Z). [Default uses min and max of data.]
−M Overrule background, foreground, and NaN colors specified in the master cpt file with the values
of the parameters COLOR_BACKGROUND, COLOR_FOREGROUND, and COLOR_NAN
specified in the .gmtdefaults4 file or on the command line. When combined with −D, only
COLOR_NAN is considered.
−N Do not write out the background, foreground, and NaN-color fields [Default will write them].
−Q Selects a logarithmic interpolation scheme [Default is linear]. −Qi expects input z-values to be
log10(z), assigns colors, and writes out z [Default]. −Qo takes log10(z) first, assigns colors, and
writes out z.
GMT 4.5.14 1 Nov 2015 1

GRD2CPT(1) Generic Mapping Tools GRD2CPT(1)
−S Set steps in cpt file. Calculate entries in cpt file from zstart to zstop in steps of (zinc). [Default
chooses arbitrary values by a crazy scheme.]
−T Force the color table to be symmetric about zero (from -R to +R). Append flag to set the range R: -
for R =|zmin|, + for R = |zmax|, _ for R = min(|zmin|, |zmax|), or = for R = max(|zmin|, |zmax|).
−V Verbose operation. This will write CDF(Z) estimates to stderr. [Default is silent.]
−Z Will create a continuous color palette. [Default is discontinuous, i.e., constant color intervals]
GRID FILE FORMATS
GMT is able to recognize many of the commonly used grid file formats, as well as the precision, scale and
offset of the values contained in the grid file. When GMT needs a little help with that, you can add the suf-
fix =id[/scale/offset[/nan]], where id is a two-letter identifier of the grid type and precision, and scale and
offset are optional scale factor and offset to be applied to all grid values, and nan is the value used to indi-
cate missing data. See grdreformat(1) and Section 4.17 of the GMT Technical Reference and Cookbook
for more information.
When reading a netCDF file that contains multiple grids, GMT will read, by default, the first 2-dimensional
grid that can find in that file. To coax GMT into reading another multi-dimensional variable in the grid file,
append ?varname to the file name, where varname is the name of the variable. Note that you may need to
escape the special meaning of ? in your shell program by putting a backslash in front of it, or by placing the
filename and suffix between quotes or double quotes. See grdreformat(1) and Section 4.18 of the GMT
Technical Reference and Cookbook for more information, particularly on how to read splices of 3-, 4-, or
5-dimensional grids.
EXAMPLES
Sometimes you don’t want to make a cpt file (yet) but would find it helpful to know that 90% of your data
lie between z1 and z2, something you cannot learn from grdinfo. So you can do this to see some points on
the CDF(Z) curve (use −V option to see more):
grd2cpt mydata.grd −V > /dev/null
To make a cpt file with entries from 0 to 200 in steps of 20, and ignore data below zero in computing
CDF(Z), and use the built-in master cpt file relief, run
grd2cpt mydata.grd −Crelief -L0/10000 -S0/200/20 > mydata.cpt

SEE ALSO
gmtdefaults(1), GMT (1), grdhisteq(1), grdinfo(1), makecpt(1)
GMT 4.5.14 1 Nov 2015 2

GRD2XYZ(1) Generic Mapping Tools GRD2XYZ(1)
NAME
grd2xyz − Converting grid file(s) to ASCII or binary data
SYNOPSIS
grd2xyz grdfiles [ −E[f][nodata] ] [ −H[i][nrec] ] [ −Nnodata ] [ −Rwest/east/south/north[r] ] [ −S[r] ] [
−V ] [ −W[weight] ] [ −Z[flags] ] [ −bo[s|S|d|D[ncol]|c[var1/...]] ] [ −fcolinfo ]
DESCRIPTION
grd2xyz reads one or more binary 2-D grid files and writes out xyz-triplets in ASCII [or binary] format to
standard output. Modify the precision of the ASCII output format by editing the D_FORMAT parameter
in your .gmtdefaults4 file or use −−D_FORMAT=value on the command line, or choose binary output
using single or double precision storage. As an option you may output z-values without the (x,y) in a num-
ber of formats, see −E or −Z below.
grdfiles Names of 2-D binary grid files to be converted. (See GRID FILE FORMATS below.)
OPTIONS
−E Output an ESRI ArcInfo ASCII interchange grid format file. Append f for float output [Default is
integer]. Append nodata which will be used wherever the grid value equals NaN [-9999].
−H Output 1 header record based on information in the first grid file header. Ignored if binary output
is selected. [Default is no header].
−N Output this z-value where the latter equals NaN [Default writes NaN].
output and plot formats are customizable; see gmtdefaults). Using the −R option will select a
subsection of the grid. If this subsection exceeds the boundaries of the grid, only the common
region will be output.
−S Suppress output for nodes whose z-value equals NaN [Default outputs all nodes]. Append r to
reverse the suppression, i.e., only output the nodes whose z-value equals NaN.
−W Write out x,y,z,w, where w is the supplied weight (or 1 if not supplied) [Default writes x,y,z only].
−Z Write a 1-column ASCII [or binary] table. Output will be organized according to the specified
ordering convention contained in flags. If data should be written by rows, make flags start with
T(op) if first row is y = ymax or B(ottom) if first row is y = ymin. Then, append L or R to indicate
that first element should start at left or right end of row. Likewise for column formats: start with L
or R to position first column, and then append T or B to position first element in a row. For grid-
line registered grids: If grid is periodic in x but the outcoming data should not contain the (redun-
dant) column at x = xmax, append x. For grid periodic in y, skip writing the redundant row at y =
ymax by appending y. If the byte-order needs to be swapped, append w. Select one of several
data types (all binary except a):
a ASCII representation
c signed 1-byte character
u unsigned 1-byte character
GMT 4.5.14 1 Nov 2015 1

h short 2-byte integer

i 4-byte integer
l long (4- or 8-byte) integer [architecture-dependent!]
f 4-byte floating point single precision
d 8-byte floating point double precision
Default format is scanline orientation of ASCII numbers: −ZTLa. Note that −Z only applies to
1-column output.
output file. [Default is 3]. This option only applies to xyz output; see −Z for z table output.
See also TIME COORDINATES below.
D_FORMAT setting.
GRID FILE FORMATS
TIME COORDINATES
Time coordinates in netCDF grids, be it the x, y, or z coordinate, will be recognized as such. The variable’s
unit attribute is parsed to determine the unit and epoch of the time coordinate in the grid. Values are then
converted to the internal time system specified by TIME_UNIT and TIME_EPOCH in the .gmtdefaults
file or on the command line. The default output is relative time in that time system, or absolute time when
using the option −f0T, −f1T, or −f2T for x, y, or z coordinate, respectively.
EXAMPLES
To edit individual values in the 5’ by 5’ hawaii_grv.grd file, dump the .grd to ASCII:
grd2xyz hawaii_grv.grd > hawaii_grv.xyz
To write a single precision binary file without the x,y positions from the file raw_data.grd file, using scan-
line orientation, run
GMT 4.5.14 1 Nov 2015 2

grd2xyz raw_data.grd −ZTLf > hawaii_grv.b

SEE ALSO
gmtdefaults(1), GMT (1), grdedit(1), xyz2grd(1)
GMT 4.5.14 1 Nov 2015 3

GRDBLEND(1) Generic Mapping Tools GRDBLEND(1)
NAME
grdblend − Blend several partially over-lapping grids into one large grid
SYNOPSIS
grdblend blendfile −Ggrdfile −Ixinc[unit][=|+][/yinc[unit][=|+]] −Rwest/east/south/north[r] [ −Nnodata ] [
−Q ] [ −Zscale ] [ −V ] [ −W ] [ −fcolinfo ]
DESCRIPTION
grdblend reads a listing of grid files and blend parameters and creates a binary grid file by blending the
other grids using cosine-taper weights. grdblend will report if some of the nodes are not filled in with data.
Such unconstrained nodes are set to a value specified by the user [Default is NaN]. Nodes with more than
one value will be set to the weighted average value. Note: Due to the row-by-row i/o nature of operations
in grdblend we only support the netCDF and native binary grid formats for both input and output.
blendfile
ASCII file with one record per grid file to include in the blend. Each record must contain three
items, separated by spaces or tabs: the gridfile name, the −R-setting for the interior region, and the
relative weight wr. In the combined weighting scheme, this grid will be given zero weight outside
its domain, weight = wr inside the interior region, and a 2-D cosine-tapered weight between those
end-members in the boundary strip. However, if a negative wr is given then the sense of tapering
is inverted (i.e., zero weight inside its domain). If the inner region should instead exactly match
the grid region then specify a - instead of the −R-setting. If the ASCII file is not given grdblend
will read standard input.
−G grdfile is the name of the binary output grid file. (See GRID FILE FORMATS below). Only
netCDF and native binary grid formats are supported.
OPTIONS
−N No data. Set nodes with no input grid to this value [Default is NaN].
GMT 4.5.14 1 Nov 2015 1

GRDBLEND(1) Generic Mapping Tools GRDBLEND(1)
−Q Create a header-less grid file suitable for use with grdraster. Requires that the output grid file is a
native format (i.e., not netCDF).
−W Do not blend, just output the weights used for each node. This option is valid when only one input
grid is provided [Default makes the blend].
−Z Scale output values by scale before writing to file. [1].
GRID FILE FORMATS
By default GMT writes out grid as single precision floats in a COARDS-complaint netCDF file format.
However, GMT is able to produce grid files in many other commonly used grid file formats and also facili-
tates so called "packing" of grids, writing out floating point data as 2- or 4-byte integers. To specify the pre-
cision, scale and offset, the user should add the suffix =id[/scale/offset[/nan]], where id is a two-letter iden-
tifier of the grid type and precision, and scale and offset are optional scale factor and offset to be applied to
all grid values, and nan is the value used to indicate missing data. See grdreformat(1) and Section 4.17 of
the GMT Technical Reference and Cookbook for more information.
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 suf-
fix between quotes or double quotes.
GEOGRAPHICAL AND TIME COORDINATES
When the output grid type is netCDF, the coordinates will be labeled "longitude", "latitude", or "time"
based on the attributes of the input data or grid (if any) or on the −f or −R options. For example, both −f0x
−f1t and −R 90w/90e/0t/3t will result in a longitude/time grid. When the x, y, or z coordinate is time, it will
be stored in the grid as relative time since epoch as specified by TIME_UNIT and TIME_EPOCH in the
.gmtdefaults file or on the command line. In addition, the unit attribute of the time variable will indicate
both this unit and epoch.
EXAMPLES
To create a grid file from the four grid files piece_?.nc, make the blendfile like this
piece_1.nc -R<subregion_1> 1
Then run
grdblend blend.job −G blend.nc −R<full_region> −I<dx/dy> -V

RESTRICTIONS
Currently, all grids processed must have the exact same node registration and grid spacing as the final out-
put grid.
SEE ALSO
GMT (1), grd2xyz(1), grdedit(1) grdraster(1)
GMT 4.5.14 1 Nov 2015 2

GRDCLIP(1) Generic Mapping Tools GRDCLIP(1)
NAME
grdclip − Clipping of range in grid files.
SYNOPSIS
grdclip input_file.grd −Goutput_file.grd [ −Sahigh/above ] [ −Sblow/below ] [ −V ]
DESCRIPTION
grdclip will set values < low to below and/or values > high to above. Useful when you want all of a conti-
nent or an ocean to fall into one color or grayshade in image processing, or clipping of the range of data
values is required. above/below can be any number or NaN (Not a Number). You must choose at least one
of −Sa or −Sb.
input_file.grd
The input 2-D binary grid file.
−G output_file.grd is the modified output grid file.
OPTIONS
−Sa Set all data[i] > high to above.
−Sb Set all data[i] < low to below.
GRID FILE FORMATS
all grid values, and nan is the value used to indicate missing data. When reading grids, the format is gener-
ally automatically recognized. If not, the same suffix can be added to input grid file names. See grdrefor-
mat(1) and Section 4.17 of the GMT Technical Reference and Cookbook for more information.
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 grdreformat(1) and Section 4.18 of
the GMT Technical Reference and Cookbook for more information, particularly on how to read splices of
3-, 4-, or 5-dimensional grids.
EXAMPLES
To set all values > 70 to NaN and all values < 0 to 0 in file data.grd:
grdclip data.grd −G new_data.grd −Sa 70/NaN −Sb 0/0 −V

SEE ALSO
GMT (1), grdlandmask(1), grdmask(1), grdmath(1), grd2xyz(1), xyz2grd(1)
GMT 4.5.14 1 Nov 2015 1

GRDCONTOUR(1) Generic Mapping Tools GRDCONTOUR(1)
NAME
grdcontour − Contouring of 2-D gridded data sets
SYNOPSIS
grdcontour grdfile −Ccont_int −Jparameters [ −A[-|annot_int][labelinfo] ] [ −B[p|s]parameters ] [
−Ddumpfile ] [ −Eazimuth/elevation ] [ −F[l|r] ] [ −G[d|f|n|l|L|x|X]params ] [ −K ] [ −Llow/high ] [ −O ] [
−P ] [ −Qcut ] [ −Rwest/east/south/north[r] ] [ −Ssmoothfactor ] [ −T[+|-][gap/length][:LH] ] [
−U[just/dx/dy/][c|label] ] [ −V ] [ −W[+][type]pen ] [ −X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [
−Z[factor[/shift]][p] ] [ −ccopies ] [ −bo[s|S|d|D[ncol]|c[var1/...]] ] [ −m[flag] ]
DESCRIPTION
grdcontour reads a 2-D grid file and produces a contour map by tracing each contour through the grid. As
an option, the x/y/z positions of the contour lines may be dumped to a single multisegment file or many
separate files. PostScript code is generated and sent to standard output. Various options that affect the plot-
ting are available.
grdfile 2-D gridded data set to be contoured. (See GRID FILE FORMATS below).
−C The contours to be drawn may be specified in one of three possible ways:
(1) If cont_int has the suffix ".cpt" and can be opened as a file, it is assumed to be a color palette
table. The color boundaries are then used as contour levels. If the cpt-file has annotation flags in
the last column then those contours will be annotated. By default all contours are labeled; use
−A− to disable all annotations.
(2) If cont_int is a file but not a cpt-file, it is expected to contain contour levels in column 1 and a
C(ontour) OR A(nnotate) in col 2. The levels marked C (or c) are contoured, the levels marked A
(or a) are contoured and annotated. Optionally, a third column may be present and contain the
fixed annotation angle for this contour level.
(3) If no file is found, then cont_int is interpreted as a constant contour interval. If −A is set and
−C is not, then the contour interval is set equal to the specified annotation interval.
If a file is given and −T is set, then only contours marked with upper case C or A will have tick-
marks. In all cases the contour values have the same units as the grid.
CONIC PROJECTIONS:
GMT 4.5.14 1 Nov 2015 1



OPTIONS
−A annot_int is annotation interval in data units; it is ignored if contour levels are given in a file.
[Default is no annotations]. Append - to disable all annotations implied by −C. The optional
labelinfo controls the specifics of the label formatting and consists of a concatenated string made
up of any of the following control arguments:
+aangle
For annotations at a fixed angle, +an for line-normal, or +ap for line-parallel [Default].
By appending the u or d we get annotations whose top face the next upper or lower anno-
tation, respectively.
+cdx[/dy]
Sets the clearance between label and optional text box. Append c|i|m|p to specify the
unit or % to indicate a percentage of the label font size [15%].
+d Turns on debug which will draw helper points and lines to illustrate the workings of the
quoted line setup.
+ffont Sets the desired font [Default ANNOT_FONT_PRIMARY].
+g[color]
Selects opaque text boxes [Default is transparent]; optionally specify the color [Default is
PAGE_COLOR]. (See SPECIFYING COLOR below).
+jjust Sets label justification [Default is MC]. Ignored when -SqN|n+|-1 is used.
GMT 4.5.14 1 Nov 2015 2

+kcolor
Sets color of text labels [Default is COLOR_BACKGROUND]. (See SPECIFYING
COLOR below).
+ndx[/dy]
Nudges the placement of labels by the specified amount (append c|i|m|p to specify the
units). Increments are considered in the coordinate system defined by the orientation of
the line; use +N to force increments in the plot x/y coordinates system [no nudging].
+o Selects rounded rectangular text box [Default is rectangular]. Not applicable for curved
text (+v) and only makes sense for opaque text boxes.
+p[pen]
Draws the outline of text boxsets [Default is no outline]; optionally specify pen for out-
line [Default is width = 0.25p, color = black, texture = solid]. (See SPECIFYING PENS
below).
+rmin_rad
Will not place labels where the line’s radius of curvature is less than min_rad [Default is
0].
+ssize Sets the desired font size in points [Default is 9].
+uunit Appends unit to all line labels. If unit starts with a leading hyphen (-) then there will be
no space between label value and the unit. If z is appended we use the unit specified in
the grid file. [Default is no unit].
+v Specifies curved labels following the path [Default is straight labels].
+w Specifies how many (x, y) points will be used to estimate label angles [Default is 10].
+=prefix
Prepends prefix to all line labels. If prefix starts with a leading hyphen (-) then there will
be no space between label value and the prefix. [Default is no prefix].
−B Sets map boundary annotation and tickmark intervals; see the psbasemap man page for all the
details.
−D Dump the (x,y,z) coordinates of each contour to separate files, one for each contour segment. The
files will be named dumpfile_cont_segment[_i].xyz (or .b is −b is selected), where cont is the con-
tour value and segment is a running segment number for each contour interval (for closed contours
we append _i.) If the prefix is given as ’-’ the file names are instead C#_i (interior) or C#_e (exter-
nal) plus extension, and # is just a running number. This allows us to make short file names that
will work with GNU utilities under DOS. However, when −m is used in conjunction with −D a
single multisegment file is created instead.
−E Sets the viewpoint’s azimuth and elevation (for perspective view) [180/90]. For frames used for
animation, you may want to append + to fix the center of your data domain (or specify a particular
world coordinate point with +wlon0/lat[/z]) which will project to the center of your page size (or
specify the coordinates of the projected view point with +vx0/y0).
−F Force dumped contours to be oriented so that higher z-values are to the left (−Fl [Default]) or right
(-Fr) as we move along the contour [Default is arbitrary orientation]. Requires −D.
−G Controls the placement of labels along the contours. Choose among five controlling algorithms:
−Gddist[c|i|m|p] or −GDdist[d|e|k|m|n]
For lower case d, give distances between labels on the plot in your preferred measure-
ment unit c (cm), i (inch), m (meter), or p (points), while for upper case D, specify dis-
tances in map units and append the unit; choose among e (m), k (km), m (mile), n (nauti-
cal mile), or d (spherical degree). [Default is 10c or 4i].
GMT 4.5.14 1 Nov 2015 3

−Gfffile.d
Reads the ascii file ffile.d and places labels at locations in the file that matches locations
along the contours. Inexact matches and points outside the region are skipped.
−Gl|Lline1[,line2,...]
Give the coordinates of the end points for one or more comma-separated straight line seg-
ments. Labels will be placed where these lines intersect the contours. The format of each
line specification is start_lon/start_lat/stop_lon/stop_lat. Both start_lon/start_lat and
stop_lon/stop_lat can be replaced by a 2-character key that uses the justification format
employed in pstext to indicate a point on the map, given as [LCR][BMT]. In addition,
you may use Z+ and Z- which correspond to the locations of the global max and min
locations in the grid, respectively. −GL will interpret the point pairs as defining great cir-
cles [Default is straight line].
−Gn|Nn_label
Specifies the number of equidistant labels for contours line [1]. Upper case −GN starts
labeling exactly at the start of the line [Default centers them along the line]. −GN-1
places one justified label at start, while −GN+1 places one justified label at the end of
contours. Optionally, append /min_dist[c|i|m|p] to enforce that a minimum distance sepa-
ration between successive labels is enforced.
−Gx|Xxfile.d
Reads the multi-segment file xfile.d and places labels at the intersections between the con-
tours and the lines inxfile.d. −GX will resample the lines first along great-circle arcs.
In addition, you may optionally append +rradius[c|i|m|p] to set a minimum label separation in the
x-y plane [no limitation].
−K More PostScript code will be appended later [Default terminates the plot system].
−L Limit range: Do not draw contours for data values below low or above high.
−O Selects Overlay plot mode [Default initializes a new plot system].
−P Selects Portrait plotting mode [Default is Landscape, see gmtdefaults to change this].
−Q Do not draw contours with less than cut number of points [Draw all contours].
output and plot formats are customizable; see gmtdefaults). [Default is region defined in the grid
file].
−S Used to resample the contour lines at roughly every (gridbox_size/smoothfactor) interval.
−T Will draw tickmarks pointing in the downward direction every gap along the innermost closed
contours. Append gap and tickmark length or use defaults [0.5c/0.1c or 0.2i/0.04i]. User may
choose to tick only local highs or local lows by specifying −T+ or −T−, respectively. Appending
:LH will plot the characters L and H at the center of closed innermost contours (local lows and
highs). L and H can be any single character (e.g., LH, -+, etc.) If a file is given by −C and −T is
set, then only contours marked with upper case C or A will have tickmarks [and annotation].
GMT 4.5.14 1 Nov 2015 4

−U Draw Unix System time stamp on plot. By adding just/dx/dy/, the user may specify the justifica-
tion of the stamp and where the stamp should fall on the page relative to lower left corner of the
plot. For example, BL/0/0 will align the lower left corner of the time stamp with the lower left
corner of the plot. Optionally, append a label, or c (which will plot the command string.). The
GMT parameters UNIX_TIME, UNIX_TIME_POS, and UNIX_TIME_FORMAT can affect
the appearance; see the gmtdefaults man page for details. The time string will be in the locale set
by the environment variable TZ (generally local time).
−W type, if present, can be a for annotated contours or c for regular contours [Default]. pen sets the
attributes for the particular line. Default values for annotated contours: width = 0.75p, color =
black, texture = solid. Regular contours have default width = 0.25p. (See SPECIFYING PENS
below). If the + flag is specified then the color of the contour lines are taken from the cpt file (see
−C).
−X −Y Shift plot origin relative to the current origin by (x-shift,y-shift) and optionally append the length
unit (c, i, m, p). You can prepend a to shift the origin back to the original position after plotting,
or prepend r [Default] to reset the current origin to the new location. If −O is used then the
default (x-shift,y-shift) is (0,0), otherwise it is (r1i, r1i) or (r2.5c, r2.5c). Alternatively, give c to
align the center coordinate (x or y) of the plot with the center of the page based on current page
size.
−Z Use to subtract shift from the data and multiply the results by factor before contouring starts [1/0].
(Numbers in −A, −C, −L refer to values after scaling and translation have occurred.) Append p to
indicate that this grid file contains z-values that are periodic in 360 degrees (e.g., phase data, angu-
lar distributions) and that special precautions must be taken when determining 0-contours.
output file.
−c Specifies the number of plot copies. [Default is 1].
−m When used in conjunction with −D a single multisegment file is created, and each contour section
is preceded by a header record whose first column is flag followed by the contour level.
SPECIFYING PENS
‘.’.
SPECIFYING COLOR
GMT 4.5.14 1 Nov 2015 5

D_FORMAT setting.
FILE FORMATS
EXAMPLES
To contour the file hawaii_grav.grd every 25 mGal on a Mercator map at 0.5 inch/degree, annotate every 50
mGal (using fontsize = 10), using 1 degree tickmarks, and draw 30 minute gridlines:
grdcontour hawaii_grav.grd −Jm 0.5i −C 25 −A 50+s10 −B 1g30m > hawaii_grav.ps
To contour the file image.grd using the levels in the file cont.d on a linear projection at 0.1 cm/x-unit and 50
cm/y-unit, using 20 (x) and 0.1 (y) tickmarks, smooth the contours a bit, use "RMS Misfit" as plot-title, use
a thick red pen for annotated contours, and a thin, dashed, blue pen for the rest, and send the output to the
default printer:
grdcontour image.grd −Jx 0.1c/50.0c −C cont.d −S 4 −B 20/0.1:."RMS Misfit": −Wa thick,red −Wc
thinnest,blue,- | lp
The labeling of local highs and lows may plot outside the innermost contour since only the mean value of
the contour coordinates is used to position the label.
SEE ALSO
GMT (1), gmtdefaults(1), gmtcolors(5), psbasemap(1), grdimage(1), grdview(1), pscontour(1)
GMT 4.5.14 1 Nov 2015 6

GRDCUT(1) Generic Mapping Tools GRDCUT(1)
NAME
grdcut − Extract a subregion out of a grid file
SYNOPSIS
grdcut input_file.grd −Goutput_file.grd −Rwest/east/south/north[r] [ −V ] [ −Z[n]min/max] ] [ −f[i|o]col-
info ]
DESCRIPTION
grdcut will produce a new output_file.grd file which is a subregion of input_file.grd. The subregion is
specified with −R as in other programs; the specified range must not exceed the range of input_file.grd. If
in doubt, run grdinfo to check range. Alternatively, define the subregion indirectly via a range check on the
node values. Complementary to grdcut there is grdpaste, which will join together two grid files along a
common edge.
input_file.grd
this is the input .grd format file.
−Goutput_file.grd
this is the output .grd format file.
output and plot formats are customizable; see gmtdefaults). This defines the subregion to be cut
out.
OPTIONS
−Z Determine the new rectangular region so that all nodes outside this region are also outside the
given z-range [-inf/+inf]. To indicate no limit on min or max, specify a hyphen (-). Normally, any
NaNs encountered are simply skipped. Use −Zn to consider a NaN to be outside the z-range.
GRID FILE FORMATS
GMT 4.5.14 1 Nov 2015 1

GRDCUT(1) Generic Mapping Tools GRDCUT(1)
EXAMPLES
Suppose you have used surface to grid ship gravity in the region between 148E - 162E and 8N - 32N, and
you do not trust the gridding near the edges, so you want to keep only the area between 150E - 160E and
10N - 30N, then:
grdcut grav_148_162_8_32.nc −G grav_150_160_10_30.nc −R 150/160/10/30 −V To return the subregion

of a grid such that any boundary strips where all values are entirely above 0, try
grdcut bathy.nc −G trimmed_bathy.nc −Z-/0 −V

SEE ALSO
grdpaste(1), grdinfo(1), GMT (1)
GMT 4.5.14 1 Nov 2015 2

GRDEDIT(1) Generic Mapping Tools GRDEDIT(1)
NAME
grdedit − Modifying the header or content of a 2-D grid file
SYNOPSIS
grdedit grdfile [ −A ] [ −Dxname/yname/zname/scale/offset/title/remark ] [ −E ] [ −Nxyzfile ] [
−Rwest/east/south/north[r] ] [ −S ] [ −T ] [ −V ] [ −:[i|o] ] [ −bi[s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ]
DESCRIPTION
grdedit reads the header information in a binary 2-D grid file and replaces the information with values pro-
vided on the command line [if any]. As an option, global, geographical grids (with 360 degrees longitude
range) can be rotated in the east-west direction, and individual nodal values can be replaced from a table of
x, y, z values. grdedit only operates on files containing a grdheader.
grdfile Name of the 2-D grid file to modify. (See GRID FILE FORMATS below).
OPTIONS
−A If necessary, adjust the file’s x_inc, y_inc to be compatible with its domain (or a new domain set
with −R). Older grid files (i.e., created prior to GMT 3.1) often had excessive slop in x_inc, y_inc
and an adjustment is necessary. Newer files are created correctly.
−D Give new values for xname, yname, zname, scale, offset, title, and remark. To leave some of the
values untouched, specify = as the new value. Alternatively, to allow "/" to be part of one of the
values, use any non-alphanumeric character (and not the equal sign) as separator by both starting
and ending with it. For example: −D:xname:yname:zname:scale:offset:title:remark:
−E Transpose the grid and exchange the x and y information. Incompatible with the other options.
skipped.
−N Read the ASCII (or binary; see −bi) file xyzfile and replace the corresponding nodal values in the
grid with these z values.
output and plot formats are customizable; see gmtdefaults). The new w/e/s/n values will replace
those in the grid, and the x_inc, y_inc values are adjusted, if necessary.
−S For global, geographical grids only. Grid values will be shifted longitudinally according to the
new borders given in −R.
−T Make necessary changes in the header to convert a gridline-registered grid to a pixel-registered
grid, or vice-versa. Basically, gridline-registered grids will have their domain extended by half the
x- and y-increments whereas pixel-registered grids will have their domain shrunk by the same
amount.
GMT 4.5.14 1 Nov 2015 1

GRID FILE FORMATS
EXAMPLES
Let us assume the file data.grd covers the area 300/310/10/30. We want to change the boundaries from geo-
detic longitudes to geographic and put a new title in the header. We accomplish this by
grdedit data.grd −R-60/-50/10/30 −D=/=/=/=/=/"Gravity Anomalies"/=
The grid world.grd has the limits 0/360/-72/72. To shift the data so that the limits would be
-180/180/-72/72, use
grdedit world.grd −R-180/180/-72/72 −S
The file junk.grd was created prior to GMT 3.1 with incompatible −R and −I arguments. To reset the x-
and y-increments we run
grdedit junk.grd −A
The file junk.grd was created prior to GMT 4.1.3 and does not contain the required information to indicate
that the grid is geographic. To add this information, run
GMT 4.5.14 1 Nov 2015 2

grdedit junk.grd −fg

SEE ALSO
GMT (1), grd2xyz(1), xyz2grd(1)
GMT 4.5.14 1 Nov 2015 3

GRDFFT(1) Generic Mapping Tools GRDFFT(1)
NAME
grdfft − Perform mathematical operations on grid files in the wavenumber (or frequency) domain
SYNOPSIS
grdfft in_grdfile −Gout_grdfile [ −Aazimuth ] [ −Czlevel ] [ −D[scale|g] ] [ −E[x|y][w] ] [ −F[x|y]params ]
[ −I[scale|g] ] [ −L ] [ −M ] [ −Nstuff ] [ −Sscale ] [ −Tte/rl/rm/rw/ri ] [ −V ]
DESCRIPTION
grdfft will take the 2-D forward Fast Fourier Transform and perform one or more mathematical operations
in the frequency domain before transforming back to the space domain. An option is provided to scale the
data before writing the new values to an output file. The horizontal dimensions of the grid are assumed to
be in meters. Geographical grids may be used by specifying the −M option that scales degrees to meters.
If you have grids with dimensions in km, you could change this to meters using grdedit or scale the output
with grdmath.
in_grdfile
2-D binary grid file to be operated on. (See GRID FILE FORMATS below).
−G Specify the name of the output grid file. (See GRID FILE FORMATS below).
OPTIONS
−A Take the directional derivative in the azimuth direction measured in degrees CW from north.
−C Upward (for zlevel > 0) or downward (for zlevel < 0) continue the field zlevel meters.
−D Differentiate the field, i.e., take d(field)/dz. This is equivalent to multiplying by kr in the fre-
quency domain (kr is radial wave number). Append a scale to multiply by (kr * scale) instead.
Alternatively, append g to indicate that your data are geoid heights in meters and output should be
gravity anomalies in mGal. [Default is no scale].
−E Estimate power spectrum in the radial direction. Place x or y immediately after −E to compute the
spectrum in the x or y direction instead. No grid file is created; f (i.e., frequency or wave number),
power[f], and 1 standard deviation in power[f] are written to stdout. Append w to write
wavelength instead of frequency.
−F Filter the data. Place x or y immediately after −F to filter x or y direction only; default is isotropic.
Choose between a cosine-tapered band-pass, a Gaussian band-pass filter, or a Butterworth band-
pass filter. Cosine-taper: Specify four wavelengths lc/lp/hp/hc in correct units (see −M) to design
a bandpass filter: wavelengths greater than lc or less than hc will be cut, wavelengths greater than
lp and less than hp will be passed, and wavelengths in between will be cosine-tapered. E.g., −F
1000000/250000/50000/10000 −M will bandpass, cutting wavelengths > 1000 km and < 10 km,
passing wavelengths between 250 km and 50 km. To make a highpass or lowpass filter, give
hyphens (-) for hp/hc or lc/lp. E.g., −Fx-/-/50/10 will lowpass x, passing wavelengths > 50 and
rejecting wavelengths < 10. −Fy 1000/250/-/- will highpass y, passing wavelengths < 250 and
rejecting wavelengths > 1000. Gaussian band-pass: Append lo/hi, the two wavelengths in correct
units (see −M) to design a bandpass filter. At the given wavelengths the Gaussian filter weights
will be 0.5. To make a highpass or lowpass filter, give a hyphen (-) for the hi or lo wavelength,
respectively. E.g., −F-/30 will lowpass the data using a Gaussian filter with half-weight at 30,
while −F 400/- will highpass the data. Butterworth band-pass: Append lo/hi/order, the two
wavelengths in correct units (see −M) and the filter order (an integer) to design a bandpass filter.
At the given wavelengths the Butterworth filter weights will be 0.5. To make a highpass or lowpass
filter, give a hyphen (-) for the hi or lo wavelength, respectively. E.g., −F-/30/2 will lowpass the
data using a 2nd-order Butterworth filter, with half-weight at 30, while −F 400/-/2 will highpass
the data.
−I Integrate the field, i.e., compute integral_over_z (field * dz). This is equivalent to divide by kr in
the frequency domain (kr is radial wave number). Append a scale to divide by (kr * scale) instead.
Alternatively, append g to indicate that your data set is gravity anomalies in mGal and output
should be geoid heights in meters. [Default is no scale].
GMT 4.5.14 1 Nov 2015 1

−L Leave trend alone. By default, a linear trend will be removed prior to the transform.
−M Map units. Choose this option if your grid file is a geographical grid and you want to convert
degrees into meters. If the data are close to either pole, you should consider projecting the grid file
onto a rectangular coordinate system using grdproject.
−N Choose or inquire about suitable grid dimensions for FFT. −Nf will force the FFT to use the
dimensions of the data. −Nq will inQuire about more suitable dimensions. −Nnx/ny will do FFT
on array size nx/ny (Must be >= grid file size). Default chooses dimensions >= data which opti-
mize speed, accuracy of FFT. If FFT dimensions > grid file dimensions, data are extended and
tapered to zero.
−S Multiply each element by scale in the space domain (after the frequency domain operations).
[Default is 1.0].
−T Compute the isostatic compensation from the topography load (input grid file) on an elastic plate
of thickness te. Also append densities for load, mantle, water, and infill in SI units. If te == 0 then
the Airy response is returned. −T implicitly sets −L.
GRID FILE FORMATS
EXAMPLES
To upward continue the sea-level magnetic anomalies in the file mag_0.grd to a level 800 m above sealevel:
grdfft mag_0.grd −C 800 −V −G mag_800.grd
To transform geoid heights in m (geoid.grd) on a geographical grid to free-air gravity anomalies in mGal:
grdfft geoid.grd −Dg −V −G grav.grd
To transform gravity anomalies in mGal (faa.grd) to deflections of the vertical (in micro-radians) in the 038
direction, we must first integrate gravity to get geoid, then take the directional derivative, and finally scale
radians to micro-radians:
grdfft faa.grd −Ig 38 −S 1e6 −V −G defl_38.grd
Second vertical derivatives of gravity anomalies are related to the curvature of the field. We can compute
these as mGal/mˆ2 by differentiating twice:
grdfft gravity.grd −D −D −V −G grav_2nd_derivative.grd
GMT 4.5.14 1 Nov 2015 2

The first order gravity anomaly (in mGal) due to the compensating surface caused by the topography load
topo.grd (in m) on a 20 km thick elastic plate, assumed to be 4 km beneath the observation level can be
computed as
grdfft topo.grd −T 20000/2800/3330/1030/2300 −S 0.022 −C 4000 −G comp_faa.grd
where 0.022 is the scale needed for the first term in Parker’s expansion for computing gravity from topogra-
phy (= 2 * PI * G * (rhom - rhol)).
SEE ALSO
GMT (1), grdedit(1), grdmath(1), grdproject(1)
GMT 4.5.14 1 Nov 2015 3

GRDFILTER(1) Generic Mapping Tools GRDFILTER(1)
NAME
grdfilter − Filter a 2-D grid file in the space (or time) domain
SYNOPSIS
grdfilter input_file −Ddistance_flag −F<filtertype><width>[mode] −Goutput_file [
−Ixinc[unit][=|+][/yinc[unit][=|+]] ] [ −Ni|p|r ] [ −Rwest/east/south/north[r] ] [ −T ] [ −V ] [ −f[i|o]colinfo ]
DESCRIPTION
grdfilter will filter a .grd file in the time domain using one of the selected convolution or non-convolution
isotropic filters and compute distances using Cartesian or Spherical geometries. The output .grd file can
optionally be generated as a subOPT(R)egion of the input and/or with a new −I ncrement. In this way, one
may have "extra space" in the input data so that the edges will not be used and the output can be within
one-half- width of the input edges. If the filter is low-pass, then the output may be less frequently sampled
than the input.
input_file
The grid file of points to be filtered. (See GRID FILE FORMATS below).
−D Distance flag tells how grid (x,y) relates to filter width as follows:
flag = 0: grid (x,y) same units as width, Cartesian distances.

flag = 1: grid (x,y) in degrees, width in kilometers, Cartesian distances.
flag = 2: grid (x,y) in degrees, width in km, dx scaled by cos(middle y), Cartesian distances.
The above options are fastest because they allow weight matrix to be computed only once. The
next three options are slower because they recompute weights for each latitude.
flag = 3: grid (x,y) in degrees, width in km, dx scaled by cosine(y), Cartesian distance calculation.
flag = 4: grid (x,y) in degrees, width in km, Spherical distance calculation.
flag = 5: grid (x,y) in Mercator -Jm1 img units, width in km, Spherical distance calculation.
−F Sets the filter type. Choose among convolution and non-convolution filters. Append the filter
code followed by the full diameter width. Available convolution filters are:
(b) Boxcar: All weights are equal.
(c) Cosine Arch: Weights follow a cosine arch curve.
(g) Gaussian: Weights are given by the Gaussian function, where width is 6 times the conventional
Gaussian sigma.
Non-convolution filters are:
(m) Median: Returns median value.
(p) Maximum likelihood probability (a mode estimator): Return modal value. If more than one
mode is found we return their average value. Append - or + to the filter width if you rather want to
return the smallest or largest of the modal values.
(l) Lower: Return the minimum of all values.
(L) Lower: Return minimum of all positive values only.
(u) Upper: Return maximum of all values.
(U) Upper: Return maximum or all negative values only.
In the case of L|U it is possible that no data passes the initial sign test; in that case the filter will
return 0.0.
−G output_file is the output grid file of the filter. (See GRID FILE FORMATS below).
OPTIONS
−I x_inc [and optionally y_inc] is the output Increment. Append m to indicate minutes, or c to indi-
cate seconds. If the new x_inc, y_inc are NOT integer multiples of the old ones (in the input
data), filtering will be considerably slower. [Default: Same as input.]
−N Determine how NaN-values in the input grid affects the filtered outout: Append i to ignore all
NaNs in the calculation of filtered value [Default], r is same as i except if the input node was NaN
then the output node will be set to NaN (only applies if both grids are coregistered), and p which
GMT 4.5.14 1 Nov 2015 1

will force the filtered value to be NaN if any grid-nodes with NaN-values are found inside the filter
circle.
−R west, east, south, and north defines the Region of the output points. [Default: Same as input.]
−T Toggle the node registration for the output grid so as to become the opposite of the input grid
[Default gives the same registration as the input grid].
GRID FILE FORMATS
EXAMPLES
Suppose that north_pacific_dbdb5.grd is a file of 5 minute bathymetry from 140E to 260E and 0N to 50N,
and you want to find the medians of values within a 300km radius (600km full width) of the output points,
which you choose to be from 150E to 250E and 10N to 40N, and you want the output values every 0.5
degree. Using spherical distance calculations, you need:
grdfilter north_pacific_dbdb5.grd −G filtered_pacific.grd −Fm 600 −D 4 −R 150/250/10/40 −I 0.5 −V

LIMITATIONS
When working with geographic (lat, lon) grids, all three convolution filters (boxcar, cosine arch, and gaus-
sian) will properly normalize the filter weights for the variation in gridbox size with latitude, and correctly
determine which nodes are needed for the convolution when the filter "circle" crosses a periodic (0-360)
boundary or contains a geographic pole. However, the spatial filters, such as median and mode filters, do
not use weights and thus should only be used on Cartesian grids (or at very low latitudes) only. If you want
to apply such spatial filters you should project your data to an equal-area projection and run grdfilter on the
resulting Cartesian grid.
To use the −D 5 option the input Mercator grid must be created by img2mercgrd using the −C option so the
GMT 4.5.14 1 Nov 2015 2

origin of the y-values is the Equator (i.e., x = y = 0 correspond to lon = lat = 0).
SEE ALSO
GMT (1), grdfft(1) img2mercgrd(1)
GMT 4.5.14 1 Nov 2015 3

GRDGRADIENT(1) Generic Mapping Tools GRDGRADIENT(1)
NAME
grdgradient − Compute directional derivative or gradient from 2-D grid file representing z(x,y)
SYNOPSIS
grdgradient in_grdfile −Gout_grdfile [ −Aazim[/azim2] ] [ −D[c][o][n] ] [ −E[s|p]azim/elev[/ambient/dif-
fuse/specular/shine] ] [ −Lflag ] [ −M ] [ −N[e][t][amp][/sigma[/offset]] ] [ −Sslopefile ] [ −V ]
DESCRIPTION
grdgradient may be used to compute the directional derivative in a given direction (−A), or the direction
(−S) [and the magnitude (−D)] of the vector gradient of the data.
Estimated values in the first/last row/column of output depend on boundary conditions (see −L).
in_grdfile
2-D grid file from which to compute directional derivative. (See GRID FILE FORMATS below).
−G Name of the output grid file for the directional derivative. (See GRID FILE FORMATS below).
OPTIONS
−A Azimuthal direction for a directional derivative; azim is the angle in the x,y plane measured in
degrees positive clockwise from north (the +y direction) toward east (the +x direction). The neg-
ative of the directional derivative, −[dz/dx*sin(azim) + dz/dy*cos(azim)], is found; negation yields
positive values when the slope of z(x,y) is downhill in the azim direction, the correct sense for
shading the illumination of an image (see grdimage and grdview) by a light source above the x,y
plane shining from the azim direction. Optionally, supply two azimuths, −Aazim/azim2, in which
case the gradients in each of these directions are calculated and the one larger in magnitude is
retained; this is useful for illuminating data with two directions of lineated structures, e.g.,
−A0/270 illuminates from the north (top) and west (left).
−D Find the up-slope direction of the gradient of the data. By default, the directions are measured
clockwise from north, as azim in −A above. Append c to use conventional Cartesian angles mea-
sured counterclockwise from the positive x (east) direction. Append o to report orientations
(0-180) rather than directions (0-360). Append n to add 90 degrees to all angles (e.g., to give ori-
entation of lineated features).
−E Compute Lambertian radiance appropriate to use with grdimage and grdview. The Lambertian
Reflection assumes an ideal surface that reflects all the light that strikes it and the surface appears
equally bright from all viewing directions. azim and elev are the azimuth and elevation of light
vector. Optionally, supply ambient diffuse specular shine which are parameters that control the
reflectance properties of the surface. Default values are: 0.55/ 0.6/0.4/10 To leave some of the val-
ues untouched, specify = as the new value. For example −E60/30/=/0.5 sets the azim elev and dif-
fuse to 60, 30 and 0.5 and leaves the other reflectance parameters untouched. Append s to use a
simpler Lambertian algorithm. Note that with this form you only have to provide the azimuth and
elevation parameters. Append p to use the Peucker piecewise linear approximation (simpler but
faster algorithm; in this case the azim and elev are hardwired to 315 and 45 degrees. This means
that even if you provide other values they will be ignored.)
−L Boundary condition flag may be x or y or xy indicating data is periodic in range of x or y or both,
or flag may be g indicating geographical conditions (x and y are lon and lat). [Default uses "natu-
ral" conditions (second partial derivative normal to edge is zero).]
−M By default the units of grdgradient are in units_of_z/ units_of_dx_and_dy. However, the user
may choose this option to convert dx,dy in degrees of longitude,latitude into meters, so that the
units of grdgradient are in z_units/meter.
−N Normalization. [Default: no normalization.] The actual gradients g are offset and scaled to pro-
duce normalized gradients gn with a maximum output magnitude of amp. If amp is not given,
default amp = 1. If offset is not given, it is set to the average of g. −N yields gn = amp * (g - off-
set)/max(abs(g
- offset)). −Ne normalizes using a cumulative Laplace distribution yielding gn = amp * (1.0 -
GMT 4.5.14 1 Nov 2015 1

GRDGRADIENT(1) Generic Mapping Tools GRDGRADIENT(1)
exp(sqrt(2) * (g - offset)/ sigma)) where sigma is estimated using the L1 norm of (g - offset) if it is
not given. −Nt normalizes using a cumulative Cauchy distribution yielding gn = (2 * amp / PI) *
atan( (g - offset)/ sigma) where sigma is estimated using the L2 norm of (g - offset) if it is not
given.
−S Name of output grid file with scalar magnitudes of gradient vectors. Requires −D but makes −G
optional.
HINTS
If you don’t know what OPT(N) options to use to make an intensity file for grdimage or grdview, a good
first try is −Ne 0.6.
If you want to make several illuminated maps of subregions of a large data set, and you need the illumina-
tion effects to be consistent across all the maps, use the −N option and supply the same value of sigma and
offset to grdgradient for each map. A good guess is offset = 0 and sigma found by grdinfo −L2 or −L1
applied to an unnormalized gradient grd.
If you simply need the x- or y-derivatives of the grid, use grdmath.

GRID FILE FORMATS
EXAMPLES
To make a file for illuminating the data in geoid.grd using exp- normalized gradients imitating light sources
in the north and west directions:
grdgradient geoid.grd −A 0/270 −G gradients.grd −Ne0.6 −V
To find the azimuth orientations of seafloor fabric in the file topo.grd:
grdgradient topo.grd −Dno −G azimuths.grd −V
REFERENCES
Horn, B.K.P., Hill-Shading and the Reflectance Map, Proceedings of the IEEE, Vol. 69, No. 1, January
1981, pp. 14-47. (http://people.csail.mit.edu/ bkph/papers/Hill-Shading.pdf)
SEE ALSO
GMT (1), gmtdefaults(1), grdhisteq(1), grdimage(1), grdview(1), grdvector(1)
GMT 4.5.14 1 Nov 2015 2

GRDHISTEQ(1) Generic Mapping Tools GRDHISTEQ(1)
NAME
grdhisteq − Histogram equalization for grid files
SYNOPSIS
grdhisteq in_grdfile [ −Gout_grdfile ] [ −Cn_cells ] [ −D ] [ −N[norm] ] [ −Q ] [ −V ]
DESCRIPTION
grdhisteq allows the user to find the data values which divide a given grid file into patches of equal area.
One common use of grdhisteq is in a kind of histogram equalization of an image. In this application, the
user might have a grid of flat topography with a mountain in the middle. Ordinary gray shading of this file
(using grdimage/grdview) with a linear mapping from topography to graytone will result in most of the
image being very dark gray, with the mountain being almost white. One could use grdhisteq to write to
stdout an ASCII list of those data values which divide the range of the data into n_cells segments, each of
which has an equal area in the image. Using awk or makecpt one can take this output and build a cpt file;
using the cptfile with grdimage will result in an image with all levels of gray occurring equally. Alterna-
tively, see grd2cpt.
The second common use of grdhisteq is in writing a grid with statistics based on some kind of cumulative
distribution function. In this application, the output has relative highs and lows in the same (x,y) locations
as the input file, but the values are changed to reflect their place in some cumulative distribution. One
example would be to find the lowest 10% of the data: Take a grid, run grdhisteq and make a grid using
n_cells = 10, and then contour the result to trace the 1 contour. This will enclose the lowest 10% of the
data, regardless of their original values. Another example is in equalizing the output of grdgradient. For
shading purposes it is desired that the data have a smooth distribution, such as a gaussian. If you run grd-
histeq on output from grdgradient and make a grid file output with the Gaussian option, you will have a
grid whose values are distributed according to a gaussian distribution with zero mean and unit variance.
The locations of these values will correspond to the locations of the input; that is, the most negative output
value will be in the (x,y) location of the most negative input value, and so on.
in_grdfile
2-D binary grid file to be equalized. (See GRID FILE FORMATS below).
OPTIONS
−C Sets how many cells (or divisions) of data range to make.
−D Dump level information to standard output.
−G Name of output 2-D grid file. Used with −N only. (See GRID FILE FORMATS below).
−N Gaussian output. Use with −G to make an output grid with standard normal scores. Append norm
to force the scores to fall in the <-1,+1> range [Default is standard normal scores].
−Q Use quadratic intensity scaling. [Default is linear].
GRID FILE FORMATS
GMT 4.5.14 1 Nov 2015 1

GRDHISTEQ(1) Generic Mapping Tools GRDHISTEQ(1)
EXAMPLES
To find the height intervals that divide the file heights.grd into 16 divisions of equal area:
grdhisteq heights.grd −C 16 −D > levels.d
To make the poorly distributed intensities in the file raw_intens.grd suitable for use with grdimage or grd-
view, run
grdhisteq raw_intens.grd −G smooth_intens.grd −N −V

RESTRICTIONS
If you use grdhisteq to make a gaussian output for gradient shading in grdimage or grdview, you should
be aware of the following: the output will be in the range [-x, x], where x is based on the number of data in
the input grid (nx * ny) and the cumulative gaussian distribution function F(x). That is, let N = nx * ny.
Then x will be adjusted so that F(x) = (N - 1 + 0.5)/N. Since about 68% of the values from a standard nor-
mal distribution fall within +/- 1, this will be true of the output grid. But if N is very large, it is possible for
x to be greater than 4. Therefore, with the grdimage program clipping gradients to the range [-1, 1], you
will get correct shading of 68% of your data, while 16% of them will be clipped to -1 and 16% of them
clipped to +1. If this makes too much of the image too light or too dark, you should take the output of grd-
histeq and rescale it using grdmath and multiplying by something less than 1.0, to shrink the range of the
values, thus bringing more than 68% of the image into the range [-1, 1]. Alternatively, supply a normaliza-
tion factor with −N.
SEE ALSO
gmtdefaults(1), GMT (1), grd2cpt(1), grdgradient(1), grdimage(1), grdmath(1), grdview(1), makecpt(1)
GMT 4.5.14 1 Nov 2015 2

GRDIMAGE(1) Generic Mapping Tools GRDIMAGE(1)
NAME
grdimage − Create grayshaded or colored image from a 2-D netCDF grid file
SYNOPSIS
grdimage grd_z | grd_r grd_g grd_b −Ccptfile [ −D[r] ] −Jparameters [ −B[p|s]parameters ] [ −Ei|dpi ] [
−G[f|b]color ] [ −Iintensfile ] [ −K ] [ −M ] [ −N ] [ −O ] [ −P ] [ −Q ] [ −Rwest/east/south/north[r] ] [
−S[-]b|c|l|n[/threshold] ] [ −T ] [ −U[just/dx/dy/][c|label] ] [ −V ] [ −X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-
shift[u]] ] [ −ccopies ] [ −f[i|o]colinfo ] [ −r ]
DESCRIPTION
grdimage reads one 2-D grid file and produces a gray-shaded (or colored) map by plotting rectangles cen-
tered on each grid node and assigning them a gray-shade (or color) based on the z-value. Alternatively,
grdimage reads three 2-D grid files with the red, green, and blue components directly (all must be in the
0-255 range). Optionally, illumination may be added by providing a file with intensities in the (-1,+1)
range. Values outside this range will be clipped. Such intensity files can be created from the grid using
grdgradient and, optionally, modified by grdmath or grdhisteq.
When using map projections, the grid is first resampled on a new rectangular grid with the same dimen-
sions. Higher resolution images can be obtained by using the −E option. To obtain the resampled value
(and hence shade or color) of each map pixel, its location is inversely projected back onto the input grid
after which a value is interpolated between the surrounding input grid values. By default bi-cubic interpola-
tion is used. Aliasing is avoided by also forward projecting the input grid nodes. If two or more nodes are
projected onto the same pixel, their average will dominate in the calculation of the pixel value. Interpolation
and aliasing is controlled with the −S option.
The −R option can be used to select a map region larger or smaller than that implied by the extent of the
grid.
A (color) PostScript file is output.
grd_z | grd_r grd_g grd_b
2-D gridded data set (or red, green, blue grids) to be imaged (See GRID FILE FORMATS below.)
−C name of the color palette table (for grd_z only).
CONIC PROJECTIONS:
GMT 4.5.14 1 Nov 2015 1



OPTIONS
details.
−D Specifies that the grid supplied is an image file to be read via GDAL. Obviously this option will
work only with GMT versions built with GDAL support. The image can be indexed or true color
(RGB) and can be an URL of a remotely located file. That is −D http://www.some-
where.com/image.jpg is a valid file syntax. Note, however, that to use it this way you must not be
blocked by a proxy. If you are, chances are good that it can work by setting the environmental
variable http_proxy with the value ’your_proxy:port’ Append r to use the region specified by −R
to apply to the image. For example, if you have used −Rd then the image will be assigned the lim-
its of a global domain. The interest of this mode is that you can project a raw image (an image
without referencing coordinates).
−E Sets the resolution of the projected grid that will be created if a map projection other than Linear
or Mercator was selected. By default, the projected grid will be of the same size (rows and col-
umns) as the input file. Specify i to use the PostScript image operator to interpolate the image at
the device resolution.
−G This option only applies when the resulting image otherwise would consist of only two colors:
black (0) and white (255). If so, this option will instead use the image as a transparent mask and
paint the mask (or its inverse, with −Gb) with the given color combination. (See SPECIFYING
COLOR below).
−I Gives the name of a grid file with intensities in the (-1,+1) range. [Default is no illumination].
GMT 4.5.14 1 Nov 2015 2

−M Force conversion to monochrome image using the (television) YIQ transformation. Cannot be
used with −Q.
−N Do not clip the image at the map boundary (only relevant for non-rectangular maps).
−Q Make grid nodes with z = NaN transparent, using the colormasking feature in PostScript Level 3
(the PS device must support PS Level 3).
output and plot formats are customizable; see gmtdefaults). You may ask for a larger w/e/s/n
region to have more room between the image and the axes. A smaller region than specified in the
grid file will result in a subset of the grid [Default is the region given by the grid file].
−S Select the 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, prepend - to switch off antialiasing. Add /threshold 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 interpo-
lation 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].
−T This option has become OBSOLETE. Use grdview −T instead. Use −Sn to plot near-neighbor
values only (use −E to increase the resolution). Use −Sn −Q to obtain something similar to the
old option −Ts. The option −To is no longer supported.
size.
GMT 4.5.14 1 Nov 2015 3

GRID FILE FORMATS
IMAGING GRIDS WITH NANS
Be aware that if your input grid contains patches of NaNs, these patches can become larger as a conse-
quence of the resampling that must take place with most map projections. Because grdimage uses the
PostScript colorimage operator, for most non-linear projections we must resample your grid onto an
equidistant rectangular lattice. If you find that the NaN areas are not treated adequately, consider (a) use a
linear projection, or (b) use grdview −Ts instead.
EXAMPLES
To gray-shade the file hawaii_grav.grd with shades given in shades.cpt on a Lambert map at 1.5 cm/degree
along the standard parallels 18 and 24, and using 1 degree tickmarks:
grdimage hawaii_grav.grd −Jl 18/24/1.5c −C shades.cpt −B 1 > hawaii_grav_image.ps
To create an illuminated color PostScript plot of the gridded data set image.grd, using the intensities pro-
vided by the file intens.grd, and color levels in the file colors.cpt, with linear scaling at 10 inch/x-unit, tick-
marks every 5 units:
grdimage image.grd −Jx 10i −C colors.cpt −I intens.grd −B 5 > image.ps
To create an false color PostScript plot from the three grid files red.grd, green.grd, and blue.grd, with linear
scaling at 10 inch/x-unit, tickmarks every 5 units:
grdimage red.grd green.grd blue.grd −Jx 10i −B 5 > rgbimage.ps
When GDAL support is built in: To create a sinusoidal projection of a remotely located Jessica Rabbit
grdimage -JI15c -Rd -Dr http://larryfire.files.wordpress.com/2009/07/untooned_jessicarabbit.jpg -P >

jess.ps
SEE ALSO
GMT (1), gmt2rgb(1), grdcontour(1), grdview(1), grdgradient(1), grdhisteq(1)
GMT 4.5.14 1 Nov 2015 4

GRDINFO(1) Generic Mapping Tools GRDINFO(1)
NAME
grdinfo − Get information about the contents of a 2-D grid file
SYNOPSIS
grdinfo grdfiles [ −C ] [ −F ] [ −I[dx[/dy]] ][ −L[0|1|2] ] [ −M ] [ −Tdz ] [ −V ] [ −f[i|o]colinfo ]
DESCRIPTION
grdinfo reads a 2-D binary grid file and reports various statistics for the (x,y,z) data in the grid file(s). The
output information contains the minimum/maximum values for x, y, and z, where the min/max of z occur,
the x- and y-increments, and the number of x and y nodes, and [optionally] the mean, standard deviation,
and/or the median, L1 scale of z, and number of nodes set to NaN.
grdfile The name of one or several 2-D grid files. (See GRID FILE FORMATS below.)
OPTIONS
−C Formats the report using tab-separated fields on a single line. The output is w e s n z0 z1 dx dy nx
ny [ x0 y0 x1 y1 ] [ med scale ] [ mean std rms] [n_nan]. The data in brackets are output only if
the corresponding options −M, −L1, −L2, and −M are used, respectively. If the −I option is used,
the output format is instead NF w e s n z0 z1, where NF is the total number of grids read and w e s
n are rounded off (see −I).
−F Report grid domain and x/y-increments in world mapping format [Default is generic]. Does not
apply to the −C option.
−I Report the min/max of the region to the nearest multiple of dx and dy, and output this in the form
−Rw/e/s/n (unless −C is set). To report the actual grid region, select −I-. If no argument is given
then we report the grid increment in the form −Ixinc/yinc.
−L0 Report range of z after actually scanning the data, not just reporting what the header says.
−L1 Report median and L1 scale of z (L1 scale = 1.4826 * Median Absolute Deviation (MAD)).
−L2 Report mean, standard deviation, and rms of z.
−M Find and report the location of min/max z-values, and count and report the number of nodes set to
NaN, if any.
−T Determine min and max z-value, round off to multiples of dz, and report as the text string
−Tzmin/zmax/dz for use by makecpt.
GRID FILE FORMATS
GMT 4.5.14 1 Nov 2015 1

GRDINFO(1) Generic Mapping Tools GRDINFO(1)
EXAMPLES
To obtain all the information about the data set in file hawaii_topo.grd:
grdinfo −L1 −L2 −M hawaii_topo.grd

SEE ALSO
GMT (1), grd2cpt(1), grd2xyz(1), grdedit(1)
GMT 4.5.14 1 Nov 2015 2

GRDLANDMASK(1) Generic Mapping Tools GRDLANDMASK(1)
NAME
grdlandmask − Create "wet-dry" mask grid file from shoreline data base.
SYNOPSIS
grdlandmask −Gmask_grd_file] −Ixinc[unit][=|+][/yinc[unit][=|+]] −Rwest/east/south/north[r] [
−Amin_area[/min_level/max_level][+r|l][ppercent] ] [ −Dresolution[+] ] [ −F ] [ −Nmaskvalues[o] ] [ −V ]
DESCRIPTION
grdlandmask reads the selected shoreline database and uses that information to decide which nodes in the
specified grid are over land or over water. The nodes defined by the selected region and lattice spacing will
be set according to one of two criteria: (1) land vs water, or (2) the more detailed (hierarchical) ocean vs
land vs lake vs island vs pond. The resulting mask may be used in subsequent operations involving grd-
math to mask out data from land [or water] areas.
−G Name of resulting output mask grid file. (See GRID FILE FORMATS below).
−R west, east, south, and north specify the Region of interest, 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 w/e/s/n. The two shorthands −Rg and −Rd stand for global
domain (0/360 and -180/+180 in longitude respectively, with -90/+90 in latitude). Alternatively,
specify the name of an existing grid file and the −R settings (and grid spacing, if applicable) are
copied from the grid.
OPTIONS
for more details.
−D Selects the resolution of the data set to use ((f)ull, (h)igh, (i)ntermediate, (l)ow, or (c)rude). The
resolution drops off by ˜80% between data sets. [Default is l]. Append + to automatically select a
lower resolution should the one requested not be available [abort if not found]. Note that because
the coastlines differ in details a node in a mask file using one resolution is not guaranteed to
remain inside [or outside] when a different resolution is selected.
−N Sets the values that will be assigned to nodes. Values can be any number, including the textstring
NaN. Append o to let nodes exactly on feature boundaries be considered outside [Default is
inside]. Specify this information using 1 of 2 formats:
−Nwet/dry.
−Nocean/land/lake/island/pond.
GMT 4.5.14 1 Nov 2015 1

GRDLANDMASK(1) Generic Mapping Tools GRDLANDMASK(1)
[Default is 0/1/0/1/0 (i.e., 0/1)].

GRID FILE FORMATS
EXAMPLES
To set all nodes on land to NaN, and nodes over water to 1, using the high resolution data set, do
grdlandmask −R-60/-40/-40/-30 −Dh −i 5m −N 1/NaN −G land_mask.grd −V
To make a 1x1 degree global grid with the hierarchical levels of the nodes based on the low resolution data:
grdlandmask −R 0/360/-90/90 −Dl −I 1 −N 0/1/2/3/4 −G levels.grd −V

GSHHS INFORMATION
SEE ALSO
GMT (1), grdmath(1), grdclip(1), psmask(1), psclip(1), pscoast(1)
GMT 4.5.14 1 Nov 2015 2

GRDMASK(1) Generic Mapping Tools GRDMASK(1)
NAME
grdmask − Create mask grid files from xy paths.
SYNOPSIS
grdmask pathfiles −Gmask_grd_file] −Ixinc[unit][=|+][/yinc[unit][=|+]] −Rwest/east/south/north[r] [
−A[m|p] ] [ −F ] [ −H[i][nrec] ] [ −Nout/edge/in ] [ −Ssearch_radius[m|c|k|K] ] [ −V ] [ −:[i|o] ] [
−bi[s|S|d|D[ncol]|c[var1/...]] ] [ −fcolinfo ] [ −m[flag] ]
DESCRIPTION
grdmask can operate in two different modes. 1. It reads one or more xy-files that each define a closed poly-
gon. The nodes defined by the specified region and lattice spacing will be set equal to one of three possible
values depending on whether the node is outside, on the polygon perimeter, or inside the polygon. The
resulting mask may be used in subsequent operations involving grdmath to mask out data from polygonal
areas. 2. The xy-files simply represent data point locations and the mask is set to the inside or outside value
depending on whether a node is within a maximum distance from the nearest data point. If the distance
specified is zero then only the nodes nearest each data point are considered "inside".
pathfiles
The name of 1 or more ASCII [or binary, see −b] files holding the polygon(s) or data points.
−G Name of resulting output mask grid file. (See GRID FILE FORMATS below).
OPTIONS
−A If the input data are geographic (as indicated by −fi) then the sides in the polygons will be approxi-
mated by great circle arcs. When using the −A sides will be regarded as straight lines. Alterna-
tively, append m to have sides first follow meridians, then parallels. Or append p to first follow
parallels, then meridians.
−F Force pixel node registration [Default is gridline registration]. (Node registrations are
defined in GMT Cookbook Appendix B on grid file formats.)
GMT 4.5.14 1 Nov 2015 1

N_HEADER_RECS. Use −Hi if only 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.
−N Sets the values that will be assigned to nodes that are outside the polygons, on the edge, or
inside. Values can be any number, including the textstring NaN [Default is 0/0/1].
−S Set nodes depending on their distance from the nearest data point. Nodes within radius
[0] from a data point are considered inside. Append m to indicate minutes or c to indi-
cate seconds. Append k to indicate km (implies −R and −I are in degrees, and we will
use a fast flat Earth approximation to calculate distance). For more accuracy, use upper-
case K if distances should be calculated along geodesics. However, if the current ELLIP-
SOID is spherical then great circle calculations are used. If −S is not set then we consider
the input data to define closed polygon(s) instead.
−bi Selects binary input. Append s for single precision [Default is d (double)]. Uppercase S
or D will force byte-swapping. Optionally, append ncol, the number of columns in your
binary input file if it exceeds the columns needed by the program. Or append c if the
input file is netCDF. Optionally, append var1/var2/... to specify the variables to be read.
[Default is 2 input columns].
−f Special formatting 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. Append T (absolute calendar
time), t (relative time in chosen TIME_UNIT since TIME_EPOCH), x (longitude), y (lati-
tude), or f (floating point) to each column or column range item. Shorthand −f[i|o]g
means −f[i|o]0x,1y (geographic coordinates).
−m Multiple segment file. Segments are separated by a record whose first character is flag.
[Default is ’>’].
GRID FILE FORMATS
By default GMT writes out grid as single precision floats in a COARDS-complaint netCDF file
format. However, GMT is able to produce grid files in many other commonly used grid file for-
mats and also facilitates so called "packing" of grids, writing out floating point data as 2- or 4-byte
integers. To specify the precision, scale and offset, the user should add the suffix =id[/scale/off-
set[/nan]], where id is a two-letter identifier of the grid type and precision, and scale and offset are
optional scale factor and offset to be applied to all grid values, and nan is the value used to indi-
cate missing data. See grdreformat(1) and Section 4.17 of the GMT Technical Reference and
Cookbook for more information.
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.
When the output grid type is netCDF, the coordinates will be labeled "longitude", "latitude", or
"time" based on the attributes of the input data or grid (if any) or on the −f or −R options. For
example, both −f0x −f1t and −R 90w/90e/0t/3t will result in a longitude/time grid. When the x,
y, or z coordinate is time, it will be stored in the grid as relative time since epoch as specified by
TIME_UNIT and TIME_EPOCH in the .gmtdefaults file or on the command line. In addition,
the unit attribute of the time variable will indicate both this unit and epoch.
EXAMPLES
To set all nodes inside and on the polygons coastline_*.xy to 0, and outside points to 1, do
GMT 4.5.14 1 Nov 2015 2

grdmask coastline_*.xy −R-60/-40/-40/-30 −I 5m −N 1/0/0 −G land_mask.grd −V
To set nodes within 50 km of data points to 1 and other nodes to NaN, do
grdmask data.xyz −R-60/-40/-40/-30 −I 5m −N NaN/1/1 −S 50k −G data_mask.grd −V

SEE ALSO
GMT(1), grdlandmask(1), grdmath(1), grdclip(1), psmask(1), psclip(1)
GMT 4.5.14 1 Nov 2015 3

GRDMATH(1) Generic Mapping Tools GRDMATH(1)
NAME
grdmath − Reverse Polish Notation calculator for grid files
SYNOPSIS
grdmath [ −F ] [ −Ixinc[unit][=|+][/yinc[unit][=|+]] ] [ −M ] [ −N ] [ −Rwest/east/south/north[r] ] [ −V ] [
−bi[s|S|d|D[ncol]|c[var1/...]] ] [ −fcolinfo ] operand [ operand ] OPERATOR [ operand ] OPERATOR ...
= outgrdfile
DESCRIPTION
grdmath will perform operations like add, subtract, multiply, and divide on one or more grid files or con-
stants using Reverse Polish Notation (RPN) syntax (e.g., Hewlett-Packard calculator-style). Arbitrarily
complicated expressions may therefore be evaluated; the final result is written to an output grid file. When
two grids are on the stack, each element in file A is modified by the corresponding element in file B. How-
ever, some operators only require one operand (see below). If no grid files are used in the expression then
options −R, −I must be set (and optionally −F). The expression = outgrdfile can occur as many times as the
depth of the stack allows.
operand
If operand can be opened as a file it will be read as a grid file. If not a file, it is interpreted as a
numerical constant or a special symbol (see below).
outgrdfile
The name of a 2-D grid file that will hold the final result. (See GRID FILE FORMATS below).
OPERATORS
Choose among the following 147 operators. "args" are the number of input and output arguments.
Operator args Returns
ABS 11 abs (A).

ACOS 11 acos (A).
ACOSH 11 acosh (A).
ACOT 11 acot (A).
ACSC 11 acsc (A).
ADD 21 A + B.
AND 21 NaN if A and B == NaN, B if A == NaN, else A.
ASEC 11 asec (A).
ASIN 11 asin (A).
ASINH 11 asinh (A).
ATAN 11 atan (A).
ATAN2 21 atan2 (A, B).
ATANH 11 atanh (A).
BEI 11 bei (A).
BER 11 ber (A).
CAZ 21 Cartesian azimuth from grid nodes to stack x,y.
CBAZ 21 Cartesian backazimuth from grid nodes to stack x,y.
CDIST 21 Cartesian distance between grid nodes and stack x,y.
CEIL 11 ceil (A) (smallest integer >= A).
CHICRIT 21 Critical value for chi-squared-distribution, with alpha = A and n = B.
CHIDIST 21 chi-squared-distribution P(chi2,n), with chi2 = A and n = B.
CORRCOEFF 21 Correlation coefficient r(A, B).
COS 11 cos (A) (A in radians).
COSD 11 cos (A) (A in degrees).
COSH 11 cosh (A).
COT 11 cot (A) (A in radians).
COTD 11 cot (A) (A in degrees).
CPOISS 21 Cumulative Poisson distribution F(x,lambda), with x = A and lambda =
GMT 4.5.14 1 Nov 2015 1

B.
CSC 11 csc (A) (A in radians).
CSCD 11 csc (A) (A in degrees).
CURV 11 Curvature of A (Laplacian).
D2DX2 11 dˆ2(A)/dxˆ2 2nd derivative.
D2DXY 11 dˆ2(A)/dxdy 2nd derivative.
D2DY2 11 dˆ2(A)/dyˆ2 2nd derivative.
D2R 11 Converts Degrees to Radians.
DDX 11 d(A)/dx Central 1st derivative.
DDY 11 d(A)/dy Central 1st derivative.
DEG2KM 11 Converts Spherical Degrees to Kilometers.
DILOG 11 dilog (A).
DIV 21 A / B.
DUP 12 Places duplicate of A on the stack.
EQ 21 1 if A == B, else 0.
ERF 11 Error function erf (A).
ERFC 11 Complementary Error function erfc (A).
ERFINV 11 Inverse error function of A.
EXCH 22 Exchanges A and B on the stack.
EXP 11 exp (A).
EXTREMA 11 Local Extrema: +2/-2 is max/min, +1/-1 is saddle with max/min in x, 0
elsewhere.
FACT 11 A! (A factorial).
FCRIT 31 Critical value for F-distribution, with alpha = A, n1 = B, and n2 = C.
FDIST 31 F-distribution Q(F,n1,n2), with F = A, n1 = B, and n2 = C.
FLIPLR 11 Reverse order of values in each row.
FLIPUD 11 Reverse order of values in each column.
FLOOR 11 floor (A) (greatest integer <= A).
FMOD 21 A % B (remainder after truncated division).
GE 21 1 if A >= B, else 0.
GT 21 1 if A > B, else 0.
HYPOT 21 hypot (A, B) = sqrt (A*A + B*B).
IN 21 Modified Bessel function of A (1st kind, order B).
INRANGE 31 1 if B <= A <= C, else 0.
INSIDE 11 1 when inside or on polygon(s) in A, else 0.
INV 11 1 / A.
ISNAN 11 1 if A == NaN, else 0.
JN 21 Bessel function of A (1st kind, order B).
K0 11 Modified Kelvin function of A (2nd kind, order 0).
K1 11 Modified Bessel function of A (2nd kind, order 1).
KEI 11 kei (A).
KER 11 ker (A).
KM2DEG 11 Converts Kilometers to Spherical Degrees.
KN 21 Modified Bessel function of A (2nd kind, order B).
KURT 11 Kurtosis of A.
LDIST 11 Compute distance from lines in multi-segment ASCII file A.
LE 21 1 if A <= B, else 0.
LMSSCL 11 LMS scale estimate (LMS STD) of A.
LOG 11 log (A) (natural log).
LOG10 11 log10 (A) (base 10).
GMT 4.5.14 1 Nov 2015 2

LOG1P 11 log (1+A) (accurate for small A).

LOG2 11 log2 (A) (base 2).
LOWER 11 The lowest (minimum) value of A.
LRAND 21 Laplace random noise with mean A and std. deviation B.
LT 21 1 if A < B, else 0.
MAD 11 Median Absolute Deviation (L1 STD) of A.
MAX 21 Maximum of A and B.
MEAN 11 Mean value of A.
MED 11 Median value of A.
MIN 21 Minimum of A and B.
MOD 21 A mod B (remainder after floored division).
MODE 11 Mode value (Least Median of Squares) of A.
MUL 21 A * B.
NAN 21 NaN if A == B, else A.
NEG 11 -A.
NEQ 21 1 if A != B, else 0.
NOT 11 NaN if A == NaN, 1 if A == 0, else 0.
NRAND 21 Normal, random values with mean A and std. deviation B.
OR 21 NaN if A or B == NaN, else A.
PDIST 11 Compute distance from points in ASCII file A.
PLM 31 Associated Legendre polynomial P(A) degree B order C.
PLMg 3 1 Normalized associated Legendre polynomial P(A) degree B order C
(geophysical convention).
POP 10 Delete top element from the stack.
POW 21 A ˆ B.
PQUANT 21 The B’th Quantile (0-100%) of A.
PSI 11 Psi (or Digamma) of A.
PV 31 Legendre function Pv(A) of degree v = real(B) + imag(C).
QV 31 Legendre function Qv(A) of degree v = real(B) + imag(C).
R2 21 R2 = Aˆ2 + Bˆ2.
R2D 11 Convert Radians to Degrees.
RAND 21 Uniform random values between A and B.
RINT 11 rint (A) (nearest integer).
ROTX 21 Rotate A by the (constant) shift B in x-direction.
ROTY 21 Rotate A by the (constant) shift B in y-direction.
SAZ 21 Spherical azimuth from grid nodes to stack x,y.
SBAZ 21 Spherical backazimuth from grid nodes to stack x,y.
SDIST 21 Spherical (Great circle|geodesic) distance (in km) between grid nodes
and stack lon,lat (A, B).
SEC 11 sec (A) (A in radians).
SECD 11 sec (A) (A in degrees).
SIGN 11 sign (+1 or -1) of A.
SIN 11 sin (A) (A in radians).
SINC 11 sinc (A) (sin (pi*A)/(pi*A)).
SIND 11 sin (A) (A in degrees).
SINH 11 sinh (A).
SKEW 11 Skewness of A.
SQR 11 Aˆ2.
SQRT 11 sqrt (A).
STD 11 Standard deviation of A.
STEP 11 Heaviside step function: H(A).
STEPX 11 Heaviside step function in x: H(x-A).
STEPY 11 Heaviside step function in y: H(y-A).
SUB 21 A - B.
GMT 4.5.14 1 Nov 2015 3

TAN 11 tan (A) (A in radians).

TAND 11 tan (A) (A in degrees).
TANH 11 tanh (A).
TCRIT 21 Critical value for Student’s t-distribution, with alpha = A and n = B.
TDIST 21 Student’s t-distribution A(t,n), with t = A, and n = B.
TN 21 Chebyshev polynomial Tn(-1<t<+1,n), with t = A, and n = B.
UPPER 11 The highest (maximum) value of A.
XOR 21 0 if A == NaN and B == NaN, NaN if B == NaN, else A.
YLM 22 Re and Im orthonormalized spherical harmonics degree A order B.
YLMg 22 Cos and Sin normalized spherical harmonics degree A order B (geo-
physical convention).
YN 21 Bessel function of A (2nd kind, order B).
ZCRIT 11 Critical value for the normal-distribution, with alpha = A.
ZDIST 11 Cumulative normal-distribution C(x), with x = A.
SYMBOLS
The following symbols have special meaning:
PI 3.1415926...
E 2.7182818...
EULER 0.5772156...
XMIN Minimum x value
XMAX Maximum x value
XINC x increment
NX The number of x nodes
YMIN Minimum y value
YMAX Maximum y value
YINC y increment
NY The number of y nodes
X Grid with x-coordinates
Y Grid with y-coordinates
Xn Grid with normalized [-1 to +1] x-coordinates
Yn Grid with normalized [-1 to +1] y-coordinates
OPTIONS
GMT Cookbook Appendix B on grid file formats.) Only used with −R −I.
−M By default any derivatives calculated are in z_units/ x(or y)_units. However, the user may choose
this option to convert dx,dy in degrees of longitude,latitude into meters using a flat Earth approxi-
mation, so that gradients are in z_units/meter.
GMT 4.5.14 1 Nov 2015 4

−N Turn off strict domain match checking when multiple grids are manipulated [Default will insist
that each grid domain is within 1e-4 * grid_spacing of the domain of the first grid listed].
append var1/var2/... to specify the variables to be read. The binary input option only applies to
the data files needed by operators LDIST, PDIST, and INSIDE.
NOTES ON OPERATORS
(1) The operator SDIST calculates spherical distances in km between the (lon, lat) point on the stack and
all node positions in the grid. The grid domain and the (lon, lat) point are expected to be in degrees. Simi-
larly, the SAZ and SBAZ operators calculate spherical azimuth and back-azimuths in degrees, respectively.
A few operators (PDIST, LDIST, and INSIDE) expects their argument to be a single file with points, lines,
or polygons, respectively. These distances will be in km (for geographical data, i.e, −fg and Cartesian other-
wise. Be aware that LDIST in particular can be slow for large grids and numerous line segments. Note: If
the current ELLIPSOID is not spherical then geodesics are used in the calculations.
(2) The operator PLM calculates the associated Legendre polynomial of degree L and order M (0 <= M <=
L), and its argument is the sine of the latitude. PLM is not normalized and includes the Condon-Shortley
phase (-1)ˆM. PLMg is normalized in the way that is most commonly used in geophysics. The C-S phase
can be added by using -M as argument. PLM will overflow at higher degrees, whereas PLMg is stable
until ultra high degrees (at least 3000).
(3) The operators YLM and YLMg calculate normalized spherical harmonics for degree L and order M (0
<= M <= L) for all positions in the grid, which is assumed to be in degrees. YLM and YLMg return two
grids, the real (cosine) and imaginary (sine) component of the complex spherical harmonic. Use the POP
operator (and EXCH) to get rid of one of them, or save both by giving two consecutive = file.grd calls.
The orthonormalized complex harmonics YLM are most commonly used in physics and seismology. The
square of YLM integrates to 1 over a sphere. In geophysics, YLMg is normalized to produce unit power
when averaging the cosine and sine terms (separately!) over a sphere (i.e., their squares each integrate to 4
pi). The Condon-Shortley phase (-1)ˆM is not included in YLM or YLMg, but it can be added by using -M
as argument.
(4) All the derivatives are based on central finite differences, with natural boundary conditions.
GMT 4.5.14 1 Nov 2015 5

(5) Files that have the same names as some operators, e.g., ADD, SIGN, =, etc. should be identified by
prepending the current directory (i.e., ./LOG).
(6) Piping of files is not allowed.
(7) The stack depth limit is hard-wired to 100.
(8) All functions expecting a positive radius (e.g., LOG, KEI, etc.) are passed the absolute value of their
argument.
GRID VALUES PRECISION
Regardless of the precision of the input data, GMT programs that create grid files will internally hold the
grids in 4-byte floating point arrays. This is done to conserve memory and furthermore most if not all real
data can be stored using 4-byte floating point values. Data with higher precision (i.e., double precision val-
ues) will lose that precision once GMT operates on the grid or writes out new grids. To limit loss of preci-
sion when processing data you should always consider normalizing the data prior to processing.
GRID FILE FORMATS
EXAMPLES
To take log10 of the average of 2 files, use
grdmath file1.grd file2.grd ADD 0.5 MUL LOG10 = file3.grd
Given the file ages.grd, which holds seafloor ages in m.y., use the relation depth(in m) = 2500 + 350 * sqrt
(age) to estimate normal seafloor depths:
grdmath ages.grd SQRT 350 MUL 2500 ADD = depths.grd
To find the angle a (in degrees) of the largest principal stress from the stress tensor given by the three files
s_xx.grd s_yy.grd, and s_xy.grd from the relation tan (2*a) = 2 * s_xy / (s_xx - s_yy), use
GMT 4.5.14 1 Nov 2015 6

grdmath 2 s_xy.grd MUL s_xx.grd s_yy.grd SUB DIV ATAN 2 DIV = direction.grd
To calculate the fully normalized spherical harmonic of degree 8 and order 4 on a 1 by 1 degree world map,
using the real amplitude 0.4 and the imaginary amplitude 1.1:
grdmath −R 0/360/-90/90 −I 1 8 4 YML 1.1 MUL EXCH 0.4 MUL ADD = harm.grd
To extract the locations of local maxima that exceed 100 mGal in the file faa.grd:
grdmath faa.grd DUP EXTREMA 2 EQ MUL DUP 100 GT MUL 0 NAN = z.grd
grd2xyz z.grd −S > max.xyz
REFERENCES
Abramowitz, M., and I. A. Stegun, 1964, Handbook of Mathematical Functions, Applied Mathematics
Series, vol. 55, Dover, New York.
Holmes, S. A., and W. E. Featherstone, 2002, A unified approach to the Clenshaw summation and the
recursive computation of very high degree and order normalised associated Legendre functions. Journal of
Geodesy, 76, 279-299.
Press, W. H., S. A. Teukolsky, W. T. Vetterling, and B. P. Flannery, 1992, Numerical Recipes, 2nd edition,
Cambridge Univ., New York.
Spanier, J., and K. B. Oldman, 1987, An Atlas of Functions, Hemisphere Publishing Corp.
SEE ALSO
GMT (1), gmtmath(1), grd2xyz(1), grdedit(1), grdinfo(1), xyz2grd(1)
GMT 4.5.14 1 Nov 2015 7

GRDPASTE(1) Generic Mapping Tools GRDPASTE(1)
NAME
grdpaste − Paste together two .grd files along a common edge.
SYNOPSIS
grdpaste file_a.grd file_b.grd −Goutfile.grd [ −V ] [ −f[i|o]colinfo ]
DESCRIPTION
grdpaste will combine file_a.grd and file_b.grd into outfile.grd by pasting them together along their com-
mon edge. Files file_a.grd and file_b.grd must have the same dx, dy and have one edge in common. If in
doubt, check with grdinfo and use grdcut and/or grdsample if necessary to prepare the edge joint. For
geographical grids, use −f to handle periodic longitudes.
file_a.grd
One of two files to be pasted together.
file_b.grd
The other of two files to be pasted together.
−Goutfile.grd
The name for the combined output.
OPTIONS
GRID FILE FORMATS
EXAMPLES
Suppose file_a.grd is 150E - 180E and 0 - 30N, and file_b.grd is 150E - 180E, -30S - 0, then you can make
outfile.grd which will be 150 - 180 and -30S - 30N by:
grdpaste file_a.grd file_b.grd −G outfile.grd −V −fg

SEE ALSO
GMT (1), grdcut(1), grdinfo(1), grdsample(1)
GMT 4.5.14 1 Nov 2015 1

GRDPROJECT(1) Generic Mapping Tools GRDPROJECT(1)
NAME
grdproject − Forward and Inverse map transformation of 2-D grid files
SYNOPSIS
grdproject in_grdfile −Gout_grdfile −Jparameters [ −A[k|m|n|i|c|p] ] [ −C[dx/dy] ] [
−Dxinc[unit][=|+][/yinc[unit][=|+]] ] [ −Edpi ] [ −F ] [ −I ] [ −Mc|i|m|p ] [ −Nnx/ny ] [
−Rwest/east/south/north[r] ] [ −S[-]b|c|l|n[/threshold] ] [ −V ]
DESCRIPTION
grdproject will do one of two things depending whether −I has been set. If set, it will transform a gridded
data set from a rectangular coordinate system onto a geographical system by resampling the surface at the
new nodes. If not set, it will project a geographical gridded data set onto a rectangular grid. To obtain the
value at each new node, its location is inversely projected back onto the input grid after which a value is
interpolated between the surrounding input grid values. By default bi-cubic interpolation is used. Aliasing
is avoided by also forward projecting the input grid nodes. If two or more nodes are projected onto the
same new node, their average will dominate in the calculation of the new node value. Interpolation and
aliasing is controlled with the −S option. The new node spacing may be determined in one of several ways
by specifying the grid spacing, number of nodes, or resolution. Nodes not constrained by input data are set
to NaN.
The −R option can be used to select a map region larger or smaller than that implied by the extent of the
grid file.
in_grdfile
2-D binary grid file to be transformed. (See GRID FILE FORMATS below.)
−G Specify the name of the output grid file. (See GRID FILE FORMATS below.)
CONIC PROJECTIONS:
GMT 4.5.14 1 Nov 2015 1



OPTIONS
−A Force 1:1 scaling, i.e., output (or input, see −I) data are in actual projected meters. To specify
other units, append k (km), m (mile),n (nautical mile), i (inch), c (cm), or p (points). Without −A,
the output (or input, see −I) are in the units specified by MEASURE_UNIT (but see −M).
−C Let projected coordinates be relative to projection center [Default is relative to lower left corner].
Optionally, add offsets in the projected units to be added (or subtracted when −I is set) to (from)
the projected coordinates, such as false eastings and northings for particular projection zones [0/0].
−D x_inc [and optionally y_inc] is the grid spacing. Optionally, append a suffix modifier. Geographi-
then grid spacing has already been initialized; use −D to override the values.
−E Set the resolution for the new grid in dots per inch.
−F Toggle between pixel and gridline node registration [Default is same as input].
−I Do the Inverse transformation, from rectangular to geographical.
−M Append c, i, or m to indicate that cm, inch, or meter should be the projected measure unit [Default
is set by MEASURE_UNIT in .gmtdefaults4]. Cannot be used with −A.
GMT 4.5.14 1 Nov 2015 2

−N Set the number of grid nodes in the new grid.

output and plot formats are customizable; see gmtdefaults). You may ask to project only a subset
of the grid by specifying a smaller input w/e/s/n region [Default is the region given by the grid
file]. Special case for the UTM projection: If −C and −I are used and −R is not given then the
region is set to coincide with the given UTM zone so as to preserve the full ellipsoidal solution
(See RESTRICTIONS for more information).
−S Select the 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, prepend - to switch off antialiasing. Add /threshold 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 interpo-
lation 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].
GRID FILE FORMATS
EXAMPLES
To transform the geographical grid dbdb5.grd onto a pixel Mercator grid at 300 dpi, run
grdproject dbdb5.grd −R 20/50/12/25 −Jm 0.25i −E 300 −F −G dbdb5_merc.grd
To inversely transform the file topo_tm.grd back onto a geographical grid, use
grdproject topo_tm.grd −R-80/-70/20/40 −Jt-75/1:500000 −I −D 5m −V −G topo.grd
This assumes, of course, that the coordinates in topo_tm.grd were created with the same projection
GMT 4.5.14 1 Nov 2015 3

parameters.
To inversely transform the file topo_utm.grd (which is in UTM meters) back to a geographical grid we
specify a one-to-one mapping with meter as the measure unit:
grdproject topo_utm.grd −R 203/205/60/65 −Ju 5/1:1 −I −Mm −G topo.grd −V

RESTRICTIONS
The boundaries of a projected (rectangular) data set will not necessarily give rectangular geographical
boundaries (Mercator is one exception). In those cases some nodes may be unconstrained (set to NaN). To
get a full grid back, your input grid may have to cover a larger area than you are interested in.
For some projections, a spherical solution may be used despite the user having selected an ellipsoid. This
occurs when the users −R setting implies a region that exceeds the domain in which the ellipsoidal series
expansions are valid. These are the conditions: (1) Lambert Conformal Conic (−JL) and Albers Equal-
Area (−JB) will use the spherical solution when the map scale exceeds 1.0E7. (2) Transverse Mercator
(−JT) and UTM (−JU) will will use the spherical solution when either the west or east boundary given in
−R is more than 10 degrees from the central meridian, and (3) same for Cassini (−JC) but with a limit of
only 4 degrees.
SEE ALSO
GMT (1), gmtdefaults(1), mapproject(1)
GMT 4.5.14 1 Nov 2015 4

GRDREFORMAT(1) Generic Mapping Tools GRDREFORMAT(1)
NAME
grdreformat − Converting between different grid file formats.
SYNOPSIS
grdreformat ingrdfile[=id[/scale/offset[/NaNvalue]]] outgrdfile[=id[/scale/offset[/NaNvalue]]] [ −N ] [
−Rwest/east/south/north[r] ] [ −f[i|o]colinfo ] [ −V ]
DESCRIPTION
grdreformat reads a grid file in one format and writes it out using another format. As an option the user
may select a subset of the data to be written and to specify scaling, translation, and NaN-value.
ingrdfile
The grid file to be read. Append format =id code if not a standard COARDS-compliant netCDF
grid file. If =id is set (see below), you may optionally append scale and offset. These options will
scale the data and then offset them with the specified amounts after reading.
If scale and offset are supplied you may also append a value that represents ’Not-a-Number’ (for
floating-point grids this is unnecessary since the IEEE NaN is used; however integers need a value
which means no data available.)
outgrdfile
The grid file to be written. Append format =id code if not a standard COARDS-compliant netCDF
grid file. If =id is set (see below), you may optionally append scale and offset. These options are
particularly practical when storing the data as integers, first removing an offset and then scaling
down the values. Since the scale and offset are applied in reverse order when reading, this does
not affect the data values (except for round-offs).
If scale and offset are supplied you may also append a value that represents ’Not-a-Number’ (for
floating-point grids this is unnecessary since the IEEE NaN is used; however integers need a value
which means no data available.)
OPTIONS
−N Suppress the writing of the GMT header structure. This is useful when you want to write a native
grid to be used by grdraster. It only applies to native grids and is ignored for netCDF output.
FORMAT IDENTIFIER
By default, grids will be written as floating point data stored in binary files using the netCDF format and
meta-data structure. This format is conform the COARDS conventions. GMT versions prior to 4.1 pro-
duced netCDF files that did not conform to these conventions. Although these files are still supported, their
use is deprecated. To write other than floating point COARDS-compliant netCDF files, append the =id
GMT 4.5.14 1 Nov 2015 1

suffix to the filename outgrdfile.

When reading files, grdreformat and other GMT programs will automatically recognize any type of
netCDF grid file. These can be in either COARDS-compliant or pre-4.1 format, and contain floating-point
or integer data. To read other types of grid files, append the =id suffix to the filename ingrdfile.
id GMT 3 netCDF legacy formats

cb GMT netCDF format (byte) (deprecated)
cs GMT netCDF format (short) (deprecated)
ci GMT netCDF format (int) (deprecated)
cf GMT netCDF format (float) (deprecated)
cd GMT netCDF format (double) (deprecated)
id GMT native binary formats

bm GMT native, C-binary format (bit-mask)
bb GMT native, C-binary format (byte)
bs GMT native, C-binary format (short)
bi GMT native, C-binary format (int)
bf GMT native, C-binary format (float)
bd GMT native, C-binary format (double)
id GMT 4 netCDF standard

nb GMT netCDF format (byte) (COARDS-compliant)
ns GMT netCDF format (short) (COARDS-compliant)
ni GMT netCDF format (int) (COARDS-compliant)
nf GMT netCDF format (float) (COARDS-compliant) [DEFAULT]
nd GMT netCDF format (double) (COARDS-compliant)
id Misc formats
rb SUN rasterfile format (8-bit standard)
rf GEODAS grid format GRD98 (NGDC)
sf Golden Software Surfer format 6 (float)
sd Golden Software Surfer format 7 (double, read-only)
af Atlantic Geoscience Center format AGC (float)
gd Import through GDAL (convert to float) -- NON-STANDARD
GMT STANDARD NETCDF FILES
The standard format used for grdfiles is based on netCDF and conforms to the COARDS conventions. Files
written in this format can be read by numerous third-party programs and are platform-independent. Some
disk-space can be saved by storing the data as bytes or shorts in stead of integers. Use the scale and offset
parameters to make this work without loss of data range or significance. For more details, see Appendix B.
Multi-variable grid files
By default, GMT programs will read the first 2-dimensional grid contained in a COARDS-compliant
netCDF file. Alternatively, use ingrdfile?varname (ahead of any optional suffix =id) to specify the
requested variable varname. Since ? has special meaning as a wildcard, escape this meaning by placing the
full filename and suffix between quotes.
Multi-dimensional grids
To extract one layer or level from a 3-dimensional grid stored in a COARDS-compliant netCDF file,
append both the name of the variable and the index associated with the layer (starting at zero) in the form:
ingrdfile?varname[layer]. Alternatively, specify the value associated with that layer using parentheses in
stead of brackets: ingridfile?varname(level).
In a similar way layers can be extracted from 4- or even 5-dimensional grids. For example, if a grid has the
dimensions (parameter, time, depth, latitude, longitude), a map can be selected by using: ingridfile?var-
name(parameter,time,depth).
Since question marks, brackets and parentheses have special meanings on the command line, escape these
GMT 4.5.14 1 Nov 2015 2

meanings by placing the full filename and suffix between quotes.

NATIVE BINARY FILES
For binary native GMT files the size of the GMT grdheader block is hsize = 892 bytes, and the total size of
the file is hsize + nx * ny * item_size, where item_size is the size in bytes of each element (1, 2, 4). Bit
grids are stored using 4-byte integers, each holding 32 bits, so for these files the size equation is modified
by using ceil (nx / 32) * 4 instead of nx. Note that these files are platform-dependent. Files written on Little
Endian machines (e.g., PCs) can not be read on Big Endian machines (e.g., most workstations). Also note
that it is not possible for GMT to determine uniquely if a 4-byte grid is float or int; in such cases it is best
to use the =ID mechanism to specify the file format. In all cases a native grid is considered to be signed
(i.e., there are no provision for unsigned short ints or unsigned bytes). For header and grid details, see Ap-
pendix B.
EXAMPLES
To extract the second layer from a 3-dimensional grid named temp from a COARDS-compliant netCDF file
climate.grd:
grdreformat climate.grd?temp[1] temp.grd -V
To create a 4-byte native floating point grid from the COARDS-compliant netCDF file data.grd:
grdreformat data.grd ras_data.b4=bf −V
To make a 2-byte short integer file, scale it by 10, subtract 32000, setting NaNs to -9999, do
grdreformat values.grd shorts.i2=bs/10/-32000/-9999 −V
To create a Sun standard 8-bit rasterfile for a subset of the data file image.grd, assuming the range in
image.grd is 0-1 and we need 0-255, run
grdreformat image.grd −R-60/-40/-40/-30 image.ras8=rb/255/0 −V
To convert etopo2.grd to etopo2.i2 that can be used by grdraster, try
grdreformat etopo2.grd etopo2.i2=bs −N −V

SEE ALSO
GMT (1), grdmath(1)
GMT 4.5.14 1 Nov 2015 3

GRDSAMPLE(1) Generic Mapping Tools GRDSAMPLE(1)
NAME
grdsample − Resample a grid file onto a new grid
SYNOPSIS
grdsample in_grdfile −Gout_grdfile [ −F ] [ −Ixinc[unit][=|+][/yinc[unit][=|+]] ] [ −Lflag ] [
−Q[b|c|l|n][[/]threshold] ] [ −Rwest/east/south/north[r] ] [ −T ] [ −V ] [ −fcolinfo ]
DESCRIPTION
grdsample reads a grid file and interpolates it to create a new grid file with either: a different registration
(−F or −T); or, a new grid-spacing or number of nodes (−I), and perhaps also a new sub-region (−R). A
bicubic [Default], bilinear, B-spline or nearest-neighbor interpolation (−Q) is used, requiring boundary con-
ditions (−L). Note that using −R only is equivalent to grdcut or grdedit −S. grdsample safely creates a
fine mesh from a coarse one; the converse may suffer aliasing unless the data are filtered using grdfft or
grdfilter.
When −R is omitted, the output grid will cover the same region as the input grid. When −I is omitted, the
grid spacing of the output grid will be the same as the input grid. Either −F or −T can be used to change
the grid registration. When omitted, the output grid will have the same registration as the input grid.
in_grdfile
The name of the input 2-D binary grid file. (See GRID FILE FORMAT below.)
−G The name of the output grid file. (See GRID FILE FORMAT below.)
OPTIONS
−F Force pixel node registration on output grid. [Default is same registration as input grid].
−L Boundary condition flag may be x or y or xy indicating data is periodic in range of x or y or both
set by −R, or flag may be g indicating geographical conditions (x and y are lon and lat). [Default
uses "natural" conditions (second partial derivative normal to edge is zero) unless the grid is auto-
matically recognised as periodic.]
−Q Quick mode, use bilinear rather than bicubic interpolation [Default]. Alternatively, select the
interpolation mode by adding b for B-spline smoothing, c for bicubic interpolation, l for bilinear
interpolation or n for nearest-neighbor value. Optionally, append threshold in the range [0,1].
This parameter controls how close to nodes with NaN values the interpolation will go. E.g., a
threshold of 0.5 will interpolate about half way from a non-NaN to a NaN node, whereas 0.1 will
go about 90% of the way, etc. [Default is 1, which means none of the (4 or 16) nearby nodes may
be NaN]. −Q0 will just return the value of the nearest node instead of interpolating. This is the
same as using −Qn.
GMT 4.5.14 1 Nov 2015 1

−T Translate between grid and pixel registration; if the input is grid-registered, the output will be
pixel-registered and vice-versa.
GRID FILE FORMATS
HINTS
If an interpolation point is not on a node of the input grid, then a NaN at any node in the neighborhood sur-
rounding the point will yield an interpolated NaN. Bicubic interpolation [default] yields continuous first
derivatives but requires a neighborhood of 4 nodes by 4 nodes. Bilinear interpolation [−Q] uses only a 2 by
2 neighborhood, but yields only zeroth-order continuity. Use bicubic when smoothness is important. Use
bilinear to minimize the propagation of NaNs.
EXAMPLES
To resample the 5 x 5 minute grid in hawaii_5by5_topo.grd onto a 1 minute grid:
grdsample hawaii_5by5_topo.grd −I 1m −Ghawaii_1by1_topo.grd
To translate the gridline-registered file surface.grd to pixel registration while keeping the same region and
GMT 4.5.14 1 Nov 2015 2

grid interval:
grdsample surface.grd −T −G pixel.grd

SEE ALSO
GMT (1), grdedit(1), grdfft(1), grdfilter(1)
GMT 4.5.14 1 Nov 2015 3

GRDTRACK(1) Generic Mapping Tools GRDTRACK(1)
NAME
grdtrack − Sampling of a 2-D grid file along 1-D trackline (a sequence of x,y points)
SYNOPSIS
grdtrack xyfile −Ggrdfile [ −H[i][nrec] ] [ −Lflag ] [ −Q[b|c|l|n][[/]threshold] ] [
−Rwest/east/south/north[r] ] [ −S ] [ −V ] [ −Z ] [ −:[i|o] ] [ −b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]col-
info ] [ −m[i|o][flag] ]
DESCRIPTION
grdtrack reads a grid file (or a Sandwell/Smith IMG file) and a table (from file or standard input) with
(x,y) positions in the first two columns (more columns may be present). It interpolates the grid at the posi-
tions in the table and writes out the table with the interpolated values added as a new column. A bicubic
[Default], bilinear, B-spline or nearest-neighbor (see −Q) interpolation is used, requiring boundary condi-
tions at the limits of the region (see −L).
xyfile This is an ASCII (or binary, see −b) file where the first 2 columns hold the (x,y) positions where
the user wants to sample the 2-D data set.
−G grdfile is a 2-D binary grid file with the function f(x,y). If the specified grid is in Sandwell/Smith
Mercator format you must append a comma-separated list of arguments that includes a scale to
multiply the data (usually 1 or 0.1), the mode which stand for the following: (0) Img files with no
constraint code, returns data at all points, (1) Img file with constraints coded, return data at all
points, (2) Img file with constraints coded, return data only at constrained points and NaN else-
where, and (3) Img file with constraints coded, return 1 at constraints and 0 elsewhere, and option-
ally the max latitude in the IMG file [80.738]. (See GRID FILE FORMAT below.)
OPTIONS
skipped.
uses "natural" conditions (second partial derivative normal to edge is zero) unless the grid is auto-
matically recognised as periodic.]
−Q Quick mode, use bilinear rather than bicubic interpolation [Default]. Alternatively, select the
interpolation mode by adding b for B-spline smoothing, c for bicubic interpolation, l for bilinear
interpolation or n for nearest-neighbor value. Optionally, append threshold in the range [0,1].
This parameter controls how close to nodes with NaN values the interpolation will go. E.g., a
threshold of 0.5 will interpolate about half way from a non-NaN to a NaN node, whereas 0.1 will
go about 90% of the way, etc. [Default is 1, which means none of the (4 or 16) nearby nodes may
be NaN]. −Q0 will just return the value of the nearest node instead of interpolating. This is the
same as using −Qn.
GMT 4.5.14 1 Nov 2015 1


−S Suppress the output of interpolated points that result in NaN values.
−Z Only write out the sampled z-values [Default writes all columns].
−: Toggles between (longitude,latitude) and (latitude,longitude) input/output. [Default is (longi-
tude,latitude)].
output file. [Default is one more than input].
D_FORMAT setting.
GRID FILE FORMATS
HINTS
If an interpolation point is not on a node of the input grid, then a NaN at any node in the neighborhood sur-
rounding the point will yield an interpolated NaN. Bicubic interpolation [default] yields continuous first
derivatives but requires a neighborhood of 4 nodes by 4 nodes. Bilinear interpolation [−Q] uses only a 2 by
2 neighborhood, but yields only zeroth-order continuity. Use bicubic when smoothness is important. Use
bilinear to minimize the propagation of NaNs, or lower threshold.
GMT 4.5.14 1 Nov 2015 2

EXAMPLES
To sample the file hawaii_topo.grd along the SEASAT track track_4.xyg (An ASCII table containing longi-
tude, latitude, and SEASAT-derived gravity, preceded by one header record):
grdtrack track_4.xyg −G hawaii_topo.grd −H > track_4.xygt
To sample the Sandwell/Smith IMG format file topo.8.2.img (2 minute predicted bathymetry on a Mercator
grid) along the lon,lat coordinates given in the file cruise_track.xy, try
grdtrack cruise_track.xy −G topo.8.2.img,1,1 > obs_and_predicted.d

SEE ALSO
GMT (1), surface(1), sample1d(1)
GMT 4.5.14 1 Nov 2015 3

GRDTREND(1) Generic Mapping Tools GRDTREND(1)
NAME
grdtrend − Fit and/or remove a polynomial trend in a grid file
SYNOPSIS
grdtrend grdfile −Nn_model[r] [ −Ddiff.grd ] [ −Ttrend.grd ] [ −V ] [ −Wweight.grd ]
DESCRIPTION
grdtrend reads a 2-D grid file and fits a low-order polynomial trend to these data by [optionally weighted]
least-squares. The trend surface is defined by:
m1 + m2*x + m3*y + m4*x*y + m5*x*x + m6*y*y + m7*x*x*x + m8*x*x*y + m9*x*y*y + m10*y*y*y.
The user must specify −Nn_model, the number of model parameters to use; thus, −N4 fits a bilinear trend,
−N6 a quadratic surface, and so on. Optionally, append r to the −N option to perform a robust fit. In this
case, the program will iteratively reweight the data based on a robust scale estimate, in order to converge to
a solution insensitive to outliers. This may be handy when separating a "regional" field from a "residual"
which should have non-zero mean, such as a local mountain on a regional surface.
If data file has values set to NaN, these will be ignored during fitting; if output files are written, these will
also have NaN in the same locations.

grdfile The name of a 2-D binary grid file.
−N [r]n_model sets the number of model parameters to fit. Append r for robust fit.
OPTIONS
−D Write the difference (input data - trend) to the file diff.grd.
−T Write the fitted trend to the file trend.grd.
−W If weight.grd exists, it will be read and used to solve a weighted least-squares problem. [Default:
Ordinary least-squares fit.] If the robust option has been selected, the weights used in the robust fit
will be written to weight.grd.
REMARKS
The domain of x and y will be shifted and scaled to [-1, 1] and the basis functions are built from Legendre
polynomials. These have a numerical advantage in the form of the matrix which must be inverted and
allow more accurate solutions. NOTE: The model parameters listed with −V are Legendre polynomial
coefficients; they are not numerically equivalent to the m#s in the equation described above. The descrip-
tion above is to allow the user to match −N with the order of the polynomial surface. See grdmath if you
need to evaluate the trend using the reported coefficients.
GRID FILE FORMATS
GMT 4.5.14 1 Nov 2015 1

GRDTREND(1) Generic Mapping Tools GRDTREND(1)
EXAMPLES
To remove a planar trend from hawaii_topo.grd and write result in hawaii_residual.grd:
grdtrend hawaii_topo.grd −N 3 −D hawaii_residual.grd
To do a robust fit of a bicubic surface to hawaii_topo.grd, writing the result in hawaii_trend.grd and the
weights used in hawaii_weight.grd, and reporting the progress:
grdtrend hawaii_topo.grd −N 10r −T hawaii_trend.grd −W hawaii_weight.grd −V

SEE ALSO
GMT (1), grdfft(1), grdfilter(1)
GMT 4.5.14 1 Nov 2015 2

GRDVECTOR(1) Generic Mapping Tools GRDVECTOR(1)
NAME
grdvector − Plot vector fields from grid files
SYNOPSIS
grdvector compx.grd compy.grd −Jparameters [ −A ] [ −B[p|s]parameters ] [ −Ccptfile ] [ −E ] [ −Gfill ] [
−Ixinc[unit][=|+][/yinc[unit][=|+]] ] [ −K ] [ −N ] [ −O ] [ −P ] [ −Qparameters ] [
−Rwest/east/south/north[r] ] [ −S[l]scale ] [ −T ] [ −U[just/dx/dy/][c|label] ] [ −V ] [ −Wpen ] [
−X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [ −Z ] [ −ccopies ] [ −f[i|o]colinfo ]
DESCRIPTION
grdvector reads two 2-D grid files which represents the x- and y-components of a vector field and produces
a vector field plot by drawing vectors with orientation and length according to the information in the files.
Alternatively, polar coordinate components may be used (r, theta). grdvector is basically a short-hand for
using 2 calls to grd2xyz and pasting the output through psxy −SV.
compx.grd
Contains the x-component of the vector field.
compy.grd
Contains the y-component of the vector field. (See GRID FILE FORMATS below.)
CONIC PROJECTIONS:

GMT 4.5.14 1 Nov 2015 1



OPTIONS
−A Means grid files have polar (r, theta) components instead of Cartesian (x, y).
details.
−C Use cptfile to assign colors based on vector length.
−E Center vectors on grid nodes [Default draws from grid node].
−G Sets color or shade for vector interiors [Default is no fill]. (See SPECIFYING FILL below).
−I Only plot vectors at nodes every x_inc, y_inc apart (must be multiples of original grid spacing).
Append m for minutes or c for seconds. [Default plots every node].
−N Do NOT clip vectors at map boundaries [Default will clip].
−Q Select vector plot [Default is stick-plot]. Optionally, specify parameters which are
arrowwidth/headlength/headwidth [Default is 0.075c/0.3c/0.25c (or 0.03i/0.12i/0.1i)]. Append
nsize which will cause vectors shorter than size to have their appearance scaled by length/size.
output and plot formats are customizable; see gmtdefaults). Specify a subset of the grid.
GMT 4.5.14 1 Nov 2015 2

−S Sets scale for vector length in data units per distance measurement unit [1]. Append c, i, m, p to
indicate the measurement unit (cm, inch, m, point). Prepend l to indicate a fixed length for all vec-
tors.
−T Means azimuth should be converted to angles based on the selected map projection.
−W Set pen attributes used for vector outlines [Default: width = 0.25p, color = black, texture = solid].
(See SPECIFYING PENS below).
size.
−Z Means the angles provided are azimuths rather than direction (requires −A).
SPECIFYING PENS
‘.’.
SPECIFYING FILL
SPECIFYING COLOR
GRID FILE FORMATS
offset are optional scale factor and offset to be applied to all grid values, and nan is the value used to
GMT 4.5.14 1 Nov 2015 3

indicate missing data. See grdreformat(1) and Section 4.17 of the GMT Technical Reference and Cook-
book for more information.
EXAMPLES
To draw the vector field given by the files r.grd and theta.grd on a linear plot with scale 5 cm per data unit,
using vector rather than stick plot, and scale vector magnitudes so that 10 units equal 1 inch, run
grdvector r.grd theta.grd −Jx 5c −A −Q −S 10i > gradient.ps
SEE ALSO
GMT (1), gmtcolors(5), grdcontour(1), psxy(1)
GMT 4.5.14 1 Nov 2015 4

GRDVIEW(1) Generic Mapping Tools GRDVIEW(1)
NAME
grdview − Create 3-D perspective grayshaded/colored image or mesh from a 2-D grid file
SYNOPSIS
grdview relief_file −Jparameters [ −B[p|s]parameters ] [ −Ccptfile ] [ −Eazim/elev[+wlon/lat[/z]][+vx0/y0]
] [ −Gdrapefile | −Ggrd_r,grd_g,grd_b ] [ −Iintensfile ] [ −Jz|Zparameters ] [ −K ] [ −L[flags] ] [
−Nlevel[/color] ] [ −O ] [ −P ] [ −Qtype[g] ] [ −Rwest/east/south/north[/zmin/zmax][r] ] [ −Ssmooth ] [
−T[s][o[pen]] ] [ −U[just/dx/dy/][c|label] ] [ −V ] [ −Wtype/pen ] [ −X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-
shift[u]] ] [ −Zzlevel ] [ −ccopies ]
DESCRIPTION
grdview reads a 2-D grid file and produces a 3-D perspective plot by drawing a mesh, painting a col-
ored/grayshaded surface made up of polygons, or by scanline conversion of these polygons to a rasterim-
age. Options include draping a data set on top of a surface, plotting of contours on top of the surface, and
apply artificial illumination based on intensities provided in a separate grid file.
relief_file
2-D gridded data set to be imaged (the relief of the surface). (See GRID FILE FORMAT below.)
CONIC PROJECTIONS:

GMT 4.5.14 1 Nov 2015 1


−Jz Sets the vertical scaling (for 3-D maps). Same syntax as −Jx.
OPTIONS
details.
−C name of the color palette file. Must be present if you want (1) mesh plot with contours (−Qm), or
(2) shaded/colored perspective image (−Qs or −Qi). For −Qs: You can specify that you want to
skip a z-slice by setting red = -; to use a pattern give red = P|pdpi/pattern[:Fr/g/b[Br/g/b]].
−G Drape the image in drapefile on top of the relief provided by relief_file. [Default is relief_file].
Note that −Jz and −N always refers to the relief_file. The drapefile only provides the information
pertaining to colors, which is looked-up via the cpt file (see −C). Alternatively, give three grid
files separated by commas. These files must contain the red, green, and blue colors directly (in
0-255 range) and no cpt file is needed. The drapefile may be of higher resolution than the
relief_file.
−I Gives the name of a grid file with intensities in the (-1,+1) range. [Default is no illumination].
−L Boundary condition flags may be x or y or xy indicating data is periodic in range of x or y or both,
or flags may be g indicating geographical conditions (x and y are lon and lat). [Default uses "natu-
ral" conditions (second partial derivative normal to edge is zero).] If no flags are set, use bilinear
rather than the default bicubic resampling when draping is required.
−N Draws a plane at this z-level. If the optional color is provided, the frontal facade between the
plane and the data perimeter is colored. See −Wf for setting the pen used for the outline. (See
SPECIFYING COLOR below).
−Q Select one of four settings: 1. Specify m for mesh plot [Default], and optionally append /color for
a different mesh paint [white]. 2. Specify s for surface plot, and optionally append m to have
mesh lines drawn on top of surface. 3. Specify i for image plot, and optionally append the effec-
tive dpi resolution for the rasterization [100]. 4. Specify c. Same as −Qi but will make nodes with
z = NaN transparent, using the colormasking feature in PostScript Level 3 (the PS device must
GMT 4.5.14 1 Nov 2015 2

support PS Level 3). For any of these choices, you may force a monochrome image by appending
g. Colors are then converted to shades of gray using the (television) YIQ transformation.
output and plot formats are customizable; see gmtdefaults). This option may be used to indicate
the range used for the 3-D axes [Default is region given by the relief_file]. You may ask for a
larger w/e/s/n region to have more room between the image and the axes. A smaller region than
specified in the relief_file will result in a subset of the grid.
−S Smooth the contours before plotting (see grdcontour) [Default is no smoothing].
−T Plot image without any interpolation. This involves converting each node-centered bin into a
polygon which is then painted separately. Append s to skip nodes with z = NaN. This option is
useful for categorical data where interpolating between values is meaningless. Optionally, append
o to draw the tile outlines, and specify a custom pen if the default pen is not to your liking. As this
option produces a flat surface it cannot be combined with −JZ or −Jz. (See SPECIFYING PENS
below).
−Wc Draw contour lines on top of surface or mesh (not image). Append pen attributes used for the con-
tours. [Default: width = 0.75p, color = black, texture = solid]. (See SPECIFYING PENS below).
−Wm Sets the pen attributes used for the mesh. [Default: width = 0.25p, color = black, texture = solid].
You must also select −Qm or −Qsm for meshlines to be drawn.
−Wf Sets the pen attributes used for the facade. [Default: width = 0.25p, color = black, texture = solid].
You must also select −N for the facade outline to be drawn. (See SPECIFYING PENS below).
size.
−Z Sets the z-level of the basemap [Default is the bottom of the z-axis].
SPECIFYING PENS
color and texture, each of which is optional. width can be indicated as a measure (points,
GMT 4.5.14 1 Nov 2015 3

centimeters, inches) or as faint, thin[ner|nest], thick[er|est], fat[ter|test], or obese. color speci-

fies a gray shade or color (see SPECIFYING COLOR below). texture is a combination of dashes
‘-’ and dots ‘.’.
SPECIFYING COLOR
GRID FILE FORMATS
EXAMPLES
To make a mesh plot from the file hawaii_grav.grd and drawing the contours given in the color palette file
hawaii.cpt on a Lambert map at 1.5 cm/degree along the standard parallels 18 and 24, with vertical scale 20
mgal/cm, and looking at the surface from SW at 30 degree elevation, run
grdview hawaii_grav.grd −Jl 18/24/1.5c −C hawaii.cpt −Jz 0.05c −Qm −N-100 −E 225/30 −Wc >
hawaii_grav_image.ps
To create a illuminated color perspective plot of the gridded data set image.grd, using the color palette file
color.rgb, with linear scaling at 10 cm/x-unit and tickmarks every 5 units, with intensities provided by the
file intens.grd, and looking from the SE, use
grdview image.grd −Jx 10.0c −C color.rgb −Qs −E 135/30 −I intens.grd > image3D.ps
To make the same plot using the rastering option with dpi = 50, use
grdview image.grd −Jx 10.0c −C color.rgb −Qi 50 −E 135/30 −I intens.grd > image3D.ps
To create a color PostScript perspective plot of the gridded data set magnetics.grd, using the color palette
file mag_intens.cpt, draped over the relief given by the file topography.grd, with Mercator map width of 6
inch and tickmarks every 1 degree, with intensities provided by the file topo_intens.grd, and looking from
the SE, run
grdview topography.grd −JM 6i −G magnetics.grd −C mag_intens.cpt −Qs −E 140/30 −I topo_intens.grd

> draped3D.ps
Given topo.grd and the Landsat image veggies.ras, first run gmt2rgb to get the red, green, and blue grids,
and then drape this image over the topography and shade the result for good measure. The commands are
gmt2rgb veggies.ras −G layer_%c.grd

grdview topo.grd −JM 6i −Qi −E 140/30 −I topo_intens.grd −G layer_r.grd,layer_g.grd,layer_b.grd >
GMT 4.5.14 1 Nov 2015 4

image.ps
REMARKS
For the −Qs option: PostScript provides no way of smoothly varying colors within a polygon, so colors can
only vary from polygon to polygon. To obtain smooth images this way you may resample the grid file(s)
using grdsample or use a finer grid size when running gridding programs like surface or nearneighbor.
Unfortunately, this produces huge PostScript files. The alternative is to use the −Qi option, which com-
putes bilinear or bicubic continuous color variations within polygons by using scanline conversion to image
the polygons.
SEE ALSO
GMT (1), gmt2rgb(1), gmtcolors(5), grdcontour(1), grdimage(1), nearneighbor(1), psbasemap(1), pscon-
tour(1), pstext(1), surface(1)
GMT 4.5.14 1 Nov 2015 5

GRDVOLUME(1) Generic Mapping Tools GRDVOLUME(1)
NAME
grdvolume − Calculating volume under a surface within a contour
SYNOPSIS
grdvolume grdfile [ −Ccval or −Clow/high/delta ] [ −Lbase ] [ −Rwest/east/south/north[r] ] [ −S[k] ] [ −T
] [ −V[l] ] [ −Zfact[/delta] ] [ −fcolinfo ]
DESCRIPTION
grdvolume reads a 2-D binary grid file and calculates the volume contained between the surface and the
plane specified by the given contour (or zero if not given) and reports the area, volume, and maximum
mean height (volume/area). Alternatively, specify a range of contours to be tried and grdvolume will
determine the volume and area inside the contour for all contour values. The contour that produced the
maximum mean height is reported as well. This feature may be used with grdfilter in designing an Opti-
mal Robust Separator [Wessel, 1998].
grdfile The name of the input 2-D binary grid file. (See GRID FILE FORMAT below.)
OPTIONS
−C find area and volume inside the cval contour. Alternatively, search using all contours from low to
high in steps of delta. [Default returns entire area and volume of grid]. The area is measured in
the plane of the contour.
−L Also add in the volume from the level of the contour down to base [Default base is contour].
−S Convert degrees to meters, append k for km [Default is Cartesian].
−T Use curvature minimum rather than maximum height to find best contour value (when contour
search is selected with −C).
−V Selects verbose mode, which will send progress reports to stderr [Default runs "silently"]. Append
l to see all the results for each contour level tested (when contour search has been selected).
−Z Optionally subtract shift before scaling data by fact. [Default is no scaling]. (Numbers in −C, −L
refer to values after this scaling has occurred).
GRID FILE FORMATS
offset are optional scale factor and offset to be applied to all grid values, and nan is the value used to
GMT 4.5.14 1 Nov 2015 1

GRDVOLUME(1) Generic Mapping Tools GRDVOLUME(1)
indicate missing data. See grdreformat(1) and Section 4.17 of the GMT Technical Reference and Cook-
book for more information.
EXAMPLES
To determine the volume in kmˆ3 under the surface hawaii_topo.grd (height in km), use
grdvolume hawaii_topo.grd −Sk
To find the volume between the surface peaks.grd and the contour z = 250, use
grdvolume peaks.grd −Sk −C 250
To search for the contour, between 100 and 300 in steps of 10, that maximizes the ratio of volume to sur-
face area for the file peaks.grd, use
grdvolume peaks.grd −Sk −C 100/300/10 > results.d
To see the areas and volumes for all the contours in the previous example, use
grdvolume peaks.grd −Sk −Vl −C 100/300/10 > results.d

NOTES
grdvolume distinguishes between gridline and gridcell oriented grids. In both cases the area and volume
are computed up to the grid boundaries. That means that in the first case the gridcells on the boundary only
contribute half their area (and volume), whereas in the second case all gridcells are fully used. The excep-
tion is when the −C flag is used: since contours do not extend beyond the outermost gridpoint, both grid
types are treated the same. That means the outer rim in gridcell oriented grids is ignored when using the −C
flag.
SEE ALSO
GMT (1), grdfilter(1)
REFERENCES
Wessel, P., 1998, An empirical method for optimal robust regional-residual separation of geophysical data,
Math. Geol., 30(4), 391−408.
GMT 4.5.14 1 Nov 2015 2

GREENSPLINE(1) Generic Mapping Tools GREENSPLINE(1)
NAME
greenspline − Interpolate 1-D, 2-D, 3-D Cartesian or spherical surface data using Green’s function splines.
SYNOPSIS
greenspline [ datafile(s) ] [ −A[1|2|3|4|5,]gradfile ] [ −Ccut[/file] ] [ −Dmode ] [ −F ] [ −Ggrdfile ] [
−H[i][nrec] ] [ −Ixinc[yinc[zinc]] ] [ −L ] [ −Nnodefile ] [ −Qaz|x/y/z ] [ −Rxmin/xmax[/ymin/ymax[/zminz-
max]] ] [ −Sc|t|g|p|q[pars] ] [ −Tmaskgrid ] [ −V ] [ −:[i|o] ] [ −bi[s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]col-
info ] [ −bo[s|S|d|D[ncol]|c[var1/...]] ]
DESCRIPTION
greenspline uses the Green’s function G(x; x’) for the chosen spline and geometry to interpolate data at
regular [or arbitrary] output locations. Mathematically, the solution is composed as w(x) = sum {c(i) G(x;
x(i))}, for i = 1, n, the number of data points {x(i), w(i)}. Once the n coefficients c(i) have been found then
the sum can be evaluated at any output point x. Choose between ten minimum curvature, regularized, or
continuous curvature splines in tension for either 1-D, 2-D, or 3-D Cartesian coordinates or spherical sur-
face coordinates. After first removing a linear or planar trend (Cartesian geometries) or mean value (spheri-
cal surface) and normalizing these residuals, the least-squares matrix solution for the spline coefficients c(i)
is found by solving the n by n linear system w(j) = sum-over-i {c(i) G(x(j); x(i))}, for j = 1, n; this solution
yields an exact interpolation of the supplied data points. Alternatively, you may choose to perform a singu-
lar value decomposition (SVD) and eliminate the contribution from the smallest eigenvalues; this approach
yields an approximate solution. Trends and scales are restored when evaluating the output.
OPTIONS
datafile(s)
The name of one or more ASCII [or binary, see −bi] files holding the x, w data points. If no file is
given then we read standard input instead.
−A The solution will partly be constrained by surface gradients v = v*n, where v is the gradient mag-
nitude and n its unit vector direction. The gradient direction may be specified either by Cartesian
components (either unit vector n and magnitude v separately or gradient components v directly) or
angles w.r.t. the coordinate axes. Specify one of five input formats: 0: For 1-D data there is no
direction, just gradient magnitude (slope) so the input format is x, gradient. Options 1-2 are for
2-D data sets: 1: records contain x, y, azimuth, gradient (azimuth in degrees is measured clockwise
from the vertical (north) [Default]). 2: records contain x, y, gradient, azimuth (azimuth in degrees
is measured clockwise from the vertical (north)). Options 3-5 are for either 2-D or 3-D data: 3:
records contain x, direction(s), v (direction(s) in degrees are measured counter-clockwise from the
horizontal (and for 3-D the vertical axis). 4: records contain x, v. 5: records contain x, n, v.
Append name of ASCII file with the surface gradients (following a comma if a format is speci-
fied).
−C Find an approximate surface fit: Solve the linear system for the spline coefficients by SVD and
eliminate the contribution from all eigenvalues whose ratio to the largest eigenvalue is less than cut
[Default uses Gauss-Jordan elimination to solve the linear system and fit the data exactly].
Optionally, append /file to save the eigenvalue ratios to the specified file for further analysis.
Finally, if a negative cut is given then /file is required and execution will stop after saving the ei-
genvalues, i.e., no surface output is produced.
−D Sets the distance flag that determines how we calculate distances between data points. Select
mode 0 for Cartesian 1-D spline interpolation: −D 0 means (x) in user units, Cartesian distances,
Select mode 1-3 for Cartesian 2-D surface spline interpolation: −D 1 means (x,y) in user units,
Cartesian distances, −D 2 for (x,y) in degrees, flat Earth distances, and −D 3 for (x,y) in degrees,
spherical distances in km. Then, if ELLIPSOID is spherical, we compute great circle arcs, other-
wise geodesics. Option mode = 4 applies to spherical surface spline interpolation only: −D 4 for
(x,y) in degrees, use cosine of great circle (or geodesic) arcs. Select mode 5 for Cartesian 3-D sur-
face spline interpolation: −D 5 means (x,y,z) in user units, Cartesian distances.
−F Force pixel registration. [Default is gridline registration].
GMT 4.5.14 1 Nov 2015 1

−G Name of resulting output file. (1) If options −R, −I, and possibly −F are set we produce an
equidistant output table. This will be written to stdout unless −G is specified. Note: for 2-D grids
the −G option is required. (2) If option −T is selected then −G is required and the output file is a
2-D binary grid file. Applies to 2-D interpolation only. (3) If −N is selected then the output is an
ASCII (or binary; see −bo) table; if −G is not given then this table is written to standard output.
Ignored if −C or −C 0 is given.
skipped.
−I Specify equidistant sampling intervals, on for each dimension, separated by slashes.
−L Do not remove a linear (1-D) or planer (2-D) trend when −D selects mode 0-3 [For those Cartesian
cases a least-squares line or plane is modeled and removed, then restored after fitting a spline to
the residuals]. However, in mixed cases with both data values and gradients, or for spherical sur-
face data, only the mean data value is removed (and later and restored).
−N ASCII file with coordinates of desired output locations x in the first column(s). The resulting w
values are appended to each record and written to the file given in −G [or stdout if not specified];
see −bo for binary output instead. This option eliminates the need to specify options −R, −I, and
−F.
−Q Rather than evaluate the surface, take the directional derivative in the az azimuth and return the
magnitude of this derivative instead. For 3-D interpolation, specify the three components of the
desired vector direction (the vector will be normalized before use).
−R Specify the domain for an equidistant lattice where output predictions are required. Requires −I
and optionally −F.
1-D: Give xmin/xmax, the minimum and maximum x coordinates.
2-D: Give xmin/xmax/ymin/ymax, the minimum and maximum x and y coordinates. These may be
Cartesian or geographical. If geographical, then west, east, south, and north specify the Region of
interest, and you may specify them in decimal degrees or in [+-]dd:mm[:ss.xxx][W|E|S|N] format.
The two shorthands −Rg and −Rd stand for global domain (0/360 and -180/+180 in longitude
respectively, with -90/+90 in latitude).
3-D: Give xmin/xmax/ymin/ymax/zmin/zmax, the minimum and maximum x, y and z coordinates.
See the 2-D section if your horizontal coordinates are geographical; note the shorthands −Rg and
−Rd cannot be used if a 3-D domain is specified.
−S Select one of five different splines. The first two are used for 1-D, 2-D, or 3-D Cartesian splines
(see −D for discussion). Note that all tension values are expected to be normalized tension in the
range 0 < t < 1: (c) Minimum curvature spline [Sandwell, 1987], (t) Continuous curvature spline in
tension [Wessel and Bercovici, 1998]; append tension[/scale] with tension in the 0−1 range and
optionally supply a length scale [Default is the average grid spacing]. The next is a 2-D or 3-D
spline: (r) Regularized spline in tension [Mitasova and Mitas, 1993]; again, append tension and
optional scale. The last two are spherical surface splines and both imply −D 4 and geographic
data: (p) Minimum curvature spline [Parker, 1994], (q) Continuous curvature spline in tension
[Wessel and Becker, 2008]; append tension. The G(x; x’) for the last method is slower to compute;
by specifying −SQ you can speed up calculations by first pre-calculating G(x; x’) for a dense set
of x values (e.g., 100,001 nodes between -1 to +1) and store them in look-up tables. Optionally
append /N (an odd integer) to specify how many points in the spline to set [100001]
−T For 2-D interpolation only. Only evaluate the solution at the nodes in the maskgrid that are not
equal to NaN. This option eliminates the need to specify options −R, −I, and −F.
GMT 4.5.14 1 Nov 2015 2

append var1/var2/... to specify the variables to be read. [Default is 2-4 input columns (x,w); the
number depends on the chosen dimension].
output file.
1-D EXAMPLES
To resample the x,y Gaussian random data created by gmtmath and stored in 1D.txt, requesting output
every 0.1 step from 0 to 10, and using a minimum cubic spline, try
gmtmath −T 0/10/1 0 1 NRAND = 1D.txt

psxy −R0/10/-5/5 −JX 6i/3i −B 2f1/1 −Sc 0.1 −G black 1D.txt −K > 1D.ps
greenspline 1D.txt −R 0/10 −I 0.1 −Sc −V | psxy −R −J −O −W thin >> 1D.ps
To apply a spline in tension instead, using a tension of 0.7, try
psxy −R0/10/-5/5 −JX 6i/3i −B 2f1/1 −Sc 0.1 −G black 1D.txt −K > 1Dt.ps
greenspline 1D.txt −R 0/10 −I 0.1 −St 0.7 −V | psxy −R −J −O −W thin >> 1Dt.ps
2-D EXAMPLES
To make a uniform grid using the minimum curvature spline for the same Cartesian data set from Davis
(1986) that is used in the GMT Cookbook example 16, try
greenspline table_5.11 −R 0/6.5/-0.2/6.5 −I 0.1 −Sc −V −D 1 −G S1987.grd

psxy −R0/6.5/-0.2/6.5 −JX 6i −B 2f1 −Sc 0.1 −G black table_5.11 −K > 2D.ps
grdcontour −JX6i −B 2f1 −O −C 25 −A 50 S1987.grd >> 2D.ps
To use Cartesian splines in tension but only evaluate the solution where the input mask grid is not NaN, try
greenspline table_5.11 −T mask.grd −St 0.5 −V −D 1 −G WB1998.grd
To use Cartesian generalized splines in tension and return the magnitude of the surface slope in the NW
direction, try
greenspline table_5.11 −R 0/6.5/-0.2/6.5 −I 0.1 −Sr 0.95 −V −D 1 −Q-45 −G slopes.grd Finally, to use
Cartesian minimum curvature splines in recovering a surface where the input data is a single surface value
(pt.d) and the remaining constraints specify only the surface slope and direction (slopes.d), use
greenspline pt.d −R-3.2/3.2/-3.2/3.2 −I 0.1 −Sc −V −D 1 −A 1,slopes.d −G slopes.grd

3-D EXAMPLES
To create a uniform 3-D Cartesian grid table based on the data in table_5.23 in Davis (1986) that contains
x,y,z locations and a measure of uranium oxide concentrations (in percent), try
greenspline table_5.23 −R 5/40/-5/10/5/16 −I 0.25 −Sr 0.85 −V −D 5 −G 3D_UO2.txt

2-D SPHERICAL SURFACE EXAMPLES
To recreate Parker’s [1994] example on a global 1x1 degree grid, assuming the data are in file
mag_obs_1990.d, try
GMT 4.5.14 1 Nov 2015 3

greenspline −V −Rg −Sp −D 3 −I 1 −G P1994.grd mag_obs_1990.d
To do the same problem but applying tension and use pre-calculated Green functions, use
greenspline −V −Rg −SQ 0.85 −D 3 −I 1 −G WB2008.grd mag_obs_1990.d

CONSIDERATIONS
(1) For the Cartesian cases we use the free-space Green functions, hence no boundary conditions are
applied at the edges of the specified domain. For most applications this is fine as the region typically is
arbitrarily set to reflect the extent of your data. However, if your application requires particular boundary
conditions then you may consider using surface instead.
(2) In all cases, the solution is obtained by inverting a n x n double precision matrix for the Green function
coefficients, where n is the number of data constraints. Hence, your computer’s memory may place restric-
tions on how large data sets you can process with greenspline. Pre-processing your data with blockmean,
blockmedian, or blockmode is recommended to avoid aliasing and may also control the size of n. For
information, if n = 1024 then only 8 Mb memory is needed, but for n = 10240 we need 800 Mb. Note that
greenspline is fully 64-bit compliant if compiled as such.
(3) The inversion for coefficients can become numerically unstable when data neighbors are very close
compared to the overall span of the data. You can remedy this by pre-processing the data, e.g., by averag-
ing closely spaced neighbors. Alternatively, you can improve stability by using the SVD solution and dis-
card information associated with the smallest eigenvalues (see −C).
TENSION
Tension is generally used to suppress spurious oscillations caused by the minimum curvature requirement,
in particular when rapid gradient changes are present in the data. The proper amount of tension can only be
determined by experimentation. Generally, very smooth data (such as potential fields) do not require much,
if any tension, while rougher data (such as topography) will typically interpolate better with moderate ten-
sion. Make sure you try a range of values before choosing your final result. Note: the regularized spline in
tension is only stable for a finite range of scale values; you must experiment to find the valid range and a
useful setting. For more information on tension see the references below.
REFERENCES
Davis, J. C., 1986, Statistics and Data Analysis in Geology, 2nd Edition, 646 pp., Wiley, New York,
Mitasova, H., and L. Mitas, 1993, Interpolation by regularized spline with tension: I. Theory and imple-
mentation, Math. Geol., 25, 641−655.
Parker, R. L., 1994, Geophysical Inverse Theory, 386 pp., Princeton Univ. Press, Princeton, N.J.
Sandwell, D. T., 1987, Biharmonic spline interpolation of Geos-3 and Seasat altimeter data, Geophys. Res.
Lett., 14, 139−142.
Wessel, P., and D. Bercovici, 1998, Interpolation with splines in tension: a Green’s function approach,
Math. Geol., 30, 77−93.
Wessel, P., and J. M. Becker, 2008, Interpolation using a generalized Green’s function for a spherical sur-
face spline in tension, Geophys. J. Int, 174, 21−28.
Wessel, P., 2009, A general-purpose Green’s function interpolator, Computers & Geosciences, 35,
1247−1254, doi:10.1016/j.cageo.2008.08.012.
SEE ALSO
GMT (1), gmtmath(1), nearneighbor(1), psxy(1), surface(1), triangulate(1), xyz2grd(1)
GMT 4.5.14 1 Nov 2015 4

ISOGMT(1) Generic Mapping Tools ISOGMT(1)
NAME
isogmt − Run GMT command or script in isolation mode
SYNOPSIS
isogmt command
DESCRIPTION
isogmt runs a single GMT command or shell script in isolation mode. This means that the files .gmtcom-
mands4 and .gmtdefaults4 will be read from the usual locations (current directory, ˜/.gmt, or home direc-
tory), but changes will only be written in a temporary directory, which will be removed after execution. The
name of the temporary directory will be available to the command or script as the environment variable
GMT_TMPDIR.
EXAMPLES
Run the shell script script.gmt in isolation mode
isogmt sh script.gmt
SEE ALSO
GMT (1)
GMT 4.5.14 1 Nov 2015 1

MAKECPT(1) Generic Mapping Tools MAKECPT(1)
NAME
makecpt − Make GMT color palette tables
SYNOPSIS
makecpt [ −Ctable ] [ −D ] [ −I ] [ −M ] [ −N ] [ −Q[i|o] ] [ −Tz0/z1/dz | −Tztable ] [ −V ] [ −Z ]
DESCRIPTION
makecpt is a utility that will help you make color palette tables (cpt files). You define an equidistant set of
contour intervals or pass your own z-table, and create a new cpt file based on an existing master cpt file.
The resulting cpt file can be reversed relative to the master cpt, and can be made continuous or discrete.
The color palette includes three additional colors beyond the range of z-values. These are the background
color (B) assigned to values lower than the lowest z-value, the foreground color (F) assigned to values
higher than the highest z-value, and the NaN color (N) painted whereever values are undefined.
If the master cpt file includes B, F, and N entries, these will be copied into the new master file. If not, the
parameters COLOR_BACKGROUND, COLOR_FOREGROUND, and COLOR_NAN from the .gmt-
defaults4 file or the command line will be used. This default behavior can be overruled using the options
−D, −M or −N.
The color model (RGB, HSV or CMYK) of the palette created by makecpt will be the same as specified in
the header of the master cpt file. When there is no COLOR_MODEL entry in the master cpt file, the
COLOR_MODEL specified in the .gmtdefaults4 file or on the command line will be used.
OPTIONS
−C Selects the master color table table to use in the interpolation. Choose among the built-in tables
(type makecpt to see the list) or give the name of an existing cpt file [Default gives a rainbow cpt
file].
−D Select the colors for lowest and highest z-values in the output cpt file as the back- and foreground
colors that will be written to the cpt file [Default uses the colors specified in the master file, or
those defined by the parameters COLOR_BACKGROUND, COLOR_FOREGROUND, and
COLOR_NAN].
−I Reverses the sense of color progression in the master cpt file. Also exchanges the foreground and
background colors, including those specified by the parameters COLOR_BACKGROUND and
COLOR_FOREGROUND.
−M Overrule background, foreground, and NaN colors specified in the master cpt file with the values
of the parameters COLOR_BACKGROUND, COLOR_FOREGROUND, and COLOR_NAN
specified in the .gmtdefaults4 file or on the command line. When combined with −D, only
COLOR_NAN is considered.
−N Do not write out the background, foreground, and NaN-color fields [Default will write them].
−Q Selects a logarithmic interpolation scheme [Default is linear]. −Qi expects input z-values to be
log10(z), assigns colors, and writes out z [Default]. −Qo takes log10(z) first, assigns colors, and
writes out z.
−T Defines the range of the new cpt file by giving the lowest and highest z-value and the interval.
Alternatively, give the name of a ASCII file that has one z-value per record. If not given, the exist-
ing range in the master cpt file will be used intact.
−Z Creates a continuous cpt file [Default is discontinuous, i.e., constant colors for each interval].
EXAMPLES
To make a cpt file with z-values from -200 to 200, with discrete color changes every 25, and using a polar
blue-white-red colortable:
makecpt −Cpolar −T-200/200/25 > colors.cpt
To make an equidistant cpt file from z = -2 to 6, in steps of 1, using continuous default rainbow colors:
GMT 4.5.14 1 Nov 2015 1

MAKECPT(1) Generic Mapping Tools MAKECPT(1)
makecpt −T-2/6/1 −Z > rainbow.cpt
To make a GEBCO look-alike cpt file for bathymetry, run
makecpt −C gebco > my_gebco.cpt

BUGS
Since makecpt will also interpolate from any existing .cpt file you may have in your directory, you cannot
use one of the listed cpt names as an output filename; hence the my_gebco.cpt in the example.
SEE ALSO
GMT (1), grd2cpt(1)
GMT 4.5.14 1 Nov 2015 2

MAPPROJECT(1) Generic Mapping Tools MAPPROJECT(1)
NAME
mapproject − Forward and Inverse map transformation of 2-D coordinates
SYNOPSIS
mapproject infiles −Jparameters −Rwest/east/south/north[r] [ −Ab|B|f|F[lon0/lat0] ] [ −C[dx/dy] ] [
−Dc|i|m|p ] [ −E[datum] ] [ −F[k|m|n|i|c|p] ] [ −G[x0/y0][+|-][/unit] ] [ −H[i][nrec] ] [ −I ] [
−Lline.xy[/unit][+] ] [ −Q[d|e ] [ −S ] [ −T[h]from[/to] ] [ −V ] [ −:[i|o] ] [ −b[i|o][s|S|d|D[ncol]|c[var1/...]]
] [ −f[i|o]colinfo ] [ −g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] ] [ −m[i|o][flag] ]
DESCRIPTION
mapproject reads (longitude, latitude) positions from infiles [or standard input] and computes (x,y) coordi-
nates using the specified map projection and scales. Optionally, it can read (x,y) positions and compute
(longitude, latitude) values doing the inverse transformation. This can be used to transform linear (x,y)
points obtained by digitizing a map of known projection to geographical coordinates. May also calculate
distances along track, to a fixed point, or closest approach to a line. Finally, can be used to perform various
datum conversions. Additional data fields are permitted after the first 2 columns which must have (longi-
tude,latitude) or (x,y). See option −: on how to read (latitude,longitude) files.
infiles Data file(s) to be transformed. If not given, standard input is read.
−J Selects the map projection. The following character determines the projection. If the character is
upper case then the argument(s) supplied as scale(s) is interpreted to be the map width (or axis
lengths), else the scale argument(s) is the map scale (see its definition for each projection). UNIT
is cm, inch, or m, depending on the MEASURE_UNIT setting in .gmtdefaults4, but this can be
overridden on the command line by appending c, i, or m to the scale or width values. Append h,
+, or - to the given width if you instead want to set map height, the maximum dimension, or the
minimum dimension, respectively [Default is w for width].
In case the central meridian is an optional parameter and it is being omitted, then the center of the
longitude range given by the −R option is used. The default standard parallel is the equator.
The ellipsoid used in the map projections is user-definable by editing the .gmtdefaults4 file in your
home directory. 73 commonly used ellipsoids and spheroids are currently supported, and users
may also specify their own custum ellipsoid parameters [Default is WGS-84]. Several GMT
parameters can affect the projection: ELLIPSOID, INTERPOLANT, MAP_SCALE_FACTOR,
and MEASURE_UNIT; see the gmtdefaults man page for details.
Choose one of the following projections (The E or C after projection names stands for Equal-Area
and Conformal, respectively):
−Jclon0/lat0/scale or −JClon0/lat0/width (Cassini).
Give projection center lon0/lat0 and scale (1:xxxx or UNIT/degree).
−Jcyl_stere/[lon0/[lat0/]]scale or −JCyl_stere/[lon0/[lat0/]]width (Cylindrical Stereographic).
Give central meridian lon0 (optional), standard parallel lat0 (optional), and scale along
parallel (1:xxxx or UNIT/degree). The standard parallel is typically one of these (but can
be any value):
66.159467 - Miller’s modified Gall
55 - Kamenetskiy’s First
45 - Gall’s Stereographic
30 - Bolshoi Sovietskii Atlas Mira or Kamenetskiy’s Second
0 - Braun’s Cylindrical
−Jj[lon0/]scale or −JJ[lon0/]width (Miller Cylindrical Projection).
Give the central meridian lon0 (optional) and scale (1:xxxx or UNIT/degree).
−Jm[lon0/[lat0/]]scale or −JM[lon0/[lat0/]]width
parallel (1:xxxx or UNIT/degree).
GMT 4.5.14 1 Nov 2015 1

−Joparameters (Oblique Mercator [C]).

Typically used with −R<...>r, otherwise region is in oblique coordinates. Specify one of:
−Jo[a]lon0/lat0/azimuth/scale or −JO[a]lon0/lat0/azimuth/width
Set projection center lon0/lat0, azimuth of oblique equator, and scale.
−Jo[b]lon0/lat0/lon1/lat1/scale or −JO[b]lon0/lat0/lon1/lat1/scale
Set projection center lon0/lat0, another point on the oblique equator lon1/lat1,
and scale.
−Joclon0/lat0/lonp/latp/scale or −JOclon0/lat0/lonp/latp/scale
Set projection center lon0/lat0, pole of oblique projection lonp/latp, and scale.
Give scale along oblique equator (1:xxxx or UNIT/degree).
−Jq[lon0/[lat0/]]scale or −JQ[lon0/[lat0/]]width (Cylindrical Equidistant).
Give the central meridian lon0 (optional), standard parallel lat0 (optional), and scale
(1:xxxx or UNIT/degree). The standard parallel is typically one of these (but can be any
value):
61.7 - Grafarend and Niermann, minimum linear distortion
50.5 - Ronald Miller Equirectangular
43.5 - Ronald Miller, minimum continental distortion
42 - Grafarend and Niermann
37.5 - Ronald Miller, minimum overall distortion
0 - Plate Carree, Simple Cylindrical, Plain/Plane Chart
−Jtlon0/[lat0/]scale or −JTlon0/[lat0/]width
Give the central meridian lon0, central parallel lat0 (optional), and scale (1:xxxx or
UNIT/degree).
−Juzone/scale or −JUzone/width (UTM - Universal Transverse Mercator [C]).
Give the UTM zone (A,B,1-60[C-X],Y,Z)) and scale (1:xxxx or UNIT/degree).
Zones: If C-X not given, prepend - or + to enforce southern or northern hemisphere con-
ventions [northern if south > 0].
−Jy[lon0/[lat0/]]scale or −JY[lon0/[lat0/]]width (Cylindrical Equal-Area [E]).
value):
50 - Balthasart
45 - Gall-Peters
37.0666 - Caster
37.4 - Trystan Edwards
37.5 - Hobo-Dyer
30 - Behrman
0 - Lambert (default)
CONIC PROJECTIONS:
−Jblon0/lat0/lat1/lat2/scale or −JBlon0/lat0/lat1/lat2/width (Albers [E]).
Give projection center lon0/lat0, two standard parallels lat1/lat2, and scale (1:xxxx or
UNIT/degree).
−Jdlon0/lat0/lat1/lat2/scale or −JDlon0/lat0/lat1/lat2/width (Conic Equidistant)
UNIT/degree).
−Jllon0/lat0/lat1/lat2/scale or −JLlon0/lat0/lat1/lat2/width (Lambert [C])
Give origin lon0/lat0, two standard parallels lat1/lat2, and scale along these (1:xxxx or
UNIT/degree).
GMT 4.5.14 1 Nov 2015 2

−Jpoly/[lon0/[lat0/]]scale or −JPoly/[lon0/[lat0/]]width ((American) Polyconic).

Give the central meridian lon0 (optional), reference parallel lat0 (optional, default =
equator), and scale along central meridian (1:xxxx or UNIT/degree).
Except for polar aspects, −R w/e/s/n will be reset to −Rg. Use −R<...>r for smaller regions.
−Jalon0/lat0[/horizon]/scale or −JAlon0/lat0[/horizon]/width (Lambert [E]).
lon0/lat0 specifies the projection center. horizon specifies the max distance from projec-
tion center (in degrees, <= 180, default 90). Give scale as 1:xxxx or radius/lat, where
radius is distance in UNIT from origin to the oblique latitude lat.
−Jelon0/lat0[/horizon]/scale or −JElon0/lat0[/horizon]/width (Azimuthal Equidistant).
−Jflon0/lat0[/horizon]/scale or −JFlon0/lat0[/horizon]/width (Gnomonic).
tion center (in degrees, < 90, default 60). Give scale as 1:xxxx or radius/lat, where radius
is distance in UNIT from origin to the oblique latitude lat.
−Jglon0/lat0[/horizon]/scale or −JGlon0/lat0[/horizon]/width (Orthographic).
−Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale or −JGlon0/lat0/alti-
tude/azimuth/tilt/twist/Width/Height/width (General Perspective).
lon0/lat0 specifies the projection center. altitude is the height (in km) of the viewpoint
above local sea level. If altitude is less than 10, then it is the distance from the center of
the earth to the viewpoint in earth radii. If altitude has a suffix r then it is the radius from
the center of the earth in kilometers. azimuth is measured to the east of north of view. tilt
is the upward tilt of the plane of projection. If tilt is negative, then the viewpoint is cen-
tered on the horizon. Further, specify the clockwise twist, Width, and Height of the view-
point in degrees. Give scale as 1:xxxx or radius/lat, where radius is distance in UNIT
from origin to the oblique latitude lat.
−Jslon0/lat0[/horizon]/scale or −JSlon0/lat0[/horizon]/width (General Stereographic [C]).
tion center (in degrees, < 180, default 90). Give scale as 1:xxxx (true at pole) or
lat/1:xxxx (true at standard parallel lat) or radius/lat (radius in UNIT from origin to the
oblique latitude lat). Note if 1:xxxx is used then to specify horizon you must also specify
the lat as +-90 to avoid ambiguity.
−Jh[lon0/]scale or −JH[lon0/]width (Hammer [E]).
Give the central meridian lon0 (optional) and scale along equator (1:xxxx or
UNIT/degree).
−Ji[lon0/]scale or −JI[lon0/]width (Sinusoidal [E]).
UNIT/degree).
−Jkf[lon0/]scale or −JKf[lon0/]width (Eckert IV) [E]).
UNIT/degree).
GMT 4.5.14 1 Nov 2015 3

−Jk[s][lon0/]scale or −JK[s][lon0/]width (Eckert VI) [E]).

UNIT/degree).
−Jn[lon0/]scale or −JN[lon0/]width (Robinson).
UNIT/degree).
−Jr[lon0/]scale −JR[lon0/]width (Winkel Tripel).
UNIT/degree).
−Jv[lon0/]scale or −JV[lon0/]width (Van der Grinten).
UNIT/degree).
−Jw[lon0/]scale or −JW[lon0/]width (Mollweide [E]).
UNIT/degree).
−Jp[a]scale[/origin][r|z] or −JP[a]width[/origin][r|z] (Polar coordinates (theta,r))
Optionally insert a after −Jp [ or −JP] for azimuths CW from North instead of directions
CCW from East [Default]. Optionally append /origin in degrees to indicate an angular
offset [0]). Finally, append r if r is elevations in degrees (requires s >= 0 and n <= 90) or
z if you want to annotate depth rather than radius [Default]. Give scale in UNIT/r-unit.
−Jxx-scale[/y-scale] or −JXwidth[/height] (Linear, log, and power scaling)
Give x-scale (1:xxxx or UNIT/x-unit) and/or y-scale (1:xxxx or UNIT/y-unit); or specify
width and/or height in UNIT. y-scale=x-scale if not specified separately and using 1:xxxx
implies that x-unit and y-unit are in meters. Use negative scale(s) to reverse the direction
of an axis (e.g., to have y be positive down). Set height or width to 0 to have it recom-
puted based on the implied scale of the other axis. Optionally, append to x-scale, y-scale,
width or height one of the following:
d Data are geographical coordinates (in degrees).
l Take log10 of values before scaling.
ppower Raise values to power before scaling.
t Input coordinates are time relative to TIME_EPOCH.
T Input coordinates are absolute time.
Default axis lengths (see gmtdefaults) can be invoked using −JXh (for landscape); −JXv
(for portrait) will swap the x- and y-axis lengths. The default unit for this installation is
either cm or inch, as defined in the file share/gmt_setup.conf. However, you may change
this by editing your .gmtdefaults4 file(s).
GMT 4.5.14 1 Nov 2015 4

output and plot formats are customizable; see gmtdefaults). Special case for the UTM projection:
If −C is used and −R is not given then the region is set to coincide with the given UTM zone so as
to preserve the full ellipsoidal solution (See RESTRICTIONS for more information).
OPTIONS
infile(s) input file(s) with 2 or more columns. If no file(s) is given, mapproject will read the standard
input.
−A[f|b] −A calculates the (forward) azimuth from fixed point lon/lat to each data point. Use −Ab to get
back-azimuth from data points to fixed point. Upper case F or B will convert from geodetic to
geocentric latitudes and estimate azimuth of geodesics (assuming the current ellipsoid is not a
sphere). If no fixed point is given then we compute the azimuth (or back-azimuth) from the previ-
ous point.
−C Set center of projected coordinates to be at map projection center [Default is lower left corner].
Optionally, add offsets in the projected units to be added (or subtracted when −I is set) to (from)
the projected coordinates, such as false eastings and northings for particular projection zones [0/0].
The unit used for the offsets is the plot distance unit in effect (see MEASURE_UNIT) unless −F
is used, in which case the offsets are always in meters.
−D Temporarily override MEASURE_UNIT and use c (cm), i (inch), m (meter), or p (points)
instead. Cannot be used with −F.
−E Convert from geodetic (lon, lat, height) to Earth Centered Earth Fixed (ECEF) (x,y,z) coordinates
(add −I for the inverse conversion). Append datum ID (see −Qd) or give ellipsoid:dx,dy,dz where
ellipsoid may be an ellipsoid ID (see −Qe) or given as a[,inv_f], where a is the semi-major axis
and inv_f is the inverse flattening (0 if omitted). If datum is - or not given we assume WGS-84.
−F Force 1:1 scaling, i.e., output (or input, see −I) data are in actual projected meters. To specify
other units, append k (km), m (mile), n (nautical mile), i (inch), c (cm), or p (points). Without −F,
the output (or input, see −I) are in the units specified by MEASURE_UNIT (but see −D).
−G Calculate distances along track OR to the optional point set with −Gx0/y0. Append IT(unit), the
distance unit; choose among e (m), k (km), m (mile), n (nautical mile), d (spherical degree), c
(Cartesian distance using input coordinates) or C (Cartesian distance using projected coordinates).
The last unit requires −R and −J to be set. Upper case E, K, M, N, or D will use exact methods
for geodesic distances (Rudoe’s method for distances in length units and employing geocentric lat-
itudes in degree calculations, assuming the current ellipsoid is not spherical). With no fixed point
we calculate cumulate distances along track. To obtain incremental distance between successive
points, use −G-. To specify the 2nd point via two extra columns in the input file, choose −G+.
skipped.
−I Do the Inverse transformation, i.e., get (longitude,latitude) from (x,y) data.
−L Determine the shortest distance from the input data points to the line(s) given in the ASCII multi-
segment file line.xy. The distance and the coordinates of the nearest point will be appended to the
output as three new columns. Append the distance unit; choose among e (m), k (km), m (mile), n
(nautical mile), d (spherical degree), c (Cartesian distance using input coordinates) or C (Cartesian
distance using projected coordinates). The last unit requires −R and −J to be set. A spherical
approximation is used for geographic data. Finally, append + to report the line segment id and the
fractional point number instead of lon/lat of the nearest point.
−Q List all projection parameters. To only list datums, use −Qd. To only list ellipsoids, use −Qe.
−S Suppress points that fall outside the region.
GMT 4.5.14 1 Nov 2015 5

−T Coordinate conversions between datums from and to using the standard Molodensky transforma-
tion. Use −Th if 3rd input column has height above ellipsoid [Default assumes height = 0, i.e., on
the ellipsoid]. Specify datums using the datum ID (see −Qd) or give ellipsoid:dx,dy,dz where
ellipsoid may be an ellipsoid ID (see −Qe) or given as a[,inv_f], where a is the semi-major axis
and inv_f is the inverse flattening (0 if omitted). If datum is - or not given we assume WGS-84.
−T may be used in conjunction with −R −J to change the datum before coordinate projection (add
−I to apply the datum conversion after the inverse projection). Make sure that the ELLIPSOID
setting is correct for your case.
line break. Issue an additional −ga to indicate that all criteria must be met instead.
D_FORMAT setting.
EXAMPLES
To transform a file with (longitude,latitude) into (x,y) positions in cm on a Mercator grid for a given scale
of 0.5 cm per degree, run
mapproject lonlatfile −R 20/50/12/25 −Jm 0.5c > xyfile
GMT 4.5.14 1 Nov 2015 6

To transform several 2-column, binary, double precision files with (latitude,longitude) into (x,y) positions in
inch on a Transverse Mercator grid (central longitude 75W) for scale = 1:500000 and suppress those points
that would fall outside the map area, run
mapproject tracks.* −R-80/-70/20/40 −Jt-75/1:500000 −: −S −Di −bo −bi 2 > tmfile.b
To convert the geodetic coordinates (lon, lat, height) in the file old.dat from the NAD27 CONUS datum
(Datum ID 131 which uses the Clarke-1866 ellipsoid) to WGS 84, run
mapproject old.dat −Th 131 > new.dat
To compute the closest distance (in km) between each point in the input file quakes.dat and the line seg-
ments given in the multi-segment ASCII file coastline.xy, run
mapproject quakes.dat −L coastline.xy/k > quake_dist.dat

RESTRICTIONS
The rectangular input region set with −R will in general be mapped into a non-rectangular grid. Unless −C
is set, the leftmost point on this grid has xvalue = 0.0, and the lowermost point will have yvalue = 0.0.
Thus, before you digitize a map, run the extreme map coordinates through mapproject using the appropri-
ate scale and see what (x,y) values they are mapped onto. Use these values when setting up for digitizing
in order to have the inverse transformation work correctly, or alternatively, use awk to scale and shift the
(x,y) values before transforming.
For some projections, a spherical solution may be used despite the user having selected an ellipsoid. This
occurs when the users −R setting implies a region that exceeds the domain in which the ellipsoidal series
expansions are valid. These are the conditions: (1) Lambert Conformal Conic (−JL) and Albers Equal-
Area (−JB) will use the spherical solution when the map scale exceeds 1.0E7. (2) Transverse Mercator
(−JT) and UTM (−JU) will will use the spherical solution when either the west or east boundary given in
−R is more than 10 degrees from the central meridian, and (3) same for Cassini (−JC) but with a limit of
only 4 degrees.
ELLIPSOIDS AND SPHEROIDS
GMT will use ellipsoidal formulae if they are implemented and the user have selected an ellipsoid as the
reference shape (see ELLIPSOID in gmtdefaults). The user needs to be aware of a few potential pitfalls:
(1) For some projections, such as Transverse Mercator, Albers, and Lamberts conformal conic we use the
ellipsoidal expressions when the areas mapped are small, and switch to the spherical expressions (and sub-
stituting the appropriate auxiliary latitudes) for larger maps. The ellipsoidal formulae are used as follows:
(a) Transverse Mercator: When all points are within 10 degrees of central meridian, (b) Conic projections
when longitudinal range is less than 90 degrees, (c) Cassini projection when all points are within 4 degrees
of central meridian. (2) When you are trying to match some historical data (e.g., coordinates obtained with
a certain projection and a certain reference ellipsoid) you may find that GMT gives results that are slightly
different. One likely source of this mismatch is that older calculations often used less significant digits.
For instance, Snyder’s examples often use the Clarke 1866 ellipsoid (defined by him as having a flattening f
= 1/294.98). From f we get the eccentricity squared to be 0.00676862818 (this is what GMT uses), while
Snyder rounds off and uses 0.00676866. This difference can give discrepancies of several tens of cm. If
you need to reproduce coordinates projected with this slightly different eccentricity, you should specify
your own ellipsoid with the same parameters as Clarke 1866, but with f = 1/294.97861076. Also, be aware
that older data may be referenced to different datums, and unless you know which datum was used and con-
vert all data to a common datum you may experience mismatches of tens to hundreds of meters. (3) Finally,
be aware that MAP_SCALE_FACTOR have certain default values for some projections so you may have
to override the setting in order to match results produced with other settings.
SEE ALSO
gmtdefaults(1), GMT (1), project(1)
GMT 4.5.14 1 Nov 2015 7

REFERENCES
Bomford, G., 1952, Geodesy, Oxford U. Press.
Snyder, J. P., 1987, Map Projections − A Working Manual, U.S. Geological Survey Prof. Paper 1395.
Vanicek, P. and Krakiwsky, E, 1982, Geodesy − The Concepts, North-Holland Publ., ISBN: 0 444 86149 1.
GMT 4.5.14 1 Nov 2015 8

MINMAX(1) Generic Mapping Tools MINMAX(1)
NAME
minmax − Find extreme values in data tables
SYNOPSIS
minmax [ files] [ −C ] [ −EL|l|H|hcol ] [ −H[i][nrec] ] [ −I[p]dx[/dy[/dz...] ] [ −S[x][y] ] [ −Tdz[/col] ] [
−:[i|o] ] [ −bi[s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ] [ −m[i|o][flag] ]
DESCRIPTION
minmax reads its standard input [or from files] and finds the extreme values in each of the columns. It rec-
ognizes NaNs and will print warnings if the number of columns vary from record to record. As an option,
minmax will find the extent of the first n columns rounded up and down to the nearest multiple of the sup-
plied increments. By default, this output will be in the form −Rw/e/s/n which can be used directly in the
command line for other programs (hence only dx and dy are needed), or the output will be in column form
for as many columns as there are increments provided. A similar option (−T) will provide a
−Tzmin/zmax/dz string for makecpt.
xyzfile ASCII [or binary, see −b] file(s) holding a fixed number of data columns.
OPTIONS
−C Report the min/max values per column in separate columns [Default uses <min/max> format].
−E Returns the record whose column col contains the minimum (l) or maximum (h) value. Upper
case (L|H) works on absolute value of the data. In case of multiple matches, only the first record
is returned.
skipped.
−I Report the min/max of the first n columns to the nearest multiple of the provided increments (sepa-
rate the n increments by slashes), and output results in the form −Rw/e/s/n (unless −C is set). If
only one increment is given we also use it for the second column (for backwards compatibility).
To override this behaviour, use −Ipdx.
−S Add extra space for error bars. Useful together with −I option and when later plotting with psxy
−E. −Sx leaves space for horizontal error bars using the values in third (2) column. −Sy leaves
space for vertical error bars using the values in third (2) column. −S or −Sxy leaves space for both
error bars using the values in third and fourth (2 and 3) columns.
−T Report the min/max of the first (0’th) column to the nearest multiple of dz and output this in the
form −Tzmin/zmax/dz. To use another column, append /col.
Only works when −I is selected.
GMT 4.5.14 1 Nov 2015 1

MINMAX(1) Generic Mapping Tools MINMAX(1)

D_FORMAT setting.
EXAMPLES
To find the extreme values in the file ship_gravity.xygd:
minmax ship_gravity.xygd
Output should look like
ship_gravity.xygd: N = 6992 <326.125/334.684> <-28.0711/-8.6837> <-47.7/177.6> <0.6/3544.9>
To find the extreme values in the file track.xy to the nearest 5 units and use this region to draw a line using
psxy, run
psxy ‘minmax −I 5 track.xy‘ track.xy −Jx 1 −B 5 −P > track.ps
To find the min and max values for each of the first 4 columns, but rounded to integers, use
minmax junkfile −C −I 1/1/1/1

BUGS
The −I option does not yet work properly with time series data (e.g., −f 0T). Thus, such variable intervals
as months and years are not calculated. Instead, specify your interval in the same units as the current set-
ting of TIME_UNIT.
SEE ALSO
GMT (1)
GMT 4.5.14 1 Nov 2015 2

NEARNEIGHBOR(1) Generic Mapping Tools NEARNEIGHBOR(1)
NAME
nearneighbor − A "Nearest neighbor" gridding algorithm
SYNOPSIS
nearneighbor [ xyzfile(s) ] −Gout_grdfile −Ixinc[unit][=|+][/yinc[unit][=|+]] −Nsectors[/min_sectors]
−Rwest/east/south/north[r] −Ssearch_radius[m|c|k|K] [ −Eempty ] [ −F ] [ −H[i][nrec] ] [ −Lflag ] [ −V ] [
−W ] [ −:[i|o] ] [ −bi[s|S|d|D[ncol]|c[var1/...]] ] [ −fcolinfo ]
DESCRIPTION
nearneighbor reads arbitrarily located (x,y,z[,w]) triples [quadruplets] from standard input [or xyzfile(s)]
and uses a nearest neighbor algorithm to assign an average value to each node that have one or more points
within a radius centered on the node. The average value is computed as a weighted mean of the nearest
point from each sector inside the search radius. The weighting function used is w(r) = 1 / (1 + d ˆ 2), where
d = 3 * r / search_radius and r is distance from the node. This weight is modulated by the observation
points’ weights [if supplied].
xyzfile(s)
3 [or 4, see −W] column ASCII file(s) [or binary, see −b] holding (x,y,z[,w]) data values. If no file
is specified, nearneighbor will read from standard input.
−G Give the name of the output grid file.
−N The circular area centered on each node is divided into sectors sectors. Average values will only
be computed if there is at least one value inside each of at least min_sectors of these sectors for a
given node. Nodes that fail this test are assigned the value NaN (but see −E). If min_sectors is
omitted it is set to be at least 50% of sectors (i.e., rounded up to next integer). [Default is a quad-
rant search with 100% coverage, i.e., sectors = min_sectors = 4]. Note that only the nearest value
per sector enters into the averaging; the more distant points are ignored.
−S Sets the search_radius in same units as the grid spacing; append m to indicate minutes or c to indi-
cate seconds. Append k to indicate km (implies −R and −I are in degrees, and we will use a fast
GMT 4.5.14 1 Nov 2015 1

NEARNEIGHBOR(1) Generic Mapping Tools NEARNEIGHBOR(1)
flat Earth approximation to calculate distance). For more accuracy, use uppercase K if distances
should be calculated along geodesics. However, if the current ELLIPSOID is spherical then great
circle calculations are used.
OPTIONS
−E Set the value assigned to empty nodes [NaN].
is no boundary conditions].
−W Input data have a 4th column containing observation point weights. These are multiplied with the
geometrical weight factor to determine the actual weights used in the calculations.
append var1/var2/... to specify the variables to be read. [Default is 3 (or 4 if −W is set) columns].
EXAMPLES
To create a gridded data set from the file seaMARCII_bathy.lon_lat_z using a 0.5 min grid, a 5 km search
radius, using an octant search with 100% sector coverage, and set empty nodes to -9999:
nearneighbor seaMARCII_bathy.lon_lat_z −R 242/244/-22/-20 −I 0.5m −E-9999 −G bathymetry.grd −S

5k −N 8/8
To make a global grid file from the data in geoid.xyz using a 1 degree grid, a 200 km search radius, spheri-
cal distances, using an quadrant search, and set nodes to NaN only when fewer than two quadrants contain
at least one value:
nearneighbor geoid.xyz −R 0/360/-90/90 −I 1 −L g −G geoid.grd −S 200K −N 4

SEE ALSO
blockmean(1), blockmedian(1), blockmode(1), GMT (1), surface(1), triangulate(1)
GMT 4.5.14 1 Nov 2015 2

PROJECT(1) Generic Mapping Tools PROJECT(1)
NAME
project − project data along a line or great circle, generate a profile track, or translate coordinates.
SYNOPSIS
project [ infile ] −Ccx/cy [ −Aazimuth ] [ −Dd|g ] [ −Ebx/by ] [ −Fflags ] [ −Gdist ] [ −H[i][nrec] ] [
−L[w][l_min/l_max] ] [ −N ] [ −Q ] [ −S ] [ −Tpx/py ] [ −V ] [ −Ww_min/w_max ] [ −:[i|o] ] [
−b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ] [ −m[i|o][flag] ]
DESCRIPTION
project reads arbitrary (x, y[, z]) data from standard input [or infile ] and writes to standard output any com-
bination of (x, y, z, p, q, r, s), where (p, q) are the coordinates in the projection, (r, s) is the position in the (x,
y) coordinate system of the point on the profile (q = 0 path) closest to (x, y), and z is all remaining columns
in the input (beyond the required x and y columns). Alternatively, project may be used to generate (r, s, p)
triples at equal increments dist along a profile. In this case ( −G option), no input is read. Projections are
defined in any (but only) one of three ways: (Definition 1) By a Center −C and an Azimuth −A in degrees
clockwise from North. (Definition 2) By a Center −C and end point E of the projection path −E. (Defini-
tion 3) By a Center −C and a roTation pole position −T. To spherically project data along a great circle
path, an oblique coordinate system is created which has its equator along that path, and the zero meridian
through the Center. Then the oblique longitude (p) corresponds to the distance from the Center along the
great circle, and the oblique latitude (q) corresponds to the distance perpendicular to the great circle path.
When moving in the increasing (p) direction, (toward B or in the azimuth direction), the positive (q) direc-
tion is to your left. If a Pole has been specified, then the positive (q) direction is toward the pole.
To specify an oblique projection, use the −T option to set the Pole. Then the equator of the projection is
already determined and the −C option is used to locate the p = 0 meridian. The Center cx/cy will be taken
as a point through which the p = 0 meridian passes. If you do not care to choose a particular point, use the
South pole (ox = 0, oy = -90).
Data can be selectively windowed by using the −L and −W options. If −W is used, the projection Width is
set to use only points with w_min < q < w_max. If −L is set, then the Length is set to use only those points
with l_min < p < l_max. If the −E option has been used to define the projection, then −Lw may be selected
to window the length of the projection to exactly the span from O to B.
Flat Earth (Cartesian) coordinate transformations can also be made. Set −N and remember that azimuth is
clockwise from North (the y axis), NOT the usual cartesian theta, which is counterclockwise from the x
axis. azimuth = 90 - theta.
No assumptions are made regarding the units for x, y, r, s, p, q, dist, l_min, l_max, w_min, w_max. If −Q is
selected, map units are assumed and x, y, r, s must be in degrees and p, q, dist, l_min, l_max, w_min, w_max
will be in km.
Calculations of specific great-circle and geodesic distances or for back-azimuths or azimuths are better
done using mapproject.
project is CASE SENSITIVE. Use UPPER CASE for all one-letter designators which begin optional argu-
ments. Use lower case for the xyzpqrs letters in −flags.
−C cx/cy sets the origin of the projection, in Definition 1 or 2. If Definition 3 is used (−T), then cx/cy
are the coordinates of a point through which the oblique zero meridian (p = 0) should pass.
OPTIONS
infile name of ASCII (or binary, see −bi) file(s) with 2 or more columns holding (x,y,[z]) data values. If
no filenames are given, project will read from standard input. If the −G option is selected, no
input data are read.
−F Specify your desired output using any combination of xyzpqrs, in any order. Do not space
between the letters. Use lower case. The output will be ASCII (or binary, see −bo) columns of
values corresponding to xyzpqrs [Default]. If both input and output are using ASCII format then
the z data are treated as textstring(s). If the −G option is selected, the output will be rsp.
−A azimuth defines the azimuth of the projection (Definition 1).
−D Set the location of the Discontinuity in longitude (r coordinate). −Dd will place the discontinuity
at the Dateline, (-180 < r < 180); −Dg will place it at Greenwich, (0 < r < 360). Default usually
GMT 4.5.14 1 Nov 2015 1

falls at dateline due to atan2 calls.

−E bx/by defines the end point of the projection path (Definition 2).
−G dist Generate mode. No input is read. Create (r, s, p) output points every dist units of p. See −Q
option.
skipped.
−L Length controls. Project only those points whose p coordinate is within l_min < p < l_max. If −E
has been set, then you may use −Lw to stay within the distance from C to E.
−N Flat Earth. Make a Cartesian coordinate transformation in the plane. [Default uses spherical
trigonometry.]
−Q Map type units, i.e., project assumes x, y, r, s are in degrees while p, q, dist, l_min, l_max, w_min,
w_max are in km. If −Q is not set, then all these are assumed to be in the same units.
−S Sort the output into increasing p order. Useful when projecting random data into a sequential pro-
file.
−T px/py sets the position of the roTation pole of the projection. (Definition 3).
−W Width controls. Project only those points whose q coordinate is within w_min < q < w_max.
output file. [Default is given by −F or −G].
D_FORMAT setting.
EXAMPLES
To generate points every 10km along a great circle from 10N,50W to 30N,10W:
project −C-50/10 −E-10/30 −G 10 −Q > great_circle_points.xyp
GMT 4.5.14 1 Nov 2015 2

(Note that great_circle_points.xyp could now be used as input for grdtrack, etc. ).
To project the shiptrack gravity, magnetics, and bathymetry in c2610.xygmb along a great circle through an
origin at 30S, 30W, the great circle having an azimuth of N20W at the origin, keeping only the data from
NE of the profile and within +/- 500 km of the origin, run:
project c2610.xygmb −C-30/-30 −A-20 −W-10000/0 −L-500/500 −F pz −Q > c2610_projected.pgmb
(Note in this example that −W-10000/0 is used to admit any value with a large negative q coordinate. This
will take those points which are on our right as we walk along the great circle path, or to the NE in this
example.)
To make a Cartesian coordinate transformation of mydata.xy so that the new origin is at 5,3 and the new x
axis (p) makes an angle of 20 degrees with the old x axis, use:
project mydata.xy −C 5/3 −A 70 −F pq > mydata.pq
To take data in the file pacific.lonlat and transform it into oblique coordinates using a pole from the hotspot
reference frame and placing the oblique zero meridian (p = 0 line) through Tahiti, run:
project pacific.lonlat −T-75/68 −C-149:26/-17:37 −F pq > pacific.pq
Suppose that pacific_topo.grd is a grid file of bathymetry, and you want to make a file of flowlines in the
hotspot reference frame. If you run:
grd2xyz pacific_topo.grd | project −T-75/68 −C 0/-90 −F xyq | xyz2grd −Retc −Ietc −C flow.grd
then flow.grd is a file in the same area as pacific_topo.grd, but flow contains the latitudes about the pole of
the projection. You now can use grdcontour on flow.grd to draw lines of constant oblique latitude, which
are flow lines in the hotspot frame.
If you have an arbitrarily rotation pole px/py and you would like to draw an oblique small circle on a map,
you will first need to make a file with the oblique coordinates for the small circle (i.e., lon = 0−360, lat is
constant), then create a file with two records: the north pole (0/90) and the origin (0/0), and find what their
oblique coordinates are using your rotation pole. Now, use the projected North pole and origin coordinates
as the rotation pole and center, respectively, and project your file as in the pacific example above. This
gives coordinates for an oblique small circle.
SEE ALSO
fitcircle(1), GMT (1), mapproject(1), grdproject(1)
GMT 4.5.14 1 Nov 2015 3

PS2RASTER(1) Generic Mapping Tools PS2RASTER(1)
NAME
ps2raster − Converts one or several PostScript file(s) to other formats using GhostScript
SYNOPSIS
ps2raster psfile(s) [ −A[u|-] ] [ −Cgs_option ] [ −Doutdir ] [ −Eresolution ] [ −Gghost_path ] [ −Llistfile ]
[ −P ] [ −Q[g|t][1|2|4] ] [ −S ] [ −Tb|e|f|j|g|G|m|t ] [ −V ] [ −W[+g][+tdocname][+nlayername][+aalt-
mode[alt]][+lminLOD/maxLOD][+fminfade/maxfade][+uURL] ]
DESCRIPTION
ps2raster converts one or more PostScript files to other formats (BMP, EPS, JPEG, PDF, PNG, PPM,
TIFF) using GhostScript. Input file names are read from the command line or from a file that lists them.
The size of the resulting images is determined by the BoundingBox (or HiResBoundingBox, if present).
As an option, a tight (HiRes)BoundingBox may be computed first. As another option, it can compute ESRI
type world files used to reference, for instance, tif files and make them be recognized as geotiff.
psfiles Names of PostScript files to be converted. The output files will have the same name (unless −F is
used) but with the conventional extension name associated to the raster format (e.g., .jpg for the
jpeg format). Use −D to redirect the output to a different directory.
OPTIONS
−A Adjust the BoundingBox and HiResBoundingBox to the minimum required by the image content.
Append u to first remove any GMT-produced time-stamps. Use −A- to override any automatic
setting of −A by −W.
−C Specify a single, custom option that will be passed on to GhostScript as is. Repeat to add several
options [none].
−D Sets an alternative output directory (which must exist) [Default is the same directory as the PS
files]. Use −D. to place the output in the current directory instead.
−E Set raster resolution in dpi [default = 720 for PDF, 300 for others].
−F Force the output file name. By default output names are constructed using the input names as base,
which are appended with an appropriate extension. Use this option to provide a different name, but
without extension. Extension is still determined automatically.
−G Full path to your GhostScript executable. NOTE: For Unix systems this is generally not necessary.
Under Windows, ghostscript path is now fetch from the registry. If this fails you can still add the
GS path to system’s path or give the full path here. (e.g., −G c:\pro-
grams\gs\gs9.02\bin\gswin32c). WARNING: because of the poor decision of embedding the bits
on the gs exe name we cannot satisfy both the 32 and 64 bits ghostscript executable names. So in
case of ’get from registry’ failure the default name (when no −G is used) is the one of the 64 bits
version, or gswin32c
−L The listfile is an ASCII file with the names of the PostScript files to be converted.
−N This option is obsolete. Use −S to print the GhostScript command, if applicable. Use −Te to save
the intermediate EPS file.
−P Force Portrait mode. All Landscape mode plots will be rotated back so that they show unrotated in
Portrait mode. This is practical when converting to image formats or preparing EPS or PDF plots
for inclusion in documents.
−Q Set the anti-aliasing options for graphics or text. Append the size of the subsample box (1, 2, or 4)
[4]. Default is no anti-aliasing (same as bits = 1).
−S Print to standard output the GhostScript command after it has been executed.
−T Sets the output format, where b means BMP, e means EPS, f means PDF, j means JPEG, g means
PNG, G means transparent PNG (untouched regions are transparent), m means PPM, and t means
TIFF [default is JPEG]. For bjgt you can append - to get a grayscale image only. The EPS format
can be combined with any of the other formats. For example, −Tef creates both an EPS and a PDF
file.
GMT 4.5.14 1 Nov 2015 1

−W Write a ESRI type world file suitable to make (e.g) .tif files be recognized as geotiff by softwares
that know how to do it. Be aware, however, that different results are obtained depending on the
image contents and if the −B option has been used or not. The trouble with the −B option is that it
creates a frame and very likely its annotations. That introduces pixels outside the map data extent,
and therefore the map extents estimation will be wrong. To avoid this problem use
--BASEMAP_TYPE=inside option which plots all annotations and ticks inside the image and
therefore does not compromise the coordinate computations. Pay attention also to the cases when
the plot has any of the sides with whites only because than the algorithm will fail miserably as
those whites will be eaten by the GhostScript. In that case you really must use −B or use a slightly
off-white color.
Together with −V it prints on screen the gdal_translate (gdal_translate is a command line tool from
the GDAL package) command that reads the raster + world file and creates a true geotiff file. Use
−W+g to do a system call to gdal_translate and create a geoTIFF image right away. The output file
will have a .tiff extension.
The world file naming follows the convention of jamming a ’w’ in the file extension. So, if output
is tif −Tt the world file is a .tfw, for jpeg we have a .jgw and so on. This option automatically sets
−A −P.
Use −W+k to create a minimalist KML file that allows loading the image in GoogleEarth. Note
that for this option the image must be in geographical coordinates. If not, a warning is issued but
the KML file is created anyway. Several modifier options are available to customize the KML file
in the form of +opt strings. Append +ttitle to set the document title [GMT KML Document],
+nlayername to set the layer name, and +a/altmode[altitude] to select one of 5 altitude modes rec-
ognized by Google Earth that determines the altitude (in m) of the image: G clamped to the
ground, g append altitude relative to ground, a append absolute altitude, s append altitude relative
to seafloor, and S clamp it to the seafloor. Control visibility of the layer with the +lmin-
LOD/maxLOD and +fminfade/maxfade options. FInally, if you plan to leave the image itself on a
server and only distribute the KML, use +uURL to prepend the URL to the image reference. See
the KML documentation for further explanation (http://code.google.com/apis/kml/documenta-
tion/).
Further notes on the creation of georeferenced rasters. ps2raster can create a georeferenced raster
image with a world file OR uses GDAL to convert the GMT PostScript file to geotiff. GDAL uses
Proj.4 for it’s projection library. To provide with the information it needs to do the georeferencing,
GMT 4.5 embeds a comment near the start of the PostScript file defining the projection using
Proj.4 syntax. Users with pre-GMT v4.5 PostScript files, or even non-GMT ps files, can provide
the information ps2raster requires by manually editing a line into the PostScript file, prefixed with
%%PROJ.
For example the command pscoast −JM0/12c −R-10/-4/37/43 −W1 −Di −Bg30m
--BASEMAP_TYPE=inside > cara.ps
adds this comment line
%%PROJ: merc -10.0 -4.0 37.0 43.0 -1113194.908 -445277.963 4413389.889 5282821.824
+proj=merc +lon_0=0 +k=-1 +x_0=0 +y_0=0 +a=6378137.0 +b=6356752.314245
where ’merc’ is the keyword for the coordinate conversion; the 2 to 5th elements contain the map
limits, 6 to 9th the map limits in projected coordinates and the rest of the line has the regular proj4
string for this projection.
NOTES
The conversion to raster images (BMP, JPEG, PNG, PPM or TIFF) inherently results in loss of details that
are available in the original PostScript file. Choose a resolution that is large enough for the application that
the image will be used for. For web pages, smaller dpi values suffice, for Word documents and PowerPoint
presentations a higher dpi value is recommended. ps2raster uses the loss-less Flate compression technique
when creating JPEG, PNG and TIFF images.
EPS is a vector, not a raster format. Therefore, the -E option has no effect on the creation of EPS files.
Using the option −Te will remove PageSize commands from the PostScript file and will adjust the
GMT 4.5.14 1 Nov 2015 2

BoundingBox when the −A option is used. Note the original and required BoundingBox is limited to inte-
ger points, hence Adobe added the optional HiResBoundingBox to add more precision in sizing. The −A
option calculates both and writes both to the EPS file used in the rasterization (and output if −Te is set).
Although PDF is also a vector format, the −E option has an effect on the resolution of pattern fills and fonts
that are stored as bitmaps in the document. ps2raster therefore uses a larger default resolution when creat-
ing PDF files. −E also determines the resolution of the boundingbox values used to indicate the size of the
output PDF. In order to obtain high-quality PDF files, the /prepress options are in effect, allowing only loss-
less Flate compression of raster images embedded in the PostScript file.
Although ps2raster was developed as part of the GMT, it can be used to convert PostScript files created by
nearly any graphics program. However, −Au is GMT-specific.
See Appendix C of the GMT Technical Reference and Cookbook for more information on how
ps2raster is used to produce graphics that can be inserted into other documents (articles, presentations,
posters, etc.).
EXAMPLES
To convert the file psfile.ps to PNG using a tight BoundingBox and rotating it back to normal orientation in
case it was in Landscape mode:
ps2raster psfile.ps −A −P −Tg
To create a simple linear map with pscoast and convert it to tif with a .tfw the tight BoundingBox computa-
tion.
pscoast −JX12cd −R-10/-4/37/43 −W1 −Di −Bg30m −P −G200 --BASEMAP_TYPE=inside > cara.ps
ps2raster cara −Tt −W
To create a Mercator version of the above example and use GDAL to produce a true geotiff file.
pscoast −JM0/12c −R-10/-4/37/43 −W1 −Di −Bg30m −P −G200 --BASEMAP_TYPE=inside > cara.ps
gdalwarp -s_srs +proj=merc cara.tif carageo.tiff
To create a Polar Stereographic geotiff file of Patagonia
pscoast -JS-55/-60/15c -R-77/-55/-57.5/-48r -Di -Gred -P -Bg2 --BASEMAP_TYPE=inside > patagonia.ps
ps2raster patagonia.ps -Tt -W+g -V
To create a simple KMZ file for use in Google Earth, try
grdimage lonlatgrid.nc -Jx1 -Ccolors.cpt -P -B0g2 --BASEMAP_TYPE=inside > tile.ps
ps2raster tile.ps -Tg -W+k+t"my title"+l256/-1 -V
(These commands assume that GhostScript can be found in your system’s path.)
BINARY DATA
GMT programs can produce binary PostScript image data and this is determined by the default setting
PS_IMAGE_FORMAT. Because ps2raster needs to process the input files on a line-by-line basis you need
to make sure the image format is set to ascii and not bin.
GMT 4.5.14 1 Nov 2015 3

GHOSTSCRIPT OPTIONS
Most of the conversions done in ps2raster are handled by GhostScript. On most Unixes this program is
available as gs; for Windows there is a version called gswin32c. GhostScript accepts a rich selection of
command-line options that modify its behavior. Many of these are set indirectly by the options available
above. However, hard-core usage may require some users to add additional options to fine-tune the result.
Use −S to examine the actual command used, and add custom options via one or more instances of the −C
option. For instance, to turn on image interpolation for all images, improving image quality for scaled
images at the expense of speed, use −C-dDOINTERPOLATE. See www.ghostscript.com for complete doc-
umentation.
SEE ALSO
GMT (1), gs(1)
GMT 4.5.14 1 Nov 2015 4

PSBASEMAP(1) Generic Mapping Tools PSBASEMAP(1)
NAME
psbasemap − To plot PostScript basemaps
SYNOPSIS
psbasemap −B[p|s]parameters −Jparameters −Rwest/east/south/north[/zmin/zmax][r] [
−Eazim/elev[+wlon/lat[/z]][+vx0/y0] ] [ −Gfill ] [ −Jz|Zparameters ] [ −K ] [
−L[f][x]lon0/lat0[/slon]/slat/length[m|n|k][+llabel][+jjust][+ppen][+ffill][+u] ] ] [ −O ] [ −P ] [
−U[just/dx/dy/][c|label] ] [ −T[f|m][x]lon0/lat0/size[/info][:w,e,s,n:][+gint[/mint]] ] [ −V ] [ −X[a|c|r][x-
shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [ −Zzlevel ] [ −ccopies ]
DESCRIPTION
psbasemap creates PostScript code that will produce a basemap. Several map projections are available,
and the user may specify separate tickmark intervals for boundary annotation, ticking, and [optionally]
gridlines. A simple map scale or directional rose may also be plotted.
−B Sets map boundary annotation and tickmark intervals. The format of tickinfo is
[p|s]xinfo[/yinfo[/zinfo]][:."Title":][W|w][E|e][S|s][N|n][Z|z[+]]. The leading p [Default] or s
selects the primary or secondary annotation information. Each of the ?info segments are
textstrings of the form info[:"Axis label":][:="prefix":][:,"unit label":]. The info string is made up
of one or more concatenated 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
can be any of Y (year, plot with 4 digits), y (year, plot with 2 digits), O (month, plot using
PLOT_DATE_FORMAT), o (month, plot with 2 digits), U (ISO week, plot using
PLOT_DATE_FORMAT), u (ISO week, plot using 2 digits), r (Gregorian week, 7-day stride
from start of week TIME_WEEK_START), K (ISO weekday, plot name of day), D (date, plot
using PLOT_DATE_FORMAT), d (day, plot day of month 0-31 or year 1-366, via
PLOT_DATE_FORMAT), R (day, same as d, aligned with TIME_WEEK_START), H (hour,
plot using PLOT_CLOCK_FORMAT), h (hour, plot with 2 digits), M (minute, plot using
PLOT_CLOCK_FORMAT), m (minute, plot with 2 digits), C (second, plot using
PLOT_CLOCK_FORMAT), c (second, plot with 2 digits). Note for geographic axes m and c
instead mean arc minutes and arc seconds. All entities that are language-specific are under control
by TIME_LANGUAGE. To specify separate x and y ticks, separate the substrings that apply to
the x and y axes with a slash [/] (If a 3-D basemap is selected with −E and −Jz, a third substring
pertaining to the vertical axis may be appended.) For linear/log/power projections (−Jx|X): Labels
for each axis can be added by surrounding them with colons (:). If the first character in the label is
a period, then the label is used as plot title; if it is a comma (,) then the label is appended to each
annotation; if it is an equal sign (=) the the prefix is prepended to each annotation (start label/pre-
fix with - to avoid space between annotation and item); else it is the axis label. If the label consists
of more than one word, enclose the entire label in double quotes (e.g., :"my label":). If you need
to use a colon (:) as part of your label you must specify it using its octal code (\072).
By default, all 4 boundaries are plotted (referred to as W, E, S, N). To change the default, append
the code for only those axes you want (e.g., WS for standard lower-left x- and y-axis system).
Upper case (e.g., W) means draw axis/tickmarks AND annotate it, whereas lower case (e.g., w)
will only draw axis/tickmarks. (If a 3-D basemap is selected with −E and −Jz, append Z or z to
control the appearance of the vertical axis. Append + to draw the outline of the cube defined by
−R. Note that for 3-D views the title, if given, will be suppressed.)
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: (1) stride can be 1, 2, 3, or -n. Annotations
will then occur at 1, 1−2−5, or 1−2−3−4−...−9, respectively; for -n we annotate every n’t magni-
tude. This option can also be used for the frame and grid intervals. (2) An l is appended to the
tickinfo string. Then, log10 of the tick value is plotted at every integer log10 value. (3) A p is
appended to the tickinfo string. Then, annotations appear as 10 raised to log10 of the tick value.
For power axes: Annotations can be specified in one of two ways: (1) stride sets the regular
GMT 4.5.14 1 Nov 2015 1

annotation interval. (2) A p is appended to the tickinfo string. Then, the annotation interval is
expected to be in transformed units, but the annotation value will be plotted as untransformed
units. E.g., if stride = 1 and power = 0.5 (i.e., sqrt), then equidistant annotations labeled 1−4−9...
will appear.
These GMT parameters can affect the appearance of the map boundary: ANNOT_MIN_ANGLE,
ANNOT_MIN_SPACING, ANNOT_FONT_PRIMARY, ANNOT_FONT_SECONDARY,
ANNOT_FONT_SIZE_PRIMARY, ANNOT_FONT_SIZE_SECONDARY, ANNOT_OFF-
SET_PRIMARY, ANNOT_OFFSET_SECONDARY, BASEMAP_AXES,
BASEMAP_FRAME_RGB, BASEMAP_TYPE, PLOT_DEGREE_FORMAT,
FRAME_PEN, FRAME_WIDTH, GRID_CROSS_SIZE_PRIMARY, GRID_PEN_PRI-
MARY, GRID_CROSS_SIZE_SECONDARY, GRID_PEN_SECONDARY,
HEADER_FONT, HEADER_FONT_SIZE, LABEL_FONT, LABEL_FONT_SIZE,
LINE_STEP, OBLIQUE_ANNOTATION, PLOT_CLOCK_FORMAT, PLOT_DATE_FOR-
MAT, TIME_FORMAT_PRIMARY, TIME_FORMAT_SECONDARY, TIME_LAN-
GUAGE, TIME_WEEK_START, TICK_LENGTH, TICK_PEN, and Y_AXIS_TYPE; see
the gmtdefaults man page for details.
−J Selects the map projection. The following character determines the projection. If the character is
upper case then the argument(s) supplied as scale(s) is interpreted to be the map width (or axis
lengths), else the scale argument(s) is the map scale (see its definition for each projection). UNIT
is cm, inch, or m, depending on the MEASURE_UNIT setting in .gmtdefaults4, but this can be
overridden on the command line by appending c, i, or m to the scale or width values. Append h,
+, or - to the given width if you instead want to set map height, the maximum dimension, or the
minimum dimension, respectively [Default is w for width].
In case the central meridian is an optional parameter and it is being omitted, then the center of the
longitude range given by the −R option is used. The default standard parallel is the equator.
The ellipsoid used in the map projections is user-definable by editing the .gmtdefaults4 file in your
home directory. 73 commonly used ellipsoids and spheroids are currently supported, and users
may also specify their own custum ellipsoid parameters [Default is WGS-84]. Several GMT
parameters can affect the projection: ELLIPSOID, INTERPOLANT, MAP_SCALE_FACTOR,
and MEASURE_UNIT; see the gmtdefaults man page for details.
Choose one of the following projections (The E or C after projection names stands for Equal-Area
and Conformal, respectively):
−Jclon0/lat0/scale or −JClon0/lat0/width (Cassini).
Give projection center lon0/lat0 and scale (1:xxxx or UNIT/degree).
−Jcyl_stere/[lon0/[lat0/]]scale or −JCyl_stere/[lon0/[lat0/]]width (Cylindrical Stereographic).
parallel (1:xxxx or UNIT/degree). The standard parallel is typically one of these (but can
be any value):
66.159467 - Miller’s modified Gall
55 - Kamenetskiy’s First
45 - Gall’s Stereographic
30 - Bolshoi Sovietskii Atlas Mira or Kamenetskiy’s Second
0 - Braun’s Cylindrical
−Jj[lon0/]scale or −JJ[lon0/]width (Miller Cylindrical Projection).
Give the central meridian lon0 (optional) and scale (1:xxxx or UNIT/degree).
−Jm[lon0/[lat0/]]scale or −JM[lon0/[lat0/]]width
parallel (1:xxxx or UNIT/degree).
−Joparameters (Oblique Mercator [C]).
Typically used with −R<...>r, otherwise region is in oblique coordinates. Specify one of:
GMT 4.5.14 1 Nov 2015 2

−Jo[a]lon0/lat0/azimuth/scale or −JO[a]lon0/lat0/azimuth/width
Set projection center lon0/lat0, azimuth of oblique equator, and scale.
−Jo[b]lon0/lat0/lon1/lat1/scale or −JO[b]lon0/lat0/lon1/lat1/scale
Set projection center lon0/lat0, another point on the oblique equator lon1/lat1,
and scale.
−Joclon0/lat0/lonp/latp/scale or −JOclon0/lat0/lonp/latp/scale
Set projection center lon0/lat0, pole of oblique projection lonp/latp, and scale.
Give scale along oblique equator (1:xxxx or UNIT/degree).
−Jq[lon0/[lat0/]]scale or −JQ[lon0/[lat0/]]width (Cylindrical Equidistant).
value):
61.7 - Grafarend and Niermann, minimum linear distortion
50.5 - Ronald Miller Equirectangular
43.5 - Ronald Miller, minimum continental distortion
42 - Grafarend and Niermann
37.5 - Ronald Miller, minimum overall distortion
0 - Plate Carree, Simple Cylindrical, Plain/Plane Chart
−Jtlon0/[lat0/]scale or −JTlon0/[lat0/]width
Give the central meridian lon0, central parallel lat0 (optional), and scale (1:xxxx or
UNIT/degree).
−Juzone/scale or −JUzone/width (UTM - Universal Transverse Mercator [C]).
Give the UTM zone (A,B,1-60[C-X],Y,Z)) and scale (1:xxxx or UNIT/degree).
Zones: If C-X not given, prepend - or + to enforce southern or northern hemisphere con-
ventions [northern if south > 0].
−Jy[lon0/[lat0/]]scale or −JY[lon0/[lat0/]]width (Cylindrical Equal-Area [E]).
value):
50 - Balthasart
45 - Gall-Peters
37.0666 - Caster
37.4 - Trystan Edwards
37.5 - Hobo-Dyer
30 - Behrman
0 - Lambert (default)
CONIC PROJECTIONS:
−Jblon0/lat0/lat1/lat2/scale or −JBlon0/lat0/lat1/lat2/width (Albers [E]).
UNIT/degree).
−Jdlon0/lat0/lat1/lat2/scale or −JDlon0/lat0/lat1/lat2/width (Conic Equidistant)
UNIT/degree).
−Jllon0/lat0/lat1/lat2/scale or −JLlon0/lat0/lat1/lat2/width (Lambert [C])
Give origin lon0/lat0, two standard parallels lat1/lat2, and scale along these (1:xxxx or
UNIT/degree).
−Jpoly/[lon0/[lat0/]]scale or −JPoly/[lon0/[lat0/]]width ((American) Polyconic).
Give the central meridian lon0 (optional), reference parallel lat0 (optional, default =
equator), and scale along central meridian (1:xxxx or UNIT/degree).
GMT 4.5.14 1 Nov 2015 3

Except for polar aspects, −R w/e/s/n will be reset to −Rg. Use −R<...>r for smaller regions.
−Jalon0/lat0[/horizon]/scale or −JAlon0/lat0[/horizon]/width (Lambert [E]).
−Jelon0/lat0[/horizon]/scale or −JElon0/lat0[/horizon]/width (Azimuthal Equidistant).
−Jflon0/lat0[/horizon]/scale or −JFlon0/lat0[/horizon]/width (Gnomonic).
tion center (in degrees, < 90, default 60). Give scale as 1:xxxx or radius/lat, where radius
is distance in UNIT from origin to the oblique latitude lat.
−Jglon0/lat0[/horizon]/scale or −JGlon0/lat0[/horizon]/width (Orthographic).
−Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale or −JGlon0/lat0/alti-
tude/azimuth/tilt/twist/Width/Height/width (General Perspective).
lon0/lat0 specifies the projection center. altitude is the height (in km) of the viewpoint
above local sea level. If altitude is less than 10, then it is the distance from the center of
the earth to the viewpoint in earth radii. If altitude has a suffix r then it is the radius from
the center of the earth in kilometers. azimuth is measured to the east of north of view. tilt
is the upward tilt of the plane of projection. If tilt is negative, then the viewpoint is cen-
tered on the horizon. Further, specify the clockwise twist, Width, and Height of the view-
point in degrees. Give scale as 1:xxxx or radius/lat, where radius is distance in UNIT
from origin to the oblique latitude lat.
−Jslon0/lat0[/horizon]/scale or −JSlon0/lat0[/horizon]/width (General Stereographic [C]).
tion center (in degrees, < 180, default 90). Give scale as 1:xxxx (true at pole) or
lat/1:xxxx (true at standard parallel lat) or radius/lat (radius in UNIT from origin to the
oblique latitude lat). Note if 1:xxxx is used then to specify horizon you must also specify
the lat as +-90 to avoid ambiguity.
−Jh[lon0/]scale or −JH[lon0/]width (Hammer [E]).
UNIT/degree).
−Ji[lon0/]scale or −JI[lon0/]width (Sinusoidal [E]).
UNIT/degree).
−Jkf[lon0/]scale or −JKf[lon0/]width (Eckert IV) [E]).
UNIT/degree).
−Jk[s][lon0/]scale or −JK[s][lon0/]width (Eckert VI) [E]).
UNIT/degree).
GMT 4.5.14 1 Nov 2015 4

−Jn[lon0/]scale or −JN[lon0/]width (Robinson).

UNIT/degree).
−Jr[lon0/]scale −JR[lon0/]width (Winkel Tripel).
UNIT/degree).
−Jv[lon0/]scale or −JV[lon0/]width (Van der Grinten).
UNIT/degree).
−Jw[lon0/]scale or −JW[lon0/]width (Mollweide [E]).
UNIT/degree).
−Jp[a]scale[/origin][r|z] or −JP[a]width[/origin][r|z] (Polar coordinates (theta,r))
Optionally insert a after −Jp [ or −JP] for azimuths CW from North instead of directions
CCW from East [Default]. Optionally append /origin in degrees to indicate an angular
offset [0]). Finally, append r if r is elevations in degrees (requires s >= 0 and n <= 90) or
z if you want to annotate depth rather than radius [Default]. Give scale in UNIT/r-unit.
−Jxx-scale[/y-scale] or −JXwidth[/height] (Linear, log, and power scaling)
Give x-scale (1:xxxx or UNIT/x-unit) and/or y-scale (1:xxxx or UNIT/y-unit); or specify
width and/or height in UNIT. y-scale=x-scale if not specified separately and using 1:xxxx
implies that x-unit and y-unit are in meters. Use negative scale(s) to reverse the direction
of an axis (e.g., to have y be positive down). Set height or width to 0 to have it recom-
puted based on the implied scale of the other axis. Optionally, append to x-scale, y-scale,
width or height one of the following:
d Data are geographical coordinates (in degrees).
l Take log10 of values before scaling.
ppower Raise values to power before scaling.
t Input coordinates are time relative to TIME_EPOCH.
T Input coordinates are absolute time.
Default axis lengths (see gmtdefaults) can be invoked using −JXh (for landscape); −JXv
(for portrait) will swap the x- and y-axis lengths. The default unit for this installation is
either cm or inch, as defined in the file share/gmt_setup.conf. However, you may change
this by editing your .gmtdefaults4 file(s).
GMT 4.5.14 1 Nov 2015 5

OPTIONS
−G Select fill shade, color or pattern for the inside of the basemap [Default is no fill color]. (See
SPECIFYING FILL below).
−L Draws a simple map scale centered on lon0/lat0. Use −Lx to specify x/y position instead. Scale is
calculated at latitude slat (optionally supply longitude slon for oblique projections [Default is cen-
tral meridian]), length is in km [miles if m is appended; nautical miles if n is appended]. Use −Lf
to get a "fancy" scale [Default is plain]. Append +l to select the default label which equals the dis-
tance unit (km, miles, nautical miles) and is justified on top of the scale [t]. Change this by giving
your own label (append +llabel). Change label justification with +jjustification (choose among
l(eft), r(ight), t(op), and b(ottom)). Apply +u to append the unit to all distance annotations along
the scale. If you want to place a rectangle behind the scale, specify suitable +ppen and/or +ffill
parameters. (See SPECIFYING PENS and SPECIFYING FILL below).
−T Draws a simple map directional rose centered on lon0/lat0. Use −Tx to specify x/y position
instead. The size is the diameter of the rose, and optional label information can be specified to
override the default values of W, E, S, and N (Give :: to suppress all labels). The default [plain]
map rose only labels north. Use −Tf to get a "fancy" rose, and specify in info what you want
drawn. The default [1] draws the two principal E-W, N-S orientations, 2 adds the two intermediate
NW-SE and NE-SW orientations, while 3 adds the eight minor orientations WNW-ESE, NNW-
SSE, NNE-SSW, and ENE-WSW. For a magnetic compass rose, specify −Tm. If given, info must
be the two parameters dec/dlabel, where dec is the magnetic declination and dlabel is a label for
the magnetic compass needle (specify - to format a label from dec). Then, both directions to geo-
graphic and magnetic north are plotted [Default is geographic only]. If the north label is * then a
north star is plotted instead of the north label. Annotation and two levels of tick intervals for geo-
graphic and magnetic directions are 10/5/1 and 30/5/1 degrees, respectively; override these set-
tings by appending +gints[/mints]. Color and pen attributes are taken from COLOR_BACK-
GROUND and TICK_PEN, respectively, while label fonts and sizes follow the usual annotation,
label, and header font settings.
size.
GMT 4.5.14 1 Nov 2015 6

−Z For 3-D projections: Sets the z-level of the basemap [Default is at the bottom end of the z-axis].
SPECIFYING PENS
‘.’.
SPECIFYING FILL
SPECIFYING COLOR
EXAMPLES
The following section illustrates the use of the options by giving some examples for the available map pro-
jections. Note how scales may be given in several different ways depending on the projection. Also note
the use of upper case letters to specify map width instead of map scale.
NON-GEOGRAPHICAL PROJECTIONS
Linear x-y plot
To make a linear x/y frame with all axes, but with only left and bottom axes annotated, using xscale =
yscale = 1.0, ticking every 1 unit and annotating every 2, and using xlabel = "Distance" and ylabel = "No of
samples", use
psbasemap −R 0/9/0/5 −Jx 1 −Bf 1a2:Distance:/:"No of samples":WeSn > linear.ps

Log-log plot
To make a log-log frame with only the left and bottom axes, where the x-axis is 25 cm and annotated every
1-2-5 and the y-axis is 15 cm and annotated every power of 10 but has tickmarks every 0.1, run
psbasemap −R 1/10000/1e20/1e25 −JX 25cl/15cl −B 2:Wavelength:/a1pf3:Power:WS > loglog.ps

Power axes
To design an axis system to be used for a depth−sqrt(age) plot with depth positive down, ticked and anno-
tated every 500m, and ages annotated at 1 my, 4 my, 9 my etc, use
psbasemap −R 0/100/0/5000 −Jx 1p0.5/-0.001 −B 1p:"Crustal age":/500:Depth: > power.ps

Polar (theta,r) plot
For a base map for use with polar coordinates, where the radius from 0 to 1000 should correspond to 3 inch
and with gridlines and ticks every 30 degrees and 100 units, use
psbasemap −R 0/360/0/1000 −JP 6i −B 30p/100 > polar.ps

CYLINDRICAL MAP PROJECTIONS
Cassini
A 10 -cm-wide basemap using the Cassini projection may be obtained by
GMT 4.5.14 1 Nov 2015 7

psbasemap −R 20/50/20/35 −JC 35/28/10c −P −B 5g5:.Cassini: > cassini.ps

Mercator [conformal]
A Mercator map with scale 0.025 inch/degree along equator, and showing the length of 5000 km along the
equator (centered on 1/1 inch), may be plotted as
psbasemap −R 90/180/-50/50 −Jm 0.025i −B 30g30:.Mercator: −Lx 1i/1i/0/5000 > mercator.ps

Miller
A global Miller cylindrical map with scale 1:200,000,000 may be plotted as
psbasemap −Rg −Jj 180/1:200000000 −B 30g30:.Miller: > miller.ps

Oblique Mercator [conformal]
To create a page-size global oblique Mercator basemap for a pole at (90,30) with gridlines every 30
degrees, run
psbasemap −R 0/360/-70/70 −Joc 0/0/90/30/0.064cd −B 30g30:."Oblique Mercator": > oblmerc.ps

Transverse Mercator [conformal]
A regular Transverse Mercator basemap for some region may look like
psbasemap −R 69:30/71:45/-17/-15:15 −Jt 70/1:1000000 −B 15m:."Survey area": −P > transmerc.ps

Equidistant Cylindrical Projection
This projection only needs the central meridian and scale. A 25 cm wide global basemap centered on the
130E meridian is made by
psbasemap −R-50/310/-90/90 −JQ 130/25c −B 30g30:."Equidistant Cylindrical": > cyl_eqdist.ps

Universal Transverse Mercator [conformal]
To use this projection you must know the UTM zone number, which defines the central meridian. A UTM
basemap for Indo-China can be plotted as
psbasemap −R 95/5/108/20r −Ju46/1:10000000 −B 3g3:.UTM: > utm.ps

Cylindrical Equal-Area
First select which of the cylindrical equal-area projections you want by deciding on the standard parallel.
Here we will use 45 degrees which gives the Gall-Peters projection. A 9 inch wide global basemap cen-
tered on the Pacific is made by
psbasemap −Rg −JY 180/45/9i −B 30g30:.Gall-Peters: > gall-peters.ps

CONIC MAP PROJECTIONS
Albers [equal-area]
A basemap for middle Europe may be created by
psbasemap −R 0/90/25/55 −Jb 45/20/32/45/0.25c −B 10g10:."Albers Equal-area": > albers.ps

Lambert [conformal]
Another basemap for middle Europe may be created by
psbasemap −R 0/90/25/55 −Jl 45/20/32/45/0.1i −B 10g10:."Lambert Conformal Conic": > lambertc.ps

Equidistant
Yet another basemap of width 6 inch for middle Europe may be created by
psbasemap −R 0/90/25/55 −JD 45/20/32/45/6i −B 10g10:."Equidistant conic": > econic.ps
GMT 4.5.14 1 Nov 2015 8

Polyconic
A basemap for north America may be created by
psbasemap −R-180/-20/0/90 −JPoly/4i −B 30g10/10g10:."Polyconic": > polyconic.ps

AZIMUTHAL MAP PROJECTIONS
Lambert [equal-area]
A 15 -cm-wide global view of the world from the vantage point -80/-30 will give the following basemap:
psbasemap −Rg −JA-80/-30/15c −B 30g30/15g15:."Lambert Azimuthal": > lamberta.ps
Follow the instructions for stereographic projection if you want to impose rectangular boundaries on the
azimuthal equal-area map but substitute −Ja for −Js.
Equidistant
A 15 -cm-wide global map in which distances from the center (here 125/10) to any point is true can be
obtained by:
psbasemap −Rg −JE 125/10/15c −B 30g30/15g15:.Equidistant: > equi.ps

Gnomonic
A view of the world from the vantage point -100/40 out to a horizon of 60 degrees from the center can be
made using the Gnomonic projection:
psbasemap −Rg −JF-100/40/60/6i −B 30g30/15g15:.Gnomonic: > gnomonic.ps

Orthographic
A global perspective (from infinite distance) view of the world from the vantage point 125/10 will give the
following 6 -inch-wide basemap:
psbasemap −Rg −JG 125/10/6i −B 30g30/15g15:.Orthographic: > ortho.ps

General Perspective
The −JG option can be used in a more generalized form, specifying altitude above the surface, width and
height of the view point, and twist and tilt. A view from 160 km above -74/41.5 with a tilt of 55 and
azimuth of 210 degrees, and limiting the viewpoint to 30 degrees width and height will product a 6 -inch-
wide basemap:
psbasemap −Rg −JG-74/41.5/160/210/55/30/30/6i −B 5g1/5g1:."General Perspective": > genper.ps

Stereographic [conformal]
To make a polar stereographic projection basemap with radius = 12 cm to −60 degree latitude, with plot
title "Salinity measurements", using 5 degrees annotation/tick interval and 1 degree gridlines, run
psbasemap −R-45/45/-90/-60 −Js 0/-90/12c/-60 −B 5g5:."Salinity measurements": > stereo1.ps
To make a 12 -cm-wide stereographic basemap for Australia from an arbitrary view point (not the poles),
and use a rectangular boundary, we must give the pole for the new projection and use the −R option to indi-
cate the lower left and upper right corners (in lon/lat) that will define our rectangle. We choose a pole at
130/-30 and use 100/-45 and 160/-5 as our corners. The command becomes
psbasemap −R 100/-45/160/-5fP −JS 130/-30/12c −B 30g30/15g15:."General Stereographic View": >

stereo2.ps
MISCELLANEOUS MAP PROJECTIONS
Hammer [equal-area]
The Hammer projection is mostly used for global maps and thus the spherical form is used. To get a world
map centered on Greenwich at a scale of 1:200000000, use
GMT 4.5.14 1 Nov 2015 9

psbasemap −Rd −Jh 0/1:200000000 −B 30g30/15g15:.Hammer: > hammer.ps

Sinusoidal [equal-area]
To make a sinusoidal world map centered on Greenwich, with a scale along the equator of 0.02 inch/degree,
use
psbasemap −Rd −Ji 0/0.02i −B 30g30/15g15:.Sinusoidal: > sinus1.ps
To make an interrupted sinusoidal world map with breaks at 160W, 20W, and 60E, with a scale along the
equator of 0.02 inch/degree, run the following sequence of commands:
psbasemap −R-160/-20/-90/90 −Ji-90/0.02i −B 30g30/15g15Wesn −K > sinus_i.ps

psbasemap −R-20/60/-90/90 −Ji 20/0.02i −B 30g30/15g15wesn −O −K −X 2.8i >> sinus_i.ps
psbasemap −R 60/200/-90/90 −Ji 130/0.02i −B 30g30/15g15wEsn −O −X 1.6i >> sinus_i.ps
Eckert IV [equal-area]
Pseudo-cylindrical projection typically used for global maps only. Set the central longitude and scale, e.g.,
psbasemap −Rg −Jkf 180/0.064c −B 30g30/15g15:."Eckert IV": > eckert4.ps

Eckert VI [equal-area]
Another pseudo-cylindrical projection typically used for global maps only. Set the central longitude and
scale, e.g.,
psbasemap −Rg −Jks 180/0.064c −B 30g30/15g15:."Eckert VI": > eckert6.ps

Robinson
Projection designed to make global maps "look right". Set the central longitude and width, e.g.,
psbasemap −Rd −JN 0/8i −B 30g30/15g15:.Robinson: > robinson.ps

Winkel Tripel
Yet another projection typically used for global maps only. You can set the central longitude, e.g.,
psbasemap −R 90/450/-90/90 −JR 270/25c −B 30g30/15g15:."Winkel Tripel": > winkel.ps

Mollweide [equal-area]
The Mollweide projection is also mostly used for global maps and thus the spherical form is used. To get a
25 -cm-wide world map centered on the Dateline:
psbasemap −Rg −JW 180/25c −B 30g30/15g15:.Mollweide: > mollweide.ps

Van der Grinten
The Van der Grinten projection is also mostly used for global maps and thus the spherical form is used. To
get a 7 -inch-wide world map centered on the Dateline:
psbasemap −Rg −JV 180/7i −B 30g30/15g15:."Van der Grinten": > grinten.ps

RESTRICTIONS
For some projections, a spherical earth is implicitly assumed. A warning will notify the user if −V is set.
Also note that plot titles are not plotted if −E is given.
BUGS
The −B option is somewhat complicated to explain and comprehend. However, it is fairly simple for most
applications (see examples).
SEE ALSO
gmtcolors(5), gmtdefaults(1), GMT (1)
GMT 4.5.14 1 Nov 2015 10

PSBBOX.SH(1) Generic Mapping Tools PSBBOX.SH(1)
NAME
psbbox.sh − Replace BoundingBox line in PostScript files by "real" BoundingBox
SYNOPSIS
psbbox.sh file ...
DESCRIPTION
This program replaces the BoundingBox line in all PostScript files specified on the command line by a
BoundingBox determined by the bbox modules of Ghostscript.
KNOWN LIMITATIONS
Works only for single-page PostScript files. Other limitations are the limitations of the Ghostscript bbox
module.
EPS Ghostscript 7.07 occasionally produces no BoundingBox at all. Try using AFPL Ghostscript 8.00 or
later instead.
OBSOLETE
With the production of ps2raster, this script became obsolete.
SEE ALSO
GMT (1), ps2raster(1)
GMT 4.5.14 1 Nov 2015 1

PSCLIP(1) Generic Mapping Tools PSCLIP(1)
NAME
psclip − To set up polygonal clip paths
SYNOPSIS
psclip xyfiles −Jparameters −Rwest/east/south/north[r] [ −B[p|s]parameters ] [ −Eazim/elev ] [ −K ] [ −N ]
[ −O ] [ −P ] [ −T ] [ −U[just/dx/dy/][c|label] ] [ −V ] [ −X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [
−Zzlevel ] [ −ccopies] [ −:[i|o] ] [ −bi[s|S|d|D[ncol]|c[var1/...]] ] [ −fcolinfo ] [ −m[flag] ]
psclip −C [ −K ] [ −O ]
DESCRIPTION
psclip reads (x,y) file(s) [or standard input] and draws polygons that are activated as clipping paths. Sev-
eral files may be read to create complex paths consisting of several non-connecting segments. Only marks
that are subsequently drawn inside the clipping path will be shown. To determine what is inside or outside
the clipping path, psclip uses the even-odd rule. When a ray drawn from any point, regardless of direction,
crosses the clipping path segments an odd number of times, the point is inside the clipping path. If the
number is even, the point is outside. The −N option, reverses the sense of what is the inside and outside of
the paths by plotting a clipping path along the map boundary. After subsequent plotting, which will be
clipped against these paths, the clipping may be deactivated by running psclip a second time with the −C
option only.
xyfiles ASCII [or binary, see −b] file(s) with (x,y) values for clip polygons. If no files are given, the stan-
dard input is read.
−C Mark end of existing clip path. No input file or projection information are needed. However, you
must supply −Xa and −Ya settings if you are using absolute positioning.
CONIC PROJECTIONS:
GMT 4.5.14 1 Nov 2015 1



OPTIONS
details.
−E Sets the viewpoint’s azimuth and elevation [180/90].
skipped.
−N Invert the sense of what is inside and outside. For example, when using a single path, this means
that only points outside that path will be shown. Cannot be used together with −B.
GMT 4.5.14 1 Nov 2015 2


−T Rather than read any input files, simply turn on clipping for the current map region. Basically, −T
is a convenient way to run psclip with the arguments −N /dev/null (or, under Windows, −N NUL).
Cannot be used together with −B.
size.
−Z For 3-D projections: Sets the z-level of the polygons [Default is the bottom of the z-axis].
EXAMPLES
To make an overlay PostScript file that will set up a complex clip area to which subsequent plotting will be
confined, run:
psclip my_region.xy −R 0/40/0/40 −Jm 0.3i −O −K > clip_mask_on.ps
To deactivate the clipping in an existing plotfile, run:
psclip −C −O >> complex_plot.ps

BUGS
psclip cannot handle polygons that contain the south or north pole. For such polygons, you should split
them into two and make each explicitly contain the polar point. The two clip polygons will combine to give
the desired effect.
GMT 4.5.14 1 Nov 2015 3

SEE ALSO
GMT (1), grdmask(1), psbasemap(1), psmask(1)
GMT 4.5.14 1 Nov 2015 4

PSCOAST(1) Generic Mapping Tools PSCOAST(1)
NAME
pscoast − To plot land-masses, water-masses, coastlines, borders, and rivers
SYNOPSIS
pscoast −Jparameters −Rwest/east/south/north[r] [ −Amin_area[/min_level/max_level][+r|l][ppercent] ] [
−B[p|s]parameters ] [ −C[l|r/]fill ] [ −Dresolution[+] ] [ −Eazim/elev[+wlon/lat[/z]][+vx0/y0] ] [ −Gfill|c ] [
−Iriver[/pen] ] [ −Jz|Zparameters ] [ −K ] [ −L[f][x]lon0/lat0[/slon]/slat/length[m|n|k][+lla-
bel][+jjust][+ppen][+ffill][+u] ] ] [ −O ] [ −Nborder[/pen] ] [ −O ] [ −P ] [ −Q ] [ −Sfill|c ] [
−T[f|m][x]lon0/lat0/size[/info][:w,e,s,n:][+gint[/mint]] ] [ −U[just/dx/dy/][c|label] ] [ −V ] [ −W[level/]pen
] [ −X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [ −Zzlevel ] [ −ccopies ] [ −bo[s|S|d|D[ncol]|c[var1/...]] ] [
−m[flag] ]
DESCRIPTION
pscoast plots grayshaded, colored, or textured land-masses [or water-masses] on maps and [optionally]
draws coastlines, rivers, and political boundaries. Alternatively, it can (1) issue clip paths that will contain
all land or all water areas, or (2) dump the data to an ASCII table. The data files come in 5 different resolu-
tions: (f)ull, (h)igh, (i)ntermediate, (l)ow, and (c)rude. The full resolution files amount to more than 55 Mb
of data and provide great detail; for maps of larger geographical extent it is more economical to use one of
the other resolutions. If the user selects to paint the land-areas and does not specify fill of water-areas then
the latter will be transparent (i.e., earlier graphics drawn in those areas will not be overwritten). Likewise,
if the water-areas are painted and no land fill is set then the land-areas will be transparent. A map projec-
tion must be supplied. The PostScript code is written to standard output.
CONIC PROJECTIONS:
GMT 4.5.14 1 Nov 2015 1



−R west, east, south, and north specify the Region of interest, 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 w/e/s/n. The two shorthands −Rg and −Rd stand for global
domain (0/360 and -180/+180 in longitude respectively, with -90/+90 in latitude). Alternatively,
specify the name of an existing grid file and the −R settings (and grid spacing, if applicable) are
copied from the grid.
OPTIONS
for more details.
details.
−C Set the shade, color, or pattern for lakes and river-lakes [Default is the fill chosen for "wet" areas
(−S)]. Optionally, specify separate fills by prepending l/ for lakes and r/ for river-lakes, repeating
the −C option as needed. (See SPECIFYING FILL below).
−D Selects the resolution of the data set to use ((f)ull, (h)igh, (i)ntermediate, (l)ow, and (c)rude). The
resolution drops off by 80% between data sets [Default is l]. Append + to automatically select a
lower resolution should the one requested not be available [abort if not found].
−G Select filling or clipping of "dry" areas. Append the shade, color, or pattern (see SPECIFYING
FILL below); or use −Gc for clipping [Default is no fill].
GMT 4.5.14 1 Nov 2015 2

−I Draw rivers. Specify the type of rivers and [optionally] append pen attributes [Default pen: width
= 0.25p, color = black, texture = solid]. (See SPECIFYING PENS below).
Choose from the list of river types below. Repeat option −I as often as necessary.
1 = Permanent major rivers
2 = Additional major rivers
3 = Additional rivers
4 = Minor rivers
5 = Intermittent rivers - major
6 = Intermittent rivers - additional
7 = Intermittent rivers - minor
8 = Major canals
9 = Minor canals
10 = Irrigation canals
a = All rivers and canals (1-10)
r = All permanent rivers (1-4)
i = All intermittent rivers (5-7)
c = All canals (8-10)
−L Draws a simple map scale centered on lon0/lat0. Use −Lx to specify x/y position instead. Scale is
calculated at latitude slat (optionally supply longitude slon for oblique projections [Default is cen-
tral meridian]), length is in km [miles if m is appended; nautical miles if n is appended]. Use −Lf
to get a "fancy" scale [Default is plain]. Append +l to select the default label which equals the dis-
tance unit (km, miles, nautical miles) and is justified on top of the scale [t]. Change this by giving
your own label (append +llabel). Change label justification with +jjustification (choose among
l(eft), r(ight), t(op), and b(ottom)). Apply +u to append the unit to all distance annotations along
the scale. If you want to place a rectangle behind the scale, specify suitable +ppen and/or +ffill
parameters. (See SPECIFYING PENS and SPECIFYING FILL below).
−N Draw political boundaries. Specify the type of boundary and [optionally] append pen attributes
[Default pen: width = 0.25p, color = black, texture = solid]. (See SPECIFYING PENS below).
(See SPECIFYING PENS below).
Choose from the list of boundaries below. Repeat option −N as often as necessary.
1 = National boundaries
2 = State boundaries within the Americas
3 = Marine boundaries
a = All boundaries (1-3)
−Q Mark end of existing clip path. No projection information is needed. However, you must supply
−Xa and −Ya settings if you are using absolute positioning.
−S Select filling or clipping of "wet" areas. Append the shade, color, or pattern (see SPECIFYING
FILL below); or use −Sc for clipping [Default is no fill].
−T Draws a simple map directional rose centered on lon0/lat0. Use −Tx to specify x/y position
instead. The size is the diameter of the rose, and optional label information can be specified to
override the default values of W, E, S, and N (Give :: to suppress all labels). The default [plain]
map rose only labels north. Use −Tf to get a "fancy" rose, and specify in info what you want
drawn. The default [1] draws the two principal E-W, N-S orientations, 2 adds the two intermediate
NW-SE and NE-SW orientations, while 3 adds the eight minor orientations WNW-ESE, NNW-
SSE, NNE-SSW, and ENE-WSW. For a magnetic compass rose, specify −Tm. If given, info must
be the two parameters dec/dlabel, where dec is the magnetic declination and dlabel is a label for
the magnetic compass needle (specify - to format a label from dec). Then, both directions to
GMT 4.5.14 1 Nov 2015 3

geographic and magnetic north are plotted [Default is geographic only]. If the north label is * then
a north star is plotted instead of the north label. Annotation and two levels of tick intervals for
geographic and magnetic directions are 10/5/1 and 30/5/1 degrees, respectively; override these set-
tings by appending +gints[/mints]. Color and pen attributes are taken from COLOR_BACK-
GROUND and TICK_PEN, respectively, while label fonts and sizes follow the usual annotation,
label, and header font settings.
−W Draw shorelines [Default is no shorelines]. Append pen attributes [Defaults: width = 0.25p, color
= black, texture = solid] which apply to all four levels. To set the pen for each level differently,
prepend level/, where level is 1-4 and represent coastline, lakeshore, island-in-lake shore, and lake-
in-island-in-lake shore. Repeat −W as needed. When specific level pens are set, those not listed
will not be drawn [Default draws all levels; but see −A]. (See SPECIFYING PENS below).
size.
−Z For 3-D projections: Sets the z-level of the coastlines [Default is the bottom of the z-axis].
output file.
−m Dumps a single multisegment ASCII (or binary, see −bo) file to standard output. No plotting
occurs. Specify any combination of −W, −I, −N. Optionally, you may append the flag character
that is written at the start of each segment header [’>’].
SPECIFYING PENS
‘.’.
SPECIFYING FILL
SPECIFYING COLOR
GMT 4.5.14 1 Nov 2015 4

EXAMPLES
To plot a green Africa with white outline on blue background, with permanent major rivers in thick blue
pen, additional major rivers in thin blue pen, and national borders as dashed lines on a Mercator map at
scale 0.1 inch/degree, use
pscoast −R-30/30/-40/40 −Jm 0.1i −B 5 −I 1/1p,blue −I 2/0.25p,blue −N 1/0.25p,- −W 0.25p,white −G

green −S blue −P > africa.ps
To plot Iceland using the lava pattern (# 28) at 100 dots per inch, on a Mercator map at scale 1 cm/degree,
run
pscoast −R-30/-10/60/65 −Jm 1c −B 5 −Gp 100/28 > iceland.ps
To initiate a clip path for Africa so that the subsequent colorimage of gridded topography is only seen over
land, using a Mercator map at scale 0.1 inch/degree, use
pscoast −R-30/30/-40/40 −Jm 0.1i −B 5 −Gc −P −K > africa.ps

grdimage −Jm 0.1i etopo5.grd −C colors.cpt −O −K >> africa.ps
pscoast −Q −O >> africa.ps
pscoast will first look for coastline files in directory $GMT_SHAREDIR/coast If the desired file is not
found, it will look for the file $GMT_SHAREDIR/coastline.conf. This file may contain any number of
records that each holds the full pathname of an alternative directory. Comment lines (#) and blank lines are
allowed. The desired file is then sought for in the alternate directories.
GSHHS INFORMATION
BUGS
The options to fill (−C −G −S) may not always work if the Azimuthal equidistant projection is chosen
(−Je|E). If the antipole of the projection is in the oceans it will most likely work. If not, try to avoid using
projection center coordinates that are even multiples of the coastline bin size (1, 2, 5, 10, and 20 degrees for
f, h, i, l, c, respectively). This projection is not supported for clipping.
The political borders are for the most part 1970s-style but have been updated to reflect more recent border
rearrangements in Europe and elsewhere. Let us know if you find something out of date.
Some users of pscoast will not be satisfied with what they find for the Antarctic shoreline. In Antarctica,
the boundary between ice and ocean varies seasonally and inter-annually. There are some areas of perma-
nent sea ice. In addition to these time-varying ice-ocean boundaries, there are also ice grounding lines
where ice goes from floating on the sea to sitting on land, and lines delimiting areas of rock outcrop. For
consistency’s sake, we have used the World Vector Shoreline throughout the world in pscoast, as described
in the GMT Cookbook Appendix K. Users who need specific boundaries in Antarctica should get the
Antarctic Digital Database, prepared by the British Antarctic Survey, Scott Polar Research Institute, World
Conservation Monitoring Centre, under the auspices of the Scientific Committee on Antarctic Research.
This data base contains various kinds of limiting lines for Antarctica and is available on CD-ROM. It is
GMT 4.5.14 1 Nov 2015 5

published by the Scientific Committee on Antarctic Research, Scott Polar Research Institute, Lensfield
Road, Cambridge CB2 1ER, United Kingdom.
SEE ALSO
gmtcolors(5), gmtdefaults(1), GMT (1), grdlandmask(1), psbasemap(1)
GMT 4.5.14 1 Nov 2015 6

PSCONTOUR(1) Generic Mapping Tools PSCONTOUR(1)
NAME
pscontour − Contour xyz-data by direct triangulation [method]
SYNOPSIS
pscontour xyzfile −Ccptfile −Jparameters −Rwest/east/south/north[r] [ −A[-][labelinfo] ] [ −B[p|s]param-
eters ] [ −D[dumpfile] ] [ −Eazim/elev[+wlon/lat[/z]][+vx0/y0] ] [ −G[d|f|n|l|L|x|X]params ] [ −H[i][nrec] ]
[ −I ] [ −K ] [ −Lpen ] [ −N ] [ −O ] [ −P ] [ −S[p|t] ] [ −Tindexfile ] [ −U[just/dx/dy/][c|label] ] [ −V ] [
−W[+]pen ] [ −X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [ −ccopies ] [ −:[i|o] ] [
−b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −m[flag] ]
DESCRIPTION
pscontour reads an ASCII [or binary] xyz-file and produces a raw contour plot by triangulation. By
default, the optimal Delaunay triangulation is performed (using either Shewchuk’s [1996] or Watson’s
[1982] method as selected during GMT installation; type pscontour − to see which method is selected),
but the user may optionally provide a second file with network information, such as a triangular mesh used
for finite element modeling. In addition to contours, the area between contours may be painted according
to the color palette file.
xyzfile Raw ASCII (or binary, see −b) xyz data to be contoured.
−C name of the color palette file. Must have discrete colors if you want to paint the surface (−I).
Only contours that have annotation flags set will be annotated.
CONIC PROJECTIONS:

GMT 4.5.14 1 Nov 2015 1


OPTIONS
−A Give - to disable all annotations. The optional labelinfo controls the specifics of the label format-
ting and consists of a concatenated string made up of any of the following control arguments:
+aangle
+cdx[/dy]
quoted line setup.
+g[color]
GMT 4.5.14 1 Nov 2015 2

+kcolor
COLOR below).
+llabel Sets the constant label text.
+Lflag Sets the label text according to the specified flag:
+Lh Take the label from the current multisegment header (first scan for an embedded
−Llabel option, if not use the first word following the segment flag). For multi-
ple-word labels, enclose entire label in double quotes.
+Ld Take the Cartesian plot distances along the line as the label; append c|i|m|p as
the unit [Default is MEASURE_UNIT].
+LD Calculate actual map distances; append d|e|k|m|n as the unit [Default is
d(egrees), unless label placement was based on map distances along the lines in
which case we use the same unit specified for that algorithm]. Requires a map
projection to be used.
+Lf Use text after the 2nd column in the fixed label location file as the label.
Requires the fixed label location setting.
+Lx As +Lh but use the headers in the xfile.d instead. Requires the crossing file
option.
+ndx[/dy]
+p[pen]
below).
+rmin_rad
0].
no space between label value and the unit. [Default is no unit].
+=prefix
details.
−D Dump the (x,y,z) coordinates of each contour to separate files, one for each contour segment. The
files will be named dumpfile_cont_segment[_i].xyz, where cont is the contour value and segment is
a running segment number for each contour interval (for closed contours we append _i.) However,
when −m is used in conjunction with −D a single multisegment file is created instead.
GMT 4.5.14 1 Nov 2015 3

−G Controls the placement of labels along the contours. Choose among five controlling algorithms:
−Gddist[c|i|m|p] or −GDdist[d|e|k|m|n]
−Gfffile.d
Reads the ascii file ffile.d and places labels at locations in the file that matches locations
along the contours. Inexact matches and points outside the region are skipped.
−Gl|Lline1[,line2,...]
ments. Labels will be placed where these lines intersect the contours. The format of each
line specification is start_lon/start_lat/stop_lon/stop_lat. Both start_lon/start_lat and
stop_lon/stop_lat can be replaced by a 2-character key that uses the justification format
employed in pstext to indicate a point on the map, given as [LCR][BMT]. −GL will
interpret the point pairs as defining great circles [Default is straight line].
−Gn|Nn_label
Specifies the number of equidistant labels for contours line [1]. Upper case −GN starts
labeling exactly at the start of the line [Default centers them along the line]. −GN-1
places one justified label at start, while −GN+1 places one justified label at the end of
contours. Optionally, append /min_dist[c|i|m|p] to enforce that a minimum distance sepa-
ration between successive labels is enforced.
−Gx|Xxfile.d
Reads the multi-segment file xfile.d and places labels at the intersections between the con-
tours and the lines inxfile.d. −GX will resample the lines first along great-circle arcs.
skipped.
−I Color the triangles using the color palette table.
−L Draw the underlying triangular mesh using the specified pen attributes [Default is no mesh]. (See
SPECIFYING PENS below).
−N Do NOT clip contours or image at the boundaries [Default will clip to fit inside region −R].
−S Or −Sp: Skip all input xyz points that fall outside the region [Default uses all the data in the trian-
gulation]. Alternatively, use −St to skip triangles whose three vertices are all outside the region.
−T Give name of file with network information. Each record must contain triplets of node numbers
for a triangle [Default computes these using Delaunay triangulation (see triangulate)].
GMT 4.5.14 1 Nov 2015 4

−W Select contouring and set contour pen attributes. If the + flag is set then the contour lines are col-
ored according to the cpt file (see −C). (See SPECIFYING PENS below).
size.
append var1/var2/... to specify the variables to be read. [Default is 3 input columns]. Use 4-byte
integer triplets for node ids (−T).
output file. [Default is 3 output columns].
−m When used in conjunction with −D a single multisegment file is created, and each contour section
is preceded by a header record whose first column is flag followed by the contour level.
SPECIFYING PENS
‘.’.
SPECIFYING COLOR
EXAMPLES
To make a raw contour plot from the file topo.xyz and drawing the contours (pen = 0.5p) given in the color
palette file topo.cpt on a Lambert map at 0.5 inch/degree along the standard parallels 18 and 24, use
pscontour topo.xyz −R 320/330/20/30 −Jl 18/24/0.5i −C topo.cpt −W 0.5p > topo.ps
To create a color PostScript plot of the numerical temperature solution obtained on a triangular mesh whose
node coordinates and temperatures are stored in temp.xyz and mesh arrangement is given by the file
mesh.ijk, using the colors in temp.cpt, run
pscontour temp.xyz −R 0/150/0/100 −Jx 0.1 −C temp.cpt −G −W 0.25p > temp.ps
GMT 4.5.14 1 Nov 2015 5

BUGS
Sometimes there will appear to be thin lines of the wrong color in the image. This is a round-off problem
which may be remedied by using a higher value of DOTS_PR_INCH in the .gmtdefaults4 file.
SEE ALSO
GMT (1), gmtcolors(5), grdcontour(1), grdimage(1), nearneighbor(1), psbasemap(1), psscale(1), sur-
face(1), triangulate(1)
REFERENCES
Watson, D. F., 1982, Acord: Automatic contouring of raw data, Comp. & Geosci., 8, 97−101.
Shewchuk, J. R., 1996, Triangle: Engineering a 2D Quality Mesh Generator and Delaunay Triangulator,
First Workshop on Applied Computational Geometry (Philadelphia, PA), 124-133, ACM, May 1996.
www.cs.cmu.edu/˜quake/triangle.html
GMT 4.5.14 1 Nov 2015 6

PSHISTOGRAM(1) Generic Mapping Tools PSHISTOGRAM(1)
NAME
pshistogram − Bin data and plot histograms
SYNOPSIS
pshistogram file −Jx|Xparameters −Wbin_width [ −A ] [ −B[p|s]parameters ] [ −Ccptfile ] [ −Eaz-
imuth/elevation ] [ −F ] [ −Gfill ] [ −H[i][nrec] ] [ −Jz|Zparameters ] [ −I[o|O] ] [ −K ] [ −Lpen ] [ −O ] [
−P ] [ −Q ] [ −Rxmin/xmax/ymin/ymax[r] ] [ −S ] [ −Tcol ] [ −U[just/dx/dy/][c|label] ] [ −V ] [ −X[a|c|r][x-
shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [ −Ztype ] [ −ccopies ] [ −bi[s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ]
DESCRIPTION
pshistogram reads file [or standard input] and examines data column col to calculate histogram parameters
based on the bin-width provided. Using these parameters, scaling, and optional range parameters it will
generate PostScript code that plots a histogram. A cumulative histogram may also be specified.
file ASCII [or binary, see −b] datafile. If no file is given, pshistogram will read standard input.
−Jx xscale[/yscale] (Linear scale(s) in distance unit/data unit).
−W Sets the bin width used for histogram calculations.
OPTIONS
−A Plot the histogram horizontally from x = 0 [Default is vertically from y = 0].
details.
−C Give a color palette file. The mid x-value for each bar is used to look-up the bar color.
−E Sets the viewpoint’s azimuth and elevation (for perspective view) [180/90].
−F Center bin on each value. [Default is left edge].
−G Select filling of bars [Default is no fill]. (See SPECIFYING FILL below).
skipped.
−I Inquire about min/max x and y after binning. No plotting is done. Append o to output an ASCII
table of the resulting x,y data to stdout. Alternatively, append O to output all x,y bin data even
when y == 0.
−L Draw bar outline using the specified pen thickness. [Default is no outline]. (See SPECIFYING
PENS below).
−Q Draw a cumulative histogram.
GMT 4.5.14 1 Nov 2015 1

output and plot formats are customizable; see gmtdefaults). If not given, pshistogram will auto-
matically find reasonable values for the region.
−S Draws a stairs-step diagram which does not include the internal bars of the default histogram.
−T Specify which column to use for the histogram data. First column is 0 [0].
size.
−Z Choose between 6 types of histograms: 0 = counts [Default], 1 = frequency_percent, 2 = log (1.0 +
count), 3 = log (1.0 + frequency_percent), 4 = log10 (1.0 + count), 5 = log10 (1.0 + fre-
quency_percent).
SPECIFYING PENS
‘.’.
SPECIFYING FILL
SPECIFYING COLOR
GMT 4.5.14 1 Nov 2015 2

EXAMPLES
To draw a histogram of the data v3206.t containing seafloor depths, using a 250 meter bin width, center
bars, and draw bar outline, use:
pshistogram v3206.t −JX h −W 250 −F −L P0.5p −V > plot.ps
If you know the distribution of your data, you may explicitly specify range and scales. E.g., to plot a his-
togram of the y-values (2nd column) in the file errors.xy using a 1 meter bin width, plot from -10 to +10
meters @ 0.75 cm/m, annotate every 2 m and 100 counts, and use black bars, run:
pshistogram errors.xy −W 1 −R-10/10/0/0 −Jx 0.75c/0.01c −B 2:Error:/100:Counts: −G black −T 1 −V >

plot.ps
Since no y-range was specified, pshistogram will calculate ymax in even increments of 100.
BUGS
The −W option does not yet work properly with time series data (e.g., −f 0T). Thus, such variable intervals
as months and years are not calculated. Instead, specify your interval in the same units as the current set-
ting of TIME_UNIT.
SEE ALSO
GMT (1), gmtcolors(5), psbasemap(1), psrose(1), psxy(1)
GMT 4.5.14 1 Nov 2015 3

PSIMAGE(1) Generic Mapping Tools PSIMAGE(1)
NAME
psimage − To plot images (EPS files or Sun raster files) on maps
SYNOPSIS
psimage imagefile [ −W[-]width[/height] | −Edpi ] [ −Cxpos/ypos[/justify] ] [ −Fpen ] [ −G[b|f|t]color ] [
−I ] [ −K ] [ −M ] [ −Nnx[/ny] ] [ −O ] [ −P ] [ −U[just/dx/dy/][c|label] ] [ −V ] [ −X[a|c|r][x-shift[u]] ] [
−Y[a|c|r][y-shift[u]] ] [ −ccopies ]
DESCRIPTION
psimage reads an Encapsulated PostScript file or a 1, 8, 24, or 32-bit Sun raster file and plots it on a map.
The image can be scaled arbitrarily, and 1-bit raster images can be (1) inverted, i.e., black pixels (on)
becomes white (off) and vice versa, or (2) colorized, by assigning different foreground and background col-
ors, and (3) made transparent where one of back- or foreground is painted only. As an option, the user may
choose to convert colored raster images to grayscale using TV’s YIQ-transformation. In case of 8-, 24- or
32-bit Sun raster files, the user can select which color to be made transparent. The user may also choose to
replicate the image which, when preceded by appropriate clip paths, may allow larger custom-designed fill
patterns to be implemented (the −Gp mechanism offered in most GMT programs is limited to rasters
smaller than 146 by 146).
imagefile
This must be an Encapsulated PostScript (EPS) file or a Sun raster file. An EPS file must contain
an appropriate BoundingBox. A raster file can have a depth of 1, 8, 24, or 32 bits. Old-style, Stan-
dard, Run-length-encoded, and RGB Sun raster files are supported. Other raster formats can be
converted to Sun format via a variety of public-domain software (e.g., convert, xv).
−E Sets the dpi of the image in dots per inch, or use −W.
−W Sets the width (and height) of the image in plot coordinates (inches, cm, etc.). If height is not
given, the original aspect ratio of the image is maintained. If width is negative we use the absolute
value and interpolate image to the device resolution using the PostScript image operator. Alterna-
tively, use −E.
OPTIONS
−C Sets position of the image in plot coordinates (inches, cm, etc.) from the current origin of the plot.
By default, this defines the position of the lower left corner of the image, but this can be changed
by specifying justification [0/0/BL].
−F Draws a rectangular frame around the image with the given pen [no frame]. (See SPECIFYING
PENS below).
−M Convert color image to monochrome grayshades using the (television) YIQ-transformation.
−N Replicate the image nx times horizontally and ny times vertically. If ny is omitted, it will be iden-
tical to nx [Default is 1/1].
GMT 4.5.14 1 Nov 2015 1

PSIMAGE(1) Generic Mapping Tools PSIMAGE(1)
size.
These options are for 1-bit Sun raster images only. They have no effect when plotting other images or Post-
Script files.
−Gb Sets background color (replace white pixel) of 1-bit images. Use - for transparency (and set −Gf
to the desired color). (See SPECIFYING COLOR below).
−Gf Sets foreground color (replace black pixel) of 1-bit images. Use - for transparency (and set −Gb
to the desired color). (See SPECIFYING COLOR below).
−I Invert 1-bit image before plotting. This is what is done when you use −GP in other GMT pro-
grams.
These options are for 8-, 24-, and 32-bit Sun raster images only. They have no effect when plotting 1-bit
images or PostScript files.
−Gt Assigns the color that is to be made transparent. Sun Raster files do not support transparency, so
indicate here which color to be made transparent. (See SPECIFYING COLOR below).
SPECIFYING PENS
‘.’.
SPECIFYING COLOR
EXAMPLES
To plot the image contained in the 8-bit raster file scanned_face.ras, scaling it to 8 by 10 cm (thereby possi-
bly changing the aspect ratio), and making the white color transparent, use
psimage scanned_face.ras −W 8c/10c -Gtwhite > image.ps
To include an Encapsulated PostScript file tiger.eps with its upper right corner 2 inch to the right and 1 inch
up from the current location, and have its width scaled to 3 inches, while keeping the aspect ratio, use
psimage tiger.eps −C 2i/1i/TR −W 3i > image.ps
To replicate the 1-bit raster image template 1_bit.ras, colorize it (brown background and red foreground),
and setting each of 5 by 5 tiles to be 1 cm wide, use
psimage 1_bit.ras −Gb brown −Gf red −N 5 −W 1c > image.ps

SEE ALSO
GMT (1), gmtcolors(5), psxy(1)
GMT 4.5.14 1 Nov 2015 2

PSLEGEND(1) Generic Mapping Tools PSLEGEND(1)
NAME
pslegend − To plot a map legend
SYNOPSIS
pslegend textfile −D[x]lon/lat/width/height/just −Jparameters −Rwest/east/south/north[r] [ −B[p|s]param-
eters ] [ −Cdx/dy ] [ −F ] [ −Gfill ] [ −K ] [ −Lspacing ] [ −O ] [ −P ] [ −S[script] ] [
−U[just/dx/dy/][c|label] ] [ −V ] [ −X[a|c|r][x-shift[u]] ] [ −ccopies ] [ −Y[a|c|r][y-shift[u]] ]
DESCRIPTION
pslegend will make legends that can be overlaid on maps. It reads specific legend-related information from
an input file [or stdin]. Because all the elements of the legend can already be created with other tools
(psxy, pstext) we use those tools by creating a batch job of commands that are executed to make the final
PostScript overlay. Because of this process, the option exists to just output the script which can then be
fine-tuned manually. Unless otherwise noted, annotations will be made using the annotation font and size
in effect.
textfile This file contains instruction for the layout of items in the legend. Each legend item is described
by a unique record. All records begin with a unique character that is common to all records of the
same kind. The order of the legend items is implied by the order of the records. Ten different
record types are recognized, and the syntax for each of these records are presented below:
# comment Records starting with # and blank lines are skipped.

B cptname offset height [ optional arguments ]
The B record will plot a horizontal color bar, psscale-style in the middle, starting at offset
from the left edge, and of the given height. You may add any additional psscale options
from the list: −A −B −E −I −L −M −N −S and −Z.
C textcolor
The C record specifies the color with which the remaining text is to be printed. textcolor
can be in the form r/g/b, c/m/y/k, or a named color.
D offset pen
The D record results in a horizontal line with specified pen across the legend with one
quarter of the line spacing left blank above and below the line. Two gaps of offset units
are left blank between the horizontal line and the left and right frame sides. (See SPECI-
FYING PENS below).
G gap The G record specifies a vertical gap of the given length. In addition to the standard units
(i, c, p) you may use l for lines.
H fontsize|- font|- header
The H record plots a centered text string using the specified font parameters. Use - to
default to HEADER_FONT_SIZE and HEADER_FONT.
I imagefile width justification
Place an EPS or Sun raster image in the legend justified relative to the current point. The
image width determines the size of the image on the page.
L fontsize|- font|- justification label
The L record plots a (L)eft, (C)entered, or (R)ight-justified text string within a column
using the specified font parameters. Use - to default to LABEL_FONT_SIZE and
LABEL_FONT.
M slon|- slat length f|p [ −Rw/e/s/n −Jparam ]
Place a map scale in the legend. Specify slon slat, the point on the map where the scale
applies (slon is only meaningful for certain oblique projections. If not needed, you must
specify - instead), length, the length of the scale in km (append m or n for miles or nauti-
cal miles), and f or p for fancy or plain scale. If the −R −J supplied to pslegend is differ-
ent than the projection needed for the scale, supply the optional −R −J settings as well.
Append +l to the length to select the default label which equals the distance unit (km,
GMT 4.5.14 1 Nov 2015 1

miles, nautical miles) and is justified on top of the scale [t]. Change this by giving your
own label (append +llabel). Change label justification with +jjustification (choose
among l(eft), r(ight), t(op), and b(ottom)). Apply +u to append the unit to all distance
annotations along the scale. If you want to place a rectangle behind the scale, specify
suitable +ppen and/or +ffill parameters. All these +modifiers are appended to length to
make a single string. (See SPECIFYING PENS and SPECIFYING FILL below).
N ncolumns
Change the number of columns in the legend [1]. This only affects the printing of sym-
bols (S) and labels (L).
S dx1 symbol size fill pen [ dx2 text ]
Plots the selected symbol with specified size, fill, and outline (see psxy). The symbol is
centered at dx1 from the left margin of the column, with the optional explanatory text
starting dx2 from the margin, printed with fontsize ANNOT_FONT_SIZE_PRIMARY
and font ANNOT_FONT_PRIMARY. Use - if no fill or outline (pen) is required.
When plotting just a symbol, without text, dx2 and text can be omitted. Two psxy sym-
bols require special attention: front (f) and vector (v). You must prepend the length of the
desired item to the rest of the symbol argument; this will be used internally to set the cor-
rect fault or vector length and will be stripped before passing the arguments to psxy.
T paragraph-text
One or more of these T records with paragraph-text printed with fontsize
ANNOT_FONT_SIZE_PRIMARY and font ANNOT_FONT_PRIMARY (aligned
and wrapped). To specify special positioning and typesetting arrangements, or to enter a
paragraph break, use the optional > record.
V offset pen
The V record draws a vertical line between columns (if more than one) using the selected
pen (See SPECIFYING PENS below). offset is analogous to the offset for the D records
but in the vertical direction.
> paragraph-mode-header-for-pstext
Start a new text paragraph by specifying all the parameters needed (see pstext −m
description). Note that pslegend knows what all those values should be, so normally you
can leave the entire record (after >) blank or leave it out all together. If you need to set at
least one of the parameters directly, you must specify all and set the ones you want to
leave at their default value to -.
−D Positions the legend and specifies its size. The just is a 2-char justification string (see pstext) that
relates the given position to a point on the rectangular legend box. If you want to specify the posi-
tion in map plot units (i.e., inches or cm), use −Dx.
GMT 4.5.14 1 Nov 2015 2


CONIC PROJECTIONS:


OPTIONS
GMT 4.5.14 1 Nov 2015 3

details.
−C Sets the clearance between the legend frame and the internal items [0.15c/0.15c (or 0.05i/0.05i)].
−F Draws a border around the legend using FRAME_PEN.
−G Select fill shade, color or pattern of the legend box [Default is no fill]. (See SPECIFYING FILL
below).
−L Sets the linespacing factor in units of the current annotation font size [1.1].
−S Instead of writing the PostScript plot [Default], output the GMT script used to make the legend to
standard output, or optionally to the file script.
size.
SPECIFYING PENS
‘.’.
SPECIFYING FILL
SPECIFYING COLOR
EXAMPLES
To add an example of a legend to a Mercator plot (map.ps) with the given specifications, use
GMT 4.5.14 1 Nov 2015 4

pslegend −R-10/10/-10/10 −JM 6i −G azure1 −Dx 0.5i/0.5i/5i/3.3i/BL −C 0.1i/0.1i −L 1.2 −F −B 5f1 <<
EOF >> map.ps
G -0.1i
H 24 Times-Roman My Map Legend
D 0.2i 1p
N2
V 0 1p
S 0.1i c 0.15i p300/12 0.25p 0.3i This circle is hachured
S 0.1i e 0.15i 255/255/0 0.25p 0.3i This ellipse is yellow
S 0.1i w 0.15i 0/255/0 0.25p 0.3i This wedge is green
S 0.1i f 0.25i/-1/0.075ilb 0/0/255 0.25p 0.3i This is a fault
S 0.1i - 0.15i - 0.25tap 0.3i A contour
S 0.1i v 0.25i/0.02i/0.06i/0.05i 255/0/255 0.25p 0.3i This is a vector
S 0.1i i 0.15i 0/255/255 0.25p 0.3i This triangle is boring
V 0 1p
D 0.2i 1p
N1
M 5 5 600+u f
G 0.05i
I SOEST_logo.ras 3i CT
G 0.05i
B colors.cpt 0.2i 0.2i
G 0.05i L 9 4 R Smith et al., @%5%J. Geophys. Res., 99@%%, 2000
G 0.1i
T Let us just try some simple text that can go on a few lines.
T There is no easy way to predetermine how many lines will be required,
T so we may have to adjust the box height to get the right size box.
EOF
WINDOWS REMARKS
Note that under Windows, the percent sign (%) is a variable indicator (like $ under Unix). To indicate a
plain percentage sign in a batch script you need to repeat it (%%); hence the font switching mechanism
(@%font% and @%%) may require twice the number of percent signs. This only applies to text inside a
script or that otherwise is processed by DOS. Data files that are opened and read by pslegend do not need
such duplication.
SEE ALSO
GMT (1), gmtcolors(5), gmtdefaults(1), psbasemap(1), pstext(1), psxy(1)
GMT 4.5.14 1 Nov 2015 5

PSLIB(3) Generic Mapping Tools PSLIB(3)
NAME
pslib 4.3 − A PostScript based plotting library
DESCRIPTION
pslib was created to make the generation of PostScript page description code easier. It is a library that con-
tains a series of tools that can be used to create plots. The resulting PostScript code is ASCII text and can
be edited using any text editor. Thus, it is fairly easy to modify a plot file even after it has been created,
e.g., to change text strings, set new gray shades or colors, experiment with various pen widths, etc. pslib is
written in C but now includes FORTRAN bindings (thanks to John Goff, WHOI) and can therefore be
called from both C and FORTRAN programs. To use this library, you must link your plotting program with
pslib.a. pslib is the core of the GMT graphics programs. pslib output conforms to the Adobe Encapsu-
lated PostScript File Specification Version 3.0 (EPSL), and may be used as EPS files and inserted into, say,
a Word document on a Mac. See Appendix F in the Technical Reference for detailed instructions.
Before any pslib calls can be issued, the plotting system must be initialized. This is done by calling
ps_plotinit (or ps_plotinit_hires), which defines macros, sets up the plot-coordinate system, scales, and
[optionally] opens a file where all the PostScript code will be written. Normally, the plot code is written to
stdout. The measure unit for sizes and positions can be set to be centimeter (c), inch (i), or meter (m).
When all plotting is done, you must terminate the plotting system by calling ps_plotend.
pslib uses the direct color model where red, green, and blue are given separately, each must be in the range
from 0-255. If red < 0 then no fill operation takes place. Most plot-items can be plotted with or without
outlines. If outline is desired (i.e., set to 1), it will be drawn using the current linewidth and pattern. pslib
uses highly optimized macro substitutions and scales the coordinates depending on the resolution of the
hardcopy device so that the output file is kept as compact as possible.
A wide variety of output devices that support PostScript exist, including laserwriters (color or mono-
chrome) and workstations running PostScript based window systems like Sun’s OpenWindows. xnews
(part of OpenWindows) or ghostscript (public domain) can be used to create rasterfiles at a user-defined res-
olution (DPI), making it possible to render PostScript on a Versatec and other non-PostScript raster devices.
Regular Sun rasterfiles created under NeWS from PostScript files can be sent to a variety of color hardcopy
units. Check the devices available on your network.
The pslib is now fully 64-bit compliant. However, only a few function parameters are affected by this
(such as the number of point in an array which can now be a 64-bit integer). These few parameters are here
given the type long to distinguish them from int. Note that under standard 32-bit compilation they are
equivalent. Users of this library under 64-bit mode must make sure they pass proper long variables (under
Unix flavors) or __int64 under Windows 64.
FUNCTION CALLS
The following is a list of available functions and a short description of what they do and what parameters
they expect. All floating point variables are expected to be double (i.e., 8 bytes), whereas all integers are
assumed to be 4 bytes long. All plotting functions are declared as functions returning an int. Currently, the
return value is undefined.
void ps_arc (x, y, radius, angle1, angle2, status)

double x, y, radius, angle1, angle2;
int status;
Draws a circular arc centered on (x,y) from angle angle1 to angle2. Angles must be given in
decimal degrees. If angle1 > angle2, a negative arc is drawn. status is a value from 0 through
3. 1 means set new anchor point, 2 means stroke the circle, 3 means both, 0 means none of the
above.
void ps_axis (xpos, ypos, length, startval, stopval, tickval, label, annotpointsize, side)
double xpos, ypos, length, startval, stopval, tickval;
double annotpointsize, side;
char *label;
Plots an axis with tickmarks, annotation, and label. xpos, ypos, and length are in inches (or cm
or meters), annotpointsize in points (72 points = 1 inch), else data units are used. side can be 0,
GMT 4.5.14 1 Nov 2015 1

1, 2, or 3, which selects lower x-axis, right y-axis, upper x-axis, or left y-axis, respectively.
labelpointsize = 1.5 * annotpointsize. A negative tickval will reverse the sense of positive
direction, e.g., to have the y-axis be positive down.
void ps_bitimage (xpos, ypos, xlength, ylength, buffer, nx, ny, invert, f_rgb, b_rgb)
double xpos, ypos, xlength, ylength;
unsigned char buffer[];
int nx, ny, invert, f_rgb[3], b_rgb[3];
Plots a 1-bit image using the given foreground color f_rgb and background color b_rgb. Spec-
ify position of lower left corner and size (in inches) of image. buffer is an unsigned character
array with 8 pixels per byte. nx,ny refers to the number of pixels in image. The rowlength of
buffer must be an integral number of 8. buffer[0] is upper left corner. buffer values are stored
as columns, starting at the lower left corner and ending at the upper right corner. If invert is 0
then the bits that are 1 are painted with the foreground color, while bits that are 0 are painted
with the backgound color. If invert is 1, foreground and background are switched. To get a
partly transparent image, set the first index of the foreground or background color to -1, i.e.,
f_rgb[0]=-1 or b_rgb[0]=1. See the Adobe Systems PostScript Reference Manual for more
details.
void ps_circle (xcenter, ycenter, diameter, rgb, outline)
double xcenter, ycenter, diameter;
int rgb[3], outline;
Plots a circle and fills it with the specified color. If outline == 1, the outline will be drawn
using current pen-width and -pattern.
void ps_clipoff ()
Resets the clip path to what it was before the last call to ps_clipon.
void ps_clipon (xarray, yarray, npoints, rgb, flag)
double xarray[], yarray[];
long npoints;
int rgb[3], flag;
Sets up a user-definable clip path. Plotting outside this polygon will be clipped until
ps_clipoff is called. If red >= 0 the inside of the path is filled with the specified color. flag is
used to create complex clip paths consisting of several disconnected regions, and takes on val-
ues 0-3. flag = 1 means this is the first path in a multi-segment clip path. flag = 2 means this is
the last segment. Thus, for a single path, flag = 3.
void ps_colorimage (xpos, ypos, xlength, ylength, buffer, nx, ny, depth)
int nx, ny, depth;
Plots a 1-, 2-, 4-, 8-, or 24-bit deep image. This functions sets up a call to the PostScript col-
orimage or image operators. xpos, ypos, xlength, ylength specify the position of lower left cor-
ner and size (in inches) of image. The pixel values are stored in buffer, an unsigned character
array in scanline orientation with gray shade or r/g/b values (0 - 255) where 0 is black, 255 is
white. buffer[0] is upper left corner. depth is number of bits per pixel (24, 8, 4, 2, or 1). nx,ny
refers to the number of pixels in image. The rowlength of buffer must be an integral number of
8/depth. E.g. if depth = 4, then buffer[j]/16 gives shade for pixel[2j-1] and buffer[j]%16 (mod
16) gives shade for pixel[2j]. When -depth is passed instead then "hardware" interpolation of
the image is requested. If -nx is passed with 8- or 24-bit images then the first one or three
bytes of buffer holds the gray or r/g/b color for pixels that are to be masked out using the Post-
Script Level 3 Color Mask method. See the Adobe Systems PostScript Reference Manual for
more details.
void ps_colortiles (x0, y0, xlength, ylength, buffer, nx, ny)
double x0, y0, xlength, ylength;
int nx, ny;
GMT 4.5.14 1 Nov 2015 2


Plots a true color image based on individual color tiles. x0, y0 is the location of the lower left
corner of the image in inches. xlength, ylength is the image size in inches. buffer contains rgb
triplets stored as rgbrgbrgb... nx, ny is the image size in pixels.
void ps_command (text)
char *text;
Writes a raw PostScript command to the PostScript output file, e.g., "1 setlinejoin".
void ps_comment (text)
char *text;
Writes a comment (text) to the PostScript output file, e.g., "Start of graph 2".
void ps_cross (xcenter, ycenter, diameter)
Plots a cross (x) at the specified point using current pen-width and -pattern that fits inside a cir-
cle of given diameter. No fill possible.
void ps_diamond (xcenter, ycenter, diameter, rgb, outline)
Plots a diamond and fills it with the specified color. If outline == 1, the outline will be drawn
using current pen-width and -pattern. The symbol will fit inside a circle of given diameter.
void ps_ellipse (xcenter, ycenter, angle, major, minor, rgb, outline)
double xcenter, ycenter, angle, major, minor;
Plots a ellipse with its major axis rotated by angle degrees and fills it with the specified color.
If outline == 1, the outline will be drawn using current pen-width and -pattern.
void ps_encode_font (font_no)
int font_no;
Will reencode this font using the current encoding vector if it is not StandardEncoding.
void ps_epsimage (xpos, ypos, xlength, ylength, buffer, size, nx, ny, ox, oy)
int size, nx, ny, ox, oy;
Plots an Encapsulated PostScript (EPS) image. The EPS file is stored in buffer and has size
bytes. This functions simply includes the image in the PostScript output stream within an
appropriate wrapper. Specify position of lower left corner and size (in inches) of image.
nx,ny,ox,oy refers to the width, height and origin (lower left corner) of the BoundingBox.
void ps_flush ()
Flushes the output buffer.
void ps_hexagon (xcenter, ycenter, diameter, rgb, outline)
Plots a hexagon and fills it with the specified color. If outline == 1, the outline will be drawn
void ps_image (xpos, ypos, xlength, ylength, buffer, nx, ny, bits)
int nx, ny, bits;
Obsolete, simply passes arguments to ps_colorimage.
void ps_imagefill (x, y, n, image, imagefile, invert, dpi, outline, f_rgb, b_rgb)
double x[], y[], x0, y0;
int n, image, invert, dpi, outline, f_rgb[3], b_rgb[3];
GMT 4.5.14 1 Nov 2015 3

char imagefile;
Similar to ps_polygon, but fills the area with an image pattern rather than a color or grayshade.
x and y hold the arrays of n points. 90 predefined patterns are available (See GMT Appendix
E). image gives the image number (1-90). If set to 0, imagefile must be the name to the user’s
image, which must be stored as a Sun 1-, 8-, or 24-bit rasterfile.
1-bit images only: (i) The set pixels (1) are colored using the RGB combination in f_rgb, while
the unset pixels (0) are painted with b_rgb. Set the f_rgb[0] to -1 to make set pixels transpar-
ent. Set b_rgb[0] to -1 to make the unset pixels transparent. (ii) If invert is TRUE (1), the set
and unset pixels are interchanged before plotting.
The unit size of the image is controlled by dpi (in dots-per-inch). If set to zero, the image is
plotted at the device resolution. If outline is TRUE, the current penwidth is used to draw the
polygon outline.
void ps_itriangle (xcenter, ycenter, diameter, rgb, outline)
Plots an inverted and fills it with the specified color. If outline == 1, the outline will be drawn
long ps_line (xarray, yarray, npoints, type, close, dummy)
long npoints;
int type, close, dummy;
Draw a continuous line from the positions in the x-y arrays. If close == 1, the first and last
point will automatically be closed by the PostScript driver. If this is the first segment in a
multi-segment path, set type == 1. To end the segments and have the line(s) drawn, set type
== 2. Thus, for a single segment, type must be 3. The line is drawn using the current pen-
width. The dummy is an obsolete parameter no longer used internally.
unsigned char *ps_load_image (fp, header)
FILE *fp;
struct imageinfo *header;
Reads the image contents of the EPS file or Sun rasterfile pointed to by the open filepointer fp.
The routine can handle Encapsulated PostScript files or 1-, 8-, 24-, or 32-bit rasterfiles in old,
standard, run-length encoded, or RGB-style Sun format.
void ps_octagon (xcenter, ycenter, diameter, rgb, outline)
Plots a octagon and fills it with the specified color. If outline == 1, the outline will be drawn
void ps_patch (xarray, yarray, npoints, rgb, outline)
long npoints;
Identical to ps_polygon except polygon must be < 20 points long and there will be no attempt
to shorten the path by discarding unnecessary intermediate points along straight segments. Pri-
marily used when painting large number of small polygons and not waste output space. If
more than 20 points are given we pass the buck to ps_polygon.
void ps_pentagon (xcenter, ycenter, diameter, rgb, outline)
Plots a pentagon and fills it with the specified color. If outline == 1, the outline will be drawn
void ps_pie (xcenter, ycenter, radius, azimuth1, azimuth2, rgb, outline)
double xcenter, ycenter, radius, azimuth1, azimuth2;
GMT 4.5.14 1 Nov 2015 4


Plots a sector of a circle and paints it with the specified RGB combination. If outline == 1, the
outline will be drawn using current pen-width and -pattern.
void ps_plot (xabs, yabs, kpen)
double xabs, yabs;
int kpen;
Absolute move (kpen=3) or draw (kpen=2), using current linewidth. Use (kpen=-2) to make
sure the line is stroked.
void ps_plotend (last_page)
int last_page;
Terminates the plotting sequence and closes plot file (if other than stdout). If last_page == 1,
then a PostScript showpage command is issued, which initiates the printing process on hard-
copy devices.
void ps_plotinit (plotfile, overlay, mode, xoff, yoff, xscl, yscl, ncopies, dpi, unit, pagesize, rgb,
encoding, eps)
char *plotfile, *encoding;
int overlay, mode, ncopies, dpi, unit;
double xoff, yoff, xscl, yscl;
int pagesize[2], rgb[3]; struct EPS * eps;
Initializes the plotting. If plotfile == NULL (or ""), then output is sent to stdout, else output is
sent to plotfile. overlay should be 1 only if you plan to append it to some existing PostScript
file. mode contains three flags in the three lowest bits. The lowest bit controls the plot orienta-
tion and can be 0 (Landscape) or 1 (Portrait). The next bit, if set to 1, will re-encode the fonts
to include European accented characters using the now-obsolete GMT 3.4 encoding. To use
the ISOLatin1 encoding set the 5th bit to 1. The third bit controls the format used to write
PostScript images: 0 means binary, 1 means hexadecimal. Most printers needs the latter while
some can handle binary which are 50% smaller and therefore execute faster. xoff,yoff are used
to move the origin from the default position in the lower left corner. xscl,yscl are used to scale
the entire plot (Usually set to 1.0, 1.0). Set ncopies to get more than 1 copy. dpi sets the hard-
copy resolution in dots pr units. For optimum plot quality and processing speed, choose dpi to
match the intended plotter resolution. Examples are 300 for most laserwriters, 2540 for Lino-
type-300, and ˜85 for Sun screens. When in doubt, use 300. unit can be any of 0 (cm), 1
(inch), or 2 (m), telling the plot system what units are used for distance and sizes. Note that,
regardless of choice of unit, dpi is still in dots-pr-inch. pagesize means the physical width and
height of the plotting media in points, (typically 612 by 792 for Letter or 595 by 842 for A4
laserwriter plotters. The rgb array holds the color of the page (usually white = 255,255,255).
The encoding is the name of a character encoding scheme to be used, e.g., Standard, ISO-
Latin1, ISO-8859-2, etc. The EPS structure is defined in the pslib.h include file and contains
information that will make up the comments header of a EPS file. Programmers who plan to
call pslib routines should read the comments in pslib.h first. Note that the FORTRAN binding
does not expect this last argument.
void ps_plotinit_hires (plotfile, overlay, mode, xoff, yoff, xscl, yscl, ncopies, dpi, unit, pagesize,
rgb, encoding, eps)
char *plotfile, *encoding;
int overlay, mode, ncopies, dpi, unit, rgb[3];
double xoff, yoff, xscl, yscl;
double pagesize[2]; struct EPS * eps;
Same as ps_plotinit but expects the page size to be given in double precision points.
void ps_plotr (xrel, yrel, kpen)
double xrel, yrel;
int kpen;
Move (kpen = 3) or draw (kpen = 2) relative to current point (see ps_plot). Use (kpen=-2) to
GMT 4.5.14 1 Nov 2015 5

make sure the line is stroked.

void ps_plus (xcenter, ycenter, diameter)
Plots a plus (+) at the specified point using current pen-width and -pattern that fits inside a cir-
cle of given diameter. No fill possible.
void ps_point (xcenter, ycenter, diameter)
Plots a point (dot) using current pen with given diameter. Note the linecap setting must first be
set to 1 for this function to work.
void ps_polygon (xarray, yarray, npoints, rgb, outline)
long npoints;
Creates a colored polygon from the positions in the x-y arrays. Polygon will automatically be
closed by the PostScript driver. If outline == 0, no outline is drawn. If outline == 1, the out-
line is drawn using current penwidth.
void ps_rect (x1, y1, x2, y2, rgb, outline)
double x1, y1, x2, y2;
Plots a colored rectangle. (x1,y1) and (x2,y2) are any two corners on a diagonal. If outline ==
1, the outline will be drawn using current pen-width and -pattern.
void ps_rotaterect (x, y, angle, xsize, ysize, rgb, outline)
double x, y, angle, xsize, ysize;
Plots a colored rectangle rotated angle degrees from baseline. (x,y) is the center and
(xsize,ysize) are the dimensions. If outline == 1, the outline will be drawn using current pen-
width and -pattern.
void ps_rotatetrans (x, y, angle)
double x, y, angle;
Rotates the coordinate system by angle degrees, then translates origin to (x,y).
void ps_segment (x0, y0, x1, y1)
double x0, y0, x1, y1;
Draws a line segment between the two points using current pen attributes.
void ps_setdash (pattern, offset)
char *pattern;
int offset;
Changes the current dashpattern. The character string pattern is set to the desired pattern.
E.g., "4 2" and offset = 1 will plot like:
x ---- ---- ----
etc, where x is starting point (The x is not plotted). That is, the line is made up of a repeating
pattern of a 4 units long line and a 2 unit long gap, starting 1 unit after the x. To reset to solid
line, specify pattern = NULL ("") and offset = 0. Units are in dpi units.
void ps_setfill (rgb, outline)
Sets the current fill color and whether or not outline is needed for symbols.
void ps_setfont (fontnr)
int fontnr;
Changes the current font number to fontnr. The fonts available are: 0 = Helvetica, 1 = H.
Bold, 2 = H. Oblique, 3 = H. Bold-Oblique, 4 = Times, 5 = T. Bold, 6 = T. Italic, 7 = T. Bold
Italic, 8 = Courier, 9 = C. Bold, 10 = C Oblique, 11 = C Bold Oblique, 12 = Symbol, 13 =
GMT 4.5.14 1 Nov 2015 6

AvantGarde-Book, 14 = A.-BookOblique, 15 = A.-Demi, 16 = A.-DemiOblique, 17 = Book-

man-Demi, 18 = B.-DemiItalic, 19 = B.-Light, 20 = B.-LightItalic, 21 = Helvetica-Narrow, 22
= H-N-Bold, 23 = H-N-Oblique, 24 = H-N-BoldOblique, 25 = NewCenturySchlbk-Roman, 26
= N.-Italic, 27 = N.-Bold, 28 = N.-BoldItalic, 29 = Palatino-Roman, 30 = P.-Italic, 31 =
P.-Bold, 32 = P.-BoldItalic, 33 = ZapfChancery-MediumItalic, 34 = ZapfDingbats, 35 = Ryu-
min-Light-EUC-H, 36 = Ryumin-Light-EUC-V, 37 = GothicBBB-Medium-EUC-H, and 38 =
GothicBBB-Medium-EUC-V. If fontnr is outside this range, it is set to 0.
void ps_setformat (n_decimals)
int n_decimals;
Sets number of decimals to be used when writing color or gray values. The default setting of 3
gives 1000 choices per red, green, and blue value, which is more than the 255 choices offered
by most 24-bit platforms. Choosing a lower value will make the output file smaller at the
expense of less color resolution. Still, a value of 2 gives 100 x 100 x 100 = 1 million colors,
more than most eyes can distinguish. For a setting of 1, you will have 10 nuances per primary
color and a total of 1000 unique combinations.
void ps_setline (linewidth)
int linewidth;
Changes the current linewidth in DPI units. 0 gives thinnest line, but the use of 0 is implemen-
tation-dependent (Works fine on most laserwriters).
void ps_setlinecap (cap)
int cap;
Changes the current linecap. 0 gives butt cap [Default], 1 gives round, and 2 gives square.
void ps_setlinejoin (join)
int join;
Changes the current linejoin. 0 gives mitered [Default], 1 gives round, and 2 gives bevel joins.
void ps_setmiterlimit (limit)
int limit;
Changes the current miter limit. 0 gives default miter, other values are the cutoff-, acute- angle
when mitering takes place.
void ps_setpaint (rgb)
int rgb[3];
Changes the current RGB setting for pens and text.
void ps_square (xcenter, ycenter, diameter, rgb, outline)
Plots a square and fills it with the specified color. If outline == 1, the outline will be drawn
void ps_star (xcenter, ycenter, diameter, rgb, outline)
Plots a star and fills it with the specified color. If outline == 1, the outline will be drawn using
current pen-width and -pattern. The symbol will fit inside a circle of given diameter.
void ps_text (x, y, pointsize, text, angle, justify, form)
double x, y, pointsize, angle;
char *text;
int justify, form;
The text is plotted starting at (x,y), and will make an angle with the horizontal. The point (x,y)
maps onto different points of the textstring by giving various values for justify. It is used as
follows:
9------------10----------- 11
GMT 4.5.14 1 Nov 2015 7

| |
5 6 7
| |
1------------ 2------------ 3
The box represents the textstring. E.g., to plot a textstring with its center of gravity at (x,y),
you must use justify == 6. If justify is negative, then all leading and trailing blanks are stripped
before plotting. Certain character sequences (flags) have special meaning to ps_text. @˜ tog-
gles between current font and the Mathematical Symbols font. @%no% sets font to no; @%%
resets to starting font. @- turns subscript on/off, @+ turns superscript on/off, @# turns small
caps on/off, and @\ will make a composite character of the following two character. @;r/g/b;
changes the font color (@;; resets it), @:size: changes the font size (@:: resets it), and @_ tog-
gles underline on/off. Give fontsize in points (72 points = 1 inch). Normally, the text is typed
using solid characters. To draw outline characters, set form == 1. If pointsize is negative it
means that the current point has already been set before ps_text was called and that (x,y)
should be ignored.
void ps_textbox (x, y, pointsize, text, angle, justify, outline, dx, dy, rgb)
double x, y, angle, pointsize, dx, dy;
char *text;
int justify, outline, rgb[3];
This function is used in conjugation with ps_text when a box surrounding the text string is
desired. Taking most of the arguments of ps_text, the user must also specify the color of the
resulting rectangle, and whether its outline should be drawn. More room between text and rec-
tangle can be obtained by setting dx and dy accordingly.
void ps_transrotate (x, y, angle)
double x, y, angle;
Translates the origin to (x,y), then rotates the coordinate system by angle degrees.
void ps_triangle (xcenter, ycenter, diameter, rgb, outline)
Plots a triangle and paints it with the specified RGB combination. If outline == 1, the outline
will be drawn using current pen-width and -pattern. The symbol will fit inside a circle of given
diameter.
void ps_vector (xtail, ytail, xtip, ytip, tailwidth, headlength, headwidth, headshape, rgb, outline)
double xtail, ytail, xtip, ytip, tailwidth, headlength, headwidth, headshape;
Draws a vector of size and appearance as specified by the various parameters. headshape can
take on values from 0-1 and specifies how far the intersection point between the base of a
straight vector head and the vector line is moved toward the tip. 0 gives a triangular head, 1.0
gives an arrow shaped head. If outline == 1, the outline will be drawn using current penwidth.
Add 8 to outline for a double-headed vector.
void ps_words (x, y, text, n_words, line_space, par_width, par_just, font, font_size, angle, rgb,
justify, draw_box, x_off, y_off, x_gap, y_gap, boxpen_width, boxpen_texture, boxpen_offset, box-
pen_rgb, vecpen_width, vecpen_texture, vecpen_offset, vecpen_rgb, boxfill_rgb)
double x, y, line_space, par_width, angle, x_off, y_off, x_gap, y_gap;
long n_words;
int font, font_size, justify, draw_box, boxpen_width, boxpen_offset;
int boxpen_rgb[3], vecpen_width, vecpen_offset, vecpen_rgb[3], boxfill_rgb[3];
char **text, *boxpen_texture, *vecpen_texture;
Typesets paragraphs of text. text is an array of the words to typeset, using the given line-spac-
ing and paragraph width. The whole text block is positioned at x, y which is the anchor point
on the box as indicated by justify (see ps_text). The whole block is then shifted by x_off, y_off.
Inside the box, text is justified left, centered, right, or justified as governed by par_just (lcrj).
GMT 4.5.14 1 Nov 2015 8

draw_box contains 4 bit flags pertaining to the surrounding outline box. If on, the first (lowest)
bit draws the box outline. The second bit fills the box interior. The third bit makes the outline
box have rounded corners (unless x_gap, y_gap, which specifies the padding between the text
and the box, are zero), while the forth bit draws a line from the original x, y point to the shifted
position. The escape sequences described for ps_text applies as well.
AUTHOR
Paul Wessel, School of Ocean and Earth Science and Technology, 1680 East-West Road, Honolulu, Hawaii
96822, (808) 956-4778, Internet address: [email protected].
BUGS
Caveat Emptor: The author is not responsible for any disasters, suicide attempts, or ulcers caused by cor-
rect or incorrect use of pslib. If you find bugs, please report them to the author by electronic mail. Be sure
to provide enough detail so that I can recreate the problem.
REFERENCES
Adobe Systems Inc., 1990, PostScript language reference manual, 2nd edition, Addison-Wesley, (ISBN
0-201-18127-4).
GMT 4.5.14 1 Nov 2015 9

PSMASK(1) Generic Mapping Tools PSMASK(1)
NAME
psmask − To clip or mask areas of no data on a map
SYNOPSIS
psmask [xyzfile] −Ixinc[unit][=|+][/yinc[unit][=|+]] −Jparameters −Rwest/east/south/north[r] [
−B[p|s]parameters ] [ −Ddumpfile ] [ −Eazim/elev[+wlon/lat[/z]][+vx0/y0] ] [ −F ] [ −Gfill ] [ −H[i][nrec] ]
[ −K ] [ −N ] [ −O ] [ −P ] [ −Ssearch_radius[m|c|k|K] ] [ −T ] [ −U[just/dx/dy/][c|label] ] [ −V ] [
−X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [ −ccopies ] [ −:[i|o] ] [ −bi[s|S|d|D[ncol]|c[var1/...]] ] [
−m[flag] ]
psmask −C [ −K ] [ −O ]
DESCRIPTION
psmask reads a (x,y,z) file [or standard input] and uses this information to find out which grid cells are reli-
able. Only gridcells which have one or more data points are considered reliable. As an option, you may
specify a radius of influence. Then, all gridcells that are within radius of a data point are considered reli-
able. Furthermore, an option is provided to reverse the sense of the test. Having found the reliable/not reli-
able points, psmask will either paint tiles to mask these nodes (with the −T switch), or use contouring to
create polygons that will clip out regions of no interest. When clipping is initiated, it will stay in effect
until turned off by a second call to psmask using the −C option.
xyzfile File with (x,y,z) values (e.g., that was used to run surface). If no file is given, standard input is
read. For binary files, see −b.
GMT 4.5.14 1 Nov 2015 1


CONIC PROJECTIONS:


OPTIONS
details.
GMT 4.5.14 1 Nov 2015 2

−C Mark end of existing clip path. No input file is needed. Implicitly sets −O. However, you must
supply −Xa and −Ya settings if you are using absolute positioning.
−D Dumps out the resulting clipping polygons to disk. Ignored if −T is set. If no dumpprefix is given
we use mask (Files will be called mask_*.d). Append +n<n_pts> to limit the number of points in
files to a minimum of n_pts. That is, do not write individual polygon files if they do not have at
least n_pts vertices. Often, when one uses the −D option it is not wished to output any ps code to
stdout. In such cases redirect the output to > /dev/null on *nix systems or to > nul on Windows.
−G Paint the clip polygons (or tiles) with a selected fill [Default is no fill]. (See SPECIFYING FILL
below).
−N Invert the sense of the test, i.e., clip regions where there is data coverage.
−S Sets radius of influence. Grid nodes within radius of a data point are considered reliable. [Default
is 0, which means that only grid cells with data in them are reliable]. Append m to indicate min-
utes or c to indicate seconds. Append k to indicate km (implies −R and −I are in degrees, and we
will use a fast flat Earth approximation to calculate distance). For more accuracy, use uppercase K
if distances should be calculated along geodesics. However, if the current ELLIPSOID is spheri-
cal then great circle calculations are used.
−T Plot tiles instead of clip polygons. Use −G to set tile color or pattern.
size.
GMT 4.5.14 1 Nov 2015 3

SPECIFYING FILL
SPECIFYING COLOR
EXAMPLES
To make an overlay PostScript file that will mask out the regions of a contour map where there is no control
data using clip polygons, use:
psmask africa_grav.xyg −R 20/40/20/40 −I 5m −JM 10i −O −K > mask.ps
The same example but this time we use white tiling:
psmask africa_grav.xyg −R 20/40/20/40 −I 5m −JM 10i −T −O −K −G white > mask.ps

SEE ALSO
GMT (1), gmtcolors(5), grdmask(1), surface(1), psbasemap(1), psclip(1)
GMT 4.5.14 1 Nov 2015 4

PSROSE(1) Generic Mapping Tools PSROSE(1)
NAME
psrose − Plot (length, azimuth) as windrose diagram or polar histogram (sector or rose diagram).
SYNOPSIS
psrose file [ −Asector_width[r] ] [ −B[p|s]parameters ] [ −C[mode_file] ] [ −D ] [ −Eazimuth/elevation ] [
−I ] [ −Gfill ] [ −H[i][nrec] ] [ −I ] [ −K ] [ −L[wlabel/elabel/slabel/nlabel] ] [ −M[parameters ] [ −O ] [
−P ] [ −Rr0/r1/az_0/az_1 ] [ −Sradial_scale[n] ] [ −T ] [ −U[just/dx/dy/][c|label] ] [ −V ] [ −Wpen ] [
−X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [ −Zscale ] [ −ccopies ] [ −:[i|o] ] [
−bi[s|S|d|D[ncol]|c[var1/...]] ]
DESCRIPTION
psrose reads (length,azimuth) pairs from file [or standard input] and generates PostScript code that will plot
a windrose diagram. Optionally (with −A), polar histograms may be drawn (sector diagram or rose dia-
gram). Options include full circle and half circle plots. The PostScript code is written to standard output.
file Name of ASCII [or binary, see −b] data file. If no file is given, psrose will read standard input.
OPTIONS
−A Gives the sector width in degrees for sector and rose diagram. [Default 0 means windrose dia-
gram]. Append r to draw rose diagram instead of sector diagram.
details. Remember that "x" here is radial distance and "y" is azimuth. The ylabel may be used to
plot a figure caption.
−C Plot vectors showing the principal directions given in the modes file. If no file is given, compute
and plot mean direction.
−D Shift sectors so that they are centered on the bin interval (e.g., first sector is centered on 0
degrees).
−E Sets the viewpoint’s azimuth and elevation [180/90]
−F Do not draw the scale length bar [Default plots scale in lower right corner]
−G Selects shade, color or pattern for filling the sectors [Default is no fill]. (See SPECIFYING FILL
below).
skipped.
−I Inquire. Computes statistics needed to specify useful −R. No plot is generated.
−L Specify labels for the 0, 90, 180, and 270 degree marks. For full-circle plot the default is
WEST/EAST/SOUTH/NORTH and for half-circle the default is 90W/90E/-/0. A - in any entry
disables that label. Use −L with no argument to disable all four labels
−M Specify new arrow attributes tailwidth/headlength/headwidth/r/g/b to change the appearance of
arrows (Only if −C is set). [Default is 0.075c/0.3c/0.25c/0/0/0 (or 0.03i/0.12i/0.1i/0/0/0)].
−R Specifies the ’region’ of interest in (r,azimuth) space. r0 is 0, r1 is max length in units. For
azimuth, specify -90/90 for half circle plot or 0/360 for full circle.
−S Specifies radius of circle. Append n to normalize input radii to go from 0 to 1.
−T Specifies that the input data is orientation data (has a 180 degree ambiguity) instead of true 0-360
degree directions [Default].
GMT 4.5.14 1 Nov 2015 1

−W Set pen attributes for sector outline or rose plot. [Default is no outline]. (See SPECIFYING
PENS below).
size.
−Z Multiply the data radii by scale. E.g., use −Z 0.001 to convert your data from m to km [Default is
no scaling].
−: Input file has (azimuth,radius) pairs rather than the expected (radius,azimuth).
SPECIFYING PENS
‘.’.
SPECIFYING FILL
SPECIFYING COLOR
EXAMPLES
To plot a half circle rose diagram of the data in the file fault_segments.az_r (containing pairs of (azimuth,
length in meters), using a 10 degree bin sector width, on a circle of radius = 3 inch, grid going out to radius
= 150 km in steps of 25 km with a 30 degree sector interval, radial direction annotated every 50 km, using a
light blue shading outlined by a solid red pen (width = 0.75 points), draw the mean azimuth, and shown in
Portrait orientation, use:
psrose fault_segments.az_r −R 0/150/-90/90 −B 50g25:"Fault length":/g30:."Rose diagram": −S 3i −A 10r
GMT 4.5.14 1 Nov 2015 2

−G lightblue −W 0.75p,red −Z 0.001 −C −P −T −: | lpr
To plot a full circle wind rose diagram of the data in the file lines.r_az, on a circle of radius = 5 cm, grid
going out to radius = 500 units in steps of 100 with a 45 degree sector interval, using a solid pen (width =
0.5 point), and shown in landscape [Default] orientation with UNIX timestamp and command line plotted,
use:
psrose lines.az_r −R 0/500/0/360 −S 5c −Bg 100/g45:."Windrose diagram": −W 0.5p −Uc | lpr

BUGS
No default radial scale and grid settings for polar histograms. User must run psrose −I to find max length
in binned data set.
SEE ALSO
GMT (1), gmtcolors(5), gmtdefaults(1), pshistogram(1)
GMT 4.5.14 1 Nov 2015 3

PSSCALE(1) Generic Mapping Tools PSSCALE(1)
NAME
psscale − Plot gray scale or color scale on maps
SYNOPSIS
psscale −Dxpos/ypos/length/width[h] [ −A[a|l|c] ] [ −B[p|s]parameters ] [ −Ccpt_file ] [ −E[b|f][length] ] [
−I[max_intens|low_i/high_i] ] [ −K ] [ −L[i][gap] ] [ −M ] [ −Ndpi ] [ −O ] [ −P ] [ −Q ] [
−U[just/dx/dy/][c|label] ] [ −V ] [ −X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [ −Zzfile ] [ −ccopies ]
DESCRIPTION
psscale plots gray scales or color scales on maps. Both horizontal and vertical scales are supported. For
cpt_files with gradational colors (i.e., the lower and upper boundary of an interval have different r/g/b val-
ues) psscale will interpolate to give a continuous scale. Variations in intensity due to shading/illumination
may be displayed by setting the option −I. Colors may be spaced according to a linear scale, all be equal
size, or by providing a file with individual tile widths.
−D Defines the position of the center/top (for horizontal scale) or center/left (for vertical scale) and the
dimensions of the scale. Give a negative length to reverse the scalebar. Append h to get a hori-
zontal scale [Default is vertical].
OPTIONS
−A Place annotations and labels above (instead of below) horizontal scalebars and to the left (instead
of the right) of vertical scalebars. Append a or l to move only the annotations or the label to the
other side. Append c if you want to print a vertical label as a column of characters (does not work
with special characters).
−B Set annotation, tick, and gridline interval for the colorbar. The x-axis label will plot beneath a hor-
izontal bar (or vertically to the right of a vertical bar), except when using −A. As an option, use
the y-axis label to plot the data unit to the right of a horizontal bar (and above a vertical bar). If
−B is omitted, or no annotation intervals are provided, the default is to annotate every color level
based on the numerical entries in the cpt file (which may be overridden by ULB flags in the cpt
file). To specify custom text annotations for intervals, you must append ;annotation to each z-slice
in the cpt file.
−C cpt_file is the color palette file to be used. By default all color changes are annotated. To use a
subset, add an extra column to the cpt-file with a L, U, or B to annotate Lower, Upper, or Both
color segment boundaries (but see −B). If not given, psscale will read stdin. Like grdview, pss-
cale can understand pattern specifications in the cpt file.
−E Add sidebar triangles for back- and/or foreground colors. Add f or b for only one sidebar triangle
[Default gives both]. Optionally, append triangle height [Default is half the barwidth].
−I Add illumination effects. Optionally, set the range of intensities from - to + max_intens. If not
specified, 1 is used. Alternatively, append low/high intensities to specify an asymmetric range
[Default is no illumination].
−L Gives equal-sized color rectangles. Default scales rectangles according to the z-range in the cpt-
file (Also see −Z). If set, any equal interval annotation set with −B will be ignored. If gap is
appended and the cpt table is discrete we will center each annotation on each rectangle, using the
lower boundary z-value for the annotation. If i is prepended we annotate the interval range
instead. If −I is used then each rectangle will have its constant color modified by the specified
intensity.
−M Force a monochrome graybar using the (television) YIQ transformation.
−N Effective dots-per-inch for the rectangular image making up the color scale [300].
GMT 4.5.14 1 Nov 2015 1

PSSCALE(1) Generic Mapping Tools PSSCALE(1)
−Q Select logarithmic scale and power of ten annotations. All z-values in the cpt file will be con-
verted to p = log10(z) and only integer p values will be annotated using the 10ˆp format [Default is
linear scale].
−S Do not separate different colour intervals with black lines.
size.
−Z File with colorbar-width per color entry. By default, width of entry is scaled to color range, i.e., z
= 0-100 gives twice the width as z = 100-150 (Also see −L).
EXAMPLES
To append a vertical color scale (7.5 cm long; 1.25 cm wide) to the right of a plot that is 6 inch wide and 4
inch high, using illumination, and show back- and foreground colors, and annotating every 5 units, use
psscale −D 6.5i/2i/7.5c/1.25c −O −C colors.cpt −I −E −B 5:BATHYMETRY:/:m: >> map.ps

NOTES
When the cpt file is discrete and no illumination is specified, the color bar will be painted using polygons.
For all other cases we must paint with an image. Some color printers may give slightly different colors for
the two methods given identical RGB values.
SEE ALSO
GMT (1), makecpt(1), grd2cpt(1)
GMT 4.5.14 1 Nov 2015 2

PSTEXT(1) Generic Mapping Tools PSTEXT(1)
NAME
pstext − To plot text strings on maps
SYNOPSIS
pstext textfile −Jparameters −Rwest/east/south/north[r] [ −A ] [ −B[p|s]parameters ] [ −Cdx/dy ] [
−D[j]dx[/dy][v[pen] ] [ −Eazim/elev[+wlon/lat[/z]][+vx0/y0] ] [ −Gcolor ] [ −H[i][nrec] ] [ −Jz|Zparame-
ters ] [ −K ] [ −L ] [ −N ] [ −O ] [ −P ] [ −Spen ] [ −U[just/dx/dy/][c|label] ] [ −V ] [
−W[color,][o|O|c|C[pen]] ] [ −X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [ −Z[zlevel|+] ] [ −:[i|o] ] [
−ccopies ] [ −f[i|o]colinfo ] [ −m[flag] ]
DESCRIPTION
pstext plots text strings of variable size, font type, and orientation. Various map projections are provided,
with the option to draw and annotate the map boundaries. PostScript code is written to standard output.
Greek characters, subscript, superscript, and small caps are supported as follows: The sequence @˜ toggles
between the selected font and Greek (Symbol). @%no% sets the font to no; @%% resets the font to the
starting font, @- toggles subscripts on/off, @+ toggles superscript on/off, @# toggles small caps on/off,
@;color; changes the font color (@;; resets it), @:size: changes the font size (@:: resets it), and @_ toggles
underline on/off. @@ prints the @ sign. @e, @o, @a, @E, @O, @A give the accented Scandinavian
characters. Composite characters (overstrike) may be indicated with the @!<char1><char2> sequence,
which will print the two characters on top of each other. To learn the octal codes for symbols not available
on the keyboard and some accented European characters, see Section 4.16 and Appendix F in the GMT
Technical Reference and Cookbook. Note that CHAR_ENCODING must be set to an extended character
set in your .gmtdefaults4 file in order to use the accented characters. Using the −W option, a colored rec-
tangle underlying the text may be plotted (Does not work for strings with sub/super scripts, symbols, or
composite characters, except in paragraph mode (−m)).
textfile This file contains 1 or more records with (x, y, size, angle, fontno, justify, text). If no file is given,
pstext will read standard input. size is text size in points, angle is measured in degrees counter-
clockwise from horizontal, fontno sets the font type, justify sets the alignment. If fontno is not an
integer, then it is taken to be a text string with the desired fontname. See the gmtdefaults man
page for names and numbers of available fonts (or run pstext −L). The alignment refers to the
part of the text string that will be mapped onto the (x,y) point. Choose 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.
GMT 4.5.14 1 Nov 2015 1

CONIC PROJECTIONS:


OPTIONS
−A Angles are given as azimuths; convert them to directions using the current projection.
details.
−C Sets the clearance between the text and the surrounding box [15%]. Only used if −W is specified.
Append the unit you want (cm, inch, meter. or point; if not given we consult MEASURE_UNIT)
GMT 4.5.14 1 Nov 2015 2

or % for a percentage of the font size.

−D Offsets the text from the projected (x,y) point by dx,dy [0/0]. If dy is not specified then it is set
equal to dx. Use -Dj to offset the text away from the point instead (i.e., the text’s justification will
determine the direction of the shift). Optionally, append v which will draw a line from the original
point to the shifted point; append a pen to change the attributes for this line. (See SPECIFYING
PENS below).
specify the coordinates of the projected view point with +vx0/y0). (Not implemented for para-
graph mode).
−G Sets the shade or color used for drawing the text [Default is BASEMAP_FRAME_RGB, the cur-
rent frame color (by default black)] (See SPECIFYING COLOR below).
skipped.
−L Lists the font-numbers and font-names available, then exits.
−N Do NOT clip text at map boundaries [Default will clip].
−S Draw text outline. Append pen attributes. (Not implemented for paragraph mode).
−W Paint a rectangle beneath the text string. Set color [Default is no fill]. Append o to draw rectangle
outline, add a pen to specify pen attributes [width = 1, color = black, texture = solid]. use a
comma to separate the fill information from the outline information if both are present. Choose
upper case O to get a rounded rectangle. Choose lower case c to get a concave rectangle (only in
paragraph mode). Choose upper case C to get a convex rectangle (only in paragraph mode). (See
also SPECIFYING PENS and SPECIFYING COLOR below).
size.
−Z For 3-D projections: Sets the z-level of the basemap [Default is the bottom of the z-axis]. If −Z+
is given we expect each item to have its own level given in the 3rd column, and −N is implicitly
set. (Not implemented for paragraph mode).
GMT 4.5.14 1 Nov 2015 3


−m Paragraph mode. Files must be multiple segment files. Segments are separated by a special record
whose first character must be flag [Default is ’>’]. Starting in the 3rd column, we expect to find
information pertaining to the typesetting of a text paragraph (the remaining lines until next seg-
ment header). The information expected is (x y size angle fontno justify linespace parwidth par-
just), where x y size angle fontno justify are defined above, while linespace and parwidth are the
linespacing and paragraph width, respectively. The justification of the text paragraph is governed
by parjust which may be l(eft), c(enter), r(ight), or j(ustified). The segment header is followed by
one or more lines with paragraph text. Text may contain the escape sequences discussed above.
Separate paragraphs with a blank line.
SPECIFYING PENS
‘.’.
SPECIFYING COLOR
EXAMPLES
To plot the outlines of the text strings stored in the file text.d on a Mercator plot with the given specifica-
tions, use
pstext text.d −R-30/30/-10/20 −Jm 0.1i −P −B 5 −S 0.5p > plot.ps
To add a typeset figure caption for a 3-inch wide illustration, use
pstext −R 0/3/0/5 −JX 3i −O −H −m −N << EOF >> figure.ps

This is an optional header record
> 0 -0.5 12 0 4 LT 13p 3i j
@%5%Figure 1.@%% This illustration shows nothing useful, but it still needs
a figure caption. Highlighted in @;255/0/0;red@;; you can see the locations
of cities where it is @_impossible@_ to get any good Thai food; these are to be avoided.
EOF
WINDOWS REMARKS
Note that under Windows, the percent sign (%) is a variable indicator (like $ under Unix). To indicate a
plain percentage sign in a batch script you need to repeat it (%%); hence the font switching mechanism
(@%font% and @%%) may require twice the number of percent signs. This only applies to text inside a
script or that otherwise is processed by DOS. Data files that are opened and read by pstext do not need
such duplication.
BUGS
In paragraph mode, the presence of composite characters and other escape sequences may lead to unfortu-
nate word splitting.
The −N option does not adjust the BoundingBox information so you may have to post-process the Post-
Script output with epstool or ps2epsi to obtain a correct BoundingBox.
GMT 4.5.14 1 Nov 2015 4

SEE ALSO
GMT (1), gmtcolors(5), psbasemap(1), pslegend(1), psxy(1)
GMT 4.5.14 1 Nov 2015 5

PSWIGGLE(1) Generic Mapping Tools PSWIGGLE(1)
NAME
pswiggle − Plot anomaly along track on a map
SYNOPSIS
pswiggle xyz_files −Jparameters −Rwest/east/south/north[r] −Zscale [ −Aazimuth ] [ −B[p|s]parameters ]
[ −Ccenter ] [ −D[x]gap ] [ −Eazim/elev[+wlon/lat[/z]][+vx0/y0] ] [ −Gfill ] [ −H[i][nrec] ] [ −Jz|Zparame-
ters ] [ −Ifix_az ] [ −K ] [ −N ] [ −O ] [ −P ] [ −S[x]lon0/lat0/length[/units] ] [ −Tpen ] [
−U[just/dx/dy/][c|label] ] [ −V ] [ −Wpen ] [ −X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [ −ccopies ] [
−:[i|o] ] [ −bi[s|S|d|D[ncol]|c[var1/...]] ] [ −fcolinfo ] [ −m[i|o][flag] ]
DESCRIPTION
pswiggle reads (x,y,z) triplets from files [or standard input] and plots z as a function of distance along track.
This means that two consecutive (x,y) points define the local distance axis, and the local z axis is then per-
pendicular to the distance axis. The user may set a preferred positive anomaly plot direction, and if the
positive normal is outside the plus/minus 90 degree window around the preferred direction, then 180
degrees are added to the direction. Either the positive or the negative wiggle may be shaded. The resulting
PostScript code is written to standard output.
files List one or more file-names. If no files are given, pswiggle will read standard input.
CONIC PROJECTIONS:

GMT 4.5.14 1 Nov 2015 1


−Z Gives anomaly scale in data-units/distance-unit.
OPTIONS
−A Sets the preferred positive azimuth. Positive wiggles will "gravitate" towards that direction.
details.
−C Subtract center from the data set before plotting [0].
−D Means there is a data gap if 2 consecutive points are more than gap distance units apart. For geo-
graphic map projections the gap is assumed to be in km, else it is in the user’s units.
−G Set fill shade, color or pattern of positive wiggles [Default is black] (See SPECIFYING FILL
below).
skipped.
GMT 4.5.14 1 Nov 2015 2

−I Set a fixed azimuth projection for wiggles [Default uses track azimuth, but see −A].
−N Paint negative wiggles instead of positive [Default].
−S Draws a simple vertical scale centered on lon0/lat0. Use −Sx to specify cartesian coordinates
instead. length is in z units, append unit name for labeling
−T Draw track [Default is no track]. Append pen attributes to use [Defaults: width = 0.25p, color =
black, texture = solid]. (See SPECIFYING PENS below).
−W Draw wiggle outline [Default is no outline]. Append pen attributes to use [Defaults: width =
0.25p, color = black, texture = solid]. (See SPECIFYING PENS below).
size.
SPECIFYING PENS
‘.’.
GMT 4.5.14 1 Nov 2015 3

SPECIFYING FILL
SPECIFYING COLOR
EXAMPLES
To plot the magnetic anomaly stored in the file track.xym along track @ 1000 nTesla/cm (after removing a
mean value of 32000 nTesla), using a 15 -cm-wide Polar Stereographic map ticked every 5 degrees in Por-
trait mode, with positive anomalies in red on a blue track of width 0.25 points, use
pswiggle track.xym −R-20/10/-80/-60 −JS 0/90/15c −Z 1000 −B 5 −C 32000 −P −G red −T 0.25p,blue −S

1000 −V > track_xym.ps
BUGS
Sometimes the (x,y) coordinates are not printed with enough significant digits, so the local perpendicular to
the track swings around a lot. To see if this is the problem, you should do this:
awk ’{ if (NR > 1) print atan2(y-$1, x-$2); y=$1; x=$2; }’ yourdata.xyz | more
(note that output is in radians; on some machines you need "nawk" to do this). Then if these numbers jump
around a lot, you may do this:
awk ’{ print NR, $0 }’ yourdata.xyz | filter1d −Fb 5 −N 4/0 −−D_FORMAT=value > smoothed.xyz
and plot this data set instead.

SEE ALSO
GMT (1), gmtcolors(5), filter1d(1), psbasemap(1), splitxyz(1)
GMT 4.5.14 1 Nov 2015 4

PSXY(1) Generic Mapping Tools PSXY(1)
NAME
psxy − Plot lines, polygons, and symbols on maps
SYNOPSIS
psxy files −Jparameters −Rwest/east/south/north[r] [ −A[m|p] ] [ −B[p|s]parameters ] [ −Ccptfile ] [
−Ddx/dy ] [ −E[x|y|X|Y][n][cap][/[-|+]pen] ] [ −Gfill ] [ −H[i][nrec] ] [ −Iintens ] [ −K ] [ −L ] [ −N ] [ −O
] [ −P ] [ −S[symbol][size] ] [ −U[just/dx/dy/][c|label] ] [ −V ] [ −W[-|+][pen] ] [ −X[a|c|r][x-shift[u]] ] [
−Y[a|c|r][y-shift[u]] ] [ −:[i|o] ] [ −bi[s|S|d|D[ncol]|c[var1/...]] ] [ −ccopies ] [ −fcolinfo ] [
−g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] ] [ −m[flag] ]
DESCRIPTION
psxy reads (x,y) pairs from files [or standard input] and generates PostScript code that will plot lines, poly-
gons, or symbols at those locations on a map. If a symbol is selected and no symbol size given, then psxy
will interpret the third column of the input data as symbol size. Symbols whose size is <= 0 are skipped. If
no symbols are specified then the symbol code (see −S below) must be present as last column in the input.
Multiple segment files may be plotted using the −m option. If −S is not used, a line connecting the data
points will be drawn instead. To explicitly close polygons, use −L. Select a fill with −G. If −G is set, −W
will control whether the polygon outline is drawn or not. If a symbol is selected, −G and −W determines
the fill and outline/no outline, respectively. The PostScript code is written to standard output.
files List one or more file-names. If no files are given, psxy will read standard input. Use −T to ignore
all input files, including standard input (see below).
CONIC PROJECTIONS:

GMT 4.5.14 1 Nov 2015 1


OPTIONS
−A By default line segments are drawn as great circle arcs. To draw them as straight lines, use the −A
flag. Alternatively, add m to draw the line by first following a meridian, then a parallel. Or append
p to start following a parallel, then a meridian. (This can be practical to draw a lines along paral-
lels, for example).
details.
−C Give a color palette file. If −S is set, let symbol fill color be determined by the z-value in the third
column. Additional fields are shifted over by one column (optional size would be 4th rather than
3rd field, etc.). If −S is not set, then psxy expects the user to supply a multisegment line or poly-
gon file (requires −m) where each segment header contains a −Zval string. The val will control
the color of the line or polygon (if −L is set) via the cpt file.
−D Offset the plot symbol or line locations by the given amounts dx/dy [Default is no offset]. If dy is
not given it is set equal to dx.
−E Draw error bars. Append x and/or y to indicate which bars you want to draw (Default is both x
and y). The x and/or y errors must be stored in the columns after the (x,y) pair [or (x,y,size)
triplet]. The cap parameter indicates the length of the end-cap on the error bars [0.25c (or 0.1i)].
Pen attributes for error bars may also be set (see SPECIFYING PENS below) [Defaults: width =
GMT 4.5.14 1 Nov 2015 2

0.25p, color = black, texture = solid]. A leading + will use the lookup color (via −C) for both
symbol fill and error pen color, while a leading - will set error pen color and turn off symbol fill.
If upper case X and/or Y is used we will instead draw "box-and-whisker" (or "stem-and-leaf")
symbols. The x (or y) coordinate is then taken as the median value, and 4 more columns are
expected to contain the minimum (0% quantile), the 25% quantile, the 75% quantile, and the max-
imum (100% quantile) values. The 25-75% box may be filled by using −G. If n is appended to X
(or Y) we draw a notched "box-and-whisker" symbol where the notch width reflects the uncer-
tainty in the median. Then a 5th extra data column is expected to contain the number of points in
the distribution.
−G Select color or pattern for filling of symbols or polygons [Default is no fill]. (See SPECIFYING
FILL below).
Note when −m is chosen, psxy will search for −G and −W strings in all the subheaders and let any
values thus found over-ride the command line settings (see −m below).
skipped.
−I Use the supplied intens value (nominally in the -1 to + 1 range) to modulate the fill color by simu-
lating illumination [none].
−L Force closed polygons: connect the endpoints of the line-segment(s) and draw polygons. Also, in
concert with −C, −m, and −Z settings in the headers will use the implied color for polygon fill
[Default is polygon pen color].
−N Do NOT skip symbols that fall outside map border [Default plots points inside border only]. The
option does not apply to lines and polygons which are always clipped to the map region.
−S Plot symbols. If present, size is symbol size in the unit set in .gmtdefaults4 (unless c, i, m, or p is
appended). If size is not given it is expected in the third (or 4th if −C is used) column. Any addi-
tional fields are shifted over by one column. If the symbol code (see below) is not given it will be
read from the last column in the input data; this cannot be used in conjunction with −b. Option-
ally, append c, i, m, p to indicate that the size information in the input data is in units of cm, inch,
meter, or point, respectively [Default is MEASURE_UNIT]. Note: if you give both size and sym-
bol via the input file you must use MEASURE_UNIT to indicate the units used for the symbol
size.
The uppercase symbols A, C, D, G, H, I, N, S, T are normalized to have the same area as a circle
with diameter size, while the size of the corresponding lowercase symbols refers to the diameter of
a circumscribed circle. Choose between these symbol codes:
−S- x-dash (-). size is the length of a short horizontal line segment.
−S+ plus (+). size is diameter of circumscribing circle.
−Sa star. size is diameter of circumscribing circle.
−Sb Vertical bar extending from base to y. size is bar width. Append u if size is in x-units [Default is
plot-distance units]. By default, base = ymin. Append bbase to change this value.
−SB Horizontal bar extending from base to x. size is bar width. Append u if size is in y-units [Default
is plot-distance units]. By default, base = xmin. Append bbase to change this value.
−Sc circle. size is diameter of circle.
−Sd diamond. size is diameter of circumscribing circle.
GMT 4.5.14 1 Nov 2015 3

−Se ellipse. Direction (in degrees counter-clockwise from horizontal), major_axis, and minor_axis
must be found in columns 3, 4, and 5.
−SE Same as −Se, except azimuth (in degrees east of north) should be given instead of direction. The
azimuth will be mapped into an angle based on the chosen map projection (−Se leaves the direc-
tions unchanged.) Furthermore, the axes lengths must be given in km instead of plot-distance
units. An exception occurs for a linear projection in which we assume the ellipse axes are given in
the same units as −R.
−Sf front. −Sfgap/size[dir][type][:offset]. Supply distance gap between symbols and symbol size. If
gap is negative, it is interpreted to mean the number of symbols along the front instead. Append
dir to plot symbols on the left or right side of the front [Default is centered]. Append type to spec-
ify which symbol to plot: box, circle, fault, slip, or triangle. [Default is fault]. Slip means left-lat-
eral or right-lateral strike-slip arrows (centered is not an option). Append :offset to offset the first
symbol from the beginning of the front by that amount [Default is 0].
−Sg octagon. size is diameter of circumscribing circle.
−Sh hexagon. size is diameter of circumscribing circle.
−Si inverted triangle. size is diameter of circumscribing circle.
−Sj Rotated rectangle. Direction (in degrees counter-clockwise from horizontal), x-dimension, and y-
dimension must be found in columns 3, 4, and 5.
−SJ Same as −Sj, except azimuth (in degrees east of north) should be given instead of direction. The
azimuth will be mapped into an angle based on the chosen map projection (−Sj leaves the direc-
tions unchanged.) Furthermore, the dimensions must be given in km instead of plot-distance units.
An exception occurs for a linear projection in which we assume the dimensions are given in the
same units as −R.
−Sk kustom symbol. Append <name>/size, and we will look for a definition file called <name>.def in
(1) the current directory or (2) in ˜/.gmt or (3) in $GMT_SHAREDIR/custom. The symbol as
defined in that file is of size 1.0 by default; the appended size will scale symbol accordingly. Users
may add their own custom *.def files; see CUSTOM SYMBOLS below.
−Sl letter or text string (less than 64 characters). Give size, and append /string after the size. Note that
the size is only approximate; no individual scaling is done for different characters. Remember to
escape special characters like *. Optionally, you may append %font to select a particular font
[Default is ANNOT_FONT_PRIMARY].
−Sm math angle arc, optionally with one or two arrow heads. The size is the radius of the arc. Start
and stop directions (in degrees counter-clockwise from horizontal) for arc must be found in col-
umns 3 and 4. Use −Smf to add arrow head at first angle, −Sml for arrow head at last angle, and
−Smb for both [Default is no arrow heads].
−Sn pentagon. size is diameter of circumscribing circle.
−Sp point. No size needs to be specified (1 pixel is used).
−Sq quoted line, i.e., lines with annotations such as contours. Append [d|D|f|l|L|n|x|X]info[:labelinfo].
The required argument controls the placement of labels along the quoted lines. Choose among
five controlling algorithms:
ddist[c|i|m|p] or Ddist[d|e|k|m|n]
fffile.d Reads the ascii file ffile.d and places labels at locations in the file that matches locations
along the quoted lines. Inexact matches and points outside the region are skipped.
GMT 4.5.14 1 Nov 2015 4

l|Lline1[,line2,...]
ments. Labels will be placed where these lines intersect the quoted lines. The format of
each line specification is start_lon/start_lat/stop_lon/stop_lat. Both start_lon/start_lat
and stop_lon/stop_lat can be replaced by a 2-character key that uses the justification for-
mat employed in pstext to indicate a point on the map, given as [LCR][BMT].
L will interpret the point pairs as defining great circles [Default is straight line].
n|Nn_label
Specifies the number of equidistant labels for quoted lines line [1]. Upper case N starts
labeling exactly at the start of the line [Default centers them along the line]. N-1 places
one justified label at start, while N+1 places one justified label at the end of quoted lines.
Optionally, append /min_dist[c|i|m|p] to enforce that a minimum distance separation
between successive labels is enforced.
x|Xxfile.d
Reads the multi-segment file xfile.d and places labels at the intersections between the
quoted lines and the lines inxfile.d. X will resample the lines first along great-circle arcs.
The optional labelinfo controls the specifics of the label formatting and consists of a concatenated
string made up of any of the following control arguments:
+aangle
+cdx[/dy]
quoted line setup.
+g[color]
+kcolor
COLOR below).
GMT 4.5.14 1 Nov 2015 5

option.
+ndx[/dy]
+p[pen]
below).
+rmin_rad
0].
+=prefix
−Sr rectangle. No size needs to be specified, but the x- and y-dimensions must be found in columns 3
and 4.
−Ss square. size is diameter of circumscribing circle.
−St triangle. size is diameter of circumscribing circle.
−Sv vector. Direction (in degrees counter-clockwise from horizontal) and length must be found in col-
umns 3 and 4. size, if present, will be interpreted as arrowwidth/headlength/headwidth [Default
unit is 0.075c/0.3c/0.25c (or 0.03i/0.12i/0.1i)]. By default arrow attributes remains invariant to the
length of the arrow. To have the size of the vector scale down with decreasing size, append
nnorm, where vectors shorter than norm will have their attributes scaled by length/norm. To cen-
ter vector on balance point, use −Svb; to align point with the vector head, use −Svh; to align point
with the vector tail, use −Svt [Default]. To give the head point’s coordinates instead of direction
and length, use −Svs. Upper case B, H, T, S will draw a double-headed vector [Default is single
head].
−SV Same as −Sv, except azimuth (in degrees east of north) should be given instead of direction. The
azimuth will be mapped into an angle based on the chosen map projection (−Sv leaves the direc-
tions unchanged.)
−Sw pie wedge. Start and stop directions (in degrees counter-clockwise from horizontal) for pie slice
must be found in columns 3 and 4.
−SW Same as −Sw, except azimuths (in degrees east of north) should be given instead of the two direc-
tions. The azimuths will be mapped into angles based on the chosen map projection (−Sw leaves
the directions unchanged.)
GMT 4.5.14 1 Nov 2015 6

−Sx cross (x). size is diameter of circumscribing circle.

−Sy y-dash (|). size is the length of a short vertical line segment.
−T Ignore all input files, including standard input. This is the same as specifying /dev/null (or NUL
for Windows users) as input file. Use this to activate only the options that are not related to plot-
ting of lines or symbols, such as psxy −R −J −O −T to terminate a sequence of GMT plotting
commands without producing any plotting output.
−W Set pen attributes for lines or the outline of symbols [Defaults: width = 0.25p, color = black, tex-
ture = solid]. A leading + will use the lookup color (via −C) for both symbol fill and outline pen
color, while a leading - will set outline pen color and turn off symbol fill. (See SPECIFYING
PENS below).
size.
append var1/var2/... to specify the variables to be read. [Default is the required number of col-
umns given the chosen settings].
line break. Issue an additional −ga to indicate that all criteria must be met instead. The −g option
is ignored if −S is set.
GMT 4.5.14 1 Nov 2015 7

−m Multiple segment file. Segments are separated by a record whose first character is flag [Default is
’>’]. On these segment header records one or more of the following options can be added:
−Gfill Use the new fill and turn filling on
−G- Turn filling off
−G+ Revert to default fill (none if not set on command line)
−Wpen Use the new pen and turn outline on
−W- Turn outline off
−W+ Revert to default pen (none if not set on command line)
−Zzval Obtain fill via cpt lookup using z-value zval
−ZNaN Get the NaN color from the cpt file
SPECIFYING PENS
‘.’.
SPECIFYING FILL
SPECIFYING COLOR
EXAMPLES
To plot solid red circles (diameter = 0.25 cm) at the positions listed in the file DSDP.xy on a Mercator map
at 5 cm/degree of the area 150E to 154E, 18N to 23N, with tickmarks every 1 degree and gridlines every 15
minutes, use
psxy DSDP.xy −R 150/154/18/23 −Jm 5c −Sc0.25c −G red −B 1g15m | lpr
To plot the xyz values in the file quakes.xyzm as circles with size given by the magnitude in the 4th column
and color based on the depth in the third using the color palette cpt on a linear map, use
psxy quakes.xyzm −R 0/1000/0/1000 −JX 6i −Sc −C cpt −B 200 > map.ps
To plot the file trench.xy on a Mercator map, with white triangles with sides 0.25 inch on the left side of the
line, spaced every 0.8 inch, use
psxy trench.xy −R 150/200/20/50 −Jm 0.15i −Sf0.8i/0.1ilt −G white −W −B 10 | lpr br
To plot the data in the file misc.d as symbols determined by the code in the last column, and with size given
by the magnitude in the 4th column, and color based on the third column via the color palette cpt on a lin-
ear map, use
psxy misc.d −R 0/100/-50/100 −JX 6i −S −C cpt −B 20 > t.ps
GMT 4.5.14 1 Nov 2015 8

CUSTOM SYMBOLS
psxy and psxyz allows users to define and plot their own custom symbols. This is done by encoding the
symbol using a simple plotting code described below. Put all the plotting codes for your new symbol in a
file whose extension must be .def; you may then address the symbol without giving the extension (e.g., the
symbol file tsunami.def is used by specifying −Sktsunami/size. The definition file can contain any number
of plot code records, as well as blank lines and comment lines (starting with #). psxy and psxyz will look
for the definition files in (1) the current directory, (2) the ˜/.gmt directory, and (3) the
$GMT_SHAREDIR/custom directory, in that order. Freeform polygons (made up of straight line seg-
ments and arcs of circles) can be designed - these polygons can be painted and filled with a pattern. Other
standard geometric symbols can also be used. Generate freeform polygons by starting with an anchor point
(append [ −Wpen ] and [ −Gfill ] to indicate pen and fill attributes):
x0 y0 M
and draw a straight line from the current point to the next point with
x y D
or add an arc by using
xc yc r dir1 dir2 A
When a record other than the D or A is encountered, the polygon is closed and considered complete. The
optional pen and fill setting hardwires particular values for this feature. If not present the polygon’s charac-
teristics are determined by the command line settings for pen and fill. To deactivate fill or outline for any
given polygon, give −G− or −W−. To add other geometric shapes to your custom symbol, add any number
of the following plot code records (each accepts the optional [ −Wpen ] and [ −Gfill ] at the end):
circle: x y size c
cross: x y size x
diamond: x y size d
ellipse: x y dir major minor e
hexagon: x y size h
invtriangle: x y size i
letter: x y size string l
octagon: x y size g
pentagon: x y size n
plus: x y size +
rect: x y xwidth ywidth r
square: x y size s
star: x y size a
triangle: x y size t
wedge: x y radius dir1 dir2 w
x-dash: x y size -
y-dash: x y size y
When designing your symbol, the x, y and other dimensions are relative to a symbol of size 1, and all the
dimensions will be scaled by the actual symbol size chosen at run-time. To design a symbol, make a grid
paper with psbasemap −R-0.5/0.5/-0.5/0.5 −JX 4i −Ba 0.1g0.05 −P > grid.ps and draw your symbol, cen-
tering it on (0,0). For examples of symbols, see the set supplied with GMT in $GMT_SHAREDIR/cus-
tom.
BUGS
Script output with ps2raster -A to obtain the correct BoundingBox.
psxy cannot handle filling of polygons that contain the south or north pole. For such a polygon, make a
copy and split it into two and make each explicitly contain the polar point. The two polygons will combine
to give the desired effect when filled; to draw outline use the original polygon.
SEE ALSO
GMT (1), gmtcolors(5), psbasemap(1), psxyz(1)
GMT 4.5.14 1 Nov 2015 9

PSXYZ(1) Generic Mapping Tools PSXYZ(1)
NAME
psxyz − Plot lines, polygons, and symbols in 3-D
SYNOPSIS
psxyz files −Jparameters −Jz|Zparameters −Rwest/east/south/north[/zmin/zmax][r] [ −B[p|s]parameters ]
[ −Ccptfile ] [ −Ddx/dy[dz] ] [ −Eazim/elev[+wlon/lat[/z]][+vx0/y0] ] [ −Gfill ] [ −H[i][nrec] ] [ −Iintens ] [
−K ] [ −L ] [ −N ] [ −O ] [ −P ] [ −Q ] [ −S[symbol][size] ] [ −U[just/dx/dy/][c|label] ] [ −V ] [
−W[-|+][pen] ] [ −X[a|c|r][x-shift[u]] ] [ −Y[a|c|r][y-shift[u]] ] [ −Zzlevel ] [ −:[i|o] ] [
−bi[s|S|d|D[ncol]|c[var1/...]] ] [ −ccopies ] [ −fcolinfo ] [ −g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] ] [ −m[flag] ]
DESCRIPTION
psxyz reads (x,y,z) triplets from files [or standard input] and generates PostScript code that will plot lines,
polygons, or symbols at those locations in 3-D. If a symbol is selected and no symbol size given, then
psxyz will interpret the fourth column of the input data as symbol size. Symbols whose size is <= 0 are
skipped. If no symbols are specified then the symbol code (see −S below) must be present as last column in
the input. Multiple segment files may be plotted using the −m option. If −S is not used, a line connecting
the data points will be drawn instead. To explicitly close polygons, use −L. Select a fill with −G. If −G is
set, −W will control whether the polygon outline is drawn or not. If a symbol is selected, −G and −W
determines the fill and outline/no outline, respectively. The PostScript code is written to standard output.
files List one or more file-names. If no files are given, psxyz will read standard input.
CONIC PROJECTIONS:

GMT 4.5.14 1 Nov 2015 1


OPTIONS
details.
−C Give a color palette file. If −S is set, let symbol fill color be determined by the t-value in the
fourth column. Additional fields are shifted over by one column (optional size would be in 5th
rather than 4th field, etc.). If −S is not set, then psxyz expects the user to supply a multisegment
line or polygon file (requires −m) where each segment header contains a −Zval string. The val
will control the color of the line or polygon (if −L is set) via the cpt file.
−D Offset the plot symbol or line locations by the given amounts dx/dy[dz] [Default is no offset].
−G Select color or pattern for filling of symbols or polygons [Default is no fill]. (See SPECIFYING
FILL below).
Note when −m is chosen, psxyz will search for −G and −W strings in all the subheaders and let
any values thus found over-ride the command line settings (see −m below).
GMT 4.5.14 1 Nov 2015 2

skipped.
−I Use the supplied intens value (nominally in the -1 to + 1 range) to modulate the fill color by simu-
lating illumination [none].
−L Force closed polygons: connect the endpoints of the line-segment(s) and draw polygons. Also, in
concert with −C, −m, and −Z settings in the headers will use the implied color for polygon fill
[Default is polygon pen color]. −N Do NOT skip symbols that fall outside map border [Default
plots points inside border only].
−Q Turn off the automatic sorting of items based on their distance from the viewer. The default is to
sort the items so that items in the foreground are plotted after items in the background.
−S Plot symbols. If present, size is symbol size in the unit set in .gmtdefaults4 (unless c, i, m, or p is
appended). If the symbol code (see below) is not given it will be read from the last column in the
input data; this cannot be used in conjunction with −b. Optionally, append c, i, m, p to indicate
that the size information in the input data is in units of cm, inch, meter, or point, respectively
[Default is MEASURE_UNIT]. Note: if you give both size and symbol via the input file you
must use MEASURE_UNIT to indicate the units used for the symbol size. The uppercase sym-
bols A, C, D, G, H, I, N, S, T are normalized to have the same area as a circle with diameter size,
while the size of the corresponding lowercase symbols refers to the diameter of a circumscribed
circle. Choose between these symbol codes:
−S- x-dash (-). size is the length of a short horizontal (x-dir) line segment.
−S+ plus (+). size is diameter of circumscribing circle.
−Sa star. size is diameter of circumscribing circle.
−Sb Vertical bar extending from base to y. size is bar width. Append u if size is in x-units [Default is
plot-distance units]. By default, base = ymin. Append bbase to change this value.
−SB Horizontal bar extending from base to x. size is bar width. Append u if size is in y-units [Default
is plot-distance units]. By default, base = xmin. Append bbase to change this value.
−Sc circle. size is diameter of circle.
−Sd diamond. size is diameter of circumscribing circle.
−Se ellipse. Direction (in degrees counter-clockwise from horizontal), major_axis, and minor_axis
must be found in columns 4, 5, and 6.
−SE Same as −Se, except azimuth (in degrees east of north) should be given instead of direction. The
azimuth will be mapped into an angle based on the chosen map projection (−Se leaves the direc-
tions unchanged.) Furthermore, the axes lengths must be given in km instead of plot-distance
units. An exception occurs for a linear projection in which we assume the ellipse axes are given in
the same units as −R.
−Sf front. −Sfgap/size[dir][type][:offset]. Supply distance gap between symbols and symbol size. If
gap is negative, it is interpreted to mean the number of symbols along the front instead. Append
dir to plot symbols on the left or right side of the front [Default is centered]. Append type to spec-
ify which symbol to plot: box, circle, fault, slip, or triangle. [Default is fault]. Slip means left-lat-
eral or right-lateral strike-slip arrows (centered is not an option). Append :offset to offset the first
symbol from the beginning of the front by that amount [Default is 0].
GMT 4.5.14 1 Nov 2015 3

−Sg octagon. size is diameter of circumscribing circle.

−Sh hexagon. size is diameter of circumscribing circle.
−Si inverted triangle. size is diameter of circumscribing circle.
−Sj Rotated rectangle. Direction (in degrees counter-clockwise from horizontal), x-dimension, and y-
dimension must be found in columns 4, 5, and 6.
−SJ Same as −Sj, except azimuth (in degrees east of north) should be given instead of direction. The
azimuth will be mapped into an angle based on the chosen map projection (−Sj leaves the direc-
tions unchanged.) Furthermore, the dimensions must be given in km instead of plot-distance units.
An exception occurs for a linear projection in which we assume the dimensions are given in the
same units as −R.
−Sk kustom symbol. Append <name>/size, and we will look for a definition file called <name>.def in
(1) the current directory or (2) in ˜/.gmt or (3) in $GMT_SHAREDIR/custom. The symbol as
defined in that file is of size 1.0 by default; the appended size will scale symbol accordingly. The
symbols are plotted in the x-y plane. Users may add their own custom *.def files; see CUSTOM
SYMBOLS in the psxy man page.
−Sl letter or text string (less than 64 characters). Give size, and append /string after the size. Note that
the size is only approximate; no individual scaling is done for different characters. Remember to
escape special characters like *. Optionally, you may append %font to select a particular font
[Default is ANNOT_FONT_PRIMARY].
−Sm math angle arc, optionally with one or two arrow heads [NOT IMPLEMENTED YET]. The size
is the radius of the arc. Start and stop directions (in degrees counter-clockwise from horizontal)
for arc must be found in columns 3 and 4. Use −Smf to add arrow head at first angle, −Sml for
arrow head at last angle, and −Smb for both [Default is no arrow heads].
−Sn pentagon. size is diameter of circumscribing circle.
−So column (3-D) extending from base to z. size sets base width (Use xsize/ysize if not the same).
Append u if size is in x-units [Default is plot-distance units]. If no size is given we expect both
xsize and ysize as two extra data columns. By default, base = 0. Append bbase to change this
value. The facet colors will be modified to simulate shading. Use −SO to disable such 3-D illumi-
nation.
−Sp point. No size needs to be specified (1 pixel is used).
−Sq quoted line, i.e., lines with annotations such as contours. It is assumed that each individual line
has a constant z level (i.e., each line must lie in the x-y plane). Append [d|f|n|l|x]info[:labelinfo].
The required argument controls the placement of labels along the quoted lines. Choose among
five controlling algorithms:
ddist[c|i|m|p] or Ddist[d|e|k|m|n]
fffile.d Reads the ascii file ffile.d and places labels at locations in the file that matches locations
along the quoted lines. Inexact matches and points outside the region are skipped.
l|Lline1[,line2,...]
ments. Labels will be placed where these lines intersect the quoted lines. The format of
each line specification is start_lon/start_lat/stop_lon/stop_lat. Both start_lon/start_lat
and stop_lon/stop_lat can be replaced by a 2-character key that uses the justification for-
mat employed in pstext to indicate a point on the map, given as [LCR][BMT].
L will interpret the point pairs as defining great circles [Default is straight line].
GMT 4.5.14 1 Nov 2015 4

n|Nn_label
Specifies the number of equidistant labels for quoted lines line [1]. Upper case N starts
labeling exactly at the start of the line [Default centers them along the line]. N-1 places
one justified label at start, while N+1 places one justified label at the end of quoted lines.
Optionally, append /min_dist[c|i|m|p] to enforce that a minimum distance separation
between successive labels is enforced.
x|Xxfile.d
Reads the multi-segment file xfile.d and places labels at the intersections between the
quoted lines and the lines inxfile.d. X will resample the lines first along great-circle arcs.
The optional labelinfo controls the specifics of the label formatting and consists of a concatenated
string made up of any of the following control arguments:
+aangle
+cdx[/dy]
quoted line setup.
+g[color]
+kcolor
COLOR below).
option.
+ndx[/dy]
GMT 4.5.14 1 Nov 2015 5

+p[pen]
below).
+rmin_rad
0].
+=prefix
−Sr rectangle. No size needs to be specified, but the x- and y-dimensions must be found in columns 4
and 5.
−Ss square. size is diameter of circumscribing circle.
−St triangle. size is diameter of circumscribing circle.
−Su cube (3-D). size sets length of all sides. Append u if size is in x-units [Default is plot-distance
units]. The facet colors will be modified to simulate shading. Use −SU to disable such 3-D illu-
mination.
−Sv vector. Direction and length must be found in columns 4 and 5 (this is a vector in the horizontal
plane). size, if present, will be interpreted as arrowwidth/headlength/headwidth [Default unit is
0.075c/0.3c/0.25c (or 0.03i/0.12i/0.1i)]. By default arrow attributes remains invariant to the length
of the arrow. To have the size of the vector scale down with decreasing size, append nnorm, where
vectors shorter than norm will have their attributes scaled by length/norm. To center vector on bal-
ance point, use −Svb; to align point with the vector head, use −Svh; to align point with the vector
tail, use −Svt [Default]. To give the head point’s x, y, z coordinates instead of direction and length,
use −Svs. Upper case B, H, T, S will draw a double-headed vector [Default is single head].
−SV Same as −Sv, except azimuth should be given instead of direction. The azimuth will be mapped
into an angle based on the chosen map projection (−Sv leaves the directions unchanged.)
−Sw pie wedge. Start and stop directions (in degrees counter-clockwise from horizontal) for pie slice
must be found in columns 4 and 5.
−SW Same as −Sw, except azimuths (in degrees east of north) should be given instead of the two direc-
tions. The azimuths will be mapped into angles based on the chosen map projection (−Sw leaves
the directions unchanged.)
−Sx cross (x). size is diameter of circumscribing circle.
−Sy y-dash (|). size is the length of a short horizontal (y-dir) line segment.
−Sz zdash. size is the length of a short vertical (z-dir) line segment.
GMT 4.5.14 1 Nov 2015 6

−W Set pen attributes for lines or the outline of symbols [Defaults: width = 1, color = black, texture =
solid]. A leading + will use the lookup color (via −C) for both symbol fill and outline pen color,
while a leading - will set outline pen color and turn off symbol fill. (See SPECIFYING PENS
below).
size.
−Z For 3-D projections: Sets the z-level of the basemap [lower end of z-range].
append var1/var2/... to specify the variables to be read. [Default is the required number of col-
umns given the chosen settings].
line break. Issue an additional −ga to indicate that all criteria must be met instead. The −g option
is ignored if −S is set.
−m Multiple segment file. Segments are separated by a record whose first character is flag [Default is
’>’]. On these segment header records one or more of the following options can be added:
−Gfill Use the new fill and turn filling on
−G- Turn filling off
−G+ Revert to default fill (none if not set on command line)
−Wpen Use the new pen and turn outline on
−W- Turn outline off
−W+ Revert to default pen (none if not set on command line)
−Zzval Obtain fill via cpt lookup using z-value zval
−ZNaN Get the NaN color from the cpt file
GMT 4.5.14 1 Nov 2015 7

SPECIFYING PENS
‘.’.
SPECIFYING FILL
SPECIFYING COLOR
EXAMPLES
To plot blue columns (width = 1.25 cm) at the positions listed in the file heights.xyz on a 3-D projection of
the space (0−10), (0−10), (0−100), with tickmarks every 2, 2, and 10, viewing it from the southeast at 30
degree elevation, use:
psxyz heights.xyz −R 0/10/0/10/0/100 −Jx 1.25c −Jz 0.125c −So 1.25c −G blue −B 2:XLABEL:/2:YLA-
BEL:/10:ZLABEL::."3-D PLOT":15 −E 135/30 −Uc −W −P > heights.ps
BUGS
No hidden line removal is employed for polygons and lines. Symbols, however, are first sorted according
to their distance from the viewpoint so that nearby symbols will overprint more distant ones should they
project to the same x,y position.
psxyz cannot handle filling of polygons that contain the south or north pole. For such a polygon, make a
copy and split it into two and make each explicitly contain the polar point. The two polygons will combine
to give the desired effect when filled; to draw outline use the original polygon.
Script output with ps2raster -A to obtain the correct BoundingBox.
SEE ALSO
GMT (1), gmtcolors(5), psbasemap(1), psxy(1)
GMT 4.5.14 1 Nov 2015 8

SAMPLE1D(1) Generic Mapping Tools SAMPLE1D(1)
NAME
sample1d − Resampling of 1-D data sets
SYNOPSIS
sample1d infile [ −Fl|a|c|n ] [ −H[i][nrec] ] [ −Ixinc ] [ −Nknotfile ] [ −Sxstart ] [ −Tx_col ] [ −V ] [
−b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ] [ −m[i|o][flag] ]
DESCRIPTION
sample1d reads a multi-column ASCII [or binary] data set from file [or standard input] and interpolates the
timeseries/profile at locations where the user needs the values. The user must provide the column number
of the independent (monotonically increasing or decreasing) variable. Equidistant or arbitrary sampling
can be selected. All columns are resampled based on the new sampling interval. Several interpolation
schemes are available. Extrapolation outside the range of the input data is not supported.
infile This is a multi-column ASCII [of binary, see −b] file with one column containing the independent
variable (which must be monotonically in/de-creasing) and the remaining columns holding misc.
data values. If no file is provided, sample1d reads from standard input.
OPTIONS
−F Choose from l (Linear), a (Akima spline), c (natural cubic spline), and n (no interpolation: nearest
point) [Default is −Fa]. You may change the default interpolant; see INTERPOLANT in your
.gmtdefaults4 file.
skipped.
−I xinc defines the sampling interval. [Default is the separation between the first and second abscissa
point in the infile]
−N knotfile is an optional ASCII file with the x locations where the data set will be resampled in the
first column. Note: if −H is selected it applies to both infile and knotfile.
−S For equidistant sampling, xstart indicates the location of the first output value. [Default is the
smallest even multiple of xinc inside the range of infile]
−T Sets the column number of the independent variable [Default is 0 (first)].
append var1/var2/... to specify the variables to be read. [Default is 2 (or at least the number of
columns implied by −T)].
GMT 4.5.14 1 Nov 2015 1

SAMPLE1D(1) Generic Mapping Tools SAMPLE1D(1)

D_FORMAT setting.
CALENDAR TIME SAMPLING
If the abscissa are calendar times then you must use the −f option to indicate this. Furthermore, −I then
expects an increment in the current TIME_UNIT units. There is not yet support for variable intervals such
as months.
EXAMPLES
To resample the file profiles.tdgmb, which contains (time,distance,gravity,magnetics,bathymetry) records,
at 1km equidistant intervals using Akima’s spline, use
sample1d profiles.tdgmb −I 1 −Fa −T 1 > profiles_equi_d.tdgmb
To resample the file depths.dt at positions listed in the file grav_pos.dg, using a cubic spline for the interpo-
lation, use
sample1d depths.dt −N grav_pos.dg −Fc > new_depths.dt

SEE ALSO
GMT (1), filter1d(1)
GMT 4.5.14 1 Nov 2015 2

SPECTRUM1D(1) Generic Mapping Tools SPECTRUM1D(1)
NAME
spectrum1d − compute auto− [and cross− ] spectra from one [or two] timeseries.
SYNOPSIS
spectrum1d [ x[y]file ] −Ssegment_size] [ −C[xycnpago] ] [ −Ddt ] [ −Nname_stem ] [ −V ] [ −W ] [
DESCRIPTION
spectrum1d reads X [and Y] values from the first [and second] columns on standard input [or x[y]file].
These values are treated as timeseries X(t) [Y(t)] sampled at equal intervals spaced dt units apart. There
may be any number of lines of input. spectrum1d will create file[s] containing auto− [and cross− ] spectral
density estimates by Welch’s method of ensemble averaging of multiple overlapped windows, using stan-
dard error estimates from Bendat and Piersol.
The output files have 3 columns: f or w, p, and e. f or w is the frequency or wavelength, p is the spectral
density estimate, and e is the one standard deviation error bar size. These files are named based on
name_stem. If the −C option is used, up to eight files are created; otherwise only one (xpower) is written.
The files (which are ASCII unless −bo is set) are as follows:
name_stem.xpower
Power spectral density of X(t). Units of X * X * dt.
name_stem.ypower
Power spectral density of Y(t). Units of Y * Y * dt.
name_stem.cpower
Power spectral density of the coherent output. Units same as ypower.
name_stem.npower
Power spectral density of the noise output. Units same as ypower.
name_stem.gain
Gain spectrum, or modulus of the transfer function. Units of (Y / X).
name_stem.phase
Phase spectrum, or phase of the transfer function. Units are radians.
name_stem.admit
Admittance spectrum, or real part of the transfer function. Units of (Y / X).
name_stem.coh
(Squared) coherency spectrum, or linear correlation coefficient as a function of frequency. Dimen-
sionless number in [0, 1]. The Signal-to-Noise-Ratio (SNR) is coh / (1 - coh). SNR = 1 when coh
= 0.5.
REQUIRED ARGUMENTS
x[y]file ASCII (or binary, see −bi) file holding X(t) [Y(t)] samples in the first 1 [or 2] columns. If no file
is specified, spectrum1d will read from standard input.
−S segment_size is a radix-2 number of samples per window for ensemble averaging. The smallest
frequency estimated is 1.0/(segment_size * dt), while the largest is 1.0/(2 * dt). One standard error
in power spectral density is approximately 1.0 / sqrt(n_data / segment_size), so if segment_size =
256, you need 25,600 data to get a one standard error bar of 10%. Cross-spectral error bars are
larger and more complicated, being a function also of the coherency.
OPTIONS
−C Read the first two columns of input as samples of two timeseries, X(t) and Y(t). Consider Y(t) to
be the output and X(t) the input in a linear system with noise. Estimate the optimum frequency
response function by least squares, such that the noise output is minimized and the coherent output
and the noise output are uncorrelated. Optionally specify up to 8 letters from the set { x y c n p a
g o } in any order to create only those output files instead of the default [all]. x = xpower, y =
ypower, c = cpower, n = npower, p = phase, a = admit, g = gain, o = coh.
GMT 4.5.14 1 Nov 2015 1

SPECTRUM1D(1) Generic Mapping Tools SPECTRUM1D(1)
−D dt Set the spacing between samples in the timeseries [Default = 1].

−N name_stem Supply the name stem to be used for output files [Default = "spectrum"].
−W Write Wavelength rather than frequency in column 1 of the output file[s] [Default = frequency,
(cycles / dt)].
output file. [Default is 2 output columns].
D_FORMAT setting.
EXAMPLES
Suppose data.g is gravity data in mGal, sampled every 1.5 km. To write its power spectrum, in
mGal**2-km, to the file data.xpower, use
spectrum1d data.g −S 256 −D 1.5 −N data
Suppose in addition to data.g you have data.t, which is topography in meters sampled at the same points as
data.g. To estimate various features of the transfer function, considering data.t as input and data.g as out-
put, use
paste data.t data.g | spectrum1d −S 256 −D 1.5 −N data −C

SEE ALSO
GMT (1), grdfft(1)
REFERENCES
Bendat, J. S., and A. G. Piersol, 1986, Random Data, 2nd revised ed., John Wiley & Sons.
Welch, P. D., 1967, The use of Fast Fourier Transform for the estimation of power spectra: a method based
on time averaging over short, modified periodograms, IEEE Transactions on Audio and Electroacoustics,
Vol AU-15, No 2.
GMT 4.5.14 1 Nov 2015 2

SPLITXYZ(1) Generic Mapping Tools SPLITXYZ(1)
NAME
splitxyz − filter to divide (x,y,z[,distance,heading]) data into (x,y,z) track segments.
SYNOPSIS
splitxyz [ xyz[dh]file ] −Ccourse_change [ −Aazimuth/tolerance ] [ −Dminimum_distance ] [ −Fxy_fil-
ter/z_filter ] [ −Ggap_distance ] [ −H[i][nrec] ] [ −M ] [ −Nnamestem ] [ −Qflags ] [ −S ] [ −V ] [ −Z ] [
−:[i|o] ] [ −b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ]
DESCRIPTION
splitxyz reads a series of (x,y[,z]) records [or optionally (x,y,z,d,h); see −S option] from standard input [or
xyz[dh]file] and splits this into separate lists of (x,y[,z]) series, such that each series has a nearly constant
azimuth through the x,y plane. There are options to choose only those series which have a certain orienta-
tion, to set a minimum length for series, and to high− or low−pass filter the z values and/or the x,y values.
splitxyz is a useful filter between data extraction and pswiggle plotting, and can also be used to divide a
large x,y,z dataset into segments. The output is always in the ASCII format; input may be ASCII or binary
(see −b).
xyz[dh]file(s)
3 (but see −Z) [or 5] column ASCII file [or binary, see −b] holding (x,y,z[,d,h]) data values. To
use (x,y,z,d,h) input, sorted so that d is non-decreasing, specify the −S option; default expects
(x,y,z) only. If no file is specified, splitxyz will read from standard input.
−C Terminate a segment when a course change exceeding course_change degrees of heading is
detected.
OPTIONS
−A Write out only those segments which are within +/- tolerance degrees of azimuth in heading, mea-
sured clockwise from North, [0 - 360]. [Default writes all acceptable segments, regardless of ori-
entation].
−D Do not write a segment out unless it is at least minimum_distance units long [0]
−F Filter the z values and/or the x,y values, assuming these are functions of d coordinate. xy_filter
and z_filter are filter widths in distance units. If a filter width is zero, the filtering is not per-
formed. The absolute value of the width is the full width of a cosine−arch low−pass filter. If the
width is positive, the data are low−pass filtered; if negative, the data are high−pass filtered by sub-
tracting the low−pass value from the observed value. If z_filter is non−zero, the entire series of
input z values is filtered before any segmentation is performed, so that the only edge effects in the
filtering will happen at the beginning and end of the complete data stream. If xy_filter is
non−zero, the data is first divided into segments and then the x,y values of each segment are fil-
tered separately. This may introduce edge effects at the ends of each segment, but prevents a
low−pass x,y filter from rounding off the corners of track segments. [Default = no filtering].
−G Do not let a segment have a gap exceeding gap_distance; instead, split it into two segments.
[Default ignores gaps].
−M Use Map units. Then x,y are in degrees of longitude, latitude, distances are in kilometers, and
angles are azimuths. [Default: distances are cartesian in same units as x,y and angles are counter-
clockwise from horizontal].
−N Create Named output files, writing each segment to a separate file in the working directory named
namestem.profile#, where # increases consecutively from 1. [Default writes entire output to std-
out, separating segments by sub-headings that start with > marks].
−Q Specify your desired output using any combination of xyzdh, in any order. Do not space between
the letters. Use lower case. The output will be ASCII (or binary, see −bo) columns of values cor-
responding to xyzdh [Default is −Qxyzdh (−Qxydh if −Z is set)].
GMT 4.5.14 1 Nov 2015 1

SPLITXYZ(1) Generic Mapping Tools SPLITXYZ(1)
−S d and h is supplied. In this case, input contains x,y,z,d,h. [Default expects (x,y,z) input, and d,h
are computed from delta x, delta y, according to −M option]
−Z Data have x,y only (no z-column).
append var1/var2/... to specify the variables to be read. [Default is 2, 3, or 5 input columns as set
by −S, −Z].
output file. [Default is 1-5 output columns as set by −Q].
D_FORMAT setting.
EXAMPLES
Suppose you want to make a wiggle plot of magnetic anomalies on segments oriented approximately
east−west from a cruise called cag71 in the region −R300/315/12/20. You want to use a 100km low−pass
filter to smooth the tracks and a 500km high−pass filter to detrend the magnetic anomalies. Try this:
gmtlist cag71 −R 300/315/12/20 −F xyzdh | splitxyz −A 90/15 −F 100/-500 −M −D 100 −S −V | pswiggle

−R 300/315/12/20 −Jm 0.6 −Ba 5f1:.cag71: −T 1 −W 0.75p −G gray −Z 200 > cag71_wiggles.ps
MGD-77 users: For this application we recommend that you extract d, h from mgd77list rather than have
splitxyz compute them separately.
Suppose you have been given a binary, double-precision file containing lat, lon, gravity values from a sur-
vey, and you want to split it into profiles named survey.profile# (when gap exceeds 100 km). Try this:
splitxyz survey.bin −N survey −V −G 100 −D 100 −: −M −bi3

SEE ALSO
GMT (1), mgd77list(1), pswiggle(1)
GMT 4.5.14 1 Nov 2015 2

SURFACE(1) Generic Mapping Tools SURFACE(1)
NAME
surface − adjustable tension continuous curvature surface gridding algorithm
SYNOPSIS
surface [ xyzfile ] −Goutputfile.grd −Ixinc[unit][=|+][/yinc[unit][=|+]] −Rwest/east/south/north[r] [
−Aaspect_ratio ] [ −Cconvergence_limit ] [ −H[i][nrec] ] [ −Lllower ] [ −Luupper ] [ −Nmax_iterations ] [
−Q ] [ −Ssearch_radius[m] ] [ −Ttension_factor[i|b] ] [ −V[l] ] [ −Zover-relaxation_factor ] [ −:[i|o] ] [
−bi[s|S|d|D[ncol]|c[var1/...]] ] [ −fcolinfo ]
DESCRIPTION
surface reads randomly-spaced (x,y,z) triples from standard input [or xyzfile] and produces a binary grid
file of gridded values z(x,y) by solving:
(1 - T) * L (L (z)) + T * L (z) = 0
where T is a tension factor between 0 and 1, and L indicates the Laplacian operator. T = 0 gives the "mini-
mum curvature" solution which is equivalent to SuperMISP and the ISM packages. Minimum curvature
can cause undesired oscillations and false local maxima or minima (See Smith and Wessel, 1990), and you
may wish to use T > 0 to suppress these effects. Experience suggests T ˜ 0.25 usually looks good for poten-
tial field data and T should be larger (T ˜ 0.35) for steep topography data. T = 1 gives a harmonic surface
(no maxima or minima are possible except at control data points). It is recommended that the user pre-
process the data with blockmean, blockmedian, or blockmode to avoid spatial aliasing and eliminate
redundant data. You may impose lower and/or upper bounds on the solution. These may be entered in the
form of a fixed value, a grid with values, or simply be the minimum/maximum input data values.
xyzfile 3 column ASCII file [or binary, see −b] holding (x,y,z) data values. If no file is specified, surface
will read from standard input.
−G Output file name. Output is a binary 2-D .grd file. Note that the smallest grid dimension must be
at least 4.
GMT 4.5.14 1 Nov 2015 1

OPTIONS
−A Aspect ratio. If desired, grid anisotropy can be added to the equations. Enter aspect_ratio, where
dy = dx / aspect_ratio relates the grid dimensions. [Default = 1 assumes isotropic grid.]
−C Convergence limit. Iteration is assumed to have converged when the maximum absolute change in
any grid value is less than convergence_limit. (Units same as data z units). [Default is scaled to
0.1 percent of typical gradient in input data.]
−L Impose limits on the output solution. llower sets the lower bound. lower can be the name of a
grid file with lower bound values, a fixed value, d to set to minimum input value, or u for uncon-
strained [Default]. uupper sets the upper bound and can be the name of a grid file with upper
bound values, a fixed value, d to set to maximum input value, or u for unconstrained [Default].
−N Number of iterations. Iteration will cease when convergence_limit is reached or when number of
iterations reaches max_iterations. [Default is 250.]
−Q Suggest grid dimensions which have a highly composite greatest common factor. This allows sur-
face to use several intermediate steps in the solution, yielding faster run times and better results.
The sizes suggested by −Q can be achieved by altering −R and/or −I. You can recover the −R and
−I you want later by using grdsample or grdcut on the output of surface.
−S Search radius. Enter search_radius in same units as x,y data; append m to indicate minutes. This
is used to initialize the grid before the first iteration; it is not worth the time unless the grid lattice
is prime and cannot have regional stages. [Default = 0.0 and no search is made.]
−T Tension factor[s]. These must be between 0 and 1. Tension may be used in the interior solution
(above equation, where it suppresses spurious oscillations) and in the boundary conditions (where
it tends to flatten the solution approaching the edges). Using zero for both values results in a mini-
mum curvature surface with free edges, i.e., a natural bicubic spline. Use −Ttension_factori to set
interior tension, and −Ttension_factorb to set boundary tension. If you do not append i or b, both
will be set to the same value. [Default = 0 for both gives minimum curvature solution.]
−V Selects verbose mode, which will send progress reports to stderr [Default runs "silently"]. −Vl
will report the convergence after each iteration; −V will report only after each regional grid is
converged.
−Z Over-relaxation factor. This parameter is used to accelerate the convergence; it is a number
between 1 and 2. A value of 1 iterates the equations exactly, and will always assure stable conver-
gence. Larger values overestimate the incremental changes during convergence, and will reach a
solution more rapidly but may become unstable. If you use a large value for this factor, it is a
good idea to monitor each iteration with the −Vl option. [Default = 1.4 converges quickly and is
almost always stable.]
GMT 4.5.14 1 Nov 2015 2


EXAMPLES
To grid 5 by 5 minute gravity block means from the ASCII data in hawaii_5x5.xyg, using a tension_factor
= 0.25, a convergence_limit = 0.1 milligal, writing the result to a file called hawaii_grd.grd, and monitoring
each iteration, try:
surface hawaii_5x5.xyg −R 198/208/18/25 −I 5m −G hawaii_grd.grd −T 0.25 −C 0.1 −Vl

BUGS
surface will complain when more than one data point is found for any node and suggest that you run
blockmean, blockmedian, or blockmode first. If you did run blockm* and still get this message it usually
means that your grid spacing is so small that you need more decimals in the output format used by
blockm*. You may specify more decimal places by editing the parameter D_FORMAT in your .gmtde-
faults4 file prior to running blockm*, or choose binary input and/or output using single or double precision
storage.
Note that only gridline registration is possible with surface. If you need a pixel-registered grid you can
resample a gridline registered grid using grdsample −T.
SEE ALSO
blockmean(1), blockmedian(1), blockmode(1), GMT (1), nearneighbor(1), triangulate(1)
REFERENCES
Smith, W. H. F, and P. Wessel, 1990, Gridding with continuous curvature splines in tension, Geophysics,
55, 293−305.
GMT 4.5.14 1 Nov 2015 3

TREND1D(1) Generic Mapping Tools TREND1D(1)
NAME
trend1d − Fit a [weighted] [robust] polynomial [or Fourier] model for y = f(x) to xy[w] data.
SYNOPSIS
trend1d −Fxymrw −N[f]n_model[r] [ xy[w]file ] [ −Ccondition_number ] [ −H[i][nrec] ] [ −I[confi-
dence_level] ] [ −V ] [ −W ] [ −:[i|o] ] [ −b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ]
DESCRIPTION
trend1d reads x,y [and w] values from the first two [three] columns on standard input [or xy[w]file] and fits
a regression model y = f(x) + e by [weighted] least squares. The functional form of f(x) may be chosen as
polynomial or Fourier, and the fit may be made robust by iterative reweighting of the data. The user may
also search for the number of terms in f(x) which significantly reduce the variance in y.
REQUIRED ARGUMENTS
−F Specify up to five letters from the set {x y m r w} in any order to create columns of ASCII [or
binary] output. x = x, y = y, m = model f(x), r = residual y - m, w = weight used in fitting.
−N Specify the number of terms in the model, n_model, whether to fit a Fourier (−Nf) or polynomial
[Default] model, and append r to do a robust fit. E.g., a robust quadratic model is −N3r.
OPTIONS
xy[w]file
ASCII [or binary, see −b] file containing x,y [w] values in the first 2 [3] columns. If no file is
specified, trend1d will read from standard input.
−C Set the maximum allowed condition number for the matrix solution. trend1d fits a damped least
squares model, retaining only that part of the eigenvalue spectrum such that the ratio of the largest
eigenvalue to the smallest eigenvalue is condition_#. [Default: condition_# = 1.0e06. ].
skipped.
−I Iteratively increase the number of model parameters, starting at one, until n_model is reached or
the reduction in variance of the model is not significant at the confidence_level level. You may set
−I only, without an attached number; in this case the fit will be iterative with a default confidence
level of 0.51. Or choose your own level between 0 and 1. See remarks section.
−W Weights are supplied in input column 3. Do a weighted least squares fit [or start with these
weights when doing the iterative robust fit]. [Default reads only the first 2 columns.]
append var1/var2/... to specify the variables to be read. [Default is 2 (or 3 if −W is set) columns].
output file. [Default is 1-5 columns as given by −F].
GMT 4.5.14 1 Nov 2015 1


D_FORMAT setting.
REMARKS
If a Fourier model is selected, the domain of x will be shifted and scaled to [-pi, pi] and the basis functions
used will be 1, cos(x), sin(x), cos(2x), sin(2x), ... If a polynomial model is selected, the domain of x will
be shifted and scaled to [-1, 1] and the basis functions will be Chebyshev polynomials. These have a
numerical advantage in the form of the matrix which must be inverted and allow more accurate solutions.
The Chebyshev polynomial of degree n has n+1 extrema in [-1, 1], at all of which its value is either -1 or
+1. Therefore the magnitude of the polynomial model coefficients can be directly compared. NOTE: The
stable model coefficients are Chebyshev coefficients. The corresponding polynomial coefficients in a + bx
+ cxx + ... are also given in Verbose mode but users must realize that they are NOT stable beyond degree 7
or 8. See Numerical Recipes for more discussion. For evaluating Chebyshev polynomials, see gmtmath.
The −Nr (robust) and −I (iterative) options evaluate the significance of the improvement in model misfit
Chi-Squared by an F test. The default confidence limit is set at 0.51; it can be changed with the −I option.
The user may be surprised to find that in most cases the reduction in variance achieved by increasing the
number of terms in a model is not significant at a very high degree of confidence. For example, with 120
degrees of freedom, Chi-Squared must decrease by 26% or more to be significant at the 95% confidence
level. If you want to keep iterating as long as Chi-Squared is decreasing, set confidence_level to zero.
A low confidence limit (such as the default value of 0.51) is needed to make the robust method work. This
method iteratively reweights the data to reduce the influence of outliers. The weight is based on the Median
Absolute Deviation and a formula from Huber [1964], and is 95% efficient when the model residuals have
an outlier-free normal distribution. This means that the influence of outliers is reduced only slightly at each
iteration; consequently the reduction in Chi-Squared is not very significant. If the procedure needs a few
iterations to successfully attenuate their effect, the significance level of the F test must be kept low.
EXAMPLES
To remove a linear trend from data.xy by ordinary least squares, use:
trend1d data.xy −F xr −N 2 > detrended_data.xy
To make the above linear trend robust with respect to outliers, use:
trend1d data.xy −F xr −N 2r > detrended_data.xy
To find out how many terms (up to 20, say) in a robust Fourier interpolant are significant in fitting data.xy,
use:
trend1d data.xy −Nf 20r −I −V

SEE ALSO
GMT (1), gmtmath(1), grdtrend(1), trend2d(1)
REFERENCES
Huber, P. J., 1964, Robust estimation of a location parameter, Ann. Math. Stat., 35, 73-101.
Menke, W., 1989, Geophysical Data Analysis: Discrete Inverse Theory, Revised Edition, Academic Press,
San Diego.
GMT 4.5.14 1 Nov 2015 2

NAME
trend2d − Fit a [weighted] [robust] polynomial model for z = f(x,y) to xyz[w] data.
SYNOPSIS
trend2d −Fxyzmrw −Nn_model[r] [ xyz[w]file ] [ −Ccondition_number ] [ −H[i][nrec] ] [ −I[confi-
dence_level] ] [ −V ] [ −W ] [ −:[i|o] ] [ −b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ]
DESCRIPTION
trend2d reads x,y,z [and w] values from the first three [four] columns on standard input [or xyz[w]file] and
fits a regression model z = f(x,y) + e by [weighted] least squares. The fit may be made robust by iterative
reweighting of the data. The user may also search for the number of terms in f(x,y) which significantly
reduce the variance in z. n_model may be in [1,10] to fit a model of the following form (similar to
grdtrend):
m1 + m2*x + m3*y + m4*x*y + m5*x*x + m6*y*y + m7*x*x*x + m8*x*x*y + m9*x*y*y + m10*y*y*y.
The user must specify −Nn_model, the number of model parameters to use; thus, −N4 fits a bilinear trend,
−N6 a quadratic surface, and so on. Optionally, append r to perform a robust fit. In this case, the program
will iteratively reweight the data based on a robust scale estimate, in order to converge to a solution insensi-
tive to outliers. This may be handy when separating a "regional" field from a "residual" which should have
non-zero mean, such as a local mountain on a regional surface.
−F Specify up to six letters from the set {x y z m r w} in any order to create columns of ASCII [or
binary] output. x = x, y = y, z = z, m = model f(x,y), r = residual z - m, w = weight used in fitting.
−N Specify the number of terms in the model, n_model, and append r to do a robust fit. E.g., a robust
bilinear model is −N4r.
OPTIONS
xyz[w]file
ASCII [or binary, see −b] file containing x,y,z [w] values in the first 3 [4] columns. If no file is
specified, trend2d will read from standard input.
−C Set the maximum allowed condition number for the matrix solution. trend2d fits a damped least
squares model, retaining only that part of the eigenvalue spectrum such that the ratio of the largest
eigenvalue to the smallest eigenvalue is condition_#. [Default: condition_# = 1.0e06. ].
skipped.
−I Iteratively increase the number of model parameters, starting at one, until n_model is reached or
the reduction in variance of the model is not significant at the confidence_level level. You may set
−I only, without an attached number; in this case the fit will be iterative with a default confidence
level of 0.51. Or choose your own level between 0 and 1. See remarks section.
−W Weights are supplied in input column 4. Do a weighted least squares fit [or start with these
weights when doing the iterative robust fit]. [Default reads only the first 3 columns.]
append var1/var2/... to specify the variables to be read. [Default is 3 (or 4 if −W is set) input col-
umns].
GMT 4.5.14 1 Nov 2015 1

output file. [Default is 1-6 columns as set by −F].
REMARKS
The domain of x and y will be shifted and scaled to [-1, 1] and the basis functions are built from Chebyshev
polynomials. These have a numerical advantage in the form of the matrix which must be inverted and
allow more accurate solutions. In many applications of trend2d the user has data located approximately
along a line in the x,y plane which makes an angle with the x axis (such as data collected along a road or
ship track). In this case the accuracy could be improved by a rotation of the x,y axes. trend2d does not
search for such a rotation; instead, it may find that the matrix problem has deficient rank. However, the
solution is computed using the generalized inverse and should still work out OK. The user should check
the results graphically if trend2d shows deficient rank. NOTE: The model parameters listed with −V are
Chebyshev coefficients; they are not numerically equivalent to the m#s in the equation described above.
The description above is to allow the user to match −N with the order of the polynomial surface. For evalu-
ating Chebyshev polynomials, see grdmath.
The −Nn_modelr (robust) and −I (iterative) options evaluate the significance of the improvement in model
misfit Chi-Squared by an F test. The default confidence limit is set at 0.51; it can be changed with the −I
option. The user may be surprised to find that in most cases the reduction in variance achieved by increas-
ing the number of terms in a model is not significant at a very high degree of confidence. For example,
with 120 degrees of freedom, Chi-Squared must decrease by 26% or more to be significant at the 95% con-
fidence level. If you want to keep iterating as long as Chi-Squared is decreasing, set confidence_level to
zero.
A low confidence limit (such as the default value of 0.51) is needed to make the robust method work. This
method iteratively reweights the data to reduce the influence of outliers. The weight is based on the Median
Absolute Deviation and a formula from Huber [1964], and is 95% efficient when the model residuals have
an outlier-free normal distribution. This means that the influence of outliers is reduced only slightly at each
iteration; consequently the reduction in Chi-Squared is not very significant. If the procedure needs a few
iterations to successfully attenuate their effect, the significance level of the F test must be kept low.
D_FORMAT setting.
EXAMPLES
To remove a planar trend from data.xyz by ordinary least squares, use:
trend2d data.xyz −F xyr −N 2 > detrended_data.xyz
To make the above planar trend robust with respect to outliers, use:
trend2d data.xzy −F xyr −N 2r > detrended_data.xyz
To find out how many terms (up to 10) in a robust interpolant are significant in fitting data.xyz, use:
GMT 4.5.14 1 Nov 2015 2

trend2d data.xyz −N 10r −I −V

SEE ALSO
GMT (1), grdmath(1), grdtrend(1), trend1d(1)
REFERENCES
Huber, P. J., 1964, Robust estimation of a location parameter, Ann. Math. Stat., 35, 73-101.
Menke, W., 1989, Geophysical Data Analysis: Discrete Inverse Theory, Revised Edition, Academic Press,
San Diego.
GMT 4.5.14 1 Nov 2015 3

TRIANGULATE(1) Generic Mapping Tools TRIANGULATE(1)
NAME
triangulate − Perform optimal Delaunay triangulation and gridding of Cartesian data [method]
SYNOPSIS
triangulate infiles [ −Dx|y ] [ −Eempty ] [ −F ] [ −Ggrdfile ] [ −H[i][nrec] ] [
−Ixinc[unit][=|+][/yinc[unit][=|+]] ] [ −Jparameters ] [ −Q ] [ −Rwest/east/south/north[r] ] [ −V ] [ −Z ] [
−:[i|o] ] [ −b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ −f[i|o]colinfo ] [ −m[i|o][flag] ]
DESCRIPTION
triangulate reads one or more ASCII [or binary] files (or standard input) containing x,y[,z] and performs
Delaunay triangulation, i.e., it find how the points should be connected to give the most equilateral triangu-
lation possible. If a map projection (give −R and −J) is chosen then it is applied before the triangulation is
calculated. By default, the output is triplets of point id numbers that make up each triangle and is written to
standard output. The id numbers refer to the points position (line number, starting at 0 for the first line) in
the input file. As an option, you may choose to create a multiple segment file that can be piped through
psxy to draw the triangulation network. If −G −I are set a grid will be calculated based on the surface
defined by the planar triangles. The actual algorithm used in the triangulations is either that of Watson
[1982] [Default] or Shewchuk [1996] (if installed; type triangulate − to see which method is selected).
This choice is made during the GMT installation.
infiles Data files with the point coordinates in ASCII (or binary; see −b). If no files are given the stan-
dard input is read.
OPTIONS
−D Take either the x- or y-derivatives of surface represented by the planar facets (only used when −G
is set).
−E Set the value assigned to empty nodes when −G is set [NaN].
GMT Cookbook Appendix B on grid file formats.) Only valid with −G).
−G Use triangulation to grid the data onto an even grid (specified with −R −I). Append the name of
the output grid file. The interpolation is performed in the original coordinates, so if your triangles
are close to the poles you are better off projecting all data to a local coordinate system before
using triangulate (this is true of all gridding routines).
skipped.
−I x_inc [and optionally y_inc] sets the grid size for optional grid output (see −G). Append m to
indicate minutes or c to indicate seconds.
GMT 4.5.14 1 Nov 2015 1


CONIC PROJECTIONS:


−Q Output the edges of the Voronoi cells instead [Default is Delaunay triangle edges]. Requires both
−m and −R and is only available if linked with the Shewchuk [1996] library.
GMT 4.5.14 1 Nov 2015 2

−Z Controls whether binary data file has two or three columns [2]. Ignored if −b is not set.
output file. [Default is same as input]. Node ids are stored as binary 4-byte integer triplets. −bo
is ignored if −m is selected.
−m Output triangulation network as multiple line segments separated by a record whose first character
is flag [>]. To plot, use psxy with the −m option (see Examples).
D_FORMAT setting.
EXAMPLES
To triangulate the points in the file samples.xyz, store the triangle information in a binary file, and make a
grid for the given area and spacing, use
triangulate samples.xyz −bo −R 0/30/0/30 −I 2 −G surf.grd > samples.ijk
To draw the optimal Delaunay triangulation network based on the same file using a 15 -cm-wide Mercator
map, use
triangulate samples.xyz −m −R-100/-90/30/34 −JM 15c | psxy −m −R-100/-90/30/34 −JM 15c −W 0.5p
−B 1 > network.ps
To instead plot the Voronoi cell outlines, try

triangulate samples.xyz −m −Q −R-100/-90/30/34 −JM 15c | psxy −m −R-100/-90/30/34 −JM 15c −W
0.5p −B 1 > cells.ps
SEE ALSO
GMT (1), pscontour(1)
GMT 4.5.14 1 Nov 2015 3

REFERENCES
Watson, D. F., 1982, Acord: Automatic contouring of raw data, Comp. & Geosci., 8, 97−101.
Shewchuk, J. R., 1996, Triangle: Engineering a 2D Quality Mesh Generator and Delaunay Triangulator,
First Workshop on Applied Computational Geometry (Philadelphia, PA), 124-133, ACM, May 1996.
www.cs.cmu.edu/˜quake/triangle.html
GMT 4.5.14 1 Nov 2015 4

XYZ2GRD(1) Generic Mapping Tools XYZ2GRD(1)
NAME
xyz2grd − Converting an ASCII or binary table to grid file format
SYNOPSIS
xyz2grd xyzfile −Ggrdfile −Ixinc[unit][=|+][/yinc[unit][=|+]] −Rwest/east/south/north[r] [ −A[n|z|u|l] ] [
−Dxname/yname/zname/scale/offset/title/remark ] [ −E[nodata] ] [ −F ] [ −H[i][nrec] ] [ −Nnodata ] [
−S[zfile] ] [ −V ] [ −Z[flags] ] [ −:[i|o] ] [ −bi[s|S|d|D[ncol]|c[var1/...]] ] [ −fcolinfo ]
DESCRIPTION
xyz2grd reads a z or xyz table and creates a binary grid file. xyz2grd will report if some of the nodes are
not filled in with data. Such unconstrained nodes are set to a value specified by the user [Default is NaN].
Nodes with more than one value will be set to the average value. As an option (using −Z), a 1-column z-ta-
ble may be read assuming all nodes are present (z-tables can be in organized in a number of formats, see
−Z below.)
[xy]zfile
ASCII [or binary] file holding z or (x,y,z) values. xyz triplets do not have to be sorted (for binary
triplets, see −b). 1-column z tables must be sorted and the −Z must be set).
−G grdfile is the name of the binary output grid file. (See GRID FILE FORMAT below.)
OPTIONS
−A Add up multiple values that belong to the same node (same as −Az). Append n to simply count
the number of data points that were assigned to each node. Append l or u to find the lowest (mini-
mum) or upper (maximum) value at each node, respectively. [Default (no −A option) will calcu-
late mean value]. Ignored if −Z is given.
−D Give values for xname, yname, zname, scale, offset, title, and remark. To leave some of these val-
ues untouched, specify = as the value. Alternatively, to allow "/" to be part of one of the values,
use any non-alphanumeric character (and not the equal sign) as separator by both starting and end-
ing with it. For example: −D:xname:yname:zname:scale:offset:title:remark:
GMT 4.5.14 1 Nov 2015 1

−E Convert an ESRI ArcInfo ASCII interchange grid format file to a GMT grid. Append nodata
which is a data value that should be set to NaN in the grid [If we find the optional 6th record in the
file we will use it instead]. The values normally given by −R, −I, and −F are determined from the
ESRI header instead.
−N No data. Set nodes with no input xyz triplet to this value [Default is NaN]. For z-tables, this
option is used to replace z-values that equal nodata with NaN.
−S Swap the byte-order of the input only. No grid file is produced. You must also supply the −Z
option. The output is written to zfile (or stdout if not supplied).
−Z Read a 1-column ASCII [or binary] table. This assumes that all the nodes are present and sorted
according to specified ordering convention contained in flags. If incoming data represents rows,
make flags start with T(op) if first row is y = ymax or B(ottom) if first row is y = ymin. Then,
append L or R to indicate that first element is at left or right end of row. Likewise for column for-
mats: start with L or R to position first column, and then append T or B to position first element in
a row. For gridline registered grids: If data are periodic in x but the incoming data do not contain
the (redundant) column at x = xmax, append x. For data periodic in y without redundant row at y
= ymax, append y. Append sn to skip the first n number of bytes (probably a header). If the byte-
order needs to be swapped, append w. Select one of several data types (all binary except a):
A ASCII representation of one or more floating point values per record
a ASCII representation of a single item per record

c signed 1-byte character
u unsigned 1-byte character
h short 2-byte integer
H unsigned short 2-byte integer
i 4-byte integer
l long (4- or 8-byte) integer [architecture-dependent!]
f 4-byte floating point single precision
d 8-byte floating point double precision
Default format is scanline orientation of ASCII numbers: −ZTLa. Note that −Z only applies to
1-column input. The difference between A and a is that the latter can decode both dateTclock and
ddd:mm:ss[.xx] formats while the former is strictly for regular floating point values.
append var1/var2/... to specify the variables to be read. [Default is 3 input columns]. This option
only applies to xyz input files; see −Z for z tables.
GMT 4.5.14 1 Nov 2015 2

GRID FILE FORMATS
EXAMPLES
To create a grid file from the ASCII data in hawaii_grv.xyz, use
xyz2grd hawaii_grv.xyz −D degree/degree/mGal/1/0/"Hawaiian Gravity"/"GRS-80 Ellipsoid used" −G

hawaii_grv_new.grd −R 198/208/18/25 −I 5m −V
To create a grid file from the raw binary (3-column, single-precision) scanline-oriented data raw.b, use
xyz2grd raw.b −D m/m/m/1/0/=/= −G raw.grd −R 0/100/0/100 −I 1 −V −Z −b 3
To make a grid file from the raw binary USGS DEM (short integer) scanline-oriented data topo30. on the
NGDC global relief Data CD-ROM, with values of -9999 indicate missing data, one must on some machine
reverse the byte-order. On such machines (like Sun), use
xyz2grd topo30. −D m/m/m/1/0/=/= −G ustopo.grd −R 234/294/24/50 −I 30c −N-9999 −B −ZTLhw
Say you have received a binary file with 4-byte floating points that were written on a machine of different
byte-order than yours. You can swap the byte-order with
xyz2grd floats.bin −S new_floats.bin −V −Zf

SEE ALSO
GMT (1), grd2xyz(1), grdedit(1)
GMT 4.5.14 1 Nov 2015 3

GMT 2010

Uploaded by

Copyright:

Available Formats

GMT 2010

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

GMT 2010

Uploaded by

Copyright:

Available Formats

GMT(1) Generic Mapping Tools GMT(1)

GMT module module-options

blockmean L2 (x,y,z) data filter/decimator

GMT 4.5.14 1 Nov 2015 1

grdvector Plot vector fields from grid files

GMT 4.5.14 1 Nov 2015 2

GMT 4.5.14 1 Nov 2015 1

blockmean hawaii.xyg −R 198/208/18/25 −I 5m > hawaii_5x5.xyg

GMT 4.5.14 1 Nov 2015 2

GMT 4.5.14 1 Nov 2015 1

blockmedian hawaii_b.xyg −R 198/208/18/25 −I 5m −bi 3 > hawaii_5x5.xyg

blockmedian depths.xyz −Rg −I 5 −F −Eb > depths_5x5.txt

GMT 4.5.14 1 Nov 2015 2

GMT 4.5.14 1 Nov 2015 3

GMT 4.5.14 1 Nov 2015 1

blockmode hawaii_b.xyg −R 198/208/18/25 −I 5m −bi 3 > hawaii_5x5.xyg

GMT 4.5.14 1 Nov 2015 2

GMT 4.5.14 1 Nov 2015 1

filter1d cruise.gmtd −T 0/1.0e5/2000 −FG 10000 −N 4/3 −V > filtered_cruise.gmtd

filter1d v3312.dt −FM 50 −T 0/100000/25 −L 10 −S 0.3 > v3312_filt.dt

GMT 4.5.14 1 Nov 2015 2

GMT 4.5.14 1 Nov 2015 1

ASCII FORMAT PRECISION

project ship.xyg −Cox/oy −Tpx/py −S −F pz | sample1d −S−100 −I 1 > output.pg

GMT 4.5.14 1 Nov 2015 2

GMT 4.5.14 1 Nov 2015 1

guessing algorithm makes uses of FFTs.

gmt2rgb hawaii_grv.grd −C topo.cpt −G hawaii_grv_%c.grd

gmt2rgb radiation.ras −L r −G comp_%c.grd

GMT 4.5.14 1 Nov 2015 2

GMT 4.5.14 1 Nov 2015 1

GMT 4.5.14 1 Nov 2015 2

GMT 4.5.14 1 Nov 2015 1

GMT 4.5.14 1 Nov 2015 2

240 230 140 khaki

GMT 4.5.14 1 Nov 2015 3

148 0 211 darkviolet

GMT 4.5.14 1 Nov 2015 4

224 238 224 honeydew2

GMT 4.5.14 1 Nov 2015 5

110 123 139 lightsteelblue4

GMT 4.5.14 1 Nov 2015 6

118 238 0 chartreuse2

GMT 4.5.14 1 Nov 2015 7

139 115 85 burlywood4

GMT 4.5.14 1 Nov 2015 8

238 18 137 deeppink2

GMT 4.5.14 1 Nov 2015 9

GMT 4.5.14 1 Nov 2015 10

GMT 4.5.14 1 Nov 2015 11

130 130 130 grey51

GMT 4.5.14 1 Nov 2015 12

199 199 199 grey78

GMT 4.5.14 1 Nov 2015 13

GMT 4.5.14 1 Nov 2015 1

gmtconvert test.b −bis 4 > test.dat

gmtconvert test.d −m −bo > test.b

gmtconvert table.d −F 5,0 | psxy ...

gmtconvert results.b −F 8,4-6 -bi9s | psxy ...