5.2. Basic Filters#

Summary:

ITO developed filter-functions for data objects

Type:

Algorithm

License:

Licensed under LGPL.

Platforms:

Windows, Linux

Author:

W. Lyda, T. Boettcher, Universität Stuttgart

5.2.1. Overview#

This plugin provides several basic filter calculations for itom::dataObject. These are for instance:

  • merging of planes

  • swap byte order of objects

  • resample slices from dataObjects

  • mean value filter along axis

This plugin does not have any unusual dependencies.

These filters are defined in the plugin:

  1. calcHist()

  2. calcMeanZ()

  3. calcObjSlice()

  4. calcRadialMean()

  5. clipAbyB()

  6. clipValues()

  7. fillObject()

  8. findEllipses()

  9. flatten3Dto2D()

  10. gaussianFilter()

  11. gaussianFilterEpsilon()

  12. highValueFilter()

  13. labeling()

  14. lowPassFilter()

  15. lowValueFilter()

  16. medianFilter()

  17. mergeColorPlane()

  18. replaceInfAndNaN()

  19. sobelOpt()

  20. spikeMeanFilter()

  21. spikeMedianFilter()

  22. swapByteOrder()

5.2.2. Filters#

Detailed overview about all defined filters:

itom.algorithms.calcHist(sourceImage, destinationImage[, bins, autoInterval, interval])#

calculates histogram of real input data object.

