Class to manage a filtering kernel for images. More...

#include <mlKernel.h>

Public Types
enum	KernModifier { KERN_SET = 0 , KERN_MULT , KERN_ADD , KERN_INVDIV , KERN_INVSUB , KERN_SQR , KERN_SQRT , KERN_POW , KERN_LOG , KERN_NORMALIZE , KERN_GAUSS , KERN_SPHERE , KERN_MIRROR , KERN_MIRROR_X , KERN_MIRROR_Y , KERN_MIRROR_Z , KERN_MIRROR_C , KERN_MIRROR_T , KERN_MIRROR_U , NUM_KERN_MODIFYERS }
	Manipulation modes for kernel values with a given value `v:` More...

Public Member Functions
	TKernel ()
	Constructor. Builds an empty kernel.

	TKernel (const TKernel &kern)
	Copy constructor. Builds a kernel with contents of `kern`.

virtual	~TKernel ()
	Destructor. Cleans up and removes instance of kernel.

const TKernel &	operator= (const TKernel &kern)
	Assignment operator. Sets current instance to contents of `kern`.

void	reset ()
	Reset kernel to construction state.

size_t	getTabSize () const
	Returns the current number of kernel elements.

const ImageVector *	getCoordTab (size_t dim=0) const
	Gets a table of coordinates pointing to all kernel elements which are currently defined.

const KDATATYPE *	getValueTab (size_t dim=0) const
	Gets the table of kernel element values which are currently defined.

KDATATYPE	getValueTabSum () const
	Return the sum of all kernel element values.

KDATATYPE	getMinValue () const
	Return the minimum value of all kernel element values If kernel value table is empty then 0 is returned.

KDATATYPE	getMaxValue () const
	Return the maximum value of all kernel element values If kernel value table is empty then 1 is returned.

KDATATYPE	getNegativeValueSum () const
	Return the sum of all negative kernel element values.

KDATATYPE	getPositiveValueSum () const
	Return the sum of all positive kernel element values.

void	manipulateKernelElements (KernModifier mode, KDATATYPE v)
	Modify all kernel element values with the value `v`.

const ImageVector &	getExtent () const
	Returns the kernel extents in 6D.

const ImageVector &	getNegativeExtent () const
	The extent of the kernel to both sides.

const ImageVector &	getPositiveExtent () const
	See `getNegativeExtent()`.

MLint	findIndex (const ImageVector &pos) const
	Return index to kernel element if it exists; otherwise return -1.

void	setPartialKernel (size_t numElems, ImageVector const coords, KDATATYPE const values=nullptr)
	Defines a set of local kernel coordinates and optionally a set of values which define the kernel elements.

std::string	getKernel (bool asLines=false, MLint fieldWidth=0, MLint precision=10) const
	Returns the current kernel elements and values as string: The string needs has the following format: .

std::string	setKernel (const std::string &kernString)
	Defines elements and values of the kernel matrix by a string.

void	setKernel (const ImageVector &ext, const KDATATYPE const values=nullptr, bool const mask=nullptr)
	Defines a complete kernel matrix whose extents are defined by `ext`.

template<typename KDATATYPE2 >
void	setKernel (const ImageVector &ext, const KDATATYPE2 const xaxis, const KDATATYPE2 const yaxis, const KDATATYPE2 const zaxis, const KDATATYPE2 const caxis, const KDATATYPE2 const taxis, const KDATATYPE2 const uaxis, bool normalize)
	Defines a complete kernel matrix whose extents are defined by `ext`.

void	setSeparableKernel (const std::vector< typename std::vector< KDATATYPE > > &separableRows)
	Create kernel coordinate and value tables in separable table format, that means a 2-D kernel where each rows describes the elements of 1-D kernels.

void	resizeKernel (const ImageVector &ext, KDATATYPE newVal=0)
	Resizes the kernel to a new state and tries to maintain the previous elements if possible.

void	fillUndefinedElements (KDATATYPE newVal=0)
	Fill all undefined kernel elements with `newVal`.

