Re-arrange filter documentation

1 files changed, 346 insertions, 319 deletions

diff --git a/docs/filters.rst b/docs/filters.rst
index 447d4f9..bd0c4b7 100644
--- a/docs/filters.rst
+++ b/docs/filters.rst
@@ -4,9 +4,9 @@ Filters
 
 Filters transform data and have at least one input and one output.
 
-Point-based filters
-===================
 
+Point-based transformation
+==========================
 
 Binarization
 ------------
@@ -19,6 +19,75 @@ Binarization
 
         Any values above the threshold are set to one all others to zero.
 
+Clipping
+--------
+
+.. gobj:class:: clip
+
+    Clip input to set minimum and maximum value.
+
+    .. gobj:prop:: min:float
+
+        Minimum value, all values lower than `min` are set to `min`.
+
+    .. gobj:prop:: max:float
+
+        Maximum value, all values higher than `max` are set to `max`.
+
+Arithmetic expressions
+----------------------
+
+.. gobj:class:: calculate
+
+    Calculate an arithmetic expression. You have access to the value stored in
+    the input buffer via the *v* letter in :gobj:prop:`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
+    :ref:`opencl <generic-opencl-ref>`.
+
+    .. gobj:prop:: expression
+
+        Arithmetic expression with math functions supported by OpenCL.
+
+
+.. _generic-opencl-ref:
+
+
+Generic OpenCL
+--------------
+
+.. gobj:class:: opencl
+
+    Load an arbitrary :gobj:prop:`kernel` from :gobj:prop:`filename` or
+    :gobj:prop:`source` 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.
+
+    .. gobj:prop:: filename:string
+
+        Filename with kernel sources to load.
+
+    .. gobj:prop:: source:string
+
+        String with OpenCL kernel code.
+
+    .. gobj:prop:: kernel:string
+
+        Name of the kernel that this filter is associated with.
+
+    .. gobj:prop:: dimensions:int
+
+        Number of dimensions the kernel works on. Must be in [1, 3].
+
+
+Spatial transformation
+======================
 
 Transposition
 -------------
@@ -41,66 +110,286 @@ Flipping
         with the image is flipped.
 
 
-Clipping
---------
+Binning
+-------
 
-.. gobj:class:: clip
+.. gobj:class:: bin
 
-    Clip input to set minimum and maximum value.
+    Bin a square of pixels by summing their values.
 
-    .. gobj:prop:: min:float
+    .. gobj:prop:: size:uint
 
-        Minimum value, all values lower than `min` are set to `min`.
+        Number of pixels in one direction to bin to a single pixel value.
 
-    .. gobj:prop:: max:float
 
-        Maximum value, all values higher than `max` are set to `max`.
+Rescaling
+---------
+
+.. gobj:class:: rescale
 
+    Rescale input data by a fixed :gobj:prop:`factor`.
 
-Binning
+    .. gobj:prop:: factor:int
+
+        Fixed factor for scaling the input in both directions.
+
+    .. gobj:prop:: x-factor:int
+
+        Fixed factor for scaling the input width.
+
+    .. gobj:prop:: y-factor:int
+
+        Fixed factor for scaling the input height.
+
+    .. gobj:prop:: width:int
+
+        Fixed width, disabling scalar rescaling.
+
+    .. gobj:prop:: height:int
+
+        Fixed height, disabling scalar rescaling.
+
+    .. gobj:prop:: interpolation:string
+
+        Interpolation method used for rescaling.
+
+Padding
 -------
 
-.. gobj:class:: bin
+.. gobj:class:: pad
 
-    Bin a square of pixels by summing their values.
+    Pad an image to some extent with specific behavior for pixels falling
+    outside the original image.
 
-    .. gobj:prop:: size:uint
+    .. gobj:prop:: x:int
 
-        Number of pixels in one direction to bin to a single pixel value.
+        Horizontal coordinate in the output image which will contain the first
+        input column.
+
+    .. gobj:prop:: y:int
+
+        Vertical coordinate in the output image which will contain the first
+        input row.
+
+    .. gobj:prop:: width:int
+
+        Width of the padded image.
+
+    .. gobj:prop:: height:int
+
+        Height of the padded image.
+
+    .. gobj:prop:: addressing-mode:string
+
+        Addressing mode specifies the behavior for pixels falling outside the
+        original image. See OpenCL sampler_t documentation for more information.
+
+
+Cropping
+--------
+
+.. gobj: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.
+
+    .. gobj:prop:: x:int
+
+        Horizontal coordinate from where to start the ROI.
+
+    .. gobj:prop:: y:int
+
+        Vertical coordinate from where to start the ROI.
+
+    .. gobj:prop:: width:int
+
+        Width of the region of interest.
+
+    .. gobj:prop:: height:int
+
+        Height of the region of interest.
 
+    .. gobj:prop:: from-center:boolean
+
+        Start cropping from the center outwards.
+
+
+Filters
+=======
+
+Median
+------
+
+.. gobj:class:: median-filter
+
+    Filters input with a simple median.
+
+    .. gobj:prop:: size:int
+
+        Odd-numbered size of the neighbouring window.
+
+
+Edge detection
+--------------
+
+.. gobj:class:: detect-edge
+
+    Detect edges by computing the power gradient image using different edge
+    filters.
+
+    .. gobj:prop:: type:string
+
+        Edge filter (or operator) which is one of ``sobel``, ``laplace`` and
+        ``prewitt``. By default, the ``sobel`` operator is used.
+
+
+
+Gaussian blur
+-------------
+
+.. gobj:class:: blur
+
+    Blur image with a gaussian kernel.
+
+    .. gobj:prop:: size:int
+
+        Size of the kernel.
+
+    .. gobj:prop:: sigma:int
+
+        Sigma of the kernel.
+
+
+
+Stream transformations
+======================
 
 Averaging
 ---------
 
 .. gobj:class:: average
 
-    Read in full data stream and generate an averaged output.
+Read in full data stream and generate an averaged output.
+
+.. gobj:prop:: number:int
+
+Number of averaged images to output. By default one image is generated.
+
+
+Slicing
+-------
+
+.. gobj:class:: slice
+
+    Slices a three-dimensional input buffer to two-dimensional slices.
+
+
+Stacking
+--------
+
+.. gobj:class:: stack
+
+    Symmetrical to the slice filter, the stack filter stacks two-dimensional
+    input.
 
     .. gobj:prop:: number:int
 
-        Number of averaged images to output. By default one image is generated.
+        Number of items, i.e. the length of the third dimension.
 
 
-Flat-field correction
----------------------
+Merging
+-------
 
-.. gobj:class:: flat-field-correct
+.. gobj:class:: merge
 
-    Computes the flat field correction using three data streams:
+    Merges the data from two or more input data streams into a single data
+    stream by concatenation.
 
-    1. Projection data on input 0
-    2. Dark field data on input 1
-    3. Flat field data on input 2
+    .. gobj:prop:: number:int
 
+        Number of input streams. By default this is two.
 
-    .. gobj:prop:: absorption-correction:boolean
 
-        If *TRUE*, compute the negative natural logarithm of the
-        flat-corrected data.
+Slice mapping
+-------------
 
-    .. gobj:prop:: fix-nan-and-inf:boolean
+.. gobj:class:: map-slice
 
-        If *TRUE*, replace all resulting NANs and INFs with zeros.
+    Lays out input images on a quadratic grid. If the :gobj:prop:`number` of
+    input elements is not the square of some integer value, the next higher
+    number is chosen and the remaining data is blackened.
+
+    .. gobj:prop:: number:int
+
+        Number of expected input elements. If more elements are sent to the
+        mapper, warnings are issued.
+
+
+Fourier domain
+==============
+
+Fast Fourier transform
+----------------------
+
+.. gobj:class:: fft
+
+    Compute the Fourier spectrum of input data. If :gobj:prop:`dimensions` is one
+    but the input data is 2-dimensional, the 1-D FFT is computed for each row.
+
+    .. gobj:prop:: auto-zeropadding:boolean
+
+        Automatically zeropad input data to a size to the next power of 2.
+
+    .. gobj:prop:: dimensions:int
+
+        Number of dimensions in [1, 3].
+
+    .. gobj:prop:: size-x:int
+
+        Size of FFT transform in x-direction.
+
+    .. gobj:prop:: size-y:int
+
+        Size of FFT transform in y-direction.
+
+    .. gobj:prop:: size-z:int
+
+        Size of FFT transform in z-direction.
+
+
+.. gobj:class:: ifft
+
+    Compute the inverse Fourier of spectral input data. If
+    :gobj:prop:`dimensions` is one but the input data is 2-dimensional, the 1-D
+    FFT is computed for each row.
+
+    .. gobj:prop:: auto-zeropadding:boolean
+
+        Automatically zeropad input data to a size to the next power of 2.
+
+    .. gobj:prop:: dimensions:int
+
+        Number of dimensions in [1, 3].
+
+    .. gobj:prop:: size-x:int
+
+        Size of FFT transform in x-direction.
+
+    .. gobj:prop:: size-y:int
+
+        Size of FFT transform in y-direction.
+
+    .. gobj:prop:: size-z:int
+
+        Size of FFT transform in z-direction.
+
+    .. gobj:prop:: crop-width:int
+
+        Width to crop output.
+
+    .. gobj:prop:: crop-height:int
+
+        Height to crop output.
 
 
 Frequency filtering
@@ -139,84 +428,45 @@ Frequency filtering
         Theta parameter of Faris-Byer filter.
 
 
-Arithmetic expressions
-----------------------
-
-.. gobj:class:: calculate
-
-    Calculate an arithmetic expression. You have access to the value stored in
-    the input buffer via the *v* letter in :gobj:prop:`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
-    :ref:`opencl <generic-opencl-ref>`.
-
-    .. gobj:prop:: expression
-
-        Arithmetic expression with math functions supported by OpenCL.
-
-
-.. _generic-opencl-ref:
-
-Generic OpenCL
---------------
-
-.. gobj:class:: opencl
-
-    Load an arbitrary :gobj:prop:`kernel` from :gobj:prop:`filename` or
-    :gobj:prop:`source` 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.
-
-    .. gobj:prop:: filename:string
-
-        Filename with kernel sources to load.
-
-    .. gobj:prop:: source:string
-
-        String with OpenCL kernel code.
-
-    .. gobj:prop:: kernel:string
-
-        Name of the kernel that this filter is associated with.
+1D stripe filtering
+-------------------
 
