VIGRA - Image Iterators

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

| Image Iterators |
--- | --- | ---

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_type` | the underlying image's pixel type
`ImageIterator::PixelType` | the 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_iterator` | the associated row iterator
`ImageIterator::column_iterator` | the associated column iterator
`ImageIterator::MoveX` | type of the horizontal navigator
`ImageIterator::MoveY` | type of the vertical navigator
Operation | Result | Semantics
`++i.x i.x--` | `void` | increment x-coordinate
`--i.x i.x--` | `void` | decrement x-coordinate
`i.x += dx` | `ImageIterator::MoveX &` | add `dx` to x-coordinate
`i.x -= dx` | `ImageIterator::MoveX &` | subtract `dx` from x-coordinate
`i.x - j.x` | `int` | difference of the x-coordinates of `i` and `j`
`i.x = j.x` | `ImageIterator::MoveX &` | `i.x += j.x - i.x`
`i.x == i.y` | `bool` | `j.x - i.x == 0`
`i.x < j.x` | `bool` | `j.x - i.x > 0`
`++i.y i.y++` | `void` | increment y-coordinate
`--i.y i.y--` | `void` | decrement y-coordinate
`i.y += dy` | `ImageIterator::MoveY &` | add `dy` to y-coordinate
`i.y -= dy` | `ImageIterator::MoveY &` | subtract `dy` from y-coordinate
`i.y - j.y` | `int` | difference of the y-coordinates of `i` and `j`
`i.y = j.y` | `ImageIterator::MoveY &` | `i.y += j.y - i.y`
`i.y == j.y` | `bool` | `j.y - i.y == 0`
`i.y < j.y` | `bool` | `j.y - i.y > 0`
`ImageIterator k(i)` | copy constructor
`k = i` | `ImageIterator &` | assignment
`ImageIterator k` | default constructor
`ImageIterator::row_iterator r(i)` | construction of row iterator
`ImageIterator::column_iterator c(i)` | construction of column iterator
`i += diff` | `ImageIterator &` | `{ i.x += diff.x i.y += diff.y; }`
`i -= diff` | `ImageIterator &` | `{ i.x -= diff.x i.y -= diff.y; }`
`i + diff` | `ImageIterator` | `{ ImageIterator tmp(i); tmp += diff; return tmp; }`
`i - diff` | `ImageIterator` | `{ ImageIterator tmp(i); tmp -= diff; return tmp; }`
`i - j` | `ImageIterator::difference_type` | `{ ImageIterator::difference_type tmp(i.x - j.x, i.y - j.y); return tmp; }`
`i == j` | `bool` | `i.x == j.x && i.y == j.y`
`*i` | `ImageIterator::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>Iterator` | the iterator type the traits are referring to
`IteratorTraits<ImageIterator>iterator` | the iterator type the traits are referring to
`IteratorTraits<ImageIterator>value_type` | the 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_iterator` | the associated row iterator
`IteratorTraits<ImageIterator>column_iterator` | the 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
`IteratorTraits<ImageIterator>hasConstantStrides` | whether the iterator uses constant strides on the underlying memory (always `VigraTrueType` for `ImageIterator`s).

### Argument Object Factories

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

Image Based Argument Object Factories
MultiArrayView 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;` or `vigra::BasicImageView<SomeType> img;`
`srcImageRange(img)` | create argument object containing upper left, lower right, and default accessor of source image
`srcImageRange(img, Rect2D(...))` | create argument object containing the ROI specified by `vigra::Rect2D` and default accessor of source image
`srcImageRange(img, SomeAccessor())` | create argument object containing upper left, lower right of source image, and given accessor
`srcImageRange(img, Rect2D(...), SomeAccessor())` | create argument object containing the ROI specified by `vigra::Rect2D` and of source image, and given accessor
`srcImage(img)` | create argument object containing upper left, and default accessor of source image
`srcImage(img, Point2D(...))` | create argument object with upper left at point given by `vigra::Point2D`, and default accessor of source image
`srcImage(img, SomeAccessor())` | create argument object containing upper left of source image, and given accessor
`srcImage(img, Point2D(...), SomeAccessor())` | create argument object with upper left at point given by `vigra::Point2D` of source image, and given accessor
`maskImage(img)` | create argument object containing upper left, and default accessor of mask image
`maskImage(img, Point2D(...))` | create argument object with upper left at point given by `vigra::Point2D`, and default accessor of mask image
`maskImage(img, SomeAccessor())` | create argument object containing upper left of mask image, and given accessor
`maskImage(img, Point2D(...), SomeAccessor())` | create argument object with upper left at point given by `vigra::Point2D` of mask image, and given accessor
`destImageRange(img)` | create argument object containing upper left, lower right, and default accessor of destination image
`destImageRange(img, Rect2D(...))` | create argument object containing the ROI specified by `vigra::Rect2D` and default accessor of destination image
`destImageRange(img, SomeAccessor())` | create argument object containing upper left, lower right of destination image, and given accessor
`destImageRange(img, Rect2D(...), SomeAccessor())` | create argument object containing the ROI specified by `vigra::Rect2D` of destination image, and given accessor
`destImage(img)` | create argument object containing upper left, and default accessor of destination image
`destImage(img, Point2D(...))` | create argument object with upper left at point given by `vigra::Point2D`, and default accessor of destination image
`destImage(img, SomeAccessor())` | create argument object containing upper left of destination image, and given accessor
`destImage(img, Point2D(...), SomeAccessor())` | create argument object with upper left at point given by `vigra::Point2D` of destination image, and given accessor

## MultiArrayView Based Argument Object Factories

Include: automatically included with "vigra/multi_array.hxx"
Namespace: vigra

These factories can be used to create argument objects when we are given instances or subclasses of vigra::MultiArrayView. These factory functions access `array.traverser_begin()`, `array.traverser_end()` to obtain the iterators. If no accessor is given, they use the `AccessorTraits<T>` to determine the default accessor associated with the array's value type `T`. The following factory functions are provided:

`vigra::MultiArrayView<N, SomeType> array;`
`srcMultiArrayRange(img)` | create argument object containing a vigra::MultiIterator marking the begin of the array, a shape object giving the desired shape of the array (possibly a subarray) and the default const accessor for `SomeType`
`srcMultiArrayRange(img, SomeAccessor())` | create argument object containing a vigra::MultiIterator marking the begin of the array, a shape object giving the desired shape of the array (possibly a subarray) and the given accessor
`srcMultiArray(img)` | create argument object containing a vigra::MultiIterator marking the begin of the array, and the default const accessor for `SomeType`
`srcMultiArray(img, SomeAccessor())` | create argument object containing a vigra::MultiIterator marking the begin of the array and the given accessor
`destMultiArrayRange(img)` | create argument object containing a vigra::MultiIterator marking the begin of the array, a shape object giving the desired shape of the array (possibly a subarray) and the default accessor for `SomeType`
`destMultiArrayRange(img, SomeAccessor())` | create argument object containing a vigra::MultiIterator's marking the begin of the array, a shape object giving the desired shape of the array (possibly a subarray) and the given accessor
`destMultiArray(img)` | create argument object containing a vigra::MultiIterator marking the begin of the array and the default accessor for `SomeType`
`destMultiArray(img, SomeAccessor())` | create argument object containing a vigra::MultiIterator's marking the begin of the array and the 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)

© Ullrich Köthe (koethe@informatik.uni-hamburg.de) Cognitive Systems Group, University of Hamburg, Germany | html generated using doxygen and Python VIGRA 1.5.0 (7 Dec 2006)