lti::kernel2D< T > Class Template Reference

two-dimensional filter kernel More...

#include <ltiLinearKernels.h>

Inheritance diagram for lti::kernel2D< T >:

[legend]

Collaboration diagram for lti::kernel2D< T >:

[legend]

List of all members.

Public Member Functions
	kernel2D ()
	kernel2D (const kernel2D &other)
	kernel2D (const int &rows, const int &columns, const T &iniValue=T())
	kernel2D (const int &fromRow, const int &fromCol, const int &toRow, const int &toCol, const T &iniValue=T())
	kernel2D (const bool &init, const int &rows, const int &columns)
	kernel2D (const bool &init, const int &fromRow, const int &fromCol, const int &toRow, const int &toCol)
virtual	~kernel2D ()
kernel2D< T > &	copy (const kernel2D< T > &other)
const char *	getTypeName () const
virtual mathObject *	clone () const
template<class U >
kernel2D< T > &	castFrom (const kernel2D< U > &other)
kernel2D< T > &	castFrom (const matrix< T > &other, const int &firstRow, const int &firstColumn)
kernel2D< T > &	castFrom (const matrix< T > &other, const point &firstElement=point(0, 0))
kernel2D< T > &	castFrom (const sepKernel< T > &other)
void	resize (const int &fromRow, const int &fromCol, const int &toRow, const int &toCol, const T &iniValue=T(), const bool &copyData=true, const bool &initNew=true)
void	fill (const matrix< T > &mat, const int &fromRow=MinInt24, const int &fromCol=MinInt24, const int &toRow=MaxInt24, const int &toCol=MaxInt24, const int &startAtRow=0, const int &startAtCol=0)
void	fill (const T *data, const int &fromRow=MinInt24, const int &fromCol=MinInt24, const int &toRow=MaxInt24, const int &toCol=MaxInt24)
const T &	getNorm () const
void	setNorm (const T &n)
const point &	getOffset () const
void	setOffset (const point &p)
int	firstRow () const
int	lastRow () const
int	firstColumn () const
int	lastColumn () const
T &	at (const point &p)
const T &	at (const point &p) const
T &	at (const int &y, const int &x)
const T &	at (const int &y, const int &x) const
kernel2D< T > &	outerProduct (const kernel1D< T > &colKernel, const kernel1D< T > &rowKernel)
void	denormalize ()
kernel2D< T > &	mirror (const kernel2D< T > &other)
kernel2D< T > &	mirror ()
virtual bool	write (ioHandler &handler, const bool complete=true) const
virtual bool	read (ioHandler &handler, const bool complete=true)
Protected Attributes
point	offset
T	norm

Detailed Description

template<class T>
class lti::kernel2D< T >

two-dimensional filter kernel

The template type of this class should coincide with the template class of the matrix or channel to be convolved with. For example, if you want to convolve a kernel2D with a channel8, you will need a kernel2D<channel8::value_type> or kernel2D<ubyte>. The offset of the kernel is at int(columns()/2),int(rows()/2). This means that for kernels of odd width and height, the origin (0,0) is exactly in the center, while for kernels with even width and/or height, it is shifted towards the upper left corner.

If you instantiate a kernel2D of a fixed point type, like kernel2D<int> or kernel2D<ubyte>, you also need to consider the "norm" of the kernel (see lti::kernel2D<T>::getNorm() and lti::kernel2D<T>::setNorm(const T&)). This "norm" allows the representation of numbers less than 1.0. You can see this norm as the value to be consider as 1.0, when operating with the kernel. For example, if you have a kernel2D<ubyte> with the values [64,128,64] and norm=255, the the interpreted values during convolution will be [0.25,0.5,0.25]. With floating-point types, the norm will be always assumed to be 1.0. For other types the default norms are the following:

For int: 65536 For ubyte: 255 Otherwise: 1.0

You can generate 2D kernels from separable ones using the castFrom() method. For example:

  lti::gaussKernel2D<float> gauss(5); // a sepKernel 5x5 
  lti::kernel2D<float>      kern;     // a 2D kernel;
  
  kern.castFrom(gauss);

You can also use the outerProduct member to construct a 2D kernel from two 1D ones:

  lti::gaussKernel1D<float> colKern(3); // a 1D kernel
  lti::gaussKernel1D<float> rowKern(5); // another 1D kernel

  lti::kernel2D<float>      kern;     // a 2D kernel;
  
  kern.outerProd(colKern,rowKern);    // outer product of both kernels

