コメント追記・修正

Author: kyaco

modules/ximgproc/include/opencv2/ximgproc/sparse_table_morphology.hpp

@@ -14,27 +14,81 @@ namespace stMorph {
 //! @addtogroup imgproc_filter
 //! @{
 
+/**
+* @struct  kernelDecompInfo
+* @brief   struct to hold the results of decomposing the structuring element.
+*/
 typedef struct _kernelDecompInfo
 {
+    //! rows of the original kernel.
     int rows;
+    //! cols of the original kernel.
     int cols;
+    //!
+    //! set of rectangles to covers the kernel which height and width both are power of 2.
+    //! point stRects[rd][cd](c,r) means a rectangle left-top (c,r), width 2^rd and height 2^cd.
+    //!
     std::vector<std::vector<std::vector<Point>>> stRects;
+    //!
+    //! Vec2b Mat which sotres the order to calculate sparse table.
+    //! The type of returned mat is Vec2b.
+    //! * if path[dr][dc][0] == 1 then st[dr+1][dc] will be calculated from st[dr][dc].
+    //! * if path[dr][dc][1] == 1 then st[dr][dc+1] will be calculated from st[dr][dc].
+    //!
     Mat plan;
+    //! anchor position of the kernel.
     Point anchor;
+    //! Number of times erosion and dilation are applied.
     int iterations;
 } kernelDecompInfo;
 
+/**
+ * @brief Decompose the structuring element.
+ *
+ * @param  kernel       structuring element used for subsequent morphological operations.
+ * @param  anchor       position of the anchor within the element.
+ *                      default value (-1, -1) means that the anchor is at the element center.
+ * @param  iterations   number of times  is applied.
+ */
 CV_EXPORTS_W kernelDecompInfo decompKernel(InputArray kernel,
                                   Point anchor = Point(-1, -1), int iterations = 1);
 
+/**
+ * @brief  Erodes an image with a kernelDecompInfo using spase table method.
+ *
+ * @param  src          input image
+ * @param  dst          output image of the same size and type as src.
+ * @param  kdi          pre-computated kernelDecompInfo structure.
+ * @param  borderType   pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
+ * @param  borderValue  border value in case of a constant border
+ */
 CV_EXPORTS_W void erode( InputArray src, OutputArray dst, kernelDecompInfo kdi,
                      BorderTypes borderType = BORDER_CONSTANT,
                      const Scalar& borderValue = morphologyDefaultBorderValue() );
 
+/**
+ * @brief  Dilates an image with a kernelDecompInfo using spase table method.
+ *
+ * @param  src          input image;
+ * @param  dst          output image of the same size and type as src.
+ * @param  kdi          pre-computated kernelDecompInfo structure.
+ * @param  borderType   pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
+ * @param  borderValue  border value in case of a constant border
+ */
 CV_EXPORTS_W void dilate( InputArray src, OutputArray dst, kernelDecompInfo kdi,
                      BorderTypes borderType = BORDER_CONSTANT,
                      const Scalar& borderValue = morphologyDefaultBorderValue() );
 
+/**
+ * @brief  Performs advanced morphological transformations with a kernelDecompInfo.
+ *
+ * @param  src          input image;
+ * @param  dst          output image of the same size and type as src.
+ * @param  op           all operations supported by cv::morphologyEx (except cv::MORPH_HITMISS)
+ * @param  kdi          pre-computated kernelDecompInfo structure.
+ * @param  borderType   pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
+ * @param  borderValue  border value in case of a constant border
+ */
 CV_EXPORTS_W void morphologyEx( InputArray src, OutputArray dst, int op, kernelDecompInfo kdi,
                                 BorderTypes borderType = BORDER_CONSTANT,
                                 const Scalar& borderValue = morphologyDefaultBorderValue() );

modules/ximgproc/src/sparse_table_morphology.cpp

@@ -10,6 +10,8 @@
 namespace cv {
 namespace stMorph {
 
+#pragma region decompKernel
+
 // normalizeAnchor; Copied from filterengine.hpp.
 static inline Point normalizeAnchor(Point anchor, Size ksize)
 {
@@ -21,11 +23,6 @@ static inline Point normalizeAnchor(Point anchor, Size ksize)
     return anchor;
 }
 
-enum Op
-{
-    Min, Max
-};
-
 int log2(int n)
 {
     int ans = -1;
@@ -97,7 +94,7 @@ std::vector<Point> findP2RectCorners(const Mat& stNode, int rowDepth, int colDep
             if (row > 0 && stNode.at<uchar>(row - 1, col) == 1
                 && row + 1 < stNode.rows && stNode.at<uchar>(row + 1, col) == 1) continue;
 
-            // ignore if neighboring block is white
+            // ignore if deeper cell is white
             if (col + colOfst < stNode.cols && stNode.at<uchar>(row, col + colOfst) == 1) continue;
             if (col - colOfst >= 0 && stNode.at<uchar>(row, col - colOfst) == 1) continue;
             if (row + rowOfst < stNode.rows && stNode.at<uchar>(row + rowOfst, col) == 1) continue;
@@ -143,15 +140,11 @@ std::vector<std::vector<std::vector<Point>>> genPow2RectsToCoverKernel(
     return p2Rects;
 }
 
+/*
+* Solves the rectilinear steiner arborescence problem greedy.
+*/
 Mat SolveRSAPGreedy(const Mat& initialMap)
 {
-    /*
-    * Solves the rectilinear steiner arborescence problem greedy.
-    * https://link.springer.com/article/10.1007/BF01758762
-    *
-    * Following implementation is O(n^3)-time algorithm
-    * which is different from the mothod proposed in the paper.
-    */
     CV_Assert(initialMap.type() == CV_8UC1);
     std::vector<Point> pos;
     for (int r = 0; r < initialMap.rows; r++)
@@ -193,7 +186,7 @@ Mat SolveRSAPGreedy(const Mat& initialMap)
             resMap.at<Vec2b>(row, maxX)[0] = 1;
 
         pos[maxI] = Point(maxX, maxY);
-        swap(pos[maxJ], pos[pos.size() - 1]);
+        std::swap(pos[maxJ], pos[pos.size() - 1]);
         pos.pop_back();
     }
     return resMap;
@@ -202,13 +195,6 @@ Mat SolveRSAPGreedy(const Mat& initialMap)
 Mat sparseTableFillPlanning(
     std::vector<std::vector<std::vector<Point>>> pow2Rects, int rowDepthLim, int colDepthLim)
 {
-    /*
-    * Plan the order to fill the required 2d-sparse-table nodes.
-    * The type of returned mat is Vec2b.
-    * if path[dr][dc][0] == 1 then st[dr+1][dc] will be calculated from st[dr][dc].
-    * if path[dr][dc][1] == 1 then st[dr][dc+1] will be calculated from st[dr][dc].
-    */
-
     // list up required sparse table nodes.
     Mat stMap = Mat::zeros(rowDepthLim, colDepthLim, CV_8UC1);
     for (int rd = 0; rd < rowDepthLim; rd++)
@@ -234,9 +220,6 @@ kernelDecompInfo decompKernel(InputArray kernel, Point anchor, int iterations)
     {
         _kernel.at<uchar>(0, 0) = 1;
     }
-    // Fix anchor to the center of the kernel.
-    anchor = stMorph::normalizeAnchor(anchor, _kernel.size());
-
 
     int rowDepthLim = log2(longestRowRunLength(_kernel)) + 1;
     int colDepthLim = log2(longestColRunLength(_kernel)) + 1;
@@ -246,11 +229,21 @@ kernelDecompInfo decompKernel(InputArray kernel, Point anchor, int iterations)
     Mat stPlan
         = sparseTableFillPlanning(pow2Rects, rowDepthLim, colDepthLim);
 
+    // Fix anchor to the center of the kernel.
     anchor = stMorph::normalizeAnchor(anchor, _kernel.size());
 
     return { _kernel.rows, _kernel.cols, pow2Rects, stPlan, anchor, iterations };
 }
 
+#pragma endregion
+
+#pragma region st-morphology
+
+enum Op
+{
+    Min, Max
+};
+
 void morphDfs(int minmax, Mat& st, Mat& dst,
     std::vector<std::vector<std::vector<Point>>> row2Rects, const Mat& stPlan,
     int rowDepth, int colDepth)
@@ -414,6 +407,10 @@ void morphologyEx(InputArray src, OutputArray dst, int op, kernelDecompInfo kdi,
     }
 }
 
+#pragma endregion
+
+#pragma region cv-morphology
+
 void erode(InputArray src, OutputArray dst, InputArray kernel,
     Point anchor, int iterations,
     BorderTypes borderType, const Scalar& borderVal)
@@ -438,4 +435,6 @@ void morphologyEx(InputArray src, OutputArray dst, int op,
     morphologyEx(src, dst, op, kdi, borderType, borderVal);
 }
 
+#pragma endregion
+
 }} // cv::stMorph::