Outputs in radians (Default is degrees). Input is always in degrees

Extended mode. For now supports only direction of streams of higher order and elevation difference between starting and finishig point of the segment.

Stream network: name of input stream map on which segmentation will be performed produced by r.watershed or r.stream.extract. Because streams network produced by r.watershed and r.stream.extract may slighty 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 r.watershed and r.stream.extract. If not 0 or NULL use r.mapcalc to set background values to null.

Flow direction: name of input direction map produced by r.watershed or r.stream.extract. If r.stream.extract 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 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 resoultion must be the same. Also stream network 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.

Elevation map. Must be the same as used to calculate streams and dirs. Map can by of any type, but for calculation speed FCELL is the best choice.

Ordering method. If different than none ordering is choosen, the segmentation proccess ignores junctions and create segments along streams belonging to the same order.

Integer values indicating the search length (in cells) to determine stright line. The longest length parameter the more tolerant the module treats local stream undulation and inequalities. Default value of 15 is suitable for 30 meters DEMS. More details DEMS may requre longer length.
Integer values indicating the length (in cells) to skip local short segment and join them with the longer neigbor. The shortest length parameter the more short segments will be produced by the module due to undulation and inequalities. Default value of 15 is suitable for 30 meters DEMS. More details DEMS may requre longer length.
real value indicates the internal angle between upstream and downsteam direction to treat actual cell as lying on the stright line. greater value (up to 180 degrees) produces more segments. Lesser values produced less segments. Values below 90 in most cases will not produce any addational segments to that resulting from ordering


The module produces one vector map divided into segments resulting form segmentation proccess. Every segmement has ascribed following parameters:


The main idea comes from works of Horton (1932) and Howard (1971, 1990). The module is designed to calculate angle relations between tributaries and its major streams. The main problem in calculating directional parameters is that streams usually are not straight lines. Therefore as the first step of the procedure, partitioning of streams into near-straight-line segments is required.

The segmentation process uses a method similar to the one used by Van & Ventura (1997) to detect corners and partition curves into straight lines and gentle arcs. Because it is almost impossible to determine exactly straight sections without creating numerous very short segments, the division process requires some approximation. The approximation is made based on three parameters: (1) the downstream/upstream search length, (2) the short segment skipping threshold, and (3) the maximum angle between downstream/upstream segments to be considered as a straight line. In order to designate straight sections of the streams, the algorithm is searching for those points where curves significantly change their direction. The definition of stream segments depends on the ordering method selected by the user, Strahler's, Horton's or Hack's main stream, or the network may remain unordered. All junctions of streams to streams of higher order are always split points, but for ordered networks, streams of higher order may be divided into sections which ignore junctions with streams of lower order. In unordered networks all junctions are always split points. In extended mode the module also calculates the direction of a stream to its higher order stream If the higher order stream begins at the junction with the current stream (Strahler's ordering only) or if the network is unordered, the direction is calculated as the direction of the line between junction point and downstream point (Howard 1971) within the user-defined global search distance. If a higher order stream continues at the junction, its direction is calculated as the direction of the tangent line to the stream of higher order at the junction point. To avoid local fluctuation, the tangent line is approximated as a secant line joining downstream/upstream points at a distance globally defined by the search length parameter (1). Such a definition of the angle between streams is not fully compatible with Horton's original criterion.


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 r.stream.extract also direction map from r.stream.extract must be used. If stream network was generated with MFD method also MFD direction map must be used.

Module is still in experimental phase. It means that something may change in the future in the module core.


r.watershed, r.stream.extract, r.stream.order, r.stream.stats, r.mapcalc, r.reclass, r.patch


Jarek Jasiewicz


Horton, R. E., (1932). Drainage basin characteristics: Am. Geophys. Union Trans., (3), 350-361.

Howard, A.D. (1971). Optimal angles of stream junction: Geometric, Stability to capture and Minimum Power Criteria, Water Resour. Res. 7(4), 863-873.

Howard, A.D. (1990). Theoretical model of optimal drainage networks Water Resour. Res., 26(9), 2107-2117.

Van, W., Ventura, J.A. (1997). Segmentation of Planar Curves into Straight-Line Segments and Elliptical Arcs, Graphical Models and Image Processing 59(6), 484-494.

Last changed: $Date$