Neighborhood Iterator on Vector Image#

Synopsis#

NeighborhoodIterator on a VectorImage.

Results#

Warning

Fix Errors Example contains errors needed to be fixed for proper output.

Code#

C++#

#include "itkVectorImage.h"
#include "itkNeighborhoodIterator.h"

using VectorImageType = itk::VectorImage<unsigned char, 2>;

int
main()
{
  // Create an image
  auto image = VectorImageType::New();

  itk::Index<2> start;
  start.Fill(0);

  itk::Size<2> size;
  size.Fill(10);

  itk::ImageRegion<2> region(start, size);

  image->SetRegions(region);
  image->SetNumberOfComponentsPerPixel(3);
  image->Allocate();

  // Create the neighborhood iterator
  VectorImageType::SizeType radius;
  radius[0] = 1;
  radius[1] = 1;

  itk::NeighborhoodIterator<VectorImageType> iterator(radius, image, image->GetLargestPossibleRegion());

  while (!iterator.IsAtEnd())
  {
    iterator.GetCenterPixel();

    ++iterator;
  }


  return EXIT_SUCCESS;
}

Classes demonstrated#

template<typename TPixel, unsigned int VImageDimension = 3>
class VectorImage : public itk::ImageBase<VImageDimension>

Templated n-dimensional vector image class.

This class differs from Image in that it is intended to represent multiple images. Each pixel represents k measurements, each of datatype TPixel. The memory organization of the resulting image is as follows: … Pi0 Pi1 Pi2 Pi3 P(i+1)0 P(i+1)1 P(i+1)2 P(i+1)3 P(i+2)0 … where Pi0 represents the 0th measurement of the pixel at index i.

Conceptually, a VectorImage< TPixel, 3 > is the same as a Image< VariableLengthVector< TPixel >, 3 >. The difference lies in the memory organization. The latter results in a fragmented organization with each location in the Image holding a pointer to an VariableLengthVector holding the actual pixel. The former stores the k pixels instead of a pointer reference, which apart from avoiding fragmentation of memory also avoids storing a 8 bytes of pointer reference for each pixel. The parameter k can be set using SetVectorLength.

The API of the class is such that it returns a pixeltype VariableLengthVector< TPixel > when queried, with the data internally pointing to the buffer. (the container does not manage the memory). Similarly SetPixel calls can be made with VariableLengthVector< TPixel >.

The API of this class is similar to Image.

Caveats:

When using Iterators on this image, you cannot use the it.Value(). You must use Set/Get() methods instead.

Note

This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149.

See

DefaultVectorPixelAccessor

See

DefaultVectorPixelAccessorFunctor

See

VectorImageToImagePixelAccessor

See

VectorImageToImageAdaptor

See

Image

See

ImportImageContainer

ITK Sphinx Examples:

See itk::VectorImage for additional documentation.
template<typename TImage, typename TBoundaryCondition = ZeroFluxNeumannBoundaryCondition<TImage>>
class NeighborhoodIterator : public itk::ConstNeighborhoodIterator<TImage, TBoundaryCondition>

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.

itk::NeighborhoodInnerProduct<ImageType> innerProduct;

itk::DerivativeOperator<ImageType> operator;
 operator->SetOrder(1);
 operator->SetDirection(0);
 operator->CreateDirectional();

itk::NeighborhoodIterator<ImageType>
  iterator(operator->GetRadius(), myImage, myImage->GetRequestedRegion());

iterator.SetToBegin();
while ( ! iterator.IsAtEnd() )
{
  std::cout << "Derivative at index " << iterator.GetIndex() << is <<
    innerProduct(iterator, operator) << std::endl;
  ++iterator;
}

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.

The API for creating and manipulating a NeighborhoodIterator mimics that of the itk::ImageIterators. Like the itk::ImageIterator, a ConstNeighborhoodIterator is defined on a region of interest in an itk::Image. Iteration is constrained within that region of interest.

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 pixel neighborhood 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.

SizeValueType c = (SizeValueType) (iterator.Size() / 2); // get offset of center pixel
SizeValueType s = iterator.GetStride(1);            // y-dimension step size

std::cout << iterator.GetPixel(7)      << std::endl;
std::cout << iterator.GetCenterPixel() << std::endl;
std::cout << iterator.GetPixel(c)      << std::endl;
std::cout << iterator.GetPixel(c-1)    << std::endl;
std::cout << iterator.GetPixel(c-s)    << std::endl;
std::cout << iterator.GetPixel(c-s-1)  << std::endl;
std::cout << *iterator[c]              << std::endl;

Results:

0.7
0.7
0.7
1.1
1.8
1.3
0.7

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 indices, 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.

See

DerivativeOperator

See

NeighborhoodInnerProduct

MORE INFORMATION

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 https://www.itk.org.

See

ImageConstIterator

See

ConditionalConstIterator

See

ConstNeighborhoodIterator

See

ConstShapedNeighborhoodIterator

See

ConstSliceIterator

See

CorrespondenceDataStructureIterator

See

FloodFilledFunctionConditionalConstIterator

See

FloodFilledImageFunctionConditionalConstIterator

See

FloodFilledImageFunctionConditionalIterator

See

FloodFilledSpatialFunctionConditionalConstIterator

See

FloodFilledSpatialFunctionConditionalIterator

See

ImageConstIterator

See

ImageConstIteratorWithIndex

See

ImageIterator

See

ImageIteratorWithIndex

See

ImageLinearConstIteratorWithIndex

See

ImageLinearIteratorWithIndex

See

ImageRandomConstIteratorWithIndex

See

ImageRandomIteratorWithIndex

See

ImageRegionConstIterator

See

ImageRegionConstIteratorWithIndex

See

ImageRegionExclusionConstIteratorWithIndex

See

ImageRegionExclusionIteratorWithIndex

See

ImageRegionIterator

See

ImageRegionIteratorWithIndex

See

ImageRegionReverseConstIterator

See

ImageRegionReverseIterator

See

ImageReverseConstIterator

See

ImageReverseIterator

See

ImageSliceConstIteratorWithIndex

See

ImageSliceIteratorWithIndex

See

NeighborhoodIterator

See

PathConstIterator

See

PathIterator

See

ShapedNeighborhoodIterator

See

SliceIterator

See

ImageConstIteratorWithIndex

See

ShapedImageNeighborhoodRange

ITK Sphinx Examples:

Subclassed by itk::ConstShapedNeighborhoodIterator< TImage, TBoundaryCondition >

See itk::NeighborhoodIterator for additional documentation.