This tool can be used to perform a convolution-type filter where the weights of the moving window, or kernel, are specified by the user. As such, this tool provides a convenient means of creating a custom filter or performing a filter type that is not currently available as a standard tool in Whitebox. The user must specify the names of the input and output images, the kernel weights text file, the location of the center of the kernel (defaults to center of window but you can also specify one of the corners), whether or not to reflect image data at the image edges, and if normalization of kernel weights should be applied. The custom weights are derived from a text file containing a rectangular table of weight values. The table columns can be delimited using either tabs, spaces, or commas. If a particular cell in the kernel should be ignored (e.g. if a non-rectangular kernel is desired) then a non-numeric value (e.g. X) or a zero should be entered. The following is an example of the contents of a kernel text file for a 9 x 9 rounded filter:
X, X, 1, 1, 1, 1, 1, X, X
X, 1, 2, 3, 3, 3, 2, 1, X
1, 2, 3, 6, 7, 6, 3, 2, 1
1, 3, 6, 9, 11, 9, 6, 3, 1
1, 3, 7, 11, 12, 11, 7, 3, 1
1, 3, 6, 9, 11, 9, 6, 3, 1
1, 2, 3, 6, 7, 6, 3, 2, 1
X, 1, 2, 3, 3, 3, 2, 1, X
X, X, 1, 1, 1, 1, 1, X, X
NoData values in the input image are ignored during the convolution operation. This can lead to unexpected behavior at the edges of images (since the default behavior is to return NoData when addressing cells beyond the grid edge) and where the grid contains interior areas of NoData values. The option to reflect image data at the edges can be useful in this regard. Normalization can also be useful for handling the edge effects associated with interior areas of NoData values. When the normalization option is selected, the sum of the cell value-weight product is divided by the sum of the weights on a cell-by-cell basis. Therefore, if the kernel at a particular grid cell contains neighboring cells of NoData values, normalization effectively re-adjusts the weighting to account for the missing data values. Normalization also ensures that the output image will possess values within the range of the input image and allows the user to specify integer value weights in the kernel.
This is an example of a Python script using this tool:
wd = pluginHost.getWorkingDirectory()
input_file = wd + "input.dep"
output_file = wd + "output.dep"
kernel_file = wd + "filter_kernel.txt"
kernel_origin = "kernel center"
reflect_edges = "true"
normalize = "true"
parallel_proc = "true"
args = [input_file, output_file, kernel_file, kernel_origin, reflect_edges, normalize, parallel_proc]
pluginHost.runPlugin("FilterUserDefinedWeights", args, False)
And the following is a Groovy script also using this tool:
def wd = pluginHost.getWorkingDirectory()
def inputFile = wd + "input.dep"
def outputFile = wd + "output.dep"
def kernelFile = wd + "filter_kernel.txt"
def kernelOrigin = "kernel center"
def reflectEdges = "true"
def normalize = "true"
def parallelProc = "true"
String[] args = [inputFile, outputFile, kernelFile, kernelOrigin, reflectEdges, normalize, parallelProc]
pluginHost.runPlugin("FilterUserDefinedWeights", args, false)