Image Component Library (ICL)
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Public Member Functions | Static Public Member Functions
icl::core::ImgIterator< Type > Class Template Reference

Iterator class used to iterate through an Images ROI-pixels. More...

#include <ImgIterator.h>

Inheritance diagram for icl::core::ImgIterator< Type >:
icl::math::MatrixSubRectIterator< Type >

List of all members.

Public Member Functions

 ImgIterator ()
 Default Constructor.
 ImgIterator (Type *data, int imageWidth, const utils::Rect &roi)
 ImgIterator (const ImgIterator< Type > &origin, const utils::Size &s, const utils::Point &a)
 3rd Constructor to create sub-regions of an Img-image
bool inRegionSubROI () const
 to check if iterator is still inside the ROI
ImgIterator< Type > & operator= (const math::MatrixSubRectIterator< Type > &other)
 Allows to assign const instances.
const ImgIterator< Type > & operator= (const math::MatrixSubRectIterator< Type > &other) const
 Allows to assign const instances.
int getROIWidth () const
 returns ROIS width
int getROIHeight () const
 returns ROIS width

Static Public Member Functions

static const ImgIterator< Type > create_end_roi_iterator (const Type *data, int width, const utils::Rect &roi)

Detailed Description

template<typename Type>
class icl::core::ImgIterator< Type >

Iterator class used to iterate through an Images ROI-pixels.

The ImgIterator is a utility to iterate line by line through all ROI-pixels of an image. The following ASCII image shows an images ROI.

      1st pixel
    ....+->Xoooooooo......... ---
    .......ooooooooo.........  |
    .......ooooooooo......... iRoiH
    .......ooooooooo.........  |
    .......ooooooooo......... ---

For image operation like thresholding or filters, it is necessary perform calculation for each ROI- pixel. To achieve that, the programmer needs to Take care about:

The following code examples demonstrate how to handle image ROIs using the ImgIterator drawing on the example of a "find-the-min-pixel"-function. The example can be found in "ICLCore/examples/img-iterator-benchmark.cpp"

Intel IPP

Ok, not very meaningful, but state of the art! If ICL is compiled without IPP the builtin-getMin()- function uses std::min_element instead. By the way, IPP-performance is ... legendary -- it's about 20-times faster than the C++ fallback!!

        icl8u find_min_ipp(const Img8u &i){
          return i.getMin();
          } // namespace core

std::min_element without ROI-iterator