See also:: lti::convolution

Constructor & Destructor Documentation

template<class T>

lti::kernel2D< T >::kernel2D ( )

default constructor

template<class T>

lti::kernel2D< T >::kernel2D ( const kernel2D< T > & other )

copy constructor

Parameters:

other

the kernel to be copied

template<class T>

lti::kernel2D< T >::kernel2D	(	const int &	rows,
		const int &	columns,
		const T &	iniValue = `T()`
	)

Create a new kernel of indicated size and initial value.

The offset is kept at zero.

Parameters:

	rows	number of rows
	columns	number of columns
	iniValue	initial value of all elements

template<class T>

lti::kernel2D< T >::kernel2D	(	const int &	fromRow,
		const int &	fromCol,
		const int &	toRow,
		const int &	toCol,
		const T &	iniValue = `T()`
	)

Create a new kernel with indicated indices.

Parameters:

	fromRow	index of the lower row of the kernel
	fromCol	index of the lower column of the kernel
	toRow	index of the higher row of the kernel
	toCol	index of the higher column of the kernel
	iniValue	the initial value for the elements of the kernel

You can initialize a 5x3 kernel to filter a lti::channel with following code:

 lti::kernel2D<channel::value_type> aKernel(-1,-2,1,2,0);
 aKernel.at(-1,-2)=0.2;
 aKernel.at(-1,-1)=0.2;
 aKernel.at(0,0)=0.2;
 aKernel.at(1,1)=0.2;
 aKernel.at(1,2)=0.2;

template<class T>

lti::kernel2D< T >::kernel2D	(	const bool &	init,
		const int &	rows,
		const int &	columns
	)

If init is true this constructor is equivalent to calling kernel2D(const int& rows, const int& columns), and thus initializing all elements with T().

However, in some cases the elements need not be initialized during construction, since complex initializion is required. Especially for large kernel2Ds, the unnecessary constructor initialization is very time consuming.

If init is false, memory is allocated but no initialization takes place.

Parameters:

	init	initialize matrix or not
	rows	number of rows
	columns	number of columns

template<class T>

lti::kernel2D< T >::kernel2D	(	const bool &	init,
		const int &	fromRow,
		const int &	fromCol,
		const int &	toRow,
		const int &	toCol
	)

If init is true this constructor is equivalent to calling kernel2D(const int& fromRow,const int& fromCol, const int& toRow,const int& toCol), and thus initializing all elements with T().

However, in some cases the elements need not be initialized during construction, since complex initializion is required. Especially for large kernel2Ds, the unnecessary constructor initialization is very time consuming.

If init is false, memory is allocated but no initialization takes place.

Parameters:

	init	initialize matrix or not
	fromRow	index of the lower row of the kernel
	fromCol	index of the lower column of the kernel
	toRow	index of the higher row of the kernel
	toCol	index of the higher column of the kernel

template<class T>

virtual lti::kernel2D< T >::~kernel2D ( ) [virtual]

destructor

Member Function Documentation

template<class T>

const T& lti::kernel2D< T >::at	(	const int &	y,
		const int &	x
	)			const `[inline]`

access operator with offset

template<class T>

T& lti::kernel2D< T >::at	(	const int &	y,
		const int &	x
	)			`[inline]`

access operator with offset

template<class T>

const T& lti::kernel2D< T >::at ( const point & p ) const [inline]

access operator with offset

Reimplemented from lti::genericMatrix< T >.

template<class T>

T& lti::kernel2D< T >::at ( const point & p ) [inline]

access operator with offset

Reimplemented from lti::genericMatrix< T >.

Referenced by lti::kernel2D< ubyte >::at().

template<class T>

kernel2D<T>& lti::kernel2D< T >::castFrom ( const sepKernel< T > & other )

copy the contents of the other separable kernel in this two-dimensional kernel

template<class T>

kernel2D<T>& lti::kernel2D< T >::castFrom	(	const matrix< T > &	other,
		const point &	firstElement = `point(0, 0)`
	)

copy the content of the other matrix in this kernel and assign the index (firstRow,firstColumn) to the first element of the matrix.

For example if other is a 3x3 matrix, then castFrom(other,-1,-1) is a 3x3 kernel which indices lay inside [-1,1].

