Convolution

std.Convolution(vnode clip, float[] matrix[, float bias=0.0, float divisor=0.0, int[] planes=[0, 1, 2], bint saturate=True, string mode="s"])

Performs a spatial convolution.

Here is how a 3x3 convolution is done. Each pixel in the 3x3 neighbourhood is multiplied by the corresponding coefficient in matrix. The results of the nine multiplications are added together, then this sum is divided by divisor. Next, bias is added, and the result is rounded to the nearest larger integer. If this integer result is negative and the saturate parameter is False, it is multiplied by -1. Finally, the result is clamped to the format’s range of valid values.

clip

Clip to process. It must have integer sample type and bit depth between 8 and 16, or float sample type and bit depth of 32. If there are any frames with other formats, an error will be returned.

matrix

Coefficients for the convolution.

When mode is “s”, this must be an array of 9 or 25 numbers, for a 3x3 or 5x5 convolution, respectively.

When mode is not “s”, this must be an array of 3 to 25 numbers, with an odd number of elements.

The values of the coefficients must be between -1023 and 1023 (inclusive). The coefficients are rounded to integers when the input is an integer format.

This is how the elements of matrix correspond to the pixels in a 3x3 neighbourhood:

2 3
5 6
8 9

It’s the same principle for the other types of convolutions. The middle element of matrix always corresponds to the center pixel.

bias

Value to add to the final result of the convolution (before clamping the result to the format’s range of valid values).

divisor

Divide the output of the convolution by this value (before adding bias).

If this parameter is 0.0 (the default), the output of the convolution will be divided by the sum of the elements of matrix, or by 1.0, if the sum is 0.

planes

Specifies which planes will be processed. Any unprocessed planes will be simply copied.

saturate

The final result is clamped to the format’s range of valid values (0 .. (2**bitdepth)-1). Therefore, if this parameter is True, negative values become 0. If this parameter is False, it’s instead the absolute value that is clamped and returned.

mode

Selects the type of convolution. Possible values are “s”, for square, “h” for horizontal, “v” for vertical, and “hv” or “vh” for both horizontal and vertical.

How to apply a simple blur equivalent to Avisynth’s Blur(1):

Convolution(matrix=[1, 2, 1, 2, 4, 2, 1, 2, 1])

How to apply a stronger blur equivalent to Avisynth’s Blur(1.58):

Convolution(matrix=[1, 1, 1, 1, 1, 1, 1, 1, 1])