convol_imageconvol_imageconvol_imageConvolImageConvolImage (Operator)

Name

convol_imageconvol_imageconvol_imageConvolImageConvolImage — Convolve an image with an arbitrary filter mask.

Signature

Description

convol_imageconvol_imageconvol_imageConvolImageConvolImage convolves the input image ImageImageImageImageimage with an arbitrary linear filter. The corresponding filter mask, which is given in FilterMaskFilterMaskFilterMaskFilterMaskfilterMask, can be generated either from a file or a tuple. Several options for the treatment at the image's borders can be chosen (MarginMarginMarginMarginmargin):

    gray value   Pixels outside of the image edges
                 are assumed to be constant (with the
                 indicated gray value).
    'continued'  Continuation of edge pixels.
    'cyclic'     Cyclic continuation of image edges.
    'mirrored'   Reflection of pixels at the image edges.

All image points are convolved with the filter mask. 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 on the currently convolved image pixel, 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 of the filter mask, while the second number defines its width. The next line contains the inverse weight of the mask, i.e., the number by which the convolution of a particular image point is divided. The remaining lines contain the filter mask as integer 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:

        |1 2 1|
   1/16 |2 4 2|
        |1 2 1|

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:

[3,3,16,1,2,1,2,4,2,1,2,1]

Attention

When using a 3x3 or 5x5 rectangular filter mask and the border treatment 'mirrored'"mirrored""mirrored""mirrored""mirrored", convol_imageconvol_imageconvol_imageConvolImageConvolImage can be executed on OpenCL devices.

Parallelization

• Supports OpenCL compute devices.
• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Multithreading scope: global (may be called from any thread).
• Automatically parallelized on tuple level.
• Automatically parallelized on channel level.
• Automatically parallelized on internal data level.

Parameters

Module

Foundation