Parameters:

  • sourceImage (itom.dataObject) – 2D or multidimensional source data object ((u)int8, (u)int16, (u)int32, float32, float64 or rgba32)

  • destinationImage (itom.dataObject) – histogram data object (will be int32, [higher-dimensions x 1 x bins] where higher-dimensions corresponds to the dimensions higher than x and y of the source object. A source object of type rgba32 will lead to [higher-dimensions x 4 x bins] where the 4-sized dimension is the histogram if the [r,g,b,gray] value channels. If the given object already fits to the type and size requirements, it is used without allocating a new object.

  • bins (int, optional) –

    Number of bins ((u)int16, (u)int32, float32 and float64 only, default: 0 leads to 1024 bins), for (u)int8 and rgba32 the number of bins is given by the total number of values represented by the data type.

    Value range: [0, 4096], Default: 0

  • autoInterval (int, optional) –

    Defines how to determine the interval of the histogram: -1 (default) use the limits of (u)int8 and rgba32 and auto-calculate the min/max values for floating point data types, 0: use the values given by interval, 1: automatically calculate the min/max values for all data types.

    Value range: [-1, 1], Default: -1

  • interval (Tuple[float,float] (interval [v1,v2]), optional) –

    Interval of the histogram (depending on parameter ‘autoInterval’). The first value is included in the first bin, the last value is included in the last bin.

    , All values allowed, Default: [-inf, inf]

itom.algorithms.calcMeanZ(srcImg, destImg[, ignoreInf, calcStd])#

Calculate mean value (and optional standard deviation) of a 3D data object in z-direction.

Parameters:

  • srcImg (itom.dataObject) – 3D input object of dimension [ZxMxN] with Z different planes.

  • destImg (itom.dataObject) – Output image of same type than input object and dimension [1xMxN] or [2xMxN] depending on parameter ‘calcStd’.

  • ignoreInf (int, optional) –

    If 1, Inf or NaN values will not be taken into account when calculating the mean value (default, only important for floating point data types).

    Value range: [0, 1], Default: 1

  • calcStd (int, optional) –

    If 1, the standard deviation is also calculated and put into the second plane of ‘destImg’.

    Value range: [0, 1], Default: 1

itom.algorithms.calcObjSlice(srcImg, dstSlice, x0, y0, x1, y1[, interpolationMode])#

Interpolate 1D-slice from along the defined line from a 2D-Object.

Parameters:

  • srcImg (itom.dataObject) – 2D image or single plane n-D object

  • dstSlice (itom.dataObject) – Slice with output data

  • x0 (float) –

    x0-coordinate for slice

    Value range: [-3.40282e+38, 3.40282e+38], Default: 0

  • y0 (float) –

    y0-coordinate for slice

    Value range: [-3.40282e+38, 3.40282e+38], Default: 1

  • x1 (float) –

    x1-coordinate for slice

    Value range: [-3.40282e+38, 3.40282e+38], Default: 0

  • y1 (float) –

    y1-coordinate for slice

    Value range: [-3.40282e+38, 3.40282e+38], Default: 1

  • interpolationMode (int, optional) –

    0: Bresenham or Nearest Neighbour, 1: weighted (not implemented, yet).

    Value range: [0, 0], Default: 0

itom.algorithms.calcRadialMean(scrImage, destImage, radiusStep[, centerX, centerY])#

Calculates the mean value for radial circles with a given center point an a radius step size

The radiuses are the distances from the given center point to the physical coordinates of each pixel.

Parameters:

  • scrImage (itom.dataObject) – Input image

  • destImage (itom.dataObject) – Output image (1xN) of the same type than the input image, where N corresponds to different radiuses.

  • radiusStep (float) –

    step size of the radius for the discretization

    Value range: [1e-09, inf], Default: 0.01

  • centerX (float, optional) –

    x-coordinate of radial center

    All values allowed, Default: 0

  • centerY (float, optional) –

    y-coordinate of radial center

    All values allowed, Default: 0

itom.algorithms.clipAbyB(sourceImage, comparisonImage, destinationImage, minValue, maxValue[, newValue, insideFlag])#

clip values of image A to newValue (default = 0) outside or inside of minValue and maxValue in image B

Depending on the parameter ‘insideFlag’, this filter sets all values in image A depending on image B within (1) or outside (0) of the range (minValue, maxValue) to the value given by ‘newValue’. In both cases the range boundaries are not clipped and replaced. If clipping is executed outside of range, NaN and Inf values are replaced as well (floating point data objects only). This filter supports only real value data types.

Parameters:

  • sourceImage (itom.dataObject) – input image [real typed data object]

  • comparisonImage (itom.dataObject) – input image [real typed data object] for comparison

  • destinationImage (itom.dataObject) – destination image (inplace possible)

  • minValue (float) –

    lowest value in range

    All values allowed, Default: 0

  • maxValue (float) –

    highest value in range

    All values allowed, Default: 0

  • newValue (float, optional) –

    value set to clipped values (default: 0.0)

    All values allowed, Default: 0

  • insideFlag (int, optional) –

    0: clip values outside of given range (default), 1: clip inside

    Value range: [0, 1], Default: 0

itom.algorithms.clipValues(sourceImage, destinationImage, minValue, maxValue[, newValue, insideFlag])#

clip values outside or inside of minValue and maxValue to newValue (default = 0)

Depending on the parameter ‘insideFlag’, this filter sets all values within (1) or outside (0) of the range (minValue, maxValue) to the value given by ‘newValue’. In both cases the range boundaries are not clipped and replaced. If clipping is executed outside of range, NaN and Inf values are replaced as well (floating point data objects only). This filter supports only real value data types.

Parameters:

  • sourceImage (itom.dataObject) – input image [real typed data object]

  • destinationImage (itom.dataObject) – destination image (inplace possible)

  • minValue (float) –

    lowest value in range

    All values allowed, Default: 0

  • maxValue (float) –

    highest value in range

    All values allowed, Default: 0

  • newValue (float, optional) –

    value set to clipped values (default: 0.0)

    All values allowed, Default: 0

  • insideFlag (int, optional) –

    0: clip values outside of given range (default), 1: clip inside

    Value range: [0, 1], Default: 0

itom.algorithms.fillObject(destinationImage, geometricElement[, insideFlag, edgeFlag, newValueInside, newValueOutside])#

fills a ROI, which defined by a geometric primitive, of the given dataObject with a defined value

Depending on the parameter ‘insideFlag’, this filter sets all values of the dataObject depending on the geometric primitive within (1) or outside (2) or both (3) to the value given by ‘newValueInside’ and ‘newValueOutside’. The ‘edgeFlag’ is currently not used but shall manage the edge handling of primitive.

Parameters:

  • destinationImage (itom.dataObject) – Preallocated dataObject to be filled

  • geometricElement (itom.dataObject) – Geometric primitive according to definition

  • insideFlag (int, optional) –

    Switch between fill inside, outside or both

    Value range: [1, 3], Default: 1

  • edgeFlag (int, optional) –

    Edge-Flag, currently not used

    Value range: [0, 0], Default: 0

  • newValueInside (float, optional) –

    New value for pixels inside the geometric element

    All values allowed, Default: 1

  • newValueOutside (float, optional) –

    New value for pixels outside the geometric element

    All values allowed, Default: 0

itom.algorithms.findEllipses(image, labelList, centers, contourPts[, numBorderPix, thresBorder, minPixEllCenter])#

Filter for detecting the centers of ellipses with subpixel accuracy.

Parameters:

  • image (itom.dataObject) – image

  • labelList (itom.dataObject) – list of found labels

  • centers (itom.dataObject) – detected ellipses’ centers

  • contourPts (itom.dataObject) – ellipses’ contour points

  • numBorderPix (float, optional) –

    number of pixels for border detection

    Value range: [0, 1000], Default: 6

  • thresBorder (float, optional) –

    threshold for identifying a border after differentation

    Value range: [0, 100], Default: 0.04

  • minPixEllCenter (int, optional) –

    minimum number of pixels for ellipses center detection in x and y direction

    Value range: [0, 100], Default: 6

itom.algorithms.flatten3Dto2D(scrImage, destImage)#

Flattens a z-Stack of Mx1xN or MxNx1 matrixes to NxM or MxN.

Parameters:

  • scrImage (itom.dataObject) – Input image

  • destImage (itom.dataObject) – Output image

itom.algorithms.gaussianFilter(sourceImage, destImage[, kernelx, kernely, sigmaX, sigmaY, replaceNaN])#

2D gaussian blur filter that convolves the source image with a Gaussian kernel.

The convolution kernel is rectangular with a side length of (kernely, kernelx). The gaussian kernel for a pixel (x0,y0) is defined by:

f(x,y) = A * exp(-[(x-x0)^2/(2*sigma_x^2) + (y-y0)^2/(2*sigma_y^2)])

with

A = 1 / (2 * pi * sigmaX * sigmaY))

