IPSDK  4_1_0_2
IPSDK : Image Processing Software Development Kit
Classes | Enumerations | Functions
Kernels
IPSDK concepts » Image processing

Kernels management. More...

Classes

class  ipsdk::BaseKernel
 Base class for kernel objects. More...
 
class  ipsdk::KernelXY
 Class encapsulating a 2d kernel spanning along x and y axis. More...
 
class  ipsdk::KernelXYZ
 Class encapsulating a 3d kernel spanning along x, y and z axis. More...
 

Enumerations

enum  ipsdk::eSobelKernelType { ipsdk::eSKT_ScharrHalfKnlSz1, ipsdk::eSKT_SobelHalfKnlSz1, ipsdk::eSKT_SobelHalfKnlSz2, ipsdk::eSKT_SobelHalfKnlSz3 }
 Enumerate describing Sobel gradient kernels. More...
 
enum  ipsdk::eKernelType { ipsdk::eKT_XY, ipsdk::eKT_XYZ }
 Enumerate describing kernel type. More...
 

Functions

IPSDKBASEDATA_API void ipsdk::separableGaussianSmoothing (const ipReal32 stdDevX, const ipReal32 stdDevY, const ipReal32 gaussianRatio, const ipUInt32 minHalfKernelSize, KernelXYPtr &pXAxisKernel, KernelXYPtr &pYAxisKernel)
 function allowing to generate a separable 2d gaussian kernel used for smoothing operation More...
 
IPSDKBASEDATA_API void ipsdk::separableGaussianSmoothing (const ipReal32 stdDevX, const ipReal32 stdDevY, const ipReal32 stdDevZ, const ipReal32 gaussianRatio, const ipUInt32 minHalfKernelSize, KernelXYZPtr &pXAxisKernel, KernelXYZPtr &pYAxisKernel, KernelXYZPtr &pZAxisKernel)
 function allowing to generate a separable 3d gaussian kernel used for smoothing operation More...
 
IPSDKBASEDATA_API void ipsdk::separableGaussianGradient (const ipReal32 stdDevX, const ipReal32 stdDevY, const ipReal32 gaussianRatio, const ipUInt32 minHalfKernelSize, KernelXYPtr &pXAxisKernel, KernelXYPtr &pYAxisKernel)
 function allowing to generate a separable 2d gaussian kernel used for gradient computation operation More...
 
IPSDKBASEDATA_API void ipsdk::separableGaussianGradient (const ipReal32 stdDevX, const ipReal32 stdDevY, const ipReal32 stdDevZ, const ipReal32 gaussianRatio, const ipUInt32 minHalfKernelSize, KernelXYZPtr &pXAxisKernel, KernelXYZPtr &pYAxisKernel, KernelXYZPtr &pZAxisKernel)
 function allowing to generate a separable 3d gaussian kernel used for gradient computation operation More...
 
IPSDKBASEDATA_API void ipsdk::separableGaussianHessian (const ipReal32 stdDevX, const ipReal32 stdDevY, const ipReal32 gaussianRatio, const ipUInt32 minHalfKernelSize, KernelXYPtr &pXAxisKernel, KernelXYPtr &pYAxisKernel)
 function allowing to generate a separable 2d Hessian kernel used for Hessian computation operation More...
 
IPSDKBASEDATA_API void ipsdk::separableGaussianHessian (const ipReal32 stdDevX, const ipReal32 stdDevY, const ipReal32 stdDevZ, const ipReal32 gaussianRatio, const ipUInt32 minHalfKernelSize, KernelXYZPtr &pXAxisKernel, KernelXYZPtr &pYAxisKernel, KernelXYZPtr &pZAxisKernel)
 function allowing to generate a separable 3d Hessian kernel used for Hessian computation operation More...
 
IPSDKBASEDATA_API KernelXYPtr ipsdk::rotate2dKernel (const ipReal32 theta, const KernelXYConstPtr pKnl)
 function allowing to create a rotated version of the input 2d kernel
 
IPSDKBASEDATA_API void ipsdk::separableSobelSmoothing (const eSobelKernelType &kernelType, KernelXYPtr &pXAxisKernel, KernelXYPtr &pYAxisKernel)
 function allowing to generate a separable 2d Sobel kernel used for smoothing operation
 
IPSDKBASEDATA_API void ipsdk::separableSobelSmoothing (const eSobelKernelType &kernelType, KernelXYZPtr &pXAxisKernel, KernelXYZPtr &pYAxisKernel, KernelXYZPtr &pZAxisKernel)
 function allowing to generate a separable 3d Sobel kernel used for smoothing operation
 
