.\" Man page generated from reStructuredText.
.
.TH "GRDCONTOUR" "1gmt" "May 21, 2019" "5.4.5" "GMT"
.SH NAME
grdcontour \- Make contour map using a grid
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBgrdcontour\fP \fIgrid\fP  \fB\-C\fP[+]\fIcont_int\fP|\fIcpt\fP
 \fB\-J\fP\fIparameters\fP [  \fB\-A\fP[\fB\-\fP|[+]\fIannot_int\fP][\fIlabelinfo\fP] ]
[  \fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP ]
[  \fB\-D\fP\fItemplate\fP ]
[  \fB\-F\fP[\fBl\fP|\fBr\fP] ]
[  \fB\-G\fP[\fBd\fP|\fBf\fP|\fBn\fP|\fBl\fP|\fBL\fP|\fBx\fP|\fBX\fP]\fIparams\fP ]
[  \fB\-J\fP\fBz\fP|\fBZ\fP\fIparameters\fP ] [  \fB\-K\fP ] [  \fB\-L\fP\fIlow/high\fP ]
[  \fB\-O\fP ] [  \fB\-P\fP ] [  \fB\-Q\fP\fIcut\fP ]
[  \fB\-R\fP\fIwest\fP/\fIeast\fP/\fIsouth\fP/\fInorth\fP[/\fIzmin\fP/\fIzmax\fP][\fB+r\fP] ]
[  \fB\-S\fP\fIsmoothfactor\fP ]
[  \fB\-T\fP[\fB+|\-\fP][\fB+d\fP\fIgap\fP[/\fIlength\fP]][\fB+l\fP[\fIlabels\fP]] ]
[  \fB\-U\fP[\fIstamp\fP] ]
[  \fB\-V\fP[\fIlevel\fP] ]
[  \fB\-W\fP[\fItype\fP]\fIpen\fP ][\fB+c\fP[\fBl\fP|\fBf\fP]]
[  \fB\-X\fP\fIx_offset\fP ]
[  \fB\-Y\fP\fIy_offset\fP ]
[  \fB\-Z\fP[\fB+s\fP\fIfactor\fP][\fB+o\fP\fIshift\fP][\fB+p\fP] ]
[ \fB\-bo\fPbinary ]
[ \fB\-do\fPnodata ]
[ \fB\-e\fPregexp ]
[ \fB\-f\fPflags ]
[ \fB\-ho\fP[\fIn\fP] ]
[ \fB\-p\fPflags ]
[ \fB\-t\fPtransp ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
\fBgrdcontour\fP 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.
.SH REQUIRED ARGUMENTS
.INDENT 0.0
.TP
.B \fIgrid\fP
2\-D gridded data set to be contoured. (See GRID FILE FORMATS below).
.UNINDENT
.INDENT 0.0
.TP
\fB\-C\fP[+]\fIcont_int\fP
The contours to be drawn may be specified in one of three possible ways:
.INDENT 7.0
.IP 1. 3
If \fIcont_int\fP has the suffix ".cpt" 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 \fB\-A\-\fP to
disable all annotations.
.IP 2. 3
If \fIcont_int\fP is a file but not a CPT, 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.
.IP 3. 3
If no file is found, then \fIcont_int\fP is interpreted as a
constant contour interval. However, if prepended with the + sign the
\fIcont_int\fP is taken as meaning draw that single contour. The \fB\-A\fP
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 \(aq... \-A+10 \-C+5\(aq that plots an annotated 10 contour and an non\-annotated 5 contour.
If \fB\-A\fP is set and \fB\-C\fP is not, then the contour interval is set
equal to the specified annotation interval.
.UNINDENT
.sp
If a file is given and \fB\-T\fP 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.
.UNINDENT
.INDENT 0.0
.TP
\fB\-J\fP\fIparameters\fP (more ...)
Select map projection.  
.UNINDENT
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
\fB\-A\fP[\fB\-\fP|[+]\fIannot_int\fP][\fIlabelinfo\fP]
\fIannot_int\fP is annotation interval in data units; it is ignored if
contour levels are given in a file. [Default is no annotations]. Append
\fB\-\fP to disable all annotations implied by \fB\-C\fP\&. Alternatively prepend
+ to the annotation interval to plot that as a single contour. The optional
\fIlabelinfo\fP controls the specifics of the label formatting and consists
of a concatenated string made up of any of the following control arguments:
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
\fB+a\fP\fIangle\fP
For annotations at a fixed angle, \fB+an\fP for contour\-normal, or
\fB+ap\fP for contour\-parallel [Default].  For \fB+ap\fP, you may optionally
append \fBu\fP for up\-hill and \fBd\fP for down\-hill cartographic annotations.
.TP
\fB+c\fP\fIdx\fP[/\fIdy\fP]
Sets the clearance between label and optional text box. Append
\fBc\fP|\fBi\fP|\fBp\fP to specify the unit or % to indicate a
percentage of the label font size [15%].
.TP
\fB+d\fP
Turns on debug which will draw helper points and lines to illustrate
the workings of the contour line setup.
.TP
\fB+e\fP
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 \fB\-Cs\fP which
finally plots the original text.
.TP
\fB+f\fP\fIfont\fP
Sets the desired font [Default \fBFONT_ANNOT_PRIMARY\fP with its
size changed to 9p].
.TP
\fB+g\fP[\fIcolor\fP]
Selects opaque text boxes [Default is transparent]; optionally
specify the color [Default is \fBPS_PAGE_COLOR\fP].
.TP
\fB+j\fP\fIjust\fP
Sets label justification [Default is MC].
.TP
\fB+n\fP\fIdx\fP[/\fIdy\fP]
Nudges the placement of labels by the specified amount (append
\fBc\fP|\fBi\fP|\fBp\fP to specify the units). Increments
are considered in the coordinate system defined by the
orientation of the contour; use \fB+N\fP to force increments in the
plot x/y coordinates system [no nudging]. Not allowed with \fB+v\fP\&.
.TP
\fB+o\fP
Selects rounded rectangular text box [Default is rectangular].
Not applicable for curved text (\fB+v\fP) and only makes sense for
opaque text boxes.
.TP
\fB+p\fP[\fIpen\fP]
Draws the outline of text boxes [Default is no outline];
optionally specify pen for outline [Default is width = 0.25p,
color = black, style = solid].
.TP
\fB+r\fP\fImin_rad\fP
Will not place labels where the contours\(aqs radius of curvature is
less than \fImin_rad\fP [Default is 0].
.TP
\fB+t\fP[\fIfile\fP]
Saves contour label x, y, angle, and text to \fIfile\fP [Contour_labels.txt].
.TP
\fB+u\fP\fIunit\fP
Appends \fIunit\fP to all contour labels. [Default is no unit].
If \fBz\fP is appended we use the z\-unit from the grdfile.
.TP
\fB+v\fP
Specifies curved labels following the contour [Default is straight
labels].
.TP
\fB+w\fP
Specifies how many (\fIx\fP,\fIy\fP) points will be used to estimate
label angles [automatic].
.TP
\fB+=\fP\fIprefix\fP
Prepends \fIprefix\fP to all contour labels. [Default is no prefix].
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
\fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP (more ...)
Set map boundary frame and axes attributes.
.UNINDENT
.INDENT 0.0
.TP
\fB\-D\fP\fItemplate\fP
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.
.UNINDENT
.INDENT 0.0
.TP
\fB\-F\fP[\fBl\fP|\fBr\fP]
Force dumped contours to be oriented so that higher z\-values are to the
left (\fB\-Fl\fP [Default]) or right (\fB\-Fr\fP) as we move along the contour
[Default is arbitrary orientation]. Requires \fB\-D\fP\&.
.UNINDENT
.sp
\fB\-G\fP[\fBd\fP|\fBf\fP|\fBn\fP|\fBl\fP|\fBL\fP|\fBx\fP|\fBX\fP]\fIparams\fP
.INDENT 0.0
.INDENT 3.5
The required argument controls the placement of labels along the quoted
lines. Choose among five controlling algorithms:
.INDENT 0.0
.TP
\fBd\fP\fIdist\fP[\fBc\fP|\fBi\fP|\fBp\fP] or \fBD\fP\fIdist\fP[\fBd\fP|\fBe\fP|\fBf\fP|\fBk\fP|\fBm\fP|\fBM\fP|\fBn\fP|\fBs\fP]
For lower case \fBd\fP, give distances between labels on the plot
in your preferred measurement unit \fBc\fP (cm), \fBi\fP (inch), or
\fBp\fP (points), while for upper case \fBD\fP, specify distances in
map units and append the unit; choose among \fBe\fP (m), \fBf\fP
(foot), \fBk\fP (km), \fBM\fP (mile), \fBn\fP (nautical mile) or \fBu\fP
(US survey foot), and \fBd\fP (arc degree), \fBm\fP (arc minute), or
\fBs\fP (arc second). [Default is 10\fBc\fP or 4\fBi\fP]. As an
option, you can append /\fIfraction\fP which is used to place the
very first label for each contour when the cumulative
along\-contour distance equals \fIfraction * dist\fP [0.25].
.TP
\fBf\fP\fIffile.d\fP
Reads the ASCII file \fIffile.d\fP and places labels at locations in
the file that matches locations along the quoted lines. Inexact
matches and points outside the region are skipped.
.TP
\fBl|L\fP\fIline1\fP[,\fIline2\fP,...]
Give \fIstart\fP and \fIstop\fP 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
\fIline\fP specification is \fIstart/stop\fP, where \fIstart\fP and \fIstop\fP
are either a specified point \fIlon/lat\fP or a 2\-character \fBXY\fP
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. \fBL\fP will interpret the point pairs
as defining great circles [Default is straight line].
.TP
\fBn\fP\fIn_label\fP
Specifies the number of equidistant labels for quoted lines line
[1]. Upper case \fBN\fP starts labeling exactly at the start of
the line [Default centers them along the line]. \fBN\fP\-1 places
one justified label at start, while \fBN\fP+1 places one
justified label at the end of quoted lines. Optionally, append
/\fImin_dist\fP[\fBc\fP|\fBi\fP|\fBp\fP] to enforce that a
minimum distance separation between successive labels is
enforced.
.TP
\fBx|X\fP\fIxfile.d\fP
Reads the multisegment file \fIxfile.d\fP and places labels at the
intersections between the quoted lines and the lines in
\fIxfile.d\fP\&. \fBX\fP will resample the lines first along
great\-circle arcs.
.UNINDENT
.sp
In addition, you may optionally append
\fB+r\fP\fIradius\fP[\fBc\fP|\fBi\fP|\fBp\fP] to set a minimum
label separation in the x\-y plane [no limitation].
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
\fB\-Jz\fP|\fBZ\fP\fIparameters\fP (more ...)
Set z\-axis scaling; same syntax as \fB\-Jx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-K\fP (more ...)
Do not finalize the PostScript plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-L\fP\fIlow/high\fP
Limit range: Do not draw contours for data values below \fIlow\fP or
above \fIhigh\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-O\fP (more ...)
Append to existing PostScript plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-P\fP (more ...)
Select "Portrait" plot orientation.
.UNINDENT
.INDENT 0.0
.TP
\fB\-Q\fP\fIcut\fP
Do not draw contours with less than \fIcut\fP number of points [Draw all contours].
.UNINDENT
.INDENT 0.0
.TP
\fB\-R\fP\fIxmin\fP/\fIxmax\fP/\fIymin\fP/\fIymax\fP[\fB+r\fP][\fB+u\fP\fIunit\fP] (more ...)
Specify the region of interest.  
.UNINDENT
.sp
For perspective view \fBp\fP, optionally append /\fIzmin\fP/\fIzmax\fP\&. (more ...) [Default is region defined in the grid file].
.INDENT 0.0
.TP
\fB\-S\fP\fIsmoothfactor\fP
Used to resample the contour lines at roughly every
(gridbox_size/\fIsmoothfactor\fP) interval.
.UNINDENT
.INDENT 0.0
.TP
\fB\-T\fP[\fB+|\-\fP][\fB+d\fP\fIgap\fP[/\fIlength\fP]][\fB+l\fP[\fIlabels\fP]]
Will draw tick marks pointing in the downward direction every \fIgap\fP
along the innermost closed contours. Append \fB+d\fP\fIgap\fP and optionally tick
mark \fIlength\fP (append units as \fBc\fP, \fBi\fP, or \fBp\fP) or use defaults
[15\fBp\fP/3\fBp\fP]. User may choose to tick only local highs or local
lows by specifying \fB\-T+\fP or \fB\-T\-\fP, respectively. Append
\fB+l\fP\fIlabels\fP to annotate the centers of closed innermost contours
(i.e., the local lows and highs). If no \fIlabels\fP is appended we use \-
and + as the labels. Appending exactly two characters, e.g., \fB+l\fP\fILH\fP,
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.,
\fB+l\fP\fIlo\fP,\fIhi\fP). If a file is given by \fB\-C\fP and \fB\-T\fP is set,
then only contours marked with upper case C or A will have tick marks
[and annotations].
.UNINDENT
.INDENT 0.0
.TP
\fB\-U\fP[[\fIjust\fP]/\fIdx\fP/\fIdy\fP/][\fBc\fP|\fIlabel\fP] (more ...)
Draw GMT time stamp logo on plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.INDENT 0.0
.TP
\fB\-W\fP[\fItype\fP]\fIpen\fP[\fB+c\fP[\fBl\fP|\fBf\fP]] (more ...)
\fItype\fP, if present, can be \fBa\fP for annotated contours or \fBc\fP for
regular contours [Default]. The \fIpen\fP sets the attributes for the
particular line. Default pen for annotated contours: 0.75p,black.
Regular contours use pen 0.25p,black. If the modifier \fB+cl\fP is appended
then the color of the contour lines are taken from the CPT (see
\fB\-C\fP). If instead modifier \fB+cf\fP is appended then the color from the cpt
file is applied to the contour annotations.  Use just \fB+c\fP for both effects.
.UNINDENT
.sp
\fB\-X\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIx\-shift\fP[\fBu\fP]]
.INDENT 0.0
.TP
\fB\-Y\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIy\-shift\fP[\fBu\fP]] (more ...)
Shift plot origin.
.UNINDENT
.INDENT 0.0
.TP
\fB\-Z\fP[\fB+s\fP\fIfactor\fP][\fB+o\fP\fIshift\fP][\fB+p\fP]
Use to subtract \fIshift\fP from the data and multiply the results by
\fIfactor\fP before contouring starts [1/0]. (Numbers in \fB\-A\fP, \fB\-C\fP,
\fB\-L\fP refer to values after this scaling has occurred.) Append
\fB+p\fP 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.
.UNINDENT
.INDENT 0.0
.TP
\fB\-bo\fP[\fIncols\fP][\fItype\fP] (more ...)
Select native binary output.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-do\fP\fInodata\fP (more ...)
Replace output columns that equal NaN with \fInodata\fP\&.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-f\fP[\fBi\fP|\fBo\fP]\fIcolinfo\fP (more ...)
Specify data types of input and/or output columns.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-h\fP[\fBi\fP|\fBo\fP][\fIn\fP][\fB+c\fP][\fB+d\fP][\fB+r\fP\fIremark\fP][\fB+r\fP\fItitle\fP] (more ...)
Skip or produce header record(s).  
.UNINDENT
.INDENT 0.0
.TP
\fB\-p\fP[\fBx\fP|\fBy\fP|\fBz\fP]\fIazim\fP[/\fIelev\fP[/\fIzlevel\fP]][\fB+w\fP\fIlon0\fP/\fIlat0\fP[/\fIz0\fP]][\fB+v\fP\fIx0\fP/\fIy0\fP] (more ...)
Select perspective view.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-t\fP[\fItransp\fP] (more ...)
Set PDF transparency level in percent.
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
.UNINDENT
.SH ASCII FORMAT PRECISION
.sp
The ASCII output formats of numerical data are controlled by parameters
in your gmt.conf file. Longitude and latitude are formatted
according to FORMAT_GEO_OUT, absolute time is
under the control of FORMAT_DATE_OUT and
FORMAT_CLOCK_OUT, whereas general floating point values are formatted
according to FORMAT_FLOAT_OUT\&. Be aware that the format in effect
can lead to loss of precision in ASCII output, which can lead to various
problems downstream. If you find the output is not written with enough
precision, consider switching to binary output (\fB\-bo\fP if available) or
specify more decimals using the FORMAT_FLOAT_OUT setting.
.SH GRID FILE FORMATS
.sp
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. (more ...)
.SH NOTES
.sp
The angle of a contour is computed as an average over \fIn\fP points along the contour.
If you obtain poor angles you can play with two variables: Change \fIn\fP via the \fB+w\fP
modifier to \fB\-A\fP, and/or resample the contour via \fB\-S\fP\&.  For a fixed \fIn\fP the
\fB\-S\fP will localize the calculation, while the opposite is true if you increase \fIn\fP
for a constant \fB\-S\fP\&.
.SH EXAMPLES
.sp
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:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt grdcontour hawaii_grav.nc \-Jm0.5i \-C25 \-A50+f10p \-B1g30m > hawaii_grav.ps
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
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:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt grdcontour image.nc \-Jx0.1c/50.0c \-Ccont.d \-S4 \-Bx20 \-By0.1 \e
           \-B+t"RMS Misfit" \-Wathick,red \-Wcthinnest,blue,\- | lp
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
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.
.sp
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
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt grdcontour topo.nc \-C100 \-S4 \-Dcontours_%c.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
gmt, gmt.conf,
gmtcolors,
psbasemap,
grdimage, grdview,
pscontour
.SH COPYRIGHT
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
.\" Generated by docutils manpage writer.
.