update documentation

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

vector/v.net.alloc/v.net.alloc.html

@@ -1,33 +1,44 @@
 <h2>DESCRIPTION</h2>
 
-<em>v.net.alloc</em> allocates subnets for nearest centres (direction from 
-centre). Centre node must be opened (costs &gt;= 0). Costs of centre node are 
-used in calculation. Supported are cost assignments for both arcs and nodes, 
-and also different in both directions of a vector line. For areas, costs will 
-be calculated along boundary lines. The input vector map for 
-<em>v.net.alloc</em> needs to be prepared with <em>v.net operation=connect</em>.
+<em>v.net.alloc</em> allocates subnets for nearest centers (direction from 
+center). center nodes must be opened (costs &gt;= 0). Costs of center nodes are 
+used in the calculation. 
+<p>
+Costs may be either line lengths, or attributes saved in a database 
+table. These attribute values are taken as costs of whole segments, not 
+as costs to traverse a length unit (e.g. meter) of the segment. 
+For example, if the speed limit is 100 km / h, the cost to traverse a 
+10 km long road segment must be calculated as 
+length / speed = 10 km / (100 km/h) = 0.1 h.
+Supported are cost assignments for both arcs and nodes, 
+and also different costs for both directions of a vector line. 
+For areas, costs will be calculated along boundary lines.
+<p>
+The input vector needs to be prepared with <em>v.net operation=connect</em> 
+in order to connect points representing center nodes to the network.
 
 <h2>NOTES</h2>
 
-Center nodes have to be assigned to vector nodes
-using <em><a href="wxGUI.Vector_Digitizing_Tool.html">wxGUI vector
-digitizer</a></em>. Nodes and arcs can be closed using cost = -1. 
+Nodes and arcs can be closed using cost = -1. 
+<p>
+Center nodes can also be assigned to vector nodes using 
+<em><a href="wxGUI.Vector_Digitizing_Tool.html">wxGUI vector digitizer</a></em>. 
 
 <h2>EXAMPLES</h2>
 
-Example 1: <em>Calculating subnets for 3 centre nodes using distances</em>
+Example 1: <em>Calculating subnets for 3 center nodes using distances</em>
 <div class="code"><pre>
 #Spearfish
 
-# centre nodes:
+# center nodes:
 echo "591235.5|4926306.62|1
 596591.8|4917042.5|2
-602722.9|4923544.2|3" | v.in.ascii out=centrenodes
+602722.9|4923544.2|3" | v.in.ascii out=centernodes
 
 g.copy vect=roads,myroads
 
 #connect points to network
-v.net myroads points=centrenodes out=myroads_net op=connect thresh=200
+v.net myroads points=centernodes out=myroads_net op=connect thresh=200
 
 # view map
 g.region vect=myroads_net
@@ -51,20 +62,53 @@ d.vect myroads_net col=red icon=basic/triangle fcol=green size=12 layer=2
 
 <img src="v_net_alloc.png" alt="v.net.alloc example" border="1">
 
-
-<p>
-Example 2: <em>Calculating subnets for 7 centre nodes using cost assigned to vector length
-</em><br>
-<div class="code"><pre>
-v.net.alloc in=vectmap out=vectmap.alloc ccats=1-7
-</pre></div>
-
 <p>
 
-Example 3: <em>Calculating subnets for 7 centre nodes using cost assignments in both 
+Example 2: <em>Calculating subnets for 3 center nodes using cost assignments in both 
 directions</em><br>
+
 <div class="code"><pre>
