<h2>DESCRIPTION</h2>

<em>v.overlay</em> allows the user to overlay two vector maps. Features
in <b>ainput</b> can be lines or areas and are cut with areas in
<b>binput</b>. Simple <i>clipping</i> can be performed with the <b>and</b>
operator.
<p>
If areas in <b>ainput</b> are overlaid with areas in <b>binput</b>,
it is sometimes necessary to snap areas of <b>binput</b> to those of
<b>ainput</b>, otherwise areas can go missing or many sliver areas
can be created. Snapping is enabled by default and can be disabled by
setting the <b>snap</b> option to a negative value. Recommended values
are between 0.00000001 and 0.0001. Using larger values for snapping can
have undesired side-effects, but may sometimes be necessary to get a
clean output (see example below). In general, it is recommended to start
with a small snapping threshold, gradually increasing the threshold until
the result is reasonably clean. Snapping modifies only boundaries in
binput, which are snapped to boundaries in ainput. Boundaries in <b>ainput</b>
are not modified.
<!-- This is outdated
There are 3 links attached to features in output map,
<ul>
<li><b>field 1</b>: link to the new table, new table has 3 columns
    <ul>
        <li><b>cat</b> - key column linking rows to features
        <li><b>cata</b> - category of <i>afield</i> from <i>ainput</i>
        <li><b>catb</b> - category of <i>bfield</i> from <i>binput</i>
    </ul>
<li><b>field 2</b>: category of <i>afield</i> from <i>ainput</i>
<li><b>field 3</b>: category of <i>bfield</i> from <i>binput</i>
</ul>
-->

<h2>NOTES</h2>

Currently only areas in <b>ainput</b> are supported for the operators
<em>or</em> and <em>xor</em>! See also <em><a href="v.select.html">v.select</a></em>.

The operator defines what kind of operation will be done. Features are
written to output, if the result of an operation <b>ainput</b> operator <b>binput</b>
is true.

<p>
If the <i>first</i> number of the <b>olayer</b> option is greater than 0, then the
resulting output map has a merged attribute table in the given layer
number. The original column names have a prefix (<em>a_</em> and
<em>b_</em>) corresponding to <b>ainput</b> and <b>binput</b> map.
<p>
If the <i>second</i> number of the <b>olayer</b> option is greater than 0, then the
categories of <b>ainput</b> in layer <b>alayer</b> are transferred to
the output layer with the second number.
<p>
If the <i>third</i> number of the <b>olayer</b> option is greater than 0, then the
categories of <b>binput</b> in layer <em>blayer</em> are transferred to
the output layer with the third number.

<p>
If <b>atype</b>=auto is given than <em>v.overlay</em> determines
feature type for <b>ainput</b> from the first found feature.

<!-- This is outdated
<p><div class="code"><pre>
v.db.connect map=outputmap table=ainput.dbf field=2
v.db.connect map=outputmap table=binput.dbf field=3

</pre></div>

<p><b>Attention:</b> Removing the output map will also delete all tables linked to
it! Therefore it is advisable to copy tables from ainput and binput first and
connect the copied tables to the output map.-->

<h2>EXAMPLES</h2>

Preparation of example data (North Carolina sample dataset):

<div class="code"><pre>
# Create an empty box for overlaying to ZIP code vector map
v.mkgrid map=box grid=1,1 position=coor coordinates=584037,201970 box=50000,50000

# set region to ZIP codes and box vector maps
g.region vector=zipcodes_wake,box -p res=100 -a
# enlarge region a bit for "white border" around map in monitor
g.region n=n+1000 s=s-1000 w=w-1000 e=e+1000 -p
d.mon wx0
</pre></div>

<h3>AND operator</h3>

Clipping example (no attribute table is generated here):

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=box fill_color=85:130:176
v.overlay -t ainput=box binput=zipcodes_wake operator=and output=v_overlay_AND
d.vect map=v_overlay_AND
</pre></div>

<center>
<img src="v_overlay_op_and.png" alt="v.overlay with AND operator"><br>
<i>Figure: v.overlay with AND operator (selected polygons in yellow color)</i>
</center>

<h3>OR operator</h3>

Union example of areas:

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=box fill_color=85:130:176
v.overlay -t ainput=box binput=zipcodes_wake operator=or output=v_overlay_OR
d.vect map=v_overlay_OR
</pre></div>

<center>
<img src="v_overlay_op_or.png" alt="v.overlay with OR operator"><br>
<i>Figure: v.overlay with OR operator (selected polygons in yellow color)</i>
</center>

<h3>XOR operator</h3>

Symmetrical difference example:

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=box fill_color=85:130:176
v.overlay -t ainput=box binput=zipcodes_wake operator=xor output=v_overlay_XOR
d.vect map=v_overlay_XOR
</pre></div>

<center>
<img src="v_overlay_op_xor.png" alt="v.overlay with XOR operator"><br>
<i>Figure: v.overlay with XOR operator (selected polygons in yellow color)</i>
</center>

