grdcontour - Make contour map using a grid
grdcontour grid -C[+]cont_int|cpt -Jparameters [ -A[-|[+]annot_int][labelinfo] ] [ -B[p|s]parameters ] [ -D<template> ] [ -F[l|r] ] [ -G[d|f|n|l|L|x|X]params ] [ -Jz|Zparameters ] [ -K ] [ -Llow/high ] [ -O ] [ -P ] [ -Qcut ] [ -Rwest/east/south/north[/zmin/zmax][r] ] [ -Ssmoothfactor ] [ -T[+|-][+dgap[/length]][+l[labels]] ] [ -U[just/dx/dy/][c|label] ] [ -V[level] ] [ -W[+][type]pen ] [ -Xx_offset ] [ -Yy_offset ] [ -Z[factor[/shift]][p] ] [ -bo<binary> ] [ -ccopies ] [ -do<nodata> ] [ -ho[n] ] [ -p<flags> ] [ -t<transp> ]
Note: No space is allowed between the option flag and the associated arguments.
grdcontour 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.
The contours to be drawn may be specified in one of three possible ways:
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.
- +aangle
- For annotations at a fixed angle, +an for contour-normal, or +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 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 psclip -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].
- +jjust
- Sets label justification [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; use +N to force increments in the 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 is 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, and text to file [Contour_labels.txt]. Use +T to save x, y, angle, text instead.
- +uunit
- Appends unit to all contour labels. [Default is no unit]. If z is appended we use the z-unit from the grdfile.
- +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].
- +=prefix
- Prepends prefix to all contour labels. [Default is no prefix].
-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 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. 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].
For perspective view p, optionally append /zmin/zmax. (more ...) [Default is region defined in the grid file].
-X[a|c|f|r][x-shift[u]]
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, whereas other values are formatted according to FORMAT_FLOAT_OUT. Be aware that the format in effect can lead to loss of precision in the 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.
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. To specify the precision, scale and offset, the user should add the suffix =id[/scale/offset[/nan]], where id is a two-letter identifier of the grid type and precision, and scale and offset are optional scale factor and offset to be applied to all grid values, and nan is the value used to indicate missing data. In case the two characters id is not provided, as in =/scale than a id=nf is assumed. When reading grids, the format is generally automatically recognized. If not, the same suffix can be added to input grid file names. See grdconvert and Section Grid file format specifications of the GMT Technical Reference and Cookbook for more information.
When reading a netCDF file that contains multiple grids, GMT will read, by default, the first 2-dimensional grid that can find in that file. To coax GMT into reading another multi-dimensional variable in the grid file, append ?varname to the file name, where varname is the name of the variable. Note that you may need to escape the special meaning of ? in your shell program by putting a backslash in front of it, or by placing the filename and suffix between quotes or double quotes. The ?varname suffix can also be used for output grids to specify a variable name different from the default: “z”. See grdconvert and Sections Modifiers for COARDS-compliant netCDF files and Grid file format specifications of the GMT Technical Reference and Cookbook for more information, particularly on how to read splices of 3-, 4-, or 5-dimensional grids.
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 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:
gmt grdcontour image.nc -Jx0.1c/50.0c -Ccont.d -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