Detailed Description

Defines iteration of a local N-dimensional neighborhood of pixels across an itk::Image.

This class is a loose extension of the Standard Template Library (STL) bi-directional iterator concept to masks of pixel neighborhoods within itk::Image objects. This NeighborhoodIterator base class defines simple forward and reverse iteration of an N-dimensional neighborhood mask across an image. Elements within the mask can be accessed like elements within an array.

NeighborhoodIterators are designed to encapsulate some of the complexity of working with image neighborhoods, complexity that would otherwise have to be managed at the algorithmic level. Use NeighborhoodIterators to simplify writing algorithms that perform geometrically localized operations on images (for example, convolution and morphological operations).

To motivate the discussion of NeighborhoodIterators and their use in Itk, consider the following code that takes directional derivatives at each point in an image.

Most of the work for the programmer in the code above is in setting up for the iteration. There are three steps. First an inner product function object is created which will be used to effect convolution with the derivative kernel. Setting up the derivative kernel, DerivativeOperator, involves setting the order and direction of the derivative. Finally, we create an iterator over the RequestedRegion of the itk::Image (see Image) using the radius of the derivative kernel as the size.

Itk iterators only loosely follow STL conventions. Notice that instead of asking myImage for myImage.begin() and myImage.end(), iterator.SetToBegin() and iterator.IsAtEnd() are called. Itk iterators are typically more complex objects than traditional, pointer-style STL iterators, and the increased overhead required to conform to the complete STL API is not always justified.

A NeighborhoodIterator is constructed as a container of pointers (offsets) to a geometric neighborhood of image pixels. As the central pixel position in the mask is moved around the image, the neighboring pixel pointers (offsets) are moved accordingly.

A pixelneighborhood is defined as a central pixel location and an N-dimensional radius extending outward from that location.

Pixels in a neighborhood can be accessed through a NeighborhoodIterator like elements in an array. For example, a 2D neighborhood with radius 2x1 has indices:

0 1 2 3 4
5 6 7 8 9
10 11 12 13 14

Now suppose a NeighborhoodIterator with the above dimensions is constructed and positioned over a neighborhood of values in an Image:

1.2 1.3 1.8 1.4 1.1
1.8 1.1 0.7 1.0 1.0
2.1 1.9 1.7 1.4 2.0

Shown below is some sample pixel access code and the values that it returns.

Use of GetPixel() is preferred over the *iterator[] form, and can be used without loss of efficiency in most cases. Some variations (subclasses) of NeighborhoodIterators may exist which do not support the latter API. Corresponding SetPixel() methods exist to modify pixel values in non-const NeighborhoodIterators.

NeighborhoodIterators are "bidirectional iterators". They move only in two directions through the data set. These directions correspond to the layout of the image data in memory and not to spatial directions of the N-dimensional itk::Image. Iteration always proceeds along the fastest increasing dimension (as defined by the layout of the image data) . For itk::Image this is the first dimension specified (i.e. for 3-dimensional (x,y,z) NeighborhoodIterator proceeds along the x-dimension) (For random access iteration through N-dimensional indicies, use RandomAccessNeighborhoodIterator.)

Each subclass of a ConstNeighborhoodIterator may also define its own mechanism for iteration through an image. In general, the Iterator does not directly keep track of its spatial location in the image, but uses a set of internal loop variables and offsets to trigger wraps at itk::Image region boundaries, and to identify the end of the itk::Image region.

For a complete description of the ITK Image Iterators and their API, please see the Iterators chapter in the ITK Software Guide. The ITK Software Guide is available in print and as a free .pdf download from http://www.itk.org.

Returns the pixel value located at the itk::Offset o from the center of the neighborhood. Sets "IsInBounds" to true if the offset is inside the image and the pixel value returned is an actual pixel in the image. Sets "IsInBounds" to false if the offset is outside the image and the pixel value returned is a boundary condition.

Return the pixel value located at a linear array location i. Sets "IsInBounds" to true if the location is inside the image and the pixel value returned is an actual pixel in the image. Sets "IsInBounds" to false if the location is outside the image and the pixel value returned is a boundary condition.

Returns the internal offset associated with wrapping around a single dimension's region boundary in the itk::Image. An offset for each dimension is necessary to shift pointers when wrapping around region edges because region memory is not necessarily contiguous within the buffer.

Allows a user to override the internal boundary condition. Care should be taken to ensure that the overriding boundary condition is a persistent object during the time it is referenced. The overriding condition can be of a different type than the default type as long as it is a subclass of ImageBoundaryCondition.

This method positions the iterator at an indexed location in the image. SetLocation should _NOT_ be used to update the position of the iterator during iteration, only for initializing it to a position prior to iteration. This method is not optimized for speed.

Pointer to the actual boundary condition that will be used. By default this points to m_BoundaryCondition, but OverrideBoundaryCondition allows a user to point this variable an external boundary condition.

The internal array of offsets that provide support for regions of interest. An offset for each dimension is necessary to shift pointers when wrapping around region edges because region memory is not necessarily contiguous within the buffer.