1GRDCONTOUR(1) GMT GRDCONTOUR(1)
2
6 grdcontour - Make contour map using a grid
7
9 grdcontour grid -C[+]cont_int|cpt
10 -Jparameters [ -A[-|[+]annot_int][labelinfo] ] [ -B[p|s]parameters ]
11 [ -Dtemplate ] [ -F[l|r] ] [ -G[d|f|n|l|L|x|X]params ] [ -Jz|Zpa‐
12 rameters ] [ -K ] [ -Llow/high ] [ -O ] [ -P ] [ -Qcut ] [
13 -Rwest/east/south/north[/zmin/zmax][+r] ] [ -Ssmoothfactor ] [
14 -T[+|-][+dgap[/length]][+l[labels]] ] [ -U[stamp] ] [ -V[level] ] [
15 -W[type]pen ][+c[l|f]] [ -Xx_offset ] [ -Yy_offset ] [ -Z[+sfac‐
16 tor][+oshift][+p] ] [ -bobinary ] [ -donodata ] [ -eregexp ] [ -fflags
17 ] [ -ho[n] ] [ -pflags ] [ -ttransp ]
18 Note: No space is allowed between the option flag and the associated
20 arguments.
21
23 grdcontour reads a 2-D grid file and produces a contour map by tracing
24 each contour through the grid. PostScript code is generated and sent to
25 standard output. Various options that affect the plotting are avail‐
26 able. Alternatively, the x/y/z positions of the contour lines may be
27 saved to one or more output files (or stdout) and no plot is produced.
28
30 grid 2-D gridded data set to be contoured. (See GRID FILE FORMATS
31 below).
32 -C[+]cont_int
34 The contours to be drawn may be specified in one of three possi‐
35 ble ways:
36 1. If cont_int has the suffix ".cpt" and can be opened as a
38 file, it is assumed to be a CPT. The color boundaries are
39 then used as contour levels. If the CPT has annotation flags
40 in the last column then those contours will be annotated. By
41 default all contours are labeled; use -A- to disable all
42 annotations.
43 2. If cont_int is a file but not a CPT, it is expected to con‐
45 tain contour levels in column 1 and a C(ontour) OR A(nnotate)
46 in col 2. The levels marked C (or c) are contoured, the lev‐
47 els marked A (or a) are contoured and annotated. Optionally,
48 a third column may be present and contain the fixed annota‐
49 tion angle for this contour level.
50 3. If no file is found, then cont_int is interpreted as a con‐
52 stant contour interval. However, if prepended with the + sign
53 the cont_int is taken as meaning draw that single contour.
54 The -A option offers the same possibility so they may be used
55 together to plot a single annotated contour and another sin‐
56 gle non-annotated contour, as in '... -A+10 -C+5' that plots
57 an annotated 10 contour and an non-annotated 5 contour. If
58 -A is set and -C is not, then the contour interval is set
59 equal to the specified annotation interval.
60 If a file is given and -T is set, then only contours marked with
62 upper case C or A will have tick-marks. In all cases the contour
63 values have the same units as the grid.
64 -Jparameters (more ...)
66 Select map projection.
67
69 -A[-|[+]annot_int][labelinfo]
70 annot_int is annotation interval in data units; it is ignored if
71 contour levels are given in a file. [Default is no annotations].
72 Append - to disable all annotations implied by -C. Alternatively
73 prepend + to the annotation interval to plot that as a single
74 contour. The optional labelinfo controls the specifics of the
75 label formatting and consists of a concatenated string made up
76 of any of the following control arguments:
77 +aangle
79 For annotations at a fixed angle, +an for contour-normal, or
80 +ap for contour-parallel [Default]. For +ap, you may option‐
81 ally append u for up-hill and d for down-hill cartographic
82 annotations.
83 +cdx[/dy]
85 Sets the clearance between label and optional text box.
86 Append c|i|p to specify the unit or % to indicate a percent‐
87 age of the label font size [15%].
88 +d Turns on debug which will draw helper points and lines to
90 illustrate the workings of the contour line setup.
91 +e Delay the plotting of the text. This is used to build a clip
93 path based on the text, then lay down other overlays while
94 that clip path is in effect, then turning of clipping with
95 psclip -Cs which finally plots the original text.
96 +ffont Sets the desired font [Default FONT_ANNOT_PRIMARY with its
98 size changed to 9p].
99 +g[color]
101 Selects opaque text boxes [Default is transparent]; option‐
102 ally specify the color [Default is PS_PAGE_COLOR].
103 +jjust Sets label justification [Default is MC].
105 +ndx[/dy]
107 Nudges the placement of labels by the specified amount
108 (append c|i|p to specify the units). Increments are consid‐
109 ered in the coordinate system defined by the orientation of
110 the contour; use +N to force increments in the plot x/y coor‐
111 dinates system [no nudging]. Not allowed with +v.
112 +o Selects rounded rectangular text box [Default is rectangu‐
114 lar]. Not applicable for curved text (+v) and only makes
115 sense for opaque text boxes.
116 +p[pen]
118 Draws the outline of text boxes [Default is no outline];
119 optionally specify pen for outline [Default is width = 0.25p,
120 color = black, style = solid].
121 +rmin_rad
123 Will not place labels where the contours's radius of curva‐
124 ture is less than min_rad [Default is 0].
125 +t[file]
127 Saves contour label x, y, angle, and text to file [Con‐
128 tour_labels.txt].
129 +uunit Appends unit to all contour labels. [Default is no unit]. If
131 z is appended we use the z-unit from the grdfile.
132 +v Specifies curved labels following the contour [Default is
134 straight labels].
135 +w Specifies how many (x,y) points will be used to estimate
137 label angles [automatic].
138 +=prefix
140 Prepends prefix to all contour labels. [Default is no pre‐
141 fix].
142 -B[p|s]parameters (more ...)
144 Set map boundary frame and axes attributes.
145 -Dtemplate
147 Dump contours as data line segments; no plotting takes place.
148 Append filename template which may contain C-format specifiers.
149 If no filename template is given we write all lines to stdout.
150 If filename has no specifiers then we write all lines to a sin‐
151 gle file. If a float format (e.g., %6.2f) is found we substi‐
152 tute the contour z-value. If an integer format (e.g., %06d) is
153 found we substitute a running segment count. If an char format
154 (%c) is found we substitute C or O for closed and open contours.
155 The 1-3 specifiers may be combined and appear in any order to
156 produce the the desired number of output files (e.g., just %c
157 gives two files, just %f would. separate segments into one file
158 per contour level, and %d would write all segments. to individ‐
159 ual files; see manual page for more examples.
160 -F[l|r]
162 Force dumped contours to be oriented so that higher z-values are
163 to the left (-Fl [Default]) or right (-Fr) as we move along the
164 contour [Default is arbitrary orientation]. Requires -D.
165 -G[d|f|n|l|L|x|X]params
167 The required argument controls the placement of labels along the
168 quoted lines. Choose among five controlling algorithms:
169 ddist[c|i|p] or Ddist[d|e|f|k|m|M|n|s]
171 For lower case d, give distances between labels on the plot
172 in your preferred measurement unit c (cm), i (inch), or p
173 (points), while for upper case D, specify distances in map
174 units and append the unit; choose among e (m), f (foot), k
175 (km), M (mile), n (nautical mile) or u (US survey foot), and
176 d (arc degree), m (arc minute), or s (arc second). [Default
177 is 10c or 4i]. As an option, you can append /fraction which
178 is used to place the very first label for each contour when
179 the cumulative along-contour distance equals fraction * dist
180 [0.25].
181 fffile.d
183 Reads the ASCII file ffile.d and places labels at locations
184 in the file that matches locations along the quoted lines.
185 Inexact matches and points outside the region are skipped.
186 l|Lline1[,line2,...]
188 Give start and stop coordinates for one or more comma-sepa‐
189 rated straight line segments. Labels will be placed where
190 these lines intersect the quoted lines. The format of each
191 line specification is start/stop, where start and stop are
192 either a specified point lon/lat or a 2-character XY key that
193 uses the justification format employed in pstext to indicate
194 a point on the map, given as [LCR][BMT]. In addition, you
195 can use Z-, Z+ to mean the global minimum and maximum loca‐
196 tions in the grid. L will interpret the point pairs as defin‐
197 ing great circles [Default is straight line].
198 nn_label
200 Specifies the number of equidistant labels for quoted lines
201 line [1]. Upper case N starts labeling exactly at the start
202 of the line [Default centers them along the line]. N-1 places
203 one justified label at start, while N+1 places one justified
204 label at the end of quoted lines. Optionally, append
205 /min_dist[c|i|p] to enforce that a minimum distance separa‐
206 tion between successive labels is enforced.
207 x|Xxfile.d
209 Reads the multisegment file xfile.d and places labels at the
210 intersections between the quoted lines and the lines in
211 xfile.d. X will resample the lines first along great-circle
212 arcs.
213 In addition, you may optionally append +rradius[c|i|p] to set a min‐
215 imum label separation in the x-y plane [no limitation].
216 -Jz|Zparameters (more ...)
218 Set z-axis scaling; same syntax as -Jx.
219 -K (more ...)
221 Do not finalize the PostScript plot.
222 -Llow/high
224 Limit range: Do not draw contours for data values below low or
225 above high.
226 -O (more ...)
228 Append to existing PostScript plot.
229 -P (more ...)
231 Select "Portrait" plot orientation.
232 -Qcut Do not draw contours with less than cut number of points [Draw
234 all contours].
235 -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
237 Specify the region of interest.
238 For perspective view p, optionally append /zmin/zmax. (more ...)
240 [Default is region defined in the grid file].
241 -Ssmoothfactor
243 Used to resample the contour lines at roughly every (grid‐
244 box_size/smoothfactor) interval.
245 -T[+|-][+dgap[/length]][+l[labels]]
247 Will draw tick marks pointing in the downward direction every
248 gap along the innermost closed contours. Append +dgap and
249 optionally tick mark length (append units as c, i, or p) or use
250 defaults [15p/3p]. User may choose to tick only local highs or
251 local lows by specifying -T+ or -T-, respectively. Append +lla‐
252 bels to annotate the centers of closed innermost contours (i.e.,
253 the local lows and highs). If no labels is appended we use - and
254 + as the labels. Appending exactly two characters, e.g., +lLH,
255 will plot the two characters (here, L and H) as labels. For more
256 elaborate labels, separate the low and hight label strings with
257 a comma (e.g., +llo,hi). If a file is given by -C and -T is set,
258 then only contours marked with upper case C or A will have tick
259 marks [and annotations].
260 -U[[just]/dx/dy/][c|label] (more ...)
262 Draw GMT time stamp logo on plot.
263 -V[level] (more ...)
265 Select verbosity level [c].
266 -W[type]pen[+c[l|f]] (more ...)
268 type, if present, can be a for annotated contours or c for regu‐
269 lar contours [Default]. The pen sets the attributes for the par‐
270 ticular line. Default pen for annotated contours: 0.75p,black.
271 Regular contours use pen 0.25p,black. If the modifier +cl is
272 appended then the color of the contour lines are taken from the
273 CPT (see -C). If instead modifier +cf is appended then the color
274 from the cpt file is applied to the contour annotations. Use
275 just +c for both effects.
276 -X[a|c|f|r][x-shift[u]]
278 -Y[a|c|f|r][y-shift[u]] (more ...)
280 Shift plot origin.
281 -Z[+sfactor][+oshift][+p]
283 Use to subtract shift from the data and multiply the results by
284 factor before contouring starts [1/0]. (Numbers in -A, -C, -L
285 refer to values after this scaling has occurred.) Append +p to
286 indicate that this grid file contains z-values that are periodic
287 in 360 degrees (e.g., phase data, angular distributions) and
288 that special precautions must be taken when determining 0-con‐
289 tours.
290 -bo[ncols][type] (more ...)
292 Select native binary output.
293 -donodata (more ...)
295 Replace output columns that equal NaN with nodata.
296 -f[i|o]colinfo (more ...)
298 Specify data types of input and/or output columns.
299 -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
301 Skip or produce header record(s).
302 -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
304 Select perspective view.
305 -t[transp] (more ...)
307 Set PDF transparency level in percent.
308 -^ or just -
310 Print a short message about the syntax of the command, then
311 exits (NOTE: on Windows just use -).
312 -+ or just +
314 Print an extensive usage (help) message, including the explana‐
315 tion of any module-specific option (but not the GMT common
316 options), then exits.
317 -? or no arguments
319 Print a complete usage (help) message, including the explanation
320 of all options, then exits.
321
323 The ASCII output formats of numerical data are controlled by parameters
324 in your gmt.conf file. Longitude and latitude are formatted according
325 to FORMAT_GEO_OUT, absolute time is under the control of FOR‐
326 MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point val‐
327 ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for‐
328 mat in effect can lead to loss of precision in ASCII output, which can
329 lead to various problems downstream. If you find the output is not
330 written with enough precision, consider switching to binary output (-bo
331 if available) or specify more decimals using the FORMAT_FLOAT_OUT set‐
332 ting.
333
335 By default GMT writes out grid as single precision floats in a
336 COARDS-complaint netCDF file format. However, GMT is able to produce
337 grid files in many other commonly used grid file formats and also
338 facilitates so called "packing" of grids, writing out floating point
339 data as 1- or 2-byte integers. (more ...)
340
342 The angle of a contour is computed as an average over n points along
343 the contour. If you obtain poor angles you can play with two vari‐
344 ables: Change n via the +w modifier to -A, and/or resample the contour
345 via -S. For a fixed n the -S will localize the calculation, while the
346 opposite is true if you increase n for a constant -S.
347
349 To contour the file hawaii_grav.nc every 25 mGal on a Mercator map at
350 0.5 inch/degree, annotate every 50 mGal (using fontsize = 10p), using 1
351 degree tickmarks, and draw 30 minute gridlines:
352 gmt grdcontour hawaii_grav.nc -Jm0.5i -C25 -A50+f10p -B1g30m > hawaii_grav.ps
354 To contour the file image.nc using the levels in the file cont.d on a
356 linear projection at 0.1 cm/x-unit and 50 cm/y-unit, using 20 (x) and
357 0.1 (y) tickmarks, smooth the contours a bit, use "RMS Misfit" as
358 plot-title, use a thick red pen for annotated contours, and a thin,
359 dashed, blue pen for the rest, and send the output to the default
360 printer:
361 gmt grdcontour image.nc -Jx0.1c/50.0c -Ccont.d -S4 -Bx20 -By0.1 \
363 -B+t"RMS Misfit" -Wathick,red -Wcthinnest,blue,- | lp
364 The labeling of local highs and lows may plot outside the innermost
366 contour since only the mean value of the contour coordinates is used to
367 position the label.
368 To save the smoothed 100-m contour lines in topo.nc and separate them
370 into two multisegment files: contours_C.txt for closed and con‐
371 tours_O.txt for open contours, try
372 gmt grdcontour topo.nc -C100 -S4 -Dcontours_%c.txt
374
376 gmt, gmt.conf, gmtcolors, psbasemap, grdimage, grdview, pscontour
377
379 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
3805.4.5 Feb 24, 2019 GRDCONTOUR(1)