r.hydro.flatten

Derive elevation of water bodies for hydro-flattening

r.hydro.flatten [-k] input=name [breaklines=name] water_elevation=name water_elevation_stddev=name [filled_elevation=name] percentile=float [min_size=integer] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.hydro.flatten input=name water_elevation=name water_elevation_stddev=name percentile=5

grass.script.run_command("r.hydro.flatten", input, breaklines=None, water_elevation, water_elevation_stddev, filled_elevation=None, percentile=5, min_size=None, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.hydro.flatten", input="name", water_elevation="name", water_elevation_stddev="name", percentile=5)

Parameters

Command linePython (grass.script)

input=name [required]
    Raster map of binned lidar point elevation
breaklines=name
    Name of input vector map
    Vector map of breaklines
water_elevation=name [required]
    Raster map of derived water elevation
    Represents single elevation value for each water body
water_elevation_stddev=name [required]
    Raster map of derived water elevation standard deviation
filled_elevation=name
    Raster map representing filled digital elevation model
percentile=float [required]
    Percentile of elevation to determine water level
    Default: 5
min_size=integer
    Minimum size of areas in map units
-k
    Keep intermediate results
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

input : str, required
    Raster map of binned lidar point elevation
    Used as: input, raster, name
breaklines : str, optional
    Name of input vector map
    Vector map of breaklines
    Used as: input, vector, name
water_elevation : str, required
    Raster map of derived water elevation
    Represents single elevation value for each water body
    Used as: output, raster, name
water_elevation_stddev : str, required
    Raster map of derived water elevation standard deviation
    Used as: output, raster, name
filled_elevation : str, optional
    Raster map representing filled digital elevation model
    Used as: output, raster, name
percentile : float, required
    Percentile of elevation to determine water level
    Default: 5
min_size : int, optional
    Minimum size of areas in map units
flags : str, optional
    Allowed values: k
    k
        Keep intermediate results
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
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

The tool derives single elevation value for water bodies based on lidar data. These values are used for hydro-flattening a digital elevation model. The input raster is expected to represent ground surface created by binning lidar data (e.g., using r.in.pdal) with averaged ground elevation. Small gaps in the input are expected. Large gaps are interpreted as water bodies. The minimum size of a water body can be set with min_size option in map units.

The output water_elevation is a raster map of water bodies where each water body has a single value representing the water level elevation derived from the lidar data at the edge of a water body. Since the elevation varies along the edge, option percentile is used to determine a single value. The variation along the edge can be examined with the water_elevation_stddev output representing the standard deviation of the lidar elevation values along the water body's edge. Higher deviation suggests problematic areas that need to be further inspected. The optional output filled_elevation is a raster map of the input ground surface filled with the computed water_elevation raster map.

The breaklines parameter is an optional input that specifies a vector map of lines that represent e.g., a break between an impoundment and downstream river, allowing correct elevation computation.

To keep the intermediate results for inspection, use flag -k.

NOTES

While this tool was designed for water bodies, it can be used for other purposes, e.g., for filling a gap in digital elevation models caused by excluding buildings.

This tool does not interpolate gaps in data, rather it derives a single value for each gap. The result can be used to fill gaps and the tool can be run on large areas. For actual gap interpolation, which is typically more computationally intensive, see r.fillnulls.

EXAMPLE

We will download a lidar tile with r.in.usgs addon, use r.in.pdal to bin the elevation points at 1 meter resolution, and derive elevation levels for lakes with minimum size of 4000 m^2.

# select study area and resolution
g.region n=213300 s=211900 w=653900 e=655300 res=1
# download lidar tile into /tmp
r.in.usgs product=lidar output_directory=/tmp title_filter=Phase2 -d
# bin point elevation using ground and road points with reprojection
r.in.pdal input=/tmp/USGS_LPC_NC_Phase2_2014_LA_37_20164902_.laz output=ground -w class_filter=2,13
# convert elevation from feet to meters
r.mapcalc "ground_m = ground * 0.304800609601219"
# derive elevation of water bodies and standard deviation
r.hydro.flatten input=ground_m water_elevation=water_elevation water_elevation_stddev=water_elevation_stddev filled_elevation=filled percentile=10 misize=4000

Figure: Input binned elevation representing ground with gaps (left), input overlayed with elevation values estimated for gaps and highlighted with an outline (middle), input overlayed with standard deviation of the elevation along the edge of the gaps (right).

REFERENCE

Method based on workflow presented at NC GIS Conference 2021 by Doug Newcomb.

AUTHOR

Anna Petrasova, NCSU GeoForAll Lab

SOURCE CODE

Available at: r.hydro.flatten source code (history)
Latest change: Thursday Feb 20 13:02:26 2025 in commit 53de819