/**
\page ImageIteratorsPage Image Iterators
\section ImageIteratorsIntroduction 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:
\code
constexpr int nx = 200;
constexpr int ny = 100;
ImageType image(nx,ny);
for(int x=0; xGetRequestedRegion() );
it.GoToBegin();
while( !it.IsAtEnd() )
{
it.Set( 10 );
++it;
}
\endcode
This code can also be written as:
\code
ImageType::Pointer im = GetAnImageSomeHow();
ImageIterator it( im, im->GetRequestedRegion() );
for (it = it.Begin(); !it.IsAtEnd(); ++it)
{
it.Set( 10 );
}
\endcode
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.
\section IteratorTypes 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:
- itk::ImageRegionIterator
- itk::ImageRegionReverseIterator
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 :
\code
const * PixelType iterator;
\endcode
or to STL const_iterators:
\code
vector::const_iterator it;
\endcode
The class name of the iterator makes clears if it provides const access
or not. Some of the const iterators available are
- itk::ImageConstIterator
- itk::ImageConstIteratorWithIndex
- itk::ImageLinearConstIteratorWithIndex
- itk::ImageRegionConstIteratorWithIndex
- itk::ImageSliceConstIteratorWithIndex
\subsection NeighbohoodIteratorType 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
\ref NeighborhoodIteratorsPage.
\subsection STL 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.
\code
for (it = vec.begin(); it != vec.end(); ++it)
{}
\endcode
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:
\code
ImageType::Pointer im = GetAnImageSomeHow();
ImageIterator it( im, im->GetRequestedRegion() );
\endcode
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.
\code
for (it = it.Begin(); !it.IsAtEnd(); ++it)
{
it.Set( 10 );
}
\endcode
\subsection IteratorsRegions 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.
\section IteratorAPI Iterator API
\subsection IteratorsPositioning Position
\subsection IteratorsIntervals 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.
\subsection IteratorsDereferencing 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 :
\code
PixelType * p; // creation of the pointer
*p = 100; // write access to a data
PixelType a = *p; // read access to data
\endcode
Iterators dereference data using Set() and Get()
\code
imageIterator.Set( 100 );
PixelType a = imageIterator.Get();
\endcode
\subsection IteratorsOperatorPlusPlus operator++
The ++ operator will move the image iterator to the next pixel,
according to the particular order in which this iterator walks
the imaage.
\subsection IteratorsOperatorMinusMinus operator--
The -- operator will move the image iterator to the previous pixel,
according to the particular order in which this iterator walks
the imaage.
\subsection IteratorsIteratorsBegin 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.
\subsection IteratorsIteratorsEnd 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.
\subsection IteratorsIteratorsGotoBegin GotoBegin()
GotoBegin() repositions the iterator to the first pixel in the region.
\subsection IteratorsGotoEnd GotoEnd()
GotoEnd() repositions the iterator to one pixel past (in the same
row) the last pixel in the region.
\subsection IteratorsIsAtBegin 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().
\code
if (it.IsAtBegin()) {} // Fast
if (it == it.Begin()) {} // Slow
\endcode
\subsection IteratorsIsAtEnd 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().
\code
if (it.IsAtEnd()) {} // Fast
if (it == it.End()) {} // Slow
\endcode
\section IteratorFinalComment 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 writing
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.
*/