riverarchitect.terraforming

Threshold-based terrain modification: grading and widening for planting.

The open-source replacement for the threshold-value part of the ArcGIS ModifyTerrain module (cModifyTerrain.lower_dem_for_plants).

The problem it solves

A lifespan map says a willow would survive at a cell if the water table were within reach of its roots. Where the ground stands too high above the water table it will not, and the answer is to lower the ground - grading, or widening the channel into a berm. This computes the resulting terrain: where a feature is planned and the depth to the water table exceeds what the feature tolerates, the DEM is lowered by exactly the excess, so that the cell ends up at the deepest tolerable depth to water and no lower.

\[\begin{split}z' = \begin{cases} z - (d_{2w} - d_{2w,\max}) & \text{where the feature applies and } d_{2w} > d_{2w,\max} \\ z & \text{elsewhere} \end{cases}\end{split}\]

Features are applied in sequence, and each works on the terrain the previous one left. That is what the original did, and it matters: lowering the ground also lowers its depth to the water table, so the second feature must see the first one’s excavation rather than the original DEM.

Pair the result with riverarchitect.volume_assessment to get the earthwork quantity.

Relation to the original

The whole of lower_dem_for_plants reduces to one nested Con, wrapped in a hundred lines of extent juggling, a cache folder and a four-deep try ladder that read the tolerated depth to water from up to four planting features. The ladder is planting_depth_limit() here, and it takes the minimum of the tolerances, as the original did - the terrain has to suit the most demanding species planned, not the least.

What is not here is RiverBuilder, the synthetic-valley generator that shares the original’s ModifyTerrain tab. It is a separate program with its own input format and is not part of this package; see the River Builder page of the legacy wiki.

class riverarchitect.terraforming.Terraforming(condition, action_dir, unit='us', d2w_max=None, features=None)[source]

Bases: object

Lower a DEM so that planned features reach the water table.

Parameters:

  • condition (Condition or str) – the condition, or its name. Supplies dem.tif and d2w.tif.

  • action_dir (str) – directory holding the best_<feature>.tif masks of riverarchitect.maxlifespan.MaxLifespan, which say where each feature is planned. Any raster whose finite cells mark an area will do.

  • unit (str) – "us" or "si"; must match the condition’s rasters.

  • d2w_max (float) – deepest tolerable depth to the water table. Defaults to planting_depth_limit().

  • features (list) – feature ids to apply, in order. Defaults to every mask found, alphabetically.

Variables:

error (bool) – True when at least one feature could not be applied.

apply_feature(dem, d2w, action)[source]

Lower one feature’s cells to the deepest tolerable depth to water.

Parameters:
Returns:

the modified terrain.

Return type:

numpy.ndarray

run(output_dir=None, write_rasters=True)[source]

Apply every feature in turn and report the terrain change.

Returns:

per_feature rows, the total cut volume, and the paths written.

Return type:

dict

riverarchitect.terraforming.planting_depth_limit(features=None, feature_ids=None)[source]

Deepest water table the planned plantings can still reach, in the condition’s units.

Parameters:
Returns:

the smallest d2w_max among them, or DEFAULT_D2W_MAX when none of them declares one.

Return type:

float

riverarchitect.terraforming.DEFAULT_D2W_MAX = 10.0

Depth to the water table used when no planting feature declares one, in feet. The original’s fallback, reached through the last except of its ladder.