dip::PixelTable class

Constructors, destructors, assignment and conversion operators

PixelTable() defaulted
A default-constructed pixel table is kinda useless
PixelTable(dip::String const& shape, dip::FloatArray size, dip::uint procDim = 0)
Construct a pixel table for default filter shapes.
PixelTable(dip::Image const& mask, dip::IntegerArray const& origin = {}, dip::uint procDim = 0)
Construct a pixel table for an arbitrary shape defined by a binary image.

Classes

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.

Functions

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.
auto Boundary() const -> dip::UnsignedArray
Returns the size of the boundary extension along each dimension that is necessary to accommodate the neighborhood on the edge pixels of the image
void ShiftOrigin(dip::IntegerArray const& shift)
Shifts the origin of the neighborhood by the given amount
void MirrorOrigin()
Shifts the origin of neighborhood by one pixel to the left for even-sized dimensions. This is useful for neighborhoods with their origin in the default location, that have been mirrored.
void Mirror()
Mirrors 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 begin() const -> dip::PixelTable::iterator
A const iterator to the first pixel in the neighborhood
auto end() const -> dip::PixelTable::iterator
A const iterator to one past the last pixel in the neighborhood
auto AsImage() const -> dip::Image
Creates a binary image representing the neighborhood, or a dfloat one if there are weights associated.
void AsImage(dip::Image& out) const
Same as previous overload, but writing into the given image.
auto Prepare(dip::Image const& image) const -> dip::PixelTableOffsets
Prepare the pixel table to be applied to a specific image.
void AddWeights(dip::Image const& image)
Add weights to each pixel in the neighborhood, taken from an image. The image must be of the same sizes as the PixelTable‘s bounding box (i.e. the image used to construct the pixel table), and of a real type (i.e. integer or float).
void AddDistanceToOriginAsWeights()
Add weights to each pixel in the neighborhood, using the Euclidean distance to the origin as the weight. This is useful for algorithms that need to, for example, sort the pixels in the neighborhood by distance to the origin.
auto HasWeights() const -> bool
Tests if there are weights associated to each pixel in the neighborhood.
auto Weights() const -> std::vector<dfloat> const&
Returns a const reference to the weights array.

Class documentation

struct PixelRun

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

Variables
dip::IntegerArray coordinates The coordinates of the first pixel in a run, w.r.t. the origin.
dip::uint length The length of the run, expected to always be larger than 0.

Function documentation

PixelTable(dip::String const& shape, dip::FloatArray size, dip::uint procDim = 0)

Construct a pixel table for default filter shapes.

The known default shapes are "rectangular", "elliptic", and "diamond", which correspond to a unit circle in the L, L2 and L1 norms; and "line", which is a single-pixel thick line.

The size array determines the size and dimensionality. For unit circles, it gives the diameter of the neighborhood (not the radius!); the neighborhood contains all pixels at a distance equal or smaller than half the diameter from the origin. This means that non-integer sizes can be meaningful. The exception is for the "rectangular" shape, where the sizes are rounded down to the nearest integer, yielding rectangle sides that are either even or odd in length. For even sizes, one can imagine that the origin is shifted by half a pixel to accommodate the requested size (though the origin is set to the pixel that is right of the center). For the "diamond" and "elliptic" shapes, the bounding box always has odd sizes, and the origin is always centered on one pixel. To accomplish the same for the “rectangular” shape, simply round the sizes array to an odd integer:

size[ ii ] = std::floor( size[ ii ] / 2 ) * 2 + 1

For the line, the size array gives the size of the bounding box (rounded to the nearest integer), as well as the direction of the line. A negative value for one dimension means that the line runs from high to low along that dimension. The line will always run from one corner of the bounding box to the opposite corner, and run through the origin.

procDim indicates the processing dimension.

PixelTable(dip::Image const& mask, dip::IntegerArray const& origin = {}, dip::uint procDim = 0)

Construct a pixel table for an arbitrary shape defined by a binary image.

Set pixels in mask indicate pixels that belong to the neighborhood.

origin gives the coordinates of the pixel in the image that will be placed at the origin (i.e. have coordinates {0,0,0}. If origin is an empty array, the origin is set to the middle pixel, as given by mask.Sizes() / 2. That is, for odd-sized dimensions, the origin is the exact middle pixel, and for even-sized dimensions the origin is the pixel to the right of the exact middle.

procDim indicates the processing dimension.

dip::PixelTableOffsets Prepare(dip::Image const& image) const

Prepare the pixel table to be applied to a specific image.

The resulting object is identical to this, but has knowledge of the image’s strides and thus directly gives offsets rather than coordinates to the neighbors.