Invalid pixels within the kernel are excluded from the convolution. It is possible to fill the invalid values by the Gaussian blurred value of the surrounding kernel, too, if the parameter ‘replaceNaN’ is set to 1. If the kernel only contains invalid values, no replacement is possible and the corresponding pixel in the destination image remains invalid.

This filter can be applied inplace, hence, the source and destination image can be the same. This filter is implemented for all real data types. 3 or higher dimensional dataObjects are processed plane-by-plane, such that the destination image has always the same size and type than the input image

Parameters:

  • sourceImage (itom.dataObject) – N-dimensional dataObject of any real type. This object is processed plane-by-plane.

  • destImage (itom.dataObject) – Resulting dataObject that has the same size and type than the sourceImage.

  • kernelx (int, optional) –

    Size of kernel in x-direction (odd values only)

    Value range: [1, 101], Default: 3

  • kernely (int, optional) –

    Size of kernel in y-direction (odd values only)

    Value range: [1, 101], Default: 3

  • sigmaX (float, optional) –

    Standard deviation in x direction

    Value range: [0.1, 5000], Default: 0.84

  • sigmaY (float, optional) –

    Standard deviation in y direction

    Value range: [0.1, 5000], Default: 0.84

  • replaceNaN (int, optional) –

    If 1, NaN values of sourceImage will be replaced by interpolated filter values in destImage, else destImage also contains NaN values at these positions (0, default).

    Value range: [0, 1], Default: 0

itom.algorithms.gaussianFilterEpsilon(sourceImage, destImage, sigmaX, epsilonX, sigmaY, epsilonY[, replaceNaN])#

2D gaussian blur filter that convolves the source image with a Gaussian kernel.

The convolution kernel is rectangular with a side length that is determined by the epsilon values epsilonX and epsilonY. The gaussian kernel for a pixel (x0,y0) is defined by:

f(x,y) = A * exp(-[(x-x0)^2/(2*sigmaX^2) + (y-y0)^2/(2*sigmaY^2)])

with

A = 1 / (2 * pi * sigmaX * sigmaY))

The size of the kernel is adjusted such that the limit values in x- and y-direction fulfill the following inequation:

f(x,y=0) = exp(-[(x-x0)^2/(2*sigmaX^2)]) / sqrt(2 * pi * sigmaX^2) >= epsilonX f(x=0,y) = exp(-[(y-y0)^2/(2*sigmaY^2)]) / sqrt(2 * pi * sigmaY^2) >= epsilonY

Invalid pixels within the kernel are excluded from the convolution. It is possible to fill the invalid values by the Gaussian blurred value of the surrounding kernel, too, if the parameter ‘replaceNaN’ is set to 1. If the kernel only contains invalid values, no replacement is possible and the corresponding pixel in the destination image remains invalid.

This filter can be applied inplace, hence, the source and destination image can be the same. This filter is implemented for all real data types. 3 or higher dimensional dataObjects are processed plane-by-plane, such that the destination image has always the same size and type than the input image

Parameters:

  • sourceImage (itom.dataObject) – N-dimensional dataObject of any real type. This object is processed plane-by-plane.

  • destImage (itom.dataObject) – Resulting dataObject that has the same size and type than the sourceImage.

  • sigmaX (float) –

    Standard deviation in x direction

    Value range: [0.1, 5000], Default: 0.84

  • epsilonX (float) –

    Stop condition in x-direction, the kernel in x-direction is cropped for Gaussian values below this limit

    Value range: [1e-05, 1], Default: 0.001

  • sigmaY (float) –

    Standard deviation in y direction

    Value range: [0.1, 5000], Default: 0.84

  • epsilonY (float) –

    Stop condition in y-direction, the kernel in y-direction is cropped for Gaussian values below this limit

    Value range: [1e-05, 1], Default: 0.001

  • replaceNaN (int, optional) –

    If 1, NaN values of sourceImage will be replaced by interpolated filter values in destImage, else destImage also contains NaN values at these positions (0, default).

    Value range: [0, 1], Default: 0

itom.algorithms.highValueFilter(sourceImage, destImage, kernelx, kernely[, replaceNaN])#

2D maximum filter that set a pixel to the highest value within the surrounding kernel.

The rectangular kernel of size (kernely, kernelx) is centered at each pixel of the source image. The same pixel in the destination image is then set to the maximum value within the kernel. Invalid values within the kernel are ignored. It is possible to fill these invalid values by the maximum of the surrounding kernel, too, if the parameter ‘replaceNaN’ is set to 1.

This filter can be applied inplace, hence, the source and destination image can be the same. This filter is implemented for all real data types. 3 or higher dimensional dataObjects are processed plane-by-plane, such that the destination image has always the same size and type than the input image

See also: lowValueFilter

Parameters:

  • sourceImage (itom.dataObject) – N-dimensional dataObject of any real type. This object is processed plane-by-plane.

  • destImage (itom.dataObject) – Resulting dataObject that has the same size and type than the sourceImage.

  • kernelx (int) –

    Size of kernel in x-direction (odd values only)

    Value range: [1, 101], Default: 3

  • kernely (int) –

    Size of kernel in y-direction (odd values only)

    Value range: [1, 101], Default: 3

  • replaceNaN (int, optional) –

    If 1, NaN values of sourceImage will be replaced by interpolated filter values in destImage, else destImage also contains NaN values at these positions (0, default).

    Value range: [0, 1], Default: 0

itom.algorithms.labeling(image, threshold, labelList[, invalids])#
Finds connected areas in an image an assigns a label to them.

In the input image according found regions get painted with the according label. The returned list has the format x0,y0,x1,y1 for each label.

Parameters:

  • image (itom.dataObject) – image

  • threshold (float) –

    threshold for labeling

    Value range: [0, 65535], Default: 50

  • labelList (itom.dataObject) – list of found labels

  • invalids (float, optional) –

    invalid pixels

    Value range: [0, 65535], Default: 0

itom.algorithms.lowPassFilter(sourceImage, destImage, kernelx, kernely[, replaceNaN])#

2D lowpass (blurring) filter that set a pixel to the mean value of all valid pixels within the kernel.

The rectangular kernel of size (kernely, kernelx) is centered at each pixel of the source image. The same pixel in the destination image is then set to the mean value of all valid pixels within the kernel. It is possible to fill the invalid values by the mean value of the surrounding kernel, too, if the parameter ‘replaceNaN’ is set to 1. If the kernel only contains invalid values, no replacement is possible and the corresponding pixel in the destination image remains invalid.

