Tool API Reference (All Tools)

This chapter documents tool wrappers by theme. It is sourced from the shared tool-reference markdown files to reduce drift between wrappers and manual docs.

Important call-style note:

• Names shown in the included lists (for example d8_flow_accum) are canonical tool identifiers, not flat global methods on WbEnvironment.

• Preferred invocation is:

  • for general subcategory tools: category-level form (for example wbe.raster.arctan(...))
  • for non-general tools: nested category/subcategory form

• Examples of nested category/subcategory style:

  • wbe.hydrology.flow_routing.d8_flow_accum(...)
  • wbe.hydrology.depressions_storage.fill_depressions(...)

• Category-level calls are supported across the API surface and are preferred for general tools.

• Generic invocation always works through wbe.run_tool(tool_id, args).

For an exhaustive tool_id-to-call-path lookup, see Tool Call Paths (Python).

Math And Statistics

Math and Statistical Tools

This document covers the Math tools currently ported into the new backend.

Unary Raster Math

These tools apply an element-wise mathematical operation to every non-nodata cell of a single input raster and write the result to an output raster.

Unary Tool Index

• abs
• arccos
• arcosh
• arcsin
• arctan
• arsinh
• artanh
• bool_not
• ceil
• cos
• cosh
• decrement
• exp
• exp2
• floor
• increment
• is_nodata
• ln
• log10
• log2
• negate
• reciprocal
• round
• sin
• sinh
• sqrt
• square
• tan
• tanh
• to_degrees
• to_radians
• truncate

abs

Calculates the absolute value of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.abs(input_raster, output_path="abs_dem.tif")

arccos

Computes the inverse cosine (in radians) of each non-nodata raster cell. Input values must be in the range [-1, 1].

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.arccos(input_raster, output_path="arccos_dem.tif")

arcosh

Computes the inverse hyperbolic cosine of each non-nodata raster cell. Input values must be ≥ 1.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.arcosh(input_raster, output_path="arcosh_dem.tif")

arcsin

Computes the inverse sine (in radians) of each non-nodata raster cell. Input values must be in the range [-1, 1].

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.arcsin(input_raster, output_path="arcsin_dem.tif")

arctan

Computes the inverse tangent (in radians) of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.arctan(input_raster, output_path="arctan_dem.tif")

arsinh

Computes the inverse hyperbolic sine of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.arsinh(input_raster, output_path="arsinh_dem.tif")

artanh

Computes the inverse hyperbolic tangent of each non-nodata raster cell. Input values must be in the range (-1, 1).

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.artanh(input_raster, output_path="artanh_dem.tif")

ceil

Rounds each non-nodata raster cell upward to the nearest integer.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.ceil(input_raster, output_path="ceil_dem.tif")

cos

Computes the cosine (input in radians) of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.cos(input_raster, output_path="cos_dem.tif")

cosh

Computes the hyperbolic cosine of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.cosh(input_raster, output_path="cosh_dem.tif")

decrement

Subtracts 1 from each non-nodata raster cell value.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.decrement_raster(input_raster, output_path="dem_minus1.tif")

Note: The WbEnvironment method is named decrement_raster to avoid a name clash with the cell-level decrement helper method.

exp

Computes e raised to the power of each non-nodata raster cell value.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.exp(input_raster, output_path="exp_dem.tif")

exp2

Computes 2 raised to the power of each non-nodata raster cell value.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.exp2(input_raster, output_path="exp2_dem.tif")

floor

Rounds each non-nodata raster cell downward to the nearest integer.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.floor(input_raster, output_path="floor_dem.tif")

increment

Adds 1 to each non-nodata raster cell value.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.increment_raster(input_raster, output_path="dem_plus1.tif")

Note: The WbEnvironment method is named increment_raster to avoid a name clash with the cell-level increment helper method.

is_nodata

Outputs 1.0 for every nodata cell and 0.0 for every valid cell. Useful for creating nodata masks.

Parameters

Outputs

• return: Raster

WbEnvironment usage

mask = wbe.is_nodata_raster(input_raster, output_path="dem_nodata_mask.tif")

Note: The WbEnvironment method is named is_nodata_raster to avoid a name clash with the Raster-class is_nodata predicate.

ln

Computes the natural logarithm of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.ln(input_raster, output_path="ln_dem.tif")

log10

Computes the base-10 logarithm of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.log10(input_raster, output_path="log10_dem.tif")

log2

Computes the base-2 logarithm of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.log2(input_raster, output_path="log2_dem.tif")

negate

Negates each non-nodata raster cell value (multiplies by -1).

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.negate(input_raster, output_path="neg_dem.tif")

reciprocal

Computes the reciprocal (1/x) of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.reciprocal(input_raster, output_path="recip_dem.tif")

round

Rounds each non-nodata raster cell to the nearest integer.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.round(input_raster, output_path="round_dem.tif")

sin

Computes the sine (input in radians) of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.sin(input_raster, output_path="sin_dem.tif")

sinh

Computes the hyperbolic sine of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.sinh(input_raster, output_path="sinh_dem.tif")

sqrt

Computes the square root of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.sqrt(input_raster, output_path="sqrt_dem.tif")

square

Squares each non-nodata raster cell value (x²).

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.square(input_raster, output_path="square_dem.tif")

tan

Computes the tangent (input in radians) of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.tan(input_raster, output_path="tan_dem.tif")

tanh

Computes the hyperbolic tangent of each non-nodata raster cell.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.tanh(input_raster, output_path="tanh_dem.tif")

to_degrees

Converts each non-nodata raster cell from radians to degrees.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.to_degrees(input_raster, output_path="deg_dem.tif")

to_radians

Converts each non-nodata raster cell from degrees to radians.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.to_radians(input_raster, output_path="rad_dem.tif")

truncate

Truncates each non-nodata raster cell to its integer part (rounds toward zero).

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.truncate(input_raster, output_path="trunc_dem.tif")

bool_not

Computes a logical NOT of each non-nodata raster cell, outputting 1 where the input cell value is 0 and 0 otherwise.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.overlay_math.bool_not(input_raster, output_path="bool_not_dem.tif")

Binary Raster Math

These tools combine two rasters on a cell-by-cell basis.

Binary Tool Index

• add
• atan2
• bool_and
• bool_or
• bool_xor
• divide
• equal_to
• greater_than
• integer_division
• less_than
• modulo
• multiply
• not_equal_to
• power
• subtract

All binary raster math tools share the same core parameter shape: input1, input2, and optional output.

WbEnvironment usage examples

sum_raster = wbe.raster.overlay_math.add(raster_a, raster_b, output_path="sum.tif")
pow_raster = wbe.raster.overlay_math.power(raster_a, raster_b, output_path="power.tif")
mask = wbe.raster.greater_than(raster_a, raster_b, output_path="gt_mask.tif")
logic = wbe.raster.overlay_math.bool_and(raster_a, raster_b, output_path="and_mask.tif")

Tool semantics:

• atan2: four-quadrant inverse tangent, cell by cell.
• bool_and, bool_or, bool_xor: treat any non-zero value as true and return 1.0 or 0.0.
• equal_to, not_equal_to, greater_than, less_than: comparison predicates that return 1.0 or 0.0.
• integer_division: divides and truncates the result toward zero.
• modulo: returns the remainder of division.
• power: raises input1 to the power of input2.

See tools_gis.md for the older documentation context around add, subtract, multiply, and divide.

Statistical Raster Tools

Tool Index

