Provided by: gmt-common_5.4.5+dfsg-1_all bug

NAME

       psmask - Use data tables to clip or mask map areas with no coverage

SYNOPSIS

       psmask [ table ]
        -Iincrement
        -Jparameters
        -Rregion   [    -B[p|s]parameters  ]  [   -Ddumpfile  ]  [   -F[l|r]  ]  [   -Gfill  ]  [
       -Jz|Zparameters ] [  -K ] [  -L[+|-]nodegrid ] [  -N ] [  -O ]  [   -P  ]  [   -Qcut  ]  [
       -Ssearch_radius[unit]  ]  [   -T  ]  [   -U[stamp]  ]  [   -V[level]  ]  [  -Xx_offset ] [
       -Yy_offset ] [ -bibinary ] [ -dinodata ] [ -eregexp ] [ -hheaders ] [ -iflags ] [  -pflags
       ] [ -r ] [ -ttransp ] [ -:[i|o] ]

       psmask -C [ -K ] [ -O ]

       Note: No space is allowed between the option flag and the associated arguments.

DESCRIPTION

       psmask  reads  a  (x,y,z)  file  [or standard input] and uses this information to find out
       which grid cells are reliable. Only grid cells which have one  or  more  data  points  are
       considered  reliable.  As an option, you may specify a radius of influence. Then, all grid
       cells that are within radius of a data point are  considered  reliable.   Furthermore,  an
       option  is  provided  to  reverse  the  sense  of the test.  Having found the reliable/not
       reliable points, psmask will either paint tiles to mask these nodes (with the -T  switch),
       or  use  contouring  to  create  polygons that will clip out regions of no interest.  When
       clipping is initiated, it will stay in effect until turned off by a second call to  psmask
       using the -C option.

REQUIRED

       -Ixinc[unit][+e|n][/yinc[unit][+e|n]]
              x_inc  [and  optionally  y_inc]  is  the  grid spacing. Optionally, append a suffix
              modifier. Geographical (degrees) coordinates: Append m to indicate arc minutes or s
              to  indicate  arc  seconds.  If  one  of  the  units e, f, k, M, n or u is appended
              instead, the increment is assumed to be given in meter, foot,  km,  Mile,  nautical
              mile  or  US  survey  foot,  respectively,  and will be converted to the equivalent
              degrees longitude at the middle latitude of the region (the conversion  depends  on
              PROJ_ELLIPSOID).  If  y_inc  is given but set to 0 it will be reset equal to x_inc;
              otherwise it will be converted to degrees  latitude.  All  coordinates:  If  +e  is
              appended  then the corresponding max x (east) or y (north) may be slightly adjusted
              to fit exactly the given increment  [by  default  the  increment  may  be  adjusted
              slightly  to fit the given domain]. Finally, instead of giving an increment you may
              specify the number of nodes  desired  by  appending  +n  to  the  supplied  integer
              argument;  the  increment  is  then  recalculated  from the number of nodes and the
              domain. The resulting increment value  depends  on  whether  you  have  selected  a
              gridline-registered  or  pixel-registered  grid;  see App-file-formats for details.
              Note: if -Rgrdfile is used then the grid spacing has already been initialized;  use
              -I to override the values.

       -Jparameters (more ...)
              Select map projection. [Not mandatory when -D].

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

       -B[p|s]parameters (more ...)
              Set map boundary frame and axes attributes.

       -C     Mark end of existing clip path. No input file is needed. Implicitly sets  -O.  Also
              supply -X and -Y settings if you have moved since the clip started.

       -Ddumpfile
              Dump the (x,y) coordinates of each clipping polygon to one or more output files (or
              stdout if template is not given). No plotting will take place. If template contains
              the C-format specifier %d (including modifications like %05d) then polygons will be
              written to different files; otherwise all polygons are  written  to  the  specified
              file  (template).  The  files are ASCII unless -bo is used. See -Q to exclude small
              polygons from consideration.

       -F[l|r]
              Force clip contours (polygons) to be oriented so that data points are to  the  left
              (-Fl [Default]) or right (-Fr) as we move along the perimeter [Default is arbitrary
              orientation]. Requires -D.

       -Gfill Paint the clip polygons (or tiles) with a selected fill [Default is no fill].

       -Jz|Zparameters (more ...)
              Set z-axis scaling; same syntax as -Jx.

       -K (more ...)
              Do not finalize the PostScript plot.

       -L[+|-]nodegrid
              Save the internal grid with ones (data constraint) and zeros (no data) to the named
              nodegrid  [no  grid  saved].   Use  L+  to convert the no data flags to NaNs before
              writing the grid, while L- will instead convert the data flags to NaNs.

       -N     Invert the sense of the test, i.e., clip regions where there is data coverage.

       -O (more ...)
              Append to existing PostScript plot.

       -P (more ...)
              Select "Portrait" plot orientation.

       -Q     Do not dump polygons with less than cut number of points [Dumps all polygons]. Only
              applicable if -D has been specified.

       -Ssearch_radius[unit]
              Sets  radius  of influence. Grid nodes within radius of a data point are considered
              reliable. [Default is 0, which means that only grid cells with  data  in  them  are
              reliable]. Append the distance unit (see UNITS).

       -T     Plot tiles instead of clip polygons. Use -G to set tile color or pattern. Cannot be
              used with -D.

       -U[[just]/dx/dy/][c|label] (more ...)
              Draw GMT time stamp logo on plot.

       -V[level] (more ...)
              Select verbosity level [c].

       -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 2 input columns].

       -dinodata (more ...)
              Replace input columns that equal nodata with NaN.

       -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). Not used with binary data.

       -icols[+l][+sscale][+ooffset][,...] (more ...)
              Select input columns and transformations (0 is first column).

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

       -r (more ...)
              Set pixel node registration [gridline].

       -t[transp] (more ...)
              Set PDF transparency level in percent.

       -:[i|o] (more ...)
              Swap 1st and 2nd column on input and/or output.

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

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. Prepend - to a distance (or the unit is no  distance  is
       given)  to  perform  "Flat Earth" calculations (quicker but less accurate) or prepend + to
       perform exact geodesic calculations (slower but more accurate).

EXAMPLES

       To make an overlay PostScript file that will mask out the regions of a contour  map  where
       there is no control data using clip polygons, use:

              gmt psmask africa_grav.xyg -R20/40/20/40 -I5m -JM10i -O -K > mask.ps

       We do it again, but this time we wish to save the clipping polygons to file all_pols.txt:

              gmt psmask africa_grav.xyg -R20/40/20/40 -I5m -Dall_pols.txt

       A repeat of the first example but this time we use white tiling:

              gmt psmask africa_grav.xyg -R20/40/20/40 -I5m -JM10i -T -O -K -Gwhite > mask.ps

SEE ALSO

       gmt, gmtcolors, grdmask, surface, psbasemap, psclip

COPYRIGHT

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