Represents the shape and size of a filtering kernel.
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.
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 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 grey-value image, then all pixels with a finite value form the kernel. The kernel then has the given weights associated to each pixel.
See dip::StructuringElement, dip::NeighborList, dip::PixelTable
Constructors, destructors, assignment and conversion operators
- 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)
dip::FloatArrayimplicitly 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.
- 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
- auto PixelTable(dip::uint nDims, dip::uint procDim) const -> dip::PixelTable
- Creates a
dip::PixelTablestructure representing the shape of the kernel, given the dimensionality
nDim. Pixel table runs will be along dimension
- 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
- 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
- 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 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::PixelTablefor the kernel, so is not a trivial function.
enum class ShapeCode: int
Possible shapes of a kernel
|RECTANGULAR = 0||
A rectangular kernel, the user will use the string
|ELLIPTIC = 1||
An elliptical (or circular) kernel, corresponding to the string
|DIAMOND = 2||
A diamond-shaped kernel, corresponding to the string
|LINE = 3||
A thin straight line, corresponding to the string
|LEFT_LINE = 4||
The same as
|CUSTOM = 5||The kernel shape and weights are given by an image.|
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
Mirror is called before or after calling
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.