Overflow
Warning: This software is currently in alpha status. While functional, it may contain bugs and undergo breaking changes. See the documentation for more details.
Overflow is a high-performance Python library for hydrological terrain analysis that specializes in processing massive Digital Elevation Models (DEMs) through parallel, tiled algorithms.
Overview
Overflow provides a complete toolchain for extracting hydrographic features from raw elevation data:
- Terrain Conditioning: Breach and fill depressions in DEMs
- Flow Routing: Calculate D8 flow direction with flat resolution and flow accumulation
- Feature Extraction: Extract stream networks, delineate basins, and compute flow lengths
Unlike traditional GIS tools that rely on virtual memory, Overflow uses sophisticated tiled algorithms with parallel processing to handle datasets of any size efficiently.
Key Features
- Highly Parallel: Every algorithm designed for parallel execution using Numba.
- Memory Efficient: Process DEMs larger than RAM through tiled algorithms with efficient I/O patterns.
- Scalable: Fixed number of passes over data regardless of size. Every operation is designed to scale from laptop-sized datasets to continental DEMs without requiring specialized hardware.
- Modern Algorithms: Implements state-of-the-art priority-flood filling, least-cost breaching, and flat resolution algorithms
Quick Start
Installation
# Create conda environment with system dependencies
conda create -n overflow python gdal -c conda-forge
conda activate overflow
# Install overflow from PyPI
pip install overflow-hydro
Basic Usage
Python API
import overflow
# Process a DEM through the complete pipeline
overflow.breach("input.tif", "breached.tif")
overflow.fill("breached.tif", "filled.tif")
overflow.flow_direction("filled.tif", "flowdir.tif")
overflow.accumulation("flowdir.tif", "flowacc.tif")
overflow.streams("flowacc.tif", "flowdir.tif", "streams/")
overflow.basins("flowdir.tif", "basins.tif")
Command Line Interface
# Run the complete pipeline
overflow pipeline \
--dem_file input.tif \
--output_dir ./results
# Or run individual steps
overflow breach input.tif breached.tif
overflow fill breached.tif filled.tif
overflow flow-direction filled.tif flowdir.tif
overflow accumulation flowdir.tif flowacc.tif
Docker
docker pull ghcr.io/fema-ffrd/overflow:latest
docker run -v $(pwd):/data ghcr.io/fema-ffrd/overflow:latest \
pipeline --dem_file /data/input.tif --output_dir /data/results
Documentation
For detailed documentation, algorithm descriptions, and API reference, visit:
https://fema-ffrd.github.io/overflow/
Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
- Documentation: https://fema-ffrd.github.io/overflow/
- Issues: GitHub Issues
1 maintainer
Metadata
1 maintainer
Release files for overflow-hydro 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| overflow_hydro-0.5.0.tar.gz | 124.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| overflow_hydro-0.5.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 273.6 kB
Release files / overflow_hydro-0.5.0.tar.gz
| Download URL | overflow_hydro-0.5.0.tar.gz |
|---|---|
| Size | 124.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c205c36514e89b1f00021e7155aff28c9817f1561bc074622e6bc5a3a2ee095e
|
|
BLAKE2b-256 checksum How to use checksums |
d625b5a2c1e57d08182fc18ea1a4ace70829869413f6f074dc6678dca827bec5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 29, 2026.
Transparency logRelease files / overflow_hydro-0.5.0-py3-none-any.whl
| Download URL | overflow_hydro-0.5.0-py3-none-any.whl |
|---|---|
| Size | 149.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
21d2b276ec4e22e5914b1110cd19870516d75e20b19a5925ef762ae17ec02d9f
|
|
BLAKE2b-256 checksum How to use checksums |
bf3394af471c69b88716f2a2a3457826913e8880e869f62d9290d6404f31cbae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 29, 2026.
Transparency log
