1PSCONTOUR(1)                          GMT                         PSCONTOUR(1)
2
3
4

NAME

6       pscontour - Contour table data by direct triangulation [method]
7

SYNOPSIS

9       pscontour [ table ]  -C[+]cpt  -Jparameters
10        -Rwest/east/south/north[/zmin/zmax][+r]                              [
11       -A[-|[+]annot_int][labelinfo] ] [  -B[p|s]parameters ] [   -D[template]
12       ] [  -Eindexfile ] [  -G[d|f|n|l|L|x|X]params ] [  -I ] [  -Jz|Zparame‐
13       ters ] [  -K ] [  -Lpen ] [  -N ] [  -O ] [  -P ] [  -Qcut ] [  -S[p|t]
14       ]  [  -T[+|-][+dgap[/length]][+l[labels]] ] [  -U[stamp] ] [  -V[level]
15       ] [  -W[type]pen ][+c[l|f]] [  -Xx_offset ] [  -Yy_offset ] [  -bbinary
16       ]  [  -dnodata  ]  [ -eregexp ] [ -hheaders ] [ -iflags ] [ -pflags ] [
17       -ttransp ] [ -:[i|o] ]
18
19       Note: No space is allowed between the option flag  and  the  associated
20       arguments.
21

DESCRIPTION

23       pscontour  reads  an ASCII [or binary] table and produces a raw contour
24       plot by triangulation. By default, the optimal  Delaunay  triangulation
25       is  performed (using either Shewchuk's [1996] or Watson's [1982] method
26       as selected during GMT installation; type  pscontour  -  to  see  which
27       method  is selected), but the user may optionally provide a second file
28       with network information, such as a triangular  mesh  used  for  finite
29       element  modeling.  In  addition to contours, the area between contours
30       may be painted according to the CPT.  Alternatively,  the  x/y/z  posi‐
31       tions of the contour lines may be saved to one or more output files (or
32       stdout) and no plot is produced.
33

REQUIRED ARGUMENTS

35       -C[+]cont_int
36              The contours to be drawn may be specified in one of three possi‐
37              ble ways:
38
39              1. If  cont_int  has  the  suffix  ".cpt" and can be opened as a
40                 file, it is assumed to be a CPT.  The  color  boundaries  are
41                 then  used as contour levels. If the CPT has annotation flags
42                 in the last column then those contours will be annotated.  By
43                 default  all  contours  are  labeled;  use -A- to disable all
44                 annotations.
45
46              2. If cont_int is a file but not a CPT, it is expected  to  con‐
47                 tain contour levels in column 1 and a C(ontour) OR A(nnotate)
48                 in col 2. The levels marked C (or c) are contoured, the  lev‐
49                 els  marked A (or a) are contoured and annotated. Optionally,
50                 a third column may be present and contain the  fixed  annota‐
51                 tion angle for this contour level.
52
53              3. If  no  file is found, then cont_int is interpreted as a con‐
54                 stant contour interval. However, if prepended with the + sign
55                 the  cont_int  is  taken as meaning draw that single contour.
56                 The -A option offers the same possibility so they may be used
57                 together  to  plot  only  one annotated and one non-annotated
58                 contour.  If -A is set and -C is not, then the contour inter‐
59                 val is set equal to the specified annotation interval.
60
61              If a file is given and -T is set, then only contours marked with
62              upper case C or A will have tick-marks. In all cases the contour
63              values have the same units as the file.
64
65       -Jparameters (more ...)
66              Select map projection.
67
68       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
69              Specify the region of interest.
70
71       For perspective view p, optionally append /zmin/zmax. (more ...)
72

OPTIONAL ARGUMENTS

