The library infrastructure module
#include "diplib/kernel.h"
dip::Kernel class

Represents the shape and size of a filtering kernel.

Contents

Some image filters allow the specification of arbitrary kernels: the user can specify the shape name and the size of a pre-defined kernel, or the user can pass an image containing the kernel.

Objects of type dip::Image, dip::FloatArray and dip::String implicitly convert to a dip::Kernel, so it should be convenient to use these various representations in your code.

To define a kernel by shape and size, pass a string defining the shape, and a floating-point array with the size along each dimension. These are the valid shape strings:

  • "elliptic": The unit circle in Euclidean (L2) metric.
  • "rectangular": A box, the unit circle in L1 metric.
  • "diamond": A box rotated 45 degrees, the unit circle in L∞ metric (max-norm).
  • "line": A one-pixel thick straight line.

In the first three of these cases, the size array indicates the diameter of the circle. The value can be different along each dimension, simply stretching the shape. Note that the sizes are not necessarily odd, and don’t even need to be integers. Pixels included in the neighborhood are those covered by the circle, with the origin on a pixel. In the case of the rectangle, however, the box is shifted by half a pixel if floor(size) is even. This means that the rectangular kernel is not necessarily symmetric. Set the size to odd values to ensure symmetry. Any size that is smaller or equal to 1 causes the kernel to not have an extent along that dimension.

For the case of the "line" kernel, 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.

To define a kernel through an image, provide a scalar binary image. The “on” or “true” pixels form the kernel. Note that, for most filters, the image is directly used as neighborhood (i.e. no mirroring is applied). As elsewhere, the origin of the kernel is in the middle of the image, and on the pixel to the right of the center in case of an even-sized image. If the image is a scalar grey-value image, then all pixels with a finite value form the kernel. The kernel then has the given weights associated to each pixel. After calling dip::Kernel::IgnoreZeros, all pixels with a finite, non-zero value form the kernel.

See dip::StructuringElement, dip::NeighborList, dip::PixelTable

Constructors, destructors, assignment and conversion operators

Kernel()
The default kernel is a disk with a diameter of 7 pixels.
Kernel(dip::String const& shape)
A string implicitly converts to a kernel, it is interpreted as a shape.
Kernel(dip::FloatArray params, dip::String const& shape = S::ELLIPTIC)
A dip::FloatArray implicitly converts to a kernel, it is interpreted as the parameter for each dimension. A second argument specifies the shape.
Kernel(dip::dfloat param, dip::String const& shape = S::ELLIPTIC)
A floating-point value implicitly converts to a kernel, it is interpreted as the parameter for all dimensions. A second argument specifies the shape.
Kernel(dip::Kernel::ShapeCode shape, dip::FloatArray params)
Low-level constructor mostly for internal use.
Kernel(dip::Image image)
An image implicitly converts to a kernel, optionally with weights.

Enums

enum class ShapeCode: uint8{ RECTANGULAR, ELLIPTIC, DIAMOND, LINE, LEFT_LINE, CUSTOM }
Possible shapes of a kernel

Functions

void Shift(dip::IntegerArray shift)
Shifts the kernel by the given amount along each of the axes.
auto Shift() const -> dip::IntegerArray const&
Retrieves the amount that the is shifted.
void Mirror()
Mirrors the kernel. This has no effect on elliptic or diamond kernels, which are always symmetric.
auto IsMirrored() const -> bool
True if kernel is mirrored
void IgnoreZeros()
Causes zeros in the kernel image to be ignored when creating a dip::PixelTable.
auto PixelTable(dip::uint nDims, dip::uint procDim) const -> dip::PixelTable
Creates a dip::PixelTable structure representing the shape of the kernel, given the dimensionality nDim. Pixel table runs will be along dimension procDim.
auto Sizes(dip::uint nDims) const -> dip::UnsignedArray
Retrieves the size of the kernel, adjusted to an image of size imsz. When computing required boundary extension, use Boundary instead.
auto Boundary(dip::uint nDims) const -> dip::UnsignedArray
Returns the size of the boundary extension along each dimension that is necessary to accommodate the kernel on the edge pixels of the image, given an image of size imsz.
auto Params() const -> dip::FloatArray const&
Returns the kernel parameters, not adjusted to image dimensionality.
auto Shape() const -> dip::Kernel::ShapeCode const&
Returns the kernel shape
auto ShapeString() const -> dip::String
Returns the kernel shape
auto IsRectangular() const -> bool
Tests to see if the kernel is rectangular
auto IsLine() const -> bool
Tests to see if the kernel is a line
auto IsCustom() const -> bool
Tests to see if the kernel is a custom shape
auto HasWeights() const -> bool
Tests to see if the kernel has weights
auto HasComplexWeights() const -> bool
Tests to see if the kernel has complex weights
auto NumberOfPixels(dip::uint nDims) const -> dip::uint
Returns the number of pixels in the kernel, given the image dimensionality nDims. This requires the creation of a dip::PixelTable for the kernel, so is not a trivial function.

Enum documentation

enum class ShapeCode: uint8

Possible shapes of a kernel

Enumerators
RECTANGULAR = 0 A rectangular kernel, the user will use the string "rectangular".
ELLIPTIC = 1 An elliptical (or circular) kernel, corresponding to the string "elliptic".
DIAMOND = 2 A diamond-shaped kernel, corresponding to the string "diamond".
LINE = 3 A thin straight line, corresponding to the string "line".
LEFT_LINE = 4 The same as dip::Kernel::ShapeCode::LINE, but the origin is placed at the leftmost end of the line.
CUSTOM = 5 The kernel shape and weights are given by an image.

Function documentation

void Shift(dip::IntegerArray shift)

Shifts the kernel by the given amount along each of the axes.

Note that the shift is only used when converting the kernel to a pixel table. Some algorithms will ignore the shift for some kernel shapes.

The shift if not cumulative, any previous shift is ignored. Any mirroring is applied after the shift, whether Mirror is called before or after calling Shift.

Big shifts can be very expensive, it is recommended to use this feature only for shifting by one pixel to adjust the location of even-sized kernels.