-v.net.alloc in=vectmap afcol=INDEX abcol=INDEXBACK out=vectmap.alloc ccats=1-7
+#Spearfish
+
+# center nodes:
+echo "591235.5|4926306.62|1
+596591.8|4917042.5|2
+602722.9|4923544.2|3" | v.in.ascii out=centernodes
+
+# create unique categories for each road in layer 2
+v.category in=roads out=myroads opt=add cat=1 layer=2
+
+# add new table for layer 2
+v.db.addtable myroads layer=2 col="cat integer,label varchar(43),length double precision,speed double precision,cost double precision,bcost double precision"
+
+# copy road type to layer 2
+v.to.db myroads layer=2 qlayer=1 opt=query qcolumn=label columns=label
+
+# create lines map connecting points to network (take care of layers)
+v.net myroads points=centernodes out=myroads_net op=connect thresh=500 alayer=2 nlayer=1
+
+# set up costs
+
+# upload road length in miles
+v.to.db map=myroads_net layer=2 type=line option=length col=length unit=miles
+
+# set speed limits in miles / hour
+v.db.update myroads_net layer=2 col=speed val="5.0"
+v.db.update myroads_net layer=2 col=speed val="75.0" where="label='interstate'"
+v.db.update myroads_net layer=2 col=speed val="75.0" where="label='primary highway, hard surface'"
+v.db.update myroads_net layer=2 col=speed val="50.0" where="label='secondary highway, hard surface'"
+v.db.update myroads_net layer=2 col=speed val="25.0" where="label='light-duty road, improved surface'"
+v.db.update myroads_net layer=2 col=speed val="5.0" where="label='unimproved road'"
+
+# define traveling costs as traveling time in hours:
+
+# set forward costs
+v.db.update myroads_net layer=2 col=cost val="length / speed"
+# set backward costs
+v.db.update myroads_net layer=2 col=bcost val="length / speed"
+
+# subnetowrk allocation with fastest paths
+v.net.alloc in=myroads_net afcol=cost abcol=bcost out=myroads_net_alloc ccats=1-3
 </pre></div>
 
 <h2>SEE ALSO</h2>

vector/v.net.iso/v.net.iso.html

@@ -1,21 +1,28 @@
 <h2>DESCRIPTION</h2>
 
 <em>v.net.iso</em> splits a network into bands between cost isolines 
-(distance from centre). Centre nodes must be opened (costs >= 0). The 
-costs of centre nodes are used in the calculation. Supported are cost 
-assignments for both arcs and nodes, and also different in both 
-directions of a vector line. For areas, costs will be calculated along 
-boundary lines.
+(distance from center). Center nodes must be opened (costs &gt;= 0). The 
+costs of center nodes are used in the calculation. 
+<p>
+Costs may be either line lengths, or attributes saved in a database 
+table. These attribute values are taken as costs of whole segments, not 
+as costs to traverse a length unit (e.g. meter) of the segment. 
+For example, if the speed limit is 100 km / h, the cost to traverse a 
+10 km long road segment must be calculated as 
+length / speed = 10 km / (100 km/h) = 0.1 h.
+Supported are cost assignments for both arcs and nodes, 
+and also different costs for both directions of a vector line. 
+For areas, costs will be calculated along boundary lines.
 <p>
 The input vector needs to be prepared with <em>v.net operation=connect</em> 
-in order to connect points representing centre nodes to the network.
+in order to connect points representing center nodes to the network.
 
 <h2>NOTES</h2>
 
-Nodes must be on the isolines.<P>
+Nodes and arcs can be closed using cost = -1. 
+<p>
+Nodes must be on the isolines.
 
-Center nodes have to be assigned to vector nodes. Nodes and arcs can be closed 
-using cost = -1. 
 
 <h2>EXAMPLE</h2>
 

vector/v.net.path/v.net.path.html

@@ -1,11 +1,27 @@
 <h2>DESCRIPTION</h2>
 
-<em>v.net.path</em> can find shortest path(s) on the vector network.
+<em>v.net.path</em> determines least costly, e.g. shortest or fastest 
+path(s) on a vector network.
+
+<p>
 Costs may be either line lengths, or attributes saved in a database 