74       table  One  or  more ASCII (or binary, see -bi[ncols][type]) data table
75              file(s) holding a number of data columns. If no tables are given
76              then we read from standard input.
77
78       -A[-|[+]annot_int][labelinfo]
79              annot_int is annotation interval in data units; it is ignored if
80              contour levels are given in a file. [Default is no annotations].
81              Append - to disable all annotations implied by -C. Alternatively
82              prepend + to the annotation interval to plot that  as  a  single
83              contour.  The  optional  labelinfo controls the specifics of the
84              label formatting and consists of a concatenated string  made  up
85              of any of the following control arguments:
86
87          +aangle
88                 For  annotations at a fixed angle, +an for contour-normal, or
89                 +ap for contour-parallel [Default].  For +ap, you may option‐
90                 ally  append  u  for up-hill and d for down-hill cartographic
91                 annotations.
92
93          +cdx[/dy]
94                 Sets the clearance  between  label  and  optional  text  box.
95                 Append  c|i|p to specify the unit or % to indicate a percent‐
96                 age of the label font size [15%].
97
98          +d     Turns on debug which will draw helper  points  and  lines  to
99                 illustrate the workings of the contour line setup.
100
101          +e     Delay  the plotting of the text. This is used to build a clip
102                 path based on the text, then lay down  other  overlays  while
103                 that  clip  path  is in effect, then turning of clipping with
104                 psclip -Cs which finally plots the original text.
105
106          +ffont Sets the desired font [Default  FONT_ANNOT_PRIMARY  with  its
107                 size changed to 9p].
108
109          +g[color]
110                 Selects  opaque  text boxes [Default is transparent]; option‐
111                 ally specify the color [Default is PS_PAGE_COLOR].
112
113          +jjust Sets label justification [Default is MC].
114
115          +ndx[/dy]
116                 Nudges the  placement  of  labels  by  the  specified  amount
117                 (append  c|i|p  to specify the units). Increments are consid‐
118                 ered in the coordinate system defined by the  orientation  of
119                 the contour; use +N to force increments in the plot x/y coor‐
120                 dinates system [no nudging]. Not allowed with +v.
121
122          +o     Selects rounded rectangular text box  [Default  is  rectangu‐
123                 lar].   Not  applicable  for  curved text (+v) and only makes
124                 sense for opaque text boxes.
125
126          +p[pen]
127                 Draws the outline of text  boxes  [Default  is  no  outline];
128                 optionally specify pen for outline [Default is width = 0.25p,
129                 color = black, style = solid].
130
131          +rmin_rad
132                 Will not place labels where the contours's radius  of  curva‐
133                 ture is less than min_rad [Default is 0].
134
135          +t[file]
136                 Saves  contour  label  x,  y,  angle,  and text to file [Con‐
137                 tour_labels.txt].
138
139          +uunit Appends unit to all contour labels. [Default is no unit].  If
140                 z is appended we use the z-unit from the grdfile.
141
142          +v     Specifies  curved  labels  following  the contour [Default is
143                 straight labels].
144
145          +w     Specifies how many (x,y) points  will  be  used  to  estimate
146                 label angles [automatic].
147
148          +=prefix
149                 Prepends  prefix  to  all contour labels. [Default is no pre‐
150                 fix].
151
152       -B[p|s]parameters (more ...)
153              Set map boundary frame and axes attributes.
154
155       -D[template]
156          Dump the (x,y,z) coordinates of each contour to one or  more  output
157          files  (or  stdout  if template is not given). No plotting will take
158          place.  If template contains one or more of the C-format  specifiers
159          %d,  %f,  %c  then line segments will be written to different files;
160          otherwise all lines are written to the  specified  file  (template).
161          The  use of the C-format specifiers controls how many files are cre‐
162          ated and how the contours are organized. If the float format  %f  is
163          present  (standard modifications to width and precision are allowed,
164          e.g., %f7.3f), then the filenames will contain the contour value and
165          lines are thus separated into files based on a common contour value.
166          If the integer format %d is present  (including  modifications  like
167          %05d), then all contours are written to individual segment files; if
168          any of the other specifiers are present they just  affect  the  file
169          names. Finally, if the character format %c is present it is replaced
170          with the letters C (for closed) or  O  (for  open),  reflecting  the
171          nature  of  each  contour. Any combination of one, two, or all three
172          modifiers are valid, resulting in different filenames and number  of
173          files.  For  instance,  if %c appears by itself, then only two files
174          are created, separating the open from the closed contours  (assuming
175          both  kinds  are present). If just %f is used, then all segments for
176          the same contour level will be written to the same  file,  resulting
177          in  N multi-segment files. If both %f and %c were combined then each
178          contour level would be further subdivided into closed and open  con‐
179          tours.  Any  combination  involving %d will result in one individual
180          file for each segment; %c, %f only modifies  the  file  names.   The
181          files are ASCII unless -bo is used.
182
183       -Eindexfile
184              Give  name  of  file  with network information. Each record must
185              contain triplets of node numbers for a  triangle  [Default  com‐
186              putes these using Delaunay triangulation (see triangulate)].
187
188       -G
189          The  required  argument  controls  the placement of labels along the
190          quoted lines. Choose among five controlling algorithms:
191
192          ddist[c|i|p] or Ddist[d|e|f|k|m|M|n|s]
193                 For lower case d, give distances between labels on  the  plot
194                 in  your  preferred  measurement  unit c (cm), i (inch), or p
195                 (points), while for upper case D, specify  distances  in  map
196                 units  and  append  the unit; choose among e (m), f (foot), k
197                 (km), M (mile), n (nautical mile) or u (US survey foot),  and
198                 d  (arc  degree), m (arc minute), or s (arc second). [Default
199                 is 10c or 4i]. As an option, you can append  /fraction  which
200                 is  used  to place the very first label for each contour when
201                 the cumulative along-contour distance equals fraction *  dist
202                 [0.25].
203
204          fffile.d
205                 Reads  the  ASCII file ffile.d and places labels at locations
206                 in the file that matches locations along  the  quoted  lines.
207                 Inexact matches and points outside the region are skipped.
208
209          l|Lline1[,line2,...]
210                 Give  start  and stop coordinates for one or more comma-sepa‐
211                 rated straight line segments. Labels  will  be  placed  where
212                 these  lines  intersect  the quoted lines. The format of each
213                 line specification is start/stop, where start  and  stop  are
214                 either a specified point lon/lat or a 2-character XY key that
215                 uses the justification format employed in pstext to  indicate
216                 a  point  on  the map, given as [LCR][BMT].  In addition, you
217                 can use Z-, Z+ to mean the global minimum and  maximum  loca‐
218                 tions in the grid. L will interpret the point pairs as defin‐
219                 ing great circles [Default is straight line].
220
221          nn_label
222                 Specifies the number of equidistant labels for  quoted  lines
223                 line  [1].  Upper case N starts labeling exactly at the start
224                 of the line [Default centers them along the line]. N-1 places
225                 one  justified label at start, while N+1 places one justified
226                 label  at  the  end  of  quoted  lines.  Optionally,   append
227                 /min_dist[c|i|p]  to  enforce that a minimum distance separa‐
228                 tion between successive labels is enforced.
229
230          x|Xxfile.d
231                 Reads the multisegment file xfile.d and places labels at  the
232                 intersections  between  the  quoted  lines  and  the lines in
233                 xfile.d. X will resample the lines first  along  great-circle
234                 arcs.
235
236          In addition, you may optionally append +rradius[c|i|p] to set a min‐
237          imum label separation in the x-y plane [no limitation].
238
239       -I     Color the triangles using the CPT.
240
241       -Jz|Zparameters (more ...)
242              Set z-axis scaling; same syntax as -Jx.
243
244       -K (more ...)
245              Do not finalize the PostScript plot.
246
247       -Lpen (more ...)
248              Draw the underlying triangular  mesh  using  the  specified  pen
249              attributes [Default is no mesh].
250
251       -N     Do  NOT  clip  contours or image at the boundaries [Default will
252              clip to fit inside region -R].
253
254       -O (more ...)
255              Append to existing PostScript plot.
256
257       -P (more ...)
258              Select "Portrait" plot orientation.
259
260       -Qcut  Do not draw contours with less than cut number of  points  [Draw
261              all contours].
262
263       -S[p|t]
264              Skip  all input xyz points that fall outside the region [Default
265              uses all the data in the triangulation].  Alternatively, use -St
266              to  skip  triangles  whose  three  vertices  are all outside the
267              region.  -S with no modifier is interpreted as -Sp.
268
269       -T[+|-][+dgap[/length]][+l[labels]]
270              Will draw tick marks pointing in the  downward  direction  every
271              gap  along  the  innermost  closed  contours.  Append  +dgap and
272              optionally tick mark length (append units as c, i, or p) or  use
273              defaults  [15p/3p].  User may choose to tick only local highs or
274              local lows by specifying -T+ or -T-, respectively. Append  +lla‐
275              bels to annotate the centers of closed innermost contours (i.e.,
276              the local lows and highs). If no labels is appended we use - and
277              +  as  the labels. Appending exactly two characters, e.g., +lLH,
278              will plot the two characters (here, L and H) as labels. For more
279              elaborate  labels, separate the low and hight label strings with
280              a comma (e.g., +llo,hi). If a file is given by -C and -T is set,
281              then  only contours marked with upper case C or A will have tick
282              marks [and annotations].
283
284       -U[[just]/dx/dy/][c|label] (more ...)
285              Draw GMT time stamp logo on plot.
286
287       -V[level] (more ...)
288              Select verbosity level [c].
289
290       -W[type]pen[+c[l|f]] (more ...)
291              type, if present, can be a for annotated contours or c for regu‐
292              lar contours [Default]. The pen sets the attributes for the par‐
293              ticular line. Default pen for annotated  contours:  0.75p,black.
294              Regular  contours  use  pen  0.25p,black. If the modifier +cl is
295              appended then the color of the contour lines are taken from  the
296              CPT (see -C). If instead modifier +cf is appended then the color
297              from the cpt file is applied to the  contour  annotations.   Use
298              just +c for both effects.
299
300       -X[a|c|f|r][x-shift[u]]
301
302       -Y[a|c|f|r][y-shift[u]] (more ...)
303              Shift plot origin.
304
305       -bi[ncols][t] (more ...)
306              Select  native  binary  input. [Default is 3 input columns]. Use
307              4-byte integer triplets for node ids (-E).
308
309       -bo[ncols][type] (more ...)
310              Select native binary output. [Default is 3 output columns].
311
312       -d[i|o]nodata (more ...)
313              Replace input columns that equal nodata  with  NaN  and  do  the
314              reverse on output.
315
316       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
317              Only accept data records that match the given pattern.
318
319       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
320              Skip or produce header record(s).
321
322       -icols[+l][+sscale][+ooffset][,...] (more ...)
323              Select input columns and transformations (0 is first column).
324
325       -:[i|o] (more ...)
326              Swap 1st and 2nd column on input and/or output.
327
328       -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
329              Select perspective view.
330
331       -t[transp] (more ...)
332              Set PDF transparency level in percent.
333
334       -^ or just -
335              Print  a  short  message  about  the syntax of the command, then
336              exits (NOTE: on Windows just use -).
337
338       -+ or just +
339              Print an extensive usage (help) message, including the  explana‐
340              tion  of  any  module-specific  option  (but  not the GMT common
341              options), then exits.
342
343       -? or no arguments
344              Print a complete usage (help) message, including the explanation
345              of all options, then exits.
346

