Auto color balance improvements

Implemented a learning-based color balance algorithm, which typically provides
noticeably better quality than grayworld, while being several times slower.
Added a python script for training this algorithm, as well as the benchmarking script
for objective quality evaluation.

Also made some modifications to the grayworld algorithm implementation, including the
16 bit image support and overall acceleration by about 1.7 times (for 8 bit images).

modules/xphoto/doc/xphoto.bib

@@ -6,3 +6,11 @@
   year={2012},
   publisher={Springer}
 }
+
+@inproceedings{Cheng2015,
+  title={Effective learning-based illuminant estimation using simple features},
+  author={Cheng, Dongliang and Price, Brian and Cohen, Scott and Brown, Michael S},
+  booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition},
+  pages={1000--1008},
+  year={2015}
+}

modules/xphoto/include/opencv2/xphoto/white_balance.hpp

@@ -105,7 +105,7 @@ namespace xphoto
     threshold of 0 means no pixels are used. Lower thresholds are useful in
     white-balancing saturated images.
 
-    Currently only works on images of type @ref CV_8UC3.
+    Currently only works on images of type @ref CV_8UC3 and @ref CV_16UC3.
 
     @param src Input array.
     @param dst Output array of the same size and type as src.
@@ -117,7 +117,69 @@ namespace xphoto
     CV_EXPORTS_W void autowbGrayworld(InputArray src, OutputArray dst,
         float thresh = 0.5f);
 
-//! @}
+    /** @brief Implements a more sophisticated learning-based automatic color balance algorithm.
+
+    As autowbGrayworld, this function works by applying different gains to the input
+    image channels, but their computation is a bit more involved compared to the
+    simple grayworld assumption. More details about the algorithm can be found in
+    @cite Cheng2015 .
+
+    To mask out saturated pixels this function uses only pixels that satisfy the
+    following condition:
+
+    \f[ \frac{\textrm{max}(R,G,B)}{\texttt{range_max_val}} < \texttt{saturation_thresh} \f]
+
+    Currently supports images of type @ref CV_8UC3 and @ref CV_16UC3.
+
+    @param src Input three-channel image in the BGR color space.
+    @param dst Output image of the same size and type as src.
+    @param range_max_val Maximum possible value of the input image (e.g. 255 for 8 bit images, 4095 for 12 bit images)
+    @param saturation_thresh Threshold that is used to determine saturated pixels
+    @param hist_bin_num Defines the size of one dimension of a three-dimensional RGB histogram that is used internally by
+    the algorithm. It often makes sense to increase the number of bins for images with higher bit depth (e.g. 256 bins
+    for a 12 bit image)
+
+    @sa autowbGrayworld
+    */
+    CV_EXPORTS_W void autowbLearningBased(InputArray src, OutputArray dst, int range_max_val = 255,
+                                          float saturation_thresh = 0.98f, int hist_bin_num = 64);
+
+    /** @brief Implements the feature extraction part of the learning-based color balance algorithm.
+
+    In accordance with @cite Cheng2015 , computes the following features for the input image:
+    1. Chromaticity of an average (R,G,B) tuple
+    2. Chromaticity of the brightest (R,G,B) tuple (while ignoring saturated pixels)
+    3. Chromaticity of the dominant (R,G,B) tuple (the one that has the highest value in the RGB histogram)
+    4. Mode of the chromaticity pallete, that is constructed by taking 300 most common colors according to
+       the RGB histogram and projecting them on the chromaticity plane. Mode is the most high-density point
+       of the pallete, which is computed by a straightforward fixed-bandwidth kernel density estimator with
+       a Epanechnikov kernel function.
+
+    @param src Input three-channel image in the BGR color space.
+    @param dst An array of four (r,g) chromaticity tuples corresponding to the features listed above.
+    @param range_max_val Maximum possible value of the input image (e.g. 255 for 8 bit images, 4095 for 12 bit images)
+    @param saturation_thresh Threshold that is used to determine saturated pixels
+    @param hist_bin_num Defines the size of one dimension of a three-dimensional RGB histogram that is used internally by
+    the algorithm. It often makes sense to increase the number of bins for images with higher bit depth (e.g. 256 bins
+    for a 12 bit image)
+
+    @sa autowbLearningBased
+    */
+    CV_EXPORTS_W void extractSimpleFeatures(InputArray src, OutputArray dst, int range_max_val = 255,
+                                            float saturation_thresh = 0.98f, int hist_bin_num = 64);
+
+    /** @brief Implements an efficient fixed-point approximation for applying channel gains.
+
+    @param src Input three-channel image in the BGR color space (either CV_8UC3 or CV_16UC3)
+    @param dst Output image of the same size and type as src.
+    @param gainB gain for the B channel
+    @param gainG gain for the G channel
+    @param gainR gain for the R channel
+
+    @sa autowbGrayworld, autowbLearningBased
+    */
+    CV_EXPORTS_W void applyChannelGains(InputArray src, OutputArray dst, float gainB, float gainG, float gainR);
+    //! @}
 
 }
 }

modules/xphoto/perf/perf_learning_based_color_balance.cpp

+/*
+*  By downloading, copying, installing or using the software you agree to this license.
+*  If you do not agree to this license, do not download, install,
+*  copy or use the software.
+*
+*
+*  License Agreement
+*  For Open Source Computer Vision Library
+*  (3 - clause BSD License)
+*
+*  Redistribution and use in source and binary forms, with or without modification,
+*  are permitted provided that the following conditions are met :
+*
+*  *Redistributions of source code must retain the above copyright notice,
+*  this list of conditions and the following disclaimer.
+*
+*  * Redistributions in binary form must reproduce the above copyright notice,
+*  this list of conditions and the following disclaimer in the documentation
+*  and / or other materials provided with the distribution.
+*
+*  * Neither the names of the copyright holders nor the names of the contributors
+*  may be used to endorse or promote products derived from this software
+*  without specific prior written permission.
+*
+*  This software is provided by the copyright holders and contributors "as is" and
+*  any express or implied warranties, including, but not limited to, the implied
+*  warranties of merchantability and fitness for a particular purpose are disclaimed.
+*  In no event shall copyright holders or contributors be liable for any direct,
+*  indirect, incidental, special, exemplary, or consequential damages
+*  (including, but not limited to, procurement of substitute goods or services;
+*  loss of use, data, or profits; or business interruption) however caused
+*  and on any theory of liability, whether in contract, strict liability,
+*  or tort(including negligence or otherwise) arising in any way out of
+*  the use of this software, even if advised of the possibility of such damage.
+*/
+
+#include "perf_precomp.hpp"
+#include "opencv2/imgproc.hpp"
+
+using std::tr1::tuple;
+using std::tr1::get;
+using namespace std;
+using namespace cv;
+using namespace perf;
+using namespace testing;
+
+typedef tuple<Size, MatType> learningBasedWBParams;
+typedef TestBaseWithParam<learningBasedWBParams> learningBasedWBPerfTest;
+
+PERF_TEST_P(learningBasedWBPerfTest, perf, Combine(SZ_ALL_HD, Values(CV_8UC3, CV_16UC3)))
+{
+    Size size = get<0>(GetParam());
+    MatType t = get<1>(GetParam());
+    Mat src(size, t);
+    Mat dst(size, t);
+
+    int range_max_val = 255, hist_bin_num = 64;
+    if (t == CV_16UC3)
+    {
+        range_max_val = 65535;
+        hist_bin_num = 256;
+    }
+
+    Mat src_dscl(Size(size.width / 16, size.height / 16), t);
+    RNG rng(1234);
+    rng.fill(src_dscl, RNG::UNIFORM, 0, range_max_val);
+    resize(src_dscl, src, src.size());
+
+    TEST_CYCLE() xphoto::autowbLearningBased(src, dst, range_max_val, 0.98f, hist_bin_num);
+
+    SANITY_CHECK_NOTHING();
+}

modules/xphoto/samples/learning_based_color_balance.cpp

+#include "opencv2/xphoto.hpp"
+#include "opencv2/highgui.hpp"
+
+using namespace cv;
+using namespace std;
+
+const char *keys = {"{help h usage ? |      | print this message}"
+                    "{i              |      | input image name  }"
+                    "{o              |      | output image name }"};
+
+int main(int argc, const char **argv)
+{
+    CommandLineParser parser(argc, argv, keys);
+    parser.about("OpenCV learning-based color balance demonstration sample");
+    if (parser.has("help") || argc < 2)
+    {
+        parser.printMessage();
+        return 0;
+    }
+
+    string inFilename = parser.get<string>("i");
+    string outFilename = parser.get<string>("o");
+
+    if (!parser.check())
+    {
+        parser.printErrors();
+        return -1;
+    }
+
+    Mat src = imread(inFilename, 1);
+    if (src.empty())
+    {
+        printf("Cannot read image file: %s\n", inFilename.c_str());
+        return -1;
+    }
+
+    Mat res;
+    xphoto::autowbLearningBased(src, res);
+
+    if (outFilename == "")
+    {
+        namedWindow("after white balance", 1);
+        imshow("after white balance", res);
+
+        waitKey(0);
+    }
+    else
+        imwrite(outFilename, res);
+
+    return 0;
+}

modules/xphoto/test/test_grayworld.cpp

@@ -81,7 +81,13 @@ namespace cvtest {
 
             Mat currentResult;
             xphoto::autowbGrayworld(src, currentResult, wb_thresh);
+            ASSERT_LE(cv::norm(currentResult, referenceResult, NORM_INF), acc_thresh);
 
+            // test the 16-bit depth:
+            Mat currentResult_16U, src_16U;
+            src.convertTo(src_16U, CV_16UC3, 256.0);
+            xphoto::autowbGrayworld(src_16U, currentResult_16U, wb_thresh);
+            currentResult_16U.convertTo(currentResult, CV_8UC3, 1/256.0);
             ASSERT_LE(cv::norm(currentResult, referenceResult, NORM_INF), acc_thresh);
         }
     }

modules/xphoto/test/test_learning_based_color_balance.cpp

+#include "test_precomp.hpp"
+using namespace cv;
+namespace cvtest
+{
+TEST(xphoto_simplefeatures, regression)
+{
+    float acc_thresh = 0.01f;
+
+    // Generate a test image:
+    Mat test_im(1000, 1000, CV_8UC3);
+    RNG rng(1234);
+    rng.fill(test_im, RNG::NORMAL, Scalar(64, 100, 128), Scalar(10, 10, 10));
+    threshold(test_im, test_im, 200.0, 255.0, THRESH_TRUNC);
+    test_im.at<Vec3b>(0, 0) = Vec3b(240, 220, 200);
+
+    // Which should have the following features:
+    Vec2f ref1(128.0f / (64 + 100 + 128), 100.0f / (64 + 100 + 128));
+    Vec2f ref2(200.0f / (240 + 220 + 200), 220.0f / (240 + 220 + 200));
+
+    vector<Vec2f> dst_features;
+    xphoto::extractSimpleFeatures(test_im, dst_features, 255, 0.98f, 64);
+    ASSERT_LE(cv::norm(dst_features[0], ref1, NORM_INF), acc_thresh);
+    ASSERT_LE(cv::norm(dst_features[1], ref2, NORM_INF), acc_thresh);
+    ASSERT_LE(cv::norm(dst_features[2], ref1, NORM_INF), acc_thresh);
+    ASSERT_LE(cv::norm(dst_features[3], ref1, NORM_INF), acc_thresh);
+
+    // check 16 bit depth:
+    test_im.convertTo(test_im, CV_16U, 256.0);
+    xphoto::extractSimpleFeatures(test_im, dst_features, 65535, 0.98f, 64);
+    ASSERT_LE(cv::norm(dst_features[0], ref1, NORM_INF), acc_thresh);
+    ASSERT_LE(cv::norm(dst_features[1], ref2, NORM_INF), acc_thresh);
+    ASSERT_LE(cv::norm(dst_features[2], ref1, NORM_INF), acc_thresh);
+    ASSERT_LE(cv::norm(dst_features[3], ref1, NORM_INF), acc_thresh);
+}
+}