[ VIGRA Homepage | Class Index | Function Index | File Index | Main Page ]

details Image Iterators VIGRA

General image iterator definition and implementations. More...

Namespaces

namespace  vigra::detail

Classes

class  ConstImageIterator
 Standard 2D random access const iterator for images that store the data as a linear array. More...

class  ConstStridedImageIterator
 Const iterator to be used when pixels are to be skipped. More...

class  ConstValueIterator
 Iterator that always returns the constant specified in the constructor. More...

class  CoordinateIterator
 Simulate an image where each pixel contains its coordinate. More...

class  ImageIterator
 Standard 2D random access iterator for images that store the data in a linear array. More...

class  ImageIteratorBase
 Base class for 2D random access iterators. More...

struct  IteratorTraits
 Export associated information for each image iterator. More...

class  StridedImageIterator
 Iterator to be used when pixels are to be skipped. More...



Detailed Description


General image iterator definition and implementations.

The following tables describe the general requirements for image iterators and their iterator traits. The iterator implementations provided here may be used for any image data type that stores its data as a linear array of pixels. The array will be interpreted as a row-major matrix with a particular width.

Requirements for Image Iterators

Local Types Meaning
ImageIterator::value_typethe underlying image's pixel type
ImageIterator::PixelTypethe underlying image's pixel type
ImageIterator::reference the iterator's reference type (return type of *iter). Will be value_type & for a mutable iterator, and convertible to value_type const & for a const iterator.
ImageIterator::index_reference the iterator's index reference type (return type of iter[diff]). Will be value_type & for a mutable iterator, and convertible to value_type const & for a const iterator.
ImageIterator::pointer the iterator's pointer type (return type of iter.operator->()). Will be value_type * for a mutable iterator, and convertible to value_type const * for a const iterator.
ImageIterator::difference_type the iterator's difference type (vigra::Diff2D)
ImageIterator::iterator_category the iterator tag (vigra::image_traverser_tag)
ImageIterator::row_iteratorthe associated row iterator
ImageIterator::column_iteratorthe associated column iterator
ImageIterator::MoveXtype of the horizontal navigator
ImageIterator::MoveYtype of the vertical navigator
Operation Result Semantics
++i.x
i.x--
voidincrement x-coordinate
--i.x
i.x--
voiddecrement x-coordinate
i.x += dxImageIterator::MoveX & add dx to x-coordinate
i.x -= dxImageIterator::MoveX & subtract dx from x-coordinate
i.x - j.xint difference of the x-coordinates of i and j
i.x = j.xImageIterator::MoveX &i.x += j.x - i.x
i.x == i.yboolj.x - i.x == 0

i.x < j.xboolj.x - i.x > 0

++i.y
i.y++
voidincrement y-coordinate
--i.y
i.y--
voiddecrement y-coordinate
i.y += dyImageIterator::MoveY & add dy to y-coordinate
i.y -= dyImageIterator::MoveY & subtract dy from y-coordinate
i.y - j.yint difference of the y-coordinates of i and j
i.y = j.yImageIterator::MoveY &i.y += j.y - i.y
i.y == j.yboolj.y - i.y == 0

i.y < j.yboolj.y - i.y > 0
ImageIterator k(i)copy constructor
k = iImageIterator &assignment
ImageIterator kdefault constructor
ImageIterator::row_iterator r(i)construction of row iterator
ImageIterator::column_iterator c(i)construction of column iterator
i += diffImageIterator & { i.x += diff.x
i.y += diff.y; }
i -= diffImageIterator & { i.x -= diff.x
i.y -= diff.y; }
i + diffImageIterator { ImageIterator tmp(i);
tmp += diff;
return tmp; }
i - diffImageIterator { ImageIterator tmp(i);
tmp -= diff;
return tmp; }
i - jImageIterator::difference_type { ImageIterator::difference_type tmp(i.x - j.x, i.y - j.y);
return tmp; }
i == jbool i.x == j.x && i.y == j.y
*iImageIterator::reference access the current pixel
i[diff]ImageIterator::index_reference access pixel at offset diff
i(dx, dy)ImageIterator::index_reference access pixel at offset (dx, dy)
i->member()depends on operation call member function of underlying pixel type via operator-> of iterator
i, j, k are of type ImageIterator
diff is of type ImageIterator::difference_type
dx, dy are of type int

