Metadata-Version: 2.4
Name: pourpoint
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Dist: pourpoint[test] ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: maturin>=1.7,<2 ; extra == 'dev'
Requires-Dist: pytest>=8 ; extra == 'test'
Requires-Dist: pyarrow>=15 ; extra == 'test'
Provides-Extra: dev
Provides-Extra: test
License-File: LICENSE
License-File: LICENSES/GDAL.txt
License-File: LICENSES/GEOS.txt
License-File: LICENSES/PROJ.txt
License-File: LICENSES/README.md
License-File: LICENSES/curl.txt
License-File: LICENSES/jpeg-turbo.txt
License-File: LICENSES/libdeflate.txt
License-File: LICENSES/libpng.txt
License-File: LICENSES/libtiff.txt
License-File: LICENSES/nghttp2.txt
License-File: LICENSES/openssl.txt
License-File: LICENSES/sqlite.txt
License-File: LICENSES/xz.txt
License-File: LICENSES/zlib.txt
License-File: LICENSES/zstd.txt
Summary: Python bindings for the pourpoint watershed delineation engine
Keywords: gis,hydrology,watershed,delineation,hfx,gdal
Home-Page: https://github.com/CooperBigFoot/pourpoint
Author-email: Nicolas Lazaro <business.coopernick@gmail.com>
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/CooperBigFoot/pourpoint/blob/main/crates/python/CHANGELOG.md
Project-URL: Documentation, https://cooperbigfoot.github.io/pourpoint/
Project-URL: Homepage, https://github.com/CooperBigFoot/pourpoint
Project-URL: Issues, https://github.com/CooperBigFoot/pourpoint/issues
Project-URL: Repository, https://github.com/CooperBigFoot/pourpoint

# pourpoint

`pourpoint` is the Python package for the `pourpoint` watershed delineation engine.
Give it a point on a river and it returns the whole upstream watershed as a
polygon. It reads HFX datasets, which are folders of pre-built river-network
files. Only HFX v0.3.0 datasets load; older versions report a clear unsupported
format error.

The wheel bundles the full native stack, including GDAL, PROJ, GEOS, libtiff,
SQLite, and more, so no system GDAL install is needed.

## Install

```bash
uv add pourpoint
```

(or `pip install pourpoint`)

**Platform support:** Apple Silicon macOS only (`macosx_11_0_arm64`).
Linux, Intel macOS, and Windows wheels are not yet built. Community
contributions are welcome; see
[CONTRIBUTING.md](https://github.com/CooperBigFoot/pourpoint/blob/main/CONTRIBUTING.md)
if you want to help port the build.

## Zero-download quickstart

Use the hosted public GRIT (Global River Topology) dataset without downloading it first:

```python
import pourpoint

# No local dataset: this reads the hosted GRIT dataset over the network.
engine = pourpoint.Engine("https://basin-delineations-public.upstream.tech/grit/hfx-v0.3.0/")
result = engine.delineate(lat=47.3769, lon=8.5417)
print(result.area_km2)
```

The engine fetches only the pieces of the dataset it needs, so the full dataset
never lands on your machine. The one public dataset hosted today is GRIT 2.0.0
(the source river network), compiled to HFX v0.3.0 (the format version). To use a
different HFX dataset, change the URL and nothing else in your code changes.

## Local quickstart

```python
import pourpoint

engine = pourpoint.Engine("/path/to/hfx/dataset")
result = engine.delineate(lat=47.3769, lon=8.5417)
print(result.area_km2)
```

`Engine` accepts local paths and remote dataset URLs such as `s3://` and
`https://`. For constructor options such as snap search radius and geometry
repair, see the
[Tuning Knobs](https://github.com/CooperBigFoot/pourpoint/blob/main/crates/python/API.md#tuning-knobs)
section of `API.md`.

## Reuse the Engine

The first open 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.

## Going further

Logging and verbose output, batch delineation with a progress callback, the
staged step-by-step API, and GeoParquet export are documented in
[`API.md`](https://github.com/CooperBigFoot/pourpoint/blob/main/crates/python/API.md)
and on the docs site at https://cooperbigfoot.github.io/pourpoint/.

## What it does

- Finds the catchment your point sits in.
- Gathers every catchment upstream.
- Merges them into one watershed polygon.
- Returns the geometry plus geodesic area in km².

## API Reference

For the full developer-oriented API surface, including argument types, return
types, and the exception hierarchy, see
[API.md](https://github.com/CooperBigFoot/pourpoint/blob/main/crates/python/API.md).

## Links

- **Source & issues:** https://github.com/CooperBigFoot/pourpoint
- **HFX dataset spec:** https://github.com/CooperBigFoot/hfx
- **License:** MIT for `pourpoint`; bundled native libraries retain their own
  licenses. See
  [`LICENSES/`](https://github.com/CooperBigFoot/pourpoint/tree/main/LICENSES).

