v.net-enhancing ddocumentation for v.net

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

vector/v.net/v.net.html

@@ -1,70 +1,117 @@
 <h2>DESCRIPTION</h2>
 
-<em>v.net</em> is used for network preparation and maintenance. 
-It permits to insert missing nodes or arcs and to connect unconnected 
-nodes to the network within a given distance threshold. 
-It can also report the current network graph status. 
-
-<h4>operation options</h4>
-<dl>
-<dt><em>connect</em> 
-<dd>Connects unconnected points in the input <em>points</em> vector map 
-to the vector network by inserting new lines.
-<dt><em>nodes</em>
-<dd>A new point is added for each node (line start/end) if a point does 
-not exist yet for this node.
-<dt><em>arcs</em>
-<dd>A new line is created from start point to end point.
-<dt><em>report</em>
-<dd>Print arc information:
-<div><pre>
-line_category start_point_category end_point_category
-</pre></div>
-<dt><em>nreport</em> 
-<dd>Print node information:
-<div><pre>point_category line_category[,line_category...]
-</pre></div>
-</dl>
-
-<p>In terms of network analysis, a network consists of nodes connected by 
-arcs. In a vector map prepared for network analysis, nodes are represented 
-by the grass-internal geometry type <em>node</em> and arcs by the geometry 
-type <em>line</em>. If a <em>line</em> consists of several vertices and 
-segments (the typical case), only its staring and ending vertex are 
-regarded as network nodes. Further more, explicit starting and ending 
-nodes for e.g. a least costly path search or subnetwork allocation are 
-represented by the geometry type point.
-
-<p>In general, network analysis will find the least costly (shortest or 
-fastest) path from point A to point B by follwing the existing lines. 
-This implies that these points must lie at the start or end point of a 
-line with is part of the network. If no line is starting or ending at a 
-given point, this point is not part of the network, i.e. the point is 
-unconnected and unreachable.
-
-<h2>NOTES</h2>
+<h3><em>v.net</em> is used for network preparation and maintenance. Its main
+use is to create a vector network from vector lines (<em>arcs</em>) and points 
+(<em>nodes</em>) by creating nodes from intersections in a map of vector 
+lines (<em>node</em> operator), by connecting a vector lines map with a points map 
+(<em>connect</em> operator), and by creating new lines between pairs of vector points 
+(<em>arcs</em> operator).</h3> 
+
+<p>A GIS network consists of topologically correct lines (arcs). That is, 
+the lines must be connected by shared vertices where real connections exist.
+In GRASS you also can add nodes to the network. These are specially 
+designated vertices used for analyzing network properties or computing 
+cost/distance measures. That is, not all vertices are treated as nodes by
+default. Only <em><a href="v.net.path.html">v.net.path</a></em> can use a network without nodes, they are reqired 
+for all the other network modules. In GRASS, network arcs are stored in one 
+data layer (normally layer 1) and nodes are stored in a different data layer 
+(normally layer 2). 
+
+<p><em>v.net</em> offers two ways to add nodes to a network of arcs and one 
+method to add arcs to a set of nodes:
+
+<ol>
+<li>Use the <em>connect</em> operation to create nodes from a vector points 
+file and add these nodes to an existing vector network of arcs (i.e., 
+lines/boundaries). This is useful when the goal is to analyze a set of places
+(points) in relation to a network--for example travel costs between places.
+Only points within the <em>thresh</em> (threshold) distance to a line/boundary
+will be connected as network nodes.</li>
+
+<p><li>Create nodes and arcs from a vector line/boundary file using the <em>node</em>
+operation. This is useful if you are mostly interested in the
+network itself and thus you can use intersections of the network as start and
+end points. Nodes will be created at all intersections of two or more lines.
+For an <em>arc</em> that consists of several segments connected by 
+vertices (the typical case), only the starting and ending vertices are 
+treated as network nodes.</li>
+
+<p><li>Create straight-line arcs between pairs of nodes with the <em>arcs</em> option. 
+This produces networks like those of airline flights between airports. It is
+also similar to the kind of network created with social networking
+software, making it possible to create georeferenced social networks.</li> 
+</ol>    
+    
+<p>While the arcs created with v.net will retain any attribute information
+associated with the input vector line/boundary file in data layer 1, nodes
+created and stored in data layer 2 will not have any associated attribute
+information. 
+
+<p>For nodes created using the <em>connect</em> and <em>arcs</em> operations (methods 1
+and 3 above), the nodes can be reconnected to the attribute table of the 
+input vector points file using the attribute table manager ("manage layers" 
+tab) or by running (<em><a href="v.db.connect.html">v.db.connect</a></em>).
+
+<p>For nodes created using the <em>nodes</em> operation 
+(method 2 above), it is possible to create an attribute table for the 
+new nodes in layer 2 using the attribute table manager and connect it to
+layer 2 ("manage layers" tab) or to create a table with v.db.addtable, 
+connect it to layer 2 with (<em><a href="v.db.connect.html">v.db.connect</a></em>), and update the new table with 
+cat values with (<em><a href="v.to.db.html">v.to.db</a></em>). 
+
+<p>Once a vector network has been created, it can be analyzed in a number
+of powerful ways using the suite of <em>v.net</em>.* modules. The shortest route 
+between two nodes, following arcs, can be computed (<em><a href="v.net.path.html">v.net.path</a></em>), as can the 
+shortest route that will pass through a set of nodes and return to the 
+starting node (<em><a href="v.net.salesman.html">v.net.salesman</a></em>). Least cost routes through the network can be 
+calculated on the basis of distance only or on the basis of distance weighted 
+by an attribute associated with each arc (for example, travel speed along a 
+network segment). A network can be divided into concentric zones of equal travel cost around 
+one or more nodes (<em><a href="v.net.iso.html">v.net.iso</a></em>) or subdivided so that each node is surrounded 
+by a zone in which all arcs can be reached with the same travel costs as all 
+arcs surrounding each other node (<em><a href="v.net.alloc.html">v.net.alloc</a></em>).</p> 
+
+In addition to the modules listed above, the GRASS vector networking suite
+includes numerous other modules for analysis of network costs and 
+connectivity.These include: 
+<em><a href="v.net.allpairs.html">v.net.allpairs</a></em>, 
+<em><a href="v.net.bridge.html">v.net.bridge</a></em>, 
+<em><a href="v.net.centrality.html">v.net.centrality</a></em>, 
+<em><a href="v.net.components.html">v.net.components</a></em>, 
+<em><a href="v.net.distance.html">v.net.distance</a></em>, 
+<em><a href="v.net.flow.html">v.net.flow</a></em>, 
+<em><a href="v.net.spanningtree.html">v.net.spanningtree</a></em>, 
+<em><a href="v.net.steiner.html">v.net.steiner</a></em>, 
+<em><a href="v.net.timetable.html">v.net.timetable</a></em>, and 
+<em><a href="v.net.visibility.html">v.net.visibility</a></em>.
+    
+<h3>NOTES</h3>
+
+For a vector map prepared for network analysis in GRASS, nodes are 
+represented by the grass-internal geometry type <em>node</em> and arcs 
+by the geometry type <em>line</em>. 
 
 If vector editing is required to modify the
 graph, <em><a href="wxGUI.Vector_Digitizer.html">wxGUI vector
 digitizer</a></em> or <em><a href="v.edit.html">v.edit</a></em> can be
