grdcontour

Make contour map using a grid

Synopsis

gmt grdcontour grid -Jparameters [ -A[-contours][labelinfo] ] [ -B[p|s]parameters ] [ -Ccontours ] [ -Dtemplate ] [ -F[l|r] ] [ -G[d|f|n|l|L|x|X]params ] [ -Jz|Zparameters ] [ -K ] [ -Llow/high|n|N|P|p ] [ -N[cpt] ] [ -O ] [ -P ] [ -Q[cut[unit]][+z] ] [ -Rwest/east/south/north[/zmin/zmax][+r][+uunit] ] [ -Ssmoothfactor ] [ -T[h|l][+a][+dgap[/length]][+l[labels]] ] [ -U[stamp] ] [ -V[level] ] [ -W[type]pen[+c[l|f]] ] [ -X[a|c|f|r][xshift[u]] ] [ -Y[a|c|f|r][yshift[u]] ] [ -Z[+sfactor][+oshift][+p] ] [ -bobinary ] [ -donodata ] [ -eregexp ] [ -fflags ] [ -ho[n] ] [ -pflags ] [ -ttransp ] [ --PAR=value ]

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. 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).
-Jparameters (more …)
Select map projection.

Optional Arguments

-A[-]|[contours][labelinfo]
contours is annotation interval in data units; it is ignored if contour levels are given in a file via -C. [Default is no annotations]. Prepend - to disable all annotations implied by -C. To just select a few specific contours give them as a comma-separated string; if only a single contour please add a trailing comma so it is seen as a list and not a contour interval. 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
Place annotations at a fixed angle, or use +an for contour-normal and +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 mode, 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 clip -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].
+h
Hide the lines [Default draws the lines]. This may be useful if all you want is to see annotations and labels and not the lines that guides them.
+jjust
Sets label justification relative to the line center point [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 (contour is x, normal to contour is y); use +N to force increments in the overall 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 selects 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, angle, and text to file [Contour_labels.txt].
+uunit
Appends unit to all contour labels. [Default is no unit]. If z is appended we use the z-unit from the grid file.
+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].
+x[first,last]
Adds first and last to these two labels [,’] placed at either end of a quoted line. This modifier is only allowed when -SqN2 is used to place a label at the start and stop of a line (the default adds a prime to the end label).
+=prefix
Prepends prefix to all contour labels. [Default is no prefix].
-B[p|s]parameters (more …)
Set map boundary frame and axes attributes.
-Ccontours

The contours to be drawn may be specified in one of four possible ways:

  1. If contours is a string with 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 -A- to disable all annotations.
  2. If contours 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.
  3. If contours is a string with comma-separated values it is interpreted as those specific contours only. To indicate a single specific contour you must append a trailing comma to separate it from a contour interval. The -A option offers the same list choice so they may be used together to plot only specific annotated and non-annotated contours.
  4. If no argument is given in modern mode then we select the current CPT.
  5. Otherwise, contours is interpreted as a constant contour 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. Finally, if neither -C nor -A are set then we auto-compute suitable contour and annotation intervals from the data range, yielding approximately 10-20 contours.

-Dtemplate
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 text 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].

-Llow/high|n|N|P|p
Limit range: Do not draw contours for data values below low or above high. Alternatively, limit contours to negative (n) or positive (p) contours. Use upper case N or P to include the zero contour.
-N[cpt]
Fill the area between contours using the discrete color table given by cpt. Then, -C and -A can be used as well to control the contour lines and annotations. If no cpt is appended then a discrete color table must be given via -C instead.
-Q[cut[unit]][+z]
Do not draw contours with less than cut number of points [Draw all contours]. Alternatively, give instead a minimum contour length in distance units (see Units for available units and how distances are computed), including c (Cartesian distances using user coordinates) or C for plot length units in current plot units after projecting the coordinates. Optionally, append +z to exclude the zero contour.
-Rxmin/xmax/ymin/ymax[+r][+uunit] (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[h|l][+a][+dgap[/length]][+l[labels]]
Will draw tick marks pointing in the downward direction every gap along the innermost closed contours only; append +a to tick all 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 -Th or -Tl, 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 high 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]. Note: The labeling of local highs and lows may plot sometimes outside the innermost contour since only the mean value of the contour coordinates is used to position the label.
-U[label][+c][+jjust][+odx/dy] (more …)
Draw GMT time stamp logo on plot.
-V[level] (more …)
Select verbosity level [c].
-W[type]pen[+c[l|f]] (more …)
type, if present, can be a for annotated contours or c for regular contours [Default]. The pen sets the attributes for the particular line. Default pen for annotated contours: 0.75p,black. Regular contours use pen 0.25p,black. Normally, all contours are drawn with a fixed color determined by the pen setting. If the modifier +cl is appended then the color of the contour lines are taken from the CPT (see -C). If instead modifier +cf is appended then the color from the cpt file is applied to the contour annotations. Select +c for both effects.

-X[a|c|f|r][xshift[u]]

-Y[a|c|f|r][yshift[u]] (more …)
Shift plot origin.
-Z[+sfactor][+oshift][+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.
-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 transparency level in percent.
-^ or just -
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use -).
-+ 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 all options, then exits.
--PAR=value
Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Units

For map distance unit, append unit d for arc degree, m for arc minute, and s for arc second, or e for meter [Default], f for foot, k for km, M for statute mile, n for nautical mile, and u for US survey foot. By default we compute such distances using a spherical approximation with great circles (-jg) using the authalic radius (see PROJ_MEAN_RADIUS). You can use -jf to perform “Flat Earth” calculations (quicker but less accurate) or -je to perform exact geodesic calculations (slower but more accurate; see PROJ_GEODESIC for method used).

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, 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 (-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. (more …)

Classic Mode Arguments

These options are used to manipulate the building of layered GMT PostScript plots in classic mode. They are not available when using GMT modern mode.

-K (more …)
Do not finalize the PostScript plot.
-O (more …)
Append to existing PostScript plot.
-P (more …)
Select “Portrait” plot orientation.

Notes

The angle of a contour is computed as an average over n points along the contour. If you obtain poor angles you can play with two variables: Change n via the +w modifier to -A, and/or resample the contour via -S. For a fixed n the -S will localize the calculation, while the opposite is true if you increase n for a constant -S.

Examples

Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with @) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

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 do the same map but only draw the 50 and 150 and annotate the 100 contour:

gmt grdcontour hawaii_grav.nc -Jm0.5i -C50.150 -A100,+f10p -B1g30m > hawaii_grav.ps

To contour the file image.nc using the levels in the file cont.txt 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.txt -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