r.fill.dir: move notes to description and reorganize, add warning about filling

Describe the alg first, then talk about outputs and settings.
Add note and reference for danger of filling.
Merge the two paragraps about directions.
Mention NULLs from r71809. Fix image size (img is small enough).


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

raster/r.fill.dir/r.fill.dir.html

@@ -2,24 +2,11 @@
 
 <em>r.fill.dir</em> filters and generates a depressionless
 elevation map and a flow direction map from a given raster elevation map.
-
-<h2>NOTES</h2>
-
-The <b>format</b> parameter is the type of format at which the user wishes to create
-the flow direction map. The <i>agnps</i> format gives category values from
-1-8, with 1 facing north and increasing values in the clockwise direction.
-The <i>answers</i> format gives category values from 0-360 degrees, with 0
-(360) facing east and values increasing in the counter clockwise direction
-at 45 degree increments. The <i>grass</i> format gives the same category
-values as <em><a href="r.slope.aspect.html">r.slope.aspect</a></em>.
-<p>
-The flow direction map can be visualized with
-<em><a href="d.rast.arrow.html">d.rast.arrow</a></em>.
-<p>
 The method adopted to filter the elevation map and rectify it is
-based on the paper titled "Software Tools to Extract Structure from Digital
-Elevation Data for Geographic Information System Analysis" by S.K. Jenson
-and J.O. Domingue (1988).
+based on the paper titled "Extracting topographic structure from
+digital elevation model data for geographic information system analysis"
+by S.K. Jenson and J.O. Domingue (1988).
+
 <p>
 The procedure takes an elevation layer as input and initially fills all the
 depressions with one pass across the layer. Next, the flow direction
@@ -28,6 +15,7 @@ program detects areas with pothholes, it delineates this area from the rest
 of the area and once again the depressions are filled using the neighborhood
 technique used by the flow direction routine. The final output will be a
 depressionless elevation layer and a unique flow direction layer.
+
 <p>
 This (D8) flow algorithm performs as follows: At each raster cell the code
 determines the slope to each of the 8 surrounding cells and assigns the flow
@@ -39,11 +27,25 @@ based on flow directions in the adjacent cells. <em>r.fill.dir</em> iterates tha
 effectively propagating flow directions from areas where the directions are
 known into the area where the flow direction cannot otherwise be resolved.
 
-<p>The flow direction map can be encoded in either ANSWERS (Beasley et.al,
-1982) or AGNPS (Young et.al, 1985) form, so that it can be readily used as
-input to these hydrologic models. The resulting depressionless elevation
-layer can further be manipulated for deriving slopes and other attributes
-required by the hydrologic models.
+<p>
+The <b>format</b> parameter is the type of format at which the user wishes to create
+the flow <b>direction</b> map.
+The flow direction map can be encoded in GRASS GIS aspect format,
+ANSWERS (Beasley et.al, 1982), or AGNPS (Young et.al, 1985) format,
+so that it can be readily used as input to other GRASS GIS modules
+or the aforementioned hydrological models.
+The <i>grass</i> format gives the same category
+values as <em><a href="r.slope.aspect.html">r.slope.aspect</a></em>
+gives for aspect, i.e. angles in degrees counter-clockwise from east
+in 45 degree increments.
+The <i>agnps</i> format gives category values from
+1-8, with 1 facing north and increasing values in the clockwise direction.
+The <i>answers</i> format gives category values from 0-360 degrees,
+with 0 (represented as 360) facing east and values increasing in the
+counter-clockwise direction at 45 degree increments.
+In all cases, NULL (no data) values are used for cells where direction
+cannot be determined.
+
 <p>
 In case of local problems, those unfilled areas can be stored optionally.
 Each unfilled area in this maps is numbered. The <b>-f</b> flag
@@ -55,15 +57,42 @@ but not filled. This option was included because filling DEMs was often not
 the best way to solve a drainage problem. These options let the user get a
 partially-fixed elevation map, identify the remaining problems and fix the
 problems appropriately.
+
 <p>
-<em>r.fill.dir</em> is sensitive to the computational region settings. Thus 
+In some cases it may be necessary to run <em>r.fill.dir</em> repeatedly (using output
+from one run as input to the next run) before all of problem areas are
+filled.
+
+<p>
+The resulting depressionless elevation
+raster map can further be processed to derive slopes and other
+attributes required by other hydrological models.
+
+<p>
+As any GRASS GIS module, <em>r.fill.dir</em> is sensitive to the
+computational region settings. Thus
 the module can be used to generate a flow direction map for any 
 sub-area within the full map layer. Also, <em>r.fill.dir</em> is
 sensitive to any raster <em>MASK</em> in effect.
+
+<h2>NOTES</h2>
+
 <p>
-In some cases it may be necessary to run <em>r.fill.dir</em> repeatedly (using output
-from one run as input to the next run) before all of problem areas are
-filled.
+The <em>r.fill.dir</em> module can be used not only to fill depression,
+but also to detect water bodies or potential water bodies based on
+the nature of the terrain and the digital elevation model used.
+
+<p>
+Not all depressions are errors in digital elevation models. In fact,
+many are wetlands and as Jenkins and McCauley (2006) note careless use
+of depression filling may lead to unintended consequences such
+as loss of wetlands.
+
+<p>
+The flow direction map can be visualized with
+<em><a href="d.rast.arrow.html">d.rast.arrow</a></em>.
+
+
 
 <h2>EXAMPLES</h2>
 
@@ -107,9 +136,8 @@ d.vect elev_lid792_1m_fill_area type=boundary color=red
 </pre></div>
 
 <div align="center" style="margin: 10px">
-<a href="r_fill_dir.png">
-<img src="r_fill_dir.png" width="600" height="643" alt="r.fill.dir example" border=0><br>
-</a>
+<img src="r_fill_dir.png" alt="r.fill.dir example">
+<br>
 <i>Figure: Sink-filled DEM (shown as shaded terrain) with areas of filling shown as vector polygons</i>
 </div>
 
@@ -119,6 +147,11 @@ d.vect elev_lid792_1m_fill_area type=boundary color=red
 <ul>
 <li>Beasley, D.B. and L.F. Huggins. 1982. ANSWERS (areal nonpoint source watershed environmental 
 response simulation): User's manual. U.S. EPA-905/9-82-001, Chicago, IL, 54 p.
+<li>Jenkins, D. G., and McCauley, L. A. 2006.
+    GIS, SINKS, FILL, and disappearing wetlands:
+    unintended consequences in algorithm development and use.
+    In Proceedings of the 2006 ACM symposium on applied computing
+    (pp. 277-282).
 <li>Jenson, S.K., and J.O. Domingue. 1988. Extracting topographic structure from
 digital elevation model data for geographic information system analysis. Photogram.
 Engr. and Remote Sens. 54: 1593-1600.