IG_IP_convolve

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 );

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); }

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.