Filters¶
Filters transform data and have at least one input and one output.
Point-based transformation¶
Binarization¶
Clipping¶
Arithmetic expressions¶
-
class
calculate
¶ Calculate an arithmetic expression. You have access to the value stored in the input buffer via the v letter in
expression
and to the index of v via letter x. Please be aware that v is a floating point number while x is an integer. This is useful if you have multidimensional data and want to address only one dimension. Let’s say the input is two dimensional, 256 pixels wide and you want to fill the x-coordinate with x for all respective y-coordinates (a gradient in x-direction). Then you can write expression=”x % 256”. Another example is the sinc function which you would calculate as expression=”sin(v) / x” for 1D input. For more complex math or other operations please consider using OpenCL.-
"expression"
: string¶ Arithmetic expression with math functions supported by OpenCL.
-
Statistics¶
Generic OpenCL¶
-
class
opencl
¶ Load an arbitrary OpenCL
kernel
fromfilename
orsource
and execute it on each input. The kernel must accept as many global float array parameters as connected to the filter and one additional as an output. For example, to compute the difference between two images, the kernel would look like:kernel void difference (global float *a, global float *b, global float *c) { size_t idx = get_global_id (1) * get_global_size (0) + get_global_id (0); c[idx] = a[idx] - b[idx]; }
and could be used like so if defined in a file named
diff.cl
:$ ufo-launch [read, read] ! opencl kernel=difference filename=diff.cl ! null
If
filename
is not set, a default kernel file (opencl.cl
) is loaded. See OpenCL default kernels for a list of kernel names defined in that file.-
"filename"
: string¶ Filename with kernel sources to load.
-
"source"
: string¶ String with OpenCL kernel code.
-
"kernel"
: string¶ Name of the kernel that this filter is associated with.
-
"options"
: string¶ OpenCL build options.
-
"dimensions"
: uint¶ Number of dimensions the kernel works on. Must be in [1, 3].
-
Spatial transformation¶
Rotation¶
-
class
rotate
¶ Rotates images clockwise by an
angle
around acenter
(x, y). Whenreshape
isTrue
, the rotated image is not cropped, i.e. the output image size can be larger that the input size. Moreover, this mode makes sure that the original coordinates of the input are all contained in the output so that it is easier to see the rotation in the output. Try e.g. rotation withcenter
equal to \((0, 0)\) and angle \(\pi / 2\).-
"angle"
: float¶ Rotation angle in radians.
-
"reshape"
: boolean¶ Reshape the result to encompass the complete input image and input indices.
-
"center"
: GValueArray¶ Center of rotation (x, y)
-
"addressing-mode"
: enum¶ Addressing mode specifies the behavior for pixels falling outside the original image. See OpenCL
sampler_t
documentation for more information.
-
"interpolation"
: enum¶ Specifies interpolation when a computed pixel coordinate falls between pixels, can be nearest or linear.
-
Flipping¶
Binning¶
Rescaling¶
-
class
rescale
¶ Rescale input data by a fixed
factor
.-
"factor"
: float¶ Fixed factor for scaling the input in both directions.
-
"x-factor"
: float¶ Fixed factor for scaling the input width.
-
"y-factor"
: float¶ Fixed factor for scaling the input height.
-
"width"
: uint¶ Fixed width, disabling scalar rescaling.
-
"height"
: uint¶ Fixed height, disabling scalar rescaling.
-
"interpolation"
: enum¶ Interpolation method used for rescaling which can be either
nearest
orlinear
.
-
Padding¶
-
class
pad
¶ Pad an image to some extent with specific behavior for pixels falling outside the original image.
-
"x"
: int¶ Horizontal coordinate in the output image which will contain the first input column.
-
"y"
: int¶ Vertical coordinate in the output image which will contain the first input row.
-
"width"
: uint¶ Width of the padded image.
-
"height"
: uint¶ Height of the padded image.
-
"addressing-mode"
: enum¶ Addressing mode specifies the behavior for pixels falling outside the original image. See OpenCL
sampler_t
documentation for more information.
-
Cropping¶
-
class
crop
¶ Crop a region of interest from two-dimensional input. If the region is (partially) outside the input, only accessible data will be copied.
-
"x"
: uint¶ Horizontal coordinate from where to start the ROI.
-
"y"
: uint¶ Vertical coordinate from where to start the ROI.
-
"width"
: uint¶ Width of the region of interest.
-
"height"
: uint¶ Height of the region of interest.
-
"from-center"
: boolean¶ Start cropping from the center outwards.
-
Cutting¶
Tiling¶
-
class
tile
¶ Cuts input into multiple tiles. The stream contains tiles in a zig-zag pattern, i.e. the first tile starts at the top left corner of the input goes on the same row until the end and continues on the first tile of the next row until the final tile in the lower right corner.
-
"width"
: uint¶ Width of a tile which must be a divisor of the input width. If this is not changed, the full width will be used.
-
"height"
: uint¶ Width of a tile which must be a divisor of the input height. If this is not changed, the full height will be used.
-
Swapping quadrants¶
-
class
swap-quadrants
¶ Cuts the input into four quadrants and swaps the lower right with the upper left and the lower left with the upper right quadrant.
Polar transformation¶
-
class
polar-coordinates
¶ Transformation between polar and cartesian coordinate systems.
When transforming from cartesian to polar coordinates the origin is in the image center (
width
/ 2,height
/ 2). When transforming from polar to cartesian coordinates the origin is in the image corner (0, 0).-
"width"
: uint¶ Final width after transformation.
-
"height"
: uint¶ Final height after transformation.
-
"direction"
: string¶ Conversion direction from
polar_to_cartesian
.
-
Stitching¶
-
class
stitch
¶ Stitches two images horizontally based on their relative given
shift
, which indicates how much is the second image shifted with respect to the first one, i.e. there is an overlapping region given by \(first\_width - shift\). First image is inserted to the stitched image from its left edge and the second image is inserted after the overlapping region. If shift is negative, the two images are swapped and stitched as described above with shift made positive.If you are stitching a 360-degree off-centered tomographic data set and know the axis of rotation, shift can be computed as \(2axis - second\_width\) for the case the axis of rotation is greater than half of the first image. If it is less, then the shift is \(first\_width - 2 axis\). Moreover, you need to horizontally flip one of the images because this task expects images which can be stitched directly, without additional needed transformations.
Stitching requires two inputs. If you want to stitch a 360-degree off-centered tomographic data set you can use:
ufo-launch [read path=projections_left/, read path=projections_right/ ! flip direction=horizontal] ! stitch shift=N ! write filename=foo.tif
-
"shift"
: int¶ How much is second image shifted with respect to the first one. For example, shift 0 means that both images overlap perfectly and the stitching doesn’t actually broaden the image. Shift corresponding to image width makes for a stitched image with twice the width of the respective images (if they have equal width).
-
"adjust-mean"
: boolean¶ Compute the mean of the overlapping region in the two images and adjust the second image to match the mean of the first one.
-
"blend"
: boolean¶ Linearly interpolate between the two images in the overlapping region.
-
Multi-stream¶
Interpolation¶
-
class
interpolate
¶ Interpolates incoming data from two compatible streams, i.e. the task computes \((1 - \alpha) s_1 + \alpha s_2\) where \(s_1\) and \(s_2\) are the two input streams and \(\alpha\) a blend factor. \(\alpha\) is \(i / (n - 1)\) for \(n > 1\), \(n\) being
number
and \(i\) the current iteration.-
"number"
: uint¶ Number of total output stream length.
-
Subtract¶
-
class
subtract
Subtract data items of the second from the first stream.
Correlate¶
-
class
correlate-stacks
¶ Reads two datastreams, the first must provide a 3D stack of images that is used to correlate individal 2D images from the second datastream. The
number
property must contain the expected number of items in the second stream.-
"number"
: uint¶ Number of data items in the second data stream.
-
Stream transformations¶
Averaging¶
Reducing with OpenCL¶
-
class
opencl-reduce
¶ Reduces or folds the input stream using a generic OpenCL kernel by loading an arbitrary
kernel
fromfilename
orsource
. The kernel must accept exactly two global float arrays, one for the input and one for the output. Additionally a secondfinish
kernel can be specified which is called once when the processing finished. This kernel must have two arguments as well, the global float array and an unsigned integer count. Folding (i.e. setting the initial data to a known value) is enabled by setting thefold-value
.Here is an OpenCL example how to compute the average:
kernel void sum (global float *in, global float *out) { size_t idx = get_global_id (1) * get_global_size (0) + get_global_id (0); out[idx] += in[idx]; } kernel void divide (global float *out, uint count) { size_t idx = get_global_id (1) * get_global_size (0) + get_global_id (0); out[idx] /= count; }
And this is how you would use it with
ufo-launch
:ufo-launch ... ! opencl-reduce kernel=sum finish=divide ! ...
If
filename
is not set, a default kernel file is loaded. See OpenCL reduction default kernels for a list of possible kernels.-
"filename"
: string¶ Filename with kernel sources to load.
-
"source"
: string¶ String with OpenCL kernel code.
-
"kernel"
: string¶ Name of the kernel that is called on each iteration. Must have two global float array arguments, the first being the input, the second the output.
-
"finish"
: string¶ Name of the kernel that is called at the end after all iterations. Must have a global float array and an unsigned integer arguments, the first being the data, the second the iteration counter.
-
"fold-value"
: float¶ If given, the initial data is filled with this value, otherwise the first input element is used.
-
"dimensions"
: uint¶ Number of dimensions the kernel works on. Must be in [1, 3].
-
Statistics¶
Stacking¶
Merging¶
Slice mapping¶
-
class
map-slice
¶ Lays out input images on a quadratic grid. If the
number
of input elements is not the square of some integer value, the next higher number is chosen and the remaining data is blackened.-
"number"
: uint¶ Number of expected input elements. If more elements are sent to the mapper, warnings are issued.
-
Color mapping¶
-
class
map-color
¶ Receives a two-dimensional image and maps its gray values to three red, green and blue color channels using the Viridis color map.
Splitting channels¶
-
class
unsplit
¶ Turns a three-dimensional image into two-dimensional image by interleaving the third dimension, i.e. [[[XXX],[YYY],[ZZZ]]] is turned into [[XYZ],[XYZ],[XYZ]]. This is useful to merge a separate multi-channel RGB image into a “regular” RGB image that can be shown with
cv-show
.This task adds the
channels
key to the output buffer containing the original depth of the input buffer.
Fourier domain¶
Fast Fourier transform¶
-
class
fft
¶ Compute the Fourier spectrum of input data. If
dimensions
is one but the input data is 2-dimensional, the 1-D FFT is computed for each row.-
"auto-zeropadding"
: boolean¶ Automatically zeropad input data to a size to the next power of 2.
-
"dimensions"
: uint¶ Number of dimensions in [1, 3].
-
"size-x"
: uint¶ Size of FFT transform in x-direction.
-
"size-y"
: uint¶ Size of FFT transform in y-direction.
-
"size-z"
: uint¶ Size of FFT transform in z-direction.
-
Frequency filtering¶
-
class
filter
¶ Computes a frequency filter function and multiplies it with its input, effectively attenuating certain frequencies.
-
"filter "
: enum¶ Any of
ramp
,ramp-fromreal
,butterworth
,faris-byer
,hamming
andbh3
(Blackman-Harris-3). The default filter isramp-fromreal
which computes a correct ramp filter avoiding offset issues encountered with naive implementations.
-
"scale"
: float¶ Arbitrary scale that is multiplied to each frequency component.
-
"cutoff"
: float¶ Cutoff frequency of the Butterworth filter.
-
"order"
: float¶ Order of the Butterworth filter.
-
"tau"
: float¶ Tau parameter of Faris-Byer filter.
-
"theta"
: float¶ Theta parameter of Faris-Byer filter.
-
1D stripe filtering¶
-
class
filter-stripes1d
¶ Filter stripes in 1D along the x-axis. The input and output are in frequency domain. The filter multiplies the frequencies with an inverse Gaussian profile centered at 0 frequency. The inversed profile means that the filter is f(k) = 1 - gauss(k) in order to suppress the low frequencies.
-
"strength"
: float¶ Filter strength, which is the full width at half maximum of the gaussian.
-
Reconstruction¶
Flat-field correction¶
-
class
flat-field-correct
¶ Computes the flat field correction using three data streams:
- Projection data on input 0
- Dark field data on input 1
- Flat field data on input 2
-
"absorption-correct"
: boolean¶ If TRUE, compute the negative natural logarithm of the flat-corrected data.
-
"fix-nan-and-inf"
: boolean¶ If TRUE, replace all resulting NANs and INFs with zeros.
-
"sinogram-input"
: boolean¶ If TRUE, correct only one line (the sinogram), thus darks are flats are 1D.
-
"dark-scale"
: float¶ Scale the dark field prior to the flat field correct.
Sinogram transposition¶
-
class
transpose-projections
¶ Read a stream of two-dimensional projections and output a stream of transposed sinograms.
number
must be set to the number of incoming projections to allocate enough memory.-
"number"
: uint¶ Number of projections.
Warning
This is a memory intensive task and can easily exhaust your system memory. Make sure you have enough memory, otherwise the process will be killed.
-
Tomographic backprojection¶
-
class
backproject
¶ Computes the backprojection for a single sinogram.
-
"num-projections"
: uint¶ Number of projections between 0 and 180 degrees.
-
"offset"
: uint¶ Offset to the first projection.
-
"axis-pos"
: double¶ Position of the rotation axis in horizontal pixel dimension of a sinogram or projection. If not given, the center of the sinogram is assumed.
-
"angle-step"
: double¶ Angle step increment in radians. If not given, pi divided by height of input sinogram is assumed.
-
"angle-offset"
: double¶ Constant angle offset in radians. This determines effectively the starting angle.
-
"mode"
: enum¶ Reconstruction mode which can be either
nearest
ortexture
.
-
"roi-x"
: uint¶ Horizontal coordinate of the start of the ROI. By default 0.
-
"roi-y"
: uint¶ Vertical coordinate of the start of the ROI. By default 0.
-
"roi-width"
: uint¶ Width of the region of interest. The default value of 0 denotes full width.
-
"roi-height"
: uint¶ Height of the region of interest. The default value of 0 denotes full height.
-
Forward projection¶
Laminographic backprojection¶
-
class
lamino-backproject
¶ Backprojects parallel beam computed laminography projection-by-projection into a 3D volume.
-
"region-values"
: int¶ Elements in regions.
-
"float-region-values"
: float¶ Elements in float regions.
-
"x-region"
: GValueArray¶ X region for reconstruction as (from, to, step).
-
"y-region"
: GValueArray¶ Y region for reconstruction as (from, to, step).
-
"z"
: float¶ Z coordinate of the reconstructed slice.
-
"region"
: GValueArray¶ Region for the parameter along z-axis as (from, to, step).
-
"projection-offset"
: GValueArray¶ Offset to projection data as (x, y) for the case input data is cropped to the necessary range of interest.
-
"center"
: GValueArray¶ Center of the volume with respect to projections (x, y), (rotation axes).
-
"overall-angle"
: float¶ Angle covered by all projections (can be negative for negative steps in case only num-projections is specified)
-
"num-projections"
: uint¶ Number of projections.
-
"tomo-angle"
: float¶ Tomographic rotation angle in radians (used for acquiring projections).
-
"lamino-angle"
: float¶ Absolute laminogrpahic angle in radians determining the sample tilt.
-
"roll-angle"
: float¶ Sample angular misalignment to the side (roll) in radians (CW is positive).
-
"parameter"
: enum¶ Which paramter will be varied along the z-axis, from
z
,x-center
,lamino-angle
,roll-angle
.
-
Fourier interpolation¶
-
class
dfi-sinc
¶ Computes the 2D Fourier spectrum of reconstructed image using 1D Fourier projection of sinogram (fft filter must be applied before). There are no default values for properties, therefore they should be assigned manually.
-
"kernel-size"
: uint¶ The length of kernel which will be used in interpolation.
-
"number-presampled-values"
: uint¶ Number of presampled values which will be used to calculate
kernel-size
kernel coefficients.
-
"roi-size"
: int¶ The length of one side of region of Interest.
-
"angle-step"
: double¶ Increment of angle in radians.
-
Center of rotation¶
Sinogram offset shift¶
Phase retrieval¶
-
class
retrieve-phase
¶ Computes and applies a fourier filter to correct phase-shifted data. Expects frequencies as an input and produces frequencies as an output.
-
"method"
: enum¶ Retrieval method which is one of
tie
,ctf
,ctfhalfsine
,qp
,qphalfsine
orqp2
.
-
"energy"
: float¶ Energy in keV.
-
"distance"
: float¶ Distance in meter.
-
"pixel-size"
: float¶ Pixel size in meter.
-
"regularization-rate"
: float¶ Regularization parameter is log10 of the constant to be added to the denominator to regularize the singularity at zero frequency: 1/sin(x) -> 1/(sin(x)+10^-RegPar).
Typical values [2, 3].
-
"thresholding-rate"
: float¶ Parameter for Quasiparticle phase retrieval which defines the width of the rings to be cropped around the zero crossing of the CTF denominator in Fourier space.
Typical values in [0.01, 0.1],
qp
retrieval is rather independent of cropping width.
-
General matrix-matrix multiplication¶
-
class
gemm
¶ Computes \(\alpha A \cdot B + \beta C\) where \(A\), \(B\) and \(C\) are input streams 0, 1 and 2 respectively. \(A\) must be of size \(m\times k\), \(B\) \(k\times n\) and \(C\) \(m\times n\).
Note
This filter is only available if CLBlast support is available.
-
"alpha"
: float¶ Scalar multiplied with \(AB\).
-
"beta"
: float¶ Scalar multiplied with \(C\).
-
Segmentation¶
-
class
segment
¶ Segments a stack of images given a field of labels using the random walk algorithm described in [1]. The first input stream must contain three-dimensional image stacks, the second input stream a label image with the same width and height as the images. Any pixel value other than zero is treated as a label and used to determine segments in all directions.
[1] Lösel and Heuveline, Enhancing a Diffusion Algorithm for 4D Image Segmentation Using Local Information in Proc. SPIE 9784, Medical Imaging 2016, http://proceedings.spiedigitallibrary.org/proceeding.aspx?articleid=2506235
Auxiliary¶
Buffering¶
-
class
buffer
¶ Buffers items internally until data stream has finished. After that all buffered elements are forwarded to the next task.
-
"number"
: uint¶ Number of pre-allocated buffers.
-
"dup-count"
: uint¶ Number of times each image should be duplicated.
-
"loop"
: boolean¶ Duplicates the data in a loop manner
dup-count
times.
-