• raster_summary_stats
• raster_histogram
• list_unique_values_raster
• z_scores
• rescale_value_range
• max
• min
• quantiles
• list_unique_values
• root_mean_square_error
• random_field
• random_sample
• cumulative_distribution
• crispness_index
• ks_normality_test
• inplace_add
• inplace_subtract
• inplace_multiply
• inplace_divide
• attribute_histogram
• attribute_scattergram
• attribute_correlation
• cross_tabulation
• zonal_statistics
• turning_bands_simulation
• trend_surface
• trend_surface_vector_points
• raster_calculator
• principal_component_analysis
• inverse_pca

raster_summary_stats

Computes summary statistics for valid raster cells and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.raster.raster_summary_stats(input_raster)

raster_histogram

Builds a fixed-bin histogram for valid raster cells and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

hist_json = wbe.raster.raster_histogram(input_raster, bins=256)

list_unique_values_raster

Lists unique raster values (integers) up to a maximum count and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

unique_json = wbe.raster.list_unique_values_raster(
    classified_raster,
    max_values=5000,
    output_path="classified_unique_values.csv",
)

z_scores

Standardizes raster values to z-scores using global mean and standard deviation.

Parameters

Outputs

• return: Raster

WbEnvironment usage

z = wbe.raster.z_scores(input_raster, output_path="z_scores.tif")

rescale_value_range

Linearly rescales raster values into a target output range.

Parameters

Outputs

• return: Raster

WbEnvironment usage

rescaled = wbe.raster.rescale_value_range(input_raster, 0.0, 255.0, output_path="rescaled.tif")

max

Computes cellwise maximum using raster/raster or raster/constant operands.

Parameters

Outputs

• return: Raster

WbEnvironment usage

maxed = wbe.raster.max(dem_a, dem_b, output_path="max_ab.tif")
maxed_const = wbe.raster.max(dem_a, 100.0, output_path="max_const.tif")

min

Computes cellwise minimum using raster/raster or raster/constant operands.

Parameters

Outputs

• return: Raster

WbEnvironment usage

mined = wbe.raster.min(dem_a, dem_b, output_path="min_ab.tif")
mined_const = wbe.raster.min(dem_a, 0.0, output_path="min_const.tif")

quantiles

Assigns each valid raster cell to a quantile class from 1..num_quantiles.

Parameters

Outputs

• return: Raster

WbEnvironment usage

q = wbe.raster.quantiles(input_raster, num_quantiles=5, output_path="quantiles.tif")

list_unique_values

Reports unique value counts for a vector attribute field and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.vector.attribute_analysis.list_unique_values(
    parcels,
    "landuse",
    output_path="parcels_landuse_unique_values.csv",
)

root_mean_square_error

Computes RMSE and related vertical-accuracy metrics between comparison and base rasters.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.raster.root_mean_square_error(dem_test, dem_reference)

random_field

Creates a raster filled with standard normal random values using a base raster for geometry.

Parameters

Outputs

• return: Raster

WbEnvironment usage

rand_img = wbe.raster.random_field(base_raster, output_path="random_field.tif")

random_sample

Creates a raster with randomly located valid sample cells labelled with unique IDs.

Parameters

Outputs

• return: Raster

WbEnvironment usage

sample = wbe.raster.random_sample(base_raster, num_samples=500, output_path="sample.tif")

cumulative_distribution

Transforms raster values into cumulative distribution probabilities in the range 0..1.

Parameters

Outputs

• return: Raster

WbEnvironment usage

cdf = wbe.raster.cumulative_distribution(input_raster, output_path="cdf.tif")

crispness_index

Calculates the crispness index for a membership-probability raster and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.raster.crispness_index(probability_raster)

ks_normality_test

Runs a Kolmogorov-Smirnov normality test on raster values and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.raster.ks_normality_test(input_raster, num_samples=1000)

kappa_index

Computes Cohen's kappa, overall agreement, and per-class agreement metrics for two categorical rasters and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.raster.kappa_index(classified_raster, reference_raster)

paired_sample_t_test

Runs a paired-sample t-test on two rasters using valid paired cells and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.raster.paired_sample_t_test(before_raster, after_raster, num_samples=2000)

phi_coefficient

Performs a binary-class agreement assessment between two rasters and returns a JSON report string containing contingency counts and the $\phi$ coefficient.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.raster.phi_coefficient(predicted_binary, reference_binary)

image_correlation

Computes a Pearson correlation matrix among two or more input rasters and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.raster.image_correlation([band1, band2, band3])

image_autocorrelation

Computes global Moran's $I$ for one or more rasters and returns a JSON report string with normality/randomization statistics.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.raster.image_autocorrelation([elevation, slope], contiguity="king")

image_correlation_neighbourhood_analysis

Computes moving-window local correlation between two rasters and returns two rasters: local correlation values and local p-values.

Parameters

Outputs

Returned as tuple[Raster, Raster] in this order:

• output1: Raster
• output2: Raster

WbEnvironment usage

local_r, local_p = wbe.raster.local_neighborhood.image_correlation_neighbourhood_analysis(
	band1,
	band2,
	filter_size=11,
	correlation_stat="spearman",
)

image_regression

Performs bivariate linear regression using two rasters and returns a residual raster plus a JSON report string containing model, ANOVA, and coefficient statistics.

Parameters

Outputs

Returned as tuple[Raster, str] in this order:

• result: Raster
• string_2: str

WbEnvironment usage

residuals, report_json = wbe.raster.image_regression(
    independent_raster,
    dependent_raster,
    standardize_residuals=True,
)

dbscan

Performs unsupervised DBSCAN (Density-Based Spatial Clustering of Applications with Noise) clustering on a stack of input rasters. Each cell's feature vector spans all input bands. Cluster IDs (0-based, I16) are written to the output raster; noise cells and nodata cells receive the nodata value (-32768). A JSON report string is also returned with summary statistics.

Parameters

Outputs

Returned as tuple[Raster, str] in this order:

• result: Raster
• string_2: str

WbEnvironment usage

clusters, report_json = wbe.raster.dbscan(
    [band1, band2, band3],
    scaling_method="normalize",
    search_distance=0.1,
    min_points=10,
)

| num_samples | int | no | Optional random sample size per raster; omit to use all valid values. |

WbEnvironment usage

report_json = wbe.two_sample_ks_test(raster_a, raster_b, num_samples=3000)

wilcoxon_signed_rank_test

Runs a Wilcoxon signed-rank test on paired raster differences and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.raster.wilcoxon_signed_rank_test(before_raster, after_raster, num_samples=2000)

conditional_evaluation

Evaluates a per-cell boolean statement and assigns TRUE/FALSE outputs from constants, rasters, or expressions.

Parameters

Outputs

• return: Raster

WbEnvironment usage

out = wbe.raster.reclass_mask.conditional_evaluation(
	input_raster,
	"(value >= 25.0) && (value <= 75.0)",
	true_value=1.0,
	false_value=0.0,
	output_path="conditional.tif",
)

anova

Performs one-way ANOVA of raster values grouped by a class raster and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.raster.anova(measurement_raster, class_raster)

inplace_add

Performs the legacy in-place add operation input1 += input2 and returns the updated raster handle.

Parameters

Outputs

• return: Raster

WbEnvironment usage

updated = wbe.raster.inplace_add(input_raster, 10.0)

inplace_subtract

Performs the legacy in-place subtract operation input1 -= input2 and returns the updated raster handle.

Parameters

Outputs

• return: Raster

WbEnvironment usage

updated = wbe.raster.inplace_subtract(input_raster, other_raster)

inplace_multiply

Performs the legacy in-place multiply operation input1 *= input2 and returns the updated raster handle.

