icl::core::Channel< T > Class Template Reference

Utility helper class for faster and more convenient access to single channel image data. More...

#include <Channel.h>

List of all members.

Public Types
typedef T *	iterator
	typedef for a normal iterator (just a pointer)
typedef const T *	const_iterator
	const iterator type (just a const pointer)
typedef ImgIterator< T >	roi_iterator
	type definition for ROI iterator
typedef const ImgIterator< T >	const_roi_iterator
	type definition for a const ROI iterator
Public Member Functions
	Channel ()
	Empty constructor (create an invalid Channel object)
	Channel (const Channel &other)
	Copy an image channel (this could be exploited to violate const concept)
Channel< T > &	operator= (Channel< T > &other)
	assignmet operator
const Channel< T > &	operator= (const Channel< T > &other) const
	assign operator (also for const channels)
T &	operator() (int x, int y)
	main working function: returns a reference to the pixel at position (x,y)
T &	operator() (const utils::Point &p)
	convenience function for point-based index access
const T &	operator() (const utils::Point &p) const
	convenience function for point-based index access (const)
const T &	operator() (int x, int y) const
	main working function: returns const a reference to the pixel at position (x,y)
T &	operator[] (int idx)
	working function for linear pixel array access ( not const version)
const T &	operator[] (int idx) const
	working function for linear pixel array access (const version)
template<class Vec2D >
T	operator() (const Vec2D &p) const
	index operator with linear interpolation
iterator	begin ()
	returns the image iterator (equal to getData(channel))
const_iterator	begin () const
	returns the image iterator (equal to getData(channel)) (const)
iterator	end ()
	returns the image end-iterator (equal to getData(channel)+getDim())
const_iterator	end () const
	returns the image end-iterator (const)
roi_iterator	beginROI ()
	returns the iterator for an images ROI
const_roi_iterator	beginROI () const
	returns the iterator for an images ROI (const)
roi_iterator	endROI ()
	returns the end-iterator for an images ROI
const_roi_iterator	endROI () const
	returns the end-iterator for an images ROI (const)
bool	isNull () const
int	getWidth () const
	returns the wrapped images width
int	getHeight () const
	returns the wrapped images height
const utils::Size &	getSize () const
	retusn the wrapped images size
int	getDim () const
	returns the wrapped images dim = width*height
const utils::Rect &	getROI () const
	returns the channel ROI
utils::Point	getROIOffset () const
	returns the channel ROI offset
utils::Size	getROISize () const
	returns the channel ROI size
int	getROIWidth () const
	returns the channel ROI width
int	getROIHeight () const
	returns the channel ROI height
int	getROIXOffset () const
	returns the channel ROI X-Offset
int	getROIYOffset () const
	returns the channel ROI Y-Offset
void	redefineROI (const utils::Rect &newROI) const
	Sets a new ROI to this image channel (this does not affect the underlying images ROI)
Private Member Functions
	Channel (const T *data, const utils::Size &size, const utils::Rect &roi)
	private constructor
	Channel (T *data, const utils::Size &size, const utils::Rect &roi)
Private Attributes
T *	m_data
utils::Size	m_size
utils::Rect	m_roi
Friends
class	Img< T >
	mades Img<T> a friend to allow it construction of ImgChannels

---

Detailed Description

template<class T>
class icl::core::Channel< T >

Utility helper class for faster and more convenient access to single channel image data.

Yet, the (x,x,c)-operator of the Img<T> class is slow, because of hight computational overhead due to the necessity of a channel lookup The (x,y,c)-operator needs first to lookup for the channel c in the channel array of the image, before it can address a pixels value by dereferencing the shared pointers wrapped data pointer. In many cases, The user works on images with a fixed channel count (mostly 1 or 3), and needs a simple (x,y)-data access operator, which translates an (x,y) pixel address into the raw data pointer address dataPointer[x+width*y].
The Channel class was designed to facilitate this procedure. To avoid the arise of an The following code example shows how to replace the Imgs (x,y,c)-operator by using the Channel template class:

        inline void copy_image(Img32f &A,Img32f &B){
          for(int x=0;x<1000;x++){                     // default version for an image copy
            for(int y=0;y<1000;y++){                   // each pixel is addressed by the
              A(x,y,0)=B(x,y,0);                       // (x,y,c)-operator (image size is fixed)
            }
          }
        }
        inline void copy_image(Img32f &A,Img32f &B){
          Channel32f a = A.extractChannel(0);         // new faster version (about 6.5-times
          Channel32f b = B.extractChannel(0);         // faster, than the above function
          for(int x=0;x<1000;x++){                    // pixels are addressed by the 
            for(int y=0;y<1000;y++){                  // ImgChannel objects
              a(x,y)=b(x,y);
            }
          }
        }

The lower function is about 6.5 times faster than the upper one!

