# PixelTable class

### Contents

## 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

## 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 `shape`

s are `"rectangular"`

, `"elliptic"`

, and `"diamond"`

,
which correspond to a unit circle in the L^{∞}, L^{2} and L^{1} 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.