run length morphology

modules/ximgproc/README.md

@@ -15,3 +15,4 @@ Extended Image Processing
 - Deriche Filter
 - Pei&Lin Normalization
 - Ridge Detection Filter
+- Binary morphology on run-length encoded images

modules/ximgproc/doc/ximgproc.bib

@@ -288,3 +288,13 @@ @article{PersoonFu1977
   year={1977},
   publisher={IEEE Computer Society}
 }
+
+@inproceedings{Breuel2008,
+  title = {Binary Morphology and Related Operations on Run-Length Representations.},
+  author = {Breuel, Thomas},
+  year = {2008},
+  month = {01},
+  pages = {159-166},
+  volume = {1},
+  booktitle = {VISAPP 2008 - 3rd International Conference on Computer Vision Theory and Applications, Proceedings}
+}

modules/ximgproc/include/opencv2/ximgproc.hpp

@@ -56,6 +56,7 @@
 #include "ximgproc/fourier_descriptors.hpp"
 #include "ximgproc/ridgefilter.hpp"
 #include "ximgproc/brightedges.hpp"
+#include "ximgproc/run_length_morphology.hpp"
 
 
 /** @defgroup ximgproc Extended Image Processing
@@ -76,6 +77,26 @@ i.e. algorithms which somehow takes into account pixel affinities in natural ima
     @defgroup ximgproc_fast_line_detector Fast line detector
 
     @defgroup ximgproc_fourier Fourier descriptors
+
+    @defgroup ximgproc_run_length_morphology Binary morphology on run-length encoded image
+
+    These functions support morphological operations on binary images. In order to be fast and space efficient binary images are encoded with a run-length representation.
+    This representation groups continuous horizontal sequences of "on" pixels together in a "run". A run is charactarized by the column position of the first pixel in the run, the column
+    position of the last pixel in the run and the row position. This representation is very compact for binary images which contain large continuous areas of "on" and "off" pixels. A checkerboard
+    pattern would be a good example. The representation is not so suitable for binary images created from random noise images or other images where little correlation between neighboring pixels
+    exists.
+
+    The morphological operations supported here are very similar to the operations supported in the imgproc module. In general they are fast. However on several occasions they are slower than the functions
+    from imgproc. The structuring elements of cv::MORPH_RECT and cv::MORPH_CROSS have very good support from the imgproc module. Also small structuring elements are very fast in imgproc (presumably
+    due to opencl support). Therefore the functions from this module are recommended for larger structuring elements (cv::MORPH_ELLIPSE or self defined structuring elements). A sample application
+    (run_length_morphology_demo) is supplied which allows to compare the speed of some morphological operations for the functions using run-length encoding and the imgproc functions for a given image.
+
+    Run length encoded images are stored in standard opencv images. Images have a single column of cv::Point3i elements. The number of rows is the number of run + 1. The first row contains
+    the size of the original (not encoded) image.  For the runs the following mapping is used (x: column begin, y: column end (last column), z: row).
+
+    The size of the original image is required for compatiblity with the imgproc functions when the boundary handling requires that pixel outside the image boundary are
+    "on".
+
     @}
 */
 

modules/ximgproc/include/opencv2/ximgproc/run_length_morphology.hpp

@@ -0,0 +1,119 @@
+// 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.
+
+#ifndef __OPENCV_RUN_LENGTH_MORPHOLOGY_HPP__
+#define __OPENCV_RUN_LENGTH_MORPHOLOGY_HPP__
+
+#include <opencv2/core.hpp>
+
+namespace cv {
+namespace ximgproc {
+namespace rl {
+
+
+//! @addtogroup ximgproc_run_length_morphology
+//! @{
+
+/**
+* @brief   Applies a fixed-level threshold to each array element.
+*
+*
+* @param   src         input array (single-channel).
+* @param   rlDest      resulting run length encoded image.
+* @param   thresh      threshold value.
+* @param   type        thresholding type (only cv::THRESH_BINARY and cv::THRESH_BINARY_INV are supported)
+*
+*/
+CV_EXPORTS void threshold(InputArray src, OutputArray rlDest, double thresh, int type);
+
+
+/**
+* @brief   Dilates an run-length encoded binary image by using a specific structuring element.
+*
+*
+* @param   rlSrc       input image
+* @param   rlDest      result
+* @param   rlKernel    kernel
+* @param   anchor      position of the anchor within the element; default value (0, 0)
+*                      is usually the element center.
+*
+*/
+CV_EXPORTS void dilate(InputArray rlSrc, OutputArray rlDest, InputArray rlKernel, Point anchor = Point(0, 0));
+
+/**
+* @brief   Erodes an run-length encoded binary image by using a specific structuring element.
+*
+*
+* @param   rlSrc       input image
+* @param   rlDest      result
+* @param   rlKernel    kernel
+* @param   bBoundaryOn indicates whether pixel outside the image boundary are assumed to be on
+            (True: works in the same way as the default of cv::erode, False: is a little faster)
+* @param   anchor      position of the anchor within the element; default value (0, 0)
+*                      is usually the element center.
+*
+*/
+CV_EXPORTS void erode(InputArray rlSrc, OutputArray rlDest, InputArray rlKernel,
+    bool bBoundaryOn = true, Point anchor = Point(0, 0));
+
+/**
+* @brief   Returns a run length encoded structuring element of the specified size and shape.
+*
+*
+* @param   shape	Element shape that can be one of cv::MorphShapes
+* @param   ksize	Size of the structuring element.
+*
+*/
+CV_EXPORTS cv::Mat getStructuringElement(int shape, Size ksize);
+
+/**
+* @brief   Paint run length encoded binary image into an image.
+*
+*
+* @param   image       image to paint into (currently only single channel images).
+* @param   rlSrc       run length encoded image
+* @param   value      all foreground pixel of the binary image are set to this value
+*
+*/
+CV_EXPORTS void paint(InputOutputArray image, InputArray rlSrc, const cv::Scalar& value);
+
+/**
+* @brief   Check whether a custom made structuring element can be used with run length morphological operations.
+*          (It must consist of a continuous array of single runs per row)
+*
+* @param   rlStructuringElement   mask to be tested
+*/
+CV_EXPORTS bool isRLMorphologyPossible(InputArray rlStructuringElement);
+
+/**
+* @brief   Creates a run-length encoded image from a vector of runs (column begin, column end, row)
+*
+* @param   runs   vector of runs
+* @param   res    result
+* @param   size   image size (to be used if an "on" boundary should be used in erosion, using the default
+*                  means that the size is computed from the extension of the input)
+*/
+CV_EXPORTS void createRLEImage(std::vector<cv::Point3i>& runs, OutputArray res, Size size = Size(0, 0));
+
+/**
+* @brief   Applies a morphological operation to a run-length encoded binary image.
+*
+*
+* @param   rlSrc       input image
+* @param   rlDest      result
+* @param   op          all operations supported by cv::morphologyEx (except cv::MORPH_HITMISS)
+* @param   rlKernel    kernel
+* @param   bBoundaryOnForErosion indicates whether pixel outside the image boundary are assumed
+*          to be on for erosion operations (True: works in the same way as the default of cv::erode,
+*          False: is a little faster)
+* @param   anchor      position of the anchor within the element; default value (0, 0) is usually the element center.
+*
+*/
+CV_EXPORTS void morphologyEx(InputArray rlSrc, OutputArray rlDest, int op, InputArray rlKernel,
+    bool bBoundaryOnForErosion = true, Point anchor = Point(0,0));
+
+}
+}
+}
+#endif

modules/ximgproc/perf/perf_run_length_morphology.cpp

@@ -0,0 +1,37 @@
+// 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.
+#include "perf_precomp.hpp"
+
+namespace opencv_test {
+namespace {
+
+typedef tuple<int, Size, int> RLParams;
+
+typedef TestBaseWithParam<RLParams> RLMorphologyPerfTest;
+
+PERF_TEST_P(RLMorphologyPerfTest, perf, Combine(Values(1,7, 21), Values(sz720p, sz2160p),
+    Values(MORPH_ERODE, MORPH_DILATE, MORPH_OPEN, MORPH_CLOSE, MORPH_GRADIENT,MORPH_TOPHAT, MORPH_BLACKHAT)))
+{
+    RLParams params = GetParam();
+    int seSize = get<0>(params);
+    Size sz = get<1>(params);
+    int op = get<2>(params);
+
+    Mat src(sz, CV_8U);
+    Mat thresholded, dstRLE;
+    Mat se = rl::getStructuringElement(MORPH_ELLIPSE, cv::Size(2 * seSize + 1, 2 * seSize + 1));
+
+    declare.in(src, WARMUP_RNG);
+
+    TEST_CYCLE_N(4)
+    {
+        rl::threshold(src, thresholded, 100.0, THRESH_BINARY);
+        rl::morphologyEx(thresholded, dstRLE, op, se);
+    }
+
+    SANITY_CHECK_NOTHING();
+}
+
+}
+} // namespace