r3.flow(1grass)

💖 r3.flow — the GRASS User's Manual glow-up 💖

okay bestie, gather round, because this is r3.flow from the GRASS User's Manual and it is lowkey a whole vibe. It computes 3D flow lines and 3D flow accumulation. That's it, that's the icon.

---

✨ NAME ✨

r3.flow — Computes 3D flow lines and 3D flow accumulation.

---

🏷️ KEYWORDS 🏷️

raster3d, hydrology, voxel

---

🌈 SYNOPSIS 🌈

r3.flow
r3.flow --help
r3.flow [-a]  [input=name]   [vector_field=name[,name,...]]
[seed_points=name]   [flowline=name]   [flowaccumulation=name]
[sampled=name]   [unit=string]   [step=float]   [limit=integer]
[max_error=float]   [skip=integer[,integer,...]]   [direction=string]
[--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

🎀 Flags 🎀

• -a — Create and fill attribute table
• --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 🫶

• input=name — Name of input 3D raster map
• vector_field=name[,name,...] — Names of three 3D raster maps describing x, y, z components of vector field
• seed_points=name — Name of vector map with points from which flow lines are generated. If no map is provided, flow lines are generated from each cell of the input 3D raster
• flowline=name — Name for vector map of flow lines
• flowaccumulation=name — Name for output flowaccumulation 3D raster
• sampled=name — Name for 3D raster sampled by flowlines. Values of this 3D raster will be stored as attributes of flowlines segments
• unit=string — Unit of integration step. Default unit is cell. Options: time, length, cell. Default: cell
  • time: elapsed time
  • length: length in map units
  • cell: length in cells (voxels)
• step=float — Integration step in selected unit. Default step is 0.25 cell. Default: 0.25
• limit=integer — Maximum number of steps. Default: 2000
• max_error=float — Maximum error of integration. Influences step, increase maximum error to allow bigger steps. Default: 1e-5
• skip=integer[,integer,...] — Number of cells between flow lines in x, y and z direction
• direction=string — Compute flowlines upstream, downstream or in both direction. Options: up, down, both. Default: down

---

💅 DESCRIPTION 💅

So the module r3.flow computes 3D flow lines and 3D flow accumulation, like a dual-threat queen. It'll take either three 3D raster maps that represent the vector field, or just one single 3D raster map. And if you hand it only one map? It computes the gradient field on-the-fly, no biggie, main character energy.

🦋 Flow lines 🦋

Flow lines get computed either from points (aka seeds) that you give it in the seed_points vector map — or, if there are literally no seeds, it just makes its own seeds in a regular grid at the center of voxels (which are the 3D raster cells, iykyk). The skip parameter is what controls the spacing between those regularly distributed seeds. And if you don't provide skip, r3.flow decides the optimal skip for each dimension based on the current 3D region, taking one tenth of the number of columns, rows, and depths. Flow lines can be computed going upstream (in the direction of the gradient or vector field), downstream, or in both directions. Versatile. ✨

🌸 Flow accumulation 🌸

Flow accumulation is computed as the number of flow lines traversing each voxel. Heads up though: since the flow lines are computed for each voxel, this computation can be more demanding. The skip parameter does not influence the flow accumulation computation, but the direction parameter does.

⭐ Flow line integration ⭐

Flow line integration can be influenced by several parameters. The option step controls the integration step and influences both the precision and the computational time. The unit of step can be defined either in terms of the size of the voxel (3D raster cell), as length in map units, or as elapsed time. The option limit specifies the maximum number of steps for each flow line.

💜 Attributes 💜

Without using flag a, no attribute table gets created, and each flow line is represented by one vector line with one category. With the a flag, an attribute table is created and each category (record) represents one segment of a flowline, so attributes specific for segments can be written. In the case of vector_field input, only velocity is written; in the case of the input option, values of the input 3D raster are written too. The option sampled lets you sample (query) a given 3D raster with flow lines (computed from a different 3D raster) and write the values of that given 3D raster as attributes of the flow line segments. Note that using the a flag results in longer computation time, so consider increasing the step and max_error parameters.

💀 fr fr, flag a = slower. Budget your time accordingly, bestie.

---

📝 NOTES 📝

r3.flow uses Runge-Kutta with adaptive step size (Cash-Karp method). Nerd shit and we love her for it. 🔥

---

🍓 EXAMPLES 🍓

First we create input data using example 1 from the r3.gwflow manual page:

# set the region accordingly
g.region res=25 res3=25 t=100 b=0 n=1000 s=0 w=0 e=1000 -p3
# now create the input raster maps for a confined aquifer
r3.mapcalc expression="phead = if(row() == 1 && depth() == 4, 50, 40)"
r3.mapcalc expression="status = if(row() == 1 && depth() == 4, 2, 1)"
r3.mapcalc expression="well = if(row() == 20 && col() == 20 && depth() == 2, -0.25, 0)"
r3.mapcalc expression="hydcond = 0.00025"
r3.mapcalc expression="syield = 0.0001"
r.mapcalc  expression="recharge = 0.0"
r3.gwflow solver=cg phead=phead status=status hc_x=hydcond hc_y=hydcond  \
   hc_z=hydcond q=well s=syield r=recharge output=gwresult dt=8640000 vx=vx vy=vy vz=vz budget=budget

Then we compute flow lines in both directions and downstream flowaccumulation.

r3.flow vector_field=vx,vy,vz flowline=gw_flowlines skip=5,5,2 direction=both
r3.flow vector_field=vx,vy,vz flowaccumulation=gw_flowacc

We can visualize the result in 3D view:

We can store velocity values (and values of the input 3D raster map if we use option input) for each segment of flow line in an attribute table.

r3.flow -a vector_field=vx,vy,vz flowline=gw_flowlines skip=5,5,2 direction=both
v.colors map=flowlines_color@user1 use=attr column=velocity color=bcyr

Again, we visualize the result in 3D view and we check 'use color for thematic rendering' on 3D view vector page.

---

👀 SEE ALSO 👀

r.flow, r3.gradient, r3.gwflow

---

👑 AUTHOR 👑

Anna Petrasova, NCSU GeoForAll Lab, developed during GSoC 2014.

---

🧚 SOURCE CODE 🧚

Available at: r3.flow source code (history)

Latest change: Monday Nov 03 07:16:48 2025 in commit: c96796774942e46bbababcd652d3986d4e295665

Main index | 3D raster index | Topics index | Keywords index | Graphical index | Full index

---

okay that's the whole thing, we ate and left no crumbs 🎀

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual — and this whole masterpiece is living in GRASS 8.5.0, babes. bye bestie, go make some flow lines 💖✨🦋