Merge pull request #1196 from tucna:fuzzy_documentation

Author: alalek

modules/fuzzy/doc/fuzzy.bib

@@ -10,10 +10,9 @@ @article{Perf:FT
 }
 
 @article{Perf:rec,
-  title={Image Reconstruction by means of F-transform},
+  title={Image Reconstruction by means of {F}-transform},
   author={Perfilieva, Irina and Vla{\v{s}}{\'a}nek, Pavel},
   journal={Knowledge-Based Systems},
-  keywords = {myown},
   volume={70},
   pages={55--63},
   year={2014},
@@ -30,3 +29,50 @@ @article{Vlas:FT
   pages={54--62},
   year={2016}
 }
+
+@article{MSLP:cod-decod,
+  title={An image coding/decoding method based on direct and inverse fuzzy transforms},
+  author={Di Martino, Ferdinando and Loia, Vincenzo and Perfilieva, Irina and Sessa, Salvatore},
+  journal={International Journal of Approximate Reasoning},
+  volume={48},
+  number={1},
+  pages={110--131},
+  year={2008},
+  publisher={Elsevier}
+}
+
+@article{Fusion:AFS12,
+  title={Advanced F-transform-based image fusion},
+  author={Vajgl, Marek and Perfilieva, Irina and Hod'{\'a}kov{\'a}, Petra},
+  journal={Advances in Fuzzy Systems},
+  volume={2012},
+  pages={4},
+  year={2012},
+  publisher={Hindawi Publishing Corp.}
+}
+
+@incollection{IPMU2012,
+  title={$F^1$-transform edge detector inspired by canny’s algorithm},
+  author={Perfilieva, Irina and Hod'{\'a}kov{\'a}, Petra and Hurtík, Petr},
+  booktitle={Advances on Computational Intelligence},
+  pages={230--239},
+  year={2012},
+  publisher={Springer}
+}
+
+@article{perfilieva2014differentiation,
+  title={Differentiation by the {F}-transform and application to edge detection},
+  author={Perfilieva, Irina and Hod{\'a}kov{\'a}, Petra and Hurt{\'\i}k, Petr},
+  journal={Fuzzy Sets and Systems},
+  year={2014},
+  publisher={Elsevier}
+}
+
+@inproceedings{vlavsanek2015patch,
+  title={Patch based inpainting method based on the F1-transform},
+  author={Vla{\v{s}}{\'a}nek, Pavel and Perfilieva, Irina},
+  booktitle={Soft Computing and Pattern Recognition (SoCPaR), 2015 7th International Conference of},
+  pages={235--240},
+  year={2015},
+  organization={IEEE}
+}

modules/fuzzy/include/opencv2/fuzzy.hpp

@@ -50,16 +50,16 @@
 /**
 @defgroup fuzzy Image processing based on fuzzy mathematics
 
-Namespace for all functions is **ft**. The module brings implementation of the last image processing algorithms based on fuzzy mathematics.
+Namespace for all functions is `ft`. The module brings implementation of the last image processing algorithms based on fuzzy mathematics. Method are named based on the pattern `FT`_degree_dimension`_`method.
 
   @{
     @defgroup f0_math Math with F0-transform support
 
-Fuzzy transform (F0-transform) of the 0th degree transforms whole image to a matrix of its components. These components are used in latter computation where each of them represents average color of certain subarea.
+Fuzzy transform (\f$F^0\f$-transform) of the 0th degree transforms whole image to a matrix of its components. These components are used in latter computation where each of them represents average color of certain subarea.
 
     @defgroup f1_math Math with F1-transform support
 
-Fuzzy transform (F1-transform) of the 1th degree transforms whole image to a matrix of its components. Each component is polynomial of the 1th degree carrying information about average color and average gradient of certain subarea.
+Fuzzy transform (\f$F^1\f$-transform) of the 1th degree transforms whole image to a matrix of its components. Each component is polynomial of the 1th degree carrying information about average color and average gradient of certain subarea.
 
     @defgroup f_image Fuzzy image processing
 

modules/fuzzy/include/opencv2/fuzzy/fuzzy_F0_math.hpp

@@ -53,68 +53,64 @@ namespace ft
     //! @addtogroup f0_math
     //! @{
 
-    /** @brief Computes components of the array using direct F0-transform.
+    /** @brief Computes components of the array using direct \f$F^0\f$-transform.
     @param matrix Input array.
-    @param kernel Kernel used for processing. Function **createKernel** can be used.
+    @param kernel Kernel used for processing. Function `ft::createKernel` can be used.
     @param components Output 32-bit float array for the components.
     @param mask Mask can be used for unwanted area marking.
 
     The function computes components using predefined kernel and mask.
-
-    @note
-        F-transform technique is described in paper @cite Perf:FT.
      */
     CV_EXPORTS_W void FT02D_components(InputArray matrix, InputArray kernel, OutputArray components, InputArray mask = noArray());
 
-    /** @brief Computes inverse F0-transfrom.
+    /** @brief Computes inverse \f$F^0\f$-transfrom.
     @param components Input 32-bit float single channel array for the components.
-    @param kernel Kernel used for processing. Function **createKernel** can be used.
+    @param kernel Kernel used for processing. Function `ft::createKernel` can be used.
     @param output Output 32-bit float array.
     @param width Width of the output array.
     @param height Height of the output array.
 
-    @note
-        F-transform technique is described in paper @cite Perf:FT.
+    Computation of inverse F-transform.
      */
     CV_EXPORTS_W void FT02D_inverseFT(InputArray components, InputArray kernel, OutputArray output, int width, int height);
 
-    /** @brief Computes F0-transfrom and inverse F0-transfrom at once.
+    /** @brief Computes \f$F^0\f$-transfrom and inverse \f$F^0\f$-transfrom at once.
     @param matrix Input matrix.
-    @param kernel Kernel used for processing. Function **createKernel** can be used.
+    @param kernel Kernel used for processing. Function `ft::createKernel` can be used.
     @param output Output 32-bit float array.
     @param mask Mask used for unwanted area marking.
 
-    This function computes F-transfrom and inverse F-transfotm in one step. It is fully sufficient and optimized for **Mat**.
+    This function computes F-transfrom and inverse F-transfotm in one step. It is fully sufficient and optimized for `cv::Mat`.
     */
     CV_EXPORTS_W void FT02D_process(InputArray matrix, InputArray kernel, OutputArray output, InputArray mask = noArray());
 
-    /** @brief Computes F0-transfrom and inverse F0-transfrom at once and return state.
+    /** @brief Computes \f$F^0\f$-transfrom and inverse \f$F^0\f$-transfrom at once and return state.
     @param matrix Input matrix.
-    @param kernel Kernel used for processing. Function **createKernel** can be used.
+    @param kernel Kernel used for processing. Function `ft::createKernel` can be used.
     @param output Output 32-bit float array.
     @param mask Mask used for unwanted area marking.
     @param maskOutput Mask after one iteration.
-    @param firstStop If **true** function returns -1 when first problem appears. In case of **false**, the process is completed and summation of all problems returned.
+    @param firstStop If **true** function returns -1 when first problem appears. In case of `false` the process is completed and summation of all problems returned.
 
-    This function computes iteration of F-transfrom and inverse F-transfotm and handle image and mask change. The function is used in *inpaint* function.
+    This function computes iteration of F-transfrom and inverse F-transfotm and handle image and mask change. The function is used in `ft::inpaint` function.
     */
     CV_EXPORTS_W int FT02D_iteration(InputArray matrix, InputArray kernel, OutputArray output, InputArray mask, OutputArray maskOutput, bool firstStop);
 
-    /** @brief Sligtly less accurate version of F0-transfrom computation optimized for higher speed. The methods counts with linear basic function.
+    /** @brief Sligtly less accurate version of \f$F^0\f$-transfrom computation optimized for higher speed. The methods counts with linear basic function.
     @param matrix Input 3 channels matrix.
-    @param radius Radius of the **LINEAR** basic function.
+    @param radius Radius of the `ft::LINEAR` basic function.
     @param output Output array.
 
-    This function computes F-transfrom and inverse F-transfotm using linear basic function in one step. It is ~10 times faster than **FT02D_process** method.
+    This function computes F-transfrom and inverse F-transfotm using linear basic function in one step. It is ~10 times faster than `ft::FT02D_process` method.
     */
     CV_EXPORTS_W void FT02D_FL_process(InputArray matrix, const int radius, OutputArray output);
 
-    /** @brief Sligtly less accurate version of F0-transfrom computation optimized for higher speed. The methods counts with linear basic function.
+    /** @brief Sligtly less accurate version of \f$F^0\f$-transfrom computation optimized for higher speed. The methods counts with linear basic function.
     @param matrix Input 3 channels matrix.
-    @param radius Radius of the **LINEAR** basic function.
+    @param radius Radius of the `ft::LINEAR` basic function.
     @param output Output array.
 
-    This function computes F-transfrom and inverse F-transfotm using linear basic function in one step. It is ~9 times faster then **FT02D_process** method and more accurate than **FT02D_FL_process** method.
+    This function computes F-transfrom and inverse F-transfotm using linear basic function in one step. It is ~9 times faster then `ft::FT02D_process` method and more accurate than `ft::FT02D_FL_process` method.
     */
     CV_EXPORTS_W void FT02D_FL_process_float(InputArray matrix, const int radius, OutputArray output);
 

modules/fuzzy/include/opencv2/fuzzy/fuzzy_F1_math.hpp

@@ -53,71 +53,67 @@ namespace ft
     //! @addtogroup f1_math
     //! @{
 
-    /** @brief Computes components of the array using direct F1-transform.
+    /** @brief Computes components of the array using direct \f$F^1\f$-transform.
     @param matrix Input array.
-    @param kernel Kernel used for processing. Function **createKernel** can be used.
+    @param kernel Kernel used for processing. Function `ft::createKernel` can be used.
     @param components Output 32-bit float array for the components.
 
     The function computes linear components using predefined kernel.
-
-    @note
-        F-transform technique of first degreee is described in paper @cite Vlas:FT.
     */
     CV_EXPORTS_W void FT12D_components(InputArray matrix, InputArray kernel, OutputArray components);
 
-    /** @brief Computes elements of F1-transform components.
+    /** @brief Computes elements of \f$F^1\f$-transform components.
     @param matrix Input array.
-    @param kernel Kernel used for processing. Function **createKernel** can be used.
+    @param kernel Kernel used for processing. Function `ft::createKernel` can be used.
     @param c00 Elements represent average color.
     @param c10 Elements represent average vertical gradient.
     @param c01 Elements represent average horizontal gradient.
     @param components Output 32-bit float array for the components.
     @param mask Mask can be used for unwanted area marking.
 
     The function computes components and its elements using predefined kernel and mask.
-
-    @note
-        F-transform technique of first degreee is described in paper @cite Vlas:FT.
     */
     CV_EXPORTS_W void FT12D_polynomial(InputArray matrix, InputArray kernel, OutputArray c00, OutputArray c10, OutputArray c01, OutputArray components, InputArray mask = noArray());
 
-    /** @brief Creates vertical matrix for F1-transform computation.
+    /** @brief Creates vertical matrix for \f$F^1\f$-transform computation.
     @param radius Radius of the basic function.
     @param matrix The vertical matrix.
     @param chn Number of channels.
 
-    The function creates helper vertical matrix for F1-transfrom processing. It is used for gradient computation.
+    The function creates helper vertical matrix for \f$F^1\f$-transfrom processing. It is used for gradient computation.
     */
     CV_EXPORTS_W void FT12D_createPolynomMatrixVertical(int radius, OutputArray matrix, const int chn);
 
-    /** @brief Creates horizontal matrix for F1-transform computation.
+    /** @brief Creates horizontal matrix for \f$F^1\f$-transform computation.
     @param radius Radius of the basic function.
     @param matrix The horizontal matrix.
     @param chn Number of channels.
 
-    The function creates helper horizontal matrix for F1-transfrom processing. It is used for gradient computation.
+    The function creates helper horizontal matrix for \f$F^1\f$-transfrom processing. It is used for gradient computation.
     */
     CV_EXPORTS_W void FT12D_createPolynomMatrixHorizontal(int radius, OutputArray matrix, const int chn);
 
-    /** @brief Computes F1-transfrom and inverse F1-transfrom at once.
+    /** @brief Computes \f$F^1\f$-transfrom and inverse \f$F^1\f$-transfrom at once.
     @param matrix Input matrix.
-    @param kernel Kernel used for processing. Function **createKernel** can be used.
+    @param kernel Kernel used for processing. Function `ft::createKernel` can be used.
     @param output Output 32-bit float array.
     @param mask Mask used for unwanted area marking.
 
-    This function computes F1-transfrom and inverse F1-transfotm in one step. It is fully sufficient and optimized for **Mat**.
+    This function computes \f$F^1\f$-transfrom and inverse \f$F^1\f$-transfotm in one step. It is fully sufficient and optimized for `cv::Mat`.
+
+    @note
+        F-transform technique of first degreee is described in paper @cite Vlas:FT.
     */
     CV_EXPORTS_W void FT12D_process(InputArray matrix, InputArray kernel, OutputArray output, InputArray mask = noArray());
 
-    /** @brief Computes inverse F1-transfrom.
+    /** @brief Computes inverse \f$F^1\f$-transfrom.
     @param components Input 32-bit float single channel array for the components.
     @param kernel Kernel used for processing. The same kernel as for components computation must be used.
     @param output Output 32-bit float array.
     @param width Width of the output array.
     @param height Height of the output array.
 
-    @note
-        F-transform technique of first degreee is described in paper @cite Vlas:FT.
+    Computation of inverse \f$F^1\f$-transform.
     */
     CV_EXPORTS_W void FT12D_inverseFT(InputArray components, InputArray kernel, OutputArray output, int width, int height);
 

modules/fuzzy/include/opencv2/fuzzy/fuzzy_image.hpp

@@ -80,11 +80,11 @@ namespace ft
     @param output Output 32-bit image.
     @param radius Radius of the basic function.
     @param function Function type could be one of the following:
-        -   **LINEAR** Linear basic function.
+        -   `ft::LINEAR` Linear basic function.
     @param algorithm Algorithm could be one of the following:
-        -   **ONE_STEP** One step algorithm.
-        -   **MULTI_STEP** Algorithm automaticaly increasing radius of the basic function.
-        -   **ITERATIVE** Iterative algorithm running in more steps using partial computations.
+        -   `ft::ONE_STEP` One step algorithm.
+        -   `ft::MULTI_STEP` This algorithm automaticaly increases radius of the basic function.
+        -   `ft::ITERATIVE` Iterative algorithm running in more steps using partial computations.
 
     This function provides inpainting technique based on the fuzzy mathematic.
 

modules/fuzzy/include/opencv2/fuzzy/types.hpp

@@ -52,15 +52,15 @@ namespace ft
 
     enum
     {
-        LINEAR = 1,
-        SINUS = 2
+        LINEAR = 1, //!< linear (triangular) shape
+        SINUS = 2 //!< sinusoidal shape
     };
 
     enum
     {
-        ONE_STEP = 1,
-        MULTI_STEP = 2,
-        ITERATIVE = 3
+        ONE_STEP = 1, //!< processing in one step
+        MULTI_STEP = 2, //!< processing in multiple step
+        ITERATIVE = 3 //!< processing in several iterations
     };
 
     //! @}

modules/fuzzy/src/fuzzy_image.cpp

@@ -47,7 +47,7 @@ void ft::createKernel(InputArray A, InputArray B, OutputArray kernel, const int
 {
     Mat AMat = A.getMat();
     Mat BMat = B.getMat();
-    Mat kernelOneChannel = AMat * BMat;
+    Mat kernelOneChannel = BMat * AMat;
     std::vector<Mat> channels;
 
     for (int i = 0; i < chn; i++)

modules/fuzzy/test/test_image.cpp

@@ -102,11 +102,11 @@ TEST(fuzzy_image, kernel)
     Mat kernel1;
     ft::createKernel(ft::LINEAR, 2, kernel1, 1);
 
-    Mat vector1 = (Mat_<float>(5, 1) << 0, 0.5, 1, 0.5, 0);
-    Mat vector2 = (Mat_<float>(1, 5) << 0, 0.5, 1, 0.5, 0);
+    Mat vectorA = (Mat_<float>(1, 5) << 0, 0.5, 1, 0.5, 0);
+    Mat vectorB = (Mat_<float>(5, 1) << 0, 0.5, 1, 0.5, 0);
 
     Mat kernel2;
-    ft::createKernel(vector1, vector2, kernel2, 1);
+    ft::createKernel(vectorA, vectorB, kernel2, 1);
 
     double diff = cvtest::norm(kernel1, kernel2, NORM_INF);
 

modules/fuzzy/tutorials/filtering/filtering.markdown

@@ -0,0 +1,60 @@
+Filtering using F-transform {#tutorial_fuzzy_filtering}
+=============
+
+Goal
+====
+This tutorial demonstrates to you how to use F-transform for image filtering. You will see:
+
+-   basic theory behind,
+-   illustration of different settings.
+
+Fuzzy transform application
+====
+As I shown in previous tutorial, F-transform is a tool of fuzzy mathematics highly usable in image processing. Let me rewrite the formula using kernel \f$g\f$ introduced before as well:
+
+\f[
+    F^0_{kl}=\frac{\sum_{x=0}^{2h+1}\sum_{y=0}^{2h+1} \iota_{kl}(x,y) g(x,y)}{\sum_{x=0}^{2h+1}\sum_{y=0}^{2h+1} g(x,y)},
+\f]
+
+where \f$\iota_{kl} \subset I\f$ centered to pixel \f$(k \cdot h,l \cdot h)\f$ and \f$g\f$ is a kernel. More details can be found in related papers.
+
+Code
+====
+@include fuzzy/samples/fuzzy_filtering.cpp
+
+Explanation
+====
+Image filtering changes input in a defined way to enhance or simply change some concrete feature. Let me demonstrate some simple blur.
+
+As a first step, we load input image.
+
+@code{.cpp}
+    // Input image
+    Mat I = imread("input.png");
+@endcode
+
+Following the F-transform formula, we must specify a kernel.
+
+@code{.cpp}
+    // Kernel cretion
+    Mat kernel1, kernel2;
+
+    ft::createKernel(ft::LINEAR, 3, kernel1, 3);
+    ft::createKernel(ft::LINEAR, 100, kernel2, 3);
+@endcode
+
+> So now, we have two kernels that differ in `radius`. Bigger radius leads to bigger blur.
+
+The filtering itself is applied as shown below.
+
+@code{.cpp}
+    // Filtering
+    Mat output1, output2;
+
+    ft::filter(I, kernel1, output1);
+    ft::filter(I, kernel2, output2);
+@endcode
+
+Output images look as follows.
+
+![input, output1 (radius 3), output2 (radius 100)](images/fuzzy_filt_output.jpg)