Parameters

Outputs

• return: Raster

WbEnvironment usage

updated = wbe.raster.inplace_multiply(input_raster, 1.25)

inplace_divide

Performs the legacy in-place divide operation input1 /= input2 and returns the updated raster handle.

Parameters

Outputs

• return: Raster

WbEnvironment usage

updated = wbe.raster.inplace_divide(input_raster, 2.0)

attribute_histogram

Builds histogram summary counts for a numeric vector attribute field and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.vector.attribute_analysis.attribute_histogram(parcels, "area")

attribute_scattergram

Computes scattergram summary statistics for two numeric vector fields and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.vector.attribute_analysis.attribute_scattergram(parcels, "area", "perimeter", trendline=True)

attribute_correlation

Computes the Pearson correlation matrix among numeric vector attribute fields and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.vector.attribute_analysis.attribute_correlation(parcels)

cross_tabulation

Creates a categorical contingency table between two rasters and returns a JSON report string.

Parameters

Outputs

• return: str

WbEnvironment usage

report_json = wbe.raster.cross_tabulation(classes_2000, classes_2020)

zonal_statistics

Computes statistics (mean, median, min, max, range, standard deviation, diversity, total) for zones defined by a features raster and returns results as a raster and JSON report.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.zonal_statistics(
    dem, 
    zone_raster, 
    stat_type="mean", 
    output_path="dem_zones_mean.tif"
)

turning_bands_simulation

Simulates a spatially-autocorrelated random field using Carr's turning bands algorithm. Useful for Monte Carlo uncertainty analysis and geostatistical simulation.

Parameters

Outputs

• return: Raster

WbEnvironment usage

simulated = wbe.raster.turning_bands_simulation(
    template_raster,
    range=100.0,
    iterations=500,
    output_path="simulated_field.tif"
)

trend_surface

Fits a polynomial trend surface to raster data via least-squares regression. Supports polynomial orders 1–10.

Parameters

Outputs

• return: Raster

WbEnvironment usage

trend = wbe.raster.trend_surface(
    dem,
    polynomial_order=2,
    output_path="dem_trend_quadratic.tif"
)

trend_surface_vector_points

Fits a polynomial trend surface to vector point data (with attribute values) and generates an output raster.

Parameters

Outputs

• return: Raster

WbEnvironment usage

trend = wbe.raster.trend_surface_vector_points(
    sample_points,
    cell_size=10.0,
    field_name="elevation",
    polynomial_order=2,
    output_path="points_trend_surface.tif"
)

raster_calculator

Evaluates arbitrary mathematical expressions cell-by-cell over one or more input rasters.

Parameters

Special Variables

Expression can reference: rows, columns, north, south, east, west, cellsizex, cellsizey, cellsize, nodata, null, minvalue, maxvalue, pi, e, row, column, rowy, columnx, and inputs as value1, value2, etc.

Outputs

• return: Raster

WbEnvironment usage

# NDVI example with named rasters
ndvi = wbe.raster.raster_calculator(
    "'nir' - 'red' / ('nir' + 'red')",
    [nir_band, red_band],
    output_path="ndvi.tif"
)

principal_component_analysis

Performs PCA (dimensionality reduction) on 3 or more raster bands. Outputs component rasters and eigendecomposition report.

Parameters

Outputs

• return: list[Raster]

WbEnvironment usage

# Perform PCA on multispectral bands
components = wbe.raster.principal_component_analysis(
    [band1, band2, band3, band4],
    num_components=3,
    standardized=True,
    output_path="pca_components/"
)

Output Files

Component rasters: {stem}_comp1.tif, {stem}_comp2.tif, etc. JSON report includes eigenvalues, eigenvectors, and factor loadings.

inverse_pca

Reconstructs original band images from PCA components, with optional noise reduction by excluding high-order components.

Parameters

Outputs

• return: list[Raster]

WbEnvironment usage

# Reconstruct with denoising (exclude last 2 components)
reconstructed = wbe.raster.inverse_pca(
    [comp1, comp2, comp3],
    pca_report=report_json,
    output_path="reconstructed_bands/"
)

Output Files

Reconstructed rasters: {stem}_img1.tif, {stem}_img2.tif, etc.

Hydrology

Hydrology Tools

This document covers hydrology tools currently ported into the backend, including DEM depression removal/conditioning and flow-accumulation workflows.

Hydrology (Depression Removal)

These tools prepare DEMs for downstream flow-routing by removing pits, flats, or larger enclosed depressions. The short version is:

• Prefer breach_depressions_least_cost when you want the lowest-impact correction and realistic cuts through barriers such as roads or embankments.
• Use fill_depressions when you need a robust full-fill solution and are comfortable modifying all enclosed depressions up to their spill elevations.
• Use fill_pits or breach_single_cell_pits as lightweight preprocessing for single-cell artifacts, not as a replacement for full depression conditioning.
• Treat the Wang-and-Liu and Planchon-and-Darboux variants mainly as compatibility methods when you need those specific historical formulations.

Tool Index

• breach_depressions_least_cost
• breach_single_cell_pits
• fill_depressions
• fill_depressions_planchon_and_darboux
• fill_depressions_wang_and_liu
• fill_pits
• depth_in_sink
• sink

Hydrology (Flow Accumulation)

Tool Index

• d8_pointer
• d8_flow_accum
• dinf_pointer
• dinf_flow_accum
• fd8_pointer
• fd8_flow_accum
• rho8_pointer
• rho8_flow_accum
• mdinf_flow_accum
• qin_flow_accumulation
• quinn_flow_accumulation
• minimal_dispersion_flow_algorithm
• flow_accum_full_workflow
• d8_mass_flux
• dinf_mass_flux

Hydrology (Diagnostics)

Tool Index

• find_noflow_cells
• num_inflowing_neighbours
• find_parallel_flow
• edge_contamination
• flow_length_diff
• downslope_flowpath_length
• max_upslope_flowpath_length
• average_upslope_flowpath_length
• elevation_above_stream
• elevation_above_stream_euclidean
• downslope_distance_to_stream
• average_flowpath_slope
• max_upslope_value
• longest_flowpath
• depth_to_water
• fill_burn
• burn_streams_at_roads
• trace_downslope_flowpaths
• flood_order
• insert_dams
• raise_walls
• topological_breach_burn
• stochastic_depression_analysis
• unnest_basins
• upslope_depression_storage
• flatten_lakes
• hydrologic_connectivity
• impoundment_size_index

Hydrology (Watersheds and Basins)

Tool Index

• basins
• watershed_from_raster_pour_points
• watershed
• jenson_snap_pour_points
• snap_pour_points
• subbasins
• hillslopes
• strahler_order_basins
• isobasins

mdinf_flow_accum

mdinf_flow_accum(dem, out_type="sca", exponent=1.1, threshold=None, log=False, clip=False, output_path=None, callback=None)

Computes MD-Infinity triangular multiple-flow-direction accumulation from a DEM.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.mdinf_flow_accum(
    dem,
    out_type="value",
    exponent=1.0,
    threshold=1.0,
    output_path="result.tif",
)

qin_flow_accumulation

qin_flow_accumulation(dem, out_type="sca", exponent=10.0, max_slope=45.0, threshold=None, log=False, clip=False, output_path=None, callback=None)

Computes Qin MFD flow accumulation from a DEM using a gradient-dependent dynamic exponent.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.qin_flow_accumulation(
    dem,
    out_type="value",
    exponent=1.0,
    max_slope=1.0,
    threshold=1.0,
    output_path="result.tif",
)