Parameters:

	other	the matrix with the data to be copied
	firstElement	index for the first element of the matrix

Returns:: a reference to this instance

template<class T>

kernel2D<T>& lti::kernel2D< T >::castFrom	(	const matrix< T > &	other,
		const int &	firstRow,
		const int &	firstColumn
	)

copy the content of the other matrix in this kernel and assign the index (firstRow,firstColumn) to the first element of the matrix.

For example if other is a 3x3 matrix, then castFrom(other,-1,-1) is a 3x3 kernel which indices lay inside [-1,1].

Parameters:

	other	the matrix with the data to be copied
	firstRow	index for the first row of the matrix
	firstColumn	index for the first column of the matrix

Returns:: a reference to this instance

template<class T>

template<class U >

kernel2D<T>& lti::kernel2D< T >::castFrom ( const kernel2D< U > & other ) [inline]

copy from kernel of different type

Parameters:

other

a one dimensional kernel of another type

Returns:: a reference to this instance

Reimplemented from lti::matrix< T >.

Referenced by lti::kernel2D< ubyte >::castFrom().

template<class T>

virtual mathObject* lti::kernel2D< T >::clone ( ) const [inline, virtual]

clone member

Returns:: a pointer to a copy of this object

Reimplemented from lti::matrix< T >.

template<class T>

kernel2D<T>& lti::kernel2D< T >::copy ( const kernel2D< T > & other )

copy member

Parameters:

other

the kernel to be copied

Returns:: a reference to this instance

Reimplemented from lti::matrix< T >.

template<class T>

void lti::kernel2D< T >::denormalize ( )

denormalize divide all elements by norm and set the norm to 1!

template<class T>

void lti::kernel2D< T >::fill	(	const T *	data,
		const int &	fromRow = `MinInt24`,
		const int &	fromCol = `MinInt24`,
		const int &	toRow = `MaxInt24`,
		const int &	toCol = `MaxInt24`
	)

fills this kernel between the "from's" and "to's" with the contents of the matrix mat starting at startAtRow and startAtCol

Parameters:

	data	the data that should fill this kernel
	fromRow	first row of the submatrix to be filled
	fromCol	first column of the submatrix to be filled
	toRow	last row of the submatrix to be filled
	toCol	last column of the submatrix to be filled

template<class T>

void lti::kernel2D< T >::fill	(	const matrix< T > &	mat,
		const int &	fromRow = `MinInt24`,
		const int &	fromCol = `MinInt24`,
		const int &	toRow = `MaxInt24`,
		const int &	toCol = `MaxInt24`,
		const int &	startAtRow = `0`,
		const int &	startAtCol = `0`
	)

fills this kernel between the "from's" and "to's" with the contents of the matrix mat starting at startAtRow and startAtCol

Parameters:

	mat	the matrix with the data to be copied
	fromRow	first row of the submatrix to be filled
	fromCol	first column of the submatrix to be filled
	toRow	last row of the submatrix to be filled
	toCol	last column of the submatrix to be filled
	startAtRow	starting row of `mat` where the data is located.
	startAtCol	starting column of `mat` where the data is located.

template<class T>

int lti::kernel2D< T >::firstColumn ( ) const [inline]

first column index

template<class T>

int lti::kernel2D< T >::firstRow ( ) const [inline]

first row index

template<class T>

const T& lti::kernel2D< T >::getNorm ( ) const [inline]

get normalization factor

The normalization factor is used by the fixed point types as a representation of the value 1. For example, the norm for a kernel1D<ubyte> can be 255, if the filter kernel don't need values greater than 1.0.

Referenced by lti::kernel2D< ubyte >::castFrom().

template<class T>

const point& lti::kernel2D< T >::getOffset ( ) const

returns offset, i.e.

center of the filter-kernel

Returns:: the position of the element with index 0 in the memory array. This value is the same as -firstIdx()

Referenced by lti::kernel2D< ubyte >::castFrom().

template<class T>

const char* lti::kernel2D< T >::getTypeName ( void ) const [inline, virtual]

returns name of this type ("kernel2D")

Reimplemented from lti::matrix< T >.

template<class T>

int lti::kernel2D< T >::lastColumn ( ) const [inline]

last column index

Reimplemented from lti::genericMatrix< T >.

template<class T>

