[GRASS-SVN] r29728 - grass/branches/releasebranch_6_3/vector/v.distance

[svn_grass at osgeo.org]

Author: epatton
Date: 2008-01-16 15:10:07 -0500 (Wed, 16 Jan 2008)
New Revision: 29728

Modified:
   grass/branches/releasebranch_6_3/vector/v.distance/description.html
Log:
General clarity and grammar improvements

Modified: grass/branches/releasebranch_6_3/vector/v.distance/description.html
===================================================================
--- grass/branches/releasebranch_6_3/vector/v.distance/description.html	2008-01-16 20:09:13 UTC (rev 29727)
+++ grass/branches/releasebranch_6_3/vector/v.distance/description.html	2008-01-16 20:10:07 UTC (rev 29728)
@@ -1,76 +1,101 @@
 <H2>DESCRIPTION</H2>
 
-<EM>v.distance</EM>
-finds features from one vector (from=) feature to another vector (to=) nearest feature.
-Various information about relation (distance, ...) may be uploaded to attribute
-table attached to first vector map or printed to 'stdout'.
-A new vector map may be created where lines connecting nearest points on features are written.
-<P>
+<EM>v.distance</EM> finds the nearest element in vector map
+(<em>to</em>) for elements in vector map (<em>from</em>). Various
+information about the vectors' relationships (distance, category, etc.) may be uploaded
+to the attribute table attached to the first vector map, or printed to
+'stdout'.  A new vector map may be created where lines connecting
+nearest points on features are written.
 
+<H2>NOTES</H2>
 
+If a nearest feature does not have a category, the attribute column is updated
+to <em>null</em>.  This is true also for areas, which means for example,
+that if a point is in an island (area WITHOUT category), <EM>v.distance</EM> 
+does not search for the nearest area WITH category; the island is identified 
+as the nearest and category updated to null.
+<p>
+The upload <em>column</em>(s) must already exist. Create one with <em>v.db.addcol</em>.
+<p>
+In lat-long locations <em>v.distance</em> gives distances (<em>dist</em>
+and <em>to_along</em>) in meters not in degrees calculated as geodesic
+distances on a sphere.
+
 <h2>EXAMPLES</H2>
 
-1) Find <B>nearest lines</B> in vector map <B>ln</B> for points from vector map
-<B>pnt</B> within the given threshold and write related line categories to
-column <B>linecat</B> in attribute table attached to vector map <B>pnt</B>:
-<br>
+<H3>Find nearest lines</H3>
+
+Find <EM>nearest lines</EM> in vector map <B>ln</B> for points from
+vector map <B>pnt</B> within the given threshold and write related
+line categories to column <B>linecat</B> in an attribute table attached
+to vector map <B>pnt</B>:
+
 <div class="code"><pre>
 v.distance from=pnt to=ln upload=cat column=linecat
 </pre></div>
 
-<p>
-2) For each point from vector map <B>pnt</B> find <B>nearest area</B> from map
-<B>ar</B> within the given threshold and write the related area categories
-to column <B>areacat</B> in attribute table attached to vector map
-<B>pnt</B>. In case a point falls into a polygon area, the distance is zero:
-<br>
+<H3>Find nearest area</H3>
+
+For each point from vector map <B>pnt</B>, find <EM>nearest area</EM>
+from map <B>ar</B> within the given threshold and write the related
+area categories to column <B>areacat</B> in an attribute table attached
+to vector map <B>pnt</B> (in the case that a point falls into a polygon area,
+the distance is zero):
+
 <div class="code"><pre>
 v.distance from=pnt to=ar upload=cat column=areacat
 </pre></div>
 
-<p>
-3) Create a new vector map which contains <B>lines connecting nearest
-features</B> of maps <B>pnt</B> and map <B>ln</B>. The resulting vector map
-can be used for example to connect points to a network as needed for
-network analysis:
-<br>
+<H3>Create a new vector map</H3>
+
+Create a new vector map which contains <EM>lines connecting nearest
+features</EM> of maps <B>pnt</B> and map <B>ln</B>. The resulting
+vector map can be used for example to connect points to a network as
+needed for network analysis:
+
 <div class="code"><pre>
 v.distance -p from=pnt to=ln out=connections upload=dist column=dist
 </pre></div>
 