When working on multi channel images with a fixed channel count, the advantage of using the ImgChannel class becomes even greater:

        inline void copy_3_channels(ImgQ &A,ImgQ &B){
          for(int x=0;x<1000;x++){
            for(int y=0;y<1000;y++){
              A(x,y,0)=B(x,y,0);
              A(x,y,1)=B(x,y,1);
              A(x,y,2)=B(x,y,2);
            }
          }
        }
  
        inline void copy_3_channels(ImgQ &A,ImgQ &B){
          Channel32f a[3]; A.extractChannels(a);
          Channel32f b[3]; B.extractChannels(b);
            for(int x=0;x<1000;x++){
              for(int y=0;y<1000;y++){            // more than one channel can be
                a[0](x,y)=b[0](x,y);              // stored in a fixed size array of
                a[1](x,y)=b[1](x,y);              // Channel32f structs; this allows
                a[2](x,y)=b[2](x,y);              // direct access to the channel data pointer
              }
            }
          }
        }

In The above example, the lower version of the copy function is even 7 times as fast as the upper version. At last, we want to examine the speed advantage for dynamic channel count and image size. The corresponding code is illustrated in the following code example:

        inline void dynamic_image_copy(ImgQ &A,ImgQ &B){
          for(int x=0;x<A.getWidth();x++){
            for(int y=0;y<A.getHeight();y++){
              for(int c=0;c<A.getChannels();c++){         // here, a dynamic channel loop
                A(x,y,c)=B(x,y,c);                        // is implemented
              }
            }
          }
        }
        
        inline void dynamic_image_copy_2(ImgQ &A,ImgQ &B){
          Channel32f *a = new Channel32f[A.getChannels()];     // pre allocate buffer for
          Channel32f *b = new Channel32f[A.getChannels()];     // the channel Objects 
          A.extractChannels(a);                                // assign the channel objects with
          B.extractChannels(b);                                // the channel data of the images
  
          for(int x=0;x<A.getWidth();x++){
            for(int y=0;y<A.getHeight();y++){
              for(int c=0;c<A.getChannels();c++){                    // again use a dynamic channel loop, 
                a[c](x,y)=b[c](x,y);                                 // but make use of the channel struct
              }
            }
          }
          delete [] a;                                              // release the channel structs
          delete [] b;
        }

In this example, the lower function is only 3 times faster, than the above one. Here, the advantage is not as large as in the above examples, but an acceleration factor of 3 should not be neglected.

The Channel<T> template class is typedef'd for all current Img<T> classes Channel8u, Channel16s, Channel32s, Channel32f, Channel64f.

---

Member Typedef Documentation

template<class T>

typedef const T* icl::core::Channel< T >::const_iterator

const iterator type (just a const pointer)

template<class T>

typedef const ImgIterator<T> icl::core::Channel< T >::const_roi_iterator

type definition for a const ROI iterator

template<class T>

typedef T* icl::core::Channel< T >::iterator

typedef for a normal iterator (just a pointer)

template<class T>

typedef ImgIterator<T> icl::core::Channel< T >::roi_iterator

type definition for ROI iterator

---

Constructor & Destructor Documentation

template<class T>

icl::core::Channel< T >::Channel

(

)

[inline]

Empty constructor (create an invalid Channel object)

This constructor is necessary for the creation of uninitialized dynamic size arrays of Channel objects

template<class T>

icl::core::Channel< T >::Channel

(

const Channel< T > &

other

)

[inline]

Copy an image channel (this could be exploited to violate const concept)

template<class T>

icl::core::Channel< T >::Channel	(	const T *	data,
		const utils::Size &	size,
		const utils::Rect &	roi
	)		[inline, private]

private constructor

Parameters:

data	data pointer (image) wich's channel should be wrapped
size	size of the data
roi	roi of the data (image)

template<class T>

icl::core::Channel< T >::Channel	(	T *	data,
		const utils::Size &	size,
		const utils::Rect &	roi
	)		[inline, private]

---

Member Function Documentation

template<class T>

iterator icl::core::Channel< T >::begin

(

)

[inline]

returns the image iterator (equal to getData(channel))

template<class T>

const_iterator icl::core::Channel< T >::begin

(

)

const [inline]

returns the image iterator (equal to getData(channel)) (const)

template<class T>

roi_iterator icl::core::Channel< T >::beginROI

(

)

[inline]

returns the iterator for an images ROI

template<class T>

const_roi_iterator icl::core::Channel< T >::beginROI

(

)

const [inline]

returns the iterator for an images ROI (const)

template<class T>

iterator icl::core::Channel< T >::end

(

)

[inline]

returns the image end-iterator (equal to getData(channel)+getDim())

template<class T>

const_iterator icl::core::Channel< T >::end

(

)

const [inline]

returns the image end-iterator (const)

template<class T>

roi_iterator icl::core::Channel< T >::endROI

(

)

[inline]

returns the end-iterator for an images ROI