int lti::kernel2D< T >::lastRow ( ) const [inline]

last row index

Reimplemented from lti::genericMatrix< T >.

template<class T>

kernel2D<T>& lti::kernel2D< T >::mirror ( )

Mirror this kernel, i.e.

at(y,x) = at(-y,-x);

Returns:: a reference to this instance

template<class T>

kernel2D<T>& lti::kernel2D< T >::mirror ( const kernel2D< T > & other )

Mirror the other kernel and leave the result here, i.e.

at(y,x) = other.at(-y,-x);

Parameters:

other

the kernel to be copied and then mirrored

Returns:: a reference to this instance

template<class T>

kernel2D<T>& lti::kernel2D< T >::outerProduct	(	const kernel1D< T > &	colKernel,
		const kernel1D< T > &	rowKernel
	)

outer product of two kernel1D.

The first kernel is a column kernel and the second kernel is a row kernel.

Parameters:

	colKernel	column kernel
	rowKernel	row kernel

Returns:: a reference to this kernel

If you want to convert a separable kernel (lti::sepKernel<T>) into a 2D kernel, see also the methods castFrom().

The final kernel will contain colKernel.size() rows and rowKernel.size() columns. Each row will be equal to the rowKernel multiplied by the respective colKernel element.

template<class T>

virtual bool lti::kernel2D< T >::read	(	ioHandler &	handler,
		const bool	complete = `true`
	)			`[virtual]`

read the object from the given ioHandler

Reimplemented from lti::genericMatrix< T >.

template<class T>

void lti::kernel2D< T >::resize	(	const int &	fromRow,
		const int &	fromCol,
		const int &	toRow,
		const int &	toCol,
		const T &	iniValue = `T()`,
		const bool &	copyData = `true`,
		const bool &	initNew = `true`
	)

resize kernel with indicated indexes

Parameters:

	fromRow	index of the lower row of the kernel
	fromCol	index of the lower column of the kernel
	toRow	index of the higher row of the kernel
	toCol	index of the higher column of the kernel
	iniValue	the initial value for the elements of the kernel
	copyData	if true, keep data (see lti::matrix::resize())
	initNew	initialize new elements with the `iniValue`.

You can initialize a 5x3 kernel to filter a lti::channel with following code:

 lti::kernel2D<channel::value_type> aKernel;
 aKernel.resize(-1,-2,1,2,0,false);
 aKernel.at(-1,-2)=0.2;
 aKernel.at(-1,-1)=0.2;
 aKernel.at(0,0)=0.2;
 aKernel.at(1,1)=0.2;
 aKernel.at(1,2)=0.2;

template<class T>

void lti::kernel2D< T >::setNorm ( const T & n ) [inline]

set normalization factor

See also:: getNorm()

template<class T>

void lti::kernel2D< T >::setOffset ( const point & p )

set kernel offset, i.e.

center of the filter-kernel

Parameters:

p

the position of the element with index (0,0) in the memory array. This value is the same as point(-firstRow(),-firstColumns()).

template<class T>

virtual bool lti::kernel2D< T >::write	(	ioHandler &	handler,
		const bool	complete = `true`
	)			const `[virtual]`

write the object in the given ioHandler

Reimplemented from lti::genericMatrix< T >.

Member Data Documentation

template<class T>

T lti::kernel2D< T >::norm [protected]

Normalisation factor.

This value will be ignored for floating point formats. For fixed point formats, this value corresponds to 1.0

Referenced by lti::kernel2D< ubyte >::castFrom(), lti::kernel2D< ubyte >::getNorm(), and lti::kernel2D< ubyte >::setNorm().

template<class T>

point lti::kernel2D< T >::offset [protected]

absolute coordinates of the kernel point (0,0)

Referenced by lti::kernel2D< ubyte >::at(), lti::kernel2D< ubyte >::castFrom(), lti::kernel2D< ubyte >::firstColumn(), lti::kernel2D< ubyte >::firstRow(), lti::kernel2D< ubyte >::lastColumn(), and lti::kernel2D< ubyte >::lastRow().

The documentation for this class was generated from the following file:

ltiLinearKernels.h

lti::kernel2D< T > Class Template Reference

Public Member Functions

Protected Attributes

Detailed Description

template<class T> class lti::kernel2D< T >

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<class T>
class lti::kernel2D< T >