quinn_flow_accumulation

quinn_flow_accumulation(dem, out_type="sca", exponent=1.1, threshold=None, log=False, clip=False, output_path=None, callback=None)

Computes Quinn MFD flow accumulation from a DEM using accumulation-dependent convergence.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.quinn_flow_accumulation(
    dem,
    out_type="value",
    exponent=1.0,
    threshold=1.0,
    output_path="result.tif",
)

minimal_dispersion_flow_algorithm

minimal_dispersion_flow_algorithm(raster, out_type="sca", path_corrected_direction_preference=0.0, log_transform=False, clip=False, esri_pntr=False, flow_dir_output_path=None, output_path=None, callback=None)

Computes the Minimal Dispersion Flow Algorithm (MDFA) from a DEM and returns both a flow-direction raster and flow-accumulation raster as a tuple.

Parameters

Outputs

Returned as tuple[Raster, Raster] in this order:

• flow_dir: Raster
• result: Raster

WbEnvironment usage

raster_1, raster_2 = wbe.hydrology.flow_routing.minimal_dispersion_flow_algorithm(
    raster,
    out_type="value",
    path_corrected_direction_preference=1.0,
    flow_dir_output_path="flow_dir.tif",
    output_path="result.tif",
)

flow_accum_full_workflow

flow_accum_full_workflow(dem, out_type="sca", log_transform=False, clip=False, esri_pntr=False, breached_dem_output_path=None, flow_dir_output_path=None, output_path=None, callback=None)

Runs a full non-divergent flow workflow in one call and returns a tuple containing a depressionless DEM, a D8 pointer raster, and a D8 accumulation raster.

Parameters

Outputs

Returned as tuple[Raster, Raster, Raster] in this order:

• breached_dem: Raster
• flow_dir: Raster
• result: Raster

WbEnvironment usage

raster_1, raster_2, raster_3 = wbe.hydrology.flow_routing.flow_accum_full_workflow(
    dem,
    out_type="value",
    breached_dem_output_path="breached_dem.tif",
    flow_dir_output_path="flow_dir.tif",
    output_path="result.tif",
)

find_noflow_cells

find_noflow_cells(dem, output_path=None, callback=None, interior_only=False)

Finds DEM cells that have no lower D8 neighbour. On a fully conditioned DEM this should usually be limited to valid edge-drainage cases; interior hits often indicate remaining pits or flats.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.hydrologic_indices.find_noflow_cells(
    dem,
    output_path="result.tif",
)

dinf_mass_flux

dinf_mass_flux(dem, loading, efficiency, absorption, output_path=None, callback=None)

Routes mass downslope using D-Infinity flow-routing, accumulating loading while applying per-cell efficiency and absorption losses.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.dinf_mass_flux(
    dem,
    loading,
    efficiency,
    absorption,
    output_path="result.tif",
)

trace_downslope_flowpaths

trace_downslope_flowpaths(seed_points, d8_pntr, esri_pntr=False, zero_background=False, output_path=None, callback=None)

Traces downslope D8 flowpaths from seed points to no-flow cells or the raster edge. Output values are visit counts where overlapping traces occur.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.trace_downslope_flowpaths(
    seed_points,
    d8_pointer,
    output_path="result.tif",
)

flood_order

flood_order(dem, output_path=None, callback=None)

Computes flood order from a DEM using a priority-flood traversal from edges inward, assigning each valid cell its visitation sequence.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.watersheds_basins.flood_order(
    dem,
    output_path="result.tif",
)

flatten_lakes

flatten_lakes(dem, lakes, output_path=None, callback=None)

Flattens lake polygons in a DEM by setting each lake interior to its minimum perimeter elevation.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.flatten_lakes(
    dem,
    lakes,
    output_path="result.tif",
)

insert_dams

insert_dams(dem, dam_points, dam_length, output_path=None, callback=None)

Inserts localized dam embankments at specified point locations using profile-based crest selection constrained by maximum dam length.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.insert_dams(
    dem,
    dam_points,
    dam_length=1.0,
    output_path="result.tif",
)

raise_walls

raise_walls(dem, walls, breach_lines=None, wall_height=100.0, output_path=None, callback=None)

Raises DEM elevations along wall features by a specified height increment, with optional breach lines used to carve openings through raised walls.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.raise_walls(
    dem,
    walls,
    breach_lines,
    wall_height=1.0,
    output_path="result.tif",
)

topological_breach_burn

topological_breach_burn(streams, dem, snap_distance=0.001, out_streams_path=None, out_dem_path=None, out_dir_path=None, out_fa_path=None, callback=None)

Performs topological stream burning using a stream vector and DEM, producing stream raster, burned/conditioned DEM, D8 pointer, and D8 accumulation outputs.

Parameters

Outputs

Returned as tuple[Raster, Raster, Raster, Raster] in this order:

• raster_1: Raster
• raster_2: Raster
• raster_3: Raster
• raster_4: Raster

WbEnvironment usage

raster_1, raster_2, raster_3, raster_4 = wbe.hydrology.depressions_storage.topological_breach_burn(
    dem,
    streams,
    snap_distance=1.0,
    output_streams_path="output_streams.dat",
    output_dem_path="output_dem.dat",
    output_dir_path="output_dir.dat",
    output_flow_accum_path="output_flow_accum.dat",
)

stochastic_depression_analysis

stochastic_depression_analysis(dem, rmse, range, iterations=100, output_path=None, callback=None)

Estimates depression-membership probability for each DEM cell using Monte Carlo perturbation of elevation error and repeated depression filling.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.stochastic_depression_analysis(
    dem,
    rmse=1.0,
    range=1.0,
    iterations=1,
    output_path="result.tif",
)

unnest_basins

unnest_basins(d8_pointer, pour_points, esri_pntr=False, output_path=None, callback=None)

Delineates full nested basins for pour points over a D8 pointer raster, producing one raster per nesting level.

Parameters

Outputs

• return: list[Raster]

WbEnvironment usage

result = wbe.hydrology.watersheds_basins.unnest_basins(
    d8_pointer,
    pour_points,
    output_path="result.tif",
)

upslope_depression_storage

upslope_depression_storage(dem, output_path=None, callback=None)

Estimates average upslope depression-storage depth by conditioning depressions and routing storage depth downslope.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.upslope_depression_storage(
    dem,
    output_path="result.tif",
)

hydrologic_connectivity

hydrologic_connectivity(dem, exponent=1.1, convergence_threshold=0.0, z_factor=1.0, output1_path=None, output2_path=None, callback=None)

Computes two hydrologic-connectivity indices from a DEM: downslope unsaturated length (DUL) and upslope disconnected saturated area (UDSA).

Parameters

Outputs

Returned as tuple[Raster, Raster] in this order:

• output1: Raster
• output2: Raster

WbEnvironment usage

raster_1, raster_2 = wbe.hydrology.hydrologic_indices.hydrologic_connectivity(
    dem,
    exponent=1.0,
    convergence_threshold=1.0,
    z_factor=1.0,
    output1="value",
    output2="value",
)

impoundment_size_index

impoundment_size_index(dem, max_dam_length, output_mean=False, output_max=False, output_volume=False, output_area=False, output_height=False, callback=None)

Estimates impoundment metrics for potential dams of a given maximum length at each DEM cell.

Parameters

Outputs

Returned as tuple[Raster | None, Raster | None, Raster | None, Raster | None, Raster | None] in this order:

• mean: Raster | None
• max: Raster | None
• volume: Raster | None
• area: Raster | None
• dam_height: Raster | None

WbEnvironment usage

