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 ] [ -O ] [ -P
12 ] [ -Qcut ] [ -Rwest/east/south/north[r] ] [ -Ssmoothfactor ] [
13 -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 [ -m[flag] ]
17
19 grdcontour reads a 2-D grid file and produces a contour map by tracing
20 each contour through the grid. As an option, the x/y/z positions of
21 the contour lines may be dumped to a single multisegment file or many
22 separate files. PostScript code is generated and sent to standard out‐
23 put. 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 -Jpoly/[lon0/[lat0/]]scale ((American) Polyconic)
86 AZIMUTHAL PROJECTIONS:
88 -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
90 -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
91 -Jflon0/lat0[/horizon]/scale (Gnomonic)
92 -Jglon0/lat0[/horizon]/scale (Orthographic)
93 -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale
94 (General Perspective).
95 -Jslon0/lat0[/horizon]/scale (General Stereographic)
96 MISCELLANEOUS PROJECTIONS:
98 -Jh[lon0/]scale (Hammer)
100 -Ji[lon0/]scale (Sinusoidal)
101 -Jkf[lon0/]scale (Eckert IV)
102 -Jk[s][lon0/]scale (Eckert VI)
103 -Jn[lon0/]scale (Robinson)
104 -Jr[lon0/]scale (Winkel Tripel)
105 -Jv[lon0/]scale (Van der Grinten)
106 -Jw[lon0/]scale (Mollweide)
107 NON-GEOGRAPHICAL PROJECTIONS:
109 -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
111 -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log,
112 and power scaling)
113
115 No space between the option flag and the associated arguments.
116 -A annot_int is annotation interval in data units; it is ignored if
118 contour levels are given in a file. [Default is no annota‐
119 tions]. Append - to disable all annotations implied by -C.
120 The optional labelinfo controls the specifics of the label for‐
121 matting and consists of a concatenated string made up of any of
122 the following control arguments:
123 +aangle
125 For annotations at a fixed angle, +an for line-normal, or
126 +ap for line-parallel [Default]. By appending the u or d
127 we get annotations whose top face the next upper or lower
128 annotation, respectively.
129 +cdx[/dy]
131 Sets the clearance between label and optional text box.
132 Append c|i|m|p to specify the unit or % to indicate a
133 percentage of the label font size [15%].
134 +d Turns on debug which will draw helper points and lines to
136 illustrate the workings of the quoted line setup.
137 +ffont Sets the desired font [Default ANNOT_FONT_PRIMARY].
139 +g[color]
141 Selects opaque text boxes [Default is transparent];
142 optionally specify the color [Default is PAGE_COLOR].
143 (See SPECIFYING COLOR below).
144 +jjust Sets label justification [Default is MC]. Ignored when
146 -SqN|n+|-1 is used.
147 +kcolor
149 Sets color of text labels [Default is COLOR_BACKGROUND].
150 (See SPECIFYING COLOR below).
151 +ndx[/dy]
153 Nudges the placement of labels by the specified amount
154 (append c|i|m|p to specify the units). Increments are
155 considered in the coordinate system defined by the orien‐
156 tation of the line; use +N to force increments in the
157 plot x/y coordinates system [no nudging].
158 +o Selects rounded rectangular text box [Default is rectan‐
160 gular]. Not applicable for curved text (+v) and only
161 makes sense for opaque text boxes.
162 +p[pen]
164 Draws the outline of text boxsets [Default is no out‐
165 line]; optionally specify pen for outline [Default is
166 width = 0.25p, color = black, texture = solid]. (See
167 SPECIFYING PENS below).
168 +rmin_rad
170 Will not place labels where the line's radius of curva‐
171 ture is less than min_rad [Default is 0].
172 +ssize Sets the desired font size in points [Default is 9].
174 +uunit Appends unit to all line labels. If unit starts with a
176 leading hyphen (-) then there will be no space between
177 label value and the unit. If no unit is appended we use
178 the units listed in the grid file. [Default is no unit].
179 +v Specifies curved labels following the path [Default is
181 straight labels].
182 +w Specifies how many (x, y) points will be used to estimate
184 label angles [Default is 10].
185 +=prefix
187 Prepends prefix to all line labels. If prefix starts
188 with a leading hyphen (-) then there will be no space
189 between label value and the prefix. [Default is no pre‐
190 fix].
191 -B Sets map boundary annotation and tickmark intervals; see the
193 psbasemap man page for all the details.
194 -D Dump the (x,y,z) coordinates of each contour to separate files,
196 one for each contour segment. The files will be named dump‐
197 file_cont_segment[_i].xyz (or .b is -b is selected), where cont
198 is the contour value and segment is a running segment number for
199 each contour interval (for closed contours we append _i.) If
200 the prefix is given as '-' the file names are instead C#_i
201 (interior) or C#_e (external) plus extension, and # is just a
202 running number. This allows us to make short file names that
203 will work with GNU utilities under DOS. However, when -m is
204 used in conjunction with -D a single multisegment file is cre‐
205 ated instead.
206 -E Sets the viewpoint's azimuth and elevation (for perspective
208 view) [180/90]. For frames used for animation, you may want to
209 append + to fix the center of your data domain (or specify a
210 particular world coordinate point with +wlon0/lat[/z]) which
211 will project to the center of your page size (or specify the
212 coordinates of the projected veiw point with +vx0/y0).
213 -F Force dumped contours to be oriented so that higher z-values are
215 to the left (-Fl [Default]) or right (-Fr) as we move along the
216 contour [Default is arbitrary orientation]. Requires -D.
217 -G Controls the placement of labels along the contours. Choose
219 among five controlling algorithms:
220 -Gddist[c|i|m|p] or -GDdist[d|e|k|m|n]
222 For lower case d, give distances between labels on the
223 plot in your preferred measurement unit c (cm), i (inch),
224 m (meter), or p (points), while for upper case D, specify
225 distances in map units and append the unit; choose among
226 e (m), k (km), m (mile), n (nautical mile), or d (spheri‐
227 cal degree). [Default is 10c or 4i].
228 -Gfffile.d
230 Reads the ascii file ffile.d and places labels at loca‐
231 tions in the file that matches locations along the con‐
232 tours. Inexact matches and points outside the region are
233 skipped.
234 -Gl|Lline1[,line2,...]
236 Give start and stop coordinates for one or more comma-
237 separated straight line segments. Labels will be placed
238 where these lines intersect the contours. The format of
239 each line specification is start/stop, where start and
240 stop are either a specified point lon/lat or a 2-charac‐
241 ter XY key that uses the justification format employed in
242 pstext to indicate a point on the map, given as
243 [LCR][BMT]. In addition, you may use Z+ and Z- which
244 correspond to the locations of the global max and min
245 locations in the grid, respectively. -GL will interpret
246 the point pairs as defining great circles [Default is
247 straight line].
248 -Gnn_label
250 Specifies the number of equidistant labels for contours
251 line [1]. Upper case -GN starts labeling exactly at the
252 start of the line [Default centers them along the line].
253 -GN-1 places one justified label at start, while -GN+1
254 places one justified label at the end of contours.
255 Optionally, append /min_dist[c|i|m|p] to enforce that a
256 minimum distance separation between successive labels is
257 enforced.
258 -Gx|Xxfile.d
260 Reads the multi-segment file xfile.d and places labels at
261 the intersections between the contours and the lines inx‐
262 file.d. -GX will resample the lines first along great-
263 circle arcs.
264 In addition, you may optionally append +rradius[c|i|m|p] to set
266 a minimum label separation in the x-y plane [no limitation].
267 -K More PostScript code will be appended later [Default terminates
269 the plot system].
270 -L Limit range: Do not draw contours for data values below low or
272 above high.
273 -O Selects Overlay plot mode [Default initializes a new plot sys‐
275 tem].
276 -P Selects Portrait plotting mode [Default is Landscape, see gmtde‐
278 faults to change this].
279 -Q Do not draw contours with less than cut number of points [Draw
281 all contours].
282 -R xmin, xmax, ymin, and ymax specify the Region of interest. For
284 geographic regions, these limits correspond to west, east,
285 south, and north and you may specify them in decimal degrees or
286 in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
287 and upper right map coordinates are given instead of w/e/s/n.
288 The two shorthands -Rg and -Rd stand for global domain (0/360
289 and -180/+180 in longitude respectively, with -90/+90 in lati‐
290 tude). Alternatively, specify the name of an existing grid file
291 and the -R settings (and grid spacing, if applicable) are copied
292 from the grid. For calendar time coordinates you may either
293 give (a) relative time (relative to the selected TIME_EPOCH and
294 in the selected TIME_UNIT; append t to -JX|x), or (b) absolute
295 time of the form [date]T[clock] (append T to -JX|x). At least
296 one of date and clock must be present; the T is always required.
297 The date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
298 calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
299 string must be of the form hh:mm:ss[.xxx]. The use of delim‐
300 iters and their type and positions must be exactly as indicated
301 (however, input, output and plot formats are customizable; see
302 gmtdefaults). [Default is region defined in the grid file].
303 -S Used to resample the contour lines at roughly every (grid‐
305 box_size/smoothfactor) interval.
306 -T Will draw tickmarks pointing in the downward direction every gap
308 along the innermost closed contours. Append gap and tickmark
309 length or use defaults [0.5c/0.1c or 0.2i/0.04i]. User may
310 choose to tick only local highs or local lows by specifying -T+
311 or -T-, respectively. Appending :LH will plot the characters L
312 and H at the center of closed innermost contours (local lows and
313 highs). L and H can be any single character (e.g., LH, -+,
314 etc.) If a file is given by -C and -T is set, then only con‐
315 tours marked with upper case C or A will have tickmarks [and
316 annotation].
317 -U Draw Unix System time stamp on plot. By adding just/dx/dy/, the
319 user may specify the justification of the stamp and where the
320 stamp should fall on the page relative to lower left corner of
321 the plot. For example, BL/0/0 will align the lower left corner
322 of the time stamp with the lower left corner of the plot.
323 Optionally, append a label, or c (which will plot the command
324 string.). The GMT parameters UNIX_TIME, UNIX_TIME_POS, and
325 UNIX_TIME_FORMAT can affect the appearance; see the gmtdefaults
326 man page for details. The time string will be in the locale set
327 by the environment variable TZ (generally local time).
328 -V Selects verbose mode, which will send progress reports to stderr
330 [Default runs "silently"].
331 -W type, if present, can be a for annotated contours or c for regu‐
333 lar contours [Default]. pen sets the attributes for the partic‐
334 ular line. Default values for annotated contours: width =
335 0.75p, color = black, texture = solid. Regular contours have
336 default width = 0.25p. (See SPECIFYING PENS below). If the +
337 flag is specified then the color of the contour lines are taken
338 from the cpt file (see -C).
339 -X -Y Shift plot origin relative to the current origin by (x-shift,y-
341 shift) and optionally append the length unit (c, i, m, p). You
342 can prepend a to shift the origin back to the original position
343 after plotting, or prepend r [Default] to reset the current
344 origin to the new location. If -O is used then the default (x-
345 shift,y-shift) is (0,0), otherwise it is (r1i, r1i) or (r2.5c,
346 r2.5c). Alternatively, give c to align the center coordinate (x
347 or y) of the plot with the center of the page based on current
348 page size.
349 -Z Use to subtract shift from the data and multiply the results by
351 factor before contouring starts [1/0]. (Numbers in -A, -C, -L
352 refer to values after this scaling has occurred.) Append p to
353 indicate that this grid file contains z-values that are periodic
354 in 360 degrees (e.g., phase data, angular distributions) and
355 that special precautions must be taken when determining 0-con‐
356 tours.
357 -bo Selects binary output. Append s for single precision [Default
359 is d (double)]. Uppercase S or D will force byte-swapping.
360 Optionally, append ncol, the number of desired columns in your
361 binary output file.
362 -c Specifies the number of plot copies. [Default is 1].
364 -f Special formatting of input and/or output columns (time or geo‐
366 graphical data). Specify i or o to make this apply only to
367 input or output [Default applies to both]. Give one or more
368 columns (or column ranges) separated by commas. Append T (abso‐
369 lute calendar time), t (relative time in chosen TIME_UNIT since
370 TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
371 to each column or column range item. Shorthand -f[i|o]g means
372 -f[i|o]0x,1y (geographic coordinates).
373 -m When used in conjunction with -D a single multisegment file is
375 created, and each contour section is preceded by a header record
376 whose first column is flag followed by the contour level.
377 SPECIFYING PENS
379 pen The attributes of lines and symbol outlines as defined by pen is
380 a comma delimetered list of width, color and texture, each of
381 which is optional. width can be indicated as a measure (points,
382 centimeters, inches) or as faint, thin[ner|nest], thick[er|est],
383 fat[ter|test], or obese. color specifies a gray shade or color
384 (see SPECIFYING COLOR below). texture is a combination of
385 dashes `-' and dots `.'.
386 SPECIFYING COLOR
388 color The color of lines, areas and patterns can be specified by a
389 valid color name; by a gray shade (in the range 0-255); by a
390 decimal color code (r/g/b, each in range 0-255; h-s-v, ranges
391 0-360, 0-1, 0-1; or c/m/y/k, each in range 0-1); or by a hexa‐
392 decimal color code (#rrggbb, as used in HTML). See the gmtcol‐
393 ors manpage for more information and a full list of color names.
394
396 The ASCII output formats of numerical data are controlled by parameters
397 in your .gmtdefaults4 file. Longitude and latitude are formatted
398 according to OUTPUT_DEGREE_FORMAT, whereas other values are formatted
399 according to D_FORMAT. Be aware that the format in effect can lead to
400 loss of precision in the output, which can lead to various problems
401 downstream. If you find the output is not written with enough preci‐
402 sion, consider switching to binary output (-bo if available) or specify
403 more decimals using the D_FORMAT setting.
404
406 GMT is able to recognize many of the commonly used grid file formats,
407 as well as the precision, scale and offset of the values contained in
408 the grid file. When GMT needs a little help with that, you can add the
409 suffix =id[/scale/offset[/nan]], where id is a two-letter identifier of
410 the grid type and precision, and scale and offset are optional scale
411 factor and offset to be applied to all grid values, and nan is the
412 value used to indicate missing data. See grdreformat(1) and Section
413 4.17 of the GMT Technical Reference and Cookbook for more information.
414 When reading a netCDF file that contains multiple grids, GMT will read,
416 by default, the first 2-dimensional grid that can find in that file. To
417 coax GMT into reading another multi-dimensional variable in the grid
418 file, append ?varname to the file name, where varname is the name of
419 the variable. Note that you may need to escape the special meaning of ?
420 in your shell program by putting a backslash in front of it, or by
421 placing the filename and suffix between quotes or double quotes. See
422 grdreformat(1) and Section 4.18 of the GMT Technical Reference and
423 Cookbook for more information, particularly on how to read splices of
424 3-, 4-, or 5-dimensional grids.
425
427 To contour the file hawaii_grav.grd every 25 mGal on a Mercator map at
428 0.5 inch/degree, annotate every 50 mGal (using fontsize = 10), using 1
429 degree tickmarks, and draw 30 minute gridlines:
430 grdcontour hawaii_grav.grd -Jm0.5i -C25 -A50+f10 -B1g30m >
432 hawaii_grav.ps
433 To contour the file image.grd using the levels in the file cont.d on a
435 linear projection at 0.1 cm/x-unit and 50 cm/y-unit, using 20 (x) and
436 0.1 (y) tickmarks, smooth the contours a bit, use "RMS Misfit" as plot-
437 title, use a thick red pen for annotated contours, and a thin, dashed,
438 blue pen for the rest, and send the output to the default printer:
439 grdcontour image.grd -Jx0.1c/50.0c -Ccont.d -S4 -B20/0.1:."RMS Misfit":
441 -Wathick,red -Wcthinnest,blue,- | lp
442 The labeling of local highs and lows may plot outside the innermost
444 contour since only the mean value of the contour coordinates is used to
445 position the label.
446
448 GMT(1), gmtdefaults(1), gmtcolors(5), psbasemap(1), grdimage(1), grd‐
449 view(1), pscontour(1)
450GMT 4.5.6 10 Mar 2011 GRDCONTOUR(1)