<h3>NOT operator</h3>

Difference example:

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=box fill_color=85:130:176
v.overlay -t ainput=box binput=zipcodes_wake operator=not output=v_overlay_NOT
d.vect map=v_overlay_NOT
</pre></div>

<center>
<img src="v_overlay_op_not.png" alt="v.overlay with NOT operator"><br>
<i>Figure: v.overlay with NOT operator (selected polygon in yellow color)</i>
</center>

<h3>Overlay operations: AND, OR, NOT, XOR</h3>

ZIP code examples, based on North Carolina sample dataset:

<div class="code"><pre>
# creation of simple dataset
v.extract input=zipcodes_wake output=poly1 where="cat = 42"
v.extract input=urbanarea output=poly2 where="cat = 55"

v.overlay ainput=poly1 binput=poly2 operator=and output=poly_1_2_and
v.overlay ainput=poly1 binput=poly2 operator=or  output=poly_1_2_or
v.overlay ainput=poly1 binput=poly2 operator=not output=poly_1_2_not
v.overlay ainput=poly1 binput=poly2 operator=xor output=poly_1_2_xor
</pre></div>

<center>
<img src="v_overlay_poly_1_2.png" alt="GRASS v.overlay: input polygons (1 and 2)" border="0">
<br>
<i>Figure: v.overlay operations: original input polygons</i>
</center>
<p>
<center>
<img src="v_overlay_poly_1_2_a_o_n_x.png" alt="GRASS v.overlay results: AND, OR, NOT, XOR operations" border="0">
<br>
<i>Figure: v.overlay results of AND, OR, NOT, XOR operations</i>
</center>

<h3>Polygons overlaid with polygons</h3>
<div class="code"><pre>
v.overlay ainput=lake binput=province output=lakeXprovince operator=or
</pre></div>

Polygon union of urban area and Census 2000 areas (North Carolina dataset):

<div class="code"><pre>
# input maps
d.vect urbanarea
d.vect census_wake2000

# union
v.overlay ain=census_wake2000 bin=urbanarea out=urban_census2000 operator=or

# show result, graphically zooming a subset
g.region n=230400 s=223800 w=655800 e=662400
d.erase
d.vect urban_census2000

# show merged attribute table
v.db.select urban_census2000 where="cat=108" -v
cat|108
a_cat|98
a_AREA|231001264
a_PERIMETE|67804.305
a_TRACT_|98
a_TRACT_ID|98
a_RINGS_OK|1
a_RINGS_NO|0
a_ID|98
a_FIPSSTCO|37183
a_TRT2000|054108
a_STFID|37183054108
a_TRACTID|541.08
a_TRACT|541.08
b_cat|55
b_OBJECTID|55
b_UA|73261
b_NAME|Raleigh
b_UA_TYPE|UA
</pre></div>

<center>
<img src="v_overlay_urbanarea.png" alt="GRASS v.overlay: polygon to polygon union (input 1)" border="1">
<img src="v_overlay_census_wake2000.png" alt="GRASS v.overlay: polygon to polygon union (input 2)" border="1">
<img src="v_overlay_urban_census2000.png" alt="GRASS v.overlay: polygon to polygon union (result)" border="1">
<br>
<i>Figure: v.overlay: Polygon union (right) of urban area (left) and Census 2000 (middle) areas (North Carolina dataset)</i>
</center>

<p>
As can be seen by the resulting large number of centroids on boundaries,
the urban areas do not match exactly the Census 2000 areas. In this case
a clean result can be obtained by snapping with a threshold of 0.1 m.

<h3>Lines overlaid with polygons</h3>

Using the North Carolina sample dataset, we clip the roads map to the area
of city of Raleigh, preserving road attributes in layer 1:
<div class="code"><pre>
g.region vector=zipcodes_wake

# extract Raleigh city:
v.extract in=zipcodes_wake out=raleigh where="ZIPNAME = 'RALEIGH'"

# clip road network to city polygon:
v.overlay ainput=roadsmajor atype=line binput=raleigh out=roadsmajor_raleigh operator=and olayer=0,1,0
</pre></div>

<center>
<img src="v_overlay_area_lines.png" alt="GRASS v.overlay: Line to polygon clipping"><br>
<table border="0" width="590">
<tr><td><center>
<i>Figure: v.overlay: Line to polygon clipping</i>
</center></td></tr>
</table>
</center>

<h2>SEE ALSO</h2>

<em>
<a href="v.clip.html">v.clip</a>,
<a href="v.db.connect.html">v.db.connect</a>,
<a href="v.select.html">v.select</a>,
<a href="g.copy.html">g.copy</a>
</em>

<h2>AUTHORS</h2>

Radim Blazek, ITC-Irst, Trento, Italy<br>
Markus Metz<br>
Speedup for large, complex input areas sponsored by <a href="https://www.mundialis.de">mundialis</a>