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

IPSDKIPLFILTERING_API image::ImagePtr	ipsdk::imaproc::filter::convolution2dImg (const image::ImageConstPtr &pInImg, const KernelXYConstPtr &pInKnlXY, const bool inNormalize)
	wrapper function for convolution algorithm of input 2d image using a given kernel More...

IPSDKIPLFILTERING_API image::ImagePtr	ipsdk::imaproc::filter::convolution2dImg (const image::ImageConstPtr &pInImg, const KernelXYConstPtr &pInKnlXY, const bool inNormalize, const image::Border2dPolicyConstPtr &pInOptConvolBorder2d)
	wrapper function for convolution algorithm of input 2d image using a given kernel More...

IPSDKIPLFILTERING_API void	ipsdk::imaproc::filter::convolution2dImg (const image::ImageConstPtr &pInImg, const KernelXYConstPtr &pInKnlXY, const bool inNormalize, const image::ImagePtr &pOutImg)
	wrapper function for convolution algorithm of input 2d image using a given kernel More...

IPSDKIPLFILTERING_API void	ipsdk::imaproc::filter::convolution2dImg (const image::ImageConstPtr &pInImg, const KernelXYConstPtr &pInKnlXY, const bool inNormalize, const image::Border2dPolicyConstPtr &pInOptConvolBorder2d, const image::ImagePtr &pOutImg)
	wrapper function for convolution algorithm of input 2d image using a given kernel More...

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

Attributes description

Attribute description for algorithm :

Name	ToolTip	Default Initializer
ipsdk::imaproc::attr::InImg	[Input] image for processing operation	X
ipsdk::imaproc::attr::InKnlXY	[Input] kernel xy for processing operation	X
ipsdk::imaproc::attr::InNormalize	[Input] flag indicating whether convolution operation should be normalized (result divide by sum of abssolute values of kernel coefficients)	X
ipsdk::imaproc::attr::InOptConvolBorder2d	[Input Optional] Border preparation policy for 2d convolution algorithm	X
ipsdk::imaproc::attr::OutImg	[Output] image for processing operation	promoteUnary (_pOutImg, _pInImg, ipsdk::imaproc::ePromoteUnaryType::ePUT_UpperSigned)

Global Rule description

Global rule description for algorithm :
ipsdk::imaproc::matchSize (_pInImg,_pOutImg)

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

Associated library

IPSDKIPLFiltering

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

See also: Convolution2dImgLvl1; Convolution2dImgLvl2; Convolution2dImgLvl3

Function Documentation

◆ convolution2dImg() [1/4]

IPSDKIPLFILTERING_API image::ImagePtr ipsdk::imaproc::filter::convolution2dImg	(	const image::ImageConstPtr &	pInImg,
		const KernelXYConstPtr &	pInKnlXY,
		const bool	inNormalize
	)

wrapper function for convolution algorithm of input 2d image using a given kernel

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure

◆ convolution2dImg() [2/4]

IPSDKIPLFILTERING_API image::ImagePtr ipsdk::imaproc::filter::convolution2dImg	(	const image::ImageConstPtr &	pInImg,
		const KernelXYConstPtr &	pInKnlXY,
		const bool	inNormalize,
		const image::Border2dPolicyConstPtr &	pInOptConvolBorder2d
	)

wrapper function for convolution algorithm of input 2d image using a given kernel

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure

◆ convolution2dImg() [3/4]

IPSDKIPLFILTERING_API void ipsdk::imaproc::filter::convolution2dImg	(	const image::ImageConstPtr &	pInImg,
		const KernelXYConstPtr &	pInKnlXY,
		const bool	inNormalize,
		const image::ImagePtr &	pOutImg
	)

wrapper function for convolution algorithm of input 2d image using a given kernel

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure

◆ convolution2dImg() [4/4]

IPSDKIPLFILTERING_API void ipsdk::imaproc::filter::convolution2dImg	(	const image::ImageConstPtr &	pInImg,
		const KernelXYConstPtr &	pInKnlXY,
		const bool	inNormalize,
		const image::Border2dPolicyConstPtr &	pInOptConvolBorder2d,
		const image::ImagePtr &	pOutImg
	)

wrapper function for convolution algorithm of input 2d image using a given kernel

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure