Stream Extraction¶

Purpose¶

Stream extraction converts accumulation-defined stream cells into vector line features. Cells exceeding accumulation threshold are classified as streams, vectorized into polylines, and written with junction points to GeoPackage output.

Parameters¶

fac_path¶

Path to flow accumulation raster. GDAL-readable format. Single band. Int64 data type. Values represent upstream cell count. Nodata values (-1) excluded from stream classification.

fdr_path¶

Path to flow direction raster. GDAL-readable format. Single band. UInt8 data type. Values 0-7 represent valid flow directions. Required for tracing stream connectivity and determining junction locations.

output_dir¶

Directory for output files. Must exist, the function does not create the directory. Writes streams.gpkg containing two layers: streams (LineString geometries) and junctions (Point geometries). Overwrites existing file.

threshold¶

Minimum accumulation value for stream classification. Cells with \(\text{accumulation} \geq \text{threshold}\) become stream cells. Controls stream network density. Lower values extract tributaries, higher values extract main channels only.

chunk_size¶

Tile dimension in pixels. Default 2048. Set to 0 or 1 for in-memory processing.

progress_callback¶

Optional callback for monitoring long operations. See ProgressCallback API.

CLI Usage¶

overflow streams \
    --fac accum.tif \
    --fdr fdr.tif \
    --output streams_output \
    --threshold 100

Python API Usage¶

import overflow

overflow.streams(
    fac_path="accum.tif",
    fdr_path="fdr.tif",
    output_dir="./output",
    threshold=100
)

The output streams.gpkg will contain two layers:

streams: The vectorized stream network of all cells with \(\text{accumulation} \geq \text{threshold}\). The vertices of the polylines will be at the grid cell centers.
junctions: Points at the downstream end of each reach and the upstream most points of the stream network.

Visualization¶

Input Flow Accumulation	Stream Classification Output

The input shows flow accumulation values with higher values (darker blue) indicating greater drainage area. The output shows binary stream classification where cells exceeding the threshold (8 in this example) are marked as streams (blue = 1) versus non-streams (gray = 0). The stream network follows the path of highest flow accumulation down the valley.

Input DEM	Streams Output