Flow Direction

Draft: written, not yet checked by a person Operation · flow-direction

For each cell of an elevation raster, the neighbour that water flows to, following the steepest descent (D8).

Pitfall. The same direction has a different code in each engine's encoding; reading one engine's output with another's codes sends water the wrong way.

Pitfall. Flat areas and sinks have no downhill neighbour; engines leave them nodata, 0, or resolve them in their own way.

About this operation
Also called	D8 flow direction, D8 pointer, flow pointer, drainage direction
Group	`raster/hydrology`
Checks	`raster.nodata`
Pitfalls	2 listed above
Columbus tool	Not stated
Notes	Not stated
Status	active
Broader	Not stated
Narrower	Not stated
Related	`flow-accumulation` `fill-sinks` `aspect`

Parameters

Name	Type	Required	Default	Values	Note
`encoding`	enum	no	`esri`	`esri, whitebox, grass, degrees`	esri: 1 E, 2 SE, 4 S, 8 SW, 16 W, 32 NW, 64 N, 128 NE. whitebox: 1 NE, 2 E, 4 SE, 8 S, 16 SW, 32 W, 64 NW, 128 N. grass (r.watershed): 1 to 8 counter-clockwise from NE, west 4. degrees (r.fill.dir): counter-clockwise from east, west 180.

Inputs and outputs

Direction	Name	Type	Geometry	Note
Input	`raster`	raster	Not stated	An elevation model, usually with sinks filled.
Output	`output`	raster	Not stated	Not stated

In each engine

Engine	Tool	Parameters	Differences
`grass`	`r.fill.dir`	`encoding` always degrees `raster` → `input` `output` → `direction`	Also writes the filled elevation (output, required; set by this mapping) and problem areas (areas). With format = grass (the default) directions are in degrees counter-clockwise from east (west is 180), not r.watershed's 1 to 8; format also offers the AGNPS and ANSWERS codings. Preset: `{"output":"filled"}`
`grass`	`r.watershed`	`encoding` always grass `raster` → `elevation` `output` → `drainage`	This mapping sets flags s (single flow direction) and a; negative codes mark cells that drain out of the region. Preset: `{"flag_s":true,"flag_a":true}`
`terra`	`terra::terrain`	`encoding` always esri `raster` → `x`	None noted Preset: `{"v":"flowdir"}`
`whiteboxtools`	`D8Pointer`	`encoding` → `esri_pntr` : esri = yes; whitebox = no. not supported: grass, degrees `raster` → `dem` `output` → `output`	Codes directions clockwise from north-east (1, 2, 4, ... 128) unless esri_pntr is set.
`xarray-spatial`	`xrspatial.hydro.flow_direction_d8`	`encoding` always esri `raster` → `agg`	Takes an xarray DataArray; edge cells are NaN by default (boundary = 'nan').