.TH r.mask 1grass "" "GRASS 7.8.5" "GRASS GIS User's Manual"
.SH NAME
\fI\fBr.mask\fR\fR  \- Creates a MASK for limiting raster operation.
.SH KEYWORDS
raster, mask
.SH SYNOPSIS
\fBr.mask\fR
.br
\fBr.mask \-\-help\fR
.br
\fBr.mask\fR [\-\fBir\fR]  [\fBraster\fR=\fIname\fR]   [\fBmaskcats\fR=\fIstring\fR]   [\fBvector\fR=\fIname\fR]   [\fBlayer\fR=\fIstring\fR]   [\fBcats\fR=\fIrange\fR]   [\fBwhere\fR=\fIsql_query\fR]   [\-\-\fBoverwrite\fR]  [\-\-\fBhelp\fR]  [\-\-\fBverbose\fR]  [\-\-\fBquiet\fR]  [\-\-\fBui\fR]
.SS Flags:
.IP "\fB\-i\fR" 4m
.br
Create inverse mask
.IP "\fB\-r\fR" 4m
.br
Remove existing mask (overrides other options)
.IP "\fB\-\-overwrite\fR" 4m
.br
Allow output files to overwrite existing files
.IP "\fB\-\-help\fR" 4m
.br
Print usage summary
.IP "\fB\-\-verbose\fR" 4m
.br
Verbose module output
.IP "\fB\-\-quiet\fR" 4m
.br
Quiet module output
.IP "\fB\-\-ui\fR" 4m
.br
Force launching GUI dialog
.SS Parameters:
.IP "\fBraster\fR=\fIname\fR" 4m
.br
Name of raster map to use as mask
.IP "\fBmaskcats\fR=\fIstring\fR" 4m
.br
Raster values to use for mask
.br
Format: 1 2 3 thru 7 *
.br
Default: \fI*\fR
.IP "\fBvector\fR=\fIname\fR" 4m
.br
Name of vector map to use as mask
.br
Or data source for direct OGR access
.IP "\fBlayer\fR=\fIstring\fR" 4m
.br
Layer number or name (vector)
.br
Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.
.br
Default: \fI1\fR
.IP "\fBcats\fR=\fIrange\fR" 4m
.br
Category values (vector)
.br
Example: 1,3,7\-9,13
.IP "\fBwhere\fR=\fIsql_query\fR" 4m
.br
WHERE conditions of SQL statement without \(cqwhere\(cq keyword (vector)
.br
Example: income < 1000 and population >= 10000
.SH DESCRIPTION
\fI\fBr.mask\fR\fR \- Facilitates creation of a raster \(dqMASK\(dq map to
control raster operations.
.PP
The MASK is only applied when \fIreading\fR an existing GRASS raster map,
for example when used in a module as an input map.
The MASK will block out certain areas of a raster map from analysis and/or
display, by \(dqhiding\(dq them from sight of other GRASS modules. Data falling
within the boundaries of the MASK can be modified and operated upon by other
GRASS raster modules; data falling outside the MASK is treated as if it were NULL.
.PP
Because the MASK is actually only a reclass map named \(dqMASK\(dq, it can be
copied, renamed, removed, and used in analyses, just like other GRASS
raster map layers.  The user should be aware that a MASK remains in
place until a user renames it to something other than \(dqMASK\(dq, or removes
it using \(dqr.mask \-r\(dq or \fIg.remove\fR.
.PP
Grid cells in the MASK map containing 0 or NULL
will replace data with NULL, while cells containing other values will allow
data to pass through unaltered.
.PP
To restore raster operations to normal (i.e., all cells of the current region),
remove the MASK file by setting the \fB\-r\fR remove MASK flag. In this case, a
dummy value must also be given for the input parameter.
A MASK also can be removed by using \fIg.remove\fR
or by renaming it to any other name with \fIg.rename\fR.
.SH NOTES
The above method for specifying a \(dqmask\(dq may seem
counterintuitive.  Areas inside the MASK are not hidden;
areas outside the MASK will be ignored until the MASK file
is removed.
.PP
The MASK is read as an integer map. If MASK is actually a
floating\-point map, the values will be converted to integers using the
map\(cqs quantisation rules (this defaults to round\-to\-nearest, but can
be changed with r.quant).
.PP
\fIr.mask\fR uses \fIr.reclass\fR to create a reclassification of an
existing raster map and name it MASK. A reclass map takes up less space, but
is affected by any changes to the underlying map from which it was created.
The user can select category values from the input raster to use in the MASK
with the \fImaskcats\fR parameter; if \fIr.mask\fR is run from the
command line, the category values listed in \fImaskcats\fR must be quoted
(see example below).
.PP
Somewhat similar program functions to those performed by
\fIr.mask\fR can be done using \fIr.mapcalc\fR,
\fIg.region\fR, and other commands.
.SH EXAMPLES
The examples are based on the North Carolina sample dataset.
.PP
Create a raster mask, for contraining the calculation of
univariate statistics of the elevation values for \(dqlakes\(dq:
.br
.nf
\fC
# set computation region to lakes raster map
g.region raster=lakes \-p
# use lakes as MASK
r.mask raster=lakes
# get statistics for elevation pixels of lakes:
r.univar elevation
\fR
.fi
Remove the raster mask (\(dqMASK\(dq map) with the \-r flag:
.br
.nf
\fC
r.mask \-r
\fR
.fi
Creating a mask from selected categories in the North Carolina
\(cqgeology_30m\(cq raster map:
.br
.nf
\fC
g.region raster=geology_30m \-p
r.category geology_30m
d.mon wx0
d.rast geology_30m
r.mask raster=geology_30m maskcats=\(dq217 thru 720\(dq
d.mon wx0
d.rast geology_30m
\fR
.fi
.SH SEE ALSO
\fI
g.region,
r.mapcalc,
r.reclass,
g.remove,
g.rename
\fR
.SH AUTHOR
Michael Barton, Arizona State University
.SH SOURCE CODE
.PP
Available at: r.mask source code (history)
.PP
Main index |
Raster index |
Topics index |
Keywords index |
Graphical index |
Full index
.PP
© 2003\-2020
GRASS Development Team,
GRASS GIS 7.8.5 Reference Manual