contour

Contour table data by direct triangulation

Synopsis

gmt contour [ table ] -Jparameters -Rwest/east/south/north[/zmin/zmax][+r][+uunit] [ -A[n|contours][labelinfo] ] [ -B[p|s]parameters ] [ -Ccontours ] [ -D[template] ] [ -Eindexfile ] [ -G[d|f|n|l|L|x|X]params ] [ -I ] [ -Jz|Zparameters ] [ -Lpen ] [ -N ] [ -Q[n][+z] ] [ -S[p|t] ] [ -T[h|l][+a][+dgap[/length]][+l[labels]] ] [ -U[stamp] ] [ -V[level] ] [ -W[type]pen[+c[l|f]] ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -bbinary ] [ -d[+ccol]nodata ] [ -eregexp ] [ -fflags ] [ -hheaders ] [ -iflags ] [ -lflags ] [ -pflags ] [ -qiflags ] [ -sflags ] [ -ttransp ] [ -:[i|o] ] [ --PAR=value ]

Description

Reads an ASCII [or binary] table and produces a raw contour plot by triangulation. By default, the optimal Delaunay triangulation is performed (using either Shewchuk’s [1996] or Watson’s [1982] method as selected during GMT installation; run the module with argument - to see which method is selected), but the user may optionally provide a second file with network information, such as a triangular mesh used for finite element modeling. In addition to contours, the area between contours may be painted according to the CPT. 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

table

One or more ASCII (or binary, see -bi[ncols][type]) data table file(s) holding a number of data columns. If no tables are given then we read from standard input.

-Jparameters

Specify the projection. (See full description) (See cookbook summary) (See projections table).

-Rxmin/xmax/ymin/ymax[+r][+uunit]

Specify the region of interest. Note: If using modern mode and -R is not provided, the region will be set based on previous plotting commands. If this is the first plotting command in the modern mode levels and -R is not provided, the region will be automatically determined based on the data in table (equivalent to using -Ra). (See full description) (See cookbook information).

For perspective view -p, optionally append /zmin/zmax. (more …)

Optional Arguments

-A[n|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 n 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 off 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].

+i

Invisible lines (i.e., 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].

+wn

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

Set map boundary frame and axes attributes. (See full description) (See cookbook information).

-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 -An to disable all annotations.

2. If contours is a file but not a CPT, it is expected to contain one record per contour, with information given in the order contour-level [angle] C|c|A|a [pen], where items in brackets are optional. The levels marked C (or c) are contoured, while the levels marked A (or a) are both contoured and annotated. If the annotation angle is present we will plot the label at that fixed angle [aligned with the contour]. Finally, a contour- specific pen may be present and will override the pen set by -W for this contour level only. Note: Please specify pen in proper format so it can be distinguished from a plain number like angle.

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 file. 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.

-D[template]

Dump the (x,y,z) coordinates of each contour to one or more output files (or stdout if template is not given). No plotting will take place. If template contains one or more of the C-format specifiers %d, %f, %c then line segments will be written to different files; otherwise all lines are written to the specified file (template). The use of the C-format specifiers controls how many files are created and how the contours are organized. If the float format %f is present (standard modifications to width and precision are allowed, e.g., %f7.3f), then the filenames will contain the contour value and lines are thus separated into files based on a common contour value. If the integer format %d is present (including modifications like %05d), then all contours are written to individual segment files; if any of the other specifiers are present they just affect the file names. Finally, if the character format %c is present it is replaced with the letters C (for closed) or O (for open), reflecting the nature of each contour. Any combination of one, two, or all three modifiers are valid, resulting in different filenames and number of files. For instance, if %c appears by itself, then only two files are created, separating the open from the closed contours (assuming both kinds are present). If just %f is used, then all segments for the same contour level will be written to the same file, resulting in N multi-segment files. If both %f and %c were combined then each contour level would be further subdivided into closed and open contours. Any combination involving %d will result in one individual file for each segment; %c, %f only modifies the file names. The files are ASCII unless -bo is used.

-Eindexfile

Give name of file with network information. Each record must contain triplets of node numbers for a triangle [Default computes these using Delaunay triangulation (see triangulate)].

-G

This 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].

-I

Color the triangles using the CPT.

-Lpen (more …)

Draw the underlying triangular mesh using the specified pen attributes [Default is no mesh].

-N

Do NOT clip contours or image at the boundaries [Default will clip to fit inside region -R].