This filter can be applied inplace, hence, the source and destination image can be the same. This filter is implemented for all real data types. 3 or higher dimensional dataObjects are processed plane-by-plane, such that the destination image has always the same size and type than the input image

Parameters:

  • sourceImage (itom.dataObject) – N-dimensional dataObject of any real type. This object is processed plane-by-plane.

  • destImage (itom.dataObject) – Resulting dataObject that has the same size and type than the sourceImage.

  • kernelx (int) –

    Size of kernel in x-direction (odd values only)

    Value range: [1, 101], Default: 3

  • kernely (int) –

    Size of kernel in y-direction (odd values only)

    Value range: [1, 101], Default: 3

  • replaceNaN (int, optional) –

    If 1, NaN values of sourceImage will be replaced by interpolated filter values in destImage, else destImage also contains NaN values at these positions (0, default).

    Value range: [0, 1], Default: 0

itom.algorithms.lowValueFilter(sourceImage, destImage, kernelx, kernely[, replaceNaN])#

2D minimum filter that set a pixel to the lowest value within the surrounding kernel.

The rectangular kernel of size (kernely, kernelx) is centered at each pixel of the source image. The same pixel in the destination image is then set to the minimum value within the kernel. Invalid values within the kernel are ignored. It is possible to fill these invalid values by the minimum of the surrounding kernel, too, if the parameter ‘replaceNaN’ is set to 1.

This filter can be applied inplace, hence, the source and destination image can be the same. This filter is implemented for all real data types. 3 or higher dimensional dataObjects are processed plane-by-plane, such that the destination image has always the same size and type than the input image.

See also: highValueFilter

Parameters:

  • sourceImage (itom.dataObject) – N-dimensional dataObject of any real type. This object is processed plane-by-plane.

  • destImage (itom.dataObject) – Resulting dataObject that has the same size and type than the sourceImage.

  • kernelx (int) –

    Size of kernel in x-direction (odd values only)

    Value range: [1, 101], Default: 3

  • kernely (int) –

    Size of kernel in y-direction (odd values only)

    Value range: [1, 101], Default: 3

  • replaceNaN (int, optional) –

    If 1, NaN values of sourceImage will be replaced by interpolated filter values in destImage, else destImage also contains NaN values at these positions (0, default).

    Value range: [0, 1], Default: 0

itom.algorithms.medianFilter(sourceImage, destImage, kernelx, kernely[, replaceNaN])#

2D median filter that set a pixel to the median value of all valid pixels within the kernel.

The rectangular kernel of size (kernely, kernelx) is centered at each pixel of the source image. The same pixel in the destination image is then set to the median value of all valid pixels within the kernel. Invalid values within the kernel are ignored. It is possible to fill these invalid values by the median value of the surrounding kernel, too, if the parameter ‘replaceNaN’ is set to 1.

This filter can be applied inplace, hence, the source and destination image can be the same. This filter is implemented for all real data types. 3 or higher dimensional dataObjects are processed plane-by-plane, such that the destination image has always the same size and type than the input image

Parameters:

  • sourceImage (itom.dataObject) – N-dimensional dataObject of any real type. This object is processed plane-by-plane.

  • destImage (itom.dataObject) – Resulting dataObject that has the same size and type than the sourceImage.

  • kernelx (int) –

    Size of kernel in x-direction (odd values only)

    Value range: [1, 101], Default: 3

  • kernely (int) –

    Size of kernel in y-direction (odd values only)

    Value range: [1, 101], Default: 3

  • replaceNaN (int, optional) –

    If 1, NaN values of sourceImage will be replaced by interpolated filter values in destImage, else destImage also contains NaN values at these positions (0, default).

    Value range: [0, 1], Default: 0

itom.algorithms.mergeColorPlane(srcImg, destImg[, toggleByteOrder])#

Merge 3 or 4 color planes to a single tRGBA32 or tInt32-plane.

If second object is tInt32 and of right size in x and y, the stack object will be converted to tInt32. In all other cases the object will be tRGBA32

Parameters:

  • srcImg (itom.dataObject) – Input image with 3 or 4 uint8 planes

  • destImg (itom.dataObject) – Output image with of type rgba32

  • toggleByteOrder (int, optional) –

    Switch between RGBA = 0, BGRA = 1, ARGB = 2, ABGR = 3

    Value range: [0, 3], Default: 0

