convol_imageconvol_imageConvolImageConvolImage (Operator)


convol_imageconvol_imageConvolImageConvolImage — Calculate the correlation between an image and an arbitrary filter mask


convol_image(Image : ImageResult : FilterMask, Margin : )

Herror convol_image(const Hobject Image, Hobject* ImageResult, const char* FilterMask, const char* Margin)

Herror T_convol_image(const Hobject Image, Hobject* ImageResult, const Htuple FilterMask, const Htuple Margin)

void ConvolImage(const HObject& Image, HObject* ImageResult, const HTuple& FilterMask, const HTuple& Margin)

HImage HImage::ConvolImage(const HTuple& FilterMask, const HTuple& Margin) const

HImage HImage::ConvolImage(const HString& FilterMask, const HString& Margin) const

HImage HImage::ConvolImage(const char* FilterMask, const char* Margin) const

HImage HImage::ConvolImage(const wchar_t* FilterMask, const wchar_t* Margin) const   (Windows only)

static void HOperatorSet.ConvolImage(HObject image, out HObject imageResult, HTuple filterMask, HTuple margin)

HImage HImage.ConvolImage(HTuple filterMask, HTuple margin)

HImage HImage.ConvolImage(string filterMask, string margin)


convol_imageconvol_imageConvolImageConvolImageConvolImage calculates the correlation between the input image ImageImageImageImageimage and an arbitrary linear filter mask. The used filter mask, which is given in FilterMaskFilterMaskFilterMaskFilterMaskfilterMask, 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 (MarginMarginMarginMarginmargin): 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 FilterMaskFilterMaskFilterMaskFilterMaskfilterMask, 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 FilterMaskFilterMaskFilterMaskFilterMaskfilterMask 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 FilterMaskFilterMaskFilterMaskFilterMaskfilterMask:


For convenience, it is possible to pass two vectors instead of a matrix in FilterMaskFilterMaskFilterMaskFilterMaskfilterMask:


The outer product of those two vectors forms the filter matrix:

E.g., the matrix above can also be passed as:


If FilterMaskFilterMaskFilterMaskFilterMaskfilterMask is separable (which is detected automatically), convol_imageconvol_imageConvolImageConvolImageConvolImage uses a special implementation that is significantly faster than the filtering with non separable masks.

If 'sse2_enable'"sse2_enable""sse2_enable""sse2_enable""sse2_enable" is set to 'true'"true""true""true""true" (and the SIMD instruction set is available), the internal calculations for 'byte' and 'real' images are performed using SIMD technology. If 'sse41_enable'"sse41_enable""sse41_enable""sse41_enable""sse41_enable" is set to 'true'"true""true""true""true" (and the SIMD instruction set is available), the internal calculations for 'int2' and 'uint2' images are performed using SIMD technology. If 'avx_enable'"avx_enable""avx_enable""avx_enable""avx_enable" is set to 'true'"true""true""true""true" (and the SIMD instruction set is available), the internal calculations for 'real' images are performed using AVX SIMD technology.


Note that convol_imageconvol_imageConvolImageConvolImageConvolImage 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'"mirrored""mirrored""mirrored""mirrored", convol_imageconvol_imageConvolImageConvolImageConvolImage can be executed on OpenCL devices.

Note that filter operators may return unexpected results if an image with a reduced domain is used as input. Please refer to the chapter Filters.

Execution Information


ImageImageImageImageimage (input_object)  (multichannel-)image(-array) objectHImageHImageHobject (byte / int2 / uint2 / real)

Images for which the correlation will be calculated.

ImageResultImageResultImageResultImageResultimageResult (output_object)  multichannel-image(-array) objectHImageHImageHobject * (byte / int2 / uint2 / real)

Result of the correlation.

FilterMaskFilterMaskFilterMaskFilterMaskfilterMask (input_control) HTupleHTupleHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double)

Filter mask as file name or tuple.

Default value: 'sobel' "sobel" "sobel" "sobel" "sobel"

Suggested values: 'sobel'"sobel""sobel""sobel""sobel", 'laplace4'"laplace4""laplace4""laplace4""laplace4", 'lowpas_3_3'"lowpas_3_3""lowpas_3_3""lowpas_3_3""lowpas_3_3"

File extension: .fil

MarginMarginMarginMarginmargin (input_control)  string HTupleHTupleHtuple (string / integer / real) (string / int / long / double) (HString / Hlong / double) (char* / Hlong / double)

Border treatment.

Default value: 'mirrored' "mirrored" "mirrored" "mirrored" "mirrored"

List of values (for compute devices): 'mirrored'"mirrored""mirrored""mirrored""mirrored"

Suggested values: 'mirrored'"mirrored""mirrored""mirrored""mirrored", 'cyclic'"cyclic""cyclic""cyclic""cyclic", 'continued'"continued""continued""continued""continued", 0, 30, 60, 90, 120, 150, 180, 210, 240, 255