r.findtheriver
Find the stream pixel nearest the input coordinate
r.findtheriver map=name [window=x] [threshold=x] coordinates=east,north [separator=character] [--verbose] [--quiet] [--qq] [--ui]
Example:
r.findtheriver map=name coordinates=east,north
grass.script.run_command("r.findtheriver", map, window=None, threshold=None, coordinates, separator="space", verbose=False, quiet=False, superquiet=False)
Example:
gs.run_command("r.findtheriver", map="name", coordinates=east,north)
Parameters
map=name [required]
Name of input upstream accumulation area raster map
window=x
The size of the window in pixels to search in for stream pixels. Must be an odd integer. If not supplied, window will be inferred based on raster resolution.
threshold=x
The threshold for distinguishing log(UAA) values of stream and non-stream pixels. If not supplied, threshold will be inferred from minimum and maximum raster values.
coordinates=east,north [required]
Coordinates of outlet point
separator=character
Field separator
Special characters: pipe, comma, space, tab, newline
Default: space
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
map : str, required
Name of input upstream accumulation area raster map
Used as: input, raster, name
window : int, optional
The size of the window in pixels to search in for stream pixels. Must be an odd integer. If not supplied, window will be inferred based on raster resolution.
Used as: x
threshold : float, optional
The threshold for distinguishing log(UAA) values of stream and non-stream pixels. If not supplied, threshold will be inferred from minimum and maximum raster values.
Used as: x
coordinates : tuple[float, float] | list[float] | str, required
Coordinates of outlet point
Used as: input, coords, east,north
separator : str, optional
Field separator
Special characters: pipe, comma, space, tab, newline
Used as: input, separator, character
Default: space
verbose: bool, optional
Verbose module output
Default: False
quiet: bool, optional
Quiet module output
Default: False
superquiet: bool, optional
Very quiet module output
Default: False
DESCRIPTION
r.findtheriver finds the nearest stream pixel to a coordinate pair using an upstream accumulating area (UAA) raster map. This is necessary because the coordinates for streamflow gages are often not perfectly registered to the topography represented by a digital elevation model (DEM) map. This presents a problem when trying to derive a watershed contributing area using r.water.outlet; if the streamflow gage does not fall on the stream as represented in the DEM, r.water.outlet can fail to derive the watershed area.
The basic assumption is that the UAA for "stream" pixels will be much higher than for adjacent "non-stream" pixels. r.findtheriver attempts to "snap" the coordinates of the streamflow gage to the "true" stream location by first identifying stream pixels within a search window, and then selecting the stream pixel that is closest (Cartesian distance) to the input gage coordinates. Stream pixels are identified by searching the UAA raster window for pixels that exceed a threshold. This is done by computing the log10 of the UAA value for the pixel corresponding to the gage coordinates and subtracting from it the log10 of each pixel in the window; for a given pixel if this difference is greater than the threshold, the pixel is deemed to be a stream pixel.
r.findtheriver will automatically compute the window and threshold if they are not supplied by the user. The window is determined based on a THRESHOLD_DISTANCE / cell resolution of the UAA map. The threshold is determined by subtracting the log10 of the UAA value at the input gage coordinate from the log10 of the maximum UAA value of the map, and then rounding down to the nearest integer, in other words: threshold = floor( log(maxUAA) - log(gageUAA) ).
The closest stream pixel is printed to standard output. If no stream pixels were found, nothing is printed.
SEE ALSO
AUTHORS
Brian Miles
Updated to GRASS 7 by Huidae Cho
SOURCE CODE
Available at: r.findtheriver source code
(history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819