Version 1.0: compiled kernels, TopoToolbox parity, and a GDAL installer

[gehilley]

Summary

• Repairs ~70 defects, several of which prevented the package from importing at all on current NumPy and SciPy, and replaces the recursive basin traversals with iterative kernels. The public interface is unchanged; results that differ because they were wrong are listed in CHANGELOG.md under "Results that change".
• Depression filling now uses the Priority-Flood algorithms of Barnes, Lehman and Mulla (2014), compiled to C++ (~50× faster), with an equivalent NumPy implementation that produces identical numbers when the extension cannot be built.
• Adds TopoAnalysis.topotoolbox, reproducing TopoToolbox 2 (MATLAB) function by function, plus a parity table saying where exact agreement is and is not achievable.
• Adds an installer for GDAL — both the C library and the Python bindings.

Why GDAL needs its own installer

There is no GDAL wheel on PyPI at any version for any platform: every release is an sdist whose setup.py shells out to gdal-config and compiles the bindings against a C library that must already exist. install.py and topoanalysis-gdal supply both halves, choosing between an existing C library, conda, a prebuilt Windows wheel, the system package manager, or a from-source build of PROJ and GDAL into the virtualenv that needs no administrator rights.

Two failure modes are detected explicitly:

• Bindings built without numpy. GDAL sdists only declared numpy as a build dependency from 3.9 on; below that, pip's build isolation omits it and osgeo.gdal_array is silently skipped — osgeo imports cleanly and ReadAsArray() fails at run time. Ubuntu 22.04 (GDAL 3.4) and 24.04 (3.8) are both affected.
• A stale PROJ_LIB/GDAL_DATA. Conda activation exports both, and they outrank the paths compiled into every other GDAL on the machine; a PROJ 9 library handed PROJ 8's proj.db refuses every lookup.

Test plan

Verified on macOS (Python 3.10):

• python3 install.py → exit 0, GeoTIFF round-trip
• python3 install.py --gdal-strategy source → PROJ + GDAL built from source into the venv, exit 0, 159 drivers
• python3 install.py --no-gdal → exit 0, library works without GDAL
• 350 tests passing with the C++ kernels, 347 with the NumPy kernels
• sdist and wheel both carry the new modules; entry points registered

Not yet exercised anywhere — this is what CI is for: Linux (the apt route, lib64, loader paths), Windows (the prebuilt-wheel strategy), the conda and system strategies, and the Dockerfile. The workflow added here covers install.py on all three platforms, an Ubuntu job that reproduces the gdal_array trap, and a scheduled from-source build.

🤖 Generated with Claude Code