1r.patch(1) GRASS GIS User's Manual r.patch(1)
2
6 r.patch - Creates a composite raster map layer by using known category
7 values from one (or more) map layer(s) to fill in areas of "no data" in
8 another map layer.
9
11 raster, geometry, mosaicking, merge, patching, aggregation, series,
12 parallel
13
15 r.patch
16 r.patch --help
17 r.patch [-zs] input=name[,name,...] output=name [nprocs=integer]
18 [memory=memory in MB] [--overwrite] [--help] [--verbose] [--quiet]
19 [--ui]
20 Flags:
22 -z
23 Use zero (0) for transparency instead of NULL
24 -s
26 Do not create color and category files
27 --overwrite
29 Allow output files to overwrite existing files
30 --help
32 Print usage summary
33 --verbose
35 Verbose module output
36 --quiet
38 Quiet module output
39 --ui
41 Force launching GUI dialog
42 Parameters:
44 input=name[,name,...]Â [required]
45 Name of raster maps to be patched together
46 output=name [required]
48 Name for resultant raster map
49 nprocs=integer
51 Number of threads for parallel computing
52 Default: 1
53 memory=memory in MB
55 Maximum memory to be used (in MB)
56 Cache size for raster rows
57 Default: 300
58
60 The GRASS program r.patch allows the user to build a new raster map the
61 size and resolution of the current region by assigning known data val‐
62 ues from input raster maps to the cells in this region.
63 In case of overlapping input raster maps this is done by filling in "no
64 data" cells, those that do not yet contain data, contain NULL data, or,
65 optionally contain 0 data, with the data from the first input map.
66 Once this is done the remaining holes are filled in by the next input
67 map, and so on.
68 In case of adjacent input raster maps the output map contains the map
69 mosaic.
70 Hence this command is useful for
72 • making a composite raster map layer from two or more adjacent
74 map layers,
75 • for filling in "holes" in a raster map layer’s data (e.g., in
77 digital elevation data), or
78 • for updating an older map layer with more recent data.
80 The current geographic region definition and mask settings are re‐
81 spected.
82 Figure: Result of patching of two raster maps containing NULLs using
84 the default settings.
85 Stacking order
87 The first name listed in the string input=name,name,name,... is the
88 name of the first map whose data values will be used to fill in cells
89 in the current region. Then, the second through the last input maps
90 (..., name, name, ...) will be used, in order, to supply data values
91 for the remaining "no data" cells (or cells with value 0 with -z flag).
92 In other words, the first raster map is used first and if it had some
94 "no data" cells, then second raster map is used for these cells, then
95 the third and so on. So the formal command line syntax can be also
96 written as input=primary,secondary,tertiary,... For two raster maps,
97 the first one can be viewed as the primary one or the default one and
98 the second one as the secondary one or a fallback.
99 Figure: Result of patching of two raster maps using the -z flag to
101 treat zeros as NULLs. Note the value 1 being preserved from the first
102 raster while the value 6 is taken from the second raster instead of the
103 value 0 from the first raster because zeros are replaced with the -z
104 flag active.
105 Relation to SQL COALESCE() function
107 The module is corresponds to the SQL COALESCE() function. This func‐
108 tion takes two or more arguments and returns a copy of its first
109 non-NULL argument. If all arguments are NULL, the function returns
110 NULL.
111 The r.patch module iterates over all cells and for each cell of the
113 output raster map uses the first corresponding non-NULL cell in the se‐
114 ries of the input raster maps.
115 Example of filling areas
117 Below, the raster map layer on the far left is patched with the middle
118 (patching) raster map layer, to produce the composite raster map layer
119 on the right. The example assumes zero values to be treated as NULLs
120 (-z flag).
121 1 1 1 0 2 2 0 0 0 0 1 1 0 0 0 0 1 1 1 1 2 2 0 0
122 1 1 0 2 2 2 0 0 0 0 1 1 0 0 0 0 1 1 1 2 2 2 0 0
123 3 3 3 3 2 2 0 0 0 0 0 0 0 0 0 0 3 3 3 3 2 2 0 0
124 3 3 3 3 0 0 0 0 4 4 4 4 4 4 4 4 3 3 3 3 4 4 4 4
125 3 3 3 0 0 0 0 0 4 4 4 4 4 4 4 4 3 3 3 4 4 4 4 4
126 0 0 0 0 0 0 0 0 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4
127 Switching the patched and the patching raster map layers produces the
128 following results:
129 0 0 1 1 0 0 0 0 1 1 1 0 2 2 0 0 1 1 1 1 2 2 0 0
130 0 0 1 1 0 0 0 0 1 1 0 2 2 2 0 0 1 1 1 1 2 2 0 0
131 0 0 0 0 0 0 0 0 3 3 3 3 2 2 0 0 3 3 3 3 2 2 0 0
132 4 4 4 4 4 4 4 4 3 3 3 3 0 0 0 0 4 4 4 4 4 4 4 4
133 4 4 4 4 4 4 4 4 3 3 3 0 0 0 0 0 4 4 4 4 4 4 4 4
134 4 4 4 4 4 4 4 4 0 0 0 0 0 0 0 0 4 4 4 4 4 4 4 4
135
137 Frequently, this program is used to patch together adjacent map layers
138 which have been digitized separately. The program v.mkgrid can be used
139 to make adjacent maps align neatly.
140 The user should check the current geographic region settings before
142 running r.patch, to ensure that the region boundaries encompass all of
143 the data desired to be included in the composite map and to ensure that
144 the region resolution is the resolution of the desired data. To set the
145 geographic region settings to one or several raster maps, the g.region
146 program can be used:
147 g.region raster=map1[,map2[,...]]
148 Use of r.patch is generally followed by use of the GRASS programs g.re‐
150 move and g.rename; g.remove is used to remove the original (un-patched)
151 raster map layers, while g.rename is used to then assign to the
152 newly-created composite (patched) raster map layer the name of the
153 original raster map layer.
154 r.patch reads the existing category label files and color tables from
156 the input maps and creates these files for the patched, composite out‐
157 put map. This can be quite time consuming for certain maps, especially
158 if there are many different category values across the patched maps.
159 The -s flag allows disabling the reading and creation of these support
160 files, meaning that the output map will have no category labels and no
161 explicit color table.
162 Number of raster maps to be processed is given by the limit of the op‐
164 erating system. For example, both the hard and soft limits are typi‐
165 cally 1024. The soft limit can be changed with e.g. ulimit -n 1500
166 (UNIX-based operating systems) but not higher than the hard limit. If
167 it is too low, you can as superuser add an entry in
168 /etc/security/limits.conf
169 # <domain> <type> <item> <value>
170 your_username hard nofile 1500
171 This would raise the hard limit to 1500 file. Be warned that more files
172 open need more RAM. See also the Wiki page Hints for large raster data
173 processing.
174 Operating systems usually limit the length of the command line which
176 limits the number of input raster maps user can pass to the module us‐
177 ing the option input. In that case, r.series can be used instead of
178 r.patch.
179 PERFORMANCE
181 By specifying the number of parallel processes with nprocs option,
182 r.patch can run significantly faster, see benchmarks below.
183 Figure: Benchmark on the left shows execution time for different number
184 of cells, benchmark on the right shows execution time for different
185 memory size for 5000x5000 raster. See benchmark scripts in source code.
186 (Intel Core i9-10940X CPU @ 3.30GHz x 28)
187 To reduce the memory requirements to minimum, set option memory to
189 zero. To take advantage of the parallelization, GRASS GIS needs to
190 compiled with OpenMP enabled.
191
193 Example with three maps
194 The input are three maps called roads, water and forest. Primarily, we
195 want to use the values from roads, then from water and if no other val‐
196 ues are available we want to use forest. First we set the computation
197 region assuming that the all three maps fully overlap and have the same
198 resolution (so we can safely use the just the one without further modi‐
199 fications of the region). Then we perform the patching.
200 g.region raster=roads
201 r.patch input=roads,water,forest output=result
202 Map mosaic example using Bash syntax
204 Create a list of maps matching a pattern, extend the region to include
205 them all, and patch them together to create a mosaic. Overlapping maps
206 will be used in the order listed.
207 MAPS=`g.list type=raster separator=comma pat="map_*"`
208 g.region raster=$MAPS -p
209 r.patch input=$MAPS output=maps_mosaic
210
212 g.region, g.remove, g.rename, r.mapcalc, r.support, r.series, v.mkgrid
213 Hints for large raster data processing
215
217 Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
218 Huidae Cho (-z flag and performance improvement)
219 Aaron Saw Min Sern (OpenMP support).
220
222 Available at: r.patch source code (history)
223 Accessed: Saturday Jan 21 21:15:00 2023
225 Main index | Raster index | Topics index | Keywords index | Graphical
227 index | Full index
228 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
230GRASS 8.2.1 r.patch(1)