Categories in layer 1 of the out_ln lines are unchanged compared to vect. In layer 2, each line has a unique category. These categories increase at a step of 1 along each input line, down the input line direction. Following attributes are stored for each line in layer 2:
lcat - category of the input vect line
z - original elevation of the rast cell under the given out_ln line
z_breach - elevation of the rast cell under the given out_ln line breached, so that the elevation gradient down the watercourse is assured; minus additional depth specified
The z_breach is calculated in a following way: One line from the vect input is processed at a time. It is divided into segments, one per each input rast cell it flows through. Segments are being read down the line direction. If the elevation of the cell under the current segment >= elevation of the previous cell, the elevation of the line segment = the elevation of the previous cell - 0.000001 m. Otherwise, the elevation of the current segment = the elevation of the current cell. 0.000001 is the lowest value possible to use, because GRASS database modules round down everything beyond 6 decimal places (at least v.db.select and db.execute used in the script do).
There is one point in the out_pt per one out_ln line. Categories in layer 1 and 2 of out_pt are identical to the cats of the closest out_ln line. Points are located in the middles of out_ln lines, except the first and last point of the given cat in layer 1, which are located, respectively, at the beginning and at the end of the given input vect line. For this reason, where 2 or more input vect lines are connected, the same number of points lie on each other. Attributes stored are the same as in the layer 2 of out_ln, plus:
along - the distance from the starting node of the given input vect line
x - X coordinate
y - Y coordinate
The out_pt's z_breach attribute can be used as an aid in creating a hydrologically sound DEM. However, mind the multiple, identically located points at the connections between the input vect lines, and the multiple points per one input rast cell in case when 2 or more vect lines flow through a given cell.
In the 1st case, as the z_breach attribute of the duplicates is identical anyway, you might want to have only one of the points (eg. if your interpolation program can't handle duplicate input points). To remove duplicates use v.clean tool=rmdupl. To assess the latter case, you will need to modify your input vect so that max one stream flows through any rast cell, or increase the resolution of your input DEM so that it meets the level of detail in your input drainage network.
2. The script was developed for a metric coordinate system, but I suppose it should work in a feet (or other unit) based system as well, only it *might* require a few modifications in parts where it directly refers to meters. It won't work in lat/lon locations though for sure, without serious modifications. Summarising, candidate troublemakers in the script might be:
r.buffer distances=
v.parallel distance=
v.distance
v.to.db option=length
v.to.db option=coor
v.segment
sort -n
all the Awk maths
3. Each input vect line must have a unique category in layer 1. Use v.category to add categories, if needed.
4. An input line must not cross itself. Otherwise the script will go into an infinite loop.
5. For the same reason, any input lines must not constitute a loop.
6. Any of the input vect lines must not stand out of the input rast DEM.
7. The input DEM must have rectangular cells.
8. Input lines direction is the key. Use v.flip from GRASS AddOns to flip any if needed.
Last changed: $Date$