Geografic-Information-System/raster/r.patch/r.patch.html

<h2>DESCRIPTION</h2>

The GRASS program <em>r.patch</em> allows the user to build a new
raster map the size and resolution of the current region by assigning
known data values from input raster maps to the cells in this region.
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.
This program
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.
<p>The first <em>name</em> listed in the string
<b>input=</b><em>name</em>,<em>name</em>,<em>name</em>, ... is the name of
the first map whose data values will be used to fill in "no data" cells
in the current region. The second through last input <em>name</em>
maps will be used, in order, to supply data values for for the remaining
"no data" cells.

<h3>Example of filling areas</h3>

<!-- this example is also used in the tests -->

Below, the raster map layer on the far left is <b>patched</b>
with the middle (<em>patching</em>) raster map layer,
to produce the <em>composite</em> raster map layer on the right.
The example assumes zero values to be treated as NULLs (<b>-z</b> flag).

<div class="code"><pre>
  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
</pre></div>

Switching the <em>patched</em> and the <em>patching</em> raster map layers 
produces the following results: 

<div class="code"><pre>
  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
</pre></div>


<h2>NOTES</h2>

Frequently, this program is used to patch together adjacent map layers which
have been digitized separately.  The program 
<em><a href="v.mkgrid.html">v.mkgrid</a></em> can be used to make adjacent
maps align neatly.

<p>The user should check the current geographic region settings before running 
<em>r.patch</em>, 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 <em>g.region</em>
program can be used:

<div class="code"><pre>
g.region raster=map1[,map2[,...]]
</pre></div>

<p>
Use of <em>r.patch</em> is generally followed by use of the GRASS programs 
<em><a href="g.remove.html">g.remove</a></em> and 
<em><a href="g.rename.html">g.rename</a></em>;
<em>g.remove</em> is used to remove the original (un-patched) raster map
layers, while <em>g.rename</em> is used to then assign to the newly-created
composite (patched) raster map layer the name of the original raster map
layer.

<p>
<em>r.patch</em> creates support files for the patched, composite output map. 

<p>
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. <tt>ulimit -n
1500</tt> (UNIX-based operating systems) but not higher than the hard
limit. If it is too low, you can as superuser add an entry in

<div class="code"><pre>
/etc/security/limits.conf
# &lt;domain&gt;      &lt;type&gt;  &lt;item&gt;         &lt;value&gt;
your_username  hard    nofile          1500
</pre></div>

This would raise the hard limit to 1500 file. Be warned that more
files open need more RAM. See also the Wiki page
<a href="http://grasswiki.osgeo.org/wiki/Large_raster_data_processing">Hints for large raster data processing</a>.


<h2>EXAMPLE</h2>

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.

<div class="code"><pre>
MAPS=`g.list type=raster sep=, pat="map_*"`
g.region raster=$MAPS
r.patch in=$MAPS out=mosaic
</pre></div>
<br>


<h2>SEE ALSO</h2>

<em>
<a href="g.region.html">g.region</a>,
<a href="g.remove.html">g.remove</a>,
<a href="g.rename.html">g.rename</a>,
<a href="r.mapcalc.html">r.mapcalc</a>,
<a href="r.support.html">r.support</a>,
<a href="v.mkgrid.html">v.mkgrid</a>
</em>
<p>
<a href="http://grasswiki.osgeo.org/wiki/Large_raster_data_processing">Hints for large raster data processing</a>

<h2>AUTHOR</h2>

Michael Shapiro, 
U.S. Army Construction Engineering Research Laboratory
<br>
-z flag and performance improvement by Huidae Cho

<p><i>Last changed: $Date$</i>