void	makeCircular ()
	Takes the current kernel, computes radii from the extents of the kernel and removes all kernel elements which are outside the ellipsoid defined by these radii.

void	mirror (int dimension=-1)
	Applies a point symmetric mirroring of all kernel elements.

void	setGauss (const ImageVector &ext)
	Replaces the current kernel by a normalized gauss kernel.

Support for an interpretation as separable kernel.
void	setSeparable (bool isSeparableVal)
	Set/unset a flag to indicate that the first 6 rows of the first kernel slice is considered as 1-D axes of a separable filter kernel.

bool	isSeparable () const
	Indicates whether the first 6 rows of the first kernel slice are interpreted as 1-D axes of a separable filter kernel; default is false.

ImageVector	getSeparableDimEntries () const
	Returns a ImageVector with the number of entries of the separable kernel for the dimensions 0,...,5.

ImageVector	getSeparableOneDimExtents () const
	Returns a vector where the components 0,...,5 contain the extent of the region spanned by the 6 separated 1-D kernels if the kernel is interpreted as a separable kernel.

size_t	getSeparableDimIndex (size_t dim=0) const
	Returns the index to entries of valueTab or coordTab which are related to the 1-D separable kernel for the dimension `dim` where `dim` must be from [0,5].

const std::vector< ImageVector > &	getSeparableCoordTab () const
	Returns the table of with all coordinates for filtering with separable kernels.

Static Public Member Functions
static MLint	coordToIndex (MLint x, MLint y, MLint z, MLint c, MLint t, MLint u, const ImageVector &size)
	Converts the coordinate (x,y,z,c,t,u) into the kernel to an index into an array with 6D extents given by `size`.

static MLint	coordToIndex (const ImageVector &p, const ImageVector &size)
	Converts the coordinate `into` the kernel with extents `size` to an index.

static ImageVector	indexToCoord (MLint idx, const ImageVector &ext)
	Converts an index into an array with extents `ext` to a coordinate.

static ImageVector	calculateNegativeExtentFromExtent (const ImageVector &ext)
	Calculate the negative extent of a kernel from a kernel extent.

static ImageVector	calculatePositiveExtentFromExtent (const ImageVector &ext)
	Calculate the positive extent of a kernel from a kernel extent.

static MLldouble	binomialcoeff (MLint n, MLint k)
	Calculate binomial coefficients for (n) (k)

static std::vector< KDATATYPE >	get1DGauss (size_t numSamples, bool normalize=true)
	Returns a vector with `numSample` values binomial coefficients.

Protected Member Functions
void	_init ()
	Initialization. Should be called only by constructors.

void	_clearTables ()
	Clear all internal (dynamic) tables.

void	_addCoordinate (const ImageVector &pos, KDATATYPE value, bool update)
	Add a new coordinate with value to the coordinate and value table.

void	_calculateRealKernelExt ()
	Calculate the correct maximum kernel extent for used kernel elements.

void	_validateSeparabilityInfos () const
	This method updates all members which are needed in query methods for separability properties of the kernel.

void	_invalidateSeparableInfos ()
	Invalidate separability information.

Detailed Description

template<typename KDATATYPE>
class ml::TKernel< KDATATYPE >

Class to manage a filtering kernel for images.

This file contains the TKernel class to manage a 6D kernel which can be applied to images. It handles a set of coordinates (see getCoordTab()) and values for those coordinates (see getValueTab()). This permits the specification of kernels with gaps or only a few defined elements. So big kernels with few elements can be manipulated and applied fast. A set of operations is available on a kernel instance which includes arithmetics on the kernel values, gauss presets, normalization, different kernel set and get routines to created/save partially defined kernels, get/set methods to load/save kernels as strings or arrays and much more.

