pygeoprocessing.kernels module

A library of kernels for use in pygeoprocessing.convolve_2d.

pygeoprocessing.convolve_2d has some stringent requirements for its kernels that require a thorough understanding of GDAL and GeoTiffs to be able to use, including:

Kernels must be GDAL-readable rasters, preferably GeoTiffs

Kernels must not be striped, and, for more efficient disk I/O, should be tiled.

The pixel values of a kernel may not represent nodata (GDAL’s internal way of indicating invalid pixel data)

Pixel values must be finite, real numbers. That is, they may not represent positive or negative infinity or NaN.

The functions in this module represent kernels that we have found to be commonly used, including:

Dichotomous kernel: dichotomous_kernel()

Gaussian (normal) decay kernel: normal_distribution_kernel()

Linear decay kernel: linear_decay_kernel()

Exponential decay kernel: exponential_decay_kernel()

Additionally, the user may define their own kernel using the helper functions included here:

kernel_from_numpy_array(), for kernels where the kernel array is already available as a numpy array, such as those used in common image processing operations like sharpening and edge detection. https://en.wikipedia.org/wiki/Kernel_(image_processing)

create_distance_decay_kernel(), for kernels that are a function of distance from the center pixel

pygeoprocessing.kernels.create_distance_decay_kernel(target_kernel_path: str, distance_decay_function: str | Callable, max_distance: int | float, normalize=True)[source]

Create a kernel raster based on pixel distance from the centerpoint.

Parameters:

target_kernel_path (string) – The path to where the target kernel should be written on disk. If this file does not have the suffix .tif, it will be added to the filepath.
distance_decay_function (callable or str) –
A python callable that takes as input a single 1D numpy array and returns a 1D numpy array. The input array will contain float32 distances to the centerpoint pixel of the kernel, in units of pixels. If a str, then it must be a python expression using the local variables:
- dist - a 1D numpy array of distances from the centerpoint.
- max_dist - a float indicating the max distance.
max_distance (float) – The maximum distance of kernel values from the center point. Values outside of this distance will be set to 0.0.
normalize=False (bool) – Whether to normalize the resulting kernel.

Returns:

None

pygeoprocessing.kernels.dichotomous_kernel(target_kernel_path: str, max_distance: int | float, normalize: bool = True) → None[source]

Create a binary kernel indicating presence/absence within a distance.

This is equivalent to int(dist <= max_distance) for each pixel in the kernel, where dist is the euclidean distance of the pixel’s centerpoint to the centerpoint of the center pixel.

Parameters:

target_kernel_path – The path to where the kernel will be written. Must have a file extension of .tif.
max_distance – The distance threshold, in pixels. Kernel pixels that are greater than max_distance from the centerpoint of the kernel will have values of 0.0.
normalize – Whether to normalize the kernel.

Returns:

None

pygeoprocessing.kernels.exponential_decay_kernel(target_kernel_path: str, max_distance: int | float, expected_distance: int | float, normalize: bool = True) → None[source]

Create an exponential decay kernel.

This is equivalent to e**(-dist / expected_distance) for each pixel in the kernel, where dist is the euclidean distance of the pixel’s centerpoint to the centerpoint of the center pixel and expected_distance represents the distance at which the kernel’s values reach 1/e. The kernel will continue to have nonzero values out to max_distance.

Parameters:

target_kernel_path – The path to where the kernel will be written. Must have a file extension of .tif.
max_distance – The maximum distance of the kernel, in pixels. Kernel pixels that are greater than max_distance from the centerpoint of the kernel will have values of 0.0.
expected_distance – The distance, in pixels, from the centerpoint at which decayed values will equal 1/e.
normalize – Whether to normalize the kernel.

Returns:

None

Create a convolution kernel from a numpy array.

Parameters:

numpy_array – A 2-dimensional numpy array to convert into a raster.
target_kernel_path – The path to where the kernel should be written.

Returns:

None

pygeoprocessing.kernels.linear_decay_kernel(target_kernel_path: str, max_distance: int | float, normalize: bool = True) → None[source]

Create a linear decay kernel.

This is equivalent to (max_distance - dist) / max_distance for each pixel in the kernel, where dist is the euclidean distance between the centerpoint of the current pixel and the centerpoint of the center pixel in the kernel.

Parameters:

target_kernel_path – The path to where the kernel will be written. Must have a file extension of .tif.
max_distance – The maximum distance of the kernel, in pixels. Kernel pixels that are greater than max_distance from the centerpoint of the kernel will have values of 0.0.
normalize – Whether to normalize the kernel.

Returns:

None

pygeoprocessing.kernels.normal_distribution_kernel(target_kernel_path: str, sigma: int | float, n_std_dev: int | float = 3, normalize: bool = True)[source]

Create an decay kernel following a normal distribution.

This is equivalent to (1/(2*pi*sigma**2))*(e**((-dist**2)/(2*sigma**2))) for each pixel, where dist is the euclidean distance between the current pixel and the centerpoint of the center pixel.

Parameters:

target_kernel_path – The path to where the kernel will be written. Must have a file extension of .tif.
sigma – The width (in pixels) of a standard deviation.
n_std_dev – The number of standard deviations to include in the kernel. The kernel will have values of 0 when at a distance of (sigma * n_std_dev) away from the centerpoint.
normalize – Whether to normalize the kernel.

Returns:

None