-table. These attributes values are taken as costs of whole segments, not 
-as costs to traverse a lnegth unit (e.g. meter) of the segment. If read 
-from the table, arcs' costs may be different in both directions.
-Shortest paths are written to output vector map with an attached attribute table.
+table. These attribute values are taken as costs of whole segments, not 
+as costs to traverse a length unit (e.g. meter) of the segment. 
+For example, if the speed limit is 100 km / h, the cost to traverse a 
+10 km long road segment must be calculated as 
+length / speed = 10 km / (100 km/h) = 0.1 h.
+Supported are cost assignments for both arcs and nodes, 
+and also different costs for both directions of a vector line. 
+For areas, costs will be calculated along boundary lines.
+<p>
+The input vector needs to be prepared with <em>v.net operation=connect</em> 
+in order to connect points representing center nodes to the network.
+
+<p>
+Nodes and arcs can be closed using cost = -1. 
+<p>
+Least cost paths are written to the output vector map with an 
+attached attribute table.
 <P>
 Nodes can be piped into the program from file or from stdin. The
 syntax is as follows:
@@ -46,58 +62,73 @@ The attribute table will contain the following attributes:
 </ul>
 
 <h2>NOTES</h2>
-
-If the columns 'afcol', 'abcol' and 'ncol' costs are not
+Nodes and arcs can be closed using cost = -1. 
+<p>
+If the cost columns 'afcol', 'abcol' and 'ncol' are not
 specified, the length of network segments is measured and 
 zero costs are assumed for nodes.
 <P>
 When using attributes, the length of segments is not used. To get
-more precise results, length should be taken indirectly into account
-by attributes. For example, to get the <b>fastest path</b> the columns 
-'max_speed' and 'length' are required. The correct fastest path can then 
-be found by specifying <tt>afcol=length/max_speed</tt> (pg driver). If needed,
+accurate results, the line length must be taken into account when 
+assigning costs as attributes. For example, to get the <b>fastest path</b>, 
+the columns 'max_speed' and 'length' are required. The correct fastest 
+path can then be found by specifying <tt>afcol=length/max_speed</tt>. If needed,
 the line length can be calculated and written to the attributes table 
 by <em>v.to.db</em>.
 
 <h2>EXAMPLE</h2>
 
-Shortest path from two digitized nodes (Spearfish):
+Fastest path between two digitized nodes (Spearfish):
 
 <div class="code"><pre>
-g.copy vect=roads,myroads
-v.db.addcolumn myroads col="forward double precision, backward double precision"
-
-# define traveling costs as inverse of speed limit:
-v.db.update myroads col=forward val=1/50
-v.db.update myroads col=backward val=1/50
-v.db.update myroads col=forward val=1/75 where="label='interstate'"
-v.db.update myroads col=backward val=1/75 where="label='interstate'"
-v.db.update myroads col=forward val=1/5 where="label='unimproved road'"
-v.db.update myroads col=backward val=1/5 where="label='unimproved road'"
-v.db.update myroads col=forward val=1/25 where="label='light-duty road, improved surface'"
-v.db.update myroads col=backward val=1/25 where="label='light-duty road, improved surface'"
-v.db.select myroads
 echo "1|601653.5|4922869.2|start
 2|593330.8|4924096.6|end" | v.in.ascii cat=1 x=2 y=3 out=startend col="cat integer, \
                          east double precision, north double precision, label varchar(43)"
 
 v.db.select startend
 
-#create lines map connecting points to network (on layer 2)
-v.net myroads points=startend out=myroads_net op=connect thresh=200
+# create unique categories for each road in layer 2
+v.category in=roads out=myroads opt=add cat=1 layer=2
+
+# add new table for layer 2
+v.db.addtable myroads layer=2 col="cat integer,label varchar(43),length double precision,speed double precision,forward double precision,backward double precision"
+
+# copy road type to layer 2
+v.to.db myroads layer=2 qlayer=1 opt=query qcolumn=label columns=label
+
+# connect points to road network (take care of layers)
+v.net myroads points=startend out=myroads_net op=connect thresh=200 alayer=2 nlayer=1
+
+# upload road length in miles
+v.to.db map=myroads_net layer=2 type=line option=length col=length unit=miles
+
+# set speed limits in miles / hour
+v.db.update myroads_net layer=2 col=speed val="5.0"
+v.db.update myroads_net layer=2 col=speed val="75.0" where="label='interstate'"
+v.db.update myroads_net layer=2 col=speed val="75.0" where="label='primary highway, hard surface'"
+v.db.update myroads_net layer=2 col=speed val="50.0" where="label='secondary highway, hard surface'"
+v.db.update myroads_net layer=2 col=speed val="25.0" where="label='light-duty road, improved surface'"
+v.db.update myroads_net layer=2 col=speed val="5.0" where="label='unimproved road'"
+
+# define traveling costs as traveling time in hours:
+
+# set forward costs
+v.db.update myroads_net layer=2 col=forward val="length / speed"
+# set backward costs
+v.db.update myroads_net layer=2 col=backward val="length / speed"
+
 g.region vect=myroads_net
 d.mon x0
 d.vect myroads_net
 d.vect startend col=red
 
