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