IPSDKBASEDATA_API void ipsdk::separableSobelGradient (const eSobelKernelType &kernelType, KernelXYPtr &pXAxisKernel, KernelXYPtr &pYAxisKernel)
 function allowing to generate a separable 2d Sobel kernel used for gradient computation operation
 
IPSDKBASEDATA_API void ipsdk::separableSobelGradient (const eSobelKernelType &kernelType, KernelXYZPtr &pXAxisKernel, KernelXYZPtr &pYAxisKernel, KernelXYZPtr &pZAxisKernel)
 function allowing to generate a separable 3d Sobel kernel used for gradient computation operation
 
IPSDKBASEDATA_API KernelXYPtr ipsdk::squareKernelXY (const ipUInt32 halfKernelSize, const Real32Vector &valueColl, const ipBool bKeepNullValue=false)
 function allowing to generate a square XY kernel More...
 
IPSDKBASEDATA_API KernelXYPtr ipsdk::rectangularKernelXY (const ipUInt32 halfKernelSizeX, const ipUInt32 halfKernelSizeY, const Real32Vector &valueColl, const ipBool bKeepNullValue=false)
 function allowing to generate a rectangular XY kernel More...
 
IPSDKBASEDATA_API KernelXYPtr ipsdk::linearKernelXY (const ipReal32 theta, const Real32Vector &valueColl, const ipBool bKeepNullValue=false)
 function allowing to generate a linear oriented XY kernel with a given number of elements. More...
 
IPSDKBASEDATA_API KernelXYPtr ipsdk::linearInterpolatedKernelXY (const ipReal32 theta, const Real32Vector &valueColl, const ipBool bKeepNullValue=false)
 function allowing to generate a linear oriented XY kernel with interpolated coefficients. More...
 
IPSDKBASEDATA_API KernelXYZPtr ipsdk::cubicKernelXYZ (const ipUInt32 halfKernelSize, const Real32Vector &valueColl, const ipBool bKeepNullValue=false)
 function allowing to generate a cubic XYZ kernel More...
 
IPSDKBASEDATA_API KernelXYZPtr ipsdk::rectangularKernelXYZ (const ipUInt32 halfKernelSizeX, const ipUInt32 halfKernelSizeY, const ipUInt32 halfKernelSizeZ, const Real32Vector &valueColl, const ipBool bKeepNullValue=false)
 function allowing to generate a rectangular parallelepiped XYZ kernel More...
 
IPSDKBASEDATA_API KernelXYZPtr ipsdk::linearKernelXYZ (const ipReal32 theta, const ipReal32 phi, const Real32Vector &valueColl, const ipBool bKeepNullValue=false)
 function allowing to generate a linear oriented XYZ kernel with a given number of elements. More...
 
IPSDKBASEDATA_API KernelXYZPtr ipsdk::linearInterpolatedKernelXYZ (const ipReal32 theta, const ipReal32 phi, const Real32Vector &valueColl, const ipBool bKeepNullValue=false)
 function allowing to generate a linear oriented XYZ kernel with interpolated coefficients. More...
 
typedef boost::shared_ptr< KernelXY > ipsdk::KernelXYPtr
 shared pointer to KernelXY
 
typedef boost::shared_ptr< const KernelXY > ipsdk::KernelXYConstPtr
 shared pointer to KernelXY
 
typedef boost::shared_ptr< KernelXYZ > ipsdk::KernelXYZPtr
 shared pointer to KernelXYZ
 
typedef boost::shared_ptr< const KernelXYZ > ipsdk::KernelXYZConstPtr
 shared pointer to KernelXYZ
 

Detailed Description

Kernels management.

Definition

Introduction

A kernel is a matrix (which may be dense or sparse) used in image convolution operations. Content of such a matrix allows image processing operations such as : blurring, sharpening, edge detection, etc.

See also
https://en.wikipedia.org/wiki/Kernel_(image_processing)

Using kernels

In 2d case, a kernel is associated to class ipsdk::KernelXY and is represented by a collection of offsets which is associated to class ipsdk::OffsetXY defining its shape, each offset being associated to a value.

In 3d case, a kernel is associated to class ipsdk::KernelXYZ and its collection of offsets is simply replaced by a class ipsdk::OffsetXYZ.

The following examples illustrates the definition of a 2d square user custom kernel given by :

\[ \begin{bmatrix} -1 & 0 & 1 \\ -1 & 0 & 1 \\ -1 & 0 & 1 \end{bmatrix} \]

#include <IPSDKBaseData/Pattern/Kernel/KernelUtils.h>
using namespace ipsdk;
void testCustomKernel()
{
const ipInt32 halfKernelSize = 1;
const ipInt32 kernelSize = 2 * halfKernelSize + 1;
Real32Vector valueColl(kernelSize * kernelSize);
valueColl[0] = -1; valueColl[1] = 0; valueColl[2] = 1;
valueColl[3] = -1; valueColl[4] = 0; valueColl[5] = 1;
valueColl[6] = -1; valueColl[7] = 0; valueColl[8] = 1;
// create kernel
// (note that null values are ignored)
KernelXYConstPtr pKernel = squareKernelXY(halfKernelSize, valueColl);
}

The same kernel creation can be written in Python:

import PyIPSDK
# create kernel
# (note that null values are ignored)
valueColl = [-1, 0, 1,
-1, 0, 1,
-1, 0, 1]
kernel = PyIPSDK.squareKernelXY(1, valueColl)
# display associated content
print(str(kernel))

The following C++ example illustrates the definition of two separable gaussian kernels which can be used for smoothing operation :

#include <IPSDKBaseData/Pattern/Kernel/Instances/GaussianKernel.h>
using namespace ipsdk;
void testGaussianKernel()
{
const ipReal32 stdDevX = 1.5f;
const ipReal32 stdDevY = 1.5f;
const ipReal32 gaussianRatio = 0.997f;
const ipUInt32 minHalfKernelSize = 2;
// create kernels
KernelXYConstPtr pKernelX, pKernelY;
separableGaussianSmoothing(stdDevX, stdDevY, gaussianRatio, minHalfKernelSize, pKernelX, pKernelY);
}

The translation in Python is:

import PyIPSDK
# create kernels
kernelX, kernelY = PyIPSDK.separableGaussianSmoothing2d(1.5, 1.5, 0.997, 2)
# display associated content
print(str(kernelX))

Associated kernel values will be sampled on a curve looking like :

gaussianKernel1d.png

Combination of these kernels long X and Y axis allows 2d processing.

See also
https://en.wikipedia.org/wiki/Separable_filter
Note
Following functions can also be usefull to create user dedicated kernels:

Enumeration Type Documentation

◆ eSobelKernelType

enum ipsdk::eSobelKernelType

Enumerate describing Sobel gradient kernels.

Note
This object is associated to a strong enumerate definition
See also
IPSDK_Enum
Enumerator
eSKT_ScharrHalfKnlSz1 

Scharr kernel, of size 3x3 in 2d and 3x3x3 in 3d.

eSKT_SobelHalfKnlSz1 

Sobel kernel, of size 3x3 in 2d and 3x3x3 in 3d.

eSKT_SobelHalfKnlSz2 

Sobel kernel, of size 5x5 in 2d and 5x5x5 in 3d.

eSKT_SobelHalfKnlSz3 

Sobel kernel, of size 7x7 in 2d and 7x7x7 in 3d.

◆ eKernelType

enum ipsdk::eKernelType

Enumerate describing kernel type.

Note
This object is associated to a strong enumerate definition
See also
IPSDK_Enum
Enumerator
eKT_XY 

2d kernel type spanning x and y direction

eKT_XYZ 

3d kernel type spanning x, y and z direction

Function Documentation

◆ separableGaussianSmoothing() [1/2]

IPSDKBASEDATA_API void ipsdk::separableGaussianSmoothing ( const ipReal32  stdDevX,
const ipReal32  stdDevY,
const ipReal32  gaussianRatio,
const ipUInt32  minHalfKernelSize,
KernelXYPtr &  pXAxisKernel,
KernelXYPtr &  pYAxisKernel 
)

function allowing to generate a separable 2d gaussian kernel used for smoothing operation

Exceptions
ipsdk::IPSDKBaseDataExceptionif stdDevX <= 0
ipsdk::IPSDKBaseDataExceptionif stdDevY <= 0
ipsdk::IPSDKBaseDataExceptionif gaussianRatio < 0 || gaussianRatio >= 1
ipsdk::IPSDKBaseDataExceptionif gaussianRatio == 0 || minHalfKernelSize == 0

◆ separableGaussianSmoothing() [2/2]