raster_1, raster_2, raster_3, raster_4, raster_5 = wbe.hydrology.depressions_storage.impoundment_size_index(
    dem,
    max_dam_length=1.0,
    mean_output_path="mean.tif",
    max_output_path="max.tif",
    volume_output_path="volume.tif",
    area_output_path="area.tif",
    dam_height_output_path="dam_height.tif",
)

num_inflowing_neighbours

num_inflowing_neighbours(dem, output_path=None, callback=None)

Counts the number of inflowing D8 neighbours for each DEM cell by deriving a D8 flow field from the DEM internally.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.num_inflowing_neighbours(
    dem,
    output_path="result.tif",
)

find_parallel_flow

find_parallel_flow(d8_pointer, streams=None, output_path=None, callback=None)

Flags stream cells that have neighboring stream cells with the same local D8 flow direction, which can indicate D8 directional bias and suspect parallel channel routing.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.hydrologic_indices.find_parallel_flow(
    d8_pointer,
    streams,
    output_path="result.tif",
)

edge_contamination

edge_contamination(dem, flow_type="mfd", z_factor=-1.0, output_path=None, callback=None)

Identifies edge-contaminated cells, i.e., cells whose upslope contributing area extends beyond the DEM boundary or boundary-connected NoData areas.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.hydrologic_indices.edge_contamination(
    dem,
    flow_type="value",
    z_factor=1.0,
    output_path="result.tif",
)

flow_length_diff

flow_length_diff(d8_pointer, esri_pntr=False, log_transform=False, output_path=None, callback=None)

Calculates the local maximum absolute difference in downslope flowpath length, which is useful for highlighting drainage divides and ridgelines.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.flow_length_diff(
    d8_pntr,
    output_path="result.tif",
)

downslope_flowpath_length

downslope_flowpath_length(d8_pointer, watersheds=None, weights=None, esri_pntr=False, output_path=None, callback=None)

Computes downslope flowpath length from each cell in a D8 pointer raster to its outlet. Optionally constrains paths within watershed IDs and applies per-cell distance weighting.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.downslope_flowpath_length(
    d8_pntr,
    output_path="result.tif",
    watersheds,
    weights,
)

max_upslope_flowpath_length

max_upslope_flowpath_length(dem, output_path=None, callback=None)

Computes the maximum upslope flowpath length passing through each DEM cell using D8 routing derived from the input DEM.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.max_upslope_flowpath_length(
    dem,
    output_path="result.tif",
)

average_upslope_flowpath_length

average_upslope_flowpath_length(dem, output_path=None, callback=None)

Computes the average upslope flowpath length passing through each DEM cell using D8 routing derived from the input DEM.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.average_upslope_flowpath_length(
    dem,
    output_path="result.tif",
)

elevation_above_stream

elevation_above_stream(dem, streams, output_path=None, callback=None)

Computes elevation above nearest stream measured along downslope D8 flowpaths (a HAND-like terrain index).

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.hydrologic_indices.elevation_above_stream(
    dem,
    streams,
    output_path="result.tif",
)

elevation_above_stream_euclidean

elevation_above_stream_euclidean(dem, streams, output_path=None, callback=None)

Computes elevation above nearest stream using Euclidean proximity to assign each cell to the nearest stream cell, then subtracts stream elevation.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.hydrologic_indices.elevation_above_stream_euclidean(
    dem,
    streams,
    output_path="result.tif",
)

downslope_distance_to_stream

downslope_distance_to_stream(dem, streams, dinf=False, output_path=None, callback=None)

Computes distance from each cell to the nearest stream along downslope flowpaths. Supports D8 routing by default and optional D-infinity routing when dinf=True.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.hydrologic_indices.downslope_distance_to_stream(
    dem,
    streams,
    output_path="result.tif",
)

average_flowpath_slope

average_flowpath_slope(dem, output_path=None, callback=None)

Calculates average slope gradient in degrees for flowpaths passing through each DEM cell, using D8 flow routing derived from the DEM.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.average_flowpath_slope(
    dem,
    output_path="result.tif",
)

max_upslope_value

max_upslope_value(dem, values, output_path=None, callback=None)

Propagates the maximum upslope value along D8 flowpaths over a DEM. Useful for carrying source characteristics downslope while preserving maxima.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.max_upslope_value(
    dem,
    values,
    output_path="result.tif",
)

longest_flowpath

longest_flowpath(dem, basins, output_path, callback=None)

Delineates one longest downslope flowpath polyline for each basin in a basin raster. Output includes basin ID, upstream/downstream elevation, flowpath length, and average slope.

Parameters

Outputs

• return: Vector

WbEnvironment usage

result = wbe.hydrology.watersheds_basins.longest_flowpath(
    dem,
    basins,
    output_path="result.tif",
)

depth_to_water

depth_to_water(dem, streams=None, lakes=None, output_path=None, callback=None)

Computes cartographic depth-to-water (DTW) by least-cost accumulation from mapped surface-water source features.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.hydrologic_indices.depth_to_water(
    dem,
    streams,
    lakes,
    output_path="result.tif",
)

fill_burn

fill_burn(dem, streams, output_path=None, callback=None)

Creates a hydro-enforced DEM by burning in stream locations and then filling depressions.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.fill_burn(
    dem,
    streams,
    output_path="result.tif",
)

burn_streams_at_roads

burn_streams_at_roads(dem, streams, roads, road_width, output_path=None, callback=None)

Lowers stream elevations near stream-road intersections to breach embankment effects in a DEM.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.burn_streams_at_roads(
    dem,
    streams,
    roads,
    output_path="result.tif",
    width=1.0,
)

d8_mass_flux

d8_mass_flux(dem, loading, efficiency, absorption, output_path=None, callback=None)

Performs D8-based mass-flux routing, suitable for modeling movement of sediment, nutrients, or contaminants over a DEM-defined flow network.

The routed mass per cell follows:

$$ ext{outflow} = (\text{loading} - \text{absorption} + \text{inflow}) \times \text{efficiency} $$

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.flow_routing.d8_mass_flux(
    dem,
    loading,
    efficiency,
    absorption,
    output_path="result.tif",
)

basins

basins(d8_pointer, esri_pntr=False, output_path=None, callback=None)

Delineates all drainage basins in a D8 pointer raster by assigning each valid cell to the edge-draining outlet basin reached along its D8 flow path.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.watersheds_basins.basins(
    d8_pntr,
    output_path="result.tif",
)

watershed_from_raster_pour_points

watershed_from_raster_pour_points(d8_pointer, pour_points, esri_pntr=False, output_path=None, callback=None)

Delineates watersheds from a D8 pointer raster and a raster of pour-point outlet IDs. Each non-zero, non-NoData cell in pour_points is treated as an outlet; its cell value becomes the watershed ID for all cells that drain to it.

Algorithm notes:

• Same two-pass flow-path labeling as basins, but seeded from user-supplied pour points rather than edge outlets.
• Watershed IDs are inherited directly from the pour-points raster values, making it easy to use stream-link or lake ID rasters as pour-point inputs.
• Cells where the D8 pointer is NoData are propagated as NoData in the output.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.watersheds_basins.watershed_from_raster_pour_points(d8_pointer, pour_points)

watershed

watershed(d8_pointer, pour_pts, esri_pntr=False, output_path=None, callback=None)

Delineates watersheds from a D8 pointer raster and a vector point file of pour points. Each vector feature is assigned a sequential 1-based watershed ID.

Algorithm notes:

• Pour-point coordinates are converted to raster row/col via the pointer raster's geotransform.
• Watershed IDs are 1-based sequential integers in feature insertion order.
• Same two-pass flow-path labeling as watershed_from_raster_pour_points.
• Only the first coordinate of each feature is used; MultiPoint features use their first point.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.watersheds_basins.watershed(
    d8_pntr,
    pour_pts,
    output_path="result.tif",
)

jenson_snap_pour_points

jenson_snap_pour_points(pour_pts, streams, snap_dist=0.0, output_path=None, callback=None)

Moves each input pour point to the nearest stream cell within a configurable search radius, snapping it onto the stream network. Preserves all input feature attributes.

Algorithm notes:

• For each point, a square window of floor((snap_dist / cell_size) / 2) cells is searched around the point's raster position.
• The nearest stream cell (value > 0 and not NoData) by squared Euclidean distance is chosen.
• If no stream cell is found within the window, the point is emitted at its original location.
• Points outside the raster extent are passed through unchanged.

Parameters

Outputs

• return: Vector

WbEnvironment usage

result = wbe.hydrology.watersheds_basins.jenson_snap_pour_points(
    pour_pts,
    streams,
    snap_dist=1.0,
    output_path="result.tif",
)

snap_pour_points

snap_pour_points(pour_pts, flow_accum, snap_dist=0.0, output_path=None, callback=None)

Moves each pour point to the highest flow-accumulation cell within a local search window. Preserves all input feature attributes.

Algorithm notes:

• For each point, the tool scans a square search window centered on the point's raster position.
• The output location is set to the cell center of the maximum flow_accum value found in that window.
• If no valid cell exists in the search window (for example, all NoData), the point is emitted unchanged.
• Points outside the raster extent are emitted unchanged.

Parameters

Outputs

• return: Vector

WbEnvironment usage

result = wbe.hydrology.watersheds_basins.snap_pour_points(
    pour_pts,
    flow_accum,
    snap_dist=1.0,
    output_path="result.tif",
)

subbasins

subbasins(d8_pointer, streams, esri_pntr=False, output_path=None, callback=None)

Identifies the catchment area of each stream link in a D8 stream network, producing a raster where every cell is labelled with the ID of the sub-basin it drains to.

Algorithm notes:

• Performs a stream-link ID operation followed by a watershed operation.
• Headwater stream cells receive a unique link ID. At each downstream confluence (cell with more than one inflowing stream neighbour) a new link ID is assigned.
• All non-stream cells are labelled by walking downstream to the nearest stream-link seed.
• Differs from hillslopes in that stream cells themselves are also labelled (not zeroed) and no left/right bank separation is applied.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.watersheds_basins.subbasins(
    d8_pntr,
    streams,
    output_path="result.tif",
)

hillslopes

hillslopes(d8_pointer, streams, esri_pntr=False, output_path=None, callback=None)

Identifies hillslope regions draining to each stream link, distinguishing left-bank and right-bank areas. Stream cells themselves are set to 0.

Algorithm notes:

• Performs the same stream-link ID and watershed labeling as subbasins.
• After labeling, all stream cells are zeroed.
• A flood-fill clump pass re-numbers spatially connected regions that share the same sub-basin ID, separating left- and right-bank hillslopes.
• Diagonal clump expansion is blocked when both adjacent cardinal cells are stream cells, preventing hillslopes from merging across the stream.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.watersheds_basins.hillslopes(
    d8_pntr,
    streams,
    output_path="result.tif",
)

strahler_order_basins

strahler_order_basins(d8_pointer, streams, esri_pntr=False, output_path=None, callback=None)

Delineates watershed basins whose cells are labelled by the Horton-Strahler order of the stream link that drains them.

Algorithm notes:

• Assigns Strahler stream orders to all stream cells: headwaters receive order 1; at a confluence where two or more inflowing streams share the same order, the downstream order is incremented by 1.
• All non-stream cells are then labelled with the Strahler order of the stream link they drain into, using the same two-pass watershed labeling as watershed.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.streams.ordering_metrics.strahler_order_basins(
    d8_pntr,
    streams,
    output_path="result.tif",
)

isobasins

isobasins(dem, target_size, output_path=None, callback=None)

Divides a landscape into approximately equal-sized watersheds (isobasins) by placing pour points wherever flow accumulation first exceeds a target threshold.

Algorithm notes:

• Computes D8 flow direction internally from the DEM using steepest descent.
• Accumulates flow cell-by-cell in topological order from headwaters downstream.
• When a cell's cumulative upstream area reaches target_size, a pour point is created at that cell or (if it produces a closer-to-target split) at its largest-accumulation inflowing neighbour.
• All cells are then traced downstream to their nearest pour point and assigned that basin's ID.
• The DEM must have been hydrologically conditioned (depressions filled or breached) before use.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.watersheds_basins.isobasins(
    dem,
    target_size=1.0,
    output_path="result.tif",
)

breach_depressions_least_cost

breach_depressions_least_cost(dem, max_cost=inf, max_dist=100, flat_increment=None, fill_deps=False, minimize_dist=False, output=None)

Breaches depressions using a constrained least-cost pathway search from pit cells.

Algorithm notes:

• Searches outward from pit cells for a lower outlet cell and cuts the least-cost breach channel through intervening terrain.
• Usually alters the DEM less than full filling because it carves narrow channels instead of raising entire depressions.
• Well suited to artificial barriers such as roads, berms, and embankments where a culvert-like breach is more realistic than filling.
• fill_deps=True is useful when a small number of depressions remain unresolved after breaching.

Parameters

When to use:

• First-choice preprocessing for hydrologic conditioning in many LiDAR-derived DEM workflows.
• Best when preserving surrounding terrain is more important than enforcing a pure fill solution.

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.breach_depressions_least_cost(
    dem,
    max_cost=1.0,
    max_dist=1,
    flat_increment=1.0,
    output_path="result.tif",
)

breach_single_cell_pits

breach_single_cell_pits(dem, output=None)

Parameters

Breaches single-cell pits by carving local one-cell channels toward lower second-ring neighbors.

Algorithm notes:

• Only targets isolated one-cell pit artifacts.
• Adjusts an adjacent cell to create a local breach path toward a lower cell in the surrounding 5x5 neighborhood.
• Very fast, but intentionally limited in scope; it does not solve larger depressions.

When to use:

• Cheap cleanup pass before a more complete breaching or filling step.
• Useful when DEM artifacts are dominated by isolated single-cell pits.

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.breach_single_cell_pits(
    dem,
    output_path="result.tif",
)

fill_depressions

fill_depressions(dem, fix_flats=True, flat_increment=0.0001, flat_resolution="garbrecht_martz", max_depth=inf, output=None)

Fills depressions using a priority-flood strategy with optional flat resolution and optional maximum fill depth.

Algorithm notes:

• Identifies depressions, raises them to spill elevation, and optionally imposes a very small gradient across resulting flats.
• fix_flats=True applies a small downstream gradient so later flow-routing tools do not stall on large flat surfaces.
• flat_resolution="garbrecht_martz" is the default and produces a more structured, less meandering flat-resolution pattern for D8-style routing. Use "natural" to recover the older natural-path behaviour that follows original within-flat topography more closely.
• max_depth can limit how much vertical filling is allowed, which is useful when deep excavations or reservoirs should not be completely removed.
• More aggressive than breaching because every enclosed depression is raised rather than selectively cut.

Parameters

When to use:

• Good general-purpose fill workflow when a complete depressionless DEM is required.
• Appropriate when breaching would create unrealistic long cuts or when a full-fill surface is preferred.

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.fill_depressions(
    dem,
    flat_increment=1.0,
    max_depth=1.0,
    flat_resolution,
    output_path="result.tif",
)