-v.db.select myroads_net
-
 d.vect myroads_net icon=basic/triangle fcol=green size=12 layer=2
 d.vect myroads_net disp=cat type=point lsize=14 layer=2
 # ... the 'start' and 'end' nodes have category number 1 and 2
 
-# ID as first number, then cat1 and cat2
+# Fastest path: ID as first number, then cat1 and cat2
 echo "1 1 2" | v.net.path myroads_net afcol=forward abcol=backward out=mypath
+
 d.vect mypath col=red width=2
 </pre></div>
 

vector/v.net.salesman/v.net.salesman.html

@@ -1,30 +1,37 @@
 <h2>DESCRIPTION</h2>
 
 <em>v.net.salesman</em> calculates the optimal route to visit nodes on a
-vector network. If no cost column is given, the length of a line (road segment)
-is used to estimate travelling costs. If a cost column is given, the cost
-values must indicate the costs to traverse a given line, e.g. if the speed
-limit is 100 km / h, the cost to traverse a 10 km long road segment is 
-calculated as length / speed = 10 km / (100 km/h) = 0.1 h.
+vector network.
+
+<p>
+Costs may be either line lengths, or attributes saved in a database 
+table. These attribute values are taken as costs of whole segments, not 
+as costs to traverse a length unit (e.g. meter) of the segment. 
+For example, if the speed limit is 100 km / h, the cost to traverse a 
+10 km long road segment must be calculated as 
+length / speed = 10 km / (100 km/h) = 0.1 h.
+Supported are cost assignments for both arcs and nodes, 
+and also different costs for both directions of a vector line. 
+For areas, costs will be calculated along boundary lines.
+<p>
+The input vector needs to be prepared with <em>v.net operation=connect</em> 
+in order to connect points representing center nodes to the network.
+
 <p>
 Points specified by category must be exactly on network nodes, and the 
 input vector map needs to be prepared with <em>v.net operation=connect</em>.
 
+<h2>NOTES</h2>
+Nodes and arcs can be closed using cost = -1. 
+
 <h2>EXAMPLE</h2>
 
 Traveling salesman for 6 digitized nodes (Spearfish):
+<p>
+Searching for the shortest path:
 
 <div class="code"><pre>
 g.copy vect=roads,myroads
-v.db.addcolumn myroads col="cost double precision, length double precision"
-
-# define traveling costs as length in miles divided by speed limit in miles per hour:
-v.to.db map=myroads layer=1 type=line qlayer=1 option=length col=length unit=miles
-v.db.update myroads col=cost val="length / 50"
-v.db.update myroads col=cost val="length / 75" where="label='interstate'"
-v.db.update myroads col=cost val="length / 5" where="label='unimproved road'"
-v.db.update myroads col=cost val="length / 25" where="label='light-duty road, improved surface'"
-v.db.select myroads
 
 # we have 6 locations to visit on our trip
 echo "1|601653.5|4922869.2|a
@@ -61,16 +68,91 @@ d.vect -c centers icon=basic/triangle
 d.font verdana
 d.vect centers col=red disp=attr attrcol=label lsize=12
 
-# run with traveling costs = length / speed
-v.net.salesman myroads_net acol=cost ccats=1-6 out=mysalesman_speed
-d.vect mysalesman_speed col=green width=2
-
 # run without traveling costs using line length
