Merge pull request #26842 from chacha21:threshold_with_mask

Added optional mask to cv::threshold #26842
 
Proposal for #26777

To avoid code duplication, and keep performance when no mask is used, inner implementation always propagate the const cv::Mat& mask, but they use a template<bool useMask> parameter that let the compiler optimize out unnecessary tests when the mask is not to be used.

See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request

- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [X] The PR is proposed to the proper branch
- [X] There is a reference to the original bug report and related work
- [X] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
      Patch to opencv_extra has the same branch name.
- [ ] The feature is well documented and sample code can be built with the project CMake

modules/imgproc/include/opencv2/imgproc.hpp

@@ -3081,11 +3081,30 @@ types.
 @param type thresholding type (see #ThresholdTypes).
 @return the computed threshold value if Otsu's or Triangle methods used.
 
-@sa  adaptiveThreshold, findContours, compare, min, max
+@sa  thresholdWithMask, adaptiveThreshold, findContours, compare, min, max
  */
 CV_EXPORTS_W double threshold( InputArray src, OutputArray dst,
                                double thresh, double maxval, int type );
 
+/** @brief Same as #threshold, but with an optional mask
+
+@note If the mask is empty, #thresholdWithMask is equivalent to #threshold.
+If the mask is not empty, dst *must* be of the same size and type as src, so that
+outliers pixels are left as-is
+
+@param src input array (multiple-channel, 8-bit or 32-bit floating point).
+@param dst output array of the same size  and type and the same number of channels as src.
+@param mask optional mask (same size as src, 8-bit).
+@param thresh threshold value.
+@param maxval maximum value to use with the #THRESH_BINARY and #THRESH_BINARY_INV thresholding
+types.
+@param type thresholding type (see #ThresholdTypes).
+@return the computed threshold value if Otsu's or Triangle methods used.
+
+@sa  threshold, adaptiveThreshold, findContours, compare, min, max
+*/
+CV_EXPORTS_W double thresholdWithMask( InputArray src, InputOutputArray dst, InputArray mask,
+                                       double thresh, double maxval, int type );
 
 /** @brief Applies an adaptive threshold to an array.
 

modules/imgproc/src/opencl/threshold_mask.cl

@@ -0,0 +1,60 @@
+// This file is part of OpenCV project.
+// 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.
+// @Authors
+//    Zhang Ying, zhangying913@gmail.com
+//    Pierre Chatelier, pierre@chachatelier.fr
+
+#ifdef DOUBLE_SUPPORT
+#ifdef cl_amd_fp64
+#pragma OPENCL EXTENSION cl_amd_fp64:enable
+#elif defined (cl_khr_fp64)
+#pragma OPENCL EXTENSION cl_khr_fp64:enable
+#endif
+#endif
+
+__kernel void threshold_mask(__global const uchar * srcptr, int src_step, int src_offset,
+                             __global uchar * dstptr, int dst_step, int dst_offset, int rows, int cols,
+                             __global const uchar * maskptr, int mask_step, int mask_offset,
+                             T1 thresh, T1 max_val, T1 min_val)
+{
+    int gx = get_global_id(0);
+    int gy = get_global_id(1) * STRIDE_SIZE;
+
+    if (gx < cols)
+    {
+        int src_index = mad24(gy, src_step, mad24(gx, (int)sizeof(T), src_offset));
+        int dst_index = mad24(gy, dst_step, mad24(gx, (int)sizeof(T), dst_offset));
+        int mask_index = mad24(gy, mask_step, mad24(gx/CN, (int)sizeof(uchar), mask_offset));
+
+        #pragma unroll
+        for (int i = 0; i < STRIDE_SIZE; i++)
+        {
+            if (gy < rows)
+            {
+                T sdata = *(__global const T *)(srcptr + src_index);
+                const uchar mdata = *(maskptr + mask_index);
+                if (mdata != 0)
+                {
+                    __global T * dst = (__global T *)(dstptr + dst_index);
+
+                    #ifdef THRESH_BINARY
+                            dst[0] = sdata > (thresh) ? (T)(max_val) : (T)(0);
+                    #elif defined THRESH_BINARY_INV
+                            dst[0] = sdata > (thresh) ? (T)(0) : (T)(max_val);
+                    #elif defined THRESH_TRUNC
+                            dst[0] = clamp(sdata, (T)min_val, (T)(thresh));
+                    #elif defined THRESH_TOZERO
+                            dst[0] = sdata > (thresh) ? sdata : (T)(0);
+                    #elif defined THRESH_TOZERO_INV
+                            dst[0] = sdata > (thresh) ? (T)(0) : sdata;
+                    #endif
+                }
+                gy++;
+                src_index += src_step;
+                dst_index += dst_step;
+                mask_index += mask_step;
+            }
+        }
+    }
+}

modules/imgproc/src/thresh.cpp

@@ -119,6 +119,65 @@ static void threshGeneric(Size roi, const T* src, size_t src_step, T* dst,
     }
 }
 
+template <typename T>
+static void threshGenericWithMask(const Mat& _src, Mat& _dst, const Mat& _mask,
+                                  T thresh, T maxval, int type)
+{
+    Size roi = _src.size();
+    const int cn = _src.channels();
+    roi.width *= cn;
+    size_t src_step = _src.step/_src.elemSize1();
+    size_t dst_step = _dst.step/_src.elemSize1();
+
+    const T* src = _src.ptr<T>(0);
+    T* dst = _dst.ptr<T>(0);
+    const unsigned char* mask = _mask.ptr<unsigned char>(0);
+    size_t mask_step = _mask.step;
+
+    int i = 0, j;
+    switch (type)
+    {
+    case THRESH_BINARY:
+        for (; i < roi.height; i++, src += src_step, dst += dst_step, mask += mask_step)
+            for (j = 0; j < roi.width; j++)
+                if (mask[j/cn] != 0)
+                    dst[j] = threshBinary<T>(src[j], thresh, maxval);
+        return;
+
+    case THRESH_BINARY_INV:
+        for (; i < roi.height; i++, src += src_step, dst += dst_step, mask += mask_step)
+            for (j = 0; j < roi.width; j++)
+                if (mask[j/cn] != 0)
+                    dst[j] = threshBinaryInv<T>(src[j], thresh, maxval);
+        return;
+
+    case THRESH_TRUNC:
+        for (; i < roi.height; i++, src += src_step, dst += dst_step, mask += mask_step)
+            for (j = 0; j < roi.width; j++)
+                if (mask[j/cn] != 0)
+                    dst[j] = threshTrunc<T>(src[j], thresh);
+        return;
+
+    case THRESH_TOZERO:
+        for (; i < roi.height; i++, src += src_step, dst += dst_step, mask += mask_step)
+            for (j = 0; j < roi.width; j++)
+                if (mask[j/cn] != 0)
+                    dst[j] = threshToZero<T>(src[j], thresh);
+        return;
+
+    case THRESH_TOZERO_INV:
+        for (; i < roi.height; i++, src += src_step, dst += dst_step, mask += mask_step)
+            for (j = 0; j < roi.width; j++)
+                if (mask[j/cn] != 0)
+                    dst[j] = threshToZeroInv<T>(src[j], thresh);
+        return;
+
+    default:
+        CV_Error( cv::Error::StsBadArg, "" ); return;
+    }
+}
+
+
 static void
 thresh_8u( const Mat& _src, Mat& _dst, uchar thresh, uchar maxval, int type )
 {
@@ -724,7 +783,6 @@ thresh_16s( const Mat& _src, Mat& _dst, short thresh, short maxval, int type )
 #endif
 }
 
-
 static void
 thresh_32f( const Mat& _src, Mat& _dst, float thresh, float maxval, int type )
 {
@@ -1121,8 +1179,8 @@ static bool ipp_getThreshVal_Otsu_8u( const unsigned char* _src, int step, Size
 }
 #endif
 
-template<typename T, size_t BinsOnStack = 0u>
-static double getThreshVal_Otsu( const Mat& _src, const Size& size)
+template<typename T, size_t BinsOnStack = 0u, bool useMask = false>
+static double getThreshVal_Otsu( const Mat& _src, const Mat& _mask, const Size& size )
 {
     const int N = std::numeric_limits<T>::max() + 1;
     int i, j;
@@ -1136,24 +1194,51 @@ static double getThreshVal_Otsu( const Mat& _src, const Size& size)
     #if CV_ENABLE_UNROLLED
     int* h_unrolled[3] = {h + N, h + 2 * N, h + 3 * N };
     #endif
+    int maskCount = 0;
     for( i = 0; i < size.height; i++ )
     {
         const T* src = _src.ptr<T>(i, 0);
+        const unsigned char* pMask = nullptr;
+        if ( useMask )
+            pMask = _mask.ptr<unsigned char>(i, 0);
         j = 0;
         #if CV_ENABLE_UNROLLED
         for( ; j <= size.width - 4; j += 4 )
         {
             int v0 = src[j], v1 = src[j+1];
-            h[v0]++; h_unrolled[0][v1]++;
+            if ( useMask )
+            {
+                h[v0] += (pMask[j] != 0) ? ++maskCount,1 : 0;
+                h_unrolled[0][v1] += (pMask[j+1] != 0) ? ++maskCount,1 : 0;
+            }
+            else
+            {
+                h[v0]++;
+                h_unrolled[0][v1]++;
+            }
             v0 = src[j+2]; v1 = src[j+3];
-            h_unrolled[1][v0]++; h_unrolled[2][v1]++;
+            if ( useMask )
+            {
+                h_unrolled[1][v0] += (pMask[j+2] != 0) ? ++maskCount,1 : 0;
+                h_unrolled[2][v1] += (pMask[j+3] != 0) ? ++maskCount,1 : 0;
+            }
+            else
+            {
+                h_unrolled[1][v0]++;
+                h_unrolled[2][v1]++;
+            }
         }
         #endif
         for( ; j < size.width; j++ )
-            h[src[j]]++;
+        {
+            if ( useMask )
+                h[src[j]] += (pMask[j] != 0) ? ++maskCount,1 : 0;
+            else
+                h[src[j]]++;
+        }
     }
 
-    double mu = 0, scale = 1./(size.width*size.height);
+    double mu = 0, scale = 1./( useMask ? maskCount : ( size.width*size.height ) );
     for( i = 0; i < N; i++ )
     {
         #if CV_ENABLE_UNROLLED
@@ -1191,46 +1276,56 @@ static double getThreshVal_Otsu( const Mat& _src, const Size& size)
 }
 
 static double
-getThreshVal_Otsu_8u( const Mat& _src )
+getThreshVal_Otsu_8u( const Mat& _src, const Mat& _mask = cv::Mat())
 {
     Size size = _src.size();
     int step = (int) _src.step;
-    if( _src.isContinuous() )
+    if( _src.isContinuous() && ( _mask.empty() || _mask.isContinuous() ) )
     {
         size.width *= size.height;
         size.height = 1;
         step = size.width;
     }
 
-#ifdef HAVE_IPP
-    unsigned char thresh = 0;
-    CV_IPP_RUN_FAST(ipp_getThreshVal_Otsu_8u(_src.ptr(), step, size, thresh), thresh);
-#else
-    CV_UNUSED(step);
-#endif
+    if (_mask.empty())
+    {
+        #ifdef HAVE_IPP
+        unsigned char thresh = 0;
+        CV_IPP_RUN_FAST(ipp_getThreshVal_Otsu_8u(_src.ptr(), step, size, thresh), thresh);
+        #else
+        CV_UNUSED(step);
+        #endif
+    }
 
-    return getThreshVal_Otsu<uchar, 256u>(_src, size);
+    if (!_mask.empty())
+        return getThreshVal_Otsu<uchar, 256u, true>(_src, _mask, size);
+    else
+        return getThreshVal_Otsu<uchar, 256u, false>(_src, _mask, size);
 }
 
 static double
-getThreshVal_Otsu_16u( const Mat& _src )
+getThreshVal_Otsu_16u( const Mat& _src, const Mat& _mask = cv::Mat() )
 {
     Size size = _src.size();
-    if( _src.isContinuous() )
+    if( _src.isContinuous() && ( _mask.empty() || _mask.isContinuous() ) )
     {
         size.width *= size.height;
         size.height = 1;
     }
 
-    return getThreshVal_Otsu<ushort>(_src, size);
+    if (!_mask.empty())
+        return getThreshVal_Otsu<ushort, 0u, true>(_src, _mask, size);
+    else
+        return getThreshVal_Otsu<ushort, 0u, false>(_src, _mask, size);
 }
 
+template<bool useMask>
 static double
-getThreshVal_Triangle_8u( const Mat& _src )
+getThreshVal_Triangle_8u( const Mat& _src, const Mat& _mask = cv::Mat() )
 {
     Size size = _src.size();
     int step = (int) _src.step;
-    if( _src.isContinuous() )
+    if( _src.isContinuous() && ( _mask.empty() || _mask.isContinuous() ) )
     {
         size.width *= size.height;
         size.height = 1;
@@ -1245,18 +1340,44 @@ getThreshVal_Triangle_8u( const Mat& _src )
     for( i = 0; i < size.height; i++ )
     {
         const uchar* src = _src.ptr() + step*i;
+        const uchar* pMask = nullptr;
+        if ( useMask )
+            pMask = _mask.ptr<unsigned char>(i);
         j = 0;
         #if CV_ENABLE_UNROLLED
         for( ; j <= size.width - 4; j += 4 )
         {
             int v0 = src[j], v1 = src[j+1];
-            h[v0]++; h_unrolled[0][v1]++;
+            if ( useMask )
+            {
+                h[v0] += (pMask[j] != 0) ? 1 : 0;
+                h_unrolled[0][v1] += (pMask[j+1] != 0) ? 1 : 0;
+            }
+            else
+            {
+                h[v0]++;
+                h_unrolled[0][v1]++;
+            }
             v0 = src[j+2]; v1 = src[j+3];
-            h_unrolled[1][v0]++; h_unrolled[2][v1]++;
+            if ( useMask )
+            {
+                h_unrolled[1][v0] += (pMask[j+2] != 0) ? 1 : 0;
+                h_unrolled[2][v1] += (pMask[j+3] != 0) ? 1 : 0;
+            }
+            else
+            {
+                h_unrolled[1][v0]++;
+                h_unrolled[2][v1]++;
+            }
         }
         #endif
         for( ; j < size.width; j++ )
-            h[src[j]]++;
+        {
+            if ( useMask )
+                h[src[j]] += (pMask[j] != 0) ? 1 : 0;
+            else
+                h[src[j]]++;
+        }
     }
 
     int left_bound = 0, right_bound = 0, max_ind = 0, max = 0;
@@ -1342,10 +1463,11 @@ getThreshVal_Triangle_8u( const Mat& _src )
 class ThresholdRunner : public ParallelLoopBody
 {
 public:
-    ThresholdRunner(Mat _src, Mat _dst, double _thresh, double _maxval, int _thresholdType)
+    ThresholdRunner(Mat _src, Mat _dst, const Mat& _mask, double _thresh, double _maxval, int _thresholdType)
     {
         src = _src;
         dst = _dst;
+        mask = _mask;
 
         thresh = _thresh;
         maxval = _maxval;
@@ -1360,35 +1482,56 @@ public:
         Mat srcStripe = src.rowRange(row0, row1);
         Mat dstStripe = dst.rowRange(row0, row1);
 
-        CALL_HAL(threshold, cv_hal_threshold, srcStripe.data, srcStripe.step, dstStripe.data, dstStripe.step,
-                 srcStripe.cols, srcStripe.rows, srcStripe.depth(), srcStripe.channels(),
-                 thresh, maxval, thresholdType);
+        const bool useMask = !mask.empty();
+
+        if ( !useMask )
+        {
+            CALL_HAL(threshold, cv_hal_threshold, srcStripe.data, srcStripe.step, dstStripe.data, dstStripe.step,
+                     srcStripe.cols, srcStripe.rows, srcStripe.depth(), srcStripe.channels(),
+                     thresh, maxval, thresholdType);
+        }
 
         if (srcStripe.depth() == CV_8U)
         {
-            thresh_8u( srcStripe, dstStripe, (uchar)thresh, (uchar)maxval, thresholdType );
+            if ( useMask )
+                threshGenericWithMask<uchar>( srcStripe, dstStripe, mask.rowRange(row0, row1), (uchar)thresh, (uchar)maxval, thresholdType );
+            else
+                thresh_8u( srcStripe, dstStripe, (uchar)thresh, (uchar)maxval, thresholdType );
         }
         else if( srcStripe.depth() == CV_16S )
         {
-            thresh_16s( srcStripe, dstStripe, (short)thresh, (short)maxval, thresholdType );
+            if ( useMask )
+                threshGenericWithMask<short>( srcStripe, dstStripe, mask.rowRange(row0, row1), (short)thresh, (short)maxval, thresholdType );
+            else
+                thresh_16s( srcStripe, dstStripe, (short)thresh, (short)maxval, thresholdType );
         }
         else if( srcStripe.depth() == CV_16U )
         {
-            thresh_16u( srcStripe, dstStripe, (ushort)thresh, (ushort)maxval, thresholdType );
+            if ( useMask )
+                threshGenericWithMask<ushort>( srcStripe, dstStripe, mask.rowRange(row0, row1), (ushort)thresh, (ushort)maxval, thresholdType );
+            else
+                thresh_16u( srcStripe, dstStripe, (ushort)thresh, (ushort)maxval, thresholdType );
         }
         else if( srcStripe.depth() == CV_32F )
         {
-            thresh_32f( srcStripe, dstStripe, (float)thresh, (float)maxval, thresholdType );
+            if ( useMask )
+                threshGenericWithMask<float>( srcStripe, dstStripe, mask.rowRange(row0, row1), (float)thresh, (float)maxval, thresholdType );
+            else
+                thresh_32f( srcStripe, dstStripe, (float)thresh, (float)maxval, thresholdType );
         }
         else if( srcStripe.depth() == CV_64F )
         {
-            thresh_64f(srcStripe, dstStripe, thresh, maxval, thresholdType);
+            if ( useMask )
+                threshGenericWithMask<double>( srcStripe, dstStripe, mask.rowRange(row0, row1), thresh, maxval, thresholdType );
+            else
+                thresh_64f(srcStripe, dstStripe, thresh, maxval, thresholdType);
         }
     }
 
 private:
     Mat src;
     Mat dst;
+    Mat mask;
 
     double thresh;
     double maxval;
@@ -1397,7 +1540,7 @@ private:
 
 #ifdef HAVE_OPENCL
 
-static bool ocl_threshold( InputArray _src, OutputArray _dst, double & thresh, double maxval, int thresh_type )
+static bool ocl_threshold( InputArray _src, OutputArray _dst, InputArray _mask, double & thresh, double maxval, int thresh_type )
 {
     int type = _src.type(), depth = CV_MAT_DEPTH(type), cn = CV_MAT_CN(type),
         kercn = ocl::predictOptimalVectorWidth(_src, _dst), ktype = CV_MAKE_TYPE(depth, kercn);
@@ -1416,16 +1559,26 @@ static bool ocl_threshold( InputArray _src, OutputArray _dst, double & thresh, d
     ocl::Device dev = ocl::Device::getDefault();
     int stride_size = dev.isIntel() && (dev.type() & ocl::Device::TYPE_GPU) ? 4 : 1;
 
-    ocl::Kernel k("threshold", ocl::imgproc::threshold_oclsrc,
-                  format("-D %s -D T=%s -D T1=%s -D STRIDE_SIZE=%d%s", thresholdMap[thresh_type],
-                         ocl::typeToStr(ktype), ocl::typeToStr(depth), stride_size,
-                         doubleSupport ? " -D DOUBLE_SUPPORT" : ""));
+    const bool useMask = !_mask.empty();
+
+    ocl::Kernel k =
+        !useMask ?
+            ocl::Kernel("threshold", ocl::imgproc::threshold_oclsrc,
+                        format("-D %s -D T=%s -D T1=%s -D STRIDE_SIZE=%d%s", thresholdMap[thresh_type],
+                               ocl::typeToStr(ktype), ocl::typeToStr(depth), stride_size,
+                               doubleSupport ? " -D DOUBLE_SUPPORT" : "")) :
+            ocl::Kernel("threshold_mask", ocl::imgproc::threshold_oclsrc,
+                        format("-D %s -D T=%s -D T1=%s -D CN=%d -D STRIDE_SIZE=%d%s", thresholdMap[thresh_type],
+                               ocl::typeToStr(ktype), ocl::typeToStr(depth), cn, stride_size,
+                               doubleSupport ? " -D DOUBLE_SUPPORT" : ""));
+
     if (k.empty())
         return false;
 
     UMat src = _src.getUMat();
     _dst.create(src.size(), type);
     UMat dst = _dst.getUMat();
+    UMat mask = !useMask ? cv::UMat() : _mask.getUMat();
 
     if (depth <= CV_32S)
         thresh = cvFloor(thresh);
@@ -1433,10 +1586,17 @@ static bool ocl_threshold( InputArray _src, OutputArray _dst, double & thresh, d
     const double min_vals[] = { 0, CHAR_MIN, 0, SHRT_MIN, INT_MIN, -FLT_MAX, -DBL_MAX, 0 };
     double min_val = min_vals[depth];
 
-    k.args(ocl::KernelArg::ReadOnlyNoSize(src), ocl::KernelArg::WriteOnly(dst, cn, kercn),
-           ocl::KernelArg::Constant(Mat(1, 1, depth, Scalar::all(thresh))),
-           ocl::KernelArg::Constant(Mat(1, 1, depth, Scalar::all(maxval))),
-           ocl::KernelArg::Constant(Mat(1, 1, depth, Scalar::all(min_val))));
+    if (!useMask)
+        k.args(ocl::KernelArg::ReadOnlyNoSize(src), ocl::KernelArg::WriteOnly(dst, cn, kercn),
+               ocl::KernelArg::Constant(Mat(1, 1, depth, Scalar::all(thresh))),
+               ocl::KernelArg::Constant(Mat(1, 1, depth, Scalar::all(maxval))),
+               ocl::KernelArg::Constant(Mat(1, 1, depth, Scalar::all(min_val))));
+    else
+        k.args(ocl::KernelArg::ReadOnlyNoSize(src), ocl::KernelArg::WriteOnly(dst, cn, kercn),
+               ocl::KernelArg::ReadOnlyNoSize(mask),
+               ocl::KernelArg::Constant(Mat(1, 1, depth, Scalar::all(thresh))),
+               ocl::KernelArg::Constant(Mat(1, 1, depth, Scalar::all(maxval))),
+               ocl::KernelArg::Constant(Mat(1, 1, depth, Scalar::all(min_val))));
 
     size_t globalsize[2] = { (size_t)dst.cols * cn / kercn, (size_t)dst.rows };
     globalsize[1] = (globalsize[1] + stride_size - 1) / stride_size;
@@ -1452,7 +1612,7 @@ double cv::threshold( InputArray _src, OutputArray _dst, double thresh, double m
     CV_INSTRUMENT_REGION();
 
     CV_OCL_RUN_(_src.dims() <= 2 && _dst.isUMat(),
-                ocl_threshold(_src, _dst, thresh, maxval, type), thresh)
+                ocl_threshold(_src, _dst, cv::noArray(), thresh, maxval, type), thresh)
 
     const bool isDisabled = ((type & THRESH_DRYRUN) != 0);
     type &= ~THRESH_DRYRUN;
@@ -1481,7 +1641,7 @@ double cv::threshold( InputArray _src, OutputArray _dst, double thresh, double m
     else if( automatic_thresh == cv::THRESH_TRIANGLE )
     {
         CV_Assert( src.type() == CV_8UC1 );
-        thresh = getThreshVal_Triangle_8u( src );
+        thresh = getThreshVal_Triangle_8u<false>( src );
     }
 
     if( src.depth() == CV_8U )
@@ -1587,7 +1747,153 @@ double cv::threshold( InputArray _src, OutputArray _dst, double thresh, double m
         return thresh;
 
     parallel_for_(Range(0, dst.rows),
-                  ThresholdRunner(src, dst, thresh, maxval, type),
+                  ThresholdRunner(src, dst, cv::Mat(), thresh, maxval, type),
+                  dst.total()/(double)(1<<16));
+    return thresh;
+}
+
+double cv::thresholdWithMask( InputArray _src, InputOutputArray _dst, InputArray _mask, double thresh, double maxval, int type )
+{
+    CV_INSTRUMENT_REGION();
+    CV_Assert( _mask.empty() || ( ( _dst.size() == _src.size() ) && ( _dst.type() == _src.type() ) ) );
+    if ( _mask.empty() )
+        return cv::threshold(_src, _dst, thresh, maxval, type);
+
+    CV_OCL_RUN_(_src.dims() <= 2 && _dst.isUMat(),
+                ocl_threshold(_src, _dst, _mask, thresh, maxval, type), thresh)
+
+    const bool isDisabled = ((type & THRESH_DRYRUN) != 0);
+    type &= ~THRESH_DRYRUN;
+
+    Mat src = _src.getMat();
+    Mat mask = _mask.getMat();
+
+    if (!isDisabled)
+        _dst.create( src.size(), src.type() );
+    Mat dst = isDisabled ? cv::Mat() : _dst.getMat();
+
+    int automatic_thresh = (type & ~cv::THRESH_MASK);
+    type &= THRESH_MASK;
+
+    CV_Assert( automatic_thresh != (cv::THRESH_OTSU | cv::THRESH_TRIANGLE) );
+    if( automatic_thresh == cv::THRESH_OTSU )
+    {
+        int src_type = src.type();
+        CV_CheckType(src_type, src_type == CV_8UC1 || src_type == CV_16UC1, "THRESH_OTSU mode");
+
+        thresh = src.type() == CV_8UC1 ? getThreshVal_Otsu_8u( src, mask )
+                                       : getThreshVal_Otsu_16u( src, mask );
+    }
+    else if( automatic_thresh == cv::THRESH_TRIANGLE )
+    {
+        CV_Assert( src.type() == CV_8UC1 );
+        thresh = getThreshVal_Triangle_8u<true>( src, mask );
+    }
+
+    if( src.depth() == CV_8U )
+    {
+        int ithresh = cvFloor(thresh);
+        thresh = ithresh;
+        if (isDisabled)
+            return thresh;
+
+        int imaxval = cvRound(maxval);
+        if( type == THRESH_TRUNC )
+            imaxval = ithresh;
+        imaxval = saturate_cast<uchar>(imaxval);
+
+        if( ithresh < 0 || ithresh >= 255 )
+        {
+            if( type == THRESH_BINARY || type == THRESH_BINARY_INV ||
+                ((type == THRESH_TRUNC || type == THRESH_TOZERO_INV) && ithresh < 0) ||
+                (type == THRESH_TOZERO && ithresh >= 255) )
+            {
+                int v = type == THRESH_BINARY ? (ithresh >= 255 ? 0 : imaxval) :
+                        type == THRESH_BINARY_INV ? (ithresh >= 255 ? imaxval : 0) :
+                        /*type == THRESH_TRUNC ? imaxval :*/ 0;
+                dst.setTo(v);
+            }
+            else
+                src.copyTo(dst);
+            return thresh;
+        }
+
+        thresh = ithresh;
+        maxval = imaxval;
+    }
+    else if( src.depth() == CV_16S )
+    {
+        int ithresh = cvFloor(thresh);
+        thresh = ithresh;
+        if (isDisabled)
+            return thresh;
+
+        int imaxval = cvRound(maxval);
+        if( type == THRESH_TRUNC )
+            imaxval = ithresh;
+        imaxval = saturate_cast<short>(imaxval);
+
+        if( ithresh < SHRT_MIN || ithresh >= SHRT_MAX )
+        {
+            if( type == THRESH_BINARY || type == THRESH_BINARY_INV ||
+               ((type == THRESH_TRUNC || type == THRESH_TOZERO_INV) && ithresh < SHRT_MIN) ||
+               (type == THRESH_TOZERO && ithresh >= SHRT_MAX) )
+            {
+                int v = type == THRESH_BINARY ? (ithresh >= SHRT_MAX ? 0 : imaxval) :
+                type == THRESH_BINARY_INV ? (ithresh >= SHRT_MAX ? imaxval : 0) :
+                /*type == THRESH_TRUNC ? imaxval :*/ 0;
+                dst.setTo(v);
+            }
+            else
+                src.copyTo(dst);
+            return thresh;
+        }
+        thresh = ithresh;
+        maxval = imaxval;
+    }
+    else if (src.depth() == CV_16U )
+    {
+        int ithresh = cvFloor(thresh);
+        thresh = ithresh;
+        if (isDisabled)
+            return thresh;
+
+        int imaxval = cvRound(maxval);
+        if (type == THRESH_TRUNC)
+            imaxval = ithresh;
+        imaxval = saturate_cast<ushort>(imaxval);
+
+        int ushrt_min = 0;
+        if (ithresh < ushrt_min || ithresh >= (int)USHRT_MAX)
+        {
+            if (type == THRESH_BINARY || type == THRESH_BINARY_INV ||
+               ((type == THRESH_TRUNC || type == THRESH_TOZERO_INV) && ithresh < ushrt_min) ||
+               (type == THRESH_TOZERO && ithresh >= (int)USHRT_MAX))
+            {
+                int v = type == THRESH_BINARY ? (ithresh >= (int)USHRT_MAX ? 0 : imaxval) :
+                        type == THRESH_BINARY_INV ? (ithresh >= (int)USHRT_MAX ? imaxval : 0) :
+                  /*type == THRESH_TRUNC ? imaxval :*/ 0;
+                dst.setTo(v);
+            }
+            else
+                src.copyTo(dst);
+            return thresh;
+        }
+        thresh = ithresh;
+        maxval = imaxval;
+    }
+    else if( src.depth() == CV_32F )
+        ;
+    else if( src.depth() == CV_64F )
+        ;
+    else
+        CV_Error( cv::Error::StsUnsupportedFormat, "" );
+
+    if (isDisabled)
+        return thresh;
+
+    parallel_for_(Range(0, dst.rows),
+                  ThresholdRunner(src, dst, mask, thresh, maxval, type),
                   dst.total()/(double)(1<<16));
     return thresh;
 }

modules/imgproc/test/ocl/test_imgproc.cpp

@@ -420,6 +420,49 @@ OCL_TEST_P(Threshold_Dryrun, Mat)
     }
 }
 
+struct Threshold_masked :
+    public ImgprocTestBase
+{
+    int thresholdType;
+
+    virtual void SetUp()
+    {
+        type = GET_PARAM(0);
+        thresholdType = GET_PARAM(2);
+        useRoi = GET_PARAM(3);
+    }
+};
+
+OCL_TEST_P(Threshold_masked, Mat)
+{
+    for (int j = 0; j < test_loop_times; j++)
+    {
+        random_roi();
+
+        double maxVal = randomDouble(20.0, 127.0);
+        double thresh = randomDouble(0.0, maxVal);
+
+        const int _thresholdType = thresholdType;
+
+        cv::Size sz = src_roi.size();
+        cv::Mat mask_roi = cv::Mat::zeros(sz, CV_8UC1);
+        cv::RotatedRect ellipseRect((cv::Point2f)cv::Point(sz.width/2, sz.height/2), (cv::Size2f)sz, 0);
+        cv::ellipse(mask_roi, ellipseRect, cv::Scalar::all(255), cv::FILLED);//for very different mask alignments
+
+        cv::UMat umask_roi(mask_roi.size(), mask_roi.type());
+        mask_roi.copyTo(umask_roi.getMat(cv::AccessFlag::ACCESS_WRITE));
+
+        src_roi.copyTo(dst_roi);
+        usrc_roi.copyTo(udst_roi);
+
+        OCL_OFF(cv::thresholdWithMask(src_roi, dst_roi, mask_roi, thresh, maxVal, _thresholdType));
+        OCL_ON(cv::thresholdWithMask(usrc_roi, udst_roi, umask_roi, thresh, maxVal, _thresholdType));
+
+        OCL_EXPECT_MATS_NEAR(dst, 0);
+    }
+}
+
+
 /////////////////////////////////////////// CLAHE //////////////////////////////////////////////////
 
 PARAM_TEST_CASE(CLAHETest, Size, double, bool)
@@ -527,6 +570,14 @@ OCL_INSTANTIATE_TEST_CASE_P(Imgproc, Threshold_Dryrun, Combine(
                                    ThreshOp(THRESH_TOZERO), ThreshOp(THRESH_TOZERO_INV)),
                             Bool()));
 
+OCL_INSTANTIATE_TEST_CASE_P(Imgproc, Threshold_masked, Combine(
+                            Values(CV_8UC1, CV_8UC3, CV_16SC1, CV_16SC3, CV_16UC1, CV_16UC3, CV_32FC1, CV_32FC3, CV_64FC1, CV_64FC3),
+                            Values(0),
+                            Values(ThreshOp(THRESH_BINARY),
+                                   ThreshOp(THRESH_BINARY_INV), ThreshOp(THRESH_TRUNC),
+                                   ThreshOp(THRESH_TOZERO), ThreshOp(THRESH_TOZERO_INV)),
+                            Bool()));
+
 OCL_INSTANTIATE_TEST_CASE_P(Imgproc, CLAHETest, Combine(
                             Values(Size(4, 4), Size(32, 8), Size(8, 64)),
                             Values(0.0, 10.0, 62.0, 300.0),

modules/imgproc/test/test_thresh.cpp

@@ -520,6 +520,98 @@ TEST(Imgproc_Threshold, threshold_dryrun)
     }
 }
 
+typedef tuple < bool, int, int, int, int > Imgproc_Threshold_Masked_Params_t;
+
+typedef testing::TestWithParam< Imgproc_Threshold_Masked_Params_t > Imgproc_Threshold_Masked_Fixed;
+
+TEST_P(Imgproc_Threshold_Masked_Fixed, threshold_mask_fixed)
+{
+    bool useROI = get<0>(GetParam());
+    int depth = get<1>(GetParam());
+    int cn = get<2>(GetParam());
+    int threshType = get<3>(GetParam());
+    int threshFlag = get<4>(GetParam());
+
+    const int _threshType = threshType | threshFlag;
+    Size sz(127, 127);
+    Size wrapperSize = useROI ? Size(sz.width+4, sz.height+4) : sz;
+    Mat wrapper(wrapperSize, CV_MAKETYPE(depth, cn));
+    Mat input = useROI ? Mat(wrapper, Rect(Point(), sz)) : wrapper;
+    cv::randu(input, cv::Scalar::all(0), cv::Scalar::all(255));
+
+    Mat mask = cv::Mat::zeros(sz, CV_8UC1);
+    cv::RotatedRect ellipseRect((cv::Point2f)cv::Point(sz.width/2, sz.height/2), (cv::Size2f)sz, 0);
+    cv::ellipse(mask, ellipseRect, cv::Scalar::all(255), cv::FILLED);//for very different mask alignments
+
+    Mat output_with_mask = cv::Mat::zeros(sz, input.type());
+    cv::thresholdWithMask(input, output_with_mask, mask, 127, 255, _threshType);
+
+    cv::bitwise_not(mask, mask);
+    input.copyTo(output_with_mask, mask);
+
+    Mat output_without_mask;
+    cv::threshold(input, output_without_mask, 127, 255, _threshType);
+    input.copyTo(output_without_mask, mask);
+
+    EXPECT_MAT_NEAR(output_with_mask, output_without_mask, 0);
+}
+
+INSTANTIATE_TEST_CASE_P(/*nothing*/, Imgproc_Threshold_Masked_Fixed,
+    testing::Combine(
+        testing::Values(false, true),//use roi
+        testing::Values(CV_8U, CV_16U, CV_16S, CV_32F, CV_64F),//depth
+        testing::Values(1, 3),//channels
+        testing::Values(THRESH_BINARY, THRESH_BINARY_INV, THRESH_TRUNC, THRESH_TOZERO, THRESH_TOZERO_INV),// threshTypes
+        testing::Values(0)
+    )
+);
+
+typedef testing::TestWithParam< Imgproc_Threshold_Masked_Params_t > Imgproc_Threshold_Masked_Auto;
+
+TEST_P(Imgproc_Threshold_Masked_Auto, threshold_mask_auto)
+{
+    bool useROI = get<0>(GetParam());
+    int depth = get<1>(GetParam());
+    int cn = get<2>(GetParam());
+    int threshType = get<3>(GetParam());
+    int threshFlag = get<4>(GetParam());
+
+    if (threshFlag == THRESH_TRIANGLE && depth != CV_8U)
+        throw SkipTestException("THRESH_TRIANGLE option supports CV_8UC1 input only");
+
+    const int _threshType = threshType | threshFlag;
+    Size sz(127, 127);
+    Size wrapperSize = useROI ? Size(sz.width+4, sz.height+4) : sz;
+    Mat wrapper(wrapperSize, CV_MAKETYPE(depth, cn));
+    Mat input = useROI ? Mat(wrapper, Rect(Point(), sz)) : wrapper;
+    cv::randu(input, cv::Scalar::all(0), cv::Scalar::all(255));
+
+    //for OTSU and TRIANGLE, we use a rectangular mask that can be just cropped
+    //in order to compute the threshold of the non-masked version
+    Mat mask = cv::Mat::zeros(sz, CV_8UC1);
+    cv::Rect roiRect(sz.width/4, sz.height/4, sz.width/2, sz.height/2);
+    cv::rectangle(mask, roiRect, cv::Scalar::all(255), cv::FILLED);
+
+    Mat output_with_mask = cv::Mat::zeros(sz, input.type());
+    const double autoThreshWithMask = cv::thresholdWithMask(input, output_with_mask, mask, 127, 255, _threshType);
+    output_with_mask = Mat(output_with_mask, roiRect);
+
+    Mat output_without_mask;
+    const double autoThresholdWithoutMask = cv::threshold(Mat(input, roiRect), output_without_mask, 127, 255, _threshType);
+
+    ASSERT_EQ(autoThreshWithMask, autoThresholdWithoutMask);
+    EXPECT_MAT_NEAR(output_with_mask, output_without_mask, 0);
+}
+
+INSTANTIATE_TEST_CASE_P(/*nothing*/, Imgproc_Threshold_Masked_Auto,
+    testing::Combine(
+        testing::Values(false, true),//use roi
+        testing::Values(CV_8U, CV_16U),//depth
+        testing::Values(1),//channels
+        testing::Values(THRESH_BINARY, THRESH_BINARY_INV, THRESH_TRUNC, THRESH_TOZERO, THRESH_TOZERO_INV),// threshTypes
+        testing::Values(THRESH_OTSU, THRESH_TRIANGLE)
+    )
+);
 
 TEST(Imgproc_Threshold, regression_THRESH_TOZERO_IPP_16085)
 {