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

SEE ALSO

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

AUTHOR

       Michael Barton, Arizona State University

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

       Full index

       © 2003-2013 GRASS Development Team

GRASS 6.4.3                                                                                       r.mask(1grass)