modules/video/include/opencv2/video/background_segm.hpp

   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_BACKGROUND_SEGM_HPP__
  44 #define __OPENCV_BACKGROUND_SEGM_HPP__
  45
  46 #include "opencv2/core/core.hpp"
  47 #include <list>
  48 namespace cv
  49 {
  50
  51 /*!
  52  The Base Class for Background/Foreground Segmentation
  53
  54  The class is only used to define the common interface for
  55  the whole family of background/foreground segmentation algorithms.
  56 */
  57 class CV_EXPORTS_W BackgroundSubtractor : public Algorithm
  58 {
  59 public:
  60     //! the virtual destructor
  61     virtual ~BackgroundSubtractor();
  62     //! the update operator that takes the next video frame and returns the current foreground mask as 8-bit binary image.
  63     CV_WRAP_AS(apply) virtual void operator()(InputArray image, OutputArray fgmask,
  64                                               double learningRate=0);
  65
  66     //! computes a background image
  67     virtual void getBackgroundImage(OutputArray backgroundImage) const;
  68 };
  69
  70
  71 /*!
  72  Gaussian Mixture-based Backbround/Foreground Segmentation Algorithm
  73
  74  The class implements the following algorithm:
  75  "An improved adaptive background mixture model for real-time tracking with shadow detection"
  76  P. KadewTraKuPong and R. Bowden,
  77  Proc. 2nd European Workshp on Advanced Video-Based Surveillance Systems, 2001."
  78  http://personal.ee.surrey.ac.uk/Personal/R.Bowden/publications/avbs01/avbs01.pdf
  79
  80 */
  81 class CV_EXPORTS_W BackgroundSubtractorMOG : public BackgroundSubtractor
  82 {
  83 public:
  84     //! the default constructor
  85     CV_WRAP BackgroundSubtractorMOG();
  86     //! the full constructor that takes the length of the history, the number of gaussian mixtures, the background ratio parameter and the noise strength
  87     CV_WRAP BackgroundSubtractorMOG(int history, int nmixtures, double backgroundRatio, double noiseSigma=0);
  88     //! the destructor
  89     virtual ~BackgroundSubtractorMOG();
  90     //! the update operator
  91     virtual void operator()(InputArray image, OutputArray fgmask, double learningRate=0);
  92
  93     //! re-initiaization method
  94     virtual void initialize(Size frameSize, int frameType);
  95
  96     virtual AlgorithmInfo* info() const;
  97
  98 protected:
  99     Size frameSize;
 100     int frameType;
 101     Mat bgmodel;
 102     int nframes;
 103     int history;
 104     int nmixtures;
 105     double varThreshold;
 106     double backgroundRatio;
 107     double noiseSigma;
 108 };
 109
 110
 111 /*!
 112  The class implements the following algorithm:
 113  "Improved adaptive Gausian mixture model for background subtraction"
 114  Z.Zivkovic
 115  International Conference Pattern Recognition, UK, August, 2004.
 116  http://www.zoranz.net/Publications/zivkovic2004ICPR.pdf
 117 */
 118 class CV_EXPORTS_W BackgroundSubtractorMOG2 : public BackgroundSubtractor
 119 {
 120 public:
 121     //! the default constructor
 122     CV_WRAP BackgroundSubtractorMOG2();
 123     //! the full constructor that takes the length of the history, the number of gaussian mixtures, the background ratio parameter and the noise strength
 124     CV_WRAP BackgroundSubtractorMOG2(int history,  float varThreshold, bool bShadowDetection=true);
 125     //! the destructor
 126     virtual ~BackgroundSubtractorMOG2();
 127     //! the update operator
 128     virtual void operator()(InputArray image, OutputArray fgmask, double learningRate=-1);
 129
 130     //! computes a background image which are the mean of all background gaussians
 131     virtual void getBackgroundImage(OutputArray backgroundImage) const;
 132
 133     //! re-initiaization method
 134     virtual void initialize(Size frameSize, int frameType);
 135
 136     virtual AlgorithmInfo* info() const;
 137
 138 protected:
 139     Size frameSize;
 140     int frameType;
 141     Mat bgmodel;
 142     Mat bgmodelUsedModes;//keep track of number of modes per pixel
 143     int nframes;
 144     int history;
 145     int nmixtures;
 146     //! here it is the maximum allowed number of mixture components.
 147     //! Actual number is determined dynamically per pixel
 148     double varThreshold;
 149     // threshold on the squared Mahalanobis distance to decide if it is well described
 150     // by the background model or not. Related to Cthr from the paper.
 151     // This does not influence the update of the background. A typical value could be 4 sigma
 152     // and that is varThreshold=4*4=16; Corresponds to Tb in the paper.
 153
 154     /////////////////////////
 155     // less important parameters - things you might change but be carefull
 156     ////////////////////////
 157     float backgroundRatio;
 158     // corresponds to fTB=1-cf from the paper
 159     // TB - threshold when the component becomes significant enough to be included into
 160     // the background model. It is the TB=1-cf from the paper. So I use cf=0.1 => TB=0.
 161     // For alpha=0.001 it means that the mode should exist for approximately 105 frames before
 162     // it is considered foreground
 163     // float noiseSigma;
 164     float varThresholdGen;
 165     //correspondts to Tg - threshold on the squared Mahalan. dist. to decide
 166     //when a sample is close to the existing components. If it is not close
 167     //to any a new component will be generated. I use 3 sigma => Tg=3*3=9.
 168     //Smaller Tg leads to more generated components and higher Tg might make
 169     //lead to small number of components but they can grow too large
 170     float fVarInit;
 171     float fVarMin;
 172     float fVarMax;
 173     //initial variance  for the newly generated components.
 174     //It will will influence the speed of adaptation. A good guess should be made.
 175     //A simple way is to estimate the typical standard deviation from the images.
 176     //I used here 10 as a reasonable value
 177     // min and max can be used to further control the variance
 178     float fCT;//CT - complexity reduction prior
 179     //this is related to the number of samples needed to accept that a component
 180     //actually exists. We use CT=0.05 of all the samples. By setting CT=0 you get
 181     //the standard Stauffer&Grimson algorithm (maybe not exact but very similar)
 182
 183     //shadow detection parameters
 184     bool bShadowDetection;//default 1 - do shadow detection
 185     unsigned char nShadowDetection;//do shadow detection - insert this value as the detection result - 127 default value
 186     float fTau;
 187     // Tau - shadow threshold. The shadow is detected if the pixel is darker
 188     //version of the background. Tau is a threshold on how much darker the shadow can be.
 189     //Tau= 0.5 means that if pixel is more than 2 times darker then it is not shadow
 190     //See: Prati,Mikic,Trivedi,Cucchiarra,"Detecting Moving Shadows...",IEEE PAMI,2003.
 191 };
 192
 193 /**
 194  * Background Subtractor module. Takes a series of images and returns a sequence of mask (8UC1)
 195  * images of the same size, where 255 indicates Foreground and 0 represents Background.
 196  * This class implements an algorithm described in "Visual Tracking of Human Visitors under
 197  * Variable-Lighting Conditions for a Responsive Audio Art Installation," A. Godbehere,
 198  * A. Matsukawa, K. Goldberg, American Control Conference, Montreal, June 2012.
 199  */
 200 class CV_EXPORTS BackgroundSubtractorGMG: public cv::BackgroundSubtractor
 201 {
 202 public:
 203     BackgroundSubtractorGMG();
 204     virtual ~BackgroundSubtractorGMG();
 205     virtual AlgorithmInfo* info() const;
 206
 207     /**
 208      * Validate parameters and set up data structures for appropriate image size.
 209      * Must call before running on data.
 210      * @param frameSize input frame size
 211      * @param min       minimum value taken on by pixels in image sequence. Usually 0
 212      * @param max       maximum value taken on by pixels in image sequence. e.g. 1.0 or 255
 213      */
 214     void initialize(cv::Size frameSize, double min, double max);
 215
 216     /**
 217      * Performs single-frame background subtraction and builds up a statistical background image
 218      * model.
 219      * @param image Input image
 220      * @param fgmask Output mask image representing foreground and background pixels
 221      */
 222     virtual void operator()(InputArray image, OutputArray fgmask, double learningRate=-1.0);
 223
 224     /**
 225      * Releases all inner buffers.
 226      */
 227     void release();
 228
 229     //! Total number of distinct colors to maintain in histogram.
 230     int     maxFeatures;
 231     //! Set between 0.0 and 1.0, determines how quickly features are "forgotten" from histograms.
 232     double  learningRate;
 233     //! Number of frames of video to use to initialize histograms.
 234     int     numInitializationFrames;
 235     //! Number of discrete levels in each channel to be used in histograms.
 236     int     quantizationLevels;
 237     //! Prior probability that any given pixel is a background pixel. A sensitivity parameter.
 238     double  backgroundPrior;
 239     //! Value above which pixel is determined to be FG.
 240     double  decisionThreshold;
 241     //! Smoothing radius, in pixels, for cleaning up FG image.
 242     int     smoothingRadius;
 243     //! Perform background model update
 244     bool updateBackgroundModel;
 245
 246 private:
 247     double maxVal_;
 248     double minVal_;
 249
 250     cv::Size frameSize_;
 251     int frameNum_;
 252
 253     cv::Mat_<int> nfeatures_;
 254     cv::Mat_<unsigned int> colors_;
 255     cv::Mat_<float> weights_;
 256
 257     cv::Mat buf_;
 258 };
 259
 260 }
 261
 262 #endif