Requirements for Image Iterator Traits

The following iterator traits must be defined for an image iterator:

Types Meaning
IteratorTraits<ImageIterator>Iteratorthe iterator type the traits are referring to
IteratorTraits<ImageIterator>iteratorthe iterator type the traits are referring to
IteratorTraits<ImageIterator>value_typethe underlying image's pixel type
IteratorTraits<ImageIterator>reference the iterator's reference type (return type of *iter)
IteratorTraits<ImageIterator>index_reference the iterator's index reference type (return type of iter[diff])
IteratorTraits<ImageIterator>pointer the iterator's pointer type (return type of iter.operator->())
IteratorTraits<ImageIterator>difference_type the iterator's difference type
IteratorTraits<ImageIterator>iterator_category the iterator tag (vigra::image_traverser_tag)
IteratorTraits<ImageIterator>row_iteratorthe associated row iterator
IteratorTraits<ImageIterator>column_iteratorthe associated column iterator
IteratorTraits<ImageIterator>DefaultAccessor the default accessor to be used with the iterator
IteratorTraits<ImageIterator>default_accessor the default accessor to be used with the iterator

Argument Object Factories

Factory functions to create argument objects which simplify long argument lists.

- Image Based Argument Object Factories
- Iterator Based Argument Object Factories

Long argument lists provide for greater flexibility of functions, but they are also tedious and error prone, when we don't need the flexibility. Thus, we define argument objects which automatically provide reasonable defaults for those arguments that we didn't specify explicitly.

The argument objects are created via a number of factory functions. Since these functions have descriptive names, they also serve to improve readability: the name of each factory tells te purpose of its argument object.

Consider the following example. Without argument objects we had to write something like this (cf. copyImageIf()):

    vigra::BImage img1, img2, img3;
    
    // fill img1 and img2 ...
    
    vigra::copyImageIf(img1.upperLeft(), img1.lowerRight(), img1.accessor(),
                img2.upperLeft(), img2.accessor(),
                img3.upperLeft(), img3.accessor());

Using the argument object factories, this becomes much shorter and more readable:

    vigra::copyImageIf(srcImageRange(img1),
                maskImage(img2),
                destImage(img3));

The names of the factories clearly tell which image is source, mask, and destination. In addition, the suffix Range must be used for those argument objects that need to specify the lower right corner of the region of interest. Typically, this is only the first source argument, but sometimes the first destiniation argument must also contain a range.

The factory functions come in two flavours: Iterator based and image based factories. Above we have seen the image based variant. The iterator based variant would look like this:

    vigra::copyImageIf(srcIterRange(img1.upperLeft(), img1.lowerRight()),
                maskIter(img2.upperLeft()),
                destIter(img3.upperLeft()));

These factory functions contain the word Iter instead of the word Image, They would normally be used if we couldn't access the images (for example, within a function which got passed iterators) or if we didn't want to operate on the entire image. The default accessor is obtained via vigra::IteratorTraits.

All factory functions also allow to specify accessors explicitly. This is useful if we can't use the default accessor. This variant looks like this:

    vigra::copyImageIf(srcImageRange(img1),
                maskImage(img2, MaskPredicateAccessor()),
                destImage(img3));    

or

    vigra::copyImageIf(srcIterRange(img1.upperLeft(), img1.lowerRight()),
                maskIter(img2.upperLeft(), MaskPredicateAccessor()),
                destIter(img3.upperLeft()));

