Provided by: gmt-common_5.4.5+dfsg-2_all 
NAME
pscontour - Contour table data by direct triangulation [method]
SYNOPSIS
pscontour [ table ] -C[+]cpt -Jparameters
-Rwest/east/south/north[/zmin/zmax][+r] [ -A[-|[+]annot_int][labelinfo] ] [
-B[p|s]parameters ] [ -D[template] ] [ -Eindexfile ] [ -G[d|f|n|l|L|x|X]params ] [ -I
] [ -Jz|Zparameters ] [ -K ] [ -Lpen ] [ -N ] [ -O ] [ -P ] [ -Qcut ] [ -S[p|t] ]
[ -T[+|-][+dgap[/length]][+l[labels]] ] [ -U[stamp] ] [ -V[level] ] [ -W[type]pen
][+c[l|f]] [ -Xx_offset ] [ -Yy_offset ] [ -bbinary ] [ -dnodata ] [ -eregexp ] [
-hheaders ] [ -iflags ] [ -pflags ] [ -ttransp ] [ -:[i|o] ]
Note: No space is allowed between the option flag and the associated arguments.
DESCRIPTION
pscontour 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; type
pscontour - 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
-C[+]cont_int
The contours to be drawn may be specified in one of three possible ways:
1. If cont_int has the 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 cont_int 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 no file is found, then cont_int is interpreted as a constant contour
interval. However, if prepended with the + sign the cont_int is taken as meaning
draw that single contour. The -A option offers the same possibility so they may
be used together to plot only one annotated and one non-annotated contour. If
-A is set and -C is not, then the contour interval is set equal to the specified
annotation 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.
-Jparameters (more ...)
Select map projection.
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
Specify the region of interest.
For perspective view p, optionally append /zmin/zmax. (more ...)
OPTIONAL 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.
-A[-|[+]annot_int][labelinfo]
annot_int is annotation interval in data units; it is ignored if contour levels are
given in a file. [Default is no annotations]. Append - to disable all annotations
implied by -C. Alternatively prepend + to the annotation interval to plot that as a
single contour. 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
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, 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 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].
-B[p|s]parameters (more ...)
Set map boundary frame and axes attributes.
-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
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].
-I Color the triangles using the CPT.
-Jz|Zparameters (more ...)
Set z-axis scaling; same syntax as -Jx.
-K (more ...)
Do not finalize the PostScript plot.
-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].
-O (more ...)
Append to existing PostScript plot.
-P (more ...)
Select "Portrait" plot orientation.
-Qcut Do not draw contours with less than cut number of points [Draw all contours].
-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[+|-][+dgap[/length]][+l[labels]]
Will draw tick marks pointing in the downward direction every gap along the
innermost 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 -T+ or -T-, 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 hight 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[[just]/dx/dy/][c|label] (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. 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. Use just +c for both effects.
-X[a|c|f|r][x-shift[u]]
-Y[a|c|f|r][y-shift[u]] (more ...)
Shift plot origin.
-bi[ncols][t] (more ...)
Select native binary input. [Default is 3 input columns]. Use 4-byte integer
triplets for node ids (-E).
-bo[ncols][type] (more ...)
Select native binary output. [Default is 3 output columns].
-d[i|o]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.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
Skip or produce header record(s).
-icols[+l][+sscale][+ooffset][,...] (more ...)
Select input columns and transformations (0 is first column).
-:[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.
-t[transp] (more ...)
Set PDF 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.
EXAMPLES
To make a raw contour plot from the file topo.xyz and drawing the contours (pen = 2) given
in the CPT topo.cpt on a Lambert map at 0.5 inch/degree along the standard parallels 18
and 24, use
gmt pscontour topo.xyz -R320/330/20/30 -Jl18/24/0.5i -Ctopo.cpt -W0.5p > topo.ps
To create a color PostScript 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 pscontour temp.xyz -R0/150/0/100 -Jx0.1i -Ctemp.cpt -G -W0.25p > temp.ps
To save the triangulated 100-m contour lines in topo.txt and separate them into
multisegment files (one for each contour level), try
gmt pscontour topo.txt -C100 -Dcontours_%.0f.txt
SEE ALSO
gmt, gmt.conf, gmtcolors, grdcontour, grdimage, nearneighbor, psbasemap, psscale, surface,
triangulate
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
COPYRIGHT
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe