r.patch(1grass)

🌸 r.patch — the GRASS User's Manual glow-up 💖

okay bestie, listen. you know how you have like seven half-finished playlists and you wanna smash them into one perfect playlist with no dead air? that's r.patch. it's a GRASS module (this is the r.patch(1grass) page, iykyk) and it literally builds you a brand new composite raster map. no cap. ✨

✨ 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, parallel

👑 SYNOPSIS 👑

r.patch
r.patch --help
r.patch [-zs] input=name[,name,...] output=name  [nprocs=integer]
[memory=memory in MB]   [--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
• nprocs=integer — Number of threads for parallel computing. 0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs. Default: 0
• memory=memory in MB — Maximum memory to be used (in MB). Cache size for raster rows. Default: 300

---

💅 DESCRIPTION 💅

so the GRASS program r.patch lets you build a brand new raster map that's the size and resolution of the current region, by assigning known data values from input raster maps to the cells in this region. it's giving "fill in the blanks" but the blanks are geographic. 🗺️✨

when your input raster maps overlap, this is done by filling in "no data" cells — those that don't yet contain data, contain NULL data, or, optionally, contain 0 data — with the data from the first input map. once that's done, the remaining holes get filled by the next input map, and so on. and when your input raster maps are adjacent instead? the output map contains the map mosaic. iconic behavior, honestly. 🧩

so basically 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 respected. 👀

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, ...) get used, in order, to supply data values for the remaining "no data" cells (or cells with value 0 when the -z flag is on). 💫

in other words: the first raster map is used first, and if it had some "no data" cells, then the second raster map fills those, then the third, and so on. so the formal command line syntax can also be 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. slay. 💖

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 🧚

this module corresponds to the SQL COALESCE() function. that function takes two or more arguments and returns a copy of its first non-NULL argument. if all arguments are NULL, the function returns NULL. (very demure, very mindful.)

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 series 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 📝

a LOT of the time, people use this program to patch together adjacent map layers that have been digitized separately. the program v.mkgrid can be used to make adjacent maps align neatly. (grid alignment is self-care. 🧘)

bestie, please 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.remove 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 output map. lowkey this can be quite time consuming for certain maps, especially if there are many different category values across the patched maps. the -s flag lets you disable the reading and creation of these support files, meaning that the output map will have no category labels and no explicit color table. 🙈

the number of raster maps to be processed is given by the limit of the operating system. for example, both the hard and soft limits are typically 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 using the option input. in that case, r.series can be used instead of r.patch.

⚡ PERFORMANCE ⚡

by specifying the number of parallel processes with the nprocs option, r.patch can run significantly faster, see benchmarks below.

Figure: Benchmark on the left shows execution time for different number of cells, benchmark on the right shows execution time for different memory size for 5000x5000 raster. See benchmark scripts in source code. (Intel Core i9-10940X CPU @ 3.30GHz x 28)

to reduce the memory requirements to minimum, set option memory to zero. to take advantage of the parallelization, GRASS needs to compiled with OpenMP enabled. 🔥

---

🧁 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 values 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 modifications 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

🫶 AUTHORS 🫶

Michael Shapiro, U.S. Army Construction Engineering Research Laboratory Huidae Cho (-z flag and performance improvement) Aaron Saw Min Sern (OpenMP support).

💜 SOURCE CODE 💜

Available at: r.patch source code (history)

Latest change: Sunday Jul 27 05:53:30 2025 in commit: da409580ef15011f3bac379c76d41101c9e36347

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

---

okay that's the whole page, bestie!! 💖 go forth and patch your rasters. mwah. 🎀✨

GRASS 8.5.0 — r.patch(1grass) 🦋 that's a wrap, periodt.