r.terraflow(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💖 r.terraflow 💖

okay bestie, welcome to the GRASS GIS User's Manual page for r.terraflow, and no cap this one is a whole main character. ✨

🌊 NAME 🌊

r.terraflow — performs flow computation for massive grids. yes literally MASSIVE. like, grids so big they'd make other tools cry. 🫶

🏷️ KEYWORDS 🏷️

raster, hydrology, flow, accumulation, sink 💧

✨ SYNOPSIS ✨

r.terraflow
r.terraflow --help
r.terraflow [-s] elevation=name  [filled=name]   [direction=name]
[swatershed=name]   [accumulation=name]   [tci=name]   [d8cut=float]
[memory=memory in MB]   [directory=string]   [stats=string]
[--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

🎀 Flags 🎀

  • -s — SFD (D8) flow, when the default is MFD. quick translation: SFD = single flow direction, MFD = multiple flow direction. 💅
  • --overwrite — lets your output files just. overwrite files that already exist. permission granted bestie 👑
  • --help — prints the usage summary, the lil cheat sheet 🧚
  • --verbose — verbose module output, so it tells you everything it's doing 💬
  • --quiet — quiet module output, so it tells you nothing and minds its business 🙈
  • --ui — force launching the GUI dialog 🖥️

🌸 Parameters 🌸

  • elevation=name [required] — the name of your input elevation raster map. you literally cannot skip this one, it's the whole point 🍓
  • filled=name — name for the output filled (flooded) elevation raster map 🌊
  • direction=name — name for the output flow direction raster map 🧭
  • swatershed=name — name for the output sink-watershed raster map 🕳️
  • accumulation=name — name for the output flow accumulation raster map 💧
  • tci=name — name for the output topographic convergence index (tci) raster map 📐
  • d8cut=float — routing using SFD (D8) direction. if flow accumulation is larger than this value, it gets routed using the SFD (D8) direction (meaningful only for MFD flow). if no answer is given it defaults to infinity. ♾️
  • memory=memory in MB — maximum memory to be used (in MB), a.k.a. cache size for raster rows. default: 300 🧠
  • directory=string — directory to hold temporary files (they can be large). and bestie, when it says large? it means LARGE. 💀
  • stats=string — name for the output file containing runtime statistics 📊

💜 DESCRIPTION 💜

so r.terraflow takes a raster digital elevation model (DEM) as input and computes the flow direction raster and the flow accumulation raster, plus the flooded elevation raster, the sink-watershed raster (which partitions everything into watersheds around sinks) and the TCI (topographic convergence index) raster maps. like. that's a lot of rasters. we love a multitasker 🫶✨

r.terraflow computes all these rasters using well-known approaches, but with one twist: its whole vibe is computational complexity of the algorithms, not modeling realistic flow. r.terraflow emerged from the necessity of having scalable software able to process very large terrains efficiently. it's based on theoretically optimal algorithms developed in the framework of I/O-efficient algorithms, and r.terraflow was designed and optimized especially for massive grids. it can process terrains that were straight-up impractical with similar functions in other GIS systems. not to be dramatic but it ate. 💅

Flow directions get computed using either the MFD (Multiple Flow Direction) model or the SFD (Single Flow Direction, or D8) model, illustrated below. both methods compute downslope flow directions by inspecting the 3-by-3 window around the current cell. the SFD method assigns a unique flow direction towards the steepest downslope neighbor. the MFD method assigns multiple flow directions towards all downslope neighbors.

🖼️ Flow direction to steepest downslope neighbor (SFD).      Flow direction to all downslope neighbors (MFD).

here's the tea though: the SFD and the MFD method cannot compute flow directions for cells which have the same height as all their neighbors (flat areas), or cells which don't have downslope neighbors (one-cell pits). 😭

  • On plateaus (flat areas that spill out) r.terraflow routes flow so that globally the flow goes towards the spill cells of the plateaus. 🌈
  • On sinks (flat areas that do not spill out, including one-cell pits) r.terraflow assigns flow by flooding the terrain until all the sinks are filled, and assigning flow directions on the filled terrain. 🌊

in order to flood the terrain, r.terraflow identifies all sinks and partitions the terrain into sink-watersheds (a sink-watershed contains all the cells that flow into that sink), builds a graph representing the adjacency information of the sink-watersheds, and uses this sink-watershed graph to merge watersheds into each other along their lowest common boundary until all watersheds have a flow path outside the terrain. flooding produces a sink-less terrain in which every cell has a downslope flow path leading outside the terrain, and therefore every cell in the terrain can be assigned SFD/MFD flow directions as above. ✨

flow directions are encoded using powers of two clockwise starting from 20 for east to 27 for north-east.

🖼️ Flow direction encoding clockwise starting from 20 for east to 27 for north-east; 0 for undetermined (sinks) and 1 for undefined (null cells) (source)

once flow directions are computed for every cell in the terrain, r.terraflow computes flow accumulation by routing water using the flow directions and keeping track of how much water flows through each cell. 💧

if flow accumulation of a cell is larger than the value given by the d8cut option, then the flow of this cell is routed to its neighbors using the SFD (D8) model. this option affects only the flow accumulation raster and is meaningful only for MFD flow (i.e. if the -s flag is not used). if this option is used for SFD flow it is ignored. the default value of d8cut is infinity. ♾️

r.terraflow also computes the tci raster (topographic convergence index, defined as the logarithm of the ratio of flow accumulation and local slope). 📐

for more details on the algorithms see [1,2,3] below. 👇

📝 NOTES 📝

one of the techniques used by r.terraflow is the space-time trade-off. in particular, in order to avoid searches (which are I/O-expensive), r.terraflow computes and works with an augmented elevation raster in which each cell stores relevant information about its 8 neighbors, in total up to 80B per cell. as a result r.terraflow works with intermediate temporary files that may be up to 80N bytes, where N is the number of cells (rows x columns) in the elevation raster (more precisely, 80K bytes, where K is the number of valid (not no-data) cells in the input elevation raster). 🧮

all these intermediate temporary files are stored in the path specified by the directory option.

⚠️ note: directory must contain enough free disk space in order to store up to 2 x 80N bytes. bestie please check your disk first, this is not a drill 💀

the memory option can be used to set the maximum amount of main memory (RAM) the module will use during processing. in practice its value should be an underestimate of the amount of available (free) main memory on the machine. r.terraflow will use at all times at most this much memory, and the virtual memory system (swap space) will never be used. the default value is 300 MB. 🧠

the stats option defines the name of the file that contains the statistics (stats) of the run. 📊

r.terraflow has a limit on the number of rows and columns (max 32,767 each). 🚧

the internal type used by r.terraflow to store elevations can be defined at compile-time. by default, r.terraflow is compiled to store elevations internally as floats. other versions can be created by the user if needed. 🔧

hints concerning compilation with storage of elevations internally as shorts: such a version uses less space (up to 60B per cell, up to 60N intermediate file) and therefore is more space and time efficient. r.terraflow is intended for use with floating point raster data (FCELL), and r.terraflow (short) with integer raster data (CELL) in which the maximum elevation does not exceed the value of a short SHRT_MAX=32767 (this is not a constraint for any terrain data of the Earth, if elevation is stored in meters). both r.terraflow and r.terraflow (short) work with input elevation rasters which can be either integer, floating point or double (CELL, FCELL, DCELL). if the input raster contains a value that exceeds the allowed internal range (short for r.terraflow (short), float for r.terraflow), the program exits with a warning message. otherwise, if all values in the input elevation raster are in range, they will be converted (truncated) to the internal elevation type (short for r.terraflow (short), float for r.terraflow). in this case precision may be lost and artificial flat areas may be created. for instance, if r.terraflow (short) is used with floating point raster data (FCELL or DCELL), the values of the elevation will be truncated as shorts. this may create artificial flat areas, and the output of r.terraflow (short) may be less realistic than those of r.terraflow on floating point raster data. the outputs of r.terraflow (short) and r.terraflow are identical for integer raster data (CELL maps). 🧐

🌈 EXAMPLES 🌈

example for a small area in the North Carolina sample dataset to calculate flow accumulation:

g.region raster=elev_lid792_1m
r.terraflow elevation=elev_lid792_1m accumulation=elev_lid792_1m_accumulation
🖼️ Flow accumulation

Spearfish sample data set:

g.region raster=elevation.10m -p
r.terraflow elev=elevation.10m filled=elevation10m.filled \
    dir=elevation10m.mfdir swatershed=elevation10m.watershed \
    accumulation=elevation10m.accu tci=elevation10m.tci
g.region raster=elevation.10m -p
r.terraflow elev=elevation.10m filled=elevation10m.filled \
    dir=elevation10m.mfdir swatershed=elevation10m.watershed \
    accumulation=elevation10m.accu tci=elevation10m.tci d8cut=500 memory=800 \
    stats=elevation10mstats.txt

📚 REFERENCES 📚

  1. The TerraFlow project at Duke University
  2. I/O-efficient algorithms for problems on grid-based terrains. Lars Arge, Laura Toma, and Jeffrey S. Vitter. In Proc. Workshop on Algorithm Engineering and Experimentation, 2000. To appear in Journal of Experimental Algorithms.
  3. Flow computation on massive grids. Lars Arge, Jeffrey S. Chase, Patrick N. Halpin, Laura Toma, Jeffrey S. Vitter, Dean Urban and Rajiv Wickremesinghe. In Proc. ACM Symposium on Advances in Geographic Information Systems, 2001.
  4. Flow computation on massive grid terrains. Lars Arge, Jeffrey S. Chase, Patrick N. Halpin, Laura Toma, Jeffrey S. Vitter, Dean Urban and Rajiv Wickremesinghe. In GeoInformatica, International Journal on Advances of Computer Science for Geographic Information Systems, 7(4):283-313, December 2003.

👀 SEE ALSO 👀

r.flow, r.basins.fill, r.drain, r.topidx, r.topmodel, r.water.outlet, r.watershed

💖 AUTHORS 💖

Original version of program: The TerraFlow project, 1999, Duke University.

  • Lars Arge, Jeff Chase, Pat Halpin, Laura Toma, Dean Urban, Jeff Vitter, Rajiv Wickremesinghe.

Porting to GRASS GIS, 2002:

  • Lars Arge, Helena Mitasova, Laura Toma.

Contact: Laura Toma 🫶

✨ SOURCE CODE ✨

okay bestie, you wanna see the actual code? say less 💅 it's all out there for you:

  • available at: r.terraflow source code (history)
  • accessed: Saturday Jan 17 05:41:13 2026

and if you're lost in the docs (no judgement, we've all been there 🫶), here's the lil navigation squad:

  • Main index
  • Raster index
  • Topics index
  • Keywords index
  • Graphical index
  • Full index

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

ngl, this whole thing lives in the GRASS GIS 8.4.2 Reference Manual, and the page you just read got pulled up on Saturday Jan 17 05:41:13 2026. go hydrate, then go flow some terrains 💖✨🌈

that's the whole page, bestie — ate and left no crumbs 👑💅

📦 where this page comes from