-Q[n][+z]

Do not draw contours with less than n 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.

-S[p|t]

Skip all input xyz points that fall outside the region [Default uses all the data in the triangulation]. Alternatively, use -St to skip triangles whose three vertices are all outside the region. -S with no modifier is interpreted as -Sp.

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

-U[label|+c][+jjust][+odx[/dy]]

Draw GMT time stamp logo on plot. (See full description) (See cookbook information).

-V[level]

Select verbosity level [w]. (See full description) (See cookbook information).

-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]

Shift plot origin. (See full description) (See cookbook information).

-Y[a|c|f|r][yshift]

Shift plot origin. (See full description) (See cookbook information).

-birecord[+b|l] (more …)

Select native binary format for primary table input. [Default is 3 input columns]. Use 4-byte integer triplets for node ids (-E).

-borecord[+b|l] (more …)

Select native binary format for table output. [Default is 3 output columns].

-d[i|o][+ccol]nodata (more …)

Replace input columns that equal nodata with NaN and do the reverse on output.

-e[~]“pattern” | -e[~]/regexp/[i] (more …)

Only accept data records that match the given pattern.

-f[i|o]colinfo (more …)

Specify data types of input and/or output columns.

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …)

Skip or produce header record(s).

-icols[+l][+ddivisor][+sscale|d|k][+ooffset][,…][,t[word]] (more …)

Select input columns and transformations (0 is first column, t is trailing text, append word to read one word only).

-l[label][+Dpen][+Ggap][+Hheader][+L[code/]txt][+Ncols][+Ssize[/height]][+V[pen]][+ffont][+gfill][+jjust][+ooff][+ppen][+sscale][+wwidth] (more …)

Add a legend entry for the symbol or line being plotted. Normally, the annotated contour is selected for the legend. You can select the regular contour instead, or both of them, by considering the label to be of the format [annotcontlabel][/contlabel]. If either label contains a slash (/) character then use | as the separator for the two labels instead.

-qi[~]rows|limits[+ccol][+a|f|s] (more …)

Select input rows or data limit(s) [default is all rows].

-:[i|o] (more …)

Swap 1st and 2nd column on input and/or output.

-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more …)

Select perspective view.

-s[cols][+a][+r] (more …)

Set handling of NaN records for output.

-ttransp[/transp2] (more …)

Set transparency level(s) in percent.

-^ or just -

Print a short message about the syntax of the command, then exit (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 exit.

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--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).

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.

Note: Since many GMT plot examples are very short (i.e., one module call between the gmt begin and gmt end commands), we will often present them using the quick modern mode GMT Modern Mode One-line Commands syntax, which simplifies such short scripts.

To make a raw contour plot from the remote file Table_5.11.txt and draw the contours every 25 and annotate every 50, using the default Cartesian projection, try

gmt contour @Table_5_11.txt -Wthin -C25 -A50 -B -pdf map

To use the same data but only contour the values 750 and 800, use

gmt contour @Table_5_11.txt -A750,800 -W0.5p -B -pdf map

To create a color plot of the numerical temperature solution obtained on a triangular mesh whose node coordinates and temperatures are stored in temp.xyz and mesh arrangement is given by the file mesh.ijk, using the colors in temp.cpt, run

gmt contour temp.xyz -R0/150/0/100 -Jx0.1i -Ctemp.cpt -G -W0.25p -pdf temp

To save the triangulated 100-m contour lines in topo.txt and separate them into multisegment files (one for each contour level), try

gmt contour topo.txt -C100 -Dcontours_%.0f.txt

References

Watson, D. F., 1982, Acord: Automatic contouring of raw data, Comp. & Geosci., 8, 97-101.

Shewchuk, J. R., 1996, Triangle: Engineering a 2D Quality Mesh Generator and Delaunay Triangulator, First Workshop on Applied Computational Geometry (Philadelphia, PA), 124-133, ACM, May 1996.

http://www.cs.cmu.edu/~quake/triangle.html

Auto-legend entries

This module allows you to use the -l option to specify an automatic legend entry. This option is available for lines or symbols only. If there is no size specified (which is always true for lines) or if the symbol size is computed from other information (which may be true for some symbols deriving size from other input columns), then you need to supply a legend size (i.e., length of a line symbol) via the +S modifier.

See Also

gmt, gmt.conf, gmtcolors, grdcontour, grdimage, nearneighbor, basemap, colorbar, surface, triangulate