NAME

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

KEYWORDS

       raster, mask

SYNOPSIS

       r.mask
       r.mask --help
       r.mask   [-ir]    [raster=name]     [maskcats=string]     [vector=name]    [layer=string]    [cats=range]
       [where=sql_query]   [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

   Flags:
       -i
           Create inverse mask

       -r
           Remove existing mask (overrides other options)

       --overwrite
           Allow output files to overwrite existing files

       --help
           Print usage summary

       --verbose
           Verbose module output

       --quiet
           Quiet module output

       --ui
           Force launching GUI dialog

   Parameters:
       raster=name
           Name of raster map to use as mask

       maskcats=string
           Raster values to use for mask
           Format: 1 2 3 thru 7 *
           Default: *

       vector=name
           Name of vector map to use as mask
           Or data source for direct OGR access

       layer=string
           Layer number or name (vector)
           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.
           Default: 1

       cats=range
           Category values (vector)
           Example: 1,3,7-9,13

       where=sql_query
           WHERE conditions of SQL statement without ’where’ keyword (vector)
           Example: income < 1000 and population >= 10000

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 file 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 file 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

       The examples are based on the North Carolina sample dataset.

       Create  a  raster  mask, for contraining the calculation of univariate statistics of the elevation values
       for "lakes":
       # 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
       Remove the raster mask ("MASK" map) with the -r flag:
       r.mask -r
       Creating a mask from selected categories in the North Carolina ’geology_30m’ raster map:
       g.region raster=geology_30m -p
       r.category geology_30m
       d.mon wx0
       d.rast geology_30m
       r.mask raster=geology_30m maskcats="217 thru 720"
       d.mon wx0
       d.rast geology_30m

SEE ALSO

        g.region, r.mapcalc, r.reclass, g.remove, g.rename

AUTHOR

       Michael Barton, Arizona State University

SOURCE CODE

       Available at: r.mask source code (history)

       Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual