Merge pull request #2729 from sunitanyk:master

Added Python wrapping and documentation for alphamat module

* updated documentation with more results for alphamat module

* Updated the image links in the tutorial

* Included cite

modules/alphamat/CMakeLists.txt

@@ -6,4 +6,5 @@ endif()
 ocv_define_module(alphamat
     opencv_core
     opencv_imgproc
+    WRAP python
 )

modules/alphamat/README.md

@@ -7,12 +7,12 @@ This project was part of the Google Summer of Code 2019.
 ***
 Alphamatting is the problem of extracting the foreground from an image. Given the input of an image and its corresponding trimap, we try to extract the foreground from the background.
 
-This project is implementation of "[[Designing Effective Inter-Pixel Information Flow for Natural Image Matting](http://people.inf.ethz.ch/aksoyy/ifm/)]" by Yağız Aksoy, Tunç Ozan Aydın and Marc Pollefeys[1]. It required implementation of parts of other papers [2,3,4].
+This project is implementation of "[Designing Effective Inter-Pixel Information Flow for Natural Image Matting](https://www.researchgate.net/publication/318489370_Designing_Effective_Inter-Pixel_Information_Flow_for_Natural_Image_Matting)" by Yağız Aksoy, Tunç Ozan Aydın and Marc Pollefeys[1]. It required implementation of parts of other papers [2,3,4].
 
 
 ## References
 
-[1] Yagiz Aksoy, Tunc Ozan Aydin, Marc Pollefeys, "[Designing Effective Inter-Pixel Information Flow for Natural Image Matting](http://people.inf.ethz.ch/aksoyy/ifm/)", CVPR, 2017.
+[1] Yagiz Aksoy, Tunc Ozan Aydin, Marc Pollefeys, "[Designing Effective Inter-Pixel Information Flow for Natural Image Matting](https://www.researchgate.net/publication/318489370_Designing_Effective_Inter-Pixel_Information_Flow_for_Natural_Image_Matting)", CVPR, 2017.
 
 [2] Roweis, Sam T., and Lawrence K. Saul. "[Nonlinear dimensionality reduction by locally linear embedding](https://science.sciencemag.org/content/290/5500/2323)" Science 290.5500 (2000): 2323-2326.
 

modules/alphamat/include/opencv2/alphamat.hpp

@@ -9,19 +9,28 @@
 
 /**
  * @defgroup alphamat Alpha Matting
- * This module is dedicated to compute alpha matting of images, given the input image and an input trimap.
- * The samples directory includes easy examples of how to use the module.
+ * Alpha matting is used to extract a foreground object with soft boundaries from a background image.
+ *
+ * This module is dedicated to computing alpha matte of objects in images from a given input image and a greyscale trimap image that contains information about the foreground, background and unknown pixels. The unknown pixels are assumed to be a combination of foreground and background pixels. The algorithm uses a combination of multiple carefully defined pixels affinities to estimate the opacity of the foreground pixels in the unkown region.
+ *
+ * The implementation is based on @cite aksoy2017designing.
+ *
+ * This module was developed by Muskaan Kularia and Sunita Nayak as a project
+ * for Google Summer of Code 2019 (GSoC 19).
+ *
  */
 
 namespace cv { namespace alphamat {
 //! @addtogroup alphamat
 //! @{
 
 /**
- * The implementation is based on Designing Effective Inter-Pixel Information Flow for Natural Image Matting by Yağız Aksoy, Tunç Ozan Aydın and Marc Pollefeys, CVPR 2019.
+ * @brief Compute alpha matte of an object in an image
+ * @param image Input RGB image
+ * @param tmap Input greyscale trimap image
+ * @param result Output alpha matte image
  *
- * This module has been originally developed by Muskaan Kularia and Sunita Nayak as a project
- * for Google Summer of Code 2019 (GSoC 19).
+ * The function infoFlow performs alpha matting on a RGB image using a greyscale trimap image, and outputs a greyscale alpha matte image. The output alpha matte can be used to softly extract the foreground object from a background image. Examples can be found in the samples directory.
  *
  */
 CV_EXPORTS_W void infoFlow(InputArray image, InputArray tmap, OutputArray result);

modules/alphamat/samples/information_flow_matting.cpp

@@ -2,16 +2,19 @@
 // It is subject to the license terms in the LICENSE file found in the top-level directory
 // of this distribution and at http://opencv.org/license.html.
 
+// Include relevant headers
 #include <iostream>
 #include "opencv2/highgui.hpp"
 #include <opencv2/core.hpp>
 #include <opencv2/imgproc.hpp>
 #include <opencv2/alphamat.hpp>
 
+// Set namespaces
 using namespace std;
 using namespace cv;
 using namespace cv::alphamat;
 
+// Set the usage parameter names
 const char* keys =
     "{img || input image name}"
     "{tri || input trimap image name}"
@@ -30,10 +33,12 @@ int main(int argc, char* argv[])
         return 0;
     }
 
+    // Read the paths to the input image, input trimap and the location of the output image.
     string img_path = parser.get<std::string>("img");
     string trimap_path = parser.get<std::string>("tri");
     string result_path = parser.get<std::string>("out");
 
+    // Make sure the user inputs paths to the input image and trimap
     if (!parser.check()
             || img_path.empty() || trimap_path.empty())
     {
@@ -44,13 +49,15 @@ int main(int argc, char* argv[])
 
     Mat image, tmap;
 
-    image = imread(img_path, IMREAD_COLOR);  // Read the input image file
+    // Read the input image
+    image = imread(img_path, IMREAD_COLOR);
     if (image.empty())
     {
         printf("Cannot read image file: '%s'\n", img_path.c_str());
         return 1;
     }
 
+    // Read the trimap
     tmap = imread(trimap_path, IMREAD_GRAYSCALE);
     if (tmap.empty())
     {
@@ -59,16 +66,19 @@ int main(int argc, char* argv[])
     }
 
     Mat result;
+    // Perform information flow alpha matting
     infoFlow(image, tmap, result);
 
     if (result_path.empty())
     {
+        // Show the alpha matte if a result filepath is not provided.
         namedWindow("result alpha matte", WINDOW_NORMAL);
         imshow("result alpha matte", result);
         waitKey(0);
     }
     else
     {
+        // Save the alphamatte
         imwrite(result_path, result);
         printf("Result saved: '%s'\n", result_path.c_str());
     }

modules/alphamat/tutorials/alphamat_tutorial.markdown

@@ -7,15 +7,26 @@ This project was part of Google Summer of Code 2019.
 
 *Mentor:* Sunita Nayak
 
-Alphamatting is the problem of extracting the foreground from an image. The extracted foreground can be used for further operations like changing the background in an image.
+Alphamatting is the problem of extracting the foreground with soft boundaries from a background image. The extracted foreground can be used for further operations like changing the background in an image.
 
 Given an input image and its corresponding trimap, we try to extract the foreground from the background. Following is an example:
 
-Input Image: ![](samples/input_images/plant.jpg)
-Input Trimap: ![](samples/trimaps/plant.png)
-Output alpha Matte: ![](samples/output_mattes/plant_result.jpg)
+Input Image: ![](alphamat/samples/input_images/plant.jpg)
+Input image should be preferably a RGB image.
 
-This project is implementation of @cite aksoy2017designing . It required implementation of parts of other papers [2,3,4].
+Input Trimap: ![](alphamat/samples/trimaps/plant.png)
+The trimap image is a greyscale image that contains information about the foreground(white pixels), background(black pixels) and unknown(grey) pixels.
+
+Output alpha Matte: ![](alphamat/samples/output_mattes/plant_result.png)
+The computed alpha matte is saved as a greyscale image where the pixel values indicate the opacity of the extracted foreground object. These opacity values can be used to blend the foreground object into a diffferent backgound, as shown below:
+![](plant_new_backgrounds.jpg)
+
+Following are some more results.
+![](matting_results.jpg)
+
+The first column is input RGB image, the second column is input trimap, third column is the extracted alpha matte and the last two columns show the foreground object blended on new backgrounds.
+
+This project is implementation of @cite aksoy2017designing . It also required implementation of parts of other papers [2,3,4].
 
 # Building
 
@@ -33,21 +44,20 @@ Please refer to OpenCV building tutorials for further details, if needed.
 
 The built target can be tested as follows:
 ```
-example_alphamat_information_flow_matting -img=<path to input image file> -tri=<path to the corresponding trimap> -out=<path to save output matte file>
+<path to your opencv build directory>/bin/example_alphamat_information_flow_matting -img=<path to input image file> -tri=<path to the corresponding trimap> -out=<path to save output matte file>
 ```
 # Source Code of the sample
 
 @includelineno alphamat/samples/information_flow_matting.cpp
 
-
 # References
 
-[1] Yagiz Aksoy, Tunc Ozan Aydin, Marc Pollefeys, "[Designing Effective Inter-Pixel Information Flow for Natural Image Matting](http://people.inf.ethz.ch/aksoyy/ifm/)", CVPR, 2017.
+[1] Yagiz Aksoy, Tunc Ozan Aydin, Marc Pollefeys, [Designing Effective Inter-Pixel Information Flow for Natural Image Matting](https://www.researchgate.net/publication/318489370_Designing_Effective_Inter-Pixel_Information_Flow_for_Natural_Image_Matting), CVPR, 2017.
 
-[2] Roweis, Sam T., and Lawrence K. Saul. "[Nonlinear dimensionality reduction by locally linear embedding](https://science.sciencemag.org/content/290/5500/2323)" Science 290.5500 (2000): 2323-2326.
+[2] Roweis, Sam T., and Lawrence K. Saul. [Nonlinear dimensionality reduction by locally linear embedding](https://science.sciencemag.org/content/290/5500/2323), Science 290.5500 (2000): 2323-2326.
 
-[3] Anat Levin, Dani Lischinski, Yair Weiss, "[A Closed Form Solution to Natural Image Matting](https://www.researchgate.net/publication/5764820_A_Closed-Form_Solution_to_Natural_Image_Matting)", IEEE TPAMI, 2008.
+[3] Anat Levin, Dani Lischinski, Yair Weiss, [A Closed Form Solution to Natural Image Matting](https://www.researchgate.net/publication/5764820_A_Closed-Form_Solution_to_Natural_Image_Matting), IEEE TPAMI, 2008.
 
-[4] Qifeng Chen, Dingzeyu Li, Chi-Keung Tang, "[KNN Matting](http://dingzeyu.li/files/knn-matting-tpami.pdf)", IEEE TPAMI, 2013.
+[4] Qifeng Chen, Dingzeyu Li, Chi-Keung Tang, [KNN Matting](http://dingzeyu.li/files/knn-matting-tpami.pdf), IEEE TPAMI, 2013.
 
-[5] Yagiz Aksoy, "[Affinity Based Matting Toolbox](https://github.com/yaksoy/AffinityBasedMattingToolbox)".
+[5] Yagiz Aksoy, [Affinity Based Matting Toolbox](https://github.com/yaksoy/AffinityBasedMattingToolbox).