image =	convolution2dImg (inImg,inKnlXY,inNormalize)
image =	convolution2dImg (inImg,inKnlXY,inNormalize,inOptConvolBorder2d)

Detailed Description

Compute convolution of an input 2d image with a kernel.

See Kernels for a detailled documentation of kernels creation and management tools.

Given an input 2d kernel :

$InKnlXY(o_{x}, o_{y}), \forall \left\{o_{x}, o_{y}\right\}\in \left [-\dfrac{n^{-}_{x}}{2},\dfrac{n^{+}_{x}}{2}\right ]\times\left [-\dfrac{n^{-}_{y}}{2},\dfrac{n^{+}_{y}}{2}\right ]$

Where :

$n^{-}_{x}$ defines "negative" part of kernel elements along x axis (elements before central element)
$n^{+}_{x}$ defines "positive" part of kernel elements along x axis (elements after central element)
$n^{-}_{y}$ defines "negative" part of kernel elements along y axis (elements before central element)
$n^{+}_{y}$ defines "positive" part of kernel elements along y axis (elements after central element)
$n_{x}=n^{-}_{x}+n^{+}_{x}$ defines kernel size along x axis
$n_{y}=n^{-}_{y}+n^{+}_{y}$ defines kernel size along y axis

Example of square kernel with $n^{-}_{x}=n^{+}_{x}=n^{-}_{y}=n^{+}_{y}=2$ (unsharp making kernel) :

$InKnlXY = -\dfrac{1}{256} \begin{bmatrix} 1 & 4 & 6 & 4 & 1 \\ 4 & 16 & 24 & 16 & 4 \\ 6 & 24 & -476 & 24 & 6 \\ 4 & 16 & 24 & 16 & 4 \\ 1 & 4 & 6 & 4 & 1 \end{bmatrix}$

Example of square kernel with $n^{-}_{x}=n^{+}_{x}=1$ and $n^{-}_{y}=n^{+}_{y}=0$ (linear box filter kernel) :

$InKnlXY = \dfrac{1}{3} \begin{bmatrix} 1 & 1 & 1 \end{bmatrix}$

On output image values are given by:

$OutImg[x, y] = \sum_{o_{y}=-\dfrac{n_{y}}{2}}^{\dfrac{n_{y}}{2}}{\sum_{o_{x}=-\dfrac{n_{x}}{2}}^{\dfrac{n_{x}}{2}}{InImg[x+o_{x}, y+o_{y}] \times InKnlXY[o_{x}, o_{y}]}}$

Input kernel coefficients can be normalized during processing if $InNormalize$ value is set to $true$ . In this case previous formula is modified into :

$OutImg[x, y] = \dfrac{1}{K}\sum_{o_{y}=-\dfrac{n_{y}}{2}}^{\dfrac{n_{y}}{2}}{\sum_{o_{x}=-\dfrac{n_{x}}{2}}^{\dfrac{n_{x}}{2}}{InImg[x+o_{x}, y+o_{y}] \times InKnlXY[o_{x}, o_{y}]}}$

with :

$K = \sum_{o_{y}=-\dfrac{n_{y}}{2}}^{\dfrac{n_{y}}{2}}{\sum_{o_{x}=-\dfrac{n_{x}}{2}}^{\dfrac{n_{x}}{2}}{InKnlXY[o_{x}, o_{y}]}}$

Case of $K=0$ is handled forcing its value to $K=1$ to avoid null division.

Neighborhood border policy is controlled by $InOptConvolBorder2d$ parameter. This parameter allows to control starting and ending rows/columns provided data during processing (see Border policy for more details).

Here is an example of a normalized convolution operation applied to an 8-bits grey levels input image with input kernel given by :

$InKnlXY = \dfrac{1}{49}\left( \begin{bmatrix} 1 & 1 & 1 & 1 & 1 & 1 & 1 \end{bmatrix}^T \times \begin{bmatrix} 1 & 1 & 1 & 1 & 1 & 1 & 1 \end{bmatrix} \right)$

See also: http://en.wikipedia.org/wiki/Kernel_%28image_processing%29; http://en.wikipedia.org/wiki/Convolution

Example of Python code :

Example imports

import PyIPSDK

import PyIPSDK.IPSDKIPLFiltering as filter

Code Example

    # opening of input images
    inImg = PyIPSDK.loadTiffImageFile(inputImgPath)
    
    # create a processing kernel
    inKnl = PyIPSDK.rectangularKernelXY(1, 2, [1.5, 1.2, 1.4,
                                               4.2, 7.0, 2.3,
                                               3.5, 4.8, 7.5,
                                               1.9, 2.3, 6.3,
                                               9.5, 0.2, 4.1])
    
    # convolution filter 2d computation
    outImg = filter.convolution2dImg(inImg, inKnl, True)

Example of C++ code :

Example informations

Header file

#include <IPSDKIPL/IPSDKIPLFiltering/Processor/Convolution2dImg/Convolution2dImg.h>

Code Example

        // opening input image
        ImageGeometryPtr pInputImageGeometry = geometry2d(inputImageBufferType, sizeX, sizeY);
        ImagePtr pInImg = loadRawImageFile(inputImgPath, *pInputImageGeometry);
        
        // compute un-normalized convolution on input image
        ImagePtr pOutImg;
        if (pInOptConvolBorder2d.get() == 0)
            pOutImg = convolution2dImg(pInImg, pInKnlXY, false);
        else
            pOutImg = convolution2dImg(pInImg, pInKnlXY, false, pInOptConvolBorder2d);