-    .. gobj:prop:: dimensions:int
+.. gobj:class:: filter-stripes1d
 
-        Number of dimensions the kernel works on. Must be in [1, 3].
+    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.
 
+    .. gobj:prop:: strength:int
 
-Complex filters
-===============
+        Filter strength, which is the full width at half maximum of the
+        gaussian.
 
-Median
-------
 
-.. gobj:class:: median-filter
+Reconstruction
+==============
 
-    Filters input with a simple median.
+Flat-field correction
+---------------------
 
-    .. gobj:prop:: size:int
+.. gobj:class:: flat-field-correct
 
-        Odd-numbered size of the neighbouring window.
+    Computes the flat field correction using three data streams:
 
+    1. Projection data on input 0
+    2. Dark field data on input 1
+    3. Flat field data on input 2
 
-Edge detection
---------------
 
-.. gobj:class:: detect-edge
+    .. gobj:prop:: absorption-correction:boolean
 
-    Detect edges by computing the power gradient image using different edge
-    filters.
+        If *TRUE*, compute the negative natural logarithm of the
+        flat-corrected data.
 
-    .. gobj:prop:: type:string
+    .. gobj:prop:: fix-nan-and-inf:boolean
 
-        Edge filter (or operator) which is one of ``sobel``, ``laplace`` and
-        ``prewitt``. By default, the ``sobel`` operator is used.
+        If *TRUE*, replace all resulting NANs and INFs with zeros.
 
 
 Sinogram transposition