Just for comparison, without roi-handling

        icl8u find_min_pointer_stl(const Img8u &i){
          return  *std::min_element(i.begin(0),i.end(0));


Quite easy to use, but surprisingly not slower than the version above, that does not care about ROIs.

        icl8u find_min_iterator_stl(const Img8u &i){
          return *std::min_element(i.beginROI(0),i.endROI(0));

C++ pointer version

This is just a reimplementation of std::min_element, so it's performance is comparable

        icl8u find_min_pointer_cpp(const Img8u &i){
          const icl8u *p = i.begin(0);
          const icl8u *end = p+i.getDim();
          icl8u minVal = *p++;
            if(*p < minVal) minVal = *p;
          return minVal;

C++ Iterator Version

This is slightly slower than std::min_element because stl uses loop unrolling.

        icl8u find_min_iterator_cpp(const Img8u &i){
          Img8u::roi_iterator p = i.beginROI(0);
          Img8u::const_roi_iterator end = i.endROI(0);
          Img8u::roi_iterator minIt = p;
          while(++p != end){
            if(*p < *minIt) minIt = p;
          return *minIt;

C++ Iterator Version using inRegionSubROI() (OLD-Style)

To compare performance with older iterator use, this function version is also listed here.

        icl8u find_min_iterator_cpp_inRegion(const Img8u &i){
          Img8u::roi_iterator p = i.beginROI(0);
          icl8u minVal = *p++;
            if(*p<minVal) minVal = *p;
          return minVal;


Ok, now let's have a look on the numbers: Here are the results of the demo example icl-img-iterator-benchmark for a Core-2-Duo with 2GHz and an input image of 1000x1000 pixels:

The ImgIterator<Type> is defined in the Img<Type> as roi_iterator. This offers an intuitive "stdlib-like" use.

Using the ImgIterator as ROW-iterator

The ImgIterator can be used as ROW-iterator too. Just call incRow() to move the iterator in y-direction

Using Nested ImgIterators for Neighborhood operations

In addition to the above functionalities, ImgIterators can be used for arbitrary image neighborhood operations like convolution, median or erosion. The following example explains how to create so called sub-region iterators, that work on a symmetrical neighborhood around a higher level ImgIterator.

        template<class KernelType, class SrcType, class DstType>
        void generic_cpp_convolution(const Img<SrcType> &src,
                                     Img<DstType> &dst,
                                     const KernelType *k,
                                     ConvolutionOp &op, int c){
          const ImgIterator<SrcType> s(const_cast<SrcType*>(src.getData(c)), src.getWidth(),Rect(op.getROIOffset(), dst.getROISize()));
          const ImgIterator<SrcType> sEnd = ImgIterator<SrcType>::create_end_roi_iterator(&src,c, Rect(op.getROIOffset(), dst.getROISize()));
          ImgIterator<DstType>      d = dst.beginROI(c);
          Point an = op.getAnchor();
          Size si = op.getMaskSize();
          int factor = op.getKernel().getFactor();
          for(; s != sEnd; ++s){
            const KernelType *m = k; 
            KernelType buffer = 0;
            for(const ImgIterator<SrcType> sR (s,si,an);sR.inRegionSubROI(); ++sR, ++m){
              buffer += (*m) * (KernelType)(*sR);
            *d++ = clipped_cast<KernelType, DstType>(buffer / factor);

This code implements a single channel image convolution operation.


There are 3 major ways to access the pixel data of an image.

Each method has its on advantages and disadvantages:


Please note that the const-ness of an ImgIterator instance does not say anything about the sturcture itselft. Hence also const ImgIterators can be 'moved' using ++-operators or incRow() method.
Instead, const-ness relates to the underlying image, which data is referenced by the iterator instance. A const image provides only const ImgIterators which do not allow to change the image data.

Constructor & Destructor Documentation

template<typename Type>
icl::core::ImgIterator< Type >::ImgIterator ( ) [inline]

Default Constructor.

Creates an ImgIterator object

template<typename Type>
icl::core::ImgIterator< Type >::ImgIterator ( Type *  data,
int  imageWidth,
const utils::Rect roi 
) [inline]

2nd Constructor creates an ImgIterator object with Type "Type"

datapointer to the corresponding channel data
imageWidthwidth of the corresponding image
roiROI rect for the iterator
template<typename Type>
icl::core::ImgIterator< Type >::ImgIterator ( const ImgIterator< Type > &  origin,
const utils::Size s,
const utils::Point a 
) [inline]

3rd Constructor to create sub-regions of an Img-image

This 3rd constructor creates a sub-region iterator, which may be used e.g. for arbitrary neighborhood operations like linear filters, medians, ... See the ImgIterator description for more detail.

originreference to source Iterator Object
smask size
amask anchor

Member Function Documentation

template<typename Type>
static const ImgIterator<Type> icl::core::ImgIterator< Type >::create_end_roi_iterator ( const Type *  data,
int  width,
const utils::Rect roi 
) [inline, static]
template<typename Type>
int icl::core::ImgIterator< Type >::getROIHeight ( ) const [inline]

returns ROIS width

template<typename Type>
int icl::core::ImgIterator< Type >::getROIWidth ( ) const [inline]

returns ROIS width

template<typename Type>
bool icl::core::ImgIterator< Type >::inRegionSubROI ( ) const [inline]

to check if iterator is still inside the ROI

This function was replaced by STL-like begin(), end() logic Although in some cases it might be quite useful, so we renamed it rather than deleting it

See also:
template<typename Type>
ImgIterator<Type>& icl::core::ImgIterator< Type >::operator= ( const math::MatrixSubRectIterator< Type > &  other) [inline]

Allows to assign const instances.

Reimplemented from icl::math::MatrixSubRectIterator< Type >.

template<typename Type>
const ImgIterator<Type>& icl::core::ImgIterator< Type >::operator= ( const math::MatrixSubRectIterator< Type > &  other) const [inline]

Allows to assign const instances.

Reimplemented from icl::math::MatrixSubRectIterator< Type >.

The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines