1r.patch(1) Grass 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
14 r.patch
15 r.patch --help
16 r.patch [-zs] input=name[,name,...] output=name [--overwrite]
17 [--help] [--verbose] [--quiet] [--ui]
18 Flags:
20 -z
21 Use zero (0) for transparency instead of NULL
22 -s
24 Do not create color and category files
25 --overwrite
27 Allow output files to overwrite existing files
28 --help
30 Print usage summary
31 --verbose
33 Verbose module output
34 --quiet
36 Quiet module output
37 --ui
39 Force launching GUI dialog
40 Parameters:
42 input=name[,name,...] [required]
43 Name of raster maps to be patched together
44 output=name [required]
46 Name for resultant raster map
47
49 The GRASS program r.patch allows the user to build a new raster map the
50 size and resolution of the current region by assigning known data val‐
51 ues from input raster maps to the cells in this region.
52 In case of overlapping input raster maps this is done by filling in "no
53 data" cells, those that do not yet contain data, contain NULL data, or,
54 optionally contain 0 data, with the data from the first input map.
55 Once this is done the remaining holes are filled in by the next input
56 map, and so on.
57 In case of adjacent input raster maps the output map contains the map
58 mosaic.
59 Hence this command is useful for
61 · making a composite raster map layer from two or more adjacent
63 map layers,
64 · for filling in "holes" in a raster map layer’s data (e.g., in
66 digital elevation data), or
67 · for updating an older map layer with more recent data.
69 The current geographic region definition and mask settings are
70 respected.
71 Figure: Result of patching of two raster maps containing NULLs using
73 the default settings.
74 Stacking order
76 The first name listed in the string input=name,name,name,... is the
77 name of the first map whose data values will be used to fill in cells
78 in the current region. Then, the second through the last input maps
79 (..., name, name, ...) will be used, in order, to supply data values
80 for the remaining "no data" cells (or cells with value 0 with -z flag).
81 In other words, the first raster map is used first and if it had some
83 "no data" cells, then second raster map is used for these cells, then
84 the third and so on. So the formal command line syntax can be also
85 written as input=primary,secondary,tertiary,... For two raster maps,
86 the first one can be viewed as the primary one or the default one and
87 the second one as the secondary one or a fallback.
88 Figure: Result of patching of two raster maps using the -z flag to
90 treat zeros as NULLs. Note the value 1 being preserved from the first
91 raster while the value 6 is taken from the second raster instead of the
92 value 0 from the first raster because zeros are replaced with the -z
93 flag active.
94 Relation to SQL COALESCE() function
96 The module is corresponds to the SQL COALESCE() function. This func‐
97 tion takes two or more arguments and returns a copy of its first
98 non-NULL argument. If all arguments are NULL, the function returns
99 NULL.
100 The r.patch module iterates over all cells and for each cell of the
102 output raster map uses the first corresponding non-NULL cell in the
103 series of the input raster maps.
104 Example of filling areas
106 Below, the raster map layer on the far left is patched with the middle
107 (patching) raster map layer, to produce the composite raster map layer
108 on the right. The example assumes zero values to be treated as NULLs
109 (-z flag).
110 1 1 1 0 2 2 0 0 0 0 1 1 0 0 0 0 1 1 1 1 2 2 0 0
111 1 1 0 2 2 2 0 0 0 0 1 1 0 0 0 0 1 1 1 2 2 2 0 0
112 3 3 3 3 2 2 0 0 0 0 0 0 0 0 0 0 3 3 3 3 2 2 0 0
113 3 3 3 3 0 0 0 0 4 4 4 4 4 4 4 4 3 3 3 3 4 4 4 4
114 3 3 3 0 0 0 0 0 4 4 4 4 4 4 4 4 3 3 3 4 4 4 4 4
115 0 0 0 0 0 0 0 0 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4
116 Switching the patched and the patching raster map layers produces the
117 following results:
118 0 0 1 1 0 0 0 0 1 1 1 0 2 2 0 0 1 1 1 1 2 2 0 0
119 0 0 1 1 0 0 0 0 1 1 0 2 2 2 0 0 1 1 1 1 2 2 0 0
120 0 0 0 0 0 0 0 0 3 3 3 3 2 2 0 0 3 3 3 3 2 2 0 0
121 4 4 4 4 4 4 4 4 3 3 3 3 0 0 0 0 4 4 4 4 4 4 4 4
122 4 4 4 4 4 4 4 4 3 3 3 0 0 0 0 0 4 4 4 4 4 4 4 4
123 4 4 4 4 4 4 4 4 0 0 0 0 0 0 0 0 4 4 4 4 4 4 4 4
124
126 Frequently, this program is used to patch together adjacent map layers
127 which have been digitized separately. The program v.mkgrid can be used
128 to make adjacent maps align neatly.
129 The user should check the current geographic region settings before
131 running r.patch, to ensure that the region boundaries encompass all of
132 the data desired to be included in the composite map and to ensure that
133 the region resolution is the resolution of the desired data. To set the
134 geographic region settings to one or several raster maps, the g.region
135 program can be used:
136 g.region raster=map1[,map2[,...]]
137 Use of r.patch is generally followed by use of the GRASS programs
139 g.remove and g.rename; g.remove is used to remove the original
140 (un-patched) raster map layers, while g.rename is used to then assign
141 to the newly-created composite (patched) raster map layer the name of
142 the original raster map layer.
143 r.patch reads the existing category label files and color tables from
145 the input maps and creates these files for the patched, composite out‐
146 put map. This can be quite time consuming for certain maps, especially
147 if there are many different category values across the patched maps.
148 The -s flag allows disabling the reading and creation of these support
149 files, meaning that the output map will have no category labels and no
150 explicit color table.
151 Number of raster maps to be processed is given by the limit of the
153 operating system. For example, both the hard and soft limits are typi‐
154 cally 1024. The soft limit can be changed with e.g. ulimit -n 1500
155 (UNIX-based operating systems) but not higher than the hard limit. If
156 it is too low, you can as superuser add an entry in
157 /etc/security/limits.conf
158 # <domain> <type> <item> <value>
159 your_username hard nofile 1500
160 This would raise the hard limit to 1500 file. Be warned that more files
161 open need more RAM. See also the Wiki page Hints for large raster data
162 processing.
163 Operating systems usually limit the length of the command line which
165 limits the number of input raster maps user can pass to the module
166 using the option input. In that case, r.series can be used instead of
167 r.patch.
168
170 Example with three maps
171 The input are three maps called roads, water and forest. Primarily, we
172 want to use the values from roads, then from water and if no other val‐
173 ues are available we want to use forest. First we set the computation
174 region assuming that the all three maps fully overlap and have the same
175 resolution (so we can safely use the just the one without further modi‐
176 fications of the region). Then we perform the patching.
177 g.region raster=roads
178 r.patch input=roads,water,forest output=result
179 Map mosaic example using Bash syntax
181 Create a list of maps matching a pattern, extend the region to include
182 them all, and patch them together to create a mosaic. Overlapping maps
183 will be used in the order listed.
184 MAPS=`g.list type=raster separator=comma pat="map_*"`
185 g.region raster=$MAPS -p
186 r.patch input=$MAPS output=maps_mosaic
187
189 g.region, g.remove, g.rename, r.mapcalc, r.support, r.series, v.mkgrid
190 Hints for large raster data processing
192
194 Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
195 -z flag and performance improvement by Huidae Cho
196 Last changed: $Date: 2018-11-26 08:50:32 +0100 (Mon, 26 Nov 2018) $
198
200 Available at: r.patch source code (history)
201 Main index | Raster index | Topics index | Keywords index | Graphical
203 index | Full index
204 © 2003-2019 GRASS Development Team, GRASS GIS 7.6.0 Reference Manual
206GRASS 7.6.0 r.patch(1)