vibespatial.raster.hydrology¶
Hydrological DEM conditioning: sink/depression filling.
CPU baseline uses iterative numpy. GPU path uses custom NVRTC kernels (kernels/hydrology.py) with shared-memory tiling and convergence detection.
The priority-flood algorithm fills depressions to their spill elevation: 1. Initialize border pixels to own elevation, interior to +infinity. 2. Iteratively propagate: fill[i] = max(elevation[i], min(neighbor_fills)). 3. Converge when no pixel changes.
Attributes¶
Functions¶
|
Fill sinks/depressions in a DEM raster to their spill elevation. |
Module Contents¶
- vibespatial.raster.hydrology.raster_fill_sinks(raster: vibespatial.raster.buffers.OwnedRasterArray, *, use_gpu: bool | None = None) vibespatial.raster.buffers.OwnedRasterArray¶
Fill sinks/depressions in a DEM raster to their spill elevation.
Uses a priority-flood algorithm: border pixels anchor the fill surface, and interior depressions are iteratively raised to the level at which water would spill out. This is essential preprocessing for hydrological analysis (flow direction, flow accumulation, watershed delineation).
For multiband rasters, each band is processed independently via per-band dispatch (
dispatch_per_band_gpu/dispatch_per_band_cpu).Parameters¶
- rasterOwnedRasterArray
Input DEM raster (single- or multi-band). Supports float32, float64, and integer dtypes (integers are promoted to float32 internally).
- use_gpubool or None
Force GPU (True), force CPU (False), or auto-dispatch (None). Auto uses GPU when available and pixel count exceeds threshold.
Returns¶
- OwnedRasterArray
HOST-resident DEM with all depressions filled to spill elevation. Nodata pixels are preserved unchanged. For multiband input, the output has the same shape
(bands, H, W).
Notes¶
The GPU implementation uses shared-memory tiled NVRTC kernels with iterative convergence detection (same pattern as connected component labeling). For large rasters, this provides significant speedup over the CPU baseline.
Examples¶
>>> dem = from_numpy(elevation_data, nodata=-9999.0) >>> filled = raster_fill_sinks(dem)
- vibespatial.raster.hydrology.logger¶