1r.mask(1)                   GRASS GIS User's Manual                  r.mask(1)
2
3
4

NAME

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

KEYWORDS

9       raster, mask, null data, no-data
10

SYNOPSIS

12       r.mask
13       r.mask --help
14       r.mask   [-ir]    [raster=name]     [maskcats=string]     [vector=name]
15       [layer=string]     [cats=range]     [where=sql_query]     [--overwrite]
16       [--help]  [--verbose]  [--quiet]  [--ui]
17
18   Flags:
19       -i
20           Create inverse mask
21
22       -r
23           Remove existing mask (overrides other options)
24
25       --overwrite
26           Allow output files to overwrite existing files
27
28       --help
29           Print usage summary
30
31       --verbose
32           Verbose module output
33
34       --quiet
35           Quiet module output
36
37       --ui
38           Force launching GUI dialog
39
40   Parameters:
41       raster=name
42           Name of raster map to use as mask
43
44       maskcats=string
45           Raster values to use for mask
46           Format: 1 2 3 thru 7 *
47           Default: *
48
49       vector=name
50           Name of vector map to use as mask
51           Or data source for direct OGR access
52
53       layer=string
54           Layer number or name (vector)
55           Vector  features can have category values in different layers. This
56           number determines which layer to use. When used with direct OGR ac‐
57           cess this is the layer name.
58           Default: 1
59
60       cats=range
61           Category values (vector)
62           Example: 1,3,7-9,13
63
64       where=sql_query
65           WHERE conditions of SQL statement without ’where’ keyword (vector)
66           Example: income < 1000 and population >= 10000
67

DESCRIPTION

69       r.mask  - Facilitates creation of a raster "MASK" map to control raster
70       operations.
71
72       The MASK is applied when reading an existing GRASS raster map, for  ex‐
73       ample  when  used  as an input map in a module. The MASK will block out
74       certain areas of a raster map from analysis and/or display, by "hiding"
75       them  from sight of other GRASS modules. Data falling within the bound‐
76       aries of the MASK can be modified and  operated  upon  by  other  GRASS
77       raster  modules; data falling outside the MASK is treated as if it were
78       NULL.
79
80       By default, r.mask converts any non-NULL value in the  input  map,  in‐
81       cluding  zero,  to 1. All these areas will be part of the MASK (see the
82       notes for more details). To only convert specific values (or  range  of
83       values) to 1 and the rest to NULL, use the maskcats parameter.
84
85       Because  the  MASK  created  with r.mask is actually only a reclass map
86       named "MASK", it can be copied, renamed, removed, and used in analyses,
87       just like other GRASS raster map layers.
88
89       The  user should be aware that a MASK remains in place until a user re‐
90       names it to something other than "MASK", or removes  it.  To  remove  a
91       mask  and  restore  raster operations to normal (i.e., all cells of the
92       current region), remove the MASK by setting the  -r  remove  MASK  flag
93       (r.mask -r).  Alternatively, a mask can be removed using g.remove or by
94       renaming it to any other name with g.rename.
95

NOTES

97       The above method for specifying a "mask" may seem counterintuitive. Ar‐
98       eas  inside the MASK are not hidden; areas outside the MASK will be ig‐
99       nored until the MASK file is removed.
100
101       r.mask uses r.reclass to  create  a  reclassification  of  an  existing
102       raster  map and name it MASK. A reclass map takes up less space, but is
103       affected by any changes to the underlying map from which  it  was  cre‐
104       ated.  The user can select category values from the input raster to use
105       in the MASK with the maskcats parameter; if r.mask is run from the com‐
106       mand  line,  the category values listed in maskcats must be quoted (see
107       example below). Note that the maskcats can only be used  if  the  input
108       map is an integer map.
109
110   Different ways to create a MASK
111       The  r.mask  function  creates  a MASK with values 1 and NULL. But note
112       that a MASK can also be created  using  other  functions  that  have  a
113       raster as output, by naming the output raster ’MASK’. Such layers could
114       have other values than 1 and NULL. The user should therefore  be  aware
115       that  grid cells in the MASK map containing NULL or 0 will replace data
116       with NULL, while cells containing other values will allow data to  pass
117       through unaltered. This means that:
118
119       If  a  binary  map  with  [0,1]  values is used as input in r.mask, all
120       raster cells with 0 and 1 will be part of the  MASK.  This  is  because
121       r.mask converts all non-NULL cells to 1.
122       r.mapcalc -s "map1 = round(rand(0,1))"
123       r.mask raster=map1
124       On  the  other  hand,  if a binary map is used as an input in g.copy to
125       create a MASK, only the raster cells with value 1 will be part  of  the
126       MASK.
127       r.mapcalc -s "map2 = round(rand(0,1))"
128       g.copy raster=map2,MASK
129
130   Handling of floating-point maps
131       r.mask treats floating-point maps the same as integer maps (except that
132       floating maps are not allowed in combination with the maskcats  parame‐
133       ter);  all  non-NULL  values of the input raster map are converted to 1
134       and are thus part of the MASK. In the example below, all  raster  cells
135       are part of the MASK, i.e., nothing is blocked out from analysis and/or
136       display.
137       r.mapcalc -s "map3 = rand(0.0,1.0)"
138       r.mask raster=map3
139       However, when using another method than r.mask to create  a  mask,  the
140       user  should  be aware that the MASK is read as an integer map. If MASK
141       is a floating-point map, the values will be converted to integers using
142       the  map’s  quantisation  rules (this defaults to round-to-nearest, but
143       can be changed with r.quant).
144       r.mapcalc -s "map4 = rand(0.0,1.0)"
145       g.copy raster=map4,MASK
146       In the example above, raster cells with a rounded value of 1  are  part
147       of the MASK, while raster cells with a rounded value of 0 are converted
148       to NULL and consequently blocked out from analysis and/or display.
149

EXAMPLES

151       The examples are based on the North Carolina sample dataset.
152
153       Create a raster mask, for contraining  the  calculation  of  univariate
154       statistics of the elevation values for "lakes":
155       # set computation region to lakes raster map
156       g.region raster=lakes -p
157       # use lakes as MASK
158       r.mask raster=lakes
159       # get statistics for elevation pixels of lakes:
160       r.univar elevation
161       Remove the raster mask ("MASK" map) with the -r flag:
162       r.mask -r
163       Creating  a  mask from selected categories in the North Carolina ’geol‐
164       ogy_30m’ raster map:
165       g.region raster=geology_30m -p
166       r.category geology_30m
167       d.mon wx0
168       d.rast geology_30m
169       r.mask raster=geology_30m maskcats="217 thru 720"
170       d.mon wx0
171       d.rast geology_30m
172

SEE ALSO

174        g.region, r.mapcalc, r.reclass, g.remove, g.rename r.quant
175

AUTHOR

177       Michael Barton, Arizona State University
178

SOURCE CODE

180       Available at: r.mask source code (history)
181
182       Accessed: Saturday Jan 21 21:17:02 2023
183
184       Main index | Raster index | Topics index | Keywords index  |  Graphical
185       index | Full index
186
187       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
188
189
190
191GRASS 8.2.1                                                          r.mask(1)
Impressum