1GRDCONTOUR(1) Generic Mapping Tools GRDCONTOUR(1)
2
6 grdcontour - Contouring of 2-D gridded data sets
7
9 grdcontour grdfile -Ccont_int -Jparameters [ -A[-|annot_int][labelinfo]
10 ] [ -B[p|s]parameters ] [ -Ddumpfile ] [ -Eazimuth/elevation ] [
11 -F[l|r] ] [ -G[d|f|n|l|L|x|X]params ] [ -K ] [ -Llow/high ] [ -M[flag]
12 ] [ -O ] [ -P ] [ -Qcut ] [ -Rwest/east/south/north[r] ] [ -Ssmoothfac‐
13 tor ] [ -T[+|-][gap/length][:LH] ] [ -U[just/dx/dy/][c|label] ] [ -V ]
14 [ -W[+][type]pen ] [ -X[a|c|r][x-shift[u]] ] [ -Y[a|c|r][y-shift[u]] ]
15 [ -Z[factor[/shift]][p] ] [ -ccopies ] [ -bo[s|S|d|D[ncol]|c[var1/...]]
16 ]
17
19 grdcontour reads a 2-D gridded file and produces a contour map by trac‐
20 ing each contour through the grid. As an option, the x/y/z positions
21 of the contour lines may be dumped to a single multisegment file or
22 many separate files. PostScript code is generated and sent to standard
23 output. Various options that affect the plotting are available.
24 grdfile
26 2-D gridded data set to be contoured. (See GRID FILE FORMATS
27 below).
28 -C The contours to be drawn may be specified in one of three possi‐
30 ble ways:
31 (1) If cont_int has the suffix ".cpt" and can be opened as a
32 file, it is assumed to be a color palette table. The color
33 boundaries are then used as contour levels. If the cpt-file has
34 annotation flags in the last column then those contours will be
35 annotated. By default all contours are labeled; use -A- to dis‐
36 able all annotations.
37 (2) If cont_int is a file but not a cpt-file, it is expected to
38 contain contour levels in column 1 and a C(ontour) OR A(nnotate)
39 in col 2. The levels marked C (or c) are contoured, the levels
40 marked A (or a) are contoured and annotated. Optionally, a
41 third column may be present and contain the fixed annotation
42 angle for this contour level.
43 (3) If no file is found, then cont_int is interpreted as a con‐
44 stant contour interval. If -A is set and -C is not, then the
45 contour interval is set equal to the specified annotation inter‐
46 val.
47 If a file is given and -T is set, then only contours marked with
48 upper case C or A will have tickmarks. In all cases the contour
49 values have the same units as the grid.
50 -J Selects the map projection. Scale is UNIT/degree, 1:xxxxx, or
52 width in UNIT (upper case modifier). UNIT is cm, inch, or m,
53 depending on the MEASURE_UNIT setting in .gmtdefaults4, but this
54 can be overridden on the command line by appending c, i, or m to
55 the scale/width value. When central meridian is optional,
56 default is center of longitude range on -R option. Default
57 standard parallel is the equator. For map height, max dimen‐
58 sion, or min dimension, append h, +, or - to the width, respec‐
59 tively.
60 More details can be found in the psbasemap man pages.
61 CYLINDRICAL PROJECTIONS:
63 -Jclon0/lat0/scale (Cassini)
65 -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
66 -Jj[lon0/]scale (Miller)
67 -Jm[lon0/[lat0/]]scale (Mercator)
68 -Jmlon0/lat0/scale (Mercator - Give meridian and standard paral‐
69 lel)
70 -Jo[a]lon0/lat0/azimuth/scale (Oblique Mercator - point and
71 azimuth)
72 -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
73 -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and
74 pole)
75 -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
76 -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
77 -Juzone/scale (UTM - Universal Transverse Mercator)
78 -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)
79 CONIC PROJECTIONS:
81 -Jblon0/lat0/lat1/lat2/scale (Albers)
83 -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
84 -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
85 AZIMUTHAL PROJECTIONS:
87 -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
89 -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
90 -Jflon0/lat0[/horizon]/scale (Gnomonic)
91 -Jglon0/lat0[/horizon]/scale (Orthographic)
92 -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale
93 (General Perspective).
94 -Jslon0/lat0[/horizon][/slat]/scale (General Stereographic)
95 MISCELLANEOUS PROJECTIONS:
97 -Jh[lon0/]scale (Hammer)
99 -Ji[lon0/]scale (Sinusoidal)
100 -Jkf[lon0/]scale (Eckert IV)
101 -Jk[s][lon0/]scale (Eckert IV)
102 -Jn[lon0/]scale (Robinson)
103 -Jr[lon0/]scale (Winkel Tripel)
104 -Jv[lon0/]scale (Van der Grinten)
105 -Jw[lon0/]scale (Mollweide)
106 NON-GEOGRAPHICAL PROJECTIONS:
108 -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
110 -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log,
111 and power scaling)
112
114 No space between the option flag and the associated arguments.
115 -A annot_int is annotation interval in data units; it is ignored if
117 contour levels are given in a file. [Default is no annota‐
118 tions]. Append - to disable all annotations implied by -C.
119 The optional labelinfo controls the specifics of the label for‐
120 matting and consists of a concatenated string made up of any of
121 the following control arguments:
122 +aangle
124 For annotations at a fixed angle, +an for line-normal, or
125 +ap for line-parallel [Default]. By appending the u or d
126 we get annotations whose top face the next upper or lower
127 annotation, respectively.
128 +cdx[/dy]
130 Sets the clearance between label and optional text box.
131 Append c|i|m|p to specify the unit or % to indicate a
132 percentage of the label font size [15%].
133 +d Turns on debug which will draw helper points and lines to
135 illustrate the workings of the quoted line setup.
136 +ffont Sets the desired font [Default ANNOT_FONT_PRIMARY].
138 +g[color]
140 Selects opaque text boxes [Default is transparent];
141 optionally specify the color [Default is PAGE_COLOR].
142 (See SPECIFYING COLOR below).
143 +jjust Sets label justification [Default is MC]. Ignored when
145 -SqN|n+|-1 is used.
146 +kcolor
148 Sets color of text labels [Default is COLOR_BACKGROUND].
149 (See SPECIFYING COLOR below).
150 +ndx[/dy]
152 Nudges the placement of labels by the specified amount
153 (append c|i|m|p to specify the units). Increments are
154 considered in the coordinate system defined by the orien‐
155 tation of the line; use +N to force increments in the
156 plot x/y coordinates system [no nudging].
157 +o Selects rounded rectangular text box [Default is rectan‐
159 gular]. Not applicable for curved text (+v) and only
160 makes sense for opaque text boxes.
161 +p[pen]
163 Draws the outline of text boxsets [Default is no out‐
164 line]; optionally specify pen for outline [Default is
165 width = 0.25p, color = black, texture = solid]. (See
166 SPECIFYING PENS below).
167 +rmin_rad
169 Will not place labels where the line's radius of curva‐
170 ture is less than min_rad [Default is 0].
171 +ssize Sets the desired font size in points [Default is 9].
173 +uunit Appends unit to all line labels. If unit starts with a
175 leading hypen (-) then there will be no space between
176 label value and the unit. If no unit is appended we use
177 the units listed in the grid file. [Default is no unit].
178 +v Specifies curved labels following the path [Default is
180 straight labels].
181 +w Specifies how many (x, y) points will be used to estimate
183 label angles [Default is 10].
184 +=prefix
186 Prepends prefix to all line labels. If prefix starts
187 with a leading hypen (-) then there will be no space
188 between label value and the prefix. [Default is no pre‐
189 fix].
190 -B Sets map boundary annotation and tickmark intervals; see the
192 psbasemap man page for all the details.
193 -D Dump the (x,y,z) coordinates of each contour to separate files,
195 one for each contour segment. The files will be named dump‐
196 file_cont_segment[_i].xyz (or .b is -b is selected), where cont
197 is the contour value and segment is a running segment number for
198 each contour interval (for closed contours we append _i.) If
199 the prefix is given as '-' the file names are instead C#_i
200 (interior) or C#_e (external) plus extension, and # is just a
201 running number. This allows us to make short file names that
202 will work with GNU utilities under DOS. However, when -M is
203 used in conjunction with -D a single multisegment file is cre‐
204 ated instead.
205 -E Sets the viewpoint's azimuth and elevation for perspective view
207 [180/90].
208 -F Force dumped contours to be oriented so that higher z-values are
210 to the left (-Fl [Default]) or right (-Fr) as we move along the
211 contour [Default is arbitrary orientation]. Requires -D.
212 -G Controls the placement of labels along the contours. Choose
214 among five controlling algorithms:
215 -Gddist[c|i|m|p] or -GDdist[d|e|k|m|n]
217 For lower case d, give distances between labels on the
218 plot in your preferred measurement unit c (cm), i (inch),
219 m (meter), or p (points), while for upper case D, specify
220 distances in map units and append the unit; choose among
221 e (m), k (km), m (mile), n (nautical mile), or d (spheri‐
222 cal degree). [Default is 10c or 4i].
223 -Gfffile.d
225 Reads the ascii file ffile.d and places labels at loca‐
226 tions in the file that matches locations along the con‐
227 tours. Inexact mathces and points outside the region are
228 skipped.
229 -Gl|Lline1[,line2,...]
231 Give start and stop coordinates for one or more comma-
232 separated straight line segments. Labels will be placed
233 where these lines intersect the contours. The format of
234 each line specification is start/stop, where start and
235 stop are either a specified point lon/lat or a 2-charac‐
236 ter XY key that uses the justification format employed in
237 pstext to indicate a point on the map, given as
238 [LCR][BMT]. In addition, you may use Z+ and Z- which
239 correspond to the locations of the global max and min
240 locations in the grid, respectively. -GL will interpret
241 the point pairs as defining great circles [Default is
242 straight line].
243 -Gnn_label
245 Specifies the number of equidistant labels for contours
246 line [1]. Upper case -GN starts labeling exactly at the
247 start of the line [Default centers them along the line].
248 -GN-1 places one justified label at start, while -GN+1
249 places one justified label at the end of contours.
250 Optionally, append /min_dist[c|i|m|p] to enforce that a
251 minimum distance separation between successive labels is
252 enforced.
253 -Gx|Xxfile.d
255 Reads the multi-segment file xfile.d and places labels at
256 the intersections between the contours and the lines inx‐
257 file.d. -GX will resample the lines first along great-
258 circle arcs.
259 In addition, you may optionally append :radius[c|i|m|p] to set a mini‐
260 mum label separation in the x-y plane [no limitation].
261 -K More PostScript code will be appended later [Default terminates
263 the plot system].
264 -L Limit range: Do not draw contours for data values below low or
266 above high.
267 -M When used in conjunction with -D a single multisegment file is
269 created, and each contour section is preceeded by a header
270 record whose first column is flag followed by the contour level.
271 -O Selects Overlay plot mode [Default initializes a new plot sys‐
273 tem].
274 -P Selects Portrait plotting mode [Default is Landscape, see gmtde‐
276 faults to change this].
277 -Q Do not draw contours with less than cut number of points [Draw
279 all contours].
280 -R xmin, xmax, ymin, and ymax specify the Region of interest. For
282 geographic regions, these limits correspond to west, east,
283 south, and north and you may specify them in decimal degrees or
284 in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
285 and upper right map coordinates are given instead of w/e/s/n.
286 The two shorthands -Rg and -Rd stand for global domain (0/360
287 and -180/+180 in longitude respectively, with -90/+90 in lati‐
288 tude). For calendar time coordinates you may either give (a)
289 relative time (relative to the selected TIME_EPOCH and in the
290 selected TIME_UNIT; append t to -JX|x), or (b) absolute time of
291 the form [date]T[clock] (append T to -JX|x). At least one of
292 date and clock must be present; the T is always required. The
293 date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
294 calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
295 string must be of the form hh:mm:ss[.xxx]. The use of delim‐
296 iters and their type and positions must be exactly as indicated
297 (however, input, output and plot formats are customizable; see
298 gmtdefaults). [Default is region defined in the grid file].
299 -S Used to resample the contour lines at roughly every (grid‐
301 box_size/smoothfactor) interval.
302 -T Will draw tickmarks pointing in the downward direction every gap
304 along the innermost closed contours. Append gap and tickmark
305 length or use defaults [0.5c/0.1c or 0.2i/0.04i]. User may
306 choose to tick only local highs or local lows by specifying -T+
307 or -T-, respectively. Appending :LH will plot the characters L
308 and H at the center of closed innermost contours (local lows and
309 highs). L and H can be any single character (e.g., LH, -+,
310 etc.) If a file is given by -C and -T is set, then only con‐
311 tours marked with upper case C or A will have tickmarks [and
312 annotation].
313 -U Draw Unix System time stamp on plot. By adding just/dx/dy/, the
315 user may specify the justification of the stamp and where the
316 stamp should fall on the page relative to lower left corner of
317 the plot. For example, BL/0/0 will align the lower left corner
318 of the time stamp with the lower left corner of the plot.
319 Optionally, append a label, or c (which will plot the command
320 string.). The GMT parameters UNIX_TIME, UNIX_TIME_POS, and
321 UNIX_TIME_FORMAT can affect the appearance; see the gmtdefaults
322 man page for details. The time string will be in the locale set
323 by the environment variable TZ (generally local time).
324 -V Selects verbose mode, which will send progress reports to stderr
326 [Default runs "silently"].
327 -W type, if present, can be a for annotated contours or c for regu‐
329 lar contours [Default]. pen sets the attributes for the partic‐
330 ular line. Default values for annotated contours: width = 3,
331 color = black, texture = solid. Regular contours have default
332 width = 1. (See SPECIFYING PENS below). If the + flag is spec‐
333 ified then the color of the contour lines are taken from the cpt
334 file (see -C).
335 -X -Y Shift plot origin relative to the current origin by (x-shift,y-
337 shift) and optionally append the length unit (c, i, m, p). You
338 can prepend a to shift the origin back to the original position
339 after plotting, or prepend r [Default] to reset the current
340 origin to the new location. If -O is used then the default (x-
341 shift,y-shift) is (0,0), otherwise it is (r1i, r1i) or (r2.5c,
342 r2.5c). Alternatively, give c to align the center coordinate (x
343 or y) of the plot with the center of the page based on current
344 page size.
345 -Z Use to subtract shift from the data and multiply the results by
347 factor before contouring starts [1/0]. (Numbers in -A, -C, -L
348 refer to values after this scaling has occurred.) Append p to
349 indicate that this grid file contains z-values that are periodic
350 in 360 degrees (e.g., phase data, angular distributions) and
351 that special precautions must be taken when determining 0-con‐
352 tours.
353 -bo Selects binary output. Append s for single precision [Default
355 is d (double)]. Uppercase S or D will force byte-swapping.
356 Optionally, append ncol, the number of desired columns in your
357 binary output file.
358 -c Specifies the number of plot copies. [Default is 1].
360 -f Special formatting of input and/or output columns (time or geo‐
362 graphical data). Specify i or o to make this apply only to
363 input or output [Default applies to both]. Give one or more
364 columns (or column ranges) separated by commas. Append T (abso‐
365 lute calendar time), t (relative time in chosen TIME_UNIT since
366 TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
367 to each column or column range item. Shorthand -f[i|o]g means
368 -f[i|o]0x,1y (geographic coordinates).
369 SPECIFYING PENS
371 pen The attributes of lines and symbol outlines as defined by pen is
372 a comma delimetered list of width, color and texture, each of
373 which is optional. width can be indicated as a measure (points,
374 centimeters, inches) or as faint, thin[ner|nest], thick[er|est],
375 fat[ter|test], or obese. color specifies a grey shade or color
376 (see SPECIFYING COLOR below). texture is a combination of
377 dashes `-' and dots `.'.
378 SPECIFYING COLOR
380 color The color of lines, areas and patterns can be specified by a
381 valid color name; by a grey shade (in the range 0-255); by a
382 decimal color code (r/g/b, each in range 0-255; h-s-v, ranges
383 0-360, 0-1, 0-1; or c/m/y/k, each in range 0-1); or by a hexa‐
384 decimal color code (#rrggbb, as used in HTML). See the gmtcol‐
385 ors manpage for more information and a full list of color names.
386
388 The ASCII output formats of numerical data are controlled by parameters
389 in your .gmtdefaults4 file. Longitude and latitude are formatted
390 according to OUTPUT_DEGREE_FORMAT, whereas other values are formatted
391 according to D_FORMAT. Be aware that the format in effect can lead to
392 loss of precision in the output, which can lead to various problems
393 downstream. If you find the output is not written with enough preci‐
394 sion, consider switching to binary output (-bo if available) or specify
395 more decimals using the D_FORMAT setting.
396
398 GMT is able to recognize many of the commonly used grid file formats,
399 as well as the precision, scale and offset of the values contained in
400 the grid file. When GMT needs a little help with that, you can add the
401 suffix =id[/scale/offset[/nan]], where id is a two-letter identifier of
402 the grid type and precision, and scale and offset are optional scale
403 factor and offset to be applied to all grid values, and nan is the
404 value used to indicate missing data. See grdreformat(1) and Section
405 4.17 of the GMT Technical Reference and Cookbook for more information.
406 When reading a netCDF file that contains multiple grids, GMT will read,
408 by default, the first 2-dimensional grid that can find in that file. To
409 coax GMT into reading another multi-dimensional variable in the grid
410 file, append ?varname to the file name, where varname is the name of
411 the variable. Note that you may need to escape the special meaning of ?
412 in your shell program by putting a backslash in front of it, or by
413 placing the filename and suffix between quotes or double quotes. See
414 grdreformat(1) and Section 4.18 of the GMT Technical Reference and
415 Cookbook for more information, particularly on how to read splices of
416 3-, 4-, or 5-dimensional grids.
417
419 To contour the file hawaii_grav.grd every 25 mGal on a Mercator map at
420 0.5 inch/degree, annotate every 50 mGal (using fontsize = 10), using 1
421 degree tickmarks, and draw 30 minute gridlines:
422 grdcontour hawaii_grav.grd -Jm0.5i -C25 -A50+f10 -B1g30m >
424 hawaii_grav.ps
425 To contour the file image.grd using the levels in the file cont.d on a
427 linear projection at 0.1 cm/x-unit and 50 cm/y-unit, using 20 (x) and
428 0.1 (y) tickmarks, smooth the contours a bit, use "RMS Misfit" as plot-
429 title, use a thick red pen for annotated contours, and a thin, dashed,
430 blue pen for the rest, and send the output to the default printer:
431 grdcontour image.grd -Jx0.1c/50.0c -Ccont.d -S4 -B20/0.1:."RMS Misfit":
433 -Wathick,red -Wcthinnest,blue,- | lp
434 The labeling of local highs and lows may plot outside the innermost
436 contour since only the mean value of the contour coordinates is used to
437 position the label.
438
440 GMT(1), gmtdefaults(1), psbasemap(1), grdimage(1), grdview(1), pscon‐
441 tour(1)
442GMT 4.3.1 15 May 2008 GRDCONTOUR(1)