IPSDKBASEDATA_API void ipsdk::separableGaussianSmoothing ( const ipReal32  stdDevX,
const ipReal32  stdDevY,
const ipReal32  stdDevZ,
const ipReal32  gaussianRatio,
const ipUInt32  minHalfKernelSize,
KernelXYZPtr &  pXAxisKernel,
KernelXYZPtr &  pYAxisKernel,
KernelXYZPtr &  pZAxisKernel 
)

function allowing to generate a separable 3d gaussian kernel used for smoothing operation

Exceptions
ipsdk::IPSDKBaseDataExceptionif stdDevX <= 0
ipsdk::IPSDKBaseDataExceptionif stdDevY <= 0
ipsdk::IPSDKBaseDataExceptionif stdDevZ <= 0
ipsdk::IPSDKBaseDataExceptionif gaussianRatio < 0 || gaussianRatio >= 1
ipsdk::IPSDKBaseDataExceptionif gaussianRatio == 0 || minHalfKernelSize == 0

◆ separableGaussianGradient() [1/2]

IPSDKBASEDATA_API void ipsdk::separableGaussianGradient ( const ipReal32  stdDevX,
const ipReal32  stdDevY,
const ipReal32  gaussianRatio,
const ipUInt32  minHalfKernelSize,
KernelXYPtr &  pXAxisKernel,
KernelXYPtr &  pYAxisKernel 
)

function allowing to generate a separable 2d gaussian kernel used for gradient computation operation

Exceptions
ipsdk::IPSDKBaseDataExceptionif stdDev <= 0
ipsdk::IPSDKBaseDataExceptionif gaussianRatio < 0 || gaussianRatio >= 1
ipsdk::IPSDKBaseDataExceptionif gaussianRatio == 0 || minHalfKernelSize == 0

◆ separableGaussianGradient() [2/2]

IPSDKBASEDATA_API void ipsdk::separableGaussianGradient ( const ipReal32  stdDevX,
const ipReal32  stdDevY,
const ipReal32  stdDevZ,
const ipReal32  gaussianRatio,
const ipUInt32  minHalfKernelSize,
KernelXYZPtr &  pXAxisKernel,
KernelXYZPtr &  pYAxisKernel,
KernelXYZPtr &  pZAxisKernel 
)

function allowing to generate a separable 3d gaussian kernel used for gradient computation operation

Exceptions
ipsdk::IPSDKBaseDataExceptionif stdDev <= 0
ipsdk::IPSDKBaseDataExceptionif gaussianRatio < 0 || gaussianRatio >= 1
ipsdk::IPSDKBaseDataExceptionif gaussianRatio == 0 || minHalfKernelSize == 0

◆ separableGaussianHessian() [1/2]

IPSDKBASEDATA_API void ipsdk::separableGaussianHessian ( const ipReal32  stdDevX,
const ipReal32  stdDevY,
const ipReal32  gaussianRatio,
const ipUInt32  minHalfKernelSize,
KernelXYPtr &  pXAxisKernel,
KernelXYPtr &  pYAxisKernel 
)

function allowing to generate a separable 2d Hessian kernel used for Hessian computation operation

Exceptions
ipsdk::IPSDKBaseDataExceptionif stdDev <= 0
ipsdk::IPSDKBaseDataExceptionif gaussianRatio < 0 || gaussianRatio >= 1
ipsdk::IPSDKBaseDataExceptionif gaussianRatio == 0 || minHalfKernelSize == 0
Note
a half kernel size of 3*stdDev is granted on output (minimum half kernel size = 2)

◆ separableGaussianHessian() [2/2]

IPSDKBASEDATA_API void ipsdk::separableGaussianHessian ( const ipReal32  stdDevX,
const ipReal32  stdDevY,
const ipReal32  stdDevZ,
const ipReal32  gaussianRatio,
const ipUInt32  minHalfKernelSize,
KernelXYZPtr &  pXAxisKernel,
KernelXYZPtr &  pYAxisKernel,
KernelXYZPtr &  pZAxisKernel 
)

function allowing to generate a separable 3d Hessian kernel used for Hessian computation operation

Exceptions
ipsdk::IPSDKBaseDataExceptionif stdDev <= 0
ipsdk::IPSDKBaseDataExceptionif gaussianRatio < 0 || gaussianRatio >= 1
ipsdk::IPSDKBaseDataExceptionif gaussianRatio == 0 || minHalfKernelSize == 0
Note
a half kernel size of 3*stdDev is granted on output (minimum half kernel size = 2)

◆ squareKernelXY()

IPSDKBASEDATA_API KernelXYPtr ipsdk::squareKernelXY ( const ipUInt32  halfKernelSize,
const Real32Vector &  valueColl,
const ipBool  bKeepNullValue = false 
)

