Provided by: gmt-common_5.4.5+dfsg-2_all 
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