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.

Reference

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

GenericImageIterator(): 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

Aliases

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

Functions

template<typename S> void swap(dip::GenericImageIterator& other): Swap
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.

Operators

auto operator*() const -> dip::GenericImageIterator::value_type: Dereference
auto operator[](dip::uint index) const -> dip::Image::CastSample: Index into tensor, it[index] is equal to (*it)[index].
auto operator++() -> dip::GenericImageIterator&: Pre-increment
auto operator++(int ) -> dip::GenericImageIterator: Post-increment
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.

Iterators module#include "diplib/generic_iterators.h" template<typename T = dip::dfloat> dip::GenericImageIterator class

Contents