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_DISPARITYFILTER_HPP__ 38 #define __OPENCV_DISPARITYFILTER_HPP__ 39 #ifdef __cplusplus 40 41 #include <opencv2/core.hpp> 42 #include <opencv2/calib3d.hpp> 43 44 namespace cv { 45 namespace ximgproc { 46 47 //! @addtogroup ximgproc_filters 48 //! @{ 49 50 /** @brief Main interface for all disparity map filters. 51 */ 52 class CV_EXPORTS_W DisparityFilter : public Algorithm 53 { 54 public: 55 56 /** @brief Apply filtering to the disparity map. 57 58 @param disparity_map_left disparity map of the left view, 1 channel, CV_16S type. Implicitly assumes that disparity 59 values are scaled by 16 (one-pixel disparity corresponds to the value of 16 in the disparity map). Disparity map 60 can have any resolution, it will be automatically resized to fit left_view resolution. 61 62 @param left_view left view of the original stereo-pair to guide the filtering process, 8-bit single-channel 63 or three-channel image. 64 65 @param filtered_disparity_map output disparity map. 66 67 @param disparity_map_right optional argument, some implementations might also use the disparity map 68 of the right view to compute confidence maps, for instance. 69 70 @param ROI region of the disparity map to filter. Optional, usually it should be set automatically. 71 72 @param right_view optional argument, some implementations might also use the right view of the original 73 stereo-pair. 74 */ 75 CV_WRAP virtual void filter(InputArray disparity_map_left, InputArray left_view, OutputArray filtered_disparity_map, InputArray disparity_map_right = Mat(), Rect ROI = Rect(), InputArray right_view = Mat()) = 0; 76 }; 77 78 /** @brief Disparity map filter based on Weighted Least Squares filter (in form of Fast Global Smoother that 79 is a lot faster than traditional Weighted Least Squares filter implementations) and optional use of 80 left-right-consistency-based confidence to refine the results in half-occlusions and uniform areas. 81 */ 82 class CV_EXPORTS_W DisparityWLSFilter : public DisparityFilter 83 { 84 public: 85 /** filter parameters */ 86 87 /** @brief Lambda is a parameter defining the amount of regularization during filtering. Larger values force 88 filtered disparity map edges to adhere more to source image edges. Typical value is 8000. 89 */ 90 CV_WRAP virtual double getLambda() = 0; 91 /** @see getLambda */ 92 CV_WRAP virtual void setLambda(double _lambda) = 0; 93 /** @brief SigmaColor is a parameter defining how sensitive the filtering process is to source image edges. 94 Large values can lead to disparity leakage through low-contrast edges. Small values can make the filter too 95 sensitive to noise and textures in the source image. Typical values range from 0.8 to 2.0. 96 */ 97 CV_WRAP virtual double getSigmaColor() = 0; 98 /** @see getSigmaColor */ 99 CV_WRAP virtual void setSigmaColor(double _sigma_color) = 0; 100 101 /** confidence-related parameters */ 102 103 /** @brief LRCthresh is a threshold of disparity difference used in left-right-consistency check during 104 confidence map computation. The default value of 24 (1.5 pixels) is virtually always good enough. 105 */ 106 CV_WRAP virtual int getLRCthresh() = 0; 107 /** @see getLRCthresh */ 108 CV_WRAP virtual void setLRCthresh(int _LRC_thresh) = 0; 109 /** @brief DepthDiscontinuityRadius is a parameter used in confidence computation. It defines the size of 110 low-confidence regions around depth discontinuities. 111 */ 112 CV_WRAP virtual int getDepthDiscontinuityRadius() = 0; 113 /** @see getDepthDiscontinuityRadius */ 114 CV_WRAP virtual void setDepthDiscontinuityRadius(int _disc_radius) = 0; 115 /** @brief Get the confidence map that was used in the last filter call. It is a CV_32F one-channel image 116 with values ranging from 0.0 (totally untrusted regions of the raw disparity map) to 255.0 (regions containing 117 correct disparity values with a high degree of confidence). 118 */ 119 CV_WRAP virtual Mat getConfidenceMap() = 0; 120 /** @brief Get the ROI used in the last filter call 121 */ 122 CV_WRAP virtual Rect getROI() = 0; 123 }; 124 125 /** @brief Convenience factory method that creates an instance of DisparityWLSFilter and sets up all the relevant 126 filter parameters automatically based on the matcher instance. Currently supports only StereoBM and StereoSGBM. 127 128 @param matcher_left stereo matcher instance that will be used with the filter 129 */ 130 CV_EXPORTS_W 131 Ptr<DisparityWLSFilter> createDisparityWLSFilter(Ptr<StereoMatcher> matcher_left); 132 133 /** @brief Convenience method to set up the matcher for computing the right-view disparity map 134 that is required in case of filtering with confidence. 135 136 @param matcher_left main stereo matcher instance that will be used with the filter 137 */ 138 CV_EXPORTS_W 139 Ptr<StereoMatcher> createRightMatcher(Ptr<StereoMatcher> matcher_left); 140 141 /** @brief More generic factory method, create instance of DisparityWLSFilter and execute basic 142 initialization routines. When using this method you will need to set-up the ROI, matchers and 143 other parameters by yourself. 144 145 @param use_confidence filtering with confidence requires two disparity maps (for the left and right views) and is 146 approximately two times slower. However, quality is typically significantly better. 147 */ 148 CV_EXPORTS_W 149 Ptr<DisparityWLSFilter> createDisparityWLSFilterGeneric(bool use_confidence); 150 151 ////////////////////////////////////////////////////////////////////////// 152 ////////////////////////////////////////////////////////////////////////// 153 154 /** @brief Function for reading ground truth disparity maps. Supports basic Middlebury 155 and MPI-Sintel formats. Note that the resulting disparity map is scaled by 16. 156 157 @param src_path path to the image, containing ground-truth disparity map 158 159 @param dst output disparity map, CV_16S depth 160 161 @result returns zero if successfully read the ground truth 162 */ 163 CV_EXPORTS_W 164 int readGT(String src_path,OutputArray dst); 165 166 /** @brief Function for computing mean square error for disparity maps 167 168 @param GT ground truth disparity map 169 170 @param src disparity map to evaluate 171 172 @param ROI region of interest 173 174 @result returns mean square error between GT and src 175 */ 176 CV_EXPORTS_W 177 double computeMSE(InputArray GT, InputArray src, Rect ROI); 178 179 /** @brief Function for computing the percent of "bad" pixels in the disparity map 180 (pixels where error is higher than a specified threshold) 181 182 @param GT ground truth disparity map 183 184 @param src disparity map to evaluate 185 186 @param ROI region of interest 187 188 @param thresh threshold used to determine "bad" pixels 189 190 @result returns mean square error between GT and src 191 */ 192 CV_EXPORTS_W 193 double computeBadPixelPercent(InputArray GT, InputArray src, Rect ROI, int thresh=24/*1.5 pixels*/); 194 195 /** @brief Function for creating a disparity map visualization (clamped CV_8U image) 196 197 @param src input disparity map (CV_16S depth) 198 199 @param dst output visualization 200 201 @param scale disparity map will be multiplied by this value for visualization 202 */ 203 CV_EXPORTS_W 204 void getDisparityVis(InputArray src,OutputArray dst,double scale=1.0); 205 206 //! @} 207 } 208 } 209 #endif 210 #endif 211