1r.mask(1) GRASS GIS User's Manual r.mask(1)
2
3
4
6 r.mask - Creates a MASK for limiting raster operation.
7
9 raster, mask, null data, no-data
10
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
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
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
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
174 g.region, r.mapcalc, r.reclass, g.remove, g.rename r.quant
175
177 Michael Barton, Arizona State University
178
180 Available at: r.mask source code (history)
181
182 Accessed: Mon Jun 20 16:47:45 2022
183
184 Main index | Raster index | Topics index | Keywords index | Graphical
185 index | Full index
186
187 © 2003-2022 GRASS Development Team, GRASS GIS 8.2.0 Reference Manual
188
189
190
191GRASS 8.2.0 r.mask(1)