psmask(1) GMT psmask(1)
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 informa-
tion 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 reli-
able/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, nau-
tical mile or US survey foot, respectively, and will be con-
verted to the equivalent degrees longitude at the middle lati-
tude 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 coordi-
nates: 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 recalcu-
lated from the number of nodes and the domain. The resulting
increment value depends on whether you have selected a grid-
line-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 a|)
Select map projection. [Not mandatory when -D].
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
Specify the region of interest.
For perspective view p, optionally append /zmin/zmax. (more a|)
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 a|)
Set map boundary frame and axes attributes.
-C Mark end of existing clip path. No input file is needed. Implic-
itly 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 plot-
ting will take place. If template contains the C-format speci-
fier %d (including modifications like %05d) then polygons will
be written to different files; otherwise all polygons are writ-
ten to the specified file (template). The files are ASCII unless
-bo is used. See -Q to exclude small polygons from considera-
tion.
-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 a|)
Set z-axis scaling; same syntax as -Jx.
-K (more a|)
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 a|)
Append to existing PostScript plot.
-P (more a|)
Select aPortraita 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 dis-
tance 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 a|)
Draw GMT time stamp logo on plot.
-V[level] (more a|)
Select verbosity level [c].
-X[a|c|f|r][x-shift[u]]
-Y[a|c|f|r][y-shift[u]] (more a|)
Shift plot origin.
-bi[ncols][t] (more a|)
Select native binary input. [Default is 2 input columns].
-dinodata (more a|)
Replace input columns that equal nodata with NaN.
-e[~]^<i>apattern^<i>a | -e[~]/regexp/[i] (more a|)
Only accept data records that match the given pattern.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more a|)
Skip or produce header record(s). Not used with binary data.
-icols[+l][+sscale][+ooffset][,^<i>a|] (more a|)
Select input columns and transformations (0 is first column).
-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more a|)
Select perspective view.
-r (more a|)
Set pixel node registration [gridline].
-t[transp] (more a|)
Set PDF transparency level in percent.
-:[i|o] (more a|)
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 explana-
tion 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 aFlat Eartha 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(1), gmtcolors(5), grdmask(1), surface(1), psbasemap(1), psclip(1)
COPYRIGHT
2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
5.4.2 Jun 24, 2017 psmask(1)
gmt5 5.4.2 - Generated Thu Jun 29 15:31:41 CDT 2017