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

IPSDKIPLFILTERING_API image::ImagePtr	ipsdk::imaproc::filter::convolution3dImg (const image::ImageConstPtr &pInImg3d, const KernelXYZConstPtr &pInKnlXYZ, const bool inNormalize)
	wrapper function for convolution algorithm of input 3d image using a given kernel More...

IPSDKIPLFILTERING_API image::ImagePtr	ipsdk::imaproc::filter::convolution3dImg (const image::ImageConstPtr &pInImg3d, const KernelXYZConstPtr &pInKnlXYZ, const bool inNormalize, const image::Border3dPolicyConstPtr &pInOptConvolBorder3d)
	wrapper function for convolution algorithm of input 3d image using a given kernel More...

IPSDKIPLFILTERING_API void	ipsdk::imaproc::filter::convolution3dImg (const image::ImageConstPtr &pInImg3d, const KernelXYZConstPtr &pInKnlXYZ, const bool inNormalize, const image::ImagePtr &pOutImg)
	wrapper function for convolution algorithm of input 3d image using a given kernel More...

IPSDKIPLFILTERING_API void	ipsdk::imaproc::filter::convolution3dImg (const image::ImageConstPtr &pInImg3d, const KernelXYZConstPtr &pInKnlXYZ, const bool inNormalize, const image::Border3dPolicyConstPtr &pInOptConvolBorder3d, const image::ImagePtr &pOutImg)
	wrapper function for convolution algorithm of input 3d image using a given kernel More...

Detailed Description

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

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

Given an input 3d kernel :

$InKnlXYZ(o_{x}, o_{y}, o_{z}), \forall \left\{o_{x}, o_{y}, o_{z}\right\}\in \left [-\dfrac{n^{-}_{x}}{2},\dfrac{n^{+}_{x}}{2} \right ]\times \left [-\dfrac{n^{-}_{y}}{2},\dfrac{n^{+}_{y}}{2} \right ]\times \left [-\dfrac{n^{-}_{z}}{2},\dfrac{n^{+}_{z}}{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^{-}_{z}$ defines "negative" part of kernel elements along z axis (elements before central element)
$n^{+}_{z}$ defines "positive" part of kernel elements along z 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
$n_{z}=n^{-}_{z}+n^{+}_{z}$ defines kernel size along z axis

On output image values are given by:

$OutImg[x, y, z] = \sum_{o_{z}=-\dfrac{n_{z}}{2}}^{\dfrac{n_{z}}{2}}{\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}, z+o_{z}] \times InKnlXYZ[o_{x}, o_{y}, o_{z}]}}}$

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, z] = \dfrac{1}{K}\sum_{o_{z}=-\dfrac{n_{z}}{2}}^{\dfrac{n_{z}}{2}}{\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}, z+o_{z}] \times InKnlXYZ[o_{x}, o_{y}, o_{z}]}}}$

with :

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

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

Neighborhood border policy is controlled by $InOptConvolBorder3d$ parameter. This parameter allows to control starting and ending plans/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 :

$InKnlXYZ = \dfrac{1}{343}\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}^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::InImg3d	[Input] 3d image for operation	X
ipsdk::imaproc::attr::InKnlXYZ	[Input] kernel xyz 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::InOptConvolBorder3d	[Input Optional] Border preparation policy for 3d convolution algorithm	X
ipsdk::imaproc::attr::OutImg	[Output] image for processing operation	promoteUnary (_pOutImg, _pInImg3d, ipsdk::imaproc::ePromoteUnaryType::ePUT_UpperSigned)

Global Rule description

Global rule description for algorithm :
ipsdk::imaproc::matchSize (_pInImg3d,_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.rectangularKernelXYZ(1, 2, 1, [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,
                                                   -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, 
                                                   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 3d computation
    outImg = filter.convolution3dImg(inImg, inKnl, True)

Example of C++ code :

Example informations

Associated library

IPSDKIPLFiltering

Header file

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

Code Example

        // opening input image
        ImageGeometryPtr pInputImageGeometry = geometry3d(inputImageBufferType, sizeX, sizeY, sizeZ);
        ImagePtr pInImg = loadRawImageFile(inputImgPath, *pInputImageGeometry);
        
        // compute un-normalized convolution on input image
        ImagePtr pOutImg;
        if (pInOptConvolBorder3d.get() == 0)
            pOutImg = convolution3dImg(pInImg, pInKnlXYZ, false);
        else
            pOutImg = convolution3dImg(pInImg, pInKnlXYZ, false, pInOptConvolBorder3d);

See also: Convolution3dImgLvl1; Convolution3dImgLvl2; Convolution3dImgLvl3

Function Documentation

◆ convolution3dImg() [1/4]

IPSDKIPLFILTERING_API image::ImagePtr ipsdk::imaproc::filter::convolution3dImg	(	const image::ImageConstPtr &	pInImg3d,
		const KernelXYZConstPtr &	pInKnlXYZ,
		const bool	inNormalize
	)

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

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure

◆ convolution3dImg() [2/4]

IPSDKIPLFILTERING_API image::ImagePtr ipsdk::imaproc::filter::convolution3dImg	(	const image::ImageConstPtr &	pInImg3d,
		const KernelXYZConstPtr &	pInKnlXYZ,
		const bool	inNormalize,
		const image::Border3dPolicyConstPtr &	pInOptConvolBorder3d
	)

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

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure

◆ convolution3dImg() [3/4]

IPSDKIPLFILTERING_API void ipsdk::imaproc::filter::convolution3dImg	(	const image::ImageConstPtr &	pInImg3d,
		const KernelXYZConstPtr &	pInKnlXYZ,
		const bool	inNormalize,
		const image::ImagePtr &	pOutImg
	)

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

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure

◆ convolution3dImg() [4/4]

IPSDKIPLFILTERING_API void ipsdk::imaproc::filter::convolution3dImg	(	const image::ImageConstPtr &	pInImg3d,
		const KernelXYZConstPtr &	pInKnlXYZ,
		const bool	inNormalize,
		const image::Border3dPolicyConstPtr &	pInOptConvolBorder3d,
		const image::ImagePtr &	pOutImg
	)

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

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure