dip::PixelTableOffsets class

Represents an arbitrarily-shaped neighborhood (filter support) in an arbitrary number of dimensions.

A PixelTableOffsets object is created from a dip::PixelTable through its dip::PixelTable::Prepare method. The object is identical to its parent, but instead of coordinates it contains offsets. It is ready to be applied to a specific image. It can only be used on other images that have the exact same strides as the image it was prepared for.

Offsets cannot be used to test for the neighbor to be within the image domain, so this object is meant to be used with images in which the boundary has been extended through dip::ExtendImage, or where the pixels being processed are away from the image edges.

Its iterator dereferences to an offset rather than coordinates. But note that the iterator is not as efficient as a manual double-loop over runs and pixels within each run. Even more efficient is to first extract an array with offsets using the Offsets method. The difference between these methods is only relevant when iterating over the pixel table for each pixel in an image, as the small difference accumulates.

PixelTableOffsets pt = ...;

for( auto offset: pt ) { ... }          // easiest, least efficient

for( auto const& run : pt.Runs() ) {
   dip::sint offset = run.offset;
   for( dip::uint ii = 0; ii < run.length; ++ii, offset += pt.Stride() ) {
}                                       // more efficient

auto offsets = pt.Offsets();
for( auto offset: offsets ) { ... }     // most efficient (when iterating many times)

Constructors, destructors, assignment and conversion operators

PixelTableOffsets() defaulted
A default-constructed pixel table is kinda useless.
PixelTableOffsets(dip::PixelTable const& pt, dip::Image const& image)
A pixel table with offsets is constructed from a dip::PixelTable and a dip::Image.


struct PixelRun
The pixel table is formed of pixel runs, represented by this structure.
class iterator
An iterator that visits each of the neighborhood’s pixels in turn.


auto Runs() const -> std::vector<PixelRun> const&
Returns the vector of runs.
auto Dimensionality() const -> dip::uint
Returns the dimensionality of the neighborhood.
auto Sizes() const -> dip::UnsignedArray const&
Returns the size of the bounding box of the neighborhood.
auto Origin() const -> dip::IntegerArray const&
Returns the coordinates of the top-left corner of the bounding box w.r.t. the origin of the neighborhood.
auto NumberOfPixels() const -> dip::uint
Returns the number of pixels in the neighborhood.
auto ProcessingDimension() const -> dip::uint
Returns the processing dimension, the dimension along which pixel runs are laid out.
auto Stride() const -> dip::sint
Returns the stride along the processing dimension used by the iterator.
auto begin() const -> dip::PixelTableOffsets::iterator
A const iterator to the first pixel in the neighborhood.
auto end() const -> dip::PixelTableOffsets::iterator
A const iterator to one past the last pixel in the neighborhood.
auto HasWeights() const -> bool
Tests if there are weights associated to each pixel in the neighborhood.
auto WeightsAreComplex() const -> bool
Tests if the weights associated to each pixel, if any, are complex-valued.
auto Weights() const -> std::vector<dfloat> const&
Returns a const reference to the weights array.
auto Offsets() const -> std::vector<dip::sint>
Computes an array with the offsets.

Class documentation

struct PixelRun

The pixel table is formed of pixel runs, represented by this structure.

dip::sint offset the offset of the first pixel in a run, w.r.t. the origin.
dip::uint length the length of the run.

Function documentation

std::vector<dfloat> const& Weights() const

Returns a const reference to the weights array.

If dip::PixelTableOffsets::HasWeights, then the array returned is not empty. If dip::PixelTableOffsets::WeightsAreComplex is false, there will be dip::PixelTableOffsets::NumberOfPixels weights, one for each pixel in the neighborhood, stored in the same order as the dip::PixelTableOffsets::Offsets array.

If dip::PixelTableOffsets::WeightsAreComplex is true, there will be two times dip::PixelTableOffsets::NumberOfPixels weights. Each pair of weights represents one complex value. The pointer to the weights array data can be cast to dip::dcomplex.