background_segm.hpp

00001 /*M///////////////////////////////////////////////////////////////////////////////////////
00002 //
00003 //  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
00004 //
00005 //  By downloading, copying, installing or using the software you agree to this license.
00006 //  If you do not agree to this license, do not download, install,
00007 //  copy or use the software.
00008 //
00009 //
00010 //                          License Agreement
00011 //                For Open Source Computer Vision Library
00012 //
00013 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
00014 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
00015 // Copyright (C) 2013, OpenCV Foundation, all rights reserved.
00016 // Third party copyrights are property of their respective owners.
00017 //
00018 // Redistribution and use in source and binary forms, with or without modification,
00019 // are permitted provided that the following conditions are met:
00020 //
00021 //   * Redistribution's of source code must retain the above copyright notice,
00022 //     this list of conditions and the following disclaimer.
00023 //
00024 //   * Redistribution's in binary form must reproduce the above copyright notice,
00025 //     this list of conditions and the following disclaimer in the documentation
00026 //     and/or other materials provided with the distribution.
00027 //
00028 //   * The name of the copyright holders may not be used to endorse or promote products
00029 //     derived from this software without specific prior written permission.
00030 //
00031 // This software is provided by the copyright holders and contributors "as is" and
00032 // any express or implied warranties, including, but not limited to, the implied
00033 // warranties of merchantability and fitness for a particular purpose are disclaimed.
00034 // In no event shall the Intel Corporation or contributors be liable for any direct,
00035 // indirect, incidental, special, exemplary, or consequential damages
00036 // (including, but not limited to, procurement of substitute goods or services;
00037 // loss of use, data, or profits; or business interruption) however caused
00038 // and on any theory of liability, whether in contract, strict liability,
00039 // or tort (including negligence or otherwise) arising in any way out of
00040 // the use of this software, even if advised of the possibility of such damage.
00041 //
00042 //M*/
00043 
00044 #ifndef __OPENCV_BACKGROUND_SEGM_HPP__
00045 #define __OPENCV_BACKGROUND_SEGM_HPP__
00046 
00047 #include "opencv2/core.hpp"
00048 
00049 namespace cv
00050 {
00051 
00052 //! @addtogroup video_motion
00053 //! @{
00054 
00055 /** @brief Base class for background/foreground segmentation. :
00056 
00057 The class is only used to define the common interface for the whole family of background/foreground
00058 segmentation algorithms.
00059  */
00060 class CV_EXPORTS_W BackgroundSubtractor : public Algorithm
00061 {
00062 public:
00063     /** @brief Computes a foreground mask.
00064 
00065     @param image Next video frame.
00066     @param fgmask The output foreground mask as an 8-bit binary image.
00067     @param learningRate The value between 0 and 1 that indicates how fast the background model is
00068     learnt. Negative parameter value makes the algorithm to use some automatically chosen learning
00069     rate. 0 means that the background model is not updated at all, 1 means that the background model
00070     is completely reinitialized from the last frame.
00071      */
00072     CV_WRAP virtual void apply(InputArray image, OutputArray fgmask, double learningRate=-1) = 0;
00073 
00074     /** @brief Computes a background image.
00075 
00076     @param backgroundImage The output background image.
00077 
00078     @note Sometimes the background image can be very blurry, as it contain the average background
00079     statistics.
00080      */
00081     CV_WRAP virtual void getBackgroundImage(OutputArray backgroundImage) const = 0;
00082 };
00083 
00084 
00085 /** @brief Gaussian Mixture-based Background/Foreground Segmentation Algorithm.
00086 
00087 The class implements the Gaussian mixture model background subtraction described in @cite Zivkovic2004
00088 and @cite Zivkovic2006 .
00089  */
00090 class CV_EXPORTS_W BackgroundSubtractorMOG2 : public BackgroundSubtractor
00091 {
00092 public:
00093     /** @brief Returns the number of last frames that affect the background model
00094     */
00095     CV_WRAP virtual int getHistory() const = 0;
00096     /** @brief Sets the number of last frames that affect the background model
00097     */
00098     CV_WRAP virtual void setHistory(int history) = 0;
00099 
00100     /** @brief Returns the number of gaussian components in the background model
00101     */
00102     CV_WRAP virtual int getNMixtures() const = 0;
00103     /** @brief Sets the number of gaussian components in the background model.
00104 
00105     The model needs to be reinitalized to reserve memory.
00106     */
00107     CV_WRAP virtual void setNMixtures(int nmixtures) = 0;//needs reinitialization!
00108 
00109     /** @brief Returns the "background ratio" parameter of the algorithm
00110 
00111     If a foreground pixel keeps semi-constant value for about backgroundRatio\*history frames, it's
00112     considered background and added to the model as a center of a new component. It corresponds to TB
00113     parameter in the paper.
00114      */
00115     CV_WRAP virtual double getBackgroundRatio() const = 0;
00116     /** @brief Sets the "background ratio" parameter of the algorithm
00117     */
00118     CV_WRAP virtual void setBackgroundRatio(double ratio) = 0;
00119 
00120     /** @brief Returns the variance threshold for the pixel-model match
00121 
00122     The main threshold on the squared Mahalanobis distance to decide if the sample is well described by
00123     the background model or not. Related to Cthr from the paper.
00124      */
00125     CV_WRAP virtual double getVarThreshold() const = 0;
00126     /** @brief Sets the variance threshold for the pixel-model match
00127     */
00128     CV_WRAP virtual void setVarThreshold(double varThreshold) = 0;
00129 
00130     /** @brief Returns the variance threshold for the pixel-model match used for new mixture component generation
00131 
00132     Threshold for the squared Mahalanobis distance that helps decide when a sample is close to the
00133     existing components (corresponds to Tg in the paper). If a pixel is not close to any component, it
00134     is considered foreground or added as a new component. 3 sigma => Tg=3\*3=9 is default. A smaller Tg
00135     value generates more components. A higher Tg value may result in a small number of components but
00136     they can grow too large.
00137      */
00138     CV_WRAP virtual double getVarThresholdGen() const = 0;
00139     /** @brief Sets the variance threshold for the pixel-model match used for new mixture component generation
00140     */
00141     CV_WRAP virtual void setVarThresholdGen(double varThresholdGen) = 0;
00142 
00143     /** @brief Returns the initial variance of each gaussian component
00144     */
00145     CV_WRAP virtual double getVarInit() const = 0;
00146     /** @brief Sets the initial variance of each gaussian component
00147     */
00148     CV_WRAP virtual void setVarInit(double varInit) = 0;
00149 
00150     CV_WRAP virtual double getVarMin() const = 0;
00151     CV_WRAP virtual void setVarMin(double varMin) = 0;
00152 
00153     CV_WRAP virtual double getVarMax() const = 0;
00154     CV_WRAP virtual void setVarMax(double varMax) = 0;
00155 
00156     /** @brief Returns the complexity reduction threshold
00157 
00158     This parameter defines the number of samples needed to accept to prove the component exists. CT=0.05
00159     is a default value for all the samples. By setting CT=0 you get an algorithm very similar to the
00160     standard Stauffer&Grimson algorithm.
00161      */
00162     CV_WRAP virtual double getComplexityReductionThreshold() const = 0;
00163     /** @brief Sets the complexity reduction threshold
00164     */
00165     CV_WRAP virtual void setComplexityReductionThreshold(double ct) = 0;
00166 
00167     /** @brief Returns the shadow detection flag
00168 
00169     If true, the algorithm detects shadows and marks them. See createBackgroundSubtractorMOG2 for
00170     details.
00171      */
00172     CV_WRAP virtual bool getDetectShadows() const = 0;
00173     /** @brief Enables or disables shadow detection
00174     */
00175     CV_WRAP virtual void setDetectShadows(bool detectShadows) = 0;
00176 
00177     /** @brief Returns the shadow value
00178 
00179     Shadow value is the value used to mark shadows in the foreground mask. Default value is 127. Value 0
00180     in the mask always means background, 255 means foreground.
00181      */
00182     CV_WRAP virtual int getShadowValue() const = 0;
00183     /** @brief Sets the shadow value
00184     */
00185     CV_WRAP virtual void setShadowValue(int value) = 0;
00186 
00187     /** @brief Returns the shadow threshold
00188 
00189     A shadow is detected if pixel is a darker version of the background. The shadow threshold (Tau in
00190     the paper) is a threshold defining how much darker the shadow can be. Tau= 0.5 means that if a pixel
00191     is more than twice darker then it is not shadow. See Prati, Mikic, Trivedi and Cucchiarra,
00192     *Detecting Moving Shadows...*, IEEE PAMI,2003.
00193      */
00194     CV_WRAP virtual double getShadowThreshold() const = 0;
00195     /** @brief Sets the shadow threshold
00196     */
00197     CV_WRAP virtual void setShadowThreshold(double threshold) = 0;
00198 };
00199 
00200 /** @brief Creates MOG2 Background Subtractor
00201 
00202 @param history Length of the history.
00203 @param varThreshold Threshold on the squared Mahalanobis distance between the pixel and the model
00204 to decide whether a pixel is well described by the background model. This parameter does not
00205 affect the background update.
00206 @param detectShadows If true, the algorithm will detect shadows and mark them. It decreases the
00207 speed a bit, so if you do not need this feature, set the parameter to false.
00208  */
00209 CV_EXPORTS_W Ptr<BackgroundSubtractorMOG2>
00210     createBackgroundSubtractorMOG2(int history=500, double varThreshold=16,
00211                                    bool detectShadows=true);
00212 
00213 /** @brief K-nearest neigbours - based Background/Foreground Segmentation Algorithm.
00214 
00215 The class implements the K-nearest neigbours background subtraction described in @cite Zivkovic2006 .
00216 Very efficient if number of foreground pixels is low.
00217  */
00218 class CV_EXPORTS_W BackgroundSubtractorKNN : public BackgroundSubtractor
00219 {
00220 public:
00221     /** @brief Returns the number of last frames that affect the background model
00222     */
00223     CV_WRAP virtual int getHistory() const = 0;
00224     /** @brief Sets the number of last frames that affect the background model
00225     */
00226     CV_WRAP virtual void setHistory(int history) = 0;
00227 
00228     /** @brief Returns the number of data samples in the background model
00229     */
00230     CV_WRAP virtual int getNSamples() const = 0;
00231     /** @brief Sets the number of data samples in the background model.
00232 
00233     The model needs to be reinitalized to reserve memory.
00234     */
00235     CV_WRAP virtual void setNSamples(int _nN) = 0;//needs reinitialization!
00236 
00237     /** @brief Returns the threshold on the squared distance between the pixel and the sample
00238 
00239     The threshold on the squared distance between the pixel and the sample to decide whether a pixel is
00240     close to a data sample.
00241      */
00242     CV_WRAP virtual double getDist2Threshold() const = 0;
00243     /** @brief Sets the threshold on the squared distance
00244     */
00245     CV_WRAP virtual void setDist2Threshold(double _dist2Threshold) = 0;
00246 
00247     /** @brief Returns the number of neighbours, the k in the kNN.
00248 
00249     K is the number of samples that need to be within dist2Threshold in order to decide that that
00250     pixel is matching the kNN background model.
00251      */
00252     CV_WRAP virtual int getkNNSamples() const = 0;
00253     /** @brief Sets the k in the kNN. How many nearest neigbours need to match.
00254     */
00255     CV_WRAP virtual void setkNNSamples(int _nkNN) = 0;
00256 
00257     /** @brief Returns the shadow detection flag
00258 
00259     If true, the algorithm detects shadows and marks them. See createBackgroundSubtractorKNN for
00260     details.
00261      */
00262     CV_WRAP virtual bool getDetectShadows() const = 0;
00263     /** @brief Enables or disables shadow detection
00264     */
00265     CV_WRAP virtual void setDetectShadows(bool detectShadows) = 0;
00266 
00267     /** @brief Returns the shadow value
00268 
00269     Shadow value is the value used to mark shadows in the foreground mask. Default value is 127. Value 0
00270     in the mask always means background, 255 means foreground.
00271      */
00272     CV_WRAP virtual int getShadowValue() const = 0;
00273     /** @brief Sets the shadow value
00274     */
00275     CV_WRAP virtual void setShadowValue(int value) = 0;
00276 
00277     /** @brief Returns the shadow threshold
00278 
00279     A shadow is detected if pixel is a darker version of the background. The shadow threshold (Tau in
00280     the paper) is a threshold defining how much darker the shadow can be. Tau= 0.5 means that if a pixel
00281     is more than twice darker then it is not shadow. See Prati, Mikic, Trivedi and Cucchiarra,
00282     *Detecting Moving Shadows...*, IEEE PAMI,2003.
00283      */
00284     CV_WRAP virtual double getShadowThreshold() const = 0;
00285     /** @brief Sets the shadow threshold
00286      */
00287     CV_WRAP virtual void setShadowThreshold(double threshold) = 0;
00288 };
00289 
00290 /** @brief Creates KNN Background Subtractor
00291 
00292 @param history Length of the history.
00293 @param dist2Threshold Threshold on the squared distance between the pixel and the sample to decide
00294 whether a pixel is close to that sample. This parameter does not affect the background update.
00295 @param detectShadows If true, the algorithm will detect shadows and mark them. It decreases the
00296 speed a bit, so if you do not need this feature, set the parameter to false.
00297  */
00298 CV_EXPORTS_W Ptr<BackgroundSubtractorKNN>
00299     createBackgroundSubtractorKNN(int history=500, double dist2Threshold=400.0,
00300                                    bool detectShadows=true);
00301 
00302 //! @} video_motion
00303 
00304 } // cv
00305 
00306 #endif
00307