r.lake(1grass)

🌊 r.lake — GRASS User's Manual, but make it a group chat 💖

okay so bestie, pull up a chair (or a beanbag, whatever) because we're talking about r.lake, and it's literally the moment. It's a GRASS module. It's one of those 1grass ones. It's giving hydrology. It's giving flood. It's giving iconic.

---

✨ NAME ✨

r.lake — fills lake at given point to given level. 🫶

🏷️ KEYWORDS 🏷️

raster, hydrology, hazard, flood — the whole vibe check passes, no notes. 💅

📜 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 to why, bestie, hold on.
• -o — overwrite the seed map with the result (lake) map. spicy, but legal. 🔥
• --overwrite — allow output files to overwrite existing files (the classic).
• --help — print usage summary. your bestie when you're lost. 🥺
• --verbose — verbose module output. it will tell you Everything.
• --quiet — quiet module output. it will tell you Nothing. the duality.
• --ui — force launching GUI dialog. for the visual girlies. ✨

🎀 Parameters 🎀

• elevation=name [required] — name of input elevation raster map. mandatory, bestie, no skipping. ⭐
• water_level=float [required] — water level. also mandatory. also in DEM units, jsyk.
• lake=name — name for output raster map.
• coordinates=east,north — seed point coordinates. either this coordinates pair or a seed map have to be specified — pick one, you can't have both vibes at once. 🌸
• seed=name — input raster map with given starting point(s) (at least 1 cell > 0). either this parameter or a coordinates pair have to be specified. same deal. 💜

---

💧 DESCRIPTION 💧

So r.lake fills a lake to a target water level, starting from a given start point. The way that the user can think of it as r.grow with additional checks for elevation — like r.grow but with trust issues and a level requirement. 😭

The resulting raster map contains cells with values representing lake depth, and NULL for all other cells beyond the lake. Lake depth is reported relative to the specified water level (specified level = 0 depth). So the water level is like your zero line. clock it. 👑

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. periodt.

---

📝 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 specified as a coordinate pair, an additional check is done to make sure that the target water level is above the level of the DEM. When a raster map is used as a seed, however, no such checks are done. 🙈 Specifying a target water level below the surface represented by DEM will result in an empty map (sad, and also literally nothing in it). 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. the continuity of it all ✨

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 user can use the -o flag to create animations of rising water level without producing a separate map for each frame. An initial seed map must be created to start the sequence, and will be overwritten during subsequent runs with resulting water levels maps (i.e., a single file serves for both input and output). one file doing both jobs? main character energy. 💅

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

🧮 r.mapcalc equivalent - for GRASS hackers 🧮

This module was initially created as a script using r.mapcalc. This had some limitations — it was slow and no checks where done to find out 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 DEM map name, and ${wlevel} with 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. the patience of it honestly 🧚

---

🚨 KNOWN ISSUES 🚨

bestie. read these. they are not cute. they are just true. 😭

• The entire map is loaded into RAM. all of it. in your memory. be aware. 💀
• 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. (so the negative thing is a one-way trip, lowkey.)

---

🌊 EXAMPLE 🌊

Example of 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). ate, honestly. 🍓

---

🔗 SEE ALSO 🔗

r.mapcalc, r.grow, r.plane — the friend group. 🫶

👑 AUTHOR 👑

Maris Nartiss (maris.nartiss gmail.com). thank you for your service. 🎀

💻 SOURCE CODE 💻

Available at: r.lake source code (history)

Latest change: Tuesday Feb 18 17:20:26 2025 in commit: 688e625e7db3be9a465ce99ba25f36d2ebdd5aeb

Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

---

okay so that's the whole thing, and now the cute sign-off because you made it to the end: this was the GRASS 8.5.0 Reference Manual, © 2003-2026 GRASS Development Team, brought to you by GRASS 8.5.0 and that Feb 18 2025 energy. slay, stay flooded, hydrate (ironically), bye bestie 💖✨🌊