ImageGear for C and C++ on Linux - Updated
IG_IP_convolve_matrix
API Reference Guide > Core Component API Reference > Core Component Functions Reference > Image Processing Functions > IG_IP_convolve_matrix

This function convolves the image using a user-defined convolution kernel.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_IP_convolve_matrix(
   HIGEAR hIGear,
   LPAT_RECT lpRect,
   LPAT_INT lpMatrix,
   UINT nMatrixWidth,
   UINT nMatrixHeight,
   DOUBLE dblNormalizer,
   AT_MODE nColorChannel,
   AT_MODE nResultForm,
   AT_BOOL bAddToOrigin
);

Arguments:

Name Type Description
hIGear HIGEAR HIGEAR handle of image to be processed.
lpRect LPAT_RECT Rectangle of image to process; setting to NULL will process the whole image.
lpMatrix LPAT_INT Pointer to the array of convolution kernel elements.
nMatrixWidth UINT Width of the convolution kernel.
nMatrixHeight UINT Height of the convolution kernel.
dblNormalizer DOUBLE Normalizer of the convolution kernel.
nColorChannel AT_MODE Specifies the color channel or group of channels to be processed. See enumIGColorChannels for possible values.
nResultForm AT_MODE Specifies how the result value should be stored. See enumIGConvolutionResults for possible values.
bAddToOrigin AT_BOOL Tells whether to add the result of the convolution to the pixel values.

Return Value:

Returns 0 if successful. Otherwise, returns the number of ImageGear errors that occurred during this function call.

Supported Raster Image Formats:

All pixel formats supported by ImageGear for C and C++.

Example:

 
Copy Code
HIGEAR hIGear;            // HIGEAR handle of the image
AT_ERRCOUNT nErrcount;    // Count of errs on stack upon ret from func

AT_INT         mxConv[5 * 3] =   // Convolution kernel
{
    1,1,1,1,1,
    -2,-2,-2,-2,-2,
    1,1,1,1,1
};

// Load image file "picture.bmp" from working directory
nErrcount = IG_load_file("picture.bmp", &hIGear);
if(nErrcount == 0)
{
    nErrcount = IG_IP_convolve_matrix(hIGear, NULL, mxConv, 5, 3, 1.0,
        IG_COLOR_COMP_RGB, IG_CONV_RESULT_RAW, FALSE);

    // ...
    // Destroy the image
    IG_image_delete(hIGear);
}

Remarks:

The result of the convolution is multiplied by the normalizer, dblNormalizer. For kernels that sum to zero, the normalizer is usually set to 1.0. When the sum is not zero, the normalizer's value will depend on the goal of convolution. In a non-weighted averaging convolution the kernel elements are often all ones. In this case the normalizer would be equal to 1/(sum of kernel). Remember that the normalizer is multiplied by the sum of the convolution and not divided into it.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular sub-region of an image. (See above.) However, before ImageGear performs the operation specified by this function, it will check to see if an internal NRA flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE, and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask.