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 // Copyright (C) 2013, OpenCV Foundation, all rights reserved. 16 // Third party copyrights are property of their respective owners. 17 // 18 // Redistribution and use in source and binary forms, with or without modification, 19 // are permitted provided that the following conditions are met: 20 // 21 // * Redistribution's of source code must retain the above copyright notice, 22 // this list of conditions and the following disclaimer. 23 // 24 // * Redistribution's in binary form must reproduce the above copyright notice, 25 // this list of conditions and the following disclaimer in the documentation 26 // and/or other materials provided with the distribution. 27 // 28 // * The name of the copyright holders may not be used to endorse or promote products 29 // derived from this software without specific prior written permission. 30 // 31 // This software is provided by the copyright holders and contributors "as is" and 32 // any express or implied warranties, including, but not limited to, the implied 33 // warranties of merchantability and fitness for a particular purpose are disclaimed. 34 // In no event shall the Intel Corporation or contributors be liable for any direct, 35 // indirect, incidental, special, exemplary, or consequential damages 36 // (including, but not limited to, procurement of substitute goods or services; 37 // loss of use, data, or profits; or business interruption) however caused 38 // and on any theory of liability, whether in contract, strict liability, 39 // or tort (including negligence or otherwise) arising in any way out of 40 // the use of this software, even if advised of the possibility of such damage. 41 // 42 //M*/ 43 44 #ifndef __OPENCV_BACKGROUND_SEGM_HPP__ 45 #define __OPENCV_BACKGROUND_SEGM_HPP__ 46 47 #include "opencv2/core.hpp" 48 49 namespace cv 50 { 51 52 //! @addtogroup video_motion 53 //! @{ 54 55 /** @brief Base class for background/foreground segmentation. : 56 57 The class is only used to define the common interface for the whole family of background/foreground 58 segmentation algorithms. 59 */ 60 class CV_EXPORTS_W BackgroundSubtractor : public Algorithm 61 { 62 public: 63 /** @brief Computes a foreground mask. 64 65 @param image Next video frame. 66 @param fgmask The output foreground mask as an 8-bit binary image. 67 @param learningRate The value between 0 and 1 that indicates how fast the background model is 68 learnt. Negative parameter value makes the algorithm to use some automatically chosen learning 69 rate. 0 means that the background model is not updated at all, 1 means that the background model 70 is completely reinitialized from the last frame. 71 */ 72 CV_WRAP virtual void apply(InputArray image, OutputArray fgmask, double learningRate=-1) = 0; 73 74 /** @brief Computes a background image. 75 76 @param backgroundImage The output background image. 77 78 @note Sometimes the background image can be very blurry, as it contain the average background 79 statistics. 80 */ 81 CV_WRAP virtual void getBackgroundImage(OutputArray backgroundImage) const = 0; 82 }; 83 84 85 /** @brief Gaussian Mixture-based Background/Foreground Segmentation Algorithm. 86 87 The class implements the Gaussian mixture model background subtraction described in @cite Zivkovic2004 88 and @cite Zivkovic2006 . 89 */ 90 class CV_EXPORTS_W BackgroundSubtractorMOG2 : public BackgroundSubtractor 91 { 92 public: 93 /** @brief Returns the number of last frames that affect the background model 94 */ 95 CV_WRAP virtual int getHistory() const = 0; 96 /** @brief Sets the number of last frames that affect the background model 97 */ 98 CV_WRAP virtual void setHistory(int history) = 0; 99 100 /** @brief Returns the number of gaussian components in the background model 101 */ 102 CV_WRAP virtual int getNMixtures() const = 0; 103 /** @brief Sets the number of gaussian components in the background model. 104 105 The model needs to be reinitalized to reserve memory. 106 */ 107 CV_WRAP virtual void setNMixtures(int nmixtures) = 0;//needs reinitialization! 108 109 /** @brief Returns the "background ratio" parameter of the algorithm 110 111 If a foreground pixel keeps semi-constant value for about backgroundRatio\*history frames, it's 112 considered background and added to the model as a center of a new component. It corresponds to TB 113 parameter in the paper. 114 */ 115 CV_WRAP virtual double getBackgroundRatio() const = 0; 116 /** @brief Sets the "background ratio" parameter of the algorithm 117 */ 118 CV_WRAP virtual void setBackgroundRatio(double ratio) = 0; 119 120 /** @brief Returns the variance threshold for the pixel-model match 121 122 The main threshold on the squared Mahalanobis distance to decide if the sample is well described by 123 the background model or not. Related to Cthr from the paper. 124 */ 125 CV_WRAP virtual double getVarThreshold() const = 0; 126 /** @brief Sets the variance threshold for the pixel-model match 127 */ 128 CV_WRAP virtual void setVarThreshold(double varThreshold) = 0; 129 130 /** @brief Returns the variance threshold for the pixel-model match used for new mixture component generation 131 132 Threshold for the squared Mahalanobis distance that helps decide when a sample is close to the 133 existing components (corresponds to Tg in the paper). If a pixel is not close to any component, it 134 is considered foreground or added as a new component. 3 sigma =\> Tg=3\*3=9 is default. A smaller Tg 135 value generates more components. A higher Tg value may result in a small number of components but 136 they can grow too large. 137 */ 138 CV_WRAP virtual double getVarThresholdGen() const = 0; 139 /** @brief Sets the variance threshold for the pixel-model match used for new mixture component generation 140 */ 141 CV_WRAP virtual void setVarThresholdGen(double varThresholdGen) = 0; 142 143 /** @brief Returns the initial variance of each gaussian component 144 */ 145 CV_WRAP virtual double getVarInit() const = 0; 146 /** @brief Sets the initial variance of each gaussian component 147 */ 148 CV_WRAP virtual void setVarInit(double varInit) = 0; 149 150 CV_WRAP virtual double getVarMin() const = 0; 151 CV_WRAP virtual void setVarMin(double varMin) = 0; 152 153 CV_WRAP virtual double getVarMax() const = 0; 154 CV_WRAP virtual void setVarMax(double varMax) = 0; 155 156 /** @brief Returns the complexity reduction threshold 157 158 This parameter defines the number of samples needed to accept to prove the component exists. CT=0.05 159 is a default value for all the samples. By setting CT=0 you get an algorithm very similar to the 160 standard Stauffer&Grimson algorithm. 161 */ 162 CV_WRAP virtual double getComplexityReductionThreshold() const = 0; 163 /** @brief Sets the complexity reduction threshold 164 */ 165 CV_WRAP virtual void setComplexityReductionThreshold(double ct) = 0; 166 167 /** @brief Returns the shadow detection flag 168 169 If true, the algorithm detects shadows and marks them. See createBackgroundSubtractorMOG2 for 170 details. 171 */ 172 CV_WRAP virtual bool getDetectShadows() const = 0; 173 /** @brief Enables or disables shadow detection 174 */ 175 CV_WRAP virtual void setDetectShadows(bool detectShadows) = 0; 176 177 /** @brief Returns the shadow value 178 179 Shadow value is the value used to mark shadows in the foreground mask. Default value is 127. Value 0 180 in the mask always means background, 255 means foreground. 181 */ 182 CV_WRAP virtual int getShadowValue() const = 0; 183 /** @brief Sets the shadow value 184 */ 185 CV_WRAP virtual void setShadowValue(int value) = 0; 186 187 /** @brief Returns the shadow threshold 188 189 A shadow is detected if pixel is a darker version of the background. The shadow threshold (Tau in 190 the paper) is a threshold defining how much darker the shadow can be. Tau= 0.5 means that if a pixel 191 is more than twice darker then it is not shadow. See Prati, Mikic, Trivedi and Cucchiarra, 192 *Detecting Moving Shadows...*, IEEE PAMI,2003. 193 */ 194 CV_WRAP virtual double getShadowThreshold() const = 0; 195 /** @brief Sets the shadow threshold 196 */ 197 CV_WRAP virtual void setShadowThreshold(double threshold) = 0; 198 }; 199 200 /** @brief Creates MOG2 Background Subtractor 201 202 @param history Length of the history. 203 @param varThreshold Threshold on the squared Mahalanobis distance between the pixel and the model 204 to decide whether a pixel is well described by the background model. This parameter does not 205 affect the background update. 206 @param detectShadows If true, the algorithm will detect shadows and mark them. It decreases the 207 speed a bit, so if you do not need this feature, set the parameter to false. 208 */ 209 CV_EXPORTS_W Ptr<BackgroundSubtractorMOG2> 210 createBackgroundSubtractorMOG2(int history=500, double varThreshold=16, 211 bool detectShadows=true); 212 213 /** @brief K-nearest neigbours - based Background/Foreground Segmentation Algorithm. 214 215 The class implements the K-nearest neigbours background subtraction described in @cite Zivkovic2006 . 216 Very efficient if number of foreground pixels is low. 217 */ 218 class CV_EXPORTS_W BackgroundSubtractorKNN : public BackgroundSubtractor 219 { 220 public: 221 /** @brief Returns the number of last frames that affect the background model 222 */ 223 CV_WRAP virtual int getHistory() const = 0; 224 /** @brief Sets the number of last frames that affect the background model 225 */ 226 CV_WRAP virtual void setHistory(int history) = 0; 227 228 /** @brief Returns the number of data samples in the background model 229 */ 230 CV_WRAP virtual int getNSamples() const = 0; 231 /** @brief Sets the number of data samples in the background model. 232 233 The model needs to be reinitalized to reserve memory. 234 */ 235 CV_WRAP virtual void setNSamples(int _nN) = 0;//needs reinitialization! 236 237 /** @brief Returns the threshold on the squared distance between the pixel and the sample 238 239 The threshold on the squared distance between the pixel and the sample to decide whether a pixel is 240 close to a data sample. 241 */ 242 CV_WRAP virtual double getDist2Threshold() const = 0; 243 /** @brief Sets the threshold on the squared distance 244 */ 245 CV_WRAP virtual void setDist2Threshold(double _dist2Threshold) = 0; 246 247 /** @brief Returns the number of neighbours, the k in the kNN. 248 249 K is the number of samples that need to be within dist2Threshold in order to decide that that 250 pixel is matching the kNN background model. 251 */ 252 CV_WRAP virtual int getkNNSamples() const = 0; 253 /** @brief Sets the k in the kNN. How many nearest neigbours need to match. 254 */ 255 CV_WRAP virtual void setkNNSamples(int _nkNN) = 0; 256 257 /** @brief Returns the shadow detection flag 258 259 If true, the algorithm detects shadows and marks them. See createBackgroundSubtractorKNN for 260 details. 261 */ 262 CV_WRAP virtual bool getDetectShadows() const = 0; 263 /** @brief Enables or disables shadow detection 264 */ 265 CV_WRAP virtual void setDetectShadows(bool detectShadows) = 0; 266 267 /** @brief Returns the shadow value 268 269 Shadow value is the value used to mark shadows in the foreground mask. Default value is 127. Value 0 270 in the mask always means background, 255 means foreground. 271 */ 272 CV_WRAP virtual int getShadowValue() const = 0; 273 /** @brief Sets the shadow value 274 */ 275 CV_WRAP virtual void setShadowValue(int value) = 0; 276 277 /** @brief Returns the shadow threshold 278 279 A shadow is detected if pixel is a darker version of the background. The shadow threshold (Tau in 280 the paper) is a threshold defining how much darker the shadow can be. Tau= 0.5 means that if a pixel 281 is more than twice darker then it is not shadow. See Prati, Mikic, Trivedi and Cucchiarra, 282 *Detecting Moving Shadows...*, IEEE PAMI,2003. 283 */ 284 CV_WRAP virtual double getShadowThreshold() const = 0; 285 /** @brief Sets the shadow threshold 286 */ 287 CV_WRAP virtual void setShadowThreshold(double threshold) = 0; 288 }; 289 290 /** @brief Creates KNN Background Subtractor 291 292 @param history Length of the history. 293 @param dist2Threshold Threshold on the squared distance between the pixel and the sample to decide 294 whether a pixel is close to that sample. This parameter does not affect the background update. 295 @param detectShadows If true, the algorithm will detect shadows and mark them. It decreases the 296 speed a bit, so if you do not need this feature, set the parameter to false. 297 */ 298 CV_EXPORTS_W Ptr<BackgroundSubtractorKNN> 299 createBackgroundSubtractorKNN(int history=500, double dist2Threshold=400.0, 300 bool detectShadows=true); 301 302 //! @} video_motion 303 304 } // cv 305 306 #endif 307