the returned iterator must not be incremented or decremented!

template<class T>

const_roi_iterator icl::core::Channel< T >::endROI

(

)

const [inline]

returns the end-iterator for an images ROI (const)

template<class T>

int icl::core::Channel< T >::getDim

(

)

const [inline]

returns the wrapped images dim = width*height

Returns:

wrapped images pixel count

template<class T>

int icl::core::Channel< T >::getHeight

(

)

const [inline]

returns the wrapped images height

Returns:

wrapped images height

template<class T>

const utils::Rect& icl::core::Channel< T >::getROI

(

)

const [inline]

returns the channel ROI

template<class T>

int icl::core::Channel< T >::getROIHeight

(

)

const [inline]

returns the channel ROI height

template<class T>

utils::Point icl::core::Channel< T >::getROIOffset

(

)

const [inline]

returns the channel ROI offset

template<class T>

utils::Size icl::core::Channel< T >::getROISize

(

)

const [inline]

returns the channel ROI size

template<class T>

int icl::core::Channel< T >::getROIWidth

(

)

const [inline]

returns the channel ROI width

template<class T>

int icl::core::Channel< T >::getROIXOffset

(

)

const [inline]

returns the channel ROI X-Offset

template<class T>

int icl::core::Channel< T >::getROIYOffset

(

)

const [inline]

returns the channel ROI Y-Offset

template<class T>

const utils::Size& icl::core::Channel< T >::getSize

(

)

const [inline]

retusn the wrapped images size

template<class T>

int icl::core::Channel< T >::getWidth

(

)

const [inline]

returns the wrapped images width

Returns:

wrapped images width

template<class T>

bool icl::core::Channel< T >::isNull

(

)

const [inline]

template<class T>

T& icl::core::Channel< T >::operator()	(	int	x,
		int	y
	)		[inline]

main working function: returns a reference to the pixel at position (x,y)

The data address is calculated by x+ImageWidth*y. Note: no checks are performed to ensure, that the position is valid!

Parameters:

x	x-Position
y	y-Position

Returns:

reference to the Pixel at (x,y)

template<class T>

T& icl::core::Channel< T >::operator()

(

const utils::Point &

p

)

[inline]

convenience function for point-based index access

calls operator()(p.x,p.y)

template<class T>

const T& icl::core::Channel< T >::operator()

(

const utils::Point &

p

)

const [inline]

convenience function for point-based index access (const)

calls operator()(p.x,p.y) const

template<class T>

const T& icl::core::Channel< T >::operator()	(	int	x,
		int	y
	)		const [inline]

main working function: returns const a reference to the pixel at position (x,y)

The data address is calculated by x+ImageWidth*y. Note: no checks are performed to ensure, that the position is valid!

Parameters:

x	x-Position
y	y-Position

Returns:

reference to the Pixel at (x,y)

template<class T>

template<class Vec2D >

T icl::core::Channel< T >::operator()

(

const Vec2D &

p

)

const [inline]

index operator with linear interpolation

The given source type must provide an index operator (so does e.g. icl::Point, icl::Point32f, icl::FixedMatrix and icl::FixedVector). There is no internal check so take care yourself that the given position is within the image rectangle

template<class T>

Channel<T>& icl::core::Channel< T >::operator=

(

Channel< T > &

other

)

[inline]

assignmet operator

template<class T>

const Channel<T>& icl::core::Channel< T >::operator=

(

const Channel< T > &

other

)

const [inline]

assign operator (also for const channels)

assign operator is const, as we use to const-ness to deny changes on the underlying image, but not on the Channel struct itself. Hence all class data is mutable

template<class T>

T& icl::core::Channel< T >::operator[]

(

int

idx

)

[inline]

working function for linear pixel array access ( not const version)

Parameters:

idx	pixel array index

Returns:

reference to the pixel at linear pixel offfset idx

template<class T>

const T& icl::core::Channel< T >::operator[]

(

int

idx

)

const [inline]

working function for linear pixel array access (const version)

Parameters:

idx	pixel array index

Returns:

reference to the pixel at linear pixel offfset idx

template<class T>

void icl::core::Channel< T >::redefineROI

(

const utils::Rect &

newROI

)

const [inline]

Sets a new ROI to this image channel (this does not affect the underlying images ROI)

Parameters:

newROI

new channel roi

---

Friends And Related Function Documentation

template<class T>

friend class Img< T > [friend]

mades Img<T> a friend to allow it construction of ImgChannels

---

Member Data Documentation

template<class T>

T* icl::core::Channel< T >::m_data [mutable, private]

template<class T>

utils::Rect icl::core::Channel< T >::m_roi [mutable, private]

template<class T>

utils::Size icl::core::Channel< T >::m_size [mutable, private]

---

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

• /home/jenkins/workspace/icl-manual-trunk/icl-manual/ICLCore/src/ICLCore/Channel.h