Creates new category sequence for stream network instead of original. It may be usefull for calculating pixel position in ordered network (i.e Strahler or Horton). By defualt it use original category of streams

Stream network: name of input stream map on which calculation are be performed produced by r.watershed, r.stream.extract or r.stream.order. 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, r.stream.extract and r.stream.order. 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.

Integer used to multiply stream category for cells output map. Default is 1000. To store in one file both origial stream category and current pixel position the stream category is multipied by multipier and next current cell position is added. For typical network, where stream segments are below 1000 cells such multipier seems to be enough. For bigger networks or ordered networks may be to small in that multiper shall be increased to larger number: 10000 or 100000. Wrong multipier (ie not power of 10) do not stop calculation but may lead to wrong results.


At least one output map is required:

Name of integer map storing both original (or new) stream category and current pixel downstream position according formula category * multipier + cur_pix_pos.
Name of floation point map storing current pixel upstream distance (in map units) to the begining of the stream. Categoy is not stored.


Module r.stream.pos is typical helper module which can be used to fine-tune investigation on stream network at pixel scale and linear geostatistics. Module can be used together with other GRASS modules and R-CRAN to investigate local geomorphometric properties at any stream position. For limiting oputput size, cells stores two informations in one file. To recive current pixel stream category use (in R-CRAN) function floor(cells, multipier), where multipier is the multipier value used in r.stream.pos calculation. To recive current pixel position in segment use modulo operator: cell %% multipier. The lengths map store only upstream distance in map units from current pixel to the stream begining.


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.


r.watershed, r.stream.extract, r.stream.order,


Jarek Jasiewicz

Last changed: $Date$