OpenCV 2.4.8 components for OpenCVgrabber.
[mmanager-3rdparty.git] / OpenCV2.4.8 / build / 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