GRASS GIS manual: r.mask

Note: A new GRASS GIS stable version has been released: GRASS GIS 7. Go directly to the new manual page here

NAME

r.mask - Creates a MASK for limiting raster operation.

KEYWORDS

raster, mask

SYNOPSIS

r.mask
r.mask help
r.mask [-ior] [input=string] [maskcats=string] [--verbose] [--quiet]

Flags:

-i: Create inverse MASK from specified 'maskcats' list
-o: Overwrite existing MASK
-r: Remove existing MASK (overrides other options)
--verbose: Verbose module output
--quiet: Quiet module output

Parameters:

input=string: Raster map to use as MASK
maskcats=string: Category values to use for MASK (format: 1 2 3 thru 7 *); Default: *

DESCRIPTION

r.mask - Facilitates creation of a raster "MASK" map to control raster operations.

The MASK is only applied when reading 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 "hiding" them from sight of other GRASS modules. Data falling within the bounaries 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.

Because the MASK is actually only a reclass map named "MASK", 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 "MASK", or removes it using "r.mask -r" or g.remove.

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.

To restore raster operations to normal (i.e., all cells of the current region), remove the MASK map by setting the -r 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 g.remove or by renaming it to any other name with g.rename.

NOTES

The above method for specifying a "mask" may seem counterintuitive. Areas inside the MASK are not hidden; areas outside the MASK will be ignored until the MASK map is removed.

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's quantisation rules (this defaults to round-to-nearest, but can be changed with r.quant).

r.mask uses r.reclass 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 maskcats parameter; if r.mask is run from the command line, the category values listed in maskcats must be quoted (see example below).

Somewhat similar program functions to those performed by r.mask can be done using r.mapcalc, g.region, and other commands.

EXAMPLES

Creating a raster MASK, for showing only elevations of lakes:

r.mask input=lakes
# statistics only for elevation pixels in the lakes:
r.univar elevation

Removing a raster MASK with the -r flag:

r.mask -r

Creating a MASK from categories 3 through 6 in the North Carolina 'geology_30m' raster map:

g.region rast=geology_30m -p
r.category geology_30m
d.mon x0
d.rast geology_30m
r.mask input=geology_30m maskcats="217 thru 720"
d.erase
d.rast geology_30m

AUTHOR

Michael Barton, Arizona State University

Last changed: $Date: 2012-02-22 11:36:23 -0800 (Wed, 22 Feb 2012) $

Main index - raster index - Full index