===============================
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
------------------------

.. gobj: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.

    .. gobj:prop:: threshold:float

        When abs(px-med) > threshold*mad the pixel value (noted px)
        is replaced by med.


Rejecting outliers in 2D
------------------------

.. gobj: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.

    .. gobj:prop:: 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.

    .. gobj:prop:: threshold:float

        When abs(px-med) > threshold*mad the pixel value (noted px)
        is replaced by med.

OpenCL one-liner computation
----------------------------

.. gobj: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 :gobj:prop:`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)` ...

   .. gobj:prop:: 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'"` .

   .. gobj:prop:: num-inputs:uint

       The number of input streams. This is mandatory since it can not
       be inferred as it is the case by the :ref:`OpenCL
       <generic-opencl-ref>` task.

   .. gobj:prop:: 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
--------------

.. gobj: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… ?)

    .. gobj:prop:: 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

    .. gobj:prop:: 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
--------------------------------------------------------

.. gobj: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.

    .. gobj:prop:: 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.

    .. gobj:prop:: 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.

    .. gobj:prop:: 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.

    .. gobj:prop:: 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.

    .. gobj:prop:: angle-offset:double

        Constant angle offset in radians. This determines effectively the
        starting angle.

    .. gobj:prop:: mode:enum

        Reconstruction mode which can be either ``nearest`` or ``texture``.

    .. gobj:prop:: roi-x:uint

        Horizontal coordinate of the start of the ROI. By default 0.

    .. gobj:prop:: roi-y:uint

        Vertical coordinate of the start of the ROI. By default 0.

    .. gobj:prop:: roi-width:uint

        Width of the region of interest. The default value of 0 denotes full
        width.

    .. gobj:prop:: roi-height:uint

        Height of the region of interest. The default value of 0 denotes full
        height.

    .. gobj:prop:: 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
--------------------

.. gobj: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`` or
    ``non-uniformity-correction``. When performed once for the full height of the
    sinogram, this correspond to what other softwares call ``double-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).

    .. gobj:prop:: 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.

    .. gobj:prop:: 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`` and ``average-length``; otherwise one is very likely
        producing over-smoothing of the sinogram.

    .. gobj:prop:: 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.

    .. gobj:prop:: 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.
	The ``destriped-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 the ``average`` sinogram (running
        projection average), the ``smooth`` average image or finally the
        ``raw-correction`` or ``clipped-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 the
	``destriped`` sinogram.

    .. gobj:prop:: correction-mode:enum

        Telling the filter if the correction should be applied by and
	``additive`` or a ``multiplicative`` 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 a ``multiplicative`` 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.

    .. gobj:prop:: 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 to ``multiplicative``
	it is the log of the scale factor that is soft-clipped by the tanh function.


Auxiliary
=========

Producing simple statistics on a stream
---------------------------------------

.. gobj:class:: stat-monitor

    Inspects a data stream in a way similar to the :gobj:class:`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.

    .. gobj:prop:: filename:string

        When provided the tabulated statistics are output the file
        with this filename rather than displayed to standard output.

    .. gobj:prop:: 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`

    .. gobj:prop:: 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 :gobj:class:`monitor` task.

    .. gobj:prop:: print:uint

        If set print the given numbers of items on stdout as hexadecimally
        formatted numbers (taken from :gobj:class:`monitor` task).
