<h2>DESCRIPTION</h2>

<em>v.select</em> allows the user to select features from a vector
map by features from another one.

<p>Supported operators (without GEOS; using GRASS' own algorithm):
<ul>
  <li><b>overlap</b> - features partially or completely overlap (GEOS equivalent: intersects)</li>
</ul>

Supported operators (internally using
<a href="https://trac.osgeo.org/geos/">GEOS</a> - Geometry Engine, Open Source):
<ul>
  <li><b>equals</b> - features are spatially equals</li>
  <li><b>disjoint</b> - features do not spatially intersect</li>
  <li><b>intersects</b> - features spatially intersect (equivalent to native 'overlap')</li>
  <li><b>touches</b> - features spatially touches</li>
  <li><b>crosses</b> - features spatially crosses</li>
  <li><b>within</b> - feature A is completely inside feature B</li>
  <li><b>contains</b> - feature B is completely inside feature A</li>
  <li><b>overlaps</b> - features spatially overlap</li>
  <li><b>relate</b> - feature A is spatially related to feature B</li>
</ul>

<h2>NOTES</h2>

Only features with category numbers will be considered. If required
the <em><a href="v.category.html">v.category</a></em> module can be
used to add them. Typically boundaries do not need to be given a
category number, as an area's attributes are inherited from the
centroid. Typically points, lines, and centroids will always want to
have a cat number. E.g. take a road which separates two farms. It is
ambiguous as to which farm an attribute that is attached to the road
belongs to. The boundary only needs a cat number if it will hold its
own attributes, such as road name or pavement form. A centroid in each
paddock holds the information with respect to ownership, area, etc.

<h2>EXAMPLES</h2>

Preparation of example data (North Carolina sample dataset):

<div class="code"><pre>
# Create an grid for overlaying to ZIP code vector map
v.mkgrid map=boxgrid grid=10,10 position=coor \
         coordinates=583600,201500 box=5000,5000

# set region to ZIP codes and boxgrid vector maps
g.region vector=zipcodes_wake,boxgrid -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>OVERLAP: features partially or completely overlap (using GRASS)</h3>

Select grid boxes (North Carolina sample dataset):

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=boxgrid fill_color=85:130:176
v.select ainput=boxgrid binput=zipcodes_wake output=v_select_OVERLAP operator=overlap
d.vect map=v_select_OVERLAP
d.vect map=zipcodes_wake type=boundary color=255:255:50
</pre></div>

<center>
<img src="v_select_op_overlap.png" alt="v.select with OVERLAP operator"><br>
v.select with OVERLAP operator: selected grid boxes shown in yellow (using GRASS method)
</center>

<h3>OVERLAPS features spatially overlap (using GEOS)</h3>

Select grid boxes (North Carolina sample dataset):

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=boxgrid fill_color=85:130:176
v.select ainput=boxgrid binput=zipcodes_wake output=v_select_OVERLAPS operator=overlaps
d.vect map=v_select_OVERLAPS
d.vect map=zipcodes_wake type=boundary color=255:255:50
</pre></div>
<center>
<img src="v_select_op_overlaps.png" alt="v.select with OVERLAPS operator"><br>
v.select with OVERLAPS operator: selected grid boxes shown in yellow (using GEOS method)
</center>

<h3>DISJOINT: features do not spatially intersect (using GEOS)</h3>

Select grid boxes (North Carolina sample dataset):

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=boxgrid fill_color=85:130:176
v.select ainput=boxgrid binput=zipcodes_wake output=v_select_DISJOINT operator=disjoint
d.vect map=v_select_DISJOINT
d.vect map=zipcodes_wake type=boundary color=255:255:50
</pre></div>

<center>
<img src="v_select_op_disjoint.png" alt="v.select with DISJOINT operator"><br>
v.select with DISJOINT operator: selected grid boxes shown in yellow
</center>

<h3>EQUALS: features are spatially equals (using GEOS)</h3>

Select zipcode polygon (North Carolina sample dataset):

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
v.extract input=zipcodes_wake where=ZIPCODE_ID=35 output=zipcodeID35
v.select ainput=zipcodes_wake binput=zipcodeID35 output=v_select_EQUALS operator=equals
d.vect map=v_select_EQUALS
d.vect map=zipcodes_wake type=boundary color=255:255:50
</pre></div>

<center>
<img src="v_select_op_equals.png" alt="v.select with EQUALS operator"><br>
v.select with EQUALS operator: selected grid boxes shown in yellow
</center>

<h3>INTERSECTS: features spatially intersect (using GEOS)</h3>

Select zipcode polygons (North Carolina sample dataset):

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=boxgrid fill_color=85:130:176
v.select ainput=zipcodes_wake binput=boxgrid output=v_select_INTERSECTS operator=intersects
d.vect map=v_select_INTERSECTS
d.vect map=boxgrid type=boundary color=255:255:50
</pre></div>

<center>
<img src="v_select_op_intersects.png" alt="v.select with INTERSECTS operator"><br>
v.select with INTERSECTS operator: selected grid boxes shown in yellow
</center>

<h3>TOUCHES: features spatially touches (using GEOS)</h3>

Select polygons (North Carolina sample dataset):

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=zipcodeID35 fill_color=85:130:176
v.select ainput=zipcodes_wake binput=zipcodeID35 output=v_select_TOUCHES operator=touches
d.vect map=v_select_TOUCHES
d.vect map=zipcodes_wake type=boundary color=255:255:50
</pre></div>

<center>
<img src="v_select_op_touches.png" alt="v.select with TOUCHES operator"><br>
v.select with TOUCHES operator: selected polygons shown in yellow (blue: input polygon)
</center>

<h3>CROSSES: features spatially crosses (using GEOS)</h3>

Select zipcode polygons by lines (North Carolina sample dataset):

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=busroute1 color=200:27:27 width=3
v.select ainput=zipcodes_wake binput=busroute1 output=v_select_CROSSES operator=crosses
d.vect map=v_select_CROSSES
d.vect map=zipcodes_wake type=boundary color=255:255:50
d.vect map=busroute1 color=200:27:27 width=3
</pre></div>

<center>
<img src="v_select_op_crosses.png" alt="v.select with CROSSES operator"><br>
v.select with CROSSES operator: selected polygons shown in yellow (red: input lines)
</center>

<h3>WITHIN feature A is completely inside feature B (using GEOS)</h3>

Select zipcode polygons (North Carolina sample dataset):

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=boundary_county fill_color=85:130:176
v.select ainput=zipcodes_wake binput=boundary_county output=v_select_WITHIN operator=within
d.vect map=v_select_WITHIN
</pre></div>

<center>
<img src="v_select_op_within.png" alt="v.select with WITHIN operator"><br>
v.select with WITHIN operator: selected polygons shown in yellow (blue: input polygons)
</center>

<h3>CONTAINS feature B is completely inside feature A (using GEOS)</h3>

Select zipcode polygon (North Carolina sample dataset):

<h4>CONTAINS with polygons</h4>

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=zipcodeID35 fill_color=85:130:176
v.select ainput=zipcodes_wake binput=zipcodeID35 \
         output=v_select_CONTAINS_pol operator=contains
d.vect map=v_select_CONTAINS
</pre></div>

<center>
<img src="v_select_op_contains_pol.png" alt="v.select with CONTAINS operator"><br>
v.select with CONTAINS operator: selected polygon shown in yellow (blue: input polygon, not visible)
</center>

<h4>CONTAINS with points</h4>

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=hospitals fill_color=195:31:31 icon=basic/cross3 size=10
v.select ainput=zipcodes_wake binput=hospitals \
         output=v_select_CONTAINS_pnts operator=contains
d.vect map=v_select_CONTAINS_pnts
d.vect map=hospitals fill_color=195:31:31 icon=basic/cross3 size=10
</pre></div>

<center>
<img src="v_select_op_contains_pnts.png" alt="v.select with CONTAINS operator"><br>
v.select with CONTAINS operator: selected polygons shown in yellow (red: input points)
</center>

<h3>RELATE feature A is spatially related to feature B (using GEOS)</h3>

This operator additionally requires the <b>relate</b> parameter (in other
GIS called 'ST_Relate').

This operator allows calculating the
<a href="https://en.wikipedia.org/wiki/DE-9IM">Dimensionally Extended nine-Intersection Model (DE-9IM)</a>.

In the following one example: Select polygon with 'TOUCHES' operator
(North Carolina sample dataset):

<div class="code"><pre>
d.vect map=zipcodes_wake fill_color=0:128:0
d.vect map=zipcodeID35 fill_color=85:130:176
v.select ainput=zipcodeID35 binput=zipcodes_wake \
         output=v_select_TOUCHES_relate operator=relate relate='T********'
d.vect map=v_select_TOUCHES
</pre></div>

The result of <code>relate='T********'</code> is the same as seen
above in the example 'TOUCHES'.

See the <a href="https://en.wikipedia.org/wiki/DE-9IM">DE-9IM</a> page
for related operators and their definition.

<h3>Extraction of points falling into a polygon</h3>

Extract fire stations (points) falling into urban area (polygon) - North Carolina
data set (point in polygon test):

<div class="code"><pre>
v.select ainput=firestations binput=urbanarea output=urban_firestations \
         operator=overlap
</pre></div>

<h3>Extraction of lines overlapping with a polygon</h3>

Extract railroad lines from zip code map overlapping with the urban area
(line in polygon test):

<div class="code"><pre>
v.select ainput=railroads binput=urbanarea \
         output=railroads_in_urbanarea operator=overlap
</pre></div>

<h3>Extraction of areas overlapping with a line</h3>

Extract those areas from zip code map which overlap with railroads
(polygon on line test):

<div class="code"><pre>
# first add a tiny buffer around railroad lines:
v.buffer input=railroads output=railroads_buf20m \
  distance=20

v.select ainput=zipcodes_wake binput=railroads_buf20m \
  output=zipcodes_wake_railroads operator=overlap
</pre></div>

<!-- 2015: still an issue?
<h2>TODO</h2>


Processing areas with GEOS is currently incredibly slow. Significant
speed-up is desired.
-->

<h2>SEE ALSO</h2>

<em>
<a href="v.category.html">v.category</a>,
<a href="v.clip.html">v.clip</a>,
<a href="v.overlay.html">v.overlay</a>,
<a href="v.extract.html">v.extract</a>
</em>

<p>
<a href="sql.html">GRASS SQL interface</a><br>
<a href="https://trac.osgeo.org/geos/">GEOS</a> - Geometry Engine, Open Source

<h2>AUTHORS</h2>

Radim Blazek<br>
GEOS support by Martin Landa, Czech Technical University in Prague, Czech Republic<br>
ZIP code examples by Carol X. Garzon-Lopez, Trento, Italy