Give pourpoint a point on a river and it returns the whole upstream area that drains to it, the watershed.
pourpoint reads HFX, a folder of pre-built
river-network files in the open HydroFabric Exchange format. It finds the
catchment that contains the point, gathers every catchment upstream, and merges
them into one watershed polygon. The same engine works with any dataset in the
HFX format.
The Python wrapper pourpoint is published
on PyPI as a self-contained wheel with GDAL, PROJ, and GEOS bundled inside, so
no system installs are needed.
uv add pourpoint(or pip install pourpoint)
Prebuilt wheels are published for:
- macOS (Apple Silicon + Intel)
- Linux (x86_64 + aarch64)
- Windows (x86_64)
as macosx_11_0_arm64, macosx_11_0_x86_64, manylinux_2_28_x86_64, manylinux_2_28_aarch64, win_amd64.
See CONTRIBUTING.md for local builds.
import pourpoint
engine = pourpoint.Engine("/path/to/hfx/dataset")
result = engine.delineate(lat=47.3769, lon=8.5417)
print(result.area_km2) # geodesic area in km²
print(result.terminal_unit_id)
geojson = result.to_geojson()See crates/python/README.md for the Python
quickstart and crates/python/API.md for the full
developer API reference.
The prepared pourpoint 0.2.1 release consumes only
hfx.aux.d8_raster.v2 D8 auxiliaries. It supports EPSG:4326 and EPSG:8857 D8
rasters, performs declaration selection, carving, and snapping in the raster's
native CRS, and converts only the refined result back to EPSG:4326. Snap
thresholds expressed as cells remain cell counts; projected km2 thresholds
are compared using projected pixel area. Version 0.2.1 rejects v1 auxiliaries
and rejects km2 accumulation on EPSG:4326 rather than approximating angular
pixel area. For identical inputs, returned carve geometry is deterministic.
Version 0.2.1 also makes remote classic-TIFF and BigTIFF metadata and planned tile-index reads independent of the raster's total tile count, and decodes bounded owned DEFLATE chunks with predictor 1.
Pourpoint 0.2.0 shipped on 2026-07-24 under tag pourpoint-v0.2.0 and was
live-fired in production. Version 0.2.1 is now prepared and awaits its
human-cut tag and GitHub Release.
The carried projected-CRS evidence is in the projected-CRS terminal-refinement runbook. The current release-register entry point is the tile-count-independent planetary COG-read evidence register.
pourpoint accepts local HFX dataset folders and remote URLs to datasets hosted
online, for example on Amazon S3 or Cloudflare R2. The root must contain the
HFX artifacts described by the
manifest: manifest.json, catchments.parquet, and graph.parquet.
Optional snap and D8 raster artifacts are declared in manifest.json
auxiliaries.
Supported dataset path forms:
| Form | Example |
|---|---|
| Local directory | /data/hfx/rhine |
| Local file URL | file:///data/hfx/rhine |
| Amazon S3 URL | s3://bucket/path/to/hfx/rhine |
| Cloudflare R2 HTTPS URL | https://<account>.r2.cloudflarestorage.com/<bucket>/path/to/hfx/rhine |
| Public R2 custom-domain URL | https://basin-delineations-public.upstream.tech/grit/hfx-v0.3.0/Reader floor: pourpoint 0.3.0 |
For remote datasets, pourpoint reads only the parts needed for each watershed, so
you never download the whole dataset. It keeps a small cache on disk so repeat
opens are faster; set HFX_CACHE_DIR to choose where it lives. On macOS that is
typically ~/Library/Caches/hfx. See
docs/raster-cache.md for details.
The canonical public dataset for examples is GRIT (Global River Topology) 2.0.0, the source river network, compiled to the HFX v0.3.0 format, at:
https://basin-delineations-public.upstream.tech/grit/hfx-v0.3.0/
Reader floor: pourpoint 0.3.0
CLI example:
./target/release/pourpoint delineate \
--dataset https://basin-delineations-public.upstream.tech/grit/hfx-v0.3.0/ \
--lat 47.3769 --lon 8.5417 # Reader floor: pourpoint 0.3.0Python example:
import pourpoint
engine = pourpoint.Engine(
"https://basin-delineations-public.upstream.tech/grit/hfx-v0.3.0/" # Reader floor: pourpoint 0.3.0
)
result = engine.delineate(lat=47.3769, lon=8.5417)
print(result.terminal_unit_id, result.area_km2)These examples use the default refine=True. GRIT does not declare a D8
raster auxiliary, so best-effort refinement safely skips with a
best_effort_no_d8_aux_declared outcome.
The first open of a remote dataset fetches dataset metadata over the network and is slower, so keep the engine around and reuse it. Repeated delineations in the same session reuse data already fetched, so overlapping watersheds are faster.
git clone https://github.com/CooperBigFoot/pourpoint
cd pourpoint
cargo build --release
# Single outlet
./target/release/pourpoint delineate --dataset /path/to/hfx \
--lat 47.3769 --lon 8.5417
# Batch via CSV
./target/release/pourpoint delineate --dataset /path/to/hfx \
--outlets outlets.csv --output watersheds.geojsonpourpoint delineate --help for all flags (snap radius, accumulation threshold,
--no-refine, --json envelope, etc.).
| Path | Purpose |
|---|---|
crates/core |
Pure-Rust algorithm core (HFX I/O, traversal, dissolve, repair) |
crates/gdal |
GDAL bridge for windowed raster reads + GEOS geometry repair |
crates/python |
Python bindings, published on PyPI as pourpoint |
src/main.rs |
The pourpoint CLI binary |
ci/, .github/ |
Five-platform wheel build, repair, test, and publication pipeline |
scripts/ |
Version-bump helpers; see CLAUDE.md for the workflow |
Build instructions, coding conventions, and the open call for community
wheel contributions (Linux / Intel macOS / Windows) live in
CONTRIBUTING.md.
Public hosting of the canonical GRIT HFX dataset at https://basin-delineations-public.upstream.tech/grit/hfx-v0.3.0/ is sponsored by Upstream Tech, who provide the hosting infrastructure as an in-kind contribution to the open HFX ecosystem.
Reader floor: pourpoint 0.3.0.
Upstream Tech is an infrastructure sponsor: pourpoint is independent open-source software, and this acknowledgment implies no commercial relationship or endorsement.
pourpoint is MIT-licensed (see LICENSE). Bundled
native libraries in the published wheel retain their own licenses; see
THIRD_PARTY_LICENSES.md and the per-library
texts in LICENSES/.