grdcontour(1) GMT grdcontour(1)
NAME
grdcontour - Make contour map using a grid
SYNOPSIS
grdcontour grid -C[+]cont_int|cpt
-Jparameters [ -A[-|[+]annot_int][labelinfo] ] [ -B[p|s]parameters ]
[ -Dtemplate ] [ -F[l|r] ] [ -G[d|f|n|l|L|x|X]params ] [ -Jz|Zpa-
rameters ] [ -K ] [ -Llow/high ] [ -O ] [ -P ] [ -Qcut ] [
-Rwest/east/south/north[/zmin/zmax][+r] ] [ -Ssmoothfactor ] [
-T[+|-][+dgap[/length]][+l[labels]] ] [ -U[stamp] ] [ -V[level] ] [
-W[type]pen ][+c[l|f]] [ -Xx_offset ] [ -Yy_offset ] [ -Z[+s *fac-
tor*][+oshift][+p] ] [ -bobinary ] [ -donodata ] [ -ho[n] ] [ -pflags ]
[ -ttransp ]
Note: No space is allowed between the option flag and the associated
arguments.
DESCRIPTION
grdcontour reads a 2-D grid file and produces a contour map by tracing
each contour through the grid. PostScript code is generated and sent to
standard output. Various options that affect the plotting are avail-
able. Alternatively, the x/y/z positions of the contour lines may be
saved to one or more output files (or stdout) and no plot is produced.
REQUIRED ARGUMENTS
grid 2-D gridded data set to be contoured. (See GRID FILE FORMATS
below).
-C[+]cont_int
The contours to be drawn may be specified in one of three possi-
ble ways:
1. If cont_int has the suffix a.cpta and can be opened as a
file, it is assumed to be a CPT. The color boundaries are
then used as contour levels. If the CPT 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, it is expected to con-
tain contour levels in column 1 and a C(ontour) OR A(nnotate)
in col 2. The levels marked C (or c) are contoured, the lev-
els marked A (or a) are contoured and annotated. Optionally,
a third column may be present and contain the fixed annota-
tion angle for this contour level.
3. If no file is found, then cont_int is interpreted as a con-
stant contour interval. However, if prepended with the + sign
the cont_int is taken as meaning draw that single contour.
The -A option offers the same possibility so they may be used
together to plot a single annotated contour and another sin-
gle non-annotated contour, as in aa| -A+10 -C+5a that plots
an annotated 10 contour and an non-annotated 5 contour. 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.
-Jparameters (more a|)
Select map projection.
OPTIONAL ARGUMENTS
-A[-|[+]annot_int][labelinfo]
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. Alternatively
prepend + to the annotation interval to plot that as a single
contour. 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 contour-normal, or
+ap for contour-parallel [Default]. For +ap, you may option-
ally append u for up-hill and d for down-hill cartographic
annotations.
+cdx[/dy]
Sets the clearance between label and optional text box.
Append c|i|p to specify the unit or % to indicate a percent-
age of the label font size [15%].
+d Turns on debug which will draw helper points and lines to
illustrate the workings of the contour line setup.
+e Delay the plotting of the text. This is used to build a clip
path based on the text, then lay down other overlays while
that clip path is in effect, then turning of clipping with
psclip -Cs which finally plots the original text.
+ffont Sets the desired font [Default FONT_ANNOT_PRIMARY with its
size changed to 9p].
+g[color]
Selects opaque text boxes [Default is transparent]; option-
ally specify the color [Default is PS_PAGE_COLOR].
+jjust Sets label justification [Default is MC].
+ndx[/dy]
Nudges the placement of labels by the specified amount
(append c|i|p to specify the units). Increments are consid-
ered in the coordinate system defined by the orientation of
the contour; use +N to force increments in the plot x/y coor-
dinates system [no nudging]. Not allowed with +v.
+o Selects rounded rectangular text box [Default is rectangu-
lar]. Not applicable for curved text (+v) and only makes
sense for opaque text boxes.
+p[pen]
Draws the outline of text boxes [Default is no outline];
optionally specify pen for outline [Default is width = 0.25p,
color = black, style = solid].
+rmin_rad
Will not place labels where the contoursas radius of curva-
ture is less than min_rad [Default is 0].
+t[file]
Saves contour label x, y, angle, and text to file [Con-
tour_labels.txt].
+uunit Appends unit to all contour labels. [Default is no unit]. If
z is appended we use the z-unit from the grdfile.
+v Specifies curved labels following the contour [Default is
straight labels].
+w Specifies how many (x,y) points will be used to estimate
label angles [automatic].
+=prefix
Prepends prefix to all contour labels. [Default is no pre-
fix].
-B[p|s]parameters (more a|)
Set map boundary frame and axes attributes.
-Dtemplate
Dump contours as data line segments; no plotting takes place.
Append filename template which may contain C-format specifiers.
If no filename template is given we write all lines to stdout.
If filename has no specifiers then we write all lines to a sin-
gle file. If a float format (e.g., %6.2f) is found we substi-
tute the contour z-value. If an integer format (e.g., %06d) is
found we substitute a running segment count. If an char format
(%c) is found we substitute C or O for closed and open contours.
The 1-3 specifiers may be combined and appear in any order to
produce the the desired number of output files (e.g., just %c
gives two files, just %f would. separate segments into one file
per contour level, and %d would write all segments. to individ-
ual files; see manual page for more examples.
-F[l|r]
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[d|f|n|l|L|x|X]params
The required argument controls the placement of labels along the
quoted lines. Choose among five controlling algorithms:
ddist[c|i|p] or Ddist[d|e|f|k|m|M|n|s]
For lower case d, give distances between labels on the plot
in your preferred measurement unit c (cm), i (inch), or p
(points), while for upper case D, specify distances in map
units and append the unit; choose among e (m), f (foot), k
(km), M (mile), n (nautical mile) or u (US survey foot), and
d (arc degree), m (arc minute), or s (arc second). [Default
is 10c or 4i]. As an option, you can append /fraction which
is used to place the very first label for each contour when
the cumulative along-contour distance equals fraction * dist
[0.25].
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,a|]
Give start and stop coordinates for one or more comma-sepa-
rated straight line segments. Labels will be placed where
these lines intersect the quoted lines. The format of each
line specification is start/stop, where start and stop are
either a specified point lon/lat or a 2-character XY key that
uses the justification format employed in pstext to indicate
a point on the map, given as [LCR][BMT]. In addition, you
can use Z-, Z+ to mean the global minimum and maximum loca-
tions in the grid. L will interpret the point pairs as defin-
ing great circles [Default is straight line].
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|p] to enforce that a minimum distance separa-
tion between successive labels is enforced.
x|Xxfile.d
Reads the multisegment file xfile.d and places labels at the
intersections between the quoted lines and the lines in
xfile.d. X will resample the lines first along great-circle
arcs.
In addition, you may optionally append +rradius[c|i|p] to set a min-
imum label separation in the x-y plane [no limitation].
-Jz|Zparameters (more a|)
Set z-axis scaling; same syntax as -Jx.
-K (more a|)
Do not finalize the PostScript plot.
-Llow/high
Limit range: Do not draw contours for data values below low or
above high.
-O (more a|)
Append to existing PostScript plot.
-P (more a|)
Select aPortraita plot orientation.
-Qcut Do not draw contours with less than cut number of points [Draw
all contours].
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
Specify the region of interest.
For perspective view p, optionally append /zmin/zmax. (more a|)
[Default is region defined in the grid file].
-Ssmoothfactor
Used to resample the contour lines at roughly every (grid-
box_size/smoothfactor) interval.
-T[+|-][+dgap[/length]][+l[labels]]
Will draw tick marks pointing in the downward direction every
gap along the innermost closed contours. Append +dgap and
optionally tick mark length (append units as c, i, or p) or use
defaults [15p/3p]. User may choose to tick only local highs or
local lows by specifying -T+ or -T-, respectively. Append +lla-
bels to annotate the centers of closed innermost contours (i.e.,
the local lows and highs). If no labels is appended we use - and
+ as the labels. Appending exactly two characters, e.g., +lLH,
will plot the two characters (here, L and H) as labels. For more
elaborate labels, separate the low and hight label strings with
a comma (e.g., +llo,hi). If a file is given by -C and -T is set,
then only contours marked with upper case C or A will have tick
marks [and annotations].
-U[[just]/dx/dy/][c|label] (more a|)
Draw GMT time stamp logo on plot.
-V[level] (more a|)
Select verbosity level [c].
-W[type]pen[+c[l|f]] (more a|)
type, if present, can be a for annotated contours or c for regu-
lar contours [Default]. The pen sets the attributes for the par-
ticular line. Default pen for annotated contours: 0.75p,black.
Regular contours use pen 0.25p,black. If the modifier +cl is
appended then the color of the contour lines are taken from the
CPT (see -C). If instead modifier +cf is appended then the color
from the cpt file is applied to the contour annotations. Use
just +c for both effects.
-X[a|c|f|r][x-shift[u]]
-Y[a|c|f|r][y-shift[u]] (more a|)
Shift plot origin.
-Z[+s *factor*][+oshift][+p]
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 this scaling has occurred.) Append +p to
indicate that this grid file contains z-values that are periodic
in 360 degrees (e.g., phase data, angular distributions) and
that special precautions must be taken when determining 0-con-
tours.
-bo[ncols][type] (more a|)
Select native binary output.
-donodata (more a|)
Replace output columns that equal NaN with nodata.
-f[i|o]colinfo (more a|)
Specify data types of input and/or output columns.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more a|)
Skip or produce header record(s).
-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more a|)
Select perspective view.
-t[transp] (more a|)
Set PDF transparency level in percent.
-^ or just -
Print a short message about the syntax of the command, then
exits (NOTE: on Windows just use -).
-+ or just +
Print an extensive usage (help) message, including the explana-
tion of any module-specific option (but not the GMT common
options), then exits.
-? or no arguments
Print a complete usage (help) message, including the explanation
of all options, then exits.
ASCII FORMAT PRECISION
The ASCII output formats of numerical data are controlled by parameters
in your gmt.conf file. Longitude and latitude are formatted according
to FORMAT_GEO_OUT, absolute time is under the control of FOR-
MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point val-
ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for-
mat in effect can lead to loss of precision in ASCII output, which can
lead to various problems downstream. If you find the output is not
written with enough precision, consider switching to binary output (-bo
if available) or specify more decimals using the FORMAT_FLOAT_OUT set-
ting.
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
facilitates so called apackinga of grids, writing out floating point
data as 1- or 2-byte integers. (more a|)
EXAMPLES
To contour the file hawaii_grav.nc every 25 mGal on a Mercator map at
0.5 inch/degree, annotate every 50 mGal (using fontsize = 10p), using 1
degree tickmarks, and draw 30 minute gridlines:
gmt grdcontour hawaii_grav.nc -Jm0.5i -C25 -A50+f10p -B1g30m > hawaii_grav.ps
To contour the file image.nc 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 aRMS Misfita 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:
gmt grdcontour image.nc -Jx0.1c/50.0c -Ccont.d -S4 -Bx20 -By0.1 \
-B+t"RMS Misfit" -Wathick,red -Wcthinnest,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.
To save the smoothed 100-m contour lines in topo.nc and separate them
into two multisegment files: contours_C.txt for closed and con-
tours_O.txt for open contours, try
gmt grdcontour topo.nc -C100 -S4 -Dcontours_%c.txt
SEE ALSO
gmt(1), gmt.conf(5), gmtcolors(1), psbasemap(1), grdimage(1),
grdview(1), pscontour(1)
COPYRIGHT
2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
5.4.2 Jun 24, 2017 grdcontour(1)
gmt5 5.4.2 - Generated Wed Jun 28 18:15:36 CDT 2017