Home

:: HYDROLOGICAL TERRAIN ANALYSIS

A high-performance library for processing massive Digital Elevation Models.

Alpha Software

This software is currently in alpha status. While functional, it may contain bugs, have incomplete features, and undergo breaking changes. Use in production environments at your own risk. We welcome feedback and bug reports on our GitHub Issues page.

Why Overflow?¶

Traditional hydrological tools are often single-threaded and rely on virtual-memory tiling (swapping memory to disk) to handle large datasets. This creates inefficient I/O patterns with no garuntees on how many times the same tile may be swapped into and out of memory. Given the wide availability of multi-core processors in modern computers and the increasing size of raster datasets used for hydrological analysis, existing tools are not well-suited for efficient processing of large-scale terrain data today. Overflow was developed to provide a modern solution for large-scale hydrological terrain analysis.

Every workflow in Overflow is designed for parallel execution using Numba JIT-compiled algorithms. This is achieved through state-of-the-art tiled, topological approaches that implement efficient IO access patterns even for global operations. Processes in Overflow are guaranteed to complete in a fixed number of passes over the data regardless of the dataset size.

Core Hydrological Processes¶

Overflow provides a complete toolchain for deriving hydrographic features from raw elevation data. The core algorithms implemented in Overflow include:

01 // CONDITIONING

Breach Carve paths through barriers
Fill Fill surface depressions

02 // ROUTING

Flow Direction Determine steepest descent
Accumulation Calculate contributing area

03 // EXTRACTION

Streams Vectorize stream network
Basins Delineate watersheds
Flow Length Longest Upstream Path

Python API¶

Overflow is available as a standard Python package making it accessible for integration into geospatial workflows leveraging Python's ecosystem.

import overflow

overflow.breach(...)
overflow.fill(...)
overflow.flow_direction(...)
overflow.accumulation(...)
overflow.streams(...)
overflow.basins(...)
overflow.flow_length(...)

Command Line Interface (CLI)¶

For batch processing and server environments, Overflow provides a robust CLI. It supports all core algorithms and provides a single command to run the complete processing pipeline end-to-end.

Available commands:

overflow breach - Breach pits using least-cost paths
overflow fill - Fill depressions in a DEM
overflow flow-direction - Compute D8 flow directions (with flat resolution)
overflow accumulation - Calculate flow accumulation
overflow streams - Extract stream networks
overflow basins - Delineate drainage basins
overflow flow-length - Calculate upstream flow length (longest flow path)
overflow pipeline - Run complete DEM processing workflow

The pipeline command orchestrates the full sequence of conditioning, flow direction, accumulation, and vector extraction in a single execution.

overflow pipeline \
    --dem_file raw_dem.tif \
    --output_dir ./results

Docker Support¶

To ensure reproducibility and eliminate complex dependency management (specifically GDAL and system libraries), Overflow is distributed with an official Docker image.

The image is built on top of the official osgeo/gdal Ubuntu-based images, ensuring binary compatibility with the underlying geospatial libraries.