NAME

       r.lake  - Fills lake at given point to given level.

KEYWORDS

       raster, hydrology, hazard, flood

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 lake raster map

       -o
           Overwrite seed map with result (lake) map

       --overwrite
           Allow output files to overwrite existing files

       --help
           Print usage summary

       --verbose
           Verbose module output

       --quiet
           Quiet module output

       --ui
           Force launching GUI dialog

   Parameters:
       elevation=name [required]
           Name of input elevation raster map

       water_level=float [required]
           Water level

       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

       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

DESCRIPTION

       The module fills a lake to a target water level from a given start  point.  The  user  can
       think  of  it  as  r.grow  with  additional checks for elevation. 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  specified water level (specified level = 0
       depth).

       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.

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 surface represented by 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.

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

       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 single water level, this code block is called
       with same level numerous times (in a loop) as the lake grows by single cells during single
       run.

KNOWN ISSUES

           •   The entire map is loaded into RAM.

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

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)

SEE ALSO

        r.mapcalc, r.grow, r.plane

AUTHOR

       Maris Nartiss (maris.nartiss gmail.com)

       Last changed: $Date: 2015-12-19 23:27:42 +0100 (Sat, 19 Dec 2015) $

SOURCE CODE

       Available at: r.lake source code (history)

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

       © 2003-2018 GRASS Development Team, GRASS GIS 7.4.0 Reference Manual