template<typename T = dip::dfloat>
dip::GenericImageIterator class

A data-type–agnostic version of dip::ImageIterator. Use this iterator only to write code that does not know at compile-time what the data type of the image is.

This iterator works similarly to dip::ImageIterator. The Pointer method returns a void pointer to the first sample in the pixel. This is the more efficient way of using the iterator.

Dereferencing the iterator returns a dip::Image::Pixel object (actually a dip::Image::CastPixel), and the [] operator return a dip::Image::Sample object (actually a dip::Image::CastSample). These objects reference the pixel or sample, assigning to them changes the pixel’s values in the image. They are convenient in use, but not very efficient. The optional template argument to GenericImageIterator sets the template argument to the dip::Image::CastPixel object that is actually returned by dereferencing the iterator. Choose a type in which you wish to work, but know that this choice will not affect the results of reading from and assigning to the dereferenced iterator. The only difference is the type to which the dereferenced iterator can implicitly be cast to.

Example usage from dip::CopyTo:

auto arrIt = offsets.begin();
GenericImageIterator<> srcIt( src );
do {
   Image::Pixel d( dest.Pointer( *arrIt ), dest.DataType(), dest.Tensor(), dest.TensorStride() );
   d = *srcIt;
} while( ++arrIt, ++srcIt ); // these two must end at the same time, we test the image iterator,
                             // as arrIt should be compared with the end iterator.

Note that when an image is stripped or reforged, all its iterators are invalidated.

Constructors, destructors, assignment and conversion operators

Default constructor yields an invalid iterator that cannot be dereferenced, and is equivalent to an end iterator
GenericImageIterator(dip::Image const& image, dip::uint procDim = std::numeric_limits::max()) explicit
To construct a useful iterator, provide an image and optionally a processing dimension


using iterator_category = std::forward_iterator_tag
Iterator category
using value_type = dip::Image::CastPixel
The type of the pixel, obtained when dereferencing the iterator
using reference = dip::GenericImageIterator::value_type
The type of a reference to a pixel (note dip::Image::CastPixel references a value in the image)
using pointer = dip::GenericImageIterator::value_type*
The type of a pointer to a pixel


template<typename S>
void swap(dip::GenericImageIterator& other)
auto begin() const -> typename value_type::Iterator
Get an iterator over the tensor for the current pixel, it.begin() is equal to (*it).begin().
auto end() const -> typename value_type::Iterator
Get an end iterator over the tensor for the current pixel
template<typename S = T>
auto GetLineIterator() const -> dip::LineIterator
Get an iterator over the current line
template<typename S = T>
auto GetConstLineIterator() const -> dip::ConstLineIterator
Get a const iterator over the current line
auto IsAtEnd() const -> bool
Test to see if the iterator reached past the last pixel
auto Coordinates() const -> dip::UnsignedArray const&
Return the current coordinates
auto SetCoordinates(dip::UnsignedArray coords) -> dip::GenericImageIterator&
Set the iterator to point at a different location in the image
auto Sizes() const -> dip::UnsignedArray const&
Return the sizes of the image we’re iterating over.
auto ProcessingDimensionSize() const -> dip::uint
Return the size along the processing dimension
auto Strides() const -> dip::IntegerArray const&
Return the strides used to iterate over the image.
auto ProcessingDimensionStride() const -> dip::sint
Return the stride along the processing dimension
auto IsOnEdge() const -> bool
Return true if the iterator points at a pixel on the edge of the image.
auto Pointer() const -> void*
Return the current pointer
auto Pointer(dip::uint index) const -> void*
Return a pointer to the tensor element index
auto Offset() const -> dip::sint
Return the current offset
auto Index() const -> dip::uint
Return the current index, which is computed: this function is not trivial
auto HasProcessingDimension() const -> bool
True if the processing dimension is set
auto ProcessingDimension() const -> dip::uint
Return the processing dimension, the direction of the lines over which the iterator iterates
auto Reset() -> dip::GenericImageIterator&
Reset the iterator to the first pixel in the image (as it was when first created)
auto Optimize() -> dip::GenericImageIterator&
Optimizes the order in which the iterator visits the image pixels.
auto OptimizeAndFlatten() -> dip::GenericImageIterator&
Like Optimize, but additionally folds dimensions together where possible (flattens the image, so that the iterator has fewer dimensions to work with). The processing dimension is not affected.


auto operator*() const -> dip::GenericImageIterator::value_type
auto operator[](dip::uint index) const -> dip::Image::CastSample
Index into tensor, it[index] is equal to (*it)[index].
auto operator++() -> dip::GenericImageIterator&
auto operator++(int ) -> dip::GenericImageIterator
template<typename S>
auto operator==(dip::GenericImageIterator const& other) const -> bool
Equality comparison, is equal if the two iterators have the same coordinates. It is possible to compare GenericImageIterator with different images.
template<typename S>
auto operator!=(dip::GenericImageIterator const& other) const -> bool
Inequality comparison
auto operator bool() const -> bool explicit
Test to see if the iterator is still pointing at a pixel

Function documentation

template<typename T>
bool IsOnEdge() const

Return true if the iterator points at a pixel on the edge of the image.

If there is a processing dimension, then the iterator always points at an edge pixel; in this case only returns true if all pixels on the line are edge pixels (i.e. the first and last pixel of the line are not counted).

template<typename T>
dip::GenericImageIterator& Optimize()

Optimizes the order in which the iterator visits the image pixels.

The iterator internally reorders and flips image dimensions to change the linear index to match the storage order (see dip::Image::StandardizeStrides). If the image’s strides were not normal, this will significantly increase the speed of reading or writing to the image. Expanded singleton dimensions are eliminated, meaning that each pixel is always only accessed once. Additionally, singleton dimensions are ignored.

After calling this function, Coordinates and Index no longer match the input image. Do not use this method if the order of accessing pixels is relevant, or if Coordinates are needed.

Note that the processing dimension stride could change sign. Use ProcessingDimensionStride. If the processing dimension was a singleton dimension, or singleton-expanded, the iterator will no longer have a singleton dimension. In this case, HasProcessingDimension will return false.

The iterator is reset to the first pixel.