fill_depressions_planchon_and_darboux

fill_depressions_planchon_and_darboux(dem, fix_flats=True, flat_increment=0.0001, output=None)

Planchon-and-Darboux-compatible interface using the shared optimized fill backend.

Algorithm notes:

• Compatibility-oriented interface for the classic Planchon and Darboux depression-filling formulation.
• Included mainly for parity with legacy workflows rather than because it is the preferred modern option.
• In practice, fill_depressions or breach_depressions_least_cost will often be the better first choice.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.fill_depressions_planchon_and_darboux(
    dem,
    flat_increment=1.0,
    output_path="result.tif",
)

fill_depressions_wang_and_liu

fill_depressions_wang_and_liu(dem, fix_flats=True, flat_increment=0.0001, output=None)

Wang-and-Liu-compatible interface using the shared optimized fill backend.

Algorithm notes:

• Compatibility-oriented interface for the Wang and Liu priority-queue depression-filling method.
• Processes cells by spill elevation and is historically important, but is not the preferred default in this port.
• Best used when reproducing older Wang-and-Liu-based workflows or published methods.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.fill_depressions_wang_and_liu(
    dem,
    flat_increment=1.0,
    output_path="result.tif",
)

fill_pits

fill_pits(dem, output=None)

Parameters

Fills single-cell pits by raising pit cells to the minimum neighboring elevation plus a small increment.

Algorithm notes:

• Only removes isolated one-cell pits.
• Leaves larger depressions unchanged.
• Minimal and fast, but much less complete than full depression filling or breaching.

When to use:

• Very lightweight preprocessing for obvious single-cell artifacts.
• A quick first pass before running fill_depressions or breach_depressions_least_cost.

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.fill_pits(
    dem,
    output_path="result.tif",
)

depth_in_sink

depth_in_sink(dem, zero_background=False, output_path=None, callback=None)

Measures the vertical depth of each cell within topographic depressions by differencing a depression-filled DEM and the original DEM.

Algorithm notes:

• Internally generates a filled DEM surface and computes filled_dem - dem for each valid cell.
• Positive values indicate depression depth.
• Non-sink cells are assigned NoData by default, or 0.0 when zero_background=True.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.depth_in_sink(
    dem,
    output_path="result.tif",
)

sink

sink(dem, zero_background=False, output_path=None, callback=None)

Creates a binary raster identifying cells that belong to topographic depressions.

Algorithm notes:

• Uses the same filled-vs-original DEM differencing approach as depth_in_sink.
• Cells with positive depth are classified as sink cells (1).
• Non-sink cells are assigned NoData by default, or 0.0 when zero_background=True.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.hydrology.depressions_storage.sink(
    dem,
    output_path="result.tif",
)

GIS And Vector

GIS Tools

This document covers the GIS tools currently ported into the backend.

GIS Workflow Products (Pro)

These workflow methods expose higher-level environmental monitoring and siting products.

Workflow Product Index

• wetland_hydrogeomorphic_classification
• urban_expansion_impact_assessment
• wind_turbine_siting
• solar_site_suitability_analysis
• corridor_mapping_intelligence
• landslide_susceptibility_assessment
• river_corridor_health_assessment

wetland_hydrogeomorphic_classification

wetland_hydrogeomorphic_classification(dem, wetland_mask, max_polygon_features=10000, output_prefix=None, callback=None)

Parameters

Returns (hgm_class_raster, wetland_polygons_vector, confidence_raster, summary_json_path).

Outputs

Returned as tuple[Raster, Vector, Raster, str] in this order:

• cls: Raster
• polys: Vector
• conf: Raster
• summary: str

Example:

hgm, polygons, confidence, summary = wbe.terrain.workflow_products.wetland_hydrogeomorphic_classification(
	dem=dem,
	wetland_mask=wetland_mask,
)

urban_expansion_impact_assessment

urban_expansion_impact_assessment(baseline_urban, scenario_urban, streams, habitat_sensitivity=None, output_prefix=None, callback=None)

Parameters

Returns (impact_severity_raster, affected_streams_vector, habitat_loss_raster, summary_json_path).

Outputs

Returned as tuple[Raster, Vector, Raster, str] in this order:

• impact: Raster
• affected: Vector
• habitat: Raster
• summary: str

Example:

impact, streams_out, habitat_loss, summary = wbe.terrain.workflow_products.urban_expansion_impact_assessment(
	baseline_urban=urban_2020,
	scenario_urban=urban_2035,
	streams=streams,
	habitat_sensitivity=habitat_sensitivity,
)

wind_turbine_siting

wind_turbine_siting(dem, settlements, settlements_epsg=None, visibility_radius_meters=5000, min_slope_degrees=5.0, max_slope_degrees=35.0, profile="balanced", sweep_spec_json=None, output_prefix=None, callback=None)

Parameters

Returns (siting_score_raster, confidence_raster, summary_json_path).

When sweep_spec_json is provided, the runtime also emits run_matrix_summary, sensitivity_report, sensitivity_report_html, and stability_map outputs. The sensitivity report includes metrics.primary_metric, metrics.primary_relative_span, and metrics.stability_class (high, medium, low).

Outputs

Returned as tuple[Raster, Raster, str, str] in this order:

• score: Raster
• confidence: Raster
• summary: str
• threshold_sensitivity: str

Example:

score, confidence, summary = wbe.terrain.workflow_products.wind_turbine_siting(
	dem=dem,
	settlements=settlements,
	profile="balanced",
)

solar_site_suitability_analysis

solar_site_suitability_analysis(dem, candidate_threshold=0.7, max_candidate_sites=200, sweep_spec_json=None, output_prefix=None, callback=None)

Parameters

Returns (suitability_score_raster, visual_impact_raster, candidate_sites_vector, summary_json_path).

When sweep_spec_json is provided, the runtime also emits run_matrix_summary, sensitivity_report, sensitivity_report_html, and stability_map outputs. The sensitivity report includes metrics.primary_metric, metrics.primary_relative_span, and metrics.stability_class (high, medium, low).

Outputs

Returned as tuple[Raster, Raster, Vector, str] in this order:

• score: Raster
• impact: Raster
• sites: Vector
• summary: str

Example:

score, impact, sites, summary = wbe.terrain.workflow_products.solar_site_suitability_analysis(
	dem=dem,
	candidate_threshold=0.7,
)

corridor_mapping_intelligence

corridor_mapping_intelligence(dem, start_features, end_features, constraints=None, cost_profile="slope_roughness", terminal_anchor_strategy="mixed", corridor_tolerance=0.15, output_prefix=None, callback=None)

Parameters

Returns (cost_surface_raster, accumulated_cost_raster, optimal_route_vector, corridor_suitability_raster, summary_json_path).

Finds the terrain least-cost route and corridor suitability band for siting linear infrastructure (roads, pipelines, utility lines). start_features and end_features are vector layers containing point and/or polygon features. cost_profile is one of "slope_only", "slope_roughness" (default), or "conservative". terminal_anchor_strategy is one of "mixed" (default), "centroid_only", or "boundary_only". corridor_tolerance is the fractional cost margin above optimal for the suitability band (default 0.15).

Value proposition vs OSS least-cost building blocks:

• This is an end-to-end workflow product rather than a low-level routing primitive.
• It derives a terrain cost surface from DEM slope/roughness, runs least-cost routing, and emits both route geometry and corridor alternatives in one call.
• It supports polygon exclusion constraints and returns a summary JSON contract for reporting/automation.

Endpoint modeling note:

• Current API is vector-first for terminal modeling.
• Point features are used directly as candidate anchors.
• Polygon features contribute sampled boundary/centroid candidates, and the tool chooses a traversable anchor pair.
• terminal_anchor_strategy controls polygon anchor candidate generation.
• If start/end layers differ from DEM CRS, they are reprojected to the DEM CRS before routing.
• If constraints differ from DEM CRS, they are reprojected to the DEM CRS before exclusion masking.
• DEM, start/end layers, and optional constraints must include EPSG metadata for CRS harmonization.

QA-style outputs:

• cost_surface_raster, accumulated_cost_raster, and corridor_suitability_raster provide inspectable diagnostic surfaces.
• optimal_route_vector includes comparative route attributes (ROUTE_LEN_M, MEAN_SLOPE, ROUTE_COST, PROFILE).
• summary_json_path stores reproducible run metadata and key metrics.

Outputs

Returned as tuple[Raster, Raster, Vector, Raster, str] in this order:

• cost_surface: Raster
• accumulated_cost: Raster
• optimal_route: Vector
• corridor_suitability: Raster
• summary: str

Example:

cost, acc_cost, route, suitability, summary = wbe.terrain.workflow_products.corridor_mapping_intelligence(
	dem=dem,
	start_features=start_features,
	end_features=end_features,
	cost_profile="slope_roughness",
	terminal_anchor_strategy="mixed",
	corridor_tolerance=0.15,
	output_prefix="output/access_road",
)

landslide_susceptibility_assessment

landslide_susceptibility_assessment(dem, rainfall_intensity=None, profile="balanced", susceptibility_threshold=0.65, max_zone_features=5000, output_prefix=None, callback=None)

Parameters

Returns (susceptibility_raster, trigger_pressure_raster, confidence_raster, risk_zones_vector, summary_json_path).

Outputs

Returned as tuple[Raster, Raster, Raster, Vector, str] in this order:

• susceptibility: Raster
• trigger: Raster
• confidence: Raster
• zones: Vector
• summary: str

Example:

sus, trigger, confidence, zones, summary = wbe.terrain.workflow_products.landslide_susceptibility_assessment(
	dem=dem,
	rainfall_intensity=rainfall,
	profile="balanced",
)

river_corridor_health_assessment

river_corridor_health_assessment(dem, streams, profile="balanced", output_prefix=None, callback=None)

Parameters

Returns (erosion_pressure_raster, corridor_confidence_raster, stream_health_score_raster, restoration_zones_vector, summary_json_path).

Outputs

Returned as tuple[Raster, Raster, Raster, Vector, str] in this order:

• erosion: Raster
• confidence: Raster
• health: Raster
• zones: Vector
• summary: str

Example:

erosion, confidence, health, restoration, summary = wbe.terrain.workflow_products.river_corridor_health_assessment(
	dem=dem,
	streams=streams,
	profile="balanced",
)

GIS (Raster Overlay)

These tools compare or combine aligned raster stacks on a cell-by-cell basis. Use them when the rasters already share the same grid geometry and you want overlay-style summaries or index outputs.

Overlay Tool Index

• average_overlay
• count_if
• highest_position
• lowest_position
• max_absolute_overlay
• max_overlay
• min_absolute_overlay
• min_overlay
• multiply_overlay
• percent_equal_to
• percent_greater_than
• percent_less_than
• pick_from_list
• standard_deviation_overlay
• sum_overlay
• weighted_overlay
• weighted_sum

GIS (Raster Aggregation and Point-Block Rasterization)

These tools are GIS raster utilities but are not raster overlay operations. They aggregate rasters, create synthetic rasters, find extrema, interpolate from points, rasterize point blocks, or derive footprint geometries.

Aggregation and Block Tool Index

• aggregate_raster
• buffer_raster
• centroid_raster
• clump
• create_plane
• find_lowest_or_highest_points
• heat_map
• hexagonal_grid_from_raster_base
• hexagonal_grid_from_vector_base
• idw_interpolation
• layer_footprint_raster
• layer_footprint_vector
• map_features
• rectangular_grid_from_raster_base
• rectangular_grid_from_vector_base
• natural_neighbour_interpolation
• nearest_neighbour_interpolation
• modified_shepard_interpolation
• radial_basis_function_interpolation
• raster_cell_assignment
• nibble
• sieve
• tin_interpolation
• block_maximum
• block_minimum

find_lowest_or_highest_points

find_lowest_or_highest_points(input, output_type="lowest", output_path=None, callback=None)

Finds the lowest and/or highest raster cell locations and outputs them as vector points.

Parameters

Outputs

• return: Vector

WbEnvironment usage

result = wbe.vector.sampling_gridding.find_lowest_or_highest_points(
    input,
    output_type="value",
    output_path="result.tif",
)

aggregate_raster

aggregate_raster(input, aggregation_factor=2, aggregation_type="mean", output_path=None, callback=None)

Reduces raster resolution by aggregating fixed-size source blocks using mean, sum, maximum, minimum, or range.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.aggregate_raster(
    input,
    aggregation_factor=1,
    aggregation_type="value",
    output_path="result.tif",
)

create_plane

create_plane(base, gradient, aspect, constant, output_path=None, callback=None)

Creates a raster from a planar equation using a base raster for output geometry.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.create_plane(
    base,
    gradient=1.0,
    aspect=1.0,
    constant=1.0,
    output_path="result.tif",
)

centroid_raster

centroid_raster(input, output_path=None, callback=None)

Calculates centroid cells for positive patch IDs in a raster and returns both output raster and a textual report.

Parameters

Outputs

Returned as tuple[Raster, str] in this order:

• result: Raster
• string_2: str

WbEnvironment usage

raster_1, string_2 = wbe.raster.centroid_raster(
    input,
    output_path="result.tif",
)

buffer_raster

buffer_raster(input, buffer_size, grid_cell_units=False, output_path=None, callback=None)

Creates a binary buffer around non-zero, non-NoData raster cells.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.distance_cost.buffer_raster(
    input,
    buffer_size=1.0,
    output_path="result.tif",
)

clump

clump(input, diag=False, zero_background=False, output_path=None, callback=None)

Groups contiguous equal-valued raster cells into unique patch IDs.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.clump(
    input,
    output_path="result.tif",
)

nibble

nibble(input, mask, use_nodata=False, nibble_nodata=True, output_path=None, callback=None)

Fills background regions in a raster by propagating values from nearest foreground cells, constrained by a mask raster.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.nibble(
    input,
    mask,
    output_path="result.tif",
)

sieve

sieve(input, threshold=1.0, zero_background=False, output_path=None, callback=None)

Removes small raster patches below a cell-count threshold by replacing them with neighbouring larger-patch values.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.sieve(
    input,
    threshold=1.0,
    output_path="result.tif",
)

heat_map

heat_map(points, bandwidth, field_name=None, cell_size=None, base_raster=None, kernel_function="quartic", output_path=None, callback=None)

Generates a kernel-density heat map raster from point occurrences.

Parameters

Outputs

• return: Raster

WbEnvironment usage

result = wbe.raster.heat_map(
    points,
    bandwidth=1.0,
    field_name="value",
    cell_size=1.0,
    base_raster,
    kernel_function="value",
    output_path="result.tif",
)

idw_interpolation

idw_interpolation(points, field_name="FID", use_z=False, weight=2.0, radius=0.0, min_points=0, cell_size=None, base_raster=None, output_path=None, callback=None)

Interpolates a raster from point samples using inverse-distance weighting.

Parameters