<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><meta name="robots" content="noindex">
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>ITK: Image Iterators</title>
<link href="DoxygenStyle.css" rel="stylesheet" type="text/css">
</head><body bgcolor="#ffffff">
<!-- Section customized for INSIGHT : Tue Jul 17 01:02:45 2001 -->
<center>
<a href="index.html" class="qindex">Main Page</a>
<a href="modules.html" class="qindex">Groups</a>
<a href="namespaces.html" class="qindex">Namespace List</a>
<a href="hierarchy.html" class="qindex">Class Hierarchy</a>
<a href="classes.html" class="qindex">Alphabetical List</a>
<a href="annotated.html" class="qindex">Compound List</a>
<a href="files.html" class="qindex">File
List</a>
<a href="namespacemembers.html" class="qindex">Namespace Members</a>
<a href="functions.html" class="qindex">Compound Members</a>
<a href="globals.html" class="qindex">File Members</a>
<a href="pages.html" class="qindex">Concepts</a></center>
<!-- Generated by Doxygen 1.5.9 -->
<div class="contents">
<h1><a class="anchor" name="ImageIteratorsPage">Image Iterators </a></h1><h2><a class="anchor" name="ImageIteratorsIntroduction">
Introduction</a></h2>
ImageIterators are the mechanism used in ITK for walking through the image data.<p>
You probably learned image processing with the classical access to the image data using <b>"for loops"</b> like:<p>
<div class="fragment"><pre class="fragment"> <span class="keyword">const</span> <span class="keywordtype">int</span> nx = 200;
<span class="keyword">const</span> <span class="keywordtype">int</span> ny = 100;
ImageType image(nx,ny);
<span class="keywordflow">for</span>(<span class="keywordtype">int</span> x=0; x<nx; x++) <span class="comment">// for all Columns</span>
{
<span class="keywordflow">for</span>(<span class="keywordtype">int</span> y=0; y<ny; y++) <span class="comment">// for all Rows</span>
{
image(x,y) = 10;
}
}
</pre></div><p>
When what you <em>really</em> mean is:<p>
<div class="fragment"><pre class="fragment"> ForAllThePixels p in image Do p = 100
</pre></div><p>
ImageIterators gets you closer to this algorithmic abstraction. They abstract the low-level processing of images from the particular implementation of the image class.<p>
Here is how an image iterator is used in ITK:<p>
<div class="fragment"><pre class="fragment"> <a class="code" href="itkFEMMacro_8h.html#539cce1a3282ba59952dedcbf9cdb23f">ImageType::Pointer</a> im = GetAnImageSomeHow();
ImageIterator it( im, im->GetRequestedRegion() );
it.GoToBegin();
<span class="keywordflow">while</span>( !it.IsAtEnd() )
{
it.Set( 10 );
++it;
}
</pre></div><p>
This code can also be written as:<p>
<div class="fragment"><pre class="fragment"> <a class="code" href="itkFEMMacro_8h.html#539cce1a3282ba59952dedcbf9cdb23f">ImageType::Pointer</a> im = GetAnImageSomeHow();
ImageIterator it( im, im->GetRequestedRegion() );
<span class="keywordflow">for</span> (it = it.Begin(); !it.IsAtEnd(); ++it)
{
it.Set( 10 );
}
</pre></div><p>
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.<p>
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.<p>
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.<h2><a class="anchor" name="IteratorTypes">
Types of Iterators</a></h2>
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.<p>
To address these diverse requirements, ITK implements a set of ImageIterators, always following the "C" philosophy of :<p>
"You only pay for what you use"<p>
Here is a list of some of the different ImageIterators implemented in ITK:<p>
<ul>
<li><a class="el" href="classitk_1_1ImageRegionIterator.html" title="A multi-dimensional iterator templated over image type that walks a region of pixels...">itk::ImageRegionIterator</a></li><li><a class="el" href="classitk_1_1ImageRegionReverseIterator.html" title="Multi-dimensional image iterator which only walks a region.">itk::ImageRegionReverseIterator</a></li></ul>
<p>
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.<p>
The following iterators allow to walk the image in specific directions<p>
<ul>
<li><a class="el" href="classitk_1_1ImageLinearIteratorWithIndex.html" title="A multi-dimensional image iterator that visits image pixels within a region in a...">itk::ImageLinearIteratorWithIndex</a> Along lines</li><li><a class="el" href="classitk_1_1ImageSliceIteratorWithIndex.html" title="A multi-dimensional image iterator that extends the ImageLinearIteratorWithIndex...">itk::ImageSliceIteratorWithIndex</a> Along lines, then along planes</li></ul>
<p>
Iterators in general can have <b>Read/Write</b> access to image pixels. <a class="el" href="classA.html">A</a> family of iterators provides <b>Read Only</b> access, in order to preserve the image content. These iterators are equivalent to "C" const pointers :<p>
<div class="fragment"><pre class="fragment"> <span class="keyword">const</span> * PixelType iterator;
</pre></div><p>
or to STL const_iterators:<p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classstd_1_1vector.html">vector<PixelType>::const_iterator</a> it;
</pre></div><p>
The class name of the iterator makes clears if it provides const access or not. Some of the <code>const</code> iterators available are<p>
<ul>
<li><a class="el" href="classitk_1_1ImageConstIterator.html" title="A multi-dimensional image iterator templated over image type.">itk::ImageConstIterator</a></li><li><a class="el" href="classitk_1_1ImageConstIteratorWithIndex.html" title="A base class for multi-dimensional iterators templated over image type that are designed...">itk::ImageConstIteratorWithIndex</a></li><li><a class="el" href="classitk_1_1ImageLinearConstIteratorWithIndex.html" title="A multi-dimensional image iterator that visits image pixels within a region in a...">itk::ImageLinearConstIteratorWithIndex</a></li><li><a class="el" href="classitk_1_1ImageRegionConstIteratorWithIndex.html" title="A multi-dimensional iterator templated over image type that walks an image region...">itk::ImageRegionConstIteratorWithIndex</a></li><li><a class="el" href="classitk_1_1ImageSliceConstIteratorWithIndex.html" title="Multi-dimensional image iterator which only walks a region.">itk::ImageSliceConstIteratorWithIndex</a></li></ul>
<h3><a class="anchor" name="NeighbohoodIteratorType">
Other Types of Iterators</a></h3>
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 <a class="el" href="NeighborhoodIteratorsPage.html">Neighborhood Iterators</a>.<h3><a class="anchor" name="STL">
ImageIterators vs. STL Iterators</a></h3>
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.<p>
<div class="fragment"><pre class="fragment"> <span class="keywordflow">for</span> (it = vec.begin(); it != vec.end(); ++it)
{}
</pre></div><p>
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.<p>
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:<p>
<div class="fragment"><pre class="fragment"> <a class="code" href="itkFEMMacro_8h.html#539cce1a3282ba59952dedcbf9cdb23f">ImageType::Pointer</a> im = GetAnImageSomeHow();
ImageIterator it( im, im->GetRequestedRegion() );
</pre></div><p>
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.<p>
<div class="fragment"><pre class="fragment"> <span class="keywordflow">for</span> (it = it.Begin(); !it.IsAtEnd(); ++it)
{
it.Set( 10 );
}
</pre></div><h3><a class="anchor" name="IteratorsRegions">
Regions</a></h3>
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.<h2><a class="anchor" name="IteratorAPI">
Iterator API</a></h2>
<h3><a class="anchor" name="IteratorsPositioning">
Position</a></h3>
<h3><a class="anchor" name="IteratorsIntervals">
Half Open Intervals - Begin/End</a></h3>
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.<h3><a class="anchor" name="IteratorsDereferencing">
Dereferencing</a></h3>
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 :<p>
<div class="fragment"><pre class="fragment"> PixelType * p; <span class="comment">// creation of the pointer</span>
*p = 100; <span class="comment">// write access to a data </span>
PixelType a = *p; <span class="comment">// read access to data</span>
</pre></div><p>
Iterators dereference data using <code>Set()</code> and <code>Get()</code><p>
<div class="fragment"><pre class="fragment"> imageIterator.Set( 100 );
PixelType a = imageIterator.Get();
</pre></div><h3><a class="anchor" name="IteratorsOperatorPlusPlus">
operator++</a></h3>
The ++ operator will move the image iterator to the next pixel, according to the particular order in which this iterator walks the imaage.<h3><a class="anchor" name="IteratorsOperatorMinusMinus">
operator--</a></h3>
The -- operator will move the image iterator to the previous pixel, according to the particular order in which this iterator walks the imaage.<h3><a class="anchor" name="IteratorsIteratorsBegin">
Begin()</a></h3>
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.<h3><a class="anchor" name="IteratorsIteratorsEnd">
End()</a></h3>
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.<h3><a class="anchor" name="IteratorsIteratorsGotoBegin">
GotoBegin()</a></h3>
GotoBegin() repositions the iterator to the first pixel in the region.<h3><a class="anchor" name="IteratorsGotoEnd">
GotoEnd()</a></h3>
GotoEnd() repositions the iterator to one pixel past (in the same row) the last pixel in the region.<h3><a class="anchor" name="IteratorsIsAtBegin">
IsAtBegin()</a></h3>
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().<p>
<div class="fragment"><pre class="fragment"> <span class="keywordflow">if</span> (it.IsAtBegin()) {} <span class="comment">// Fast</span>
<span class="keywordflow">if</span> (it == it.Begin()) {} <span class="comment">// Slow</span>
</pre></div><h3><a class="anchor" name="IteratorsIsAtEnd">
IsAtEnd()</a></h3>
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().<p>
<div class="fragment"><pre class="fragment"> <span class="keywordflow">if</span> (it.IsAtEnd()) {} <span class="comment">// Fast</span>
<span class="keywordflow">if</span> (it == it.End()) {} <span class="comment">// Slow</span>
</pre></div><h2><a class="anchor" name="IteratorFinalComment">
Final Comments</a></h2>
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.<p>
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. </div>
<hr><address><small>
Generated at Fri May 8 00:42:55 2009 for ITK by <a href="http://www.stack.nl/~dimitri/doxygen/index.html"> <img
src="http://www.stack.nl/~dimitri/doxygen/doxygen.png" alt="doxygen"
align="middle" border=0 width=110 height=53>
</a> 1.5.9 written by <a href="mailto:dimitri@stack.nl">Dimitri van Heesch</a>,
© 1997-2000</small></address>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
d5e74628f0e673bb8680aebce32b2c04
>
files
>
33
