RivGraph is a Python package for converting a binary mask of a channel network into a directed, weighted graph of connected links and nodes. It is designed for river and delta channel networks derived from remote sensing imagery and geospatial masks.
- morphologic metrics such as widths, lengths, and branching characteristics
- graph-based and algebraic representations of channel networks
- topologic and dynamic metrics such as alternative paths, flux sharing, and entropy-based measures
- tools for cleaning and preparing binary channel masks
- island detection, metrics, and filtering
- mesh generation for along-river analysis
- geospatial export of links, nodes, rasters, and derived products
RivGraph preserves georeferencing information throughout the workflow. If you start with a georeferenced mask, exported rasters and vectors remain aligned with the source data and can be used directly in GIS workflows.
The flow-directionality logic and validation are described in our ESurf Dynamics paper. General package usage is described in our JOSS paper.
Start with the documentation and the notebooks in examples/. RivGraph contains two primary classes, delta and river, that organize the main processing workflows. These notebooks show the end-to-end usage patterns:
examples/delta_example.ipynbexamples/braided_river_example.ipynbexamples/mouse_brain_example.ipynb
RivGraph was initially released before the advent of LLMs and thus v0.5.0 was written entirely without AI assistance. However, the v1.0 release was made possible through efficiencies provided by relying heavily on AI coding (mainly OpenAI tools).
Bug reports, documentation improvements, and pull requests are welcome. The easiest way to start is to open an issue in the tracker.
If you use RivGraph in your research, please consider citing it.
If you use RivGraph's flow-directionality algorithms, please cite our ESurf Dynamics paper.
If you use RivGraph's flux paritioning scheme that asssumes steady-state, width-weighted fluxes at junctions, you should be aware of this work.
RivGraph is distributed under the BSD 3-clause license.