convol_image — Calculate the correlation between an image and an arbitrary filter mask
convol_image calculates the correlation between the input image Image and an arbitrary linear filter mask. The used filter mask, which is given in FilterMask, can be either loaded from a file or passed as a tuple. Several options for the treatment at the image's borders can be chosen (Margin):
gray value Pixels outside of the image border are assumed to be constant (with the indicated gray value). 'continued' Continuation of the gray values at the image border. 'cyclic' Cyclic continuation at the image border. 'mirrored' Reflection of pixels at the image border.At all image positions, the correlation between the image and the filter mask is calculated. If an overflow or underflow occurs, the resulting gray value is clipped. Hence, if filters that result in negative output values are used (e.g., derivative filters), the input image should be of type int2 or real.
The reference pixel of the mask, i.e., the pixel that lies at the current image position for which the correlation is calculated, is determined as follows: First, the region of all mask pixels with a weight other than 0 is computed. Then, the center of this region is computed and rounded. This is the reference point of the mask.
If a file name is given in FilterMask, the filter mask is read from a text file with the following structure:
<Mask size> <Inverse weight of the mask> <Matrix>The first line contains the size of the filter mask, given as two numbers separated by white space (e.g., 3 3 for 3 x 3). Here, the first number defines the height (rows) of the filter mask, while the second number defines its width (columns). The next line contains the inverse weight of the mask, i.e., the number by which the correlation at a particular image position is divided. The remaining lines contain the filter mask as integer or floating point numbers (separated by white space), one line of the mask per line in the file. The default HALCON file extension for the filter mask is 'fil'. It is not necessary to pass this extension to the operator. If the filter mask is to be computed from a tuple, the tuple given in FilterMask must also satisfy the structure described above. However, in this case the line feed is omitted.
For example, lets assume we want to use the following filter mask:
If the filter mask should be generated from a file, then the file should look like this:
3 3 16 1 2 1 2 4 2 1 2 1
In contrast, if the filter mask should be generated from a tuple, then the following tuple must be passed in FilterMask:
For convenience, it is possible to pass two vectors instead of a matrix in FilterMask:
The outer product of those two vectors forms the filter matrix:
E.g., the matrix above can also be passed as:
If FilterMask is separable (which is detected automatically), convol_image uses a special implementation that is significantly faster than the filtering with non separable masks.
If 'sse2_enable' is set to 'true' (and the SIMD instruction set is available), the internal calculations for 'byte' and 'real' images are performed using SIMD technology. If 'sse41_enable' is set to 'true' (and the SIMD instruction set is available), the internal calculations for 'int2' and 'uint2' images are performed using SIMD technology. If 'avx_enable' is set to 'true' (and the SIMD instruction set is available), the internal calculations for 'real' images are performed using AVX SIMD technology.
Note that convol_image does not compute a convolution of the image with the given filter mask but a correlation, i.e., it uses the given filter mask directly, not a mirrored version of the filter mask.
When using a 3x3 or 5x5 rectangular filter mask and the border treatment 'mirrored', convol_image can be executed on OpenCL devices.
Images for which the correlation will be calculated.
Result of the correlation.
Filter mask as file name or tuple.
Default value: 'sobel'
Suggested values: 'sobel', 'laplace4', 'lowpas_3_3'
File extension: .fil
Default value: 'mirrored'
List of values (for compute devices): 'mirrored'
Suggested values: 'mirrored', 'cyclic', 'continued', 0, 30, 60, 90, 120, 150, 180, 210, 240, 255