add --weights option to D8FlowAccumulation tool

[mholling]

This patch adds a --weights option to the D8FlowAccumulation tool. A raster containing weight values is provided as the argument:

whitebox_tools --run=D8FlowAccumulation --input=d8_pnt.tif --output=d8_acc.tif --weights=weights.tif --pntr

The weights raster is used to reduce flow accumulation in areas where the weight is less than one. For example, I am using this patch to produce less accumulation in flat areas. I generate a slope raster, and then re-scale it using a ramp function, giving a unit weighting above 15% gradient, down to an 0.2 weighting below 5% gradient:

whitebox_tools --run=Slope --input=dem.tif --output=gradient.tif --units=percent
whitebox_tools --run=RescaleValueRange --input=gradient.tif --output=weights.tif --clip_min=5 --clip_max=15 --out_min_val=0.2 --out_max_val=1.0

I extract streams for topographic maps using this method. The weighting reduces streams in flat areas and looks more natural on the map.

[jblindsay]

There is already a tool for doing this. It's called D8MassFlux, with a corresponding tool for Dinf as well.

[mholling]

Oh, very interesting! I don't think I'd seen that tool. So the weights in my example correspond to the D8MassFlux loading raster. Alternatively, I could use the efficiency raster to attenuate accumulation in flat areas.

I think there might still be a place for my suggested feature. The D8MassFlux tool uses more rasters, which is a burden on memory when running large DEMs. But also, specifically for stream extraction, that tool doesn't give you the flow pointer raster. This is needed by RasterStreamsToVector to create stream vectors. (And also ShreveStreamMagnitude, which I use to add a size attribute for the vectors.)

Alternatively, could the D8MassFlux tool be made to use a flow pointer as input, instead of a DEM? (As per D8FlowAccumulation with the --pntr switch.) Or, could it optionally save its flow pointer as a second output raster?