image =	convolution3dImg (inImg3d,inKnlXYZ,inNormalize)
image =	convolution3dImg (inImg3d,inKnlXYZ,inNormalize,inOptConvolBorder3d)

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

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

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