-v.net.salesman myroads_net ccats=1-6 out=mysalesman_length
+v.net.salesman myroads_net ccats=1-6 out=mysalesman_shortest
 d.vect mysalesman_length col=green width=2
 d.vect centers col=red disp=attr attrcol=label lsize=12
 </pre></div>
 
+<p>
+Searching for the fastest path, using speed limits according to road type:
+
+<div class="code"><pre>
+# we have 6 locations to visit on our trip
+echo "1|601653.5|4922869.2|a
+2|608284|4923776.6|b
+3|601845|4914981.9|c
+4|596270|4917456.3|d
+5|593330.8|4924096.6|e
+6|598005.5|4921439.2|f" | v.in.ascii cat=1 x=2 y=3 out=centers col="cat integer, \
+                         east double precision, north double precision, label varchar(43)"
+
+# verify data preparation
+v.db.select centers
+v.category centers op=report
+# type       count        min        max
+# point          6          1          6
+
+# create unique categories for each road in layer 2
+v.category in=roads out=myroads opt=add cat=1 layer=2
+
+# add new table for layer 2
+v.db.addtable myroads layer=2 col="cat integer,label varchar(43),length double precision,speed double precision,cost double precision,bcost double precision"
+
+# copy road type to layer 2
+v.to.db myroads layer=2 qlayer=1 opt=query qcolumn=label columns=label
+
+# create lines map connecting points to network (take care of layers)
+v.net myroads points=centers out=myroads_net op=connect thresh=500 alayer=2 nlayer=1
+v.category myroads_net op=report
+# Layer/table: 2/myroads_net_myroads_l_2
+# type       count        min        max
+# point          6          1          6
+# line         837          1          5
+#
+# Layer/table: 1/myroads_net_roads
+# type       count        min        max
+# point          0          0          0
+# line         837          1        825
+
+# The network is now prepared. Visualize it
+g.region vect=myroads_net
+d.mon x0
+d.vect myroads_net
+d.vect -c centers icon=basic/triangle
+d.font verdana
+d.vect centers col=red disp=attr attrcol=label lsize=12
+
+# set up costs
+
+# upload road length in miles
+v.to.db map=myroads_net layer=2 type=line option=length col=length unit=miles
+
+# set speed limits in miles / hour
+v.db.update myroads_net layer=2 col=speed val="5.0"
+v.db.update myroads_net layer=2 col=speed val="75.0" where="label='interstate'"
+v.db.update myroads_net layer=2 col=speed val="75.0" where="label='primary highway, hard surface'"
+v.db.update myroads_net layer=2 col=speed val="50.0" where="label='secondary highway, hard surface'"
+v.db.update myroads_net layer=2 col=speed val="25.0" where="label='light-duty road, improved surface'"
+v.db.update myroads_net layer=2 col=speed val="5.0" where="label='unimproved road'"
+
+# define traveling costs as traveling time in hours:
+
+# set forward costs
+v.db.update myroads_net layer=2 col=cost val="length / speed"
+# set backward costs
+v.db.update myroads_net layer=2 col=bcost val="length / speed"
+
+# fastest path: traveling costs = length / speed = hours
+v.net.salesman myroads_net alayer=2 nlayer=1 acol=cost ccats=1-6 out=mysalesman_fastest
+
+# with different columns for forward and backward costs:
+# result is identical to fastest path
+v.net.salesman myroads_net afcol=cost abcol=bcost ccats=1-6 out=mysalesman_back
+
+d.vect mysalesman_fastest col=green width=2
+d.vect centers col=red disp=attr attrcol=label lsize=12
+</pre></div>
 
 <img src="vnetsalesman.png" alt="v.net.salesman example" border="1">
 

vector/v.net.steiner/v.net.steiner.html

@@ -11,25 +11,26 @@ which will minimize the amount of fibre optic cable needed to connect
 a series of satellite offices.
 
 <p>
+Costs may be either line lengths, or attributes saved in a database 
+table. These attribute values are taken as costs of whole segments, not 
+as costs to traverse a length unit (e.g. meter) of the segment. 
+For example, if the speed limit is 100 km / h, the cost to traverse a 
+10 km long road segment must be calculated as 
+length / speed = 10 km / (100 km/h) = 0.1 h.
+Supported are cost assignments for both arcs and nodes. 
+For areas, costs will be calculated along boundary lines.
+
+<p>
 Points representing nodes must be exactly on network nodes, and the 
 input vector map needs to be prepared with <em>v.net operation=connect</em>.
 
 
 <h2>EXAMPLE</h2>
 
-Steiner tree for for 6 digitized nodes (Spearfish):
+Steiner tree for 6 digitized nodes (Spearfish), using traveling time as 
+costs:
 
 <div class="code"><pre>
-g.copy vect=roads,myroads
-v.db.addcolumn myroads col="cost double precision"
-
-# define traveling costs as inverse of speed limit:
-v.db.update myroads col=cost val=1/50
-v.db.update myroads col=cost val=1/75 where="label='interstate'"
-v.db.update myroads col=cost val=1/5 where="label='unimproved road'"
-v.db.update myroads col=cost val=1/25 where="label='light-duty road, improved surface'"
-v.db.select myroads
-
 # we have 6 locations to allocate
 echo "1|601653.5|4922869.2|a
 2|608284|4923776.6|b
@@ -44,17 +45,46 @@ v.category centers op=report
 # type       count        min        max
 # point          6          1          6
 
+# create unique categories for each road in layer 2
+v.category in=roads out=myroads opt=add cat=1 layer=2
+
+# add new table for layer 2
+v.db.addtable myroads layer=2 col="cat integer,label varchar(43),length double precision,speed double precision,cost double precision"
+
+# copy road type to layer 2
+v.to.db myroads layer=2 qlayer=1 opt=query qcolumn=label columns=label
+
 
-#create lines map connecting points to network (on layer 2)
-v.net myroads points=centers out=myroads_net op=connect thresh=500
+# create lines map connecting points to network (take care of layers)
+v.net myroads points=centers out=myroads_net op=connect thresh=500 alayer=2 nlayer=1
 v.category myroads_net op=report
-# Layer / table: 1 / myroads_net
+# Layer/table: 2/myroads_net_myroads_l_2
 # type       count        min        max
+# point          6          1          6
 # line         837          1          5
 #
-# Layer: 2
+# Layer/table: 1/myroads_net_roads
 # type       count        min        max
-# point          6          1          5
+# point          0          0          0
+# line         837          1        825
+
+# set up costs
+
+# upload road length in miles
+v.to.db map=myroads_net layer=2 type=line option=length col=length unit=miles
+
+# set speed limits in miles / hour
+v.db.update myroads_net layer=2 col=speed val="5.0"
+v.db.update myroads_net layer=2 col=speed val="75.0" where="label='interstate'"
+v.db.update myroads_net layer=2 col=speed val="75.0" where="label='primary highway, hard surface'"
+v.db.update myroads_net layer=2 col=speed val="50.0" where="label='secondary highway, hard surface'"
+v.db.update myroads_net layer=2 col=speed val="25.0" where="label='light-duty road, improved surface'"
+v.db.update myroads_net layer=2 col=speed val="5.0" where="label='unimproved road'"
+
+# define traveling costs as traveling time in hours:
+
+# set costs as traveling time
+v.db.update myroads_net layer=2 col=cost val="length / speed"
 
 # The network is now prepared.
 g.region vect=myroads_net
@@ -64,7 +94,7 @@ d.vect -c centers icon=basic/triangle
 d.font verdana
 d.vect centers col=red disp=attr attrcol=label lsize=12
 
-v.net.steiner myroads_net acol=cost tcats=1-6 out=mysteiner
+v.net.steiner myroads_net alayer=2 nlayer=1 acol=cost tcats=1-6 out=mysteiner
 d.vect mysteiner col=blue width=2
 </pre></div>