v.select manual: full set of NC example added (contributed by Carol X Garzon-Lopez)

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@65898 15284696-431f-4ddb-bdfa-cd5b030d7da7

vector/v.select/v.select.html

@@ -3,12 +3,13 @@
 <em>v.select</em> allows the user to select features from a vector 
 map by features from another one.
 
-<p>Supported operators (without GEOS):
+<p>Supported operators (without GEOS; using GRASS' own algorithm):
 <ul>
   <li><b>overlap</b> - features partially or completely overlap
 </ul>
 
-Supported operators (with GEOS):
+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>
@@ -37,6 +38,227 @@ 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=50:50: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 grey
+</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=50:50: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 grey
+</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=50:50: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 grey
+</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=50:50: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 grey
+</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=50:50:50
+</pre></div>
+
+<center>
+<img src="v_select_op_intersects.png" alt="v.select with OVERLAP operator"><br>
+v.select with OVERLAP operator: selected grid boxes shown in grey
+</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=50:50: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 grey (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=50:50: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 grey (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 grey (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 grey (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 grey (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 to calculate 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 <tt>relate='T********'</tt> 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):
 
@@ -45,6 +267,8 @@ 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):
 
@@ -53,6 +277,8 @@ 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):
 
@@ -65,10 +291,12 @@ 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>
 
@@ -79,13 +307,16 @@ speed-up is desired.
 </em>
 
 <p>
-<a href="sql.html">GRASS SQL interface</a>
+<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
+GEOS support by Martin Landa, Czech Technical University in Prague, Czech Republic<br>
+
+ZIP code examples by Carol X. Garzon-Lopez, Trento, Italy
 
 <p>
 <i>Last changed: $Date$</i>