r.patch(1grass) GRASS GIS User's Manual r.patch(1grass)
NAME
r.patch - Creates a composite raster map layer by using known category
values from one (or more) map layer(s) to fill in areas of "no data" in
another map layer.
KEYWORDS
raster, geometry, mosaicking, merge, patching, aggregation, series
SYNOPSIS
r.patch
r.patch --help
r.patch [-zs] input=name[,name,...] output=name [--overwrite]
[--help] [--verbose] [--quiet] [--ui]
Flags:
-z
Use zero (0) for transparency instead of NULL
-s
Do not create color and category files
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog
Parameters:
input=name[,name,...] [required]
Name of raster maps to be patched together
output=name [required]
Name for resultant raster map
DESCRIPTION
The GRASS program r.patch allows the user to build a new raster map the
size and resolution of the current region by assigning known data val-
ues from input raster maps to the cells in this region.
In case of overlapping input raster maps this is done by filling in "no
data" cells, those that do not yet contain data, contain NULL data, or,
optionally contain 0 data, with the data from the first input map.
Once this is done the remaining holes are filled in by the next input
map, and so on.
In case of adjacent input raster maps the output map contains the map
mosaic.
Hence this command is useful for
• making a composite raster map layer from two or more adjacent
map layers,
• for filling in "holes" in a raster map layer’s data (e.g., in
digital elevation data), or
• for updating an older map layer with more recent data.
The current geographic region definition and mask settings are re-
spected.
Figure: Result of patching of two raster maps containing NULLs using
the default settings.
Stacking order
The first name listed in the string input=name,name,name,... is the
name of the first map whose data values will be used to fill in cells
in the current region. Then, the second through the last input maps
(..., name, name, ...) will be used, in order, to supply data values
for the remaining "no data" cells (or cells with value 0 with -z flag).
In other words, the first raster map is used first and if it had some
"no data" cells, then second raster map is used for these cells, then
the third and so on. So the formal command line syntax can be also
written as input=primary,secondary,tertiary,... For two raster maps,
the first one can be viewed as the primary one or the default one and
the second one as the secondary one or a fallback.
Figure: Result of patching of two raster maps using the -z flag to
treat zeros as NULLs. Note the value 1 being preserved from the first
raster while the value 6 is taken from the second raster instead of the
value 0 from the first raster because zeros are replaced with the -z
flag active.
Relation to SQL COALESCE() function
The module is corresponds to the SQL COALESCE() function. This func-
tion takes two or more arguments and returns a copy of its first
non-NULL argument. If all arguments are NULL, the function returns
NULL.
The r.patch module iterates over all cells and for each cell of the
output raster map uses the first corresponding non-NULL cell in the se-
ries of the input raster maps.
Example of filling areas
Below, the raster map layer on the far left is patched with the middle
(patching) raster map layer, to produce the composite raster map layer
on the right. The example assumes zero values to be treated as NULLs
(-z flag).
1 1 1 0 2 2 0 0 0 0 1 1 0 0 0 0 1 1 1 1 2 2 0 0
1 1 0 2 2 2 0 0 0 0 1 1 0 0 0 0 1 1 1 2 2 2 0 0
3 3 3 3 2 2 0 0 0 0 0 0 0 0 0 0 3 3 3 3 2 2 0 0
3 3 3 3 0 0 0 0 4 4 4 4 4 4 4 4 3 3 3 3 4 4 4 4
3 3 3 0 0 0 0 0 4 4 4 4 4 4 4 4 3 3 3 4 4 4 4 4
0 0 0 0 0 0 0 0 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4
Switching the patched and the patching raster map layers produces the
following results:
0 0 1 1 0 0 0 0 1 1 1 0 2 2 0 0 1 1 1 1 2 2 0 0
0 0 1 1 0 0 0 0 1 1 0 2 2 2 0 0 1 1 1 1 2 2 0 0
0 0 0 0 0 0 0 0 3 3 3 3 2 2 0 0 3 3 3 3 2 2 0 0
4 4 4 4 4 4 4 4 3 3 3 3 0 0 0 0 4 4 4 4 4 4 4 4
4 4 4 4 4 4 4 4 3 3 3 0 0 0 0 0 4 4 4 4 4 4 4 4
4 4 4 4 4 4 4 4 0 0 0 0 0 0 0 0 4 4 4 4 4 4 4 4
NOTES
Frequently, this program is used to patch together adjacent map layers
which have been digitized separately. The program v.mkgrid can be used
to make adjacent maps align neatly.
The user should check the current geographic region settings before
running r.patch, to ensure that the region boundaries encompass all of
the data desired to be included in the composite map and to ensure that
the region resolution is the resolution of the desired data. To set the
geographic region settings to one or several raster maps, the g.region
program can be used:
g.region raster=map1[,map2[,...]]
Use of r.patch is generally followed by use of the GRASS programs g.re-
move and g.rename; g.remove is used to remove the original (un-patched)
raster map layers, while g.rename is used to then assign to the
newly-created composite (patched) raster map layer the name of the
original raster map layer.
r.patch reads the existing category label files and color tables from
the input maps and creates these files for the patched, composite out-
put map. This can be quite time consuming for certain maps, especially
if there are many different category values across the patched maps.
The -s flag allows disabling the reading and creation of these support
files, meaning that the output map will have no category labels and no
explicit color table.
Number of raster maps to be processed is given by the limit of the op-
erating system. For example, both the hard and soft limits are typi-
cally 1024. The soft limit can be changed with e.g. ulimit -n 1500
(UNIX-based operating systems) but not higher than the hard limit. If
it is too low, you can as superuser add an entry in
/etc/security/limits.conf
# <domain> <type> <item> <value>
your_username hard nofile 1500
This would raise the hard limit to 1500 file. Be warned that more files
open need more RAM. See also the Wiki page Hints for large raster data
processing.
Operating systems usually limit the length of the command line which
limits the number of input raster maps user can pass to the module us-
ing the option input. In that case, r.series can be used instead of
r.patch.
EXAMPLES
Example with three maps
The input are three maps called roads, water and forest. Primarily, we
want to use the values from roads, then from water and if no other val-
ues are available we want to use forest. First we set the computation
region assuming that the all three maps fully overlap and have the same
resolution (so we can safely use the just the one without further modi-
fications of the region). Then we perform the patching.
g.region raster=roads
r.patch input=roads,water,forest output=result
Map mosaic example using Bash syntax
Create a list of maps matching a pattern, extend the region to include
them all, and patch them together to create a mosaic. Overlapping maps
will be used in the order listed.
MAPS=`g.list type=raster separator=comma pat="map_*"`
g.region raster=$MAPS -p
r.patch input=$MAPS output=maps_mosaic
SEE ALSO
g.region, g.remove, g.rename, r.mapcalc, r.support, r.series, v.mkgrid
Hints for large raster data processing
AUTHOR
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
-z flag and performance improvement by Huidae Cho
SOURCE CODE
Available at: r.patch source code (history)
Accessed: unknown
Main index | Raster index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 r.patch(1grass)
Generated by dwww version 1.14 on Sun Dec 29 18:57:27 CET 2024.