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

| Image Iterators |

General image iterator definition and implementations. More...

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

## Typedefs

typedef Diff2D | CoordinateIterator
| Simulate an image where each pixel contains its coordinate.

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

## Typedef Documentation

typedef Diff2D CoordinateIterator

Simulate an image where each pixel contains its coordinate.

CoordinateIterator used to be a separate class, but has now become an alias for vigra::Diff2D. This is possible because Diff2D now provides all the necessary functionality.

CoordinateIterator behaves like a read-only vigra::ImageIterator for an image in which each pixel contains its coordinate. This is useful for algorithms that need access to the current pixel's location. For example, you can use CoordinateIterator/Diff2D to find the center of mass of an image region. To implement this, we first need a functor for center-of-mass calculations:

        struct CenterOfMassFunctor
        {
            CenterOfMassFunctor()
            : x(0.0), y(0.0), size(0)
            {}

            void operator()(Diff2d const& diff)
            {
                ++size;
                x += diff.x;
                y += diff.y;
            }

            float xCenter() const
            {   return x / size; }

            float yCenter() const
            {   return y / size; }

            float x;
            float y;
            int size;
        };

Using this functor, we find the center of mass like so:

        vigra::BImage img(w,h);
        ... // mark a region in the image with '1', background with '0'

        CenterOfMassFunctor center;

        vigra::inspectImageIf(
            srcIterRange(Diff2D(), Diff2D() + img.size()),
            srcImage(img),
            center);

        std::cout << "Center of mass: " << center.xCenter() <<
                                    ", " << center.yCenter() << std::endl;

#include <vigra/imageiterator.hxx>

Namespace: vigra

© Ullrich Köthe (ullrich.koethe@iwr.uni-heidelberg.de) Heidelberg Collaboratory for Image Processing, University of Heidelberg, Germany | html generated using doxygen and Python VIGRA 1.6.0 (13 Aug 2008)