All versions can be mixed freely within one explession. Technically, the argument objects are simply defined as pairs and triples of iterators and accessor so that all algorithms should declare a call interface version based on pairs and triples (see for example copyImageIf()).

Image Based Argument Object Factories

Include: automatically included with the image classes
Namespace: vigra

These factories can be used to create argument objects when we are given instances or subclasses of vigra::BasicImage (see Standard Image Types for instances defined per default). These factory functions access img.upperLeft(), img.lowerRight(), and img.accessor() to obtain the iterators and accessor for the given image (unless the accessor is given explicitly). The following factory functions are provided:

vigra::BasicImage<SomeType> img;

srcImageRange(img)

create argument object containing upper left, lower right, and default accessor of source image

srcImageRange(img, SomeAccessor())

create argument object containing upper left, lower right of source image, and given accessor

srcImage(img)

create argument object containing upper left, and default accessor of source image

srcImage(img, SomeAccessor())

create argument object containing upper left of source image, and given accessor

maskImage(img)

create argument object containing upper left, and default accessor of mask image

maskImage(img, SomeAccessor())

create argument object containing upper left of mask image, and given accessor

destImageRange(img)

create argument object containing upper left, lower right, and default accessor of destination image

destImageRange(img, SomeAccessor())

create argument object containing upper left, lower right of destination image, and given accessor

destImage(img)

create argument object containing upper left, and default accessor of destination image

destImage(img, SomeAccessor())

create argument object containing upper left of destination image, and given accessor

Iterator Based Argument Object Factories

#include "vigra/iteratortraits.hxx" Namespace: vigra

These factories can be used to create argument objects when we are given Image Iterators. These factory functions use vigra::IteratorTraits to get the default accessor for the given iterator unless the accessor is given explicitly. The following factory functions are provided:

vigra::BasicImage<SomeType>::Iterator i1, i2;

srcIterRange(i1, i2)

create argument object containing the given iterators and corresponding default accessor (for source image)

srcIterRange(i1, i2, SomeAccessor())

create argument object containing given iterators and accessor (for source image)

srcIter(i1)

create argument object containing the given iterator and corresponding default accessor (for source image)

srcIter(i1, SomeAccessor())

create argument object containing given iterator and accessor (for source image)

maskIter(i1)

create argument object containing the given iterator and corresponding default accessor (for mask image)

maskIter(i1, SomeAccessor())

create argument object containing given iterator and accessor (for mask image)

destIterRange(i1, i2)

create argument object containing the given iterators and corresponding default accessor (for destination image)

destIterRange(i1, i2, SomeAccessor())

create argument object containing given iterators and accessor (for destination image)

destIter(i1)

create argument object containing the given iterator and corresponding default accessor (for destination image)

destIter(i1, SomeAccessor())

create argument object containing given iterator and accessor (for destination image)


Define Documentation


#define VIGRA_DEFINE_ITERATORTRAITS ITERATOR,
VALUETYPE,
ACCESSOR   

 

Value:

template<> \
    struct IteratorTraits<ITERATOR<VALUETYPE > > \
    { \
        typedef ITERATOR<VALUETYPE >                  Iterator; \
        typedef ITERATOR<VALUETYPE >                  iterator; \
        typedef iterator::iterator_category           iterator_category; \
        typedef iterator::value_type                  value_type; \
        typedef iterator::reference                   reference; \
        typedef iterator::index_reference             index_reference; \
        typedef iterator::pointer                     pointer; \
        typedef iterator::difference_type             difference_type; \
        typedef iterator::row_iterator                row_iterator; \
        typedef iterator::column_iterator             column_iterator; \
        typedef ACCESSOR<VALUETYPE >                  default_accessor; \
        typedef ACCESSOR<VALUETYPE >                  DefaultAccessor; \
    };

© Ullrich Köthe (koethe@informatik.uni-hamburg.de)
Cognitive Systems Group, University of Hamburg, Germany

html generated using doxygen and Python
VIGRA 1.2.0 (7 Aug 2003)