This TKernel class is implemented as template dependent on KDATATYPE to have different precisions for kernel elements. Normally the kernel is instantiated with double as KDATATYPE. You can also instantiate this class as MLfloat or MLldouble kernel. Instantiating this class with integer types as KDATATYPE is legal, however results of numeric operations are not rounded but cast. Also note that the usage of integer for KDATATYPE is not really useful since pure integer kernel operations are rare and some operations would suffer, because of the mentioned cast operations, because of integer overflows when many kernel elements are summed up or when creating default initializations where the sum of (all equal valued) kernel elements shall be one which is normally impossible with integer types.

The same consideration also holds for non scalar voxel values which could be used as kernel element type KDATATYPE; however no tests have been applied for that. At least conversions from/to strings will reduce values to scalars.

Since this class does not have any support to apply the kernel to the image since this is usually the algorithmic part of the modules. However there are some helper functions available in mlKernelTools for standard convolutions which can be called directly from the modules filtering (sub)images.

For related code and more information see mlKernelExample.h, mlKernel.h, mlKernelBaseModule.h, mlKernelModule.h, mlKernelEditor.h, mlRankFilter.h, mlExtConvolutionFilter.h, mlKernelMacros, mlKernelTools.h and mlConvolutionFilter.h.

Definition at line 73 of file mlKernel.h.

Enumerator
KERN_SET
KERN_MULT
KERN_ADD
KERN_INVDIV
KERN_INVSUB
KERN_SQR
KERN_SQRT
KERN_POW
KERN_LOG
KERN_NORMALIZE
KERN_GAUSS
KERN_SPHERE
KERN_MIRROR
KERN_MIRROR_X
KERN_MIRROR_Y
KERN_MIRROR_Z
KERN_MIRROR_C
KERN_MIRROR_T
KERN_MIRROR_U
NUM_KERN_MODIFYERS

std::string ml::TKernel< KDATATYPE >::getKernel	(	bool	asLines = false,
		MLint	fieldWidth = 0,
		MLint	precision = 10 ) const

void ml::TKernel< KDATATYPE >::manipulateKernelElements	(	KernModifier	mode,
		KDATATYPE	v )

void ml::TKernel< KDATATYPE >::resizeKernel	(	const ImageVector &	ext,
		KDATATYPE	newVal = 0 )

void ml::TKernel< KDATATYPE >::setKernel	(	const ImageVector &	ext,
		const KDATATYPE *const	values = nullptr,
		bool *const	mask = nullptr )

void ml::TKernel< KDATATYPE >::setPartialKernel	(	size_t	numElems,
		ImageVector *const	coords,
		KDATATYPE *const	values = nullptr )

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ KernModifier

Constructor & Destructor Documentation

◆ TKernel() [1/2]

◆ TKernel() [2/2]

◆ ~TKernel()

Member Function Documentation

◆ _addCoordinate()

◆ _calculateRealKernelExt()

◆ _clearTables()

◆ _init()

◆ _invalidateSeparableInfos()

◆ _validateSeparabilityInfos()

◆ binomialcoeff()

◆ calculateNegativeExtentFromExtent()

◆ calculatePositiveExtentFromExtent()

◆ coordToIndex() [1/2]

◆ coordToIndex() [2/2]

◆ fillUndefinedElements()

◆ findIndex()

◆ get1DGauss()

◆ getCoordTab()

◆ getExtent()

◆ getKernel()

◆ getMaxValue()

◆ getMinValue()

◆ getNegativeExtent()

◆ getNegativeValueSum()

◆ getPositiveExtent()

◆ getPositiveValueSum()

◆ getSeparableCoordTab()

◆ getSeparableDimEntries()

◆ getSeparableDimIndex()

◆ getSeparableOneDimExtents()

◆ getTabSize()

◆ getValueTab()

◆ getValueTabSum()

◆ indexToCoord()

◆ isSeparable()

◆ makeCircular()

◆ manipulateKernelElements()

◆ mirror()

◆ operator=()

◆ reset()

◆ resizeKernel()

◆ setGauss()

◆ setKernel() [1/3]

◆ setKernel() [2/3]

◆ setKernel() [3/3]

◆ setPartialKernel()

◆ setSeparable()

◆ setSeparableKernel()