5.2. Basic Filters

Summary:	ITO developed filter-functions for data objects
Type:	Algorithm
License:	LGPL
Platforms:	Windows, Linux
Author:	W. Lyda, T. Boettcher, University 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:

5.2.2. Filters

Detailed overview about all defined filters:

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

calculates histgram 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 comparision
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 primitiv 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 primitiv 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 fullfill 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