EXAMPLES

348       To  make a raw contour plot from the file topo.xyz and drawing the con‐
349       tours (pen = 2) given in the CPT topo.cpt  on  a  Lambert  map  at  0.5
350       inch/degree along the standard parallels 18 and 24, use
351
352              gmt pscontour topo.xyz -R320/330/20/30 -Jl18/24/0.5i -Ctopo.cpt -W0.5p > topo.ps
353
354       To create a color PostScript plot of the numerical temperature solution
355       obtained on a triangular mesh whose node coordinates  and  temperatures
356       are  stored  in  temp.xyz  and  mesh  arrangement  is given by the file
357       mesh.ijk, using the colors in temp.cpt, run
358
359              gmt pscontour temp.xyz -R0/150/0/100 -Jx0.1i -Ctemp.cpt -G -W0.25p > temp.ps
360
361       To save the triangulated 100-m contour lines in topo.txt  and  separate
362       them into multisegment files (one for each contour level), try
363
364              gmt pscontour topo.txt -C100 -Dcontours_%.0f.txt
365

SEE ALSO

367       gmt,   gmt.conf,   gmtcolors,   grdcontour,   grdimage,   nearneighbor,
368       psbasemap, psscale, surface, triangulate
369

REFERENCES

371       Watson, D. F., 1982, Acord: Automatic contouring of raw data,  Comp.  &
372       Geosci., 8, 97-101.
373
374       Shewchuk,  J. R., 1996, Triangle: Engineering a 2D Quality Mesh Genera‐
375       tor and Delaunay Triangulator, First Workshop on Applied  Computational
376       Geometry (Philadelphia, PA), 124-133, ACM, May 1996.
377
378       http://www.cs.cmu.edu/~quake/triangle.html
379
381       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
382
383
384
385
3865.4.5                            Feb 24, 2019                     PSCONTOUR(1)
Impressum