r3.flow(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

💖 NAME 💖

okay so bestie, this is r3.flow(1) from the GRASS GIS User's Manual, and it is literally the moment your 3D raster data learns to move. It computes 3D flow lines and 3D flow accumulation. that's it, that's the whole vibe. 💫

🎀 KEYWORDS 🎀

raster3d, hydrology, voxel — yeah, the science-y trifecta, slay.

✨ 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 an attribute table. yes queen, give me the extra data 💅
  • --overwrite — let output files overwrite files that already exist. use responsibly bestie, no cap
  • --help — print the usage summary
  • --verbose — verbose module output (she's chatty)
  • --quiet — quiet module output (she's mysterious)
  • --ui — force launching the GUI dialog

🦋 Parameters 🦋

  • input=name — name of the input 3D raster map
  • vector_field=name[,name,...] — names of three 3D raster maps describing the x, y, z components of the vector field
  • seed_points=name — name of a vector map with points from which flow lines are generated. if you don't hand her a map, flow lines get generated from each cell of the input 3D raster
  • flowline=name — name for the vector map of flow lines
  • flowaccumulation=name — name for the output flowaccumulation 3D raster
  • sampled=name — name for a 3D raster sampled by flowlines. values of this 3D raster get stored as attributes of the flowline segments 🫶
  • unit=string — unit of the 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 the 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, so increase the maximum error if you wanna 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 directions.
    • Options: up, down, both
    • Default: down

💜 DESCRIPTION 💜

Module r3.flow computes 3D flow lines and 3D flow accumulation. She's flexible like that: she accepts either three 3D raster maps representing the vector field, or just one 3D raster map. and if you give her only one? she computes the gradient field on-the-fly, no prep needed, main character energy fr fr. 🔥

🌈 Flow lines

Flow lines are computed either from points (seeds) provided in the seed_points vector map, or — if there are no seeds — she creates seeds in a regular grid in the center of voxels (3D raster cells). Parameter skip then controls the step between the regularly distributed seeds. If skip isn't provided, 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 in upstream direction (in the direction of the gradient or vector field), in downstream direction, or in both directions. both is for the overachievers 💅

💧 Flow accumulation

Flow accumulation is computed as the number of flow lines traversing each voxel. and because the flow lines are computed for each voxel, the flow accumulation computation can be more demanding — she's doing the most, literally. Parameter skip does not influence the flow accumulation computation, but parameter direction does. noted. 📝

⭐ Flow line integration

Flow line integration can be influenced by several parameters. Option step controls the integration step and influences 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), length in map units, or as elapsed time. Option limit specifies the maximum number of steps of each flow line.

🎀 Attributes

Without using flag -a, no attribute table is created and each flow line is represented by one vector line with one category. With the flag, an attribute table is created and each category (record) represents one segment of a flowline, so that attributes specific for segments can be written. In case of vector_field input, only velocity is written; in case of the input option, values of the input 3D raster are written too. Option sampled allows sampling (querying) a given 3D raster by flow lines (computed from a different 3D raster) and writing the values of the given 3D raster as attributes of the flow line segments. 🫶

heads up bestie: using the flag -a results in longer computation time, so consider increasing the step and max_error parameters. don't say I didn't warn you 😭

🧚 NOTES 🧚

r3.flow uses Runge-Kutta with adaptive step size (Cash-Karp method). fancy? yes. iconic? also yes. 👑

🔥 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. queen behavior, honestly 👑

💅 SOURCE CODE 💅

Available at: r3.flow source code (history)

Accessed: Saturday Jan 17 05:41:16 2026

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

and that's a wrap bestie 💫 this whole thing came out of GRASS 8.4.2, from the GRASS GIS 8.4.2 Reference Manual, © 2003-2025 GRASS Development Team, and this lil page was last looked at on Saturday Jan 17 05:41:16 2026. go make some flow lines, you've got this 🫶✨

📦 where this page comes from