(Return to Images)

Image Pixels may be accessed via iterators or locators; the former are simpler if you want single-pixel access, while the latter provide you with access to a pixel's friends and neighbours. There are a set of tutorials:

In the case of MaskedImage, the user-visible iterators and locators (and const variants) are derived from MaskedImageIteratorBase and MaskedImageLocatorBase; the following documentation refers to these base classes.

Iterators

You can use an STL-compliant iterator to access the pixels:
- ImageBase::begin() const
- ImageBase::begin(bool) const
- MaskedImage::begin() const
- MaskedImage::begin(bool) const
- ImageBase::end() const
- ImageBase::end(bool) const
- MaskedImage::end() const
- MaskedImage::end(bool) const
- ImageBase::rbegin() const
- MaskedImage::rbegin() const
- ImageBase::rend() const
- MaskedImage::rend() const
- ImageBase::at(int x, int y) const
- MaskedImage::at(int x, int y) const

N.b. These iterators aren't the most efficient way to access all the image's pixels as they may not be contiguous in memory so a test for end-of-row is needed after every pixel (we do guarantee that a row's pixels will be contiguous). The exceptions are the begin(bool) and end(bool) pairs which are only valid for contiguous images (they'll throw an exception if the image isn't), but are the fastest way to traverse an image if available. Note that they return an x_iterator not an iterator.

Incrementing an y_iterator moves it across the row
Incrementing an y_iterator moves it up the column
Iterators can be dereferenced:
- imageIterator::operator*()
- MaskedImage::MaskedImageIteratorBase::operator*()
Additionally, MaskedImage iterators support
Iterators may be advanced with
and compared with
- imageIterator::operator==(imageIterator const& rhs)
- MaskedImage::MaskedImageIteratorBase::operator==(MaskedImageIteratorBase const& rhs)
- imageIterator::operator!=(imageIterator const& rhs)
- MaskedImage::MaskedImageIteratorBase::operator!=(MaskedImageIteratorBase const& rhs)
- imageIterator::operator<(imageIterator const& rhs)
- MaskedImage::MaskedImageIteratorBase::operator<(MaskedImageIteratorBase const& rhs)

Locators

Locators are more flexible than iterators, permitting us to manipulate regions of an image

locators may be created with
- ImageBase::xy_at(int x, int y) const
- MaskedImage::xy_at(int x, int y) const
and dereferenced with:
Retrieve an x- or y-iterator that may be dereferenced or incremented
Manipulate those iterators (n.b. this moves the underlying locator, so ++locator.x() is the standard way to advance a locator)
- imageLocator::xy_x_iterator::operator*()
- MaskedImage::MaskedImageLocatorBase::xy_x_iterator::operator*()
- imageLocator::xy_y_iterator::operator*()
- MaskedImage::MaskedImageLocatorBase::xy_y_iterator::operator*()
Additionally, MaskedImage locator-iterators support
Move those iterators (n.b. this moves the underlying locator, so ++locator.x() is the standard way to advance a locator)
Advance (or retreat) an xy_locator directly
- ImageBase::operator+=(xy_locator& loc, pair2I const& off)
- MaskedImage::MaskedImageLocatorBase::operator+=(pair2I const& off)
- ImageBase::operator+=(const_xy_locator& loc, pair2I const& off)
- ImageBase::operator-=(xy_locator& loc, pair2I const& off)
- ImageBase::operator-=(const_xy_locator& loc, pair2I const& off)
Save or use a saved relative location
- imageLocator::cache_location()
- MaskedImage::MaskedImageLocatorBase::cache_location()
- imageLocator::cache_location(int x, int y)
- MaskedImage::MaskedImageLocatorBase::cache_location(int x, int y) const
- imageLocator::operator[](cached_location_t const&);
- MaskedImage::MaskedImageLocatorBase::operator[](cached_location_t const&);
MaskedImage locators also support
- MaskedImage::MaskedImageLocatorBase::image(cached_location_t const&);
- MaskedImage::MaskedImageLocatorBase::mask(cached_location_t const&);
- MaskedImage::MaskedImageLocatorBase::variance(cached_location_t const&);

(Note that these are function calls, as opposed to the operator[] in the previous APIs)