-used. Separately,
-<a href="lrs.html">Linear Referencing System</a> is available in
+used. 
+See also the <a href="lrs.html">Linear Referencing System</a> available in
 GRASS.
 
-<h2>EXAMPLES</h2>
+<h3>EXAMPLES</h3>
 
 <a href="http://www.grassbook.org/data_menu3rd.php">NC dataset</a> based examples.
 
 <p>Create nodes globally for all line ends and intersections:
 
 <div class="code"><pre>
-v.net input=streams output=streams_node operation=nodes
+v.net input=streets_wake output=streets_node operation=nodes
 </pre></div>
 
 Merge in nodes from a separate map within given threshold:
 
 <div class="code"><pre>
-v.net input=streams points=firestations out=streems_net operation=connect thresh=500
+v.net input=streets_wake points=firestations out=streets_net operation=connect thresh=500
 </pre></div>
 
 For generating network for given vector point map is required input file in format
@@ -86,10 +133,6 @@ v.net points=geodetic_swwake_pts output=geodetic_swwake_pts_net operation=arcs f
 <em>
   <a href="wxGUI.Vector_Digitizer.html">wxGUI vector digitizer</a>,
   <a href="v.edit.html">v.edit</a><br>
-  <a href="v.net.iso.html">v.net.iso</a>,
-  <a href="v.net.path.html">v.net.path</a>,
-  <a href="v.net.steiner.html">v.net.steiner</a>,
-  <a href="v.net.salesman.html">v.net.salesman</a>
 </em>
 
 <h2>AUTHORS</h2>