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 inhab >= 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

       Last changed: $Date: 2014-12-19 22:55:37 +0100 (Fri, 19 Dec 2014) $

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

       © 2003-2016 GRASS Development Team, GRASS GIS 7.0.3 Reference Manual