.\" Man page generated from reStructuredText.
.
.TH "PSMASK" "1gmt" "May 21, 2019" "5.4.5" "GMT"
.SH NAME
psmask \- Use data tables to clip or mask map areas with no coverage
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBpsmask\fP [ \fItable\fP ]
 \fB\-I\fP\fIincrement\fP
 \fB\-J\fP\fIparameters\fP
 \fB\-R\fP\fIregion\fP
[  \fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP ]
[  \fB\-D\fP\fIdumpfile\fP ]
[  \fB\-F\fP[\fBl\fP|\fBr\fP] ]
[  \fB\-G\fP\fIfill\fP ] [  \fB\-J\fP\fBz\fP|\fBZ\fP\fIparameters\fP ]
[  \fB\-K\fP ]
[  \fB\-L\fP[\fB+\fP|\fB\-\fP]\fInodegrid\fP ]
[  \fB\-N\fP ] [  \fB\-O\fP ]
[  \fB\-P\fP ] [  \fB\-Q\fP\fIcut\fP ]
[  \fB\-S\fP\fIsearch_radius\fP[\fIunit\fP] ]
[  \fB\-T\fP ]
[  \fB\-U\fP[\fIstamp\fP] ]
[  \fB\-V\fP[\fIlevel\fP] ]
[  \fB\-X\fP\fIx_offset\fP ]
[  \fB\-Y\fP\fIy_offset\fP ]
[ \fB\-bi\fPbinary ]
[ \fB\-di\fPnodata ]
[ \fB\-e\fPregexp ]
[ \fB\-h\fPheaders ]
[ \fB\-i\fPflags ]
[ \fB\-p\fPflags ]
[ \fB\-r\fP ]
[ \fB\-t\fPtransp ]
[ \fB\-:\fP[\fBi\fP|\fBo\fP] ]
.sp
\fBpsmask\fP \fB\-C\fP [ \fB\-K\fP ] [ \fB\-O\fP ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
\fBpsmask\fP reads a (\fIx\fP,\fIy\fP,\fIz\fP) 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 \fIradius\fP 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, \fBpsmask\fP will either
paint tiles to mask these nodes (with the \fB\-T\fP 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 \fBpsmask\fP using the \fB\-C\fP option.
.SH REQUIRED
.INDENT 0.0
.TP
\fB\-I\fP\fIxinc\fP[\fIunit\fP][\fB+e\fP|\fBn\fP][/\fIyinc\fP[\fIunit\fP][\fB+e\fP|\fBn\fP]]
\fIx_inc\fP [and optionally \fIy_inc\fP] is the grid spacing. Optionally,
append a suffix modifier. \fBGeographical (degrees) coordinates\fP: Append
\fBm\fP to indicate arc minutes or \fBs\fP to indicate arc seconds. If one
of the units \fBe\fP, \fBf\fP, \fBk\fP, \fBM\fP, \fBn\fP or \fBu\fP 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 \fIy_inc\fP is given
but set to 0 it will be reset equal to \fIx_inc\fP; otherwise it will be
converted to degrees latitude. \fBAll coordinates\fP: If \fB+e\fP is appended
then the corresponding max \fIx\fP (\fIeast\fP) or \fIy\fP (\fInorth\fP) 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 \fInumber of nodes\fP desired by
appending \fB+n\fP 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 \fB\-R\fP\fIgrdfile\fP is used then the grid spacing has
already been initialized; use \fB\-I\fP to override the values.
.UNINDENT
.INDENT 0.0
.TP
\fB\-J\fP\fIparameters\fP (more ...)
Select map projection. [Not mandatory when \-D].
.UNINDENT
.INDENT 0.0
.TP
\fB\-R\fP\fIxmin\fP/\fIxmax\fP/\fIymin\fP/\fIymax\fP[\fB+r\fP][\fB+u\fP\fIunit\fP] (more ...)
Specify the region of interest.  
.UNINDENT
.sp
For perspective view \fBp\fP, optionally append /\fIzmin\fP/\fIzmax\fP\&. (more ...)  
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
.B \fItable\fP
One or more ASCII (or binary, see \fB\-bi\fP[\fIncols\fP][\fItype\fP]) data
table file(s) holding a number of data columns. If no tables are given
then we read from standard input.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP (more ...)
Set map boundary frame and axes attributes.
.UNINDENT
.INDENT 0.0
.TP
\fB\-C\fP
Mark end of existing clip path. No input file is needed. Implicitly
sets \fB\-O\fP\&. Also supply \fB\-X\fP and \fB\-Y\fP settings if you have
moved since the clip started.
.UNINDENT
.INDENT 0.0
.TP
\fB\-D\fP\fIdumpfile\fP
Dump the (x,y) coordinates of each clipping polygon to one or more
output files (or \fIstdout\fP if \fItemplate\fP is not given). No plotting
will take place. If \fItemplate\fP 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 (\fItemplate\fP). The files are ASCII unless
\fB\-bo\fP is used. See \fB\-Q\fP to exclude small
polygons from consideration.
.UNINDENT
.INDENT 0.0
.TP
\fB\-F\fP[\fBl\fP|\fBr\fP]
Force clip contours (polygons) to be oriented so that data points are to the
left (\fB\-Fl\fP [Default]) or right (\fB\-Fr\fP) as we move along the perimeter
[Default is arbitrary orientation]. Requires \fB\-D\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-G\fP\fIfill\fP
Paint the clip polygons (or tiles) with a selected fill [Default is no fill].
.UNINDENT
.INDENT 0.0
.TP
\fB\-Jz\fP|\fBZ\fP\fIparameters\fP (more ...)
Set z\-axis scaling; same syntax as \fB\-Jx\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-K\fP (more ...)
Do not finalize the PostScript plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-L\fP[\fB+\fP|\fB\-\fP]\fInodegrid\fP
Save the internal grid with ones (data constraint) and zeros (no data) to
the named \fInodegrid\fP [no grid saved].  Use \fBL+\fP to convert the no data
flags to NaNs before writing the grid, while \fBL\-\fP will instead convert
the data flags to NaNs.
.UNINDENT
.INDENT 0.0
.TP
\fB\-N\fP
Invert the sense of the test, i.e., clip regions where there is data coverage.
.UNINDENT
.INDENT 0.0
.TP
\fB\-O\fP (more ...)
Append to existing PostScript plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-P\fP (more ...)
Select "Portrait" plot orientation.
.UNINDENT
.INDENT 0.0
.TP
\fB\-Q\fP
Do not dump polygons with less than \fIcut\fP number of points [Dumps
all polygons]. Only applicable if \fB\-D\fP has been specified.
.UNINDENT
.INDENT 0.0
.TP
\fB\-S\fP\fIsearch_radius\fP[\fIunit\fP]
Sets radius of influence. Grid nodes within \fIradius\fP 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).
.UNINDENT
.INDENT 0.0
.TP
\fB\-T\fP
Plot tiles instead of clip polygons. Use \fB\-G\fP to set tile color or
pattern. Cannot be used with \fB\-D\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-U\fP[[\fIjust\fP]/\fIdx\fP/\fIdy\fP/][\fBc\fP|\fIlabel\fP] (more ...)
Draw GMT time stamp logo on plot.
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.sp
\fB\-X\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIx\-shift\fP[\fBu\fP]]
.INDENT 0.0
.TP
\fB\-Y\fP[\fBa\fP|\fBc\fP|\fBf\fP|\fBr\fP][\fIy\-shift\fP[\fBu\fP]] (more ...)
Shift plot origin.
.UNINDENT
.INDENT 0.0
.TP
\fB\-bi\fP[\fIncols\fP][\fBt\fP] (more ...)
Select native binary input. [Default is 2 input columns].
.UNINDENT
.INDENT 0.0
.TP
\fB\-di\fP\fInodata\fP (more ...)
Replace input columns that equal \fInodata\fP with NaN.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-e\fP[\fB~\fP]\fI"pattern"\fP \fB|\fP \fB\-e\fP[\fB~\fP]/\fIregexp\fP/[\fBi\fP] (more ...)
Only accept data records that match the given pattern.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-h\fP[\fBi\fP|\fBo\fP][\fIn\fP][\fB+c\fP][\fB+d\fP][\fB+r\fP\fIremark\fP][\fB+r\fP\fItitle\fP] (more ...)
Skip or produce header record(s). Not used with binary data.
.UNINDENT
.INDENT 0.0
.TP
\fB\-i\fP\fIcols\fP[\fB+l\fP][\fB+s\fP\fIscale\fP][\fB+o\fP\fIoffset\fP][,\fI\&...\fP] (more ...)
Select input columns and transformations (0 is first column).
.UNINDENT
.INDENT 0.0
.TP
\fB\-p\fP[\fBx\fP|\fBy\fP|\fBz\fP]\fIazim\fP[/\fIelev\fP[/\fIzlevel\fP]][\fB+w\fP\fIlon0\fP/\fIlat0\fP[/\fIz0\fP]][\fB+v\fP\fIx0\fP/\fIy0\fP] (more ...)
Select perspective view.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-r\fP (more ...)
Set pixel node registration [gridline].  
.UNINDENT
.INDENT 0.0
.TP
\fB\-t\fP[\fItransp\fP] (more ...)
Set PDF transparency level in percent.
.UNINDENT
.INDENT 0.0
.TP
\fB\-:\fP[\fBi\fP|\fBo\fP] (more ...)
Swap 1st and 2nd column on input and/or output.
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
.UNINDENT
.SH UNITS
.sp
For map distance unit, append \fIunit\fP \fBd\fP for arc degree, \fBm\fP for arc
minute, and \fBs\fP for arc second, or \fBe\fP for meter [Default], \fBf\fP
for foot, \fBk\fP for km, \fBM\fP for statute mile, \fBn\fP for nautical mile,
and \fBu\fP for US survey foot. By default we compute such distances using
a spherical approximation with great circles. Prepend \fB\-\fP to a
distance (or the unit is no distance is given) to perform "Flat Earth"
calculations (quicker but less accurate) or prepend \fB+\fP to perform
exact geodesic calculations (slower but more accurate).
.SH EXAMPLES
.sp
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:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt psmask africa_grav.xyg \-R20/40/20/40 \-I5m \-JM10i \-O \-K > mask.ps
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
We do it again, but this time we wish to save the clipping polygons to
file all_pols.txt:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt psmask africa_grav.xyg \-R20/40/20/40 \-I5m \-Dall_pols.txt
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
A repeat of the first example but this time we use white tiling:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt psmask africa_grav.xyg \-R20/40/20/40 \-I5m \-JM10i \-T \-O \-K \-Gwhite > mask.ps
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
gmt, gmtcolors,
grdmask, surface,
psbasemap, psclip
.SH COPYRIGHT
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
.\" Generated by docutils manpage writer.
.