1 /*M///////////////////////////////////////////////////////////////////////////////////////
2 //
3 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
4 //
5 //  By downloading, copying, installing or using the software you agree to this license.
6 //  If you do not agree to this license, do not download, install,
7 //  copy or use the software.
8 //
9 //
10 //                           License Agreement
11 //                For Open Source Computer Vision Library
12 //
13 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
14 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
15 // Third party copyrights are property of their respective owners.
16 //
17 // Redistribution and use in source and binary forms, with or without modification,
18 // are permitted provided that the following conditions are met:
19 //
20 //   * Redistribution's of source code must retain the above copyright notice,
21 //     this list of conditions and the following disclaimer.
22 //
23 //   * Redistribution's in binary form must reproduce the above copyright notice,
24 //     this list of conditions and the following disclaimer in the documentation
25 //     and/or other materials provided with the distribution.
26 //
27 //   * The name of the copyright holders may not be used to endorse or promote products
28 //     derived from this software without specific prior written permission.
29 //
30 // This software is provided by the copyright holders and contributors "as is" and
31 // any express or implied warranties, including, but not limited to, the implied
32 // warranties of merchantability and fitness for a particular purpose are disclaimed.
33 // In no event shall the Intel Corporation or contributors be liable for any direct,
34 // indirect, incidental, special, exemplary, or consequential damages
35 // (including, but not limited to, procurement of substitute goods or services;
36 // loss of use, data, or profits; or business interruption) however caused
37 // and on any theory of liability, whether in contract, strict liability,
38 // or tort (including negligence or otherwise) arising in any way out of
39 // the use of this software, even if advised of the possibility of such damage.
40 //
41 //M*/
42 
43 #ifndef __OPENCV_CUDASTEREO_HPP__
44 #define __OPENCV_CUDASTEREO_HPP__
45 
46 #ifndef __cplusplus
47 #  error cudastereo.hpp header must be compiled as C++
48 #endif
49 
50 #include "opencv2/core/cuda.hpp"
51 #include "opencv2/calib3d.hpp"
52 
53 /**
54   @addtogroup cuda
55   @{
56     @defgroup cudastereo Stereo Correspondence
57   @}
58  */
59 
60 namespace cv { namespace cuda {
61 
62 //! @addtogroup cudastereo
63 //! @{
64 
65 /////////////////////////////////////////
66 // StereoBM
67 
68 /** @brief Class computing stereo correspondence (disparity map) using the block matching algorithm. :
69 
70 @sa StereoBM
71  */
72 class CV_EXPORTS StereoBM : public cv::StereoBM
73 {
74 public:
75     using cv::StereoBM::compute;
76 
77     virtual void compute(InputArray left, InputArray right, OutputArray disparity, Stream& stream) = 0;
78 };
79 
80 /** @brief Creates StereoBM object.
81 
82 @param numDisparities the disparity search range. For each pixel algorithm will find the best
83 disparity from 0 (default minimum disparity) to numDisparities. The search range can then be
84 shifted by changing the minimum disparity.
85 @param blockSize the linear size of the blocks compared by the algorithm. The size should be odd
86 (as the block is centered at the current pixel). Larger block size implies smoother, though less
87 accurate disparity map. Smaller block size gives more detailed disparity map, but there is higher
88 chance for algorithm to find a wrong correspondence.
89  */
90 CV_EXPORTS Ptr<cuda::StereoBM> createStereoBM(int numDisparities = 64, int blockSize = 19);
91 
92 /////////////////////////////////////////
93 // StereoBeliefPropagation
94 
95 /** @brief Class computing stereo correspondence using the belief propagation algorithm. :
96 
97 The class implements algorithm described in @cite Felzenszwalb2006 . It can compute own data cost
98 (using a truncated linear model) or use a user-provided data cost.
99 
100 @note
101    StereoBeliefPropagation requires a lot of memory for message storage:
102 
103     \f[width \_ step  \cdot height  \cdot ndisp  \cdot 4  \cdot (1 + 0.25)\f]
104 
105     and for data cost storage:
106 
107     \f[width\_step \cdot height \cdot ndisp \cdot (1 + 0.25 + 0.0625 +  \dotsm + \frac{1}{4^{levels}})\f]
108 
109     width_step is the number of bytes in a line including padding.
110 
111 StereoBeliefPropagation uses a truncated linear model for the data cost and discontinuity terms:
112 
113 \f[DataCost = data \_ weight  \cdot \min ( \lvert Img_Left(x,y)-Img_Right(x-d,y)  \rvert , max \_ data \_ term)\f]
114 
115 \f[DiscTerm =  \min (disc \_ single \_ jump  \cdot \lvert f_1-f_2  \rvert , max \_ disc \_ term)\f]
116 
117 For more details, see @cite Felzenszwalb2006 .
118 
119 By default, StereoBeliefPropagation uses floating-point arithmetics and the CV_32FC1 type for
120 messages. But it can also use fixed-point arithmetics and the CV_16SC1 message type for better
121 performance. To avoid an overflow in this case, the parameters must satisfy the following
122 requirement:
123 
124 \f[10  \cdot 2^{levels-1}  \cdot max \_ data \_ term < SHRT \_ MAX\f]
125 
126 @sa StereoMatcher
127  */
128 class CV_EXPORTS StereoBeliefPropagation : public cv::StereoMatcher
129 {
130 public:
131     using cv::StereoMatcher::compute;
132 
133     /** @overload */
134     virtual void compute(InputArray left, InputArray right, OutputArray disparity, Stream& stream) = 0;
135 
136     /** @brief Enables the stereo correspondence operator that finds the disparity for the specified data cost.
137 
138     @param data User-specified data cost, a matrix of msg_type type and
139     Size(\<image columns\>\*ndisp, \<image rows\>) size.
140     @param disparity Output disparity map. If disparity is empty, the output type is CV_16SC1 .
141     Otherwise, the type is retained.
142     @param stream Stream for the asynchronous version.
143      */
144     virtual void compute(InputArray data, OutputArray disparity, Stream& stream = Stream::Null()) = 0;
145 
146     //! number of BP iterations on each level
147     virtual int getNumIters() const = 0;
148     virtual void setNumIters(int iters) = 0;
149 
150     //! number of levels
151     virtual int getNumLevels() const = 0;
152     virtual void setNumLevels(int levels) = 0;
153 
154     //! truncation of data cost
155     virtual double getMaxDataTerm() const = 0;
156     virtual void setMaxDataTerm(double max_data_term) = 0;
157 
158     //! data weight
159     virtual double getDataWeight() const = 0;
160     virtual void setDataWeight(double data_weight) = 0;
161 
162     //! truncation of discontinuity cost
163     virtual double getMaxDiscTerm() const = 0;
164     virtual void setMaxDiscTerm(double max_disc_term) = 0;
165 
166     //! discontinuity single jump
167     virtual double getDiscSingleJump() const = 0;
168     virtual void setDiscSingleJump(double disc_single_jump) = 0;
169 
170     //! type for messages (CV_16SC1 or CV_32FC1)
171     virtual int getMsgType() const = 0;
172     virtual void setMsgType(int msg_type) = 0;
173 
174     /** @brief Uses a heuristic method to compute the recommended parameters ( ndisp, iters and levels ) for the
175     specified image size ( width and height ).
176      */
177     static void estimateRecommendedParams(int width, int height, int& ndisp, int& iters, int& levels);
178 };
179 
180 /** @brief Creates StereoBeliefPropagation object.
181 
182 @param ndisp Number of disparities.
183 @param iters Number of BP iterations on each level.
184 @param levels Number of levels.
185 @param msg_type Type for messages. CV_16SC1 and CV_32FC1 types are supported.
186  */
187 CV_EXPORTS Ptr<cuda::StereoBeliefPropagation>
188     createStereoBeliefPropagation(int ndisp = 64, int iters = 5, int levels = 5, int msg_type = CV_32F);
189 
190 /////////////////////////////////////////
191 // StereoConstantSpaceBP
192 
193 /** @brief Class computing stereo correspondence using the constant space belief propagation algorithm. :
194 
195 The class implements algorithm described in @cite Yang2010 . StereoConstantSpaceBP supports both local
196 minimum and global minimum data cost initialization algorithms. For more details, see the paper
197 mentioned above. By default, a local algorithm is used. To enable a global algorithm, set
198 use_local_init_data_cost to false .
199 
200 StereoConstantSpaceBP uses a truncated linear model for the data cost and discontinuity terms:
201 
202 \f[DataCost = data \_ weight  \cdot \min ( \lvert I_2-I_1  \rvert , max \_ data \_ term)\f]
203 
204 \f[DiscTerm =  \min (disc \_ single \_ jump  \cdot \lvert f_1-f_2  \rvert , max \_ disc \_ term)\f]
205 
206 For more details, see @cite Yang2010 .
207 
208 By default, StereoConstantSpaceBP uses floating-point arithmetics and the CV_32FC1 type for
209 messages. But it can also use fixed-point arithmetics and the CV_16SC1 message type for better
210 performance. To avoid an overflow in this case, the parameters must satisfy the following
211 requirement:
212 
213 \f[10  \cdot 2^{levels-1}  \cdot max \_ data \_ term < SHRT \_ MAX\f]
214 
215  */
216 class CV_EXPORTS StereoConstantSpaceBP : public cuda::StereoBeliefPropagation
217 {
218 public:
219     //! number of active disparity on the first level
220     virtual int getNrPlane() const = 0;
221     virtual void setNrPlane(int nr_plane) = 0;
222 
223     virtual bool getUseLocalInitDataCost() const = 0;
224     virtual void setUseLocalInitDataCost(bool use_local_init_data_cost) = 0;
225 
226     /** @brief Uses a heuristic method to compute parameters (ndisp, iters, levelsand nrplane) for the specified
227     image size (widthand height).
228      */
229     static void estimateRecommendedParams(int width, int height, int& ndisp, int& iters, int& levels, int& nr_plane);
230 };
231 
232 /** @brief Creates StereoConstantSpaceBP object.
233 
234 @param ndisp Number of disparities.
235 @param iters Number of BP iterations on each level.
236 @param levels Number of levels.
237 @param nr_plane Number of disparity levels on the first level.
238 @param msg_type Type for messages. CV_16SC1 and CV_32FC1 types are supported.
239  */
240 CV_EXPORTS Ptr<cuda::StereoConstantSpaceBP>
241     createStereoConstantSpaceBP(int ndisp = 128, int iters = 8, int levels = 4, int nr_plane = 4, int msg_type = CV_32F);
242 
243 /////////////////////////////////////////
244 // DisparityBilateralFilter
245 
246 /** @brief Class refining a disparity map using joint bilateral filtering. :
247 
248 The class implements @cite Yang2010 algorithm.
249  */
250 class CV_EXPORTS DisparityBilateralFilter : public cv::Algorithm
251 {
252 public:
253     /** @brief Refines a disparity map using joint bilateral filtering.
254 
255     @param disparity Input disparity map. CV_8UC1 and CV_16SC1 types are supported.
256     @param image Input image. CV_8UC1 and CV_8UC3 types are supported.
257     @param dst Destination disparity map. It has the same size and type as disparity .
258     @param stream Stream for the asynchronous version.
259      */
260     virtual void apply(InputArray disparity, InputArray image, OutputArray dst, Stream& stream = Stream::Null()) = 0;
261 
262     virtual int getNumDisparities() const = 0;
263     virtual void setNumDisparities(int numDisparities) = 0;
264 
265     virtual int getRadius() const = 0;
266     virtual void setRadius(int radius) = 0;
267 
268     virtual int getNumIters() const = 0;
269     virtual void setNumIters(int iters) = 0;
270 
271     //! truncation of data continuity
272     virtual double getEdgeThreshold() const = 0;
273     virtual void setEdgeThreshold(double edge_threshold) = 0;
274 
275     //! truncation of disparity continuity
276     virtual double getMaxDiscThreshold() const = 0;
277     virtual void setMaxDiscThreshold(double max_disc_threshold) = 0;
278 
279     //! filter range sigma
280     virtual double getSigmaRange() const = 0;
281     virtual void setSigmaRange(double sigma_range) = 0;
282 };
283 
284 /** @brief Creates DisparityBilateralFilter object.
285 
286 @param ndisp Number of disparities.
287 @param radius Filter radius.
288 @param iters Number of iterations.
289  */
290 CV_EXPORTS Ptr<cuda::DisparityBilateralFilter>
291     createDisparityBilateralFilter(int ndisp = 64, int radius = 3, int iters = 1);
292 
293 /////////////////////////////////////////
294 // Utility
295 
296 /** @brief Reprojects a disparity image to 3D space.
297 
298 @param disp Input disparity image. CV_8U and CV_16S types are supported.
299 @param xyzw Output 3- or 4-channel floating-point image of the same size as disp . Each element of
300 xyzw(x,y) contains 3D coordinates (x,y,z) or (x,y,z,1) of the point (x,y) , computed from the
301 disparity map.
302 @param Q \f$4 \times 4\f$ perspective transformation matrix that can be obtained via stereoRectify .
303 @param dst_cn The number of channels for output image. Can be 3 or 4.
304 @param stream Stream for the asynchronous version.
305 
306 @sa reprojectImageTo3D
307  */
308 CV_EXPORTS void reprojectImageTo3D(InputArray disp, OutputArray xyzw, InputArray Q, int dst_cn = 4, Stream& stream = Stream::Null());
309 
310 /** @brief Colors a disparity image.
311 
312 @param src_disp Source disparity image. CV_8UC1 and CV_16SC1 types are supported.
313 @param dst_disp Output disparity image. It has the same size as src_disp . The type is CV_8UC4
314 in BGRA format (alpha = 255).
315 @param ndisp Number of disparities.
316 @param stream Stream for the asynchronous version.
317 
318 This function draws a colored disparity map by converting disparity values from [0..ndisp) interval
319 first to HSV color space (where different disparity values correspond to different hues) and then
320 converting the pixels to RGB for visualization.
321  */
322 CV_EXPORTS void drawColorDisp(InputArray src_disp, OutputArray dst_disp, int ndisp, Stream& stream = Stream::Null());
323 
324 //! @}
325 
326 }} // namespace cv { namespace cuda {
327 
328 #endif /* __OPENCV_CUDASTEREO_HPP__ */
329