easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.fill_dem

DEM conditioning helpers for hydroanalysis workflows.

This module provides utilities to estimate terrain-scale increments, add deterministic perturbations to break flat ties, and generate hydrologically conditioned DEM rasters using WhiteboxTools operations.

Functions

add_deterministic_perturbation(dem[, ...])

Add tiny monotonic perturbation to break flat-elevation ties.

estimate_typical_dz(dem[, nodata])

Estimate representative local elevation difference for a DEM.

filldem(wbe, dem_path[, output_file, ...])

Condition a DEM using least-cost breaching and optional post-processing.
easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.fill_dem.estimate_typical_dz(dem, nodata=None)[source]

Estimate representative local elevation difference for a DEM.

Parameters:

  • dem (numpy.ndarray) – Input DEM array.

  • nodata (float, optional) – Nodata value to be ignored during estimation.

Returns:

Median absolute difference between each cell and its 8 neighbors.

Return type:

float

easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.fill_dem.add_deterministic_perturbation(dem, epsilon_ratio=0.01)[source]

Add tiny monotonic perturbation to break flat-elevation ties.

Parameters:

  • dem (numpy.ndarray) – Input DEM array.

  • epsilon_ratio (float, optional) – Ratio used to scale perturbation based on minimum non-zero elevation difference in the DEM.

Returns:

Perturbed DEM array with deterministic tie-breaking offsets.

Return type:

numpy.ndarray

easy_vic_build.tools.hydroanalysis_func.hydroanalysis_wbw.fill_dem.filldem(wbe, dem_path, output_file='filled_dem.tif', add_perturbation=False, burn_streams_path=None, fill_depressions_bool=True, **kwargs)[source]

Condition a DEM using least-cost breaching and optional post-processing.

Parameters:

  • wbe (WbEnvironment) – WhiteboxTools workflow environment instance

  • dem_path (str) – Path to input DEM raster file

  • output_file (str, optional) – Output file path for filled DEM (default=”filled_dem.tif”)

  • add_perturbation (bool, optional) – If True, add a small deterministic perturbation before breaching to reduce flat-area tie effects.

  • burn_streams_path (str, optional) – Optional path to stream vectors used by fill_burn after filling.

  • fill_depressions_bool (bool, optional) – If True, run wbe.fill_depressions after breaching.

  • **kwargs (dict, optional) –

    Additional parameters for breach_depressions_least_cost:

    • max_distfloat

      Maximum breach channel length (in meters). Recommended value is DEM resolution multiplied by terrain complexity factor: - 10-20x for simple terrain - 30-50x for complex/mountainous terrain Example: 500.0 for 30m resolution DEM (e.g., SRTM)

    • flat_incrementfloat

      Elevation increment applied to flat areas (prevents flow direction artifacts). Recommended: - 0.001 for meter-level DEMs - 0.0001 for sub-meter DEMs

    • min_distbool

      Whether to enforce minimum distance paths (default=True). Set to False may create shorter but less natural breach paths.

Returns:

Conditioned DEM raster object. If burn_streams_path is provided, returns the burned DEM.

Return type:

WbRaster

Examples

>>> # Basic usage with default parameters
>>> filled = filldem(wbe, "input_dem.tif")

>>> # Advanced usage with custom parameters
>>> filled = filldem(wbe, "input_dem.tif",
...                 output_file="output_dem.tif",
...                 max_dist=100.0,
...                 flat_increment=0.001)

Notes

flat_increment is auto-estimated from local elevation differences and can be overridden through **kwargs.