[GRASS-SVN] r65633 - grass-addons/grass7/raster/r.stream.basins
svn_grass at osgeo.org
svn_grass at osgeo.org
Sun Jul 19 08:52:07 PDT 2015
Author: madi
Date: 2015-07-19 08:52:07 -0700 (Sun, 19 Jul 2015)
New Revision: 65633
Modified:
grass-addons/grass7/raster/r.stream.basins/r.stream.basins.html
Log:
Improved documentation
Modified: grass-addons/grass7/raster/r.stream.basins/r.stream.basins.html
===================================================================
--- grass-addons/grass7/raster/r.stream.basins/r.stream.basins.html 2015-07-19 15:44:21 UTC (rev 65632)
+++ grass-addons/grass7/raster/r.stream.basins/r.stream.basins.html 2015-07-19 15:52:07 UTC (rev 65633)
@@ -1,130 +1,154 @@
<h2>DESCRIPTION</h2>
-Module <em>r.stream.basins</em> is prepared to delineate basins and
-subbasins with different input data. Module is prepared to delineate
-unrestricted number of basins in one step. It can delineate basins
+The module <em>r.stream.basins</em> is prepared to delineate basins and
+subbasins with different input data. The module is prepared to delineate
+an unrestricted number of basins in one step. It can delineate basins
with three methods:
<ul>
-<li>Using coordinates: this option simply copies functionality of <em>r.water.outlet</em>.
-<li>Using vector points: it allow to manually point outlets with any method
-<li>Using streams (most advanced) it allow on lots of modifications. See
+<li>Using coordinates: this option performs the same operation as <em>r.water.outlet</em>.
+<li>Using vector points: it allows to manually point outlets with any method.
+<li>Using streams (most advanced): it allows broader functionalities: See the
examples for more details.
</ul>
-Only one method can be used at once. Methods cannot be mixed.
+Only one method can be used at once: the methods cannot be mixed.
<p>
-The most recommended method requires two maps: direction and
-streams. In spite of stream map we can store information required to
+The recommended method requires two maps: flow direction and
+streams.
+
+<!--FIXME: I do not understand, can this be rephrased?
+
+Original paragraph:
+
+In spite of streams map we can store information required to
proper delineation, we can also enumerate stream categories for
-which basins are to be created (cats option). Module is prepared to
-work with output data of <em>r.watershed</em>, <em>r.stream.extract</em>,
-<em>r.stream.order</em> also with modification done by
-<em>r.reclass</em> and <em>r.mapcalc</em>. <em>r.stream.basin</em> can delineate
-basins according outlets marked by raster streams, and polygons,
-vector points and numerical coordinates. If outlets are marked by
-points or coordinates it delineates basins which cells contribute to
-that points, if outlets are marked by streams it delineate cells
-which contribute to the last (downstream) cell of the every stream.
-If outlets are marked by polygon it delineate cells contributing to
-most downstream cell of the polygon. If polygon covers more outlets
-than of one basins it will create collective basin for all outlets
+which basins are to be created (cats option).
+
+My interpretation is the following sentence:
+-->
+
+Using cats option it is possible to create basins having the
+same category of the stream they refer to.
+
+The module is prepared to work with output data of <em>r.watershed</em>,
+<em>r.stream.extract</em>, <em>r.stream.order</em> also with modification done by
+<em>r.reclass</em> and <em>r.mapcalc</em>. <em>r.stream.basins</em> can delineate
+basins according outlets marked by raster streams, polygons,
+vector points or coordinates. If the outlets are given by
+points or coordinates, the module delineates the basins individuating the cells that
+drain into that point. If the outlets are marked by the streams, it includes the cells
+that contribute to the last (downstream) cell of each stream.
+If the outlets are marked by polygons, it includes the cells contributing to the
+most downstream cell of the polygon. If the polygon covers more outlets
+than of one basins, it will create a collective basin for all the outlets
with common category.
<h2>OPTIONS</h2>
<dl>
<dt><b>-z</b></dt>
<dd>Creates zero-value background instead of NULL. For some reason (like map
-algebra calculation) zero-valued background may be required. This flag produces
-zero-filled background instead of NULL (default).</dd>
+algebra calculation) zero-valued background may be required.
+</dd>
+
<dt><b>-c</b></dt>
<dd>By default <em>r.stream.basins</em> uses streams category as basin category. In some
-cases - for example if stream map is a product of map algebra and separate streams
-may not have unique values this option will create a new category sequence for
-each basin (do not work in vector point mode).
+cases - for example if streams map is a product of map algebra and separate streams
+may not have unique values - this option will create a new category sequence for
+each basin (it does not work in vector point mode).
</dd>
+
<dt><b>-l</b></dt>
-<dd>By default <em>r.stream.basins</em> create basins for all unique streams. This option
-delineate basins only for last streams ignoring upstream (do not work in vector
-point mode).
+<dd>By default <em>r.stream.basins</em> creates basins for all unique streams. This option
+delineates basins only for the last streams, ignoring upstream (it does not work in vector
+point mode).
</dd>
<dt><b>direction</b></dt>
-<dd> Flow direction: name of input direction map produced by
-<em>r.watershed</em> or <em>r.stream.extract</em>. If <em>
+<dd> Flow direction: name of input flow direction map produced by
+<em>r.watershed</em> or <em>r.stream.extract</em>.
+
+<!--FIXME: Verify this sentence:
+
+If <em>
r.stream.extract</em> output map is used, it only has non-NULL
-values in places where streams occur. NULL (nodata) cells are
-ignored, zero and negative values are valid direction data if they
+values in places where streams occur.
+
+My interpretation is that it mixes the flow direction output and the
+stream_rast output.
+-->
+
+<!--FIXME: Is the following sentence important? It seems to me that it describes the
+default conditions.
+
+NULL cells are ignored, zero and negative values are valid direction data if they
vary from -8 to 8 (CCW from East in steps of 45 degrees). Direction
-map shall be of type CELL values. Region resolution and map
-resolution must be the same.
-Also <em>stream</em> network map (if used) and direction map must
-have the same resolution. It is checked by default. If resolutions
-differ the module informs about it and stops. Region boundary and
-maps boundary may be differ but it may lead to unexpected results.
+map shall be of type CELL values.
+-->
+
+The resolution of the computational region must match with the resolution of
+the raster map. Also the <em>stream</em> network map (if used) and the direction map
+must have the same resolution. It is checked by default. If resolutions
+differ, the module informs about it and stops. Region boundary and
+maps boundaries may differ but it may lead to unexpected results.
</dd>
<dt><b>coors</b></dt>
-<dd>East and north coordinates for basin outlet. It can delineate only
-one basin using that option. This option simply copies functionality of
-<em>r.water.outlet</em>.
+<dd>East and north coordinates for the basin outlet. Using this option, it is possible
+to delineate only one basin at a time, similarly to <em>r.water.outlet</em>.
</dd>
+
<dt><b>stream_rast</b></dt>
-<dd>Stream network: name of input stream map on which ordering will
-be performed produced by <em>r.watershed</em> or <em>r.stream.extract</em>.
-Because streams network produced by <em>r.watershed</em> and
-<em>r.stream.extract</em> may slightly differ in detail, it is
+<dd>Stream network: name of input map of stream network, ordered according to the
+convention used by <em>r.watershed</em> or <em>r.stream.extract</em>.
+Since streams network produced by <em>r.watershed</em> and
+<em>r.stream.extract</em> might slightly differ in detail, it is
required to use both stream and direction map produced by the same
-module. Stream background shall have NULL value or zero value.
-Background values of NULL are by default produced by <em>r.watershed</em>
-and <em>r.stream.extract</em>. If not 0 or NULL use
-<em>>r.mapcalc</em> to set background values to null. </dd>
+module. The stream background can have either NULL or zero values.
+</dd>
<dt><b>cats</b></dt>
<dd>Stream categories to delineate basins for: All categories which are not in
-stream map are ignored. It can be used with stream network created by
+the stream map are ignored. It is possible to use the stream network created by
<em>r.watershed</em>, <em>r.stream.extract</em> or <em>r.stream.order</em>.
-For <em>r.stream.order</em> use category of order for which basins must
-be created. For example to delineate only basins for order two use <b>cats=2</b>.
-If you need unique category for every basin use <b>-c</b> flag.
+For <em>r.stream.order</em>, it is possible to select the order for which basins will
+be created. For example, to delineate only basins for the streams of second order,
+use <b>cats=2</b>.
+If you need unique categories for each basin, use <b>-c</b> flag.
</dd>
<dt><b>points</b></dt>
-<dd>Vector file containing basins outlet as vector points. Only point's
-categories are used to prepare basins. Attached table attached is ignored. Every
-point shall have his own unique category. In that mode flags <b>-l</b> and
+<dd>Vector file containing basins outlets as vector points. Only points'
+categories are used to delineate the basins. Attached tables are ignored. Every
+point shall have its own unique category. In this mode, flags <b>-l</b> and
<b>-c</b> are ignored.
</dd>
</dl>
<h2>OUTPUTS</h2>
-<p>The module produces one raster map with basins according user's rules</p>
+<p>The module produces one raster map with basins defined according to the user's
+rules.</p>
<h2>NOTES</h2>
<p>
-To receive good results outlets markers created by user shall overlapping with
-streams. On the other way basins could results with very small area. Input maps
+To achieve good results, outlets markers created by the user shall overlap with
+the streams, otherwise basins could result with very small area. Input maps
must be in CELL format (default output of <em>r.watershed</em>,
<em>r.stream.order</em> or <em>r.stream.extract</em>).
-<p>
-Module can work only if direction map, stream map and region map has same
-settings. It is also required that stream map and direction map come from the
-same source. For lots of reason this limitation probably cannot be omitted.
-This means, if stream map comes from <em>r.stream.extract</em>, also direction map from
-<em>r.stream.extract</em> must be used. If stream network was generated
-with MFD method, also MFD direction map must be used. Nowadays, if direction
-map comes from <em>r.stream.extract</em>, it must be patched by direction
-map from <em>r.watershed</em> (with <em>r.patch</em>).
<h2>EXAMPLES</h2>
<p>
To delineate all basins with categories of streams:
+
<div class="code"><pre>
r.stream.basins direction=direction stream_rast=streams basins=bas_basins_elem
</pre></div>
-To determine major and minor basins in area, defined by outlets, ignoring
-subbasins use - l flag. That flag ignores all nodes and uses only real outlets
+
+<p>
+To determine major and minor basins defined by outlets, ignoring
+subbasins, use -l flag. This flag ignores all nodes and uses only real outlets
(in most cases that on map border):
+
<div class="code"><pre>
r.stream.basins -l direction=direction stream_rast=streams basins=bas_basins_last
@@ -134,35 +158,39 @@
<p>
To delineate one or more particular basins defined by given streams, add simply
stream categories:
+
<div class="code"><pre>
r.stream.basins -lc direction=direction stream_rast=streams cats=2,7,184 basins=bas_basin
</pre></div>
<p>
-Do delineate basins of particular order we must use the following procedure:
+To delineate basins of particular order, the following procedure can be used:
<div class="code"><pre>
r.stream.basins -lc direction=direction stream_rast=strahler cats=2 \
- basins=bas_basin_strahler_2
+ basins=bas_basin_strahler_2
</pre></div>
<p>
-The usage of polygons as outlets markers is very useful when exact stream course
-cannot be clearly determined before running analysis, but the area of its
-occurrence can be determined (mostly in iterative simulations) Example uses
-<em>r.circle</em> but can be substituted by any polygon created for example with
-<em>v.digit</em>:
+The usage of polygons as outlets markers is useful when the exact stream course
+cannot be clearly determined before running the analysis, but the area of its
+occurrence can be determined (mainly by iterative simulations). In the example,
+<em>r.circle</em> is used, but it can be substituted by any polygon created for example
+with <em>v.digit</em>:
+
<div class="code"><pre>
r.circle -b output=circle coordinate=639936.623832,216939.836449 max=200
r.stream.basins -c direction=direction streams=circle basins=bas_simul
</pre></div>
+
<p>
To determine areas of contribution to streams of particular order use as
streams the result of ordering:
-<p>
+
<div class="code"><pre>
r.stream.basins direction=direction stream_rast=ord_strahler basins=bas_basin_strahler
</pre></div>
+
<p>
Determination of areas of potential source of pollution. The example will be
done for lake marked with FULL_HYDR 8056 in North Carolina sample dataset. The
@@ -171,11 +199,14 @@
<div class="code"><pre>
v.extract -d input=lakes at PERMANENT output=lake8056 type=area layer=1 \
where='FULL_HYDRO = 8056' new=-1
+
v.to.rast input=lake8056 output=lake8056 use=val type=area layer=1 value=1
+
r.stream.basins direction=direction streams=lake8056 basins=bas_basin_lake
</pre></div>
+
<p>
-See also tutorial: <a href="http://grass.OSGeo.org/wiki/R.stream.*">http://grass.OSGeo.org/wiki/R.stream.*</a>
+See also the tutorial: <a href="http://grass.OSGeo.org/wiki/R.stream.*">http://grass.OSGeo.org/wiki/R.stream.*</a>
<h2>SEE ALSO</h2>
More information about the grass-commit
mailing list