Merge pull request #2113 from clunietp:quality-refactor

* Simplified quality API

* Compilation fixes

* test fixes

* Test updates

* Test fixes

* Fixed brisque data file location for install, test

* Increase error epsilon to account for multiple architectures

Author: clunietp

modules/quality/CMakeLists.txt

@@ -1,5 +1,9 @@
 set(the_description "Image Quality Analysis API")
 ocv_define_module(quality opencv_core opencv_imgproc opencv_ml WRAP python)
-ocv_add_testdata(samples/ contrib/quality
-    FILES_MATCHING PATTERN "*.yml"
-)
+
+# add test data from samples dir to contrib/quality
+ocv_add_testdata(samples/ contrib/quality FILES_MATCHING PATTERN "*.yml")
+
+# add brisque model, range files to installation
+file(GLOB QUALITY_MODEL_DATA samples/*.yml)
+install(FILES ${QUALITY_MODEL_DATA} DESTINATION ${OPENCV_OTHER_INSTALL_PATH}/quality COMPONENT libs)

modules/quality/README.md

@@ -46,14 +46,14 @@ Quick Start/Usage
 
 ```cpp
     #include <opencv2/quality.hpp>
-    cv::Mat img1, img2; /* your cv::Mat images */
-    std::vector<cv::Mat> quality_maps;  /* output quality map(s) (optional) */
+    cv::Mat img1, img2; /* your cv::Mat images to compare */
+    cv::Mat quality_map;  /* output quality map (optional) */
     /* compute MSE via static method */
-    cv::Scalar result_static = quality::QualityMSE::compute(img1, img2, quality_maps);  /* or cv::noArray() if not interested in output quality maps */
+    cv::Scalar result_static = quality::QualityMSE::compute(img1, img2, quality_map);  /* or cv::noArray() if not interested in output quality maps */
     /* alternatively, compute MSE via instance */
     cv::Ptr<quality::QualityBase> ptr = quality::QualityMSE::create(img1);
     cv::Scalar result = ptr->compute( img2 );  /* compute MSE, compare img1 vs img2 */
-    ptr->getQualityMaps(quality_maps);  /* optionally, access output quality maps */
+    ptr->getQualityMap(quality_map);  /* optionally, access output quality maps */
 ```
 
 **For No Reference IQA Algorithm (BRISQUE)**
@@ -81,11 +81,11 @@ model_path, range_path);
     img1 = cv2.imread(img1, 1) # specify img1
     img2 = cv2.imread(img2_path, 1) # specify img2_path
     # compute MSE score and quality maps via static method
-    result_static, quality_maps = cv2.quality.QualityMSE_compute(img1, img2)
+    result_static, quality_map = cv2.quality.QualityMSE_compute(img1, img2)
     # compute MSE score and quality maps via Instance
     obj = cv2.quality.QualityMSE_create(img1)
     result = obj.compute(img2)
-    quality_maps = obj.getQualityMaps()
+    quality_map = obj.getQualityMap()
 ```
 
 **For No Reference IQA Algorithm (BRISQUE)**
@@ -94,28 +94,26 @@ model_path, range_path);
     import cv2
     # read image
     img = cv2.imread(img_path, 1) # mention img_path
-    # make a list of image to be passed
-    img_list = [img]
     # compute brisque quality score via static method
-    score = cv2.quality.QualityBRISQUE_compute(img_list, model_path,
+    score = cv2.quality.QualityBRISQUE_compute(img, model_path,
 range_path) # specify model_path and range_path
     # compute brisque quality score via instance
     # specify model_path and range_path
     obj = cv2.quality.QualityBRISQUE_create(model_path, range_path)
-    score = obj.compute(img_list)
+    score = obj.compute(img)
 ```
 
 Library Design
 -----------------------------------------
 Each implemented algorithm shall:
 - Inherit from `QualityBase`, and properly implement/override `compute`, `empty` and `clear` instance methods, along with a static `compute` method.
-- Accept one or more `cv::Mat` or `cv::UMat` via `InputArrayOfArrays` for computation.  Each input `cv::Mat` or `cv::UMat` may contain one or more channels.  If the algorithm does not support multiple channels or multiple inputs, it should be documented and an appropriate assertion should be in place.
-- Return a `cv::Scalar` with per-channel computed value.  If multiple input images are provided, the resulting scalar should return the average result per channel.
+- Accept one `cv::Mat` or `cv::UMat` via `InputArray` for computation.  Each input `cv::Mat` or `cv::UMat` may contain one or more channels.  If the algorithm does not support multiple channels, it should be documented and an appropriate assertion should be in place.
+- Return a `cv::Scalar` with per-channel computed value
 - Compute result via a single, static method named `compute` and via an overridden instance method (see `compute` in `qualitybase.hpp`).
-- Perform any setup and/or pre-processing of reference images in the constructor, allowing for efficient computation when comparing the reference image(s) versus multiple comparison image(s).  No-reference algorithms should accept images for evaluation in the `compute` method.
-- Optionally compute resulting quality maps.  Instance `compute` method should store them in `QualityBase::_qualityMaps` as the mat type defined by `QualityBase::_quality_map_type`, or override `QualityBase::getQualityMaps`.  Static `compute` method should return them in an `OutputArrayOfArrays` parameter.
-- Document algorithm in this readme and in its respective header.  Documentation should include interpretation for the results of `compute` as well as the format of the output quality maps (if supported), along with any other notable usage information.
-- Implement tests of static `compute` method and instance methods using single- and multi-channel images, multi-frame images, and OpenCL enabled and disabled
+- Perform any setup and/or pre-processing of reference images in the constructor, allowing for efficient computation when comparing the reference image versus multiple comparison image(s).  No-reference algorithms should accept images for evaluation in the `compute` method.
+- Optionally compute resulting quality map.  Instance `compute` method should store them in `QualityBase::_qualityMap` as the mat type defined by `QualityBase::_mat_type`, or override `QualityBase::getQualityMap`.  Static `compute` method should return the quality map in an `OutputArray` parameter.
+- Document algorithm in this readme and in its respective header.  Documentation should include interpretation for the results of `compute` as well as the format of the output quality map (if supported), along with any other notable usage information.
+- Implement tests of static `compute` method and instance methods using single- and multi-channel images and OpenCL enabled and disabled
 
 To Do
 -----------------------------------------

modules/quality/include/opencv2/quality/quality_utils.hpp

@@ -5,7 +5,6 @@
 #ifndef OPENCV_QUALITY_QUALITY_UTILS_HPP
 #define OPENCV_QUALITY_QUALITY_UTILS_HPP
 
-#include <limits>   // numeric_limits
 #include "qualitybase.hpp"
 
 namespace cv
@@ -18,94 +17,44 @@ namespace quality_utils
 // default type of matrix to expand to
 static CV_CONSTEXPR const int EXPANDED_MAT_DEFAULT_TYPE = CV_32F;
 
-// convert input array to vector of specified mat types.  set type == -1 to preserve existing type
+// convert inputarray to specified mat type.  set type == -1 to preserve existing type
 template <typename R>
-inline std::vector<R> extract_mats( InputArrayOfArrays arr, const int type = -1 )
+inline R extract_mat(InputArray in, const int type = -1)
 {
-    std::vector<R> result = {};
-    std::vector<UMat> umats = {};
-    std::vector<Mat> mats = {};
-
-    if (arr.isUMatVector())
-        arr.getUMatVector(umats);
-    else if (arr.isUMat())
-        umats.emplace_back(arr.getUMat());
-    else if (arr.isMatVector())
-        arr.getMatVector(mats);
-    else if (arr.isMat())
-        mats.emplace_back(arr.getMat());
+    R result = {};
+    if ( in.isMat() )
+        in.getMat().convertTo( result, (type != -1) ? type : in.getMat().type());
+    else if ( in.isUMat() )
+        in.getUMat().convertTo( result, (type != -1) ? type : in.getUMat().type());
     else
         CV_Error(Error::StsNotImplemented, "Unsupported input type");
 
-    // convert umats, mats to desired type
-    for (auto& umat : umats)
-    {
-        result.emplace_back(R{});
-        umat.convertTo(result.back(), ( type != -1 ) ? type : umat.type() );
-    }
-
-    for (auto& mat : mats)
-    {
-        result.emplace_back(R{});
-        mat.convertTo(result.back(), (type != -1) ? type : mat.type() );
-    }
-
     return result;
 }
 
-// expand matrix to target type
-template <typename OutT, typename InT>
-inline OutT expand_mat(const InT& src, int TYPE_DEFAULT = EXPANDED_MAT_DEFAULT_TYPE)
+// extract and expand matrix to target type
+template <typename R>
+inline R expand_mat( InputArray src, int TYPE_DEFAULT = EXPANDED_MAT_DEFAULT_TYPE)
 {
-    OutT result = {};
+    auto result = extract_mat<R>(src, -1);
 
     // by default, expand to 32F unless we already have >= 32 bits, then go to 64
     //  if/when we can detect OpenCL CV_16F support, opt for that when input depth == 8
     //  note that this may impact the precision of the algorithms and would need testing
     int type = TYPE_DEFAULT;
 
-    switch (src.depth())
+    switch (result.depth())
     {
     case CV_32F:
     case CV_32S:
     case CV_64F:
         type = CV_64F;
     };  // switch
 
-    src.convertTo(result, type);
+    result.convertTo(result, type);
     return result;
 }
 
-// convert input array to vector of expanded mat types
-template <typename R>
-inline std::vector<R> expand_mats(InputArrayOfArrays arr, int TYPE_DEFAULT = EXPANDED_MAT_DEFAULT_TYPE)
-{
-    std::vector<R> result = {};
-
-    auto mats = extract_mats<R>(arr, -1);
-    for (auto& mat : mats)
-        result.emplace_back(expand_mat<R>(mat, TYPE_DEFAULT));
-
-    return result;
-}
-
-// convert mse to psnr
-inline double mse_to_psnr(double mse, double max_pixel_value)
-{
-    return (mse == 0.)
-        ? std::numeric_limits<double>::infinity()
-        : 10. * std::log10((max_pixel_value * max_pixel_value) / mse)
-        ;
-}
-
-// convert scalar of mses to psnrs
-inline cv::Scalar mse_to_psnr(cv::Scalar mse, double max_pixel_value)
-{
-    for (int i = 0; i < mse.rows; ++i)
-        mse(i) = mse_to_psnr(mse(i), max_pixel_value);
-    return mse;
-}
-
 // return mat of observed min/max pair per column
 //  row 0:  min per column
 //  row 1:  max per column

modules/quality/include/opencv2/quality/qualitybase.hpp

@@ -5,7 +5,6 @@
 #ifndef OPENCV_QUALITYBASE_HPP
 #define OPENCV_QUALITYBASE_HPP
 
-#include <vector>
 #include <opencv2/core.hpp>
 
 /**
@@ -21,7 +20,6 @@ namespace quality
 //! @{
 
 /************************************ Quality Base Class ************************************/
-
 class CV_EXPORTS_W QualityBase
     : public virtual Algorithm
 {
@@ -32,34 +30,31 @@ class CV_EXPORTS_W QualityBase
 
     /**
     @brief Compute quality score per channel with the per-channel score in each element of the resulting cv::Scalar.  See specific algorithm for interpreting result scores
-    @param cmpImgs comparison image(s), or image(s) to evalute for no-reference quality algorithms
+    @param img comparison image, or image to evalute for no-reference quality algorithms
     */
-    virtual CV_WRAP cv::Scalar compute( InputArrayOfArrays cmpImgs ) = 0;
+    virtual CV_WRAP cv::Scalar compute( InputArray img ) = 0;
 
-    /** @brief Returns output quality map images that were generated during computation, if supported by the algorithm  */
-    virtual CV_WRAP void getQualityMaps(OutputArrayOfArrays dst) const
+    /** @brief Returns output quality map that was generated during computation, if supported by the algorithm  */
+    virtual CV_WRAP void getQualityMap(OutputArray dst) const
     {
-        if (!dst.needed() || _qualityMaps.empty() )
+        if (!dst.needed() || _qualityMap.empty() )
             return;
-
-        auto qMaps = InputArray(_qualityMaps);
-        dst.create(qMaps.size(), qMaps.type());
-        dst.assign(_qualityMaps);
+        dst.assign(_qualityMap);
     }
 
     /** @brief Implements Algorithm::clear()  */
-    CV_WRAP void clear() CV_OVERRIDE { _qualityMaps.clear(); Algorithm::clear(); }
+    CV_WRAP void clear() CV_OVERRIDE { _qualityMap = _mat_type(); Algorithm::clear(); }
 
     /** @brief Implements Algorithm::empty()  */
-    CV_WRAP bool empty() const CV_OVERRIDE { return _qualityMaps.empty(); }
+    CV_WRAP bool empty() const CV_OVERRIDE { return _qualityMap.empty(); }
 
 protected:
 
-    /** @brief internal quality map type default */
-    using _quality_map_type = cv::UMat;
+    /** @brief internal mat type default */
+    using _mat_type = cv::UMat;
 
     /** @brief Output quality maps if generated by algorithm */
-    std::vector<_quality_map_type> _qualityMaps;
+    _mat_type _qualityMap;
 
 };  // QualityBase
 //! @}

modules/quality/include/opencv2/quality/qualitybrisque.hpp

@@ -26,19 +26,18 @@ C++ code for the BRISQUE LIVE-R2 trainer and TID2008 evaluator are also provided
 class CV_EXPORTS_W QualityBRISQUE : public QualityBase {
 public:
 
-    /** @brief Computes BRISQUE quality score for input images
-    @param imgs Images for which to compute quality (should be passed as a vector<Mat> in C++ and list of images in Python)
-    @returns Score (averaged over individual scores of all images) ranging from 0 to 100
-    (0 denotes the best quality and 100 denotes the worst quality). The format of the score is: {score, 0., 0., 0.}
+    /** @brief Computes BRISQUE quality score for input image
+    @param img Image for which to compute quality
+    @returns cv::Scalar with the score in the first element.  The score ranges from 0 (best quality) to 100 (worst quality)
     */
-    CV_WRAP cv::Scalar compute( InputArrayOfArrays imgs ) CV_OVERRIDE;
+    CV_WRAP cv::Scalar compute( InputArray img ) CV_OVERRIDE;
 
     /**
     @brief Create an object which calculates quality
-    @param model_file_path cv::String which contains a path to the BRISQUE model data.  If empty, attempts to load from ${OPENCV_DIR}/testdata/contrib/quality/brisque_model_live.yml
-    @param range_file_path cv::String which contains a path to the BRISQUE range data.  If empty, attempts to load from ${OPENCV_DIR}/testdata/contrib/quality/brisque_range_live.yml
+    @param model_file_path cv::String which contains a path to the BRISQUE model data, eg. /path/to/brisque_model_live.yml
+    @param range_file_path cv::String which contains a path to the BRISQUE range data, eg. /path/to/brisque_range_live.yml
     */
-    CV_WRAP static Ptr<QualityBRISQUE> create( const cv::String& model_file_path = "", const cv::String& range_file_path = "" );
+    CV_WRAP static Ptr<QualityBRISQUE> create( const cv::String& model_file_path, const cv::String& range_file_path );
 
     /**
     @brief Create an object which calculates quality
@@ -49,12 +48,12 @@ class CV_EXPORTS_W QualityBRISQUE : public QualityBase {
 
     /**
     @brief static method for computing quality
-    @param imgs image(s) for which to compute quality (passed as Mat or vector<Mat> in C++ and as list of images in Python)
-    @param model_file_path cv::String which contains a path to the BRISQUE model data.  If empty, attempts to load from ${OPENCV_DIR}/testdata/contrib/quality/brisque_model_live.yml
-    @param range_file_path cv::String which contains a path to the BRISQUE range data.  If empty, attempts to load from ${OPENCV_DIR}/testdata/contrib/quality/brisque_range_live.yml
-    @returns cv::Scalar result of format {std::double score, 0., 0., 0.}. Score ranges from 0 to 100 (100 means worst and 0 means best)
+    @param img image for which to compute quality
+    @param model_file_path cv::String which contains a path to the BRISQUE model data, eg. /path/to/brisque_model_live.yml
+    @param range_file_path cv::String which contains a path to the BRISQUE range data, eg. /path/to/brisque_range_live.yml
+    @returns cv::Scalar with the score in the first element.  The score ranges from 0 (best quality) to 100 (worst quality)
     */
-    CV_WRAP static cv::Scalar compute( InputArrayOfArrays imgs, const cv::String& model_file_path, const cv::String& range_file_path );
+    CV_WRAP static cv::Scalar compute( InputArray img, const cv::String& model_file_path, const cv::String& range_file_path );
 
     /**
     @brief static method for computing image features used by the BRISQUE algorithm

modules/quality/include/opencv2/quality/qualitygmsd.hpp

@@ -22,65 +22,67 @@ class CV_EXPORTS_W QualityGMSD
 
     /**
     @brief Compute GMSD
-    @param cmpImgs Comparison images
-    @returns Per-channel GMSD
+    @param cmp comparison image
+    @returns cv::Scalar with per-channel quality value.  Values range from 0 (worst) to 1 (best)
     */
-    CV_WRAP cv::Scalar compute(InputArrayOfArrays cmpImgs) CV_OVERRIDE;
+    CV_WRAP cv::Scalar compute( InputArray cmp ) CV_OVERRIDE;
 
     /** @brief Implements Algorithm::empty()  */
     CV_WRAP bool empty() const CV_OVERRIDE { return _refImgData.empty() && QualityBase::empty(); }
 
     /** @brief Implements Algorithm::clear()  */
-    CV_WRAP void clear() CV_OVERRIDE { _refImgData.clear(); QualityBase::clear(); }
+    CV_WRAP void clear() CV_OVERRIDE { _refImgData = _mat_data(); QualityBase::clear(); }
 
     /**
     @brief Create an object which calculates image quality
-    @param refImgs input image(s) to use as the source for comparison
+    @param ref reference image
     */
-    CV_WRAP static Ptr<QualityGMSD> create(InputArrayOfArrays refImgs);
+    CV_WRAP static Ptr<QualityGMSD> create( InputArray ref );
 
     /**
     @brief static method for computing quality
-    @param refImgs reference image(s)
-    @param cmpImgs comparison image(s)
-    @param qualityMaps output quality map(s), or cv::noArray()
+    @param ref reference image
+    @param cmp comparison image
+    @param qualityMap output quality map, or cv::noArray()
     @returns cv::Scalar with per-channel quality value.  Values range from 0 (worst) to 1 (best)
     */
-    CV_WRAP static cv::Scalar compute(InputArrayOfArrays refImgs, InputArrayOfArrays cmpImgs, OutputArrayOfArrays qualityMaps);
+    CV_WRAP static cv::Scalar compute( InputArray ref, InputArray cmp, OutputArray qualityMap );
 
 protected:
 
-    // holds computed values for an input mat
+    // holds computed values for a mat
     struct _mat_data
     {
-        using mat_type = QualityBase::_quality_map_type;
+        // internal mat type
+        using mat_type = QualityBase::_mat_type;
 
         mat_type
             gradient_map
             , gradient_map_squared
             ;
 
+        // allow default construction
+        _mat_data() = default;
+
+        // construct from mat_type
         _mat_data(const mat_type&);
 
-        // converts mat/umat to vector of mat_data
-        static std::vector<_mat_data> create(InputArrayOfArrays arr);
+        // construct from inputarray
+        _mat_data(InputArray);
+
+        // returns flag if empty
+        bool empty() const { return this->gradient_map.empty() && this->gradient_map_squared.empty(); }
 
         // compute for a single frame
         static std::pair<cv::Scalar, mat_type> compute(const _mat_data& lhs, const _mat_data& rhs);
 
-        // compute for vector of inputs
-        static cv::Scalar compute(const std::vector<_mat_data>& lhs, const std::vector<_mat_data>& rhs, OutputArrayOfArrays qualityMaps);
-
     };  // mat_data
 
     /** @brief Reference image data */
-    std::vector<_mat_data> _refImgData;
+    _mat_data _refImgData;
 
-    /**
-    @brief Constructor
-    @param refImgData vector of reference images, converted to internal type
-    */
-    QualityGMSD(std::vector<_mat_data> refImgData)
+    // internal constructor
+    QualityGMSD(_mat_data refImgData)
         : _refImgData(std::move(refImgData))
     {}