itom.algorithms.replaceInfAndNaN(srcImg, replaceImg, destImg)#

replaces infinite and/or nan-values by values of second matrix.

Parameters:

  • srcImg (itom.dataObject) – Input object of type float32 or float64 whose non-finite values will be replaced with the values in replaceImg.

  • replaceImg (itom.dataObject) – replacement data object of same type and shape than srcImg.

  • destImg (itom.dataObject) – Output object of same type and shape than srcImg (inplace possible).

Returns:

nrOfReplacements - number of values that have been replaced.

Return type:

int

itom.algorithms.sobelOpt(sourceImage, destImage, dir[, replaceNaN])#

Performs a Sobel filtering with kernelsize (3 ,3) using the generic mcpp filter engine

Parameters:

  • sourceImage (itom.dataObject) – n-dim DataObject

  • destImage (itom.dataObject) – n-dim DataObject of type sourceImage

  • dir (int) –

    derivative in x: 0, y: 1 direction or 2: 2D magnitude sqrt(dx*dx + dy*dy)

    Value range: [0, 2], Default: 0

  • replaceNaN (int, optional) –

    if 0 NaN values in input image will be copied to output image (default)

    Value range: [0, 1], Default: 0

itom.algorithms.spikeMeanFilter(sourceImage, destImage, kernelx, kernely, delta, newValue[, replaceSpikeByNewValue])#

Performs a linear mean filter with kernelsize (kernelx, kernely) and pixelwise comparison of filtered image and original image to remove spikes according to delta value.

At first the input image is filtered by a linear mean filter (filter: ‘lowPassFilter’) using the given kernel size. The output image then contains the input image, where every pixel is replaced ‘newValue’ if the absolute distance between the median filtered and the input image at the specific pixel is bigger than ‘delta’.

This filter also works inplace (same source and destination).

Parameters:

  • sourceImage (itom.dataObject) – source dataObject of any real data type.

  • destImage (itom.dataObject) – destination dataObject (can be the same than source)

  • kernelx (int) –

    Odd kernelsize in x

    Value range: [1, 101], Default: 3

  • kernely (int) –

    Odd kernelsize in y

    Value range: [1, 101], Default: 3

  • delta (float) –

    Delta value for comparison

    Value range: [2.22045e-15, inf], Default: 0.05

  • newValue (float) –

    value set to clipped values

    All values allowed, Default: 0

  • replaceSpikeByNewValue (int, optional) –

    if 1 (default), a spike value is replaced by the parameter ‘newValue’, else it is replaced by the value from the filtered object.

    Value range: [0, 1], Default: 1

itom.algorithms.spikeMedianFilter(sourceImage, destImage, kernelx, kernely, delta, newValue[, replaceSpikeByNewValue])#

Performs a median filter with kernelsize (kernelx, kernely) and pixelwise comparison of filtered image and original image to remove spikes according to delta value.

At first the input image is filtered by a median filter (filter: ‘medianFilter’) using the given kernel size. The output image then contains the input image, where every pixel is replaced ‘newValue’ if the absolute distance between the median filtered and the input image at the specific pixel is bigger than ‘delta’.

This filter also works inplace (same source and destination).

Parameters:

  • sourceImage (itom.dataObject) – source dataObject of any real data type.

  • destImage (itom.dataObject) – destination dataObject (can be the same than source)

  • kernelx (int) –

    Odd kernelsize in x

    Value range: [1, 101], Default: 3

  • kernely (int) –

    Odd kernelsize in y

    Value range: [1, 101], Default: 3

  • delta (float) –

    Delta value for comparison

    Value range: [2.22045e-15, inf], Default: 0.05

  • newValue (float) –

    value set to clipped values

    All values allowed, Default: 0

  • replaceSpikeByNewValue (int, optional) –

    if 1 (default), a spike value is replaced by the parameter ‘newValue’, else it is replaced by the value from the filtered object.

    Value range: [0, 1], Default: 1

itom.algorithms.swapByteOrder(scrImage, destImage)#

Swap byte order for input image.

Parameters:

  • scrImage (itom.dataObject) – Input image

  • destImage (itom.dataObject) – Output image

5.2.3. Changelog#

  • itom setup 1.2.0: Release