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 predefined 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 floatingpoint array with the size along each dimension. These are the valid shape strings:
"elliptic"
: The unit circle in Euclidean (L^{2}) metric."rectangular"
: A box, the unit circle in L^{1} metric."diamond"
: A box rotated 45 degrees, the unit circle in L^{∞} metric (maxnorm)."line"
: A onepixel 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 evensized image. If the image
is a scalar greyvalue 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, nonzero 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 floatingpoint 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)
 Lowlevel constructor mostly for internal use.
 Kernel(dip::Image image)
 An image implicitly converts to a kernel, optionally with weights.
Enums
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 dimensionalitynDim
. Pixel table runs will be along dimensionprocDim
.  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, useBoundary
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 adip::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 diamondshaped 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 evensized kernels.