Provided by: gmt-common_5.2.1+dfsg-3build1_all 
NAME
grdcontour - Make contour map using a grid
SYNOPSIS
grdcontour grid [+]cont_int|cpt parameters [ [-|[+]annot_int][labelinfo] ] [
[p|s]parameters ] [ <template> ] [ [l|r] ] [ [d|f|n|l|L|x|X]params ] [ z|Zparameters ] [
] [ low/high ] [ ] [ ] [ cut ] [ west/east/south/north[/zmin/zmax][r] ] [ smoothfactor ]
[ [+|-][+dgap[/length]][+l[labels]] ] [ [just/dx/dy/][c|label] ] [ [level] ] [
[+][type]pen ] [ x_offset ] [ y_offset ] [ [factor[/shift]][p] ] [ -bo<binary> ] [
-ccopies ] [ -do<nodata> ] [ -ho[n] ] [ -p<flags> ] [ -t<transp> ]
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 available. 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 possible ways:
1. If cont_int has the suffix ".cpt" and can be opened as a file, it is assumed to
be a CPT file. 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. 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 single
non-annotated contour, as in '... -A+10 -C+5' 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 ...)
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 optionally 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 percentage 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]; optionally 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 considered in the coordinate system defined by the
orientation of the contour; use +N to force increments in the plot x/y
coordinates system [no nudging]. Not allowed with +v.
+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 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 contours's radius of curvature is less than
min_rad [Default is 0].
+t[file]
Saves contour label x, y, and text to file [Contour_labels.txt]. Use +T to save
x, y, angle, text instead.
+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 prefix].
-B[p|s]parameters (more ...)
Set map boundary intervals.
-D<template>
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 single file. If a float format (e.g., %6.2f) is found we substitute 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 individual 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,...]
Give start and stop coordinates for one or more comma-separated 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 locations in the grid. L will interpret the point pairs as defining
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 separation 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 minimum label
separation in the x-y plane [no limitation].
-Jz|Zparameters (more ...)
Set z-axis scaling; same syntax as -Jx.
-K (more ...)
Do not finalize the PostScript plot.
-Llow/high
Limit range: Do not draw contours for data values below low or above high.
-O (more ...)
Append to existing PostScript plot.
-P (more ...)
Select "Portrait" plot orientation.
-Qcut Do not draw contours with less than cut number of points [Draw all contours].
-R[unit]xmin/xmax/ymin/ymax[r] (more ...)
Specify the region of interest.
For perspective view p, optionally append /zmin/zmax. (more ...) [Default is region
defined in the grid file].
-Ssmoothfactor
Used to resample the contour lines at roughly every (gridbox_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 +llabels 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 ...)
Draw GMT time stamp logo on plot.
-V[level] (more ...)
Select verbosity level [c].
-W[+][type]pen (more ...)
type, if present, can be a for annotated contours or c for regular contours
[Default]. pen sets the attributes for the particular line. Default pen for
annotated contours: 0.75p,black. Regular contours use pen 0.25p,black. If the +
flag is prepended then the color of the contour lines are taken from the CPT file
(see -C). If the - flag is prepended then the color from the cpt file is applied
both to the contours and the contour annotations.
-X[a|c|f|r][x-shift[u]]
-Y[a|c|f|r][y-shift[u]] (more ...)
Shift plot origin.
-Z[factor[/shift]][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-contours.
-bo[ncols][type] (more ...)
Select native binary output.
-ccopies (more ...)
Specify number of plot copies [Default is 1].
-donodata (more ...)
Replace output columns that equal NaN with nodata.
-f[i|o]colinfo (more ...)
Specify data types of input and/or output columns.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
Skip or produce header record(s).
-p[x|y|z]azim/elev[/zlevel][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
Select perspective view.
-t[transp] (more ...)
Set PDF transparency level in percent.
-^ or just -
Print a short message about the syntax of the command, then exits (NOTE: on Windows
use just -).
-+ or just +
Print an extensive usage (help) message, including the explanation 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 options, then
exits.
--version
Print GMT version and exit.
--show-datadir
Print full path to GMT share directory and exit.
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, whereas other
values are formatted according to FORMAT_FLOAT_OUT. 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 FORMAT_FLOAT_OUT setting.
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 "packing" of grids, writing out floating point
data as 1- or 2-byte integers. To specify the precision, scale and offset, the user should
add the suffix =id[/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 indicate missing data. In case
the two characters id is not provided, as in =/scale than a id=nf is assumed. When
reading grids, the format is generally automatically recognized. If not, the same suffix
can be added to input grid file names. See grdconvert and Section grid-file-format 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. The ?varname suffix can also be used
for output grids to specify a variable name different from the default: "z". See
grdconvert and Sections modifiers-for-CF and grid-file-format 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 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 "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:
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 contours_O.txt for open contours, try
gmt grdcontour topo.nc -C100 -S4 -Dcontours_%c.txt
SEE ALSO
gmt, gmt.conf, gmtcolors, psbasemap, grdimage, grdview, pscontour
COPYRIGHT
2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe