r.lake(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💧 r.lake(1) — the GRASS GIS User's Manual page, but make it cute 💧

okay bestie, gather round, because this is the manual page for r.lake(1) from the GRASS GIS User's Manual and she is serving hydrology.

KEYWORDS: raster, hydrology, hazard, flood 🌊

✨ NAME ✨

r.lake — fills a lake at a given point up to a given level. that's it, that's the whole job, and she does it flawlessly 💅

🎀 SYNOPSIS 🎀

r.lake
r.lake --help
r.lake [-no] elevation=name water_level=float  [lake=name]
[coordinates=east,north]   [seed=name]   [--overwrite]  [--help]
[--verbose]  [--quiet]  [--ui]

🚩 Flags

  • -n — use negative depth values for the lake raster map (yes, negative, we'll get into why, it's giving NVIZ visuals)
  • -o — overwrite the seed map with the result (lake) map. one map, doing double duty, main character energy
  • --overwrite — allow output files to overwrite files that already exist
  • --help — print the usage summary
  • --verbose — verbose module output, for when you want the tea ☕
  • --quiet — quiet module output, for when you don't
  • --ui — force launching the GUI dialog

🌸 Parameters

  • elevation=name [required] — name of the input elevation raster map
  • water_level=float [required] — the water level
  • lake=name — name for the output raster map
  • coordinates=east,north — seed point coordinates. either this coordinates pair or a seed map has to be specified, no skipping 🫶
  • seed=name — input raster map with the given starting point(s) (at least 1 cell > 0). either this parameter or a coordinates pair has to be specified

💖 DESCRIPTION 💖

r.lake fills a lake up to a target water level starting from a given start point. think of it as r.grow but with extra elevation checks, like r.grow's responsible older sister. the resulting raster map contains cells whose values represent lake depth, and NULL for every other cell beyond the lake. and the depth is reported relative to the specified water level, meaning the specified level = 0 depth. iconic behaviour, honestly.

this module uses a 3x3 moving window approach to find all cells that match three criteria and to define the lake:

  • cells are below the specified elevation (i.e., water level);
  • cells are connected with an initial cell (seed or coordinates pair value);
  • cells are not NULL or masked.

the water level must be in DEM units. no cap.

📝 NOTES 📝

the seed (starting) point can be a raster map with at least one cell value greater than zero, or a seed point can be specified as an E, N coordinate pair. if the seed is given as a coordinate pair, an extra check gets run to make sure the target water level is above the level of the DEM. but when a raster map is used as the seed? no such checks, bestie, none, zero, nada. specifying a target water level below the surface represented by the DEM will result in an empty map. 🙈

note: a raster lake map created in a previous run can also be used as a seed map for a new run, to simulate rising water levels. yes, the map is its own glow-up arc.

the module will create a new map (lake=foo) or can be set to replace the input (seed=bar) map if the -o flag is used. the -o flag lets you make animations of rising water level without producing a separate map for each frame — you just need an initial seed map to start the sequence, and it gets overwritten during subsequent runs with the resulting water level maps (so a single file serves as both input and output, she's versatile like that). ✨

negative output (the -n flag) is useful for visualisations in NVIZ. it equals the mapcalc expression "negative = 0 - positive".

🧮 r.mapcalc equivalent — for GRASS hackers

this module was initially created as a script using r.mapcalc. that had some limitations — it was slow, and no checks were done to find out the required iteration count. the shell script code (using r.mapcalc) used in the original script is shown below:

${seedmap} = if( ${dem}, \
if( if( isnull(${seedmap}),0,${seedmap} > 0), ${wlevel}-${dem}, \
 if( \
  if(isnull(${seedmap}[-1,0]),0, ${seedmap}[-1,0] > 0 && ${wlevel} > ${dem}) ||\
  if(isnull(${seedmap}[-1,1]),0, ${seedmap}[-1,1] > 0 && ${wlevel} > ${dem}) ||\
  if(isnull(${seedmap}[0,1]), 0, ${seedmap}[0,1] > 0  && ${wlevel} > ${dem}) ||\
  if(isnull(${seedmap}[1,1]), 0, ${seedmap}[1,1] > 0  && ${wlevel} > ${dem}) ||\
  if(isnull(${seedmap}[1,0]), 0, ${seedmap}[1,0] > 0  && ${wlevel} > ${dem}) ||\
  if(isnull(${seedmap}[1,-1]),0, ${seedmap}[1,-1] > 0 && ${wlevel} > ${dem}) ||\
  if(isnull(${seedmap}[0,-1]),0, ${seedmap}[0,-1] > 0  && ${wlevel} > ${dem}) ||\
  if(isnull(${seedmap}[-1,-1]),0, ${seedmap}[-1,-1] > 0  && ${wlevel} > ${dem}),\
 ${wlevel}-${dem}, null() )))

the ${seedmap} variable is replaced by seed map names, ${dem} with the DEM map name, and ${wlevel} with the target water level. to get a single water level, this code block is called with the same level numerous times (in a loop), because the lake grows by single cells during a single run. slay, but slowly.

💀 KNOWN ISSUES 💀

  • the entire map is loaded into RAM. the entire map. she's hungry.
  • a completely negative seed map will not work! at least one cell must have a value > 0. output from r.lake -n cannot be used as input in the next run. periodt.

🌈 EXAMPLE 🌈

example of a small flooding along a street (North Carolina sample dataset):

g.region raster=elev_lid792_1m -p
# water accumulation next to street dam
r.lake elev_lid792_1m coordinates=638759.3,220264.1 water_level=113.4 lake=flooding
# draw resulting lake map over shaded terrain map
r.relief input=elev_lid792_1m output=elev_lid792_1m_shade
d.rast elev_lid792_1m_shade
d.rast flooding
d.vect streets_wake

small flooding along a street (r.lake, using Lidar 1m DEM) 🦋

👀 SEE ALSO 👀

r.mapcalc, r.grow, r.plane

👑 AUTHOR 👑

Maris Nartiss (maris.nartiss gmail.com)

🧚 SOURCE CODE 🧚

available at: r.lake source code (history)

accessed: Saturday Jan 17 05:40:49 2026

main index | raster index | topics index | keywords index | graphical index | full index

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual

okay that's the whole page bestie, you're officially a lake-filling expert, no notes, 10/10, go flood a street (responsibly). this was GRASS 8.4.2, r.lake(1), dated Saturday Jan 17 05:40:49 2026, © 2003-2025 GRASS Development Team — mwah 💖

📦 where this page comes from