Image Iterators

General image iterator definition and implementations. More...

Classes
class	ConstImageIterator< PIXELTYPE >
	Standard 2D random access const iterator for images that store the data as a linear array. More...
class	ConstStridedImageIterator< PIXELTYPE >
	Const iterator to be used when pixels are to be skipped. More...
class	ConstValueIterator< PIXELTYPE >
	Iterator that always returns the constant specified in the constructor. More...
class	ImageIterator< PIXELTYPE >
	Standard 2D random access iterator for images that store the data in a linear array. More...
class	ImageIteratorBase< IMAGEITERATOR, PIXELTYPE, REFERENCE, POINTER, StridedOrUnstrided >
	Base class for 2D random access iterators. More...
struct	IteratorTraits< T >
	Export associated information for each image iterator. More...
class	StridedImageIterator< PIXELTYPE >
	Iterator to be used when pixels are to be skipped. More...

Typedefs
typedef Diff2D	CoordinateIterator
	Simulate an image where each pixel contains its coordinate. 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 ImageIterators).

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