+<H3>Query information</H3>
+
+Query information from selected point(s). <EM>v.distance</EM> takes
+points from a vector map as input instead of stdin. A new vector map
+with query points has to be created before the map can be analysed.
 <p>
-4) Query information from selected point(s). v.distance takes points from 
-   vector as input instead of stdin. First new vector map with query points, 
-   has to be created, then the map can be analysed:
-<br>   
-Create query map (if not present):<br>
+
+Create query map (if not present):
+
 <div class="code"><pre>
 echo "123456|654321|1" | v.in.ascii output=pnt
 </pre></div>
-<br>
-Find nearest features:<br>
+
+Find nearest features:
+
 <div class="code"><pre>
 v.distance from=pnt to=map_to_query upload=cat col=somecol -p
 </pre></div>
 
-<p>
-5) Point-in-polygon: Find <B>area</B> from vector map <B>ar</B> for each point 
-from vector map <B>pnt</B> in which the individual point falls into and write
-the related area categories to column <B>areacat</B> into attribute table 
-attached to vector map <B>pnt</B>:
-<br>
+<H3>Point-in-polygon</H3>
+
+Find <EM>area</EM> from vector map <B>ar</B> for each point from
+vector map <B>pnt</B> in which the individual point falls, and
+write the related area categories to column <B>areacat</B> into
+the attribute table attached to vector map <B>pnt</B>:
+
 <div class="code"><pre>
 v.distance from=pnt to=ar dmax=0 upload=cat column=areacat
 </pre></div>
 
-<p>
-6) Univariate statistics on results: Create a vector map containing connecting
-lines and investigate mean distance to targets.<br>
-An alternative solution is to use the <tt>v.distance upload=dist</tt> option 
-to upload distances into the <i>bugs</i> vector directly, then run v.univar 
-on that. Also note you can  upload two columns at a time.<BR>
-e.g. <tt>v.distance upload=cat,dist column=nearest_id,dist_to_nr</tt>
-<br>
+<H3>Univariate statistics on results</H3>
+
+Create a vector map containing connecting lines and investigate mean
+distance to targets. An alternative solution is to use
+the <tt>v.distance upload=dist</tt> option to upload distances into
+the <i>bugs</i> vector directly, then run v.univar on that. Also note
+you can upload two columns at a time, e.g. <tt>v.distance
+upload=cat,dist column=nearest_id,dist_to_nr</tt>.
+
 <div class="code"><pre>
 # create working copy
 g.copy vect=bugsites,bugs
@@ -93,15 +118,15 @@
 v.univar vdistance_vectors column=length
 </pre></div>
 
+<H3>Print distance matrix</H3>
 
-<H2>NOTES</H2>
-If a nearest feature does not have a category, column is updated to <B>null</B>.
-This is true also for areas, which means for example, that if point is in island
-(area WITHOUT category), v.distance does not search for nearest area WITH category,
-island is identified as nearest and category updated to null.
-<p>
-The upload <B>column</B>(s) must already exist. Create one with <em>v.db.addcol</em>.
+<div class="code"><pre>
+v.distance -pa from=archsites to=archsites upload=dist col=dist
+</pre></div>
 
+Note: Matrix-like output is enabled only for flag <EM>-a</EM> and one
+given upload option.
+
 <H2>SEE ALSO</H2>
 
 <EM>
@@ -113,11 +138,9 @@
 
 <H2>AUTHOR</H2>
 
-Janne Soimasuo 1994, Finland<br>
-University of Joensuu, Faculty of Forestry, Finland
-<p>
-5.0 cmd line coordinates support: Markus Neteler, ITC-irst, Trento, Italy<BR>
-<p>
-5.1 update Radim Blazek, ITC-irst, Trento, Italy
+Janne Soimasuo 1994, University of Joensuu, Faculty of Forestry, Finland<BR>
+Cmd line coordinates support: Markus Neteler, ITC-irst, Trento, Italy<BR>
+Updated for 5.1: Radim Blazek, ITC-irst, Trento, Italy<BR>
+Martix-like output by Martin Landa, FBK-irst, Trento, Italy
 
 <p><i>Last changed: $Date$</i>