function allowing to generate a square XY kernel

Exceptions
ipsdk::IPSDKBaseDataExceptionif valueColl.size() != (2*halfKernelSize+1) * (2*halfKernelSize+1)

◆ rectangularKernelXY()

IPSDKBASEDATA_API KernelXYPtr ipsdk::rectangularKernelXY ( const ipUInt32  halfKernelSizeX,
const ipUInt32  halfKernelSizeY,
const Real32Vector &  valueColl,
const ipBool  bKeepNullValue = false 
)

function allowing to generate a rectangular XY kernel

Exceptions
ipsdk::IPSDKBaseDataExceptionif valueColl.size() != (2*halfKernelSizeX+1) * (2*halfKernelSizeY+1)

◆ linearKernelXY()

IPSDKBASEDATA_API KernelXYPtr ipsdk::linearKernelXY ( const ipReal32  theta,
const Real32Vector &  valueColl,
const ipBool  bKeepNullValue = false 
)

function allowing to generate a linear oriented XY kernel with a given number of elements.

See also
Points and vectors 2d representation
Note
Input valueColl size defines output kernel size (number of elements). Kernel length will not be the same given different angles (there will be for example a ratio of $\sqrt{2}$ between angles 0 and $\frac{\pi}{4}$)
Exceptions
ipsdk::IPSDKBaseDataExceptionif valueColl.size() % 2 != 1

◆ linearInterpolatedKernelXY()

IPSDKBASEDATA_API KernelXYPtr ipsdk::linearInterpolatedKernelXY ( const ipReal32  theta,
const Real32Vector &  valueColl,
const ipBool  bKeepNullValue = false 
)

function allowing to generate a linear oriented XY kernel with interpolated coefficients.

See also
Points and vectors 2d representation
Note
Input valueColl size defines output kernel length. Kernel length will be the same regardless of angle value
Exceptions
ipsdk::IPSDKBaseDataExceptionif valueColl.size() % 2 != 1

◆ cubicKernelXYZ()

IPSDKBASEDATA_API KernelXYZPtr ipsdk::cubicKernelXYZ ( const ipUInt32  halfKernelSize,
const Real32Vector &  valueColl,
const ipBool  bKeepNullValue = false 
)

function allowing to generate a cubic XYZ kernel

Exceptions
ipsdk::IPSDKBaseDataExceptionif valueColl.size() != (2*halfKernelSize+1) * (2*halfKernelSize+1) * (2*halfKernelSize+1)

◆ rectangularKernelXYZ()

IPSDKBASEDATA_API KernelXYZPtr ipsdk::rectangularKernelXYZ ( const ipUInt32  halfKernelSizeX,
const ipUInt32  halfKernelSizeY,
const ipUInt32  halfKernelSizeZ,
const Real32Vector &  valueColl,
const ipBool  bKeepNullValue = false 
)

function allowing to generate a rectangular parallelepiped XYZ kernel

Exceptions
ipsdk::IPSDKBaseDataExceptionif valueColl.size() != (2*halfKernelSizeX+1) * (2*halfKernelSizeY+1) * (2*halfKernelSizeZ+1)

◆ linearKernelXYZ()

IPSDKBASEDATA_API KernelXYZPtr ipsdk::linearKernelXYZ ( const ipReal32  theta,
const ipReal32  phi,
const Real32Vector &  valueColl,
const ipBool  bKeepNullValue = false 
)

function allowing to generate a linear oriented XYZ kernel with a given number of elements.

See also
Points and vectors 3d representation
Note
Input valueColl size defines output kernel size (number of elements). Kernel length will not be the same given different angles (see linearKernelXY for an example)
Exceptions
ipsdk::IPSDKBaseDataExceptionif valueColl.size() % 2 != 1

◆ linearInterpolatedKernelXYZ()

IPSDKBASEDATA_API KernelXYZPtr ipsdk::linearInterpolatedKernelXYZ ( const ipReal32  theta,
const ipReal32  phi,
const Real32Vector &  valueColl,
const ipBool  bKeepNullValue = false 
)

function allowing to generate a linear oriented XYZ kernel with interpolated coefficients.

See also
Points and vectors 3d representation
Note
Input valueColl size defines output kernel length. Kernel length will be the same regardless of angle value
Exceptions
ipsdk::IPSDKBaseDataExceptionif valueColl.size() % 2 != 1
Generated on Tue Apr 15 2025 16:20:53 for IPSDK by   doxygen 1.8.14