License Information

Use of this function requires a license for Whitebox Workflows for Python Professional (WbW-Pro). Please visit www.whiteboxgeo.com to purchase a license.

Description

This tool creates an interactive animation that demonstrates the variation in deviation from mean elevation (DEV, DevFromMeanElev) as scale increases across a range for an input digital elevation model (input). DEV is calculated as the difference between the elevation of each grid cell and the mean elevation of the centering local neighbourhood, normalized by standard deviation and is a measure of local topographic position. DEV is useful for highlighting locally prominent (either elevated or low-lying) locations within a landscape. Topographic position animations are extemely useful for interpreting landscape geomorphic structure across a range of scales.

The set of scales for which DEV is measured (using varying filter sizes) is determined by the three user-specified parameters, including min_scale, num_steps, and step_nonlinearity. Experience with DEV scale signatures has shown that it is highly variable at shorter scales and changes more gradually at broader scales. Therefore, a nonlinear scale sampling interval is used by this tool to ensure that the scale sampling density is higher for short scale ranges and coarser at longer tested scales, such that:

ri = rL + (i - rL)p

Where ri is the filter radius for step i, rL is the lower range of filter sizes (min_scale), and p is the nonlinear scaling factor (step_nonlinearity).

The tool can be run in one of two modes: using regular DEV calculations, or using DEVmax (max_elevation_deviation), a multiscale version of DEV that outputs the maximum absolute value of DEV encountered across a range of tested scales. Use the dev_max flag to run the tool in DEVmax mode.

The output (output) of this tool is an HTML file, containing the interactive GIF animation. Users are able to zoom and pan around the displayed DEV animation. The DEV images may be rendered in one of several available palettes (palette) suitable for visualization DEV. The output DEV/DEVmax animation will also be hillshaded to further enchance topographic interpretation. The user must also specify the image height (height) in the output file, the time delay (delay, in milliseconds) used in the GIF animation, and an optional label (label), which will appear in the upper lefthand corner. Note that the output is simply HTML, CSS, javascript code, and a GIF file, which can be readily embedded in other documents.

Users should be aware that the outut GIF can be very large in size, depending on the size of the input DEM file. To reduce the file size of the output, it may be desirable to coarsen the input DEM resolution using image resampling (resample).

The following is an example of what the output of this tool looks like. Click the image for an interactive example.

For more information about this tool and example outputs, see this blog on the WhiteboxTools homepage.

See Also

DevFromMeanElev, max_elevation_deviation

Function Signature

def topographic_position_animation(self, dem: Raster, output_html_file: str = "topo_pos.html", palette: WbPalette = WbPalette.Soft, min_scale: int = 1, num_steps: int = 1, step_nonlinearity: float = 1.0, image_height: int = 600, delay: int = 250, label: str = "", use_dev_max: bool = False) -> None: ...

Project Links

WbW Homepage User Manual Support WbW