latest version v1.9 - last update 24 Nov 2005

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 >.

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

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

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.

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

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

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

absolute coordinates of the kernel point (0,0)

---

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

• ltiLinearKernels.h

---