Skip to content

r.hand

Performs Height Above Nearest Drainage (HAND) analysis and flood inundation mapping with HAND method.

r.hand [-tm] elevation=name [streams=name] [direction=name] [inundation_raster=name] [hand=name] [inundation_strds=name] [threshold=integer] [depth=float] [start_water_level=float] [end_water_level=float] [water_level_step=float] [memory=memory in MB] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.hand elevation=name

grass.script.run_command("r.hand", elevation, streams=None, direction=None, inundation_raster=None, hand=None, inundation_strds=None, threshold=10000, depth=None, start_water_level=None, end_water_level=None, water_level_step=1, memory=300, flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.hand", elevation="name")

Parameters

elevation=name [required]
    Name of input elevation raster map
streams=name
    Stream raster map
    Name of the stream raster map
direction=name
    Flow direction raster map
    Name of the flow direction raster map
inundation_raster=name
    Name of the output inundation raster map
hand=name
    Height above nearest drainage raster map
    Name of the output HAND raster map
inundation_strds=name
    Name of the output inundation STRDS.
threshold=integer
    Basin threshold value
    Default: 10000
depth=float
    Inundation depth (single output)
start_water_level=float
    Start water level for flooding simulation
end_water_level=float
    End water level for flooding simulation
water_level_step=float
    Step increment for water level in flooding simulation
    Default: 1
memory=memory in MB
    Maximum memory to be used (in MB)
    Cache size for raster rows
    Default: 300
-t
    Generate inundation raster maps for a series of water levels
-m
    Use memory swap (operation is slow)
--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

elevation : str, required
    Name of input elevation raster map
    Used as: input, raster, name
streams : str, optional
    Stream raster map
    Name of the stream raster map
    Used as: input, raster, name
direction : str, optional
    Flow direction raster map
    Name of the flow direction raster map
    Used as: input, raster, name
inundation_raster : str, optional
    Name of the output inundation raster map
    Used as: output, raster, name
hand : str, optional
    Height above nearest drainage raster map
    Name of the output HAND raster map
    Used as: output, raster, name
inundation_strds : str, optional
    Name of the output inundation STRDS.
    Used as: output, strds, name
threshold : int, optional
    Basin threshold value
    Default: 10000
depth : float, optional
    Inundation depth (single output)
start_water_level : float, optional
    Start water level for flooding simulation
end_water_level : float, optional
    End water level for flooding simulation
water_level_step : float, optional
    Step increment for water level in flooding simulation
    Default: 1
memory : int, optional
    Maximum memory to be used (in MB)
    Cache size for raster rows
    Used as: memory in MB
    Default: 300
flags : str, optional
    Allowed values: t, m
    t
        Generate inundation raster maps for a series of water levels
    m
        Use memory swap (operation is slow)
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

r.hand - Height Above Nearest Drainage (HAND) is a terrain-based model that computes the height of the terrain above the nearest stream using a digital elevation model (DEM) Nobre et al., 2011. The HAND method is widely used for hydrological analysis, particularly for estimating flood inundation extents based on user-defined water levels.

The tool generates flood inundation extent maps by applying the HAND method to a DEM. Users can optionally provide streams and flow direction raster maps to improve processing efficiency and accuracy. The tool will return an inundation raster map or time series (STRDS) of inundation raster maps based on user-defined water levels. Additionally, the HAND raster map can be returned as an output if desired by setting the difference parameter.

Dependencies

GRASS Addons

EXAMPLES

Calculate an inundation raster map from a DEM raster map

r.hand elevation=elevation hand=hand depth=2 inundation_raster=inundation

Inundation event 2 m
Figure: Inundation event $2 m$.

Calculate series of inundation raster maps from a DEM raster map

r.hand -t elevation=elevation hand=hand inundation_strds=inundation_strds \
start_water_level=0 end_water_level=5 water_level_step=1

Output HAND raster in addition to inundation raster(s)

r.hand elevation=elevation hand=hand depth=4 threshold=5000 \
inundation_raster=inundation

The HAND raster is classified according to Nobre et al (2011) where:

HAND Range Classification
0 < HAND < 5 m Surface Water Table
5 < HAND < 15 m Shallow Water Table
HAND > 15 m Deep Water Table

r.hand HAND example Figure: Height Above Nearest Drainage (HAND)

# Reclassify HAND raster into categories
r.reclass input=hand output=hand_reclass rules=- << EOF
-30000 thru 0 = NULL
1 thru 5 = 1 Surface
5 thru 15 = 2 Shallow
15 thru 30000 = 3 Deep
EOF

# Set color table for HAND raster
r.colors map=hand_reclass rules=- << EOF
1 #1d91c0
2 #41ab5d
3 #ec7014
nv white
default grey
EOF

r.hand HAND classification example Figure: Height Above Nearest Drainage (HAND) water table classification.

REFERENCES

  • Nobre, A.D., Cuartas, L.A., Hodnett, M., Rennó, C.D., Rodrigues, G., Silveira, A., Waterloo, M., Saleska, S., 2011. Height Above the Nearest Drainage – a hydrologically relevant new terrain model. Journal of Hydrology 404, 13–29. https://doi.org/10.1016/j.jhydrol.2011.03.051

SEE ALSO

r.watershed, r.lake, r.lake.series

AUTHORS

Corey T. White OpenPlains Inc.

SOURCE CODE

Available at: r.hand source code (history)
Latest change: Tuesday Mar 04 09:58:40 2025 in commit 66645d6