Contributions by Serge X. Cohen¶
These filters were initially written with X-ray tomographic processing in mind. Still they are of a general usage as long as input are image.
Point-based transformation¶
Rejecting outliers in 3D¶
- class med-mad-reject¶
For each pixel of a frame within a stream, makes a 3x3x3 box (that is, 3x3 box including previous, current and following frames) and compute the median (med) and median absolute deviation (mad). If the value of the central pixel is too far from the median (relative to the mad) it is rejected and its value is replaced by the median value of the box.
- "threshold": float¶
When abs(px-med) > threshold*mad the pixel value (noted px) is replaced by med.
Rejecting outliers in 2D¶
- class med-mad-reject-2d¶
For each pixel of a frame make a square box centred on the pixel and compute the median (med) and median absolute deviation (mad). If the value of the central pixel is too far from the median (relative to the mad) it is rejected and its value is replaced by the median value of the box.
- "box-size": uint¶
The edge size of the box to be used (in px). This should be an even number so that it can be centred on a pixel.
- "threshold": float¶
When abs(px-med) > threshold*mad the pixel value (noted px) is replaced by med.
OpenCL one-liner computation¶
- class ocl-1liner¶
The aim is to enable the implementation of simple, nevertheless multiple input, computation on the basis of one work-item per pixel of the frame. The filter accepts arbitrary number of inputs, as long as more than one is provided. The output has the same size as the first input (indexed 0) and the generated OpenCL kernel is run with one work item per pixel of the output. The user provides a single computation line and the filter places it within a skeleton to produce an OpenCL kernel on the fly, then compiles it and uses it in the current workflow.
In the kernel the following variables are defined : sizeX and sizeY are the size of the frame in X and Y directions; x and y are the coordinate of the pixel corresponding to the current work item; in_x are the buffer holding the 0..(n-1) input frames; out is the buffer holding the output of the computation.
In the computation line provided through
one-line
the pixel corresponding to the current work item is px_index. Also reference to the pixel values can use multiple syntax : out[px_index], in_0[px_index], … in_x[px_index] or as shortcut (indeed macro of those) out_px, in_0_px, … in_x_px. Finally if one wants to have finer control over the pixel used in the computation (being able to use neighbouring pixel values) one can use the IMG_VAL macro as such IMG_VAL(x,y,out), IMG_VAL(x,y,in_x) …- "one-line": string¶
The computation to be performed expressed in one line of OpenCL, no trailing semi-column (added by the skeleton). To avoid miss-interpretation of the symbols by the line parser of ufo-launch it is advisable to surround the line by single quotes (on top of shell quoting). One example (invoking through ufo-launch) would be “‘out_px = (in_0_px > 0) ? sqrt(in_0_px) : 0.0f’” .
- "num-inputs": uint¶
The number of input streams. This is mandatory since it can not be inferred as it is the case by the OpenCL task.
- "quiet": boolean¶
Default to true, when set to false the dynamically generated kernel sources are printed to the standard output during the task setup.
Binning voxels¶
- class bin-voxels¶
Bin a cubic box made of voxel, assigning to each bin the value of one from a choice of functions (mean, max, min, var, range… ?)
- "edge-size"¶
The size fo the edge of the binning box. The total volume will be reduced by a factor equal to the cube of this parameter
- "kernel"¶
The choice of the reduction functions. To date one can select among mean, max, min, var, range and later maybe other ones ?
Reconstruction¶
Tomographic backprojection with irregular angular spaces¶
- class backproject-irregular¶
Computes the backprojection for a single sinogram, but with irregular angular spacing between projections. The angle position of each projection is provided by an ascii file containing all angular values in radian.
- "angles-filename"¶
The path to the file containing all the values of angular positions corresponding to each projection. These are provided in radian and parsed to double values.
- "projection-num": uint¶
Number of projections to backproject. The aim is to enable reconstruction based on a sub-part of the sinogram, to be used together with projection-offset.
- "projection-offset": uint¶
The index of the first projection ot be backprojected. The aim is to enable reconstruction based on a sub-part of the sinogram, to be used together with projection-offset.
- "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-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.
- "chuncking": uint¶
On some hardware, the GPU is monitored by a watchdog which kills the current if the time spent is larger than a certain amount. To avoid hitting this limit while reconstructing very large section, the computation can be split into multiple calls, practically accumulating over chunks of each sinograms. With value 0, or 1, the computation is done in a single pass for each section. Otherwise the computation is split in
chuncking
blocks. Furthermore, if chuncking is not 0, the call to the bacprojection kernel is done using the blocking semantic to ensure not averloading the GPU (at the risk to add a bit of dead-time at each call).
Destripping sinogram¶
- class destrip-siongram¶
Remove (partially) vertical stripes in the sinogram. These stripes can often occure due to non-lineartiy in scintillator or any other phenomenom which are not fully corrected by a so called
flat-field-correction
ornon-uniformity-correction
. When performed once for the full height of the sinogram, this correspond to what other softwares calldouble-flat-field
correction. In this instance we also provide and angular-running version of this correction to account for time-based scintillator non-uniformity (eg. what happens due to scintillator heating during the measruments).- "threshold": double¶
The threshold to use to detect stripes in the angular-averaged projections. The higher the value the less the correction will have effects. Should probably be in the range 1.0-3.0.
- "strip-width": uint¶
The width, in pixel, of the stripes to remove. This affects the way the stripe detection is performed once the run-averaged profile of a projection is computed. Hence when trying to detect/remove larger stripes one has to be carefull in setting a large enough value to both
strip-width
andaverage-length
; otherwise one is very likely producing over-smoothing of the sinogram.
- "average-length": uint¶
The number of projection to use before and after each projection to compute the local average on which is based the stripe detection (and removal). When this value is larger than the total number of projection of the sinogram, this filter correspond to the ‘classic’
double-flat-field
correction available in other reconstruction software.
- "output": enum¶
Setting which of the product of the filter should be transferred to the output. Indeed, unless for debuging or understanding the filter or tuning its parameter, you should keep the
destriped
value. Thedestriped-raw
value gives you the possibility to perform the correction without any (soft) clipping of the correciton factor (use at your own risks). But you can also have access to theaverage
sinogram (running projection average), thesmooth
average image or finally theraw-correction
orclipped-correction
factor, that is the difference or ratio between the previous two (depending on the correction-mode) which is applied to the input to provide thedestriped
sinogram.
- "correction-mode": enum¶
Telling the filter if the correction should be applied by and
additive
or amultiplicative
mode. Most likely, by the time you use this filter your sinograms will be expressed in absorbance (that is in logarithmic scale) in which case you should apply the correction by applying an additive offset. But if your sinogram is in transmitance (in linear scaled compared to the raw initial radiograph measurments) then you should better apply the correction through the use of a pixel-wise scale factor, in other words using amultiplicative
correction mode. Notice that even thouhg you can choose the correction more the results will be different when the raw correction factor is computed on absorbances vs. transmittances.
- "max-correction": double¶
The maximum correction to be applied. The correction found by comparing the averaged to the averaged-smoothed sinograms will be soft-clipped (using a tanh function) to be contained within [-max-correction, max-correction]. If the correction mode is set to
additive
the offset is clipped directly by the tanh function. When the correction mode is set tomultiplicative
it is the log of the scale factor that is soft-clipped by the tanh function.
Auxiliary¶
Producing simple statistics on a stream¶
- class stat-monitor¶
Inspects a data stream in a way similar to the
monitor
task but also computing simple statistics on the monitored frame stream: min, max, mean and standard deviation of each frame is computed. To limit truncation errors the OpenCL kernel uses fp64 operations if those are supported by the used OpenCL device, otherwise it falls back to use fp32 arithmetic which might incurs significant truncation errors on images of large dimensions.- "filename": string¶
When provided the tabulated statistics are output the file with this filename rather than displayed to standard output.
- "trace": boolean¶
When set to true will print processed frame index to standard output. This is useful if the task is placed in before a task somehow hiding the number of processed frames (in a complex workflow). Defaulting to false
- "quiet": boolean¶
When set to true will not print the frame monitoring. Defaulting to false to be as close as possible to the output of the
monitor
task.
- "print": uint¶
If set print the given numbers of items on stdout as hexadecimally formatted numbers (taken from
monitor
task).