[GRASS-SVN] r71830 - grass/branches/releasebranch_7_4/raster/r.fill.dir

[svn_grass at osgeo.org]

Author: wenzeslaus
Date: 2017-11-25 14:35:40 -0800 (Sat, 25 Nov 2017)
New Revision: 71830

Modified:
   grass/branches/releasebranch_7_4/raster/r.fill.dir/r.fill.dir.html
Log:
r.fill.dir: move notes to description and reorganize, add warning about filling (backport r71811 and r71816 without ref to r71809)

Modified: grass/branches/releasebranch_7_4/raster/r.fill.dir/r.fill.dir.html
===================================================================
--- grass/branches/releasebranch_7_4/raster/r.fill.dir/r.fill.dir.html	2017-11-25 22:27:34 UTC (rev 71829)
+++ grass/branches/releasebranch_7_4/raster/r.fill.dir/r.fill.dir.html	2017-11-25 22:35:40 UTC (rev 71830)
@@ -2,25 +2,12 @@
 
 <em>r.fill.dir</em> filters and generates a depressionless
 elevation map and a flow direction map from a given raster elevation map.
+The method adopted to filter the elevation map and rectify it is
+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).
 
-<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).
-<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
 algorithm tries to find a unique direction for each cell. If the watershed
@@ -28,6 +15,7 @@
 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,12 +27,24 @@
 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.
+
+<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
 instructs the program to fill single-cell pits but otherwise to just find
@@ -55,16 +55,53 @@
 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 
-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.
-<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.
 
+<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>
+
+<ul>
+
+<li>
+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.
+
+<li>
+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.
+
+<li>
+Although many hydrological algorithms require depression filling,
+advanced algorithms such as those implemented in
+<em><a href="r.watershed.html">r.watershed</a></em> and
+<em><a href="r.sim.water.html">r.sim.water</a></em> do not require
+depressionless digital elevation model to work.
+
+<li>
+The flow direction map can be visualized with
+<em><a href="d.rast.arrow.html">d.rast.arrow</a></em>.
+
+</ul>
+
+
 <h2>EXAMPLES</h2>
 
 Generic example: create a depressionless (sinkless) elevation
@@ -107,9 +144,8 @@
 </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 +155,11 @@
 <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.