xenial (1) pscontour.1gmt.gz

Provided by: gmt-common_5.2.1+dfsg-3build1_all bug

NAME

       pscontour - Contour table data by direct triangulation [method]

SYNOPSIS

       pscontour  [ table ] [+]cpt parameters west/east/south/north[/zmin/zmax][r] [ [-|[+]annot_int][labelinfo]
       ] [ [p|s]parameters ] [ [template] ] [ indexfile ] [ [d|f|n|l|L|x|X]params ] [  ] [ z|Zparameters ] [   ]
       [ pen ] [  ] [  ] [  ] [ cut ] [ [p|t] ] [ [+|-][+dgap[/length]][+l[labels]] ] [ [just/dx/dy/][c|label] ]
       [ [level] ] [ [+]pen ] [ x_offset ] [ y_offset ] [ -b<binary> ] [ -ccopies ] [ -h<headers> ] [  -i<flags>
       ] [ -p<flags> ] [ -t<transp> ] [ -:[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
       file.  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 file.
                 The color boundaries are then used as contour levels. If the CPT file 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 file, 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.

       -R[unit]xmin/xmax/ymin/ymax[r] (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, 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].

       -B[p|s]parameters (more ...)
              Set map boundary intervals.

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

       -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[+]pen (more ...)
              Select contouring and set contour pen attributes. If the + flag is prepended then the color of the
              contour lines are taken from the CPT file (see -C). If the - flag is prepended then the color from
              the CPT file is applied both to the contours and the contour annotations.

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

       -ccopies (more ...)
              Specify number of plot copies [Default is 1].

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
              Skip or produce header record(s).

       -icols[l][sscale][ooffset][,...] (more ...)
              Select input columns (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 use just -).

       -+ 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 options, then exits.

       --version
              Print GMT version and exit.

       --show-datadir
              Print full path to GMT share directory and exit.

EXAMPLES

       To make a raw contour plot from the file topo.xyz and drawing the contours (pen = 2)  given  in  the  CPT
       file 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

       2015, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe