1 /* 2 * By downloading, copying, installing or using the software you agree to this license. 3 * If you do not agree to this license, do not download, install, 4 * copy or use the software. 5 * 6 * 7 * License Agreement 8 * For Open Source Computer Vision Library 9 * (3 - clause BSD License) 10 * 11 * Redistribution and use in source and binary forms, with or without modification, 12 * are permitted provided that the following conditions are met : 13 * 14 * * Redistributions of source code must retain the above copyright notice, 15 * this list of conditions and the following disclaimer. 16 * 17 * * Redistributions in binary form must reproduce the above copyright notice, 18 * this list of conditions and the following disclaimer in the documentation 19 * and / or other materials provided with the distribution. 20 * 21 * * Neither the names of the copyright holders nor the names of the contributors 22 * may be used to endorse or promote products derived from this software 23 * without specific prior written permission. 24 * 25 * This software is provided by the copyright holders and contributors "as is" and 26 * any express or implied warranties, including, but not limited to, the implied 27 * warranties of merchantability and fitness for a particular purpose are disclaimed. 28 * In no event shall copyright holders or contributors be liable for any direct, 29 * indirect, incidental, special, exemplary, or consequential damages 30 * (including, but not limited to, procurement of substitute goods or services; 31 * loss of use, data, or profits; or business interruption) however caused 32 * and on any theory of liability, whether in contract, strict liability, 33 * or tort(including negligence or otherwise) arising in any way out of 34 * the use of this software, even if advised of the possibility of such damage. 35 */ 36 37 #ifndef __OPENCV_SPARSEMATCHINTERPOLATOR_HPP__ 38 #define __OPENCV_SPARSEMATCHINTERPOLATOR_HPP__ 39 #ifdef __cplusplus 40 41 #include <opencv2/core.hpp> 42 43 namespace cv { 44 namespace ximgproc { 45 46 //! @addtogroup ximgproc_filters 47 //! @{ 48 49 /** @brief Main interface for all filters, that take sparse matches as an 50 input and produce a dense per-pixel matching (optical flow) as an output. 51 */ 52 class CV_EXPORTS_W SparseMatchInterpolator : public Algorithm 53 { 54 public: 55 /** @brief Interpolate input sparse matches. 56 57 @param from_image first of the two matched images, 8-bit single-channel or three-channel. 58 59 @param from_points points of the from_image for which there are correspondences in the 60 to_image (Point2f vector or Mat of depth CV_32F) 61 62 @param to_image second of the two matched images, 8-bit single-channel or three-channel. 63 64 @param to_points points in the to_image corresponding to from_points 65 (Point2f vector or Mat of depth CV_32F) 66 67 @param dense_flow output dense matching (two-channel CV_32F image) 68 */ 69 CV_WRAP virtual void interpolate(InputArray from_image, InputArray from_points, 70 InputArray to_image , InputArray to_points, 71 OutputArray dense_flow) = 0; 72 }; 73 74 /** @brief Sparse match interpolation algorithm based on modified locally-weighted affine 75 estimator from @cite Revaud2015 and Fast Global Smoother as post-processing filter. 76 */ 77 class CV_EXPORTS_W EdgeAwareInterpolator : public SparseMatchInterpolator 78 { 79 public: 80 /** @brief Interface to provide a more elaborated cost map, i.e. edge map, for the edge-aware term. 81 * This implementation is based on a rather simple gradient-based edge map estimation. 82 * To used more complex edge map estimator (e.g. StructuredEdgeDetection that has been 83 * used in the original publication) that may lead to improved accuracies, the internal 84 * edge map estimation can be bypassed here. 85 * @param _costMap a type CV_32FC1 Mat is required. 86 * @see cv::ximgproc::createSuperpixelSLIC 87 */ 88 CV_WRAP virtual void setCostMap(const Mat & _costMap) = 0; 89 /** @brief Parameter to tune the approximate size of the superpixel used for oversegmentation. 90 * @see cv::ximgproc::createSuperpixelSLIC 91 */ 92 /** @brief K is a number of nearest-neighbor matches considered, when fitting a locally affine 93 model. Usually it should be around 128. However, lower values would make the interpolation 94 noticeably faster. 95 */ 96 CV_WRAP virtual void setK(int _k) = 0; 97 /** @see setK */ 98 CV_WRAP virtual int getK() = 0; 99 100 /** @brief Sigma is a parameter defining how fast the weights decrease in the locally-weighted affine 101 fitting. Higher values can help preserve fine details, lower values can help to get rid of noise in the 102 output flow. 103 */ 104 CV_WRAP virtual void setSigma(float _sigma) = 0; 105 /** @see setSigma */ 106 CV_WRAP virtual float getSigma() = 0; 107 108 /** @brief Lambda is a parameter defining the weight of the edge-aware term in geodesic distance, 109 should be in the range of 0 to 1000. 110 */ 111 CV_WRAP virtual void setLambda(float _lambda) = 0; 112 /** @see setLambda */ 113 CV_WRAP virtual float getLambda() = 0; 114 115 /** @brief Sets whether the fastGlobalSmootherFilter() post-processing is employed. It is turned on by 116 default. 117 */ 118 CV_WRAP virtual void setUsePostProcessing(bool _use_post_proc) = 0; 119 /** @see setUsePostProcessing */ 120 CV_WRAP virtual bool getUsePostProcessing() = 0; 121 122 /** @brief Sets the respective fastGlobalSmootherFilter() parameter. 123 */ 124 CV_WRAP virtual void setFGSLambda(float _lambda) = 0; 125 /** @see setFGSLambda */ 126 CV_WRAP virtual float getFGSLambda() = 0; 127 128 /** @see setFGSLambda */ 129 CV_WRAP virtual void setFGSSigma(float _sigma) = 0; 130 /** @see setFGSLambda */ 131 CV_WRAP virtual float getFGSSigma() = 0; 132 }; 133 134 /** @brief Factory method that creates an instance of the 135 EdgeAwareInterpolator. 136 */ 137 CV_EXPORTS_W 138 Ptr<EdgeAwareInterpolator> createEdgeAwareInterpolator(); 139 140 /** @brief Sparse match interpolation algorithm based on modified piecewise locally-weighted affine 141 * estimator called Robust Interpolation method of Correspondences or RIC from @cite Hu2017 and Variational 142 * and Fast Global Smoother as post-processing filter. The RICInterpolator is a extension of the EdgeAwareInterpolator. 143 * Main concept of this extension is an piece-wise affine model based on over-segmentation via SLIC superpixel estimation. 144 * The method contains an efficient propagation mechanism to estimate among the pieces-wise models. 145 */ 146 class CV_EXPORTS_W RICInterpolator : public SparseMatchInterpolator 147 { 148 public: 149 /** @brief K is a number of nearest-neighbor matches considered, when fitting a locally affine 150 *model for a superpixel segment. However, lower values would make the interpolation 151 *noticeably faster. The original implementation of @cite Hu2017 uses 32. 152 */ 153 CV_WRAP virtual void setK(int k = 32) = 0; 154 /** @copybrief setK 155 * @see setK 156 */ 157 CV_WRAP virtual int getK() const = 0; 158 /** @brief Interface to provide a more elaborated cost map, i.e. edge map, for the edge-aware term. 159 * This implementation is based on a rather simple gradient-based edge map estimation. 160 * To used more complex edge map estimator (e.g. StructuredEdgeDetection that has been 161 * used in the original publication) that may lead to improved accuracies, the internal 162 * edge map estimation can be bypassed here. 163 * @param costMap a type CV_32FC1 Mat is required. 164 * @see cv::ximgproc::createSuperpixelSLIC 165 */ 166 CV_WRAP virtual void setCostMap(const Mat & costMap) = 0; 167 /** @brief Get the internal cost, i.e. edge map, used for estimating the edge-aware term. 168 * @see setCostMap 169 */ 170 CV_WRAP virtual void setSuperpixelSize(int spSize = 15) = 0; 171 /** @copybrief setSuperpixelSize 172 * @see setSuperpixelSize 173 */ 174 CV_WRAP virtual int getSuperpixelSize() const = 0; 175 /** @brief Parameter defines the number of nearest-neighbor matches for each superpixel considered, when fitting a locally affine 176 *model. 177 */ 178 CV_WRAP virtual void setSuperpixelNNCnt(int spNN = 150) = 0; 179 /** @copybrief setSuperpixelNNCnt 180 * @see setSuperpixelNNCnt 181 */ 182 CV_WRAP virtual int getSuperpixelNNCnt() const = 0; 183 /** @brief Parameter to tune enforcement of superpixel smoothness factor used for oversegmentation. 184 * @see cv::ximgproc::createSuperpixelSLIC 185 */ 186 CV_WRAP virtual void setSuperpixelRuler(float ruler = 15.f) = 0; 187 /** @copybrief setSuperpixelRuler 188 * @see setSuperpixelRuler 189 */ 190 CV_WRAP virtual float getSuperpixelRuler() const = 0; 191 /** @brief Parameter to choose superpixel algorithm variant to use: 192 * - cv::ximgproc::SLICType SLIC segments image using a desired region_size (value: 100) 193 * - cv::ximgproc::SLICType SLICO will optimize using adaptive compactness factor (value: 101) 194 * - cv::ximgproc::SLICType MSLIC will optimize using manifold methods resulting in more content-sensitive superpixels (value: 102). 195 * @see cv::ximgproc::createSuperpixelSLIC 196 */ 197 CV_WRAP virtual void setSuperpixelMode(int mode = 100) = 0; 198 /** @copybrief setSuperpixelMode 199 * @see setSuperpixelMode 200 */ 201 CV_WRAP virtual int getSuperpixelMode() const = 0; 202 /** @brief Alpha is a parameter defining a global weight for transforming geodesic distance into weight. 203 */ 204 CV_WRAP virtual void setAlpha(float alpha = 0.7f) = 0; 205 /** @copybrief setAlpha 206 * @see setAlpha 207 */ 208 CV_WRAP virtual float getAlpha() const = 0; 209 /** @brief Parameter defining the number of iterations for piece-wise affine model estimation. 210 */ 211 CV_WRAP virtual void setModelIter(int modelIter = 4) = 0; 212 /** @copybrief setModelIter 213 * @see setModelIter 214 */ 215 CV_WRAP virtual int getModelIter() const = 0; 216 /** @brief Parameter to choose wether additional refinement of the piece-wise affine models is employed. 217 */ 218 CV_WRAP virtual void setRefineModels(bool refineModles = true) = 0; 219 /** @copybrief setRefineModels 220 * @see setRefineModels 221 */ 222 CV_WRAP virtual bool getRefineModels() const = 0; 223 /** @brief MaxFlow is a threshold to validate the predictions using a certain piece-wise affine model. 224 * If the prediction exceeds the treshold the translational model will be applied instead. 225 */ 226 CV_WRAP virtual void setMaxFlow(float maxFlow = 250.f) = 0; 227 /** @copybrief setMaxFlow 228 * @see setMaxFlow 229 */ 230 CV_WRAP virtual float getMaxFlow() const = 0; 231 /** @brief Parameter to choose wether the VariationalRefinement post-processing is employed. 232 */ 233 CV_WRAP virtual void setUseVariationalRefinement(bool use_variational_refinement = false) = 0; 234 /** @copybrief setUseVariationalRefinement 235 * @see setUseVariationalRefinement 236 */ 237 CV_WRAP virtual bool getUseVariationalRefinement() const = 0; 238 /** @brief Sets whether the fastGlobalSmootherFilter() post-processing is employed. 239 */ 240 CV_WRAP virtual void setUseGlobalSmootherFilter(bool use_FGS = true) = 0; 241 /** @copybrief setUseGlobalSmootherFilter 242 * @see setUseGlobalSmootherFilter 243 */ 244 CV_WRAP virtual bool getUseGlobalSmootherFilter() const = 0; 245 /** @brief Sets the respective fastGlobalSmootherFilter() parameter. 246 */ 247 CV_WRAP virtual void setFGSLambda(float lambda = 500.f) = 0; 248 /** @copybrief setFGSLambda 249 * @see setFGSLambda 250 */ 251 CV_WRAP virtual float getFGSLambda() const = 0; 252 /** @brief Sets the respective fastGlobalSmootherFilter() parameter. 253 */ 254 CV_WRAP virtual void setFGSSigma(float sigma = 1.5f) = 0; 255 /** @copybrief setFGSSigma 256 * @see setFGSSigma 257 */ 258 CV_WRAP virtual float getFGSSigma() const = 0; 259 }; 260 261 /** @brief Factory method that creates an instance of the 262 RICInterpolator. 263 */ 264 CV_EXPORTS_W 265 Ptr<RICInterpolator> createRICInterpolator(); 266 //! @} 267 } 268 } 269 #endif 270 #endif 271