diff --git a/modules/gpubgsegm/doc/background_segmentation.rst b/modules/gpubgsegm/doc/background_segmentation.rst index f892ee66642b9598c0e25c559c1bd569c078c998..c39028c086caa6cd04286ea99d037be2e274af65 100644 --- a/modules/gpubgsegm/doc/background_segmentation.rst +++ b/modules/gpubgsegm/doc/background_segmentation.rst @@ -5,128 +5,11 @@ Background Segmentation -gpu::FGDStatModel ------------------ -.. ocv:class:: gpu::FGDStatModel +gpu::BackgroundSubtractorMOG +---------------------------- +Gaussian Mixture-based Background/Foreground Segmentation Algorithm. -Class used for background/foreground segmentation. :: - - class FGDStatModel - { - public: - struct Params - { - ... - }; - - explicit FGDStatModel(int out_cn = 3); - explicit FGDStatModel(const cv::gpu::GpuMat& firstFrame, const Params& params = Params(), int out_cn = 3); - - ~FGDStatModel(); - - void create(const cv::gpu::GpuMat& firstFrame, const Params& params = Params()); - void release(); - - int update(const cv::gpu::GpuMat& curFrame); - - //8UC3 or 8UC4 reference background image - cv::gpu::GpuMat background; - - //8UC1 foreground image - cv::gpu::GpuMat foreground; - - std::vector< std::vector > foreground_regions; - }; - - The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [FGD2003]_. - - The results are available through the class fields: - - .. ocv:member:: cv::gpu::GpuMat background - - The output background image. - - .. ocv:member:: cv::gpu::GpuMat foreground - - The output foreground mask as an 8-bit binary image. - - .. ocv:member:: cv::gpu::GpuMat foreground_regions - - The output foreground regions calculated by :ocv:func:`findContours`. - - - -gpu::FGDStatModel::FGDStatModel -------------------------------- -Constructors. - -.. ocv:function:: gpu::FGDStatModel::FGDStatModel(int out_cn = 3) -.. ocv:function:: gpu::FGDStatModel::FGDStatModel(const cv::gpu::GpuMat& firstFrame, const Params& params = Params(), int out_cn = 3) - - :param firstFrame: First frame from video stream. Supports 3- and 4-channels input ( ``CV_8UC3`` and ``CV_8UC4`` ). - - :param params: Algorithm's parameters. See [FGD2003]_ for explanation. - - :param out_cn: Channels count in output result and inner buffers. Can be 3 or 4. 4-channels version requires more memory, but works a bit faster. - -.. seealso:: :ocv:func:`gpu::FGDStatModel::create` - - - -gpu::FGDStatModel::create -------------------------- -Initializes background model. - -.. ocv:function:: void gpu::FGDStatModel::create(const cv::gpu::GpuMat& firstFrame, const Params& params = Params()) - - :param firstFrame: First frame from video stream. Supports 3- and 4-channels input ( ``CV_8UC3`` and ``CV_8UC4`` ). - - :param params: Algorithm's parameters. See [FGD2003]_ for explanation. - - - -gpu::FGDStatModel::release --------------------------- -Releases all inner buffer's memory. - -.. ocv:function:: void gpu::FGDStatModel::release() - - - -gpu::FGDStatModel::update --------------------------- -Updates the background model and returns foreground regions count. - -.. ocv:function:: int gpu::FGDStatModel::update(const cv::gpu::GpuMat& curFrame) - - :param curFrame: Next video frame. - - - -gpu::MOG_GPU ------------- -.. ocv:class:: gpu::MOG_GPU - -Gaussian Mixture-based Backbround/Foreground Segmentation Algorithm. :: - - class MOG_GPU - { - public: - MOG_GPU(int nmixtures = -1); - - void initialize(Size frameSize, int frameType); - - void operator()(const GpuMat& frame, GpuMat& fgmask, float learningRate = 0.0f, Stream& stream = Stream::Null()); - - void getBackgroundImage(GpuMat& backgroundImage, Stream& stream = Stream::Null()) const; - - void release(); - - int history; - float varThreshold; - float backgroundRatio; - float noiseSigma; - }; +.. ocv:class:: gpu::BackgroundSubtractorMOG : public cv::BackgroundSubtractorMOG The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [MOG2001]_. @@ -134,275 +17,108 @@ The class discriminates between foreground and background pixels by building and -gpu::MOG_GPU::MOG_GPU ---------------------- -The constructor. - -.. ocv:function:: gpu::MOG_GPU::MOG_GPU(int nmixtures = -1) - - :param nmixtures: Number of Gaussian mixtures. - -Default constructor sets all parameters to default values. - - - -gpu::MOG_GPU::operator() ------------------------- -Updates the background model and returns the foreground mask. - -.. ocv:function:: void gpu::MOG_GPU::operator()(const GpuMat& frame, GpuMat& fgmask, float learningRate = 0.0f, Stream& stream = Stream::Null()) - - :param frame: Next video frame. - - :param fgmask: The output foreground mask as an 8-bit binary image. - - :param stream: Stream for the asynchronous version. - - - -gpu::MOG_GPU::getBackgroundImage --------------------------------- -Computes a background image. +gpu::createBackgroundSubtractorMOG +---------------------------------- +Creates mixture-of-gaussian background subtractor -.. ocv:function:: void gpu::MOG_GPU::getBackgroundImage(GpuMat& backgroundImage, Stream& stream = Stream::Null()) const +.. ocv:function:: Ptr gpu::createBackgroundSubtractorMOG(int history=200, int nmixtures=5, double backgroundRatio=0.7, double noiseSigma=0) - :param backgroundImage: The output background image. + :param history: Length of the history. - :param stream: Stream for the asynchronous version. - - - -gpu::MOG_GPU::release ---------------------- -Releases all inner buffer's memory. - -.. ocv:function:: void gpu::MOG_GPU::release() - - - -gpu::MOG2_GPU -------------- -.. ocv:class:: gpu::MOG2_GPU - -Gaussian Mixture-based Background/Foreground Segmentation Algorithm. :: - - class MOG2_GPU - { - public: - MOG2_GPU(int nmixtures = -1); - - void initialize(Size frameSize, int frameType); - - void operator()(const GpuMat& frame, GpuMat& fgmask, float learningRate = 0.0f, Stream& stream = Stream::Null()); - - void getBackgroundImage(GpuMat& backgroundImage, Stream& stream = Stream::Null()) const; - - void release(); - - // parameters - ... - }; - - The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [MOG2004]_. - - Here are important members of the class that control the algorithm, which you can set after constructing the class instance: - - .. ocv:member:: float backgroundRatio - - Threshold defining whether the component is significant enough to be included into the background model ( corresponds to ``TB=1-cf`` from the paper??which paper??). ``cf=0.1 => TB=0.9`` is default. For ``alpha=0.001``, it means that the mode should exist for approximately 105 frames before it is considered foreground. - - .. ocv:member:: float varThreshold - - Threshold for the squared Mahalanobis distance that helps decide when a sample is close to the existing components (corresponds to ``Tg``). If it is not close to any component, a new component is generated. ``3 sigma => Tg=3*3=9`` is default. A smaller ``Tg`` value generates more components. A higher ``Tg`` value may result in a small number of components but they can grow too large. - - .. ocv:member:: float fVarInit - - Initial variance for the newly generated components. It affects the speed of adaptation. The parameter value is based on your estimate of the typical standard deviation from the images. OpenCV uses 15 as a reasonable value. - - .. ocv:member:: float fVarMin - - Parameter used to further control the variance. - - .. ocv:member:: float fVarMax - - Parameter used to further control the variance. - - .. ocv:member:: float fCT + :param nmixtures: Number of Gaussian mixtures. - Complexity reduction parameter. This parameter defines the number of samples needed to accept to prove the component exists. ``CT=0.05`` is a default value for all the samples. By setting ``CT=0`` you get an algorithm very similar to the standard Stauffer&Grimson algorithm. + :param backgroundRatio: Background ratio. - .. ocv:member:: uchar nShadowDetection + :param noiseSigma: Noise strength (standard deviation of the brightness or each color channel). 0 means some automatic value. - The value for marking shadow pixels in the output foreground mask. Default value is 127. - .. ocv:member:: float fTau - Shadow threshold. The shadow is detected if the pixel is a darker version of the background. ``Tau`` is a threshold defining how much darker the shadow can be. ``Tau= 0.5`` means that if a pixel is more than twice darker then it is not shadow. See [ShadowDetect2003]_. +gpu::BackgroundSubtractorMOG2 +----------------------------- +Gaussian Mixture-based Background/Foreground Segmentation Algorithm. - .. ocv:member:: bool bShadowDetection +.. ocv:class:: gpu::BackgroundSubtractorMOG2 : public cv::BackgroundSubtractorMOG2 - Parameter defining whether shadow detection should be enabled. +The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [MOG2004]_. .. seealso:: :ocv:class:`BackgroundSubtractorMOG2` -gpu::MOG2_GPU::MOG2_GPU ------------------------ -The constructor. - -.. ocv:function:: gpu::MOG2_GPU::MOG2_GPU(int nmixtures = -1) - - :param nmixtures: Number of Gaussian mixtures. - -Default constructor sets all parameters to default values. - +gpu::createBackgroundSubtractorMOG2 +----------------------------------- +Creates MOG2 Background Subtractor +.. ocv:function:: Ptr gpu::createBackgroundSubtractorMOG2( int history=500, double varThreshold=16, bool detectShadows=true ) -gpu::MOG2_GPU::operator() -------------------------- -Updates the background model and returns the foreground mask. + :param history: Length of the history. -.. ocv:function:: void gpu::MOG2_GPU::operator()( const GpuMat& frame, GpuMat& fgmask, float learningRate=-1.0f, Stream& stream=Stream::Null() ) + :param varThreshold: Threshold on the squared Mahalanobis distance between the pixel and the model to decide whether a pixel is well described by the background model. This parameter does not affect the background update. - :param frame: Next video frame. + :param detectShadows: If true, the algorithm will detect shadows and mark them. It decreases the speed a bit, so if you do not need this feature, set the parameter to false. - :param fgmask: The output foreground mask as an 8-bit binary image. - :param stream: Stream for the asynchronous version. +gpu::BackgroundSubtractorGMG +---------------------------- +Background/Foreground Segmentation Algorithm. +.. ocv:class:: gpu::BackgroundSubtractorGMG : public cv::BackgroundSubtractorGMG -gpu::MOG2_GPU::getBackgroundImage ---------------------------------- -Computes a background image. +The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [GMG2012]_. -.. ocv:function:: void gpu::MOG2_GPU::getBackgroundImage(GpuMat& backgroundImage, Stream& stream = Stream::Null()) const - :param backgroundImage: The output background image. - :param stream: Stream for the asynchronous version. +gpu::createBackgroundSubtractorGMG +---------------------------------- +Creates GMG Background Subtractor +.. ocv:function:: Ptr gpu::createBackgroundSubtractorGMG(int initializationFrames = 120, double decisionThreshold = 0.8) + :param initializationFrames: Number of frames of video to use to initialize histograms. -gpu::MOG2_GPU::release ----------------------- -Releases all inner buffer's memory. + :param decisionThreshold: Value above which pixel is determined to be FG. -.. ocv:function:: void gpu::MOG2_GPU::release() +gpu::BackgroundSubtractorFGD +---------------------------- -gpu::GMG_GPU ------------- -.. ocv:class:: gpu::GMG_GPU +.. ocv:class:: gpu::BackgroundSubtractorFGD : public cv::BackgroundSubtractor - Class used for background/foreground segmentation. :: +The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [FGD2003]_. :: - class GMG_GPU_GPU + class CV_EXPORTS BackgroundSubtractorFGD : public cv::BackgroundSubtractor { public: - GMG_GPU(); - - void initialize(Size frameSize, float min = 0.0f, float max = 255.0f); - - void operator ()(const GpuMat& frame, GpuMat& fgmask, float learningRate = -1.0f, Stream& stream = Stream::Null()); - - void release(); - - int maxFeatures; - float learningRate; - int numInitializationFrames; - int quantizationLevels; - float backgroundPrior; - float decisionThreshold; - int smoothingRadius; - - ... + virtual void getForegroundRegions(OutputArrayOfArrays foreground_regions) = 0; }; - The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [GMG2012]_. - - Here are important members of the class that control the algorithm, which you can set after constructing the class instance: - - .. ocv:member:: int maxFeatures - - Total number of distinct colors to maintain in histogram. - - .. ocv:member:: float learningRate - - Set between 0.0 and 1.0, determines how quickly features are "forgotten" from histograms. - - .. ocv:member:: int numInitializationFrames - - Number of frames of video to use to initialize histograms. - - .. ocv:member:: int quantizationLevels - - Number of discrete levels in each channel to be used in histograms. - - .. ocv:member:: float backgroundPrior - - Prior probability that any given pixel is a background pixel. A sensitivity parameter. - - .. ocv:member:: float decisionThreshold +.. seealso:: :ocv:class:`BackgroundSubtractor` - Value above which pixel is determined to be FG. - .. ocv:member:: float smoothingRadius - Smoothing radius, in pixels, for cleaning up FG image. +gpu::BackgroundSubtractorFGD::getForegroundRegions +-------------------------------------------------- +Returns the output foreground regions calculated by :ocv:func:`findContours`. +.. ocv:function:: void gpu::BackgroundSubtractorFGD::getForegroundRegions(OutputArrayOfArrays foreground_regions) + :params foreground_regions: Output array (CPU memory). -gpu::GMG_GPU::GMG_GPU ---------------------- -The default constructor. -.. ocv:function:: gpu::GMG_GPU::GMG_GPU() -Default constructor sets all parameters to default values. +gpu::createBackgroundSubtractorFGD +---------------------------------- +Creates FGD Background Subtractor +.. ocv:function:: Ptr gpu::createBackgroundSubtractorFGD(const FGDParams& params = FGDParams()) - -gpu::GMG_GPU::initialize ------------------------- -Initialize background model and allocates all inner buffers. - -.. ocv:function:: void gpu::GMG_GPU::initialize(Size frameSize, float min = 0.0f, float max = 255.0f) - - :param frameSize: Input frame size. - - :param min: Minimum value taken on by pixels in image sequence. Usually 0. - - :param max: Maximum value taken on by pixels in image sequence, e.g. 1.0 or 255. - - - -gpu::GMG_GPU::operator() ------------------------- -Updates the background model and returns the foreground mask - -.. ocv:function:: void gpu::GMG_GPU::operator ()( const GpuMat& frame, GpuMat& fgmask, float learningRate=-1.0f, Stream& stream=Stream::Null() ) - - :param frame: Next video frame. - - :param fgmask: The output foreground mask as an 8-bit binary image. - - :param stream: Stream for the asynchronous version. - - - -gpu::GMG_GPU::release ---------------------- -Releases all inner buffer's memory. - -.. ocv:function:: void gpu::GMG_GPU::release() + :param params: Algorithm's parameters. See [FGD2003]_ for explanation. .. [FGD2003] Liyuan Li, Weimin Huang, Irene Y.H. Gu, and Qi Tian. *Foreground Object Detection from Videos Containing Complex Background*. ACM MM2003 9p, 2003. .. [MOG2001] P. KadewTraKuPong and R. Bowden. *An improved adaptive background mixture model for real-time tracking with shadow detection*. Proc. 2nd European Workshop on Advanced Video-Based Surveillance Systems, 2001 .. [MOG2004] Z. Zivkovic. *Improved adaptive Gausian mixture model for background subtraction*. International Conference Pattern Recognition, UK, August, 2004 -.. [ShadowDetect2003] Prati, Mikic, Trivedi and Cucchiarra. *Detecting Moving Shadows...*. IEEE PAMI, 2003 .. [GMG2012] A. Godbehere, A. Matsukawa and K. Goldberg. *Visual Tracking of Human Visitors under Variable-Lighting Conditions for a Responsive Audio Art Installation*. American Control Conference, Montreal, June 2012