@@ -407,209 +657,8 @@ Phase retrieval
         cropping width.
 
 
-Gaussian blur
--------------
-
-.. gobj:class:: blur
-
-    Blur image with a gaussian kernel.
-
-    .. gobj:prop:: size:int
-
-        Size of the kernel.
-
-    .. gobj:prop:: sigma:int
-
-        Sigma of the kernel.
-
-
-Padding
--------
-
-.. gobj:class:: pad
-
-    Pad an image to some extent with specific behavior for pixels falling
-    outside the original image.
-
-    .. gobj:prop:: x:int
-
-        Horizontal coordinate in the output image which will contain the first
-        input column.
-
-    .. gobj:prop:: y:int
-
-        Vertical coordinate in the output image which will contain the first
-        input row.
-
-    .. gobj:prop:: width:int
-
-        Width of the padded image.
-
-    .. gobj:prop:: height:int
-
-        Height of the padded image.
-
-    .. gobj:prop:: addressing-mode:string
-
-        Addressing mode specifies the behavior for pixels falling outside the
-        original image. See OpenCL sampler_t documentation for more information.
-
-
-Cropping
---------
-
-.. gobj: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.
-
-    .. gobj:prop:: x:int
-
-        Horizontal coordinate from where to start the ROI.
-
-    .. gobj:prop:: y:int
-
-        Vertical coordinate from where to start the ROI.
-
-    .. gobj:prop:: width:int
-
-        Width of the region of interest.
-
-    .. gobj:prop:: height:int
-
-        Height of the region of interest.
-
-    .. gobj:prop:: from-center:boolean
-
-        Start cropping from the center outwards.
-
-
-Rescaling
----------
-
-.. gobj:class:: rescale
-
-    Rescale input data by a fixed :gobj:prop:`factor`.
-
-    .. gobj:prop:: factor:int
-
-        Fixed factor for scaling the input.
-
-    .. gobj:prop:: interpolation:string
-
-        Interpolation method used for rescaling.
-
-
-Merging
--------
-
-.. gobj:class:: merge
-
-    Merges the data from two or more input data streams into a single data
-    stream by concatenation.
-
-    .. gobj:prop:: number:int
-
-        Number of input streams. By default this is two.
-
-
-Slice mapping
--------------
-
-.. gobj:class:: map-slice
-
-    Lays out input images on a quadratic grid. If the :gobj:prop:`number` of
-    input elements is not the square of some integer value, the next higher
-    number is chosen and the remaining data is blackened.
-
-    .. gobj:prop:: number:int
-
-        Number of expected input elements. If more elements are sent to the
-        mapper, warnings are issued.
-
-
-Fast Fourier transform
-----------------------
-
-.. gobj:class:: fft
-
-    Compute the Fourier spectrum of input data. If :gobj:prop:`dimensions` is one
-    but the input data is 2-dimensional, the 1-D FFT is computed for each row.
-
-    .. gobj:prop:: auto-zeropadding:boolean
-
-        Automatically zeropad input data to a size to the next power of 2.
-
-    .. gobj:prop:: dimensions:int
-
-        Number of dimensions in [1, 3].
-
-    .. gobj:prop:: size-x:int
-
-        Size of FFT transform in x-direction.
-
-    .. gobj:prop:: size-y:int
-
-        Size of FFT transform in y-direction.
-
-    .. gobj:prop:: size-z:int
-
-        Size of FFT transform in z-direction.
-
-
-.. gobj:class:: ifft
-
-    Compute the inverse Fourier of spectral input data. If
-    :gobj:prop:`dimensions` is one but the input data is 2-dimensional, the 1-D
-    FFT is computed for each row.
-
-    .. gobj:prop:: auto-zeropadding:boolean
-
-        Automatically zeropad input data to a size to the next power of 2.
-
-    .. gobj:prop:: dimensions:int
-
-        Number of dimensions in [1, 3].
-
-    .. gobj:prop:: size-x:int
-
-        Size of FFT transform in x-direction.
-
-    .. gobj:prop:: size-y:int
-
-        Size of FFT transform in y-direction.
-
-    .. gobj:prop:: size-z:int
-
-        Size of FFT transform in z-direction.
-
-    .. gobj:prop:: crop-width:int
-
-        Width to crop output.
-
-    .. gobj:prop:: crop-height:int
-
-        Height to crop output.
-
-
-1D stripe filtering
--------------------
-
-.. gobj: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.
-
-    .. gobj:prop:: strength:int
-
-        Filter strength, which is the full width at half maximum of the
-        gaussian.
-
-
 General matrix-matrix multiplication
-------------------------------------
+====================================
 
 .. gobj:class:: gemm
 
@@ -631,7 +680,7 @@ General matrix-matrix multiplication
 
 
 Segmentation
-------------
+============
 
 .. gobj:class:: segment
 
@@ -648,8 +697,8 @@ Segmentation
         Imaging 2016, https://doi.org/10.1117/12.2216202
 
 
-Auxiliary filters
-=================
+Auxiliary
+=========
 
 Buffering
 ---------
@@ -690,25 +739,3 @@ Monitoring
 
         If set print the given numbers of items on stdout as hexadecimally
         formatted numbers.
-
-
-Slicing
--------
-
-.. gobj:class:: slice
-
-    Slices a three-dimensional input buffer to two-dimensional slices.
-
-
-Stacking
---------
-
-.. gobj:class:: stack
-
-    Symmetrical to the slice filter, the stack filter stacks two-dimensional
-    input.
-
-    .. gobj:prop:: number:int
-
-        Number of items, i.e. the length of the third dimension.
-