Introduction

ImageIterators are the mechanism used in ITK for walking through the image data.

You probably learned image processing with the classical access to the image data using "for loops" like:

constexpr int nx  = 200;
constexpr int ny  = 100;
ImageType image(nx,ny);
for(int x=0; x<nx; x++) // for all Columns
{
  for(int y=0; y<ny; y++) // for all Rows
  {
    image(x,y) = 10;
  }
}

When what you really mean is:

ForAllThePixels p in image Do p = 100

ImageIterators gets you closer to this algorithmic abstraction. They abstract the low-level processing of images from the particular implementation of the image class.

Here is how an image iterator is used in ITK:

ImageType::Pointer im = GetAnImageSomeHow();
ImageIterator  it( im, im->GetRequestedRegion() );
it.GoToBegin();
while( !it.IsAtEnd() )
{
  it.Set( 10 );
  ++it;
}

This code can also be written as:

ImageType::Pointer im = GetAnImageSomeHow();
ImageIterator  it( im, im->GetRequestedRegion() );
for (it = it.Begin(); !it.IsAtEnd(); ++it)
{
  it.Set( 10 );
}

One important advantage of ImageIterators is that they provide support for the N-Dimensional images in ITK. Otherwise it would be impossible (or at least very hard) to write algorithms that work independent of the image dimension.

Another advantage of ImageIterators is that they support walking a region of an image. In fact, one argument of an ImageIterator's constructor defines the region or portion of an image to traverse.

Iterators know a lot about the internal composition of the image, relieving the user from these details. Your algorithm can go through all the pixels of an image without ever knowing the dimension of the image.

Types of Iterators

The order in which the image pixels are visited can be quite important for some image processing algorithms and may be inconsequential to other algorithms as long as pixels are accessed as fast as possible.

To address these diverse requirements, ITK implements a set of ImageIterators, always following the "C" philosophy of :

"You only pay for what you use"

Here is a list of some of the different ImageIterators implemented in ITK:

Region iterators don't define any specific order to walk over the pixels on the image. The user can be sure though, that all the pixels inside the region will be visited.

The following iterators allow to walk the image in specific directions

itk::ImageLinearIteratorWithIndex Along lines
itk::ImageSliceIteratorWithIndex Along lines, then along planes

Iterators in general can have Read/Write access to image pixels. A family of iterators provides Read Only access, in order to preserve the image content. These iterators are equivalent to "C" const pointers :

const * PixelType iterator;

or to STL const_iterators:

vector<PixelType>::const_iterator it;

The class name of the iterator makes clears if it provides const access or not. Some of the const iterators available are

Other Types of Iterators

Another group of iterators support a moving neighborhood. Here the neighborhood can "iterate" over an image and a calculation can iterate over the neighborhood. This allows N-dimensional implementations of convolution and finite differences to be implemented succintly. This class of iterators is described in detail on the page Neighborhood Iterators.

ImageIterators vs. STL Iterators

Given the breadth and complexity of ImageIterators, they are designed to operate slightly differently than STL iterators. In STL, you ask a container for an iterator that will traverse the container. Furthermore, in STL, you frequently compare an iterator against another iterator. Here is a loop to walk over an STL vector.

for (it = vec.begin(); it != vec.end(); ++it)

{}

ImageIterators, unfortunately, are more complicated than STL iterators. ImageIterators need to store more state information than STL iterators. As one example, ImageIterators can walk a region of an image and an image can have multiple ImageIterators traversing different regions simultaneously. Thus, each ImageIterator must maintain which region it traverses. This results in a fairly heavyweight iterator, where comparing two ImageIterators and constructing iterators is an expensive operation. To address this issue, ImageIterators have a slightly different API than STL iterators.

First, you do not ask the container (the image) for an iterator. Instead, you construct an iterator and tell it which image to traverse. Here is a snippet of code to construct an iterator that will walk a region of an image:

ImageType::Pointer im = GetAnImageSomeHow();
ImageIterator  it( im, im->GetRequestedRegion() );

Second, since constructing and comparing ImageIterators is expensive, ImageIterators know the beginning and end of the region. So you ask the iterator rather than the container whether the iterator is at the end of a region.

for (it = it.Begin(); !it.IsAtEnd(); ++it)
{
  it.Set( 10 );
}

Regions

Iterators are typically defined to walk a region of an image. ImageRegions are defined to be rectangular prisms. (Insight also has a number of iterators that can walk a region defined by a spatial function.) The region for an iterator is defined at constructor time. Regions are not validated, so the programmer is responsible for assigning a region that is within the image. Iterator methods Begin() and End() are defined relative to the region. See below.

Iterator API

Position

Half Open Intervals - Begin/End

Like most iterator implementations, ImageIterators walk a half-open interval. Begin is defined as the first pixel in the region. End is defined as one pixel past the last pixel in the region (one pixel past in the same row). So Begin points a valid pixel in the region and End points to a pixel that is outside the region.

Dereferencing

In order to get access to the image data pointed by the iterator, dereferencing is required. This is equivalent to the classical "C" dereferencing code :

PixelType * p;    // creation of the pointer
*p = 100;         // write access to a data
PixelType a = *p; // read access to data

Iterators dereference data using Set() and Get()

imageIterator.Set( 100 );

PixelType a = imageIterator.Get();

operator++

The ++ operator will move the image iterator to the next pixel, according to the particular order in which this iterator walks the imaage.

operator--

The – operator will move the image iterator to the previous pixel, according to the particular order in which this iterator walks the imaage.

Begin()

Begin() returns an iterator for the same image and region as the current iterator but positioned at the first pixel in the region. The current iterator is not modified.

End()

End() returns an iterator for the same image and region as the current iterator but positioned one pixel past the last pixel in the region. The current iterator is not modified.

GotoBegin()

GotoBegin() repositions the iterator to the first pixel in the region.

GotoEnd()

GotoEnd() repositions the iterator to one pixel past (in the same row) the last pixel in the region.

IsAtBegin()

IsAtBegin() returns true if the iterator is positioned at the first pixel in the region, returns false otherwise. IsAtBegin() is faster than comparing an iterator for equivalence to the iterator returned by Begion().

if (it.IsAtBegin()) {}   // Fast
if (it == it.Begin()) {} // Slow

IsAtEnd()

IsAtEnd() returns true if the iterator is positioned one pixel past the last pixel in the region, returns false otherwise. IsAtEnd() is faster than comparing an iterator for equivalence to the iterator returned by End().

if (it.IsAtEnd()) {}   // Fast
if (it == it.End()) {} // Slow

Final Comments

In general, iterators are not the kind of objects that users of the toolkit would need to use. They are rather designed to be used by code developers that add new components to the toolkit, like writting a new Image filter, for example.

Before starting to write code that use iterators, users should consider to verify if the particular operation they intend to apply to the image is not already defined in the form of an existing image filter.