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 two raster maps containing NULLs using the
73 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 "no
78 data" cells in the current region. The second through last input name
79 maps will be used, in order, to supply data values for for the remain‐
80 ing "no data" cells.
81 Figure: Result of patching two raster maps using the -z flag to treat
83 zeros as NULLs
84 Relation to SQL COALESCE() function
86 The module is corresponds to the SQL COALESCE() function. This func‐
87 tion takes two or more arguments and returns a copy of its first
88 non-NULL argument. If all arguments are NULL, the function returns
89 NULL.
90 The r.patch module iterates over all cells and for each cell of the
92 output raster map uses the first corresponding non-NULL cell in the
93 series of the input raster maps.
94 Example of filling areas
96 Below, the raster map layer on the far left is patched with the middle
97 (patching) raster map layer, to produce the composite raster map layer
98 on the right. The example assumes zero values to be treated as NULLs
99 (-z flag).
100 1 1 1 0 2 2 0 0 0 0 1 1 0 0 0 0 1 1 1 1 2 2 0 0
101 1 1 0 2 2 2 0 0 0 0 1 1 0 0 0 0 1 1 1 2 2 2 0 0
102 3 3 3 3 2 2 0 0 0 0 0 0 0 0 0 0 3 3 3 3 2 2 0 0
103 3 3 3 3 0 0 0 0 4 4 4 4 4 4 4 4 3 3 3 3 4 4 4 4
104 3 3 3 0 0 0 0 0 4 4 4 4 4 4 4 4 3 3 3 4 4 4 4 4
105 0 0 0 0 0 0 0 0 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4
106 Switching the patched and the patching raster map layers produces the
107 following results:
108 0 0 1 1 0 0 0 0 1 1 1 0 2 2 0 0 1 1 1 1 2 2 0 0
109 0 0 1 1 0 0 0 0 1 1 0 2 2 2 0 0 1 1 1 1 2 2 0 0
110 0 0 0 0 0 0 0 0 3 3 3 3 2 2 0 0 3 3 3 3 2 2 0 0
111 4 4 4 4 4 4 4 4 3 3 3 3 0 0 0 0 4 4 4 4 4 4 4 4
112 4 4 4 4 4 4 4 4 3 3 3 0 0 0 0 0 4 4 4 4 4 4 4 4
113 4 4 4 4 4 4 4 4 0 0 0 0 0 0 0 0 4 4 4 4 4 4 4 4
114
116 Frequently, this program is used to patch together adjacent map layers
117 which have been digitized separately. The program v.mkgrid can be used
118 to make adjacent maps align neatly.
119 The user should check the current geographic region settings before
121 running r.patch, to ensure that the region boundaries encompass all of
122 the data desired to be included in the composite map and to ensure that
123 the region resolution is the resolution of the desired data. To set the
124 geographic region settings to one or several raster maps, the g.region
125 program can be used:
126 g.region raster=map1[,map2[,...]]
127 Use of r.patch is generally followed by use of the GRASS programs
129 g.remove and g.rename; g.remove is used to remove the original
130 (un-patched) raster map layers, while g.rename is used to then assign
131 to the newly-created composite (patched) raster map layer the name of
132 the original raster map layer.
133 r.patch reads the existing category label files and color tables from
135 the input maps and creates these files for the patched, composite out‐
136 put map. This can be quite time consuming for certain maps, especially
137 if there are many different category values across the patched maps.
138 The -s flag allows disabling the reading and creation of these support
139 files, meaning that the output map will have no category labels and no
140 explicit color table.
141 Number of raster maps to be processed is given by the limit of the
143 operating system. For example, both the hard and soft limits are typi‐
144 cally 1024. The soft limit can be changed with e.g. ulimit -n 1500
145 (UNIX-based operating systems) but not higher than the hard limit. If
146 it is too low, you can as superuser add an entry in
147 /etc/security/limits.conf
148 # <domain> <type> <item> <value>
149 your_username hard nofile 1500
150 This would raise the hard limit to 1500 file. Be warned that more files
151 open need more RAM. See also the Wiki page Hints for large raster data
152 processing.
153 Operating systems usually limit the length of the command line which
155 limits the number of input raster maps user can pass to the module
156 using the option input. In that case, r.series can be used instead of
157 r.patch.
158
160 Example with three maps
161 The input are three maps called roads, water and forest. Primarily, we
162 want to use the values from roads, then from water and if no other val‐
163 ues are available we want to use forest. First we set the computation
164 region assuming that the all three maps fully overlap and have the same
165 resolution (so we can safely use the just the one without further modi‐
166 fications of the region). Then we perform the patching.
167 g.region raster=roads
168 r.patch input=roads,water,forest output=result
169 Map mosaic example using Bash syntax
171 Create a list of maps matching a pattern, extend the region to include
172 them all, and patch them together to create a mosaic. Overlapping maps
173 will be used in the order listed.
174 MAPS=`g.list type=raster separator=comma pat="map_*"`
175 g.region raster=$MAPS -p
176 r.patch input=$MAPS output=maps_mosaic
177
179 g.region, g.remove, g.rename, r.mapcalc, r.support, r.series, v.mkgrid
180 Hints for large raster data processing
182
184 Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
185 -z flag and performance improvement by Huidae Cho
186 Last changed: $Date: 2018-07-08 20:37:14 +0200 (Sun, 08 Jul 2018) $
188
190 Available at: r.patch source code (history)
191 Main index | Raster index | Topics index | Keywords index | Graphical
193 index | Full index
194 © 2003-2019 GRASS Development Team, GRASS GIS 7.4.4 Reference Manual
196GRASS 7.4.4 r.patch(1)