In support of Optional Known Foreground Mask for Background Subtractors

modules/bgsegm/include/opencv2/bgsegm.hpp

@@ -62,6 +62,32 @@ The class implements the algorithm described in @cite KB2001 .
 class CV_EXPORTS_W BackgroundSubtractorMOG : public BackgroundSubtractor
 {
 public:
+    // BackgroundSubtractor interface
+    /** @brief Computes a foreground mask.
+
+    @param image Next video frame of type CV_8UC(n),CV_8SC(n),CV_16UC(n),CV_16SC(n),CV_32SC(n),CV_32FC(n),CV_64FC(n), where n is 1,2,3,4.
+    @param fgmask The output foreground mask as an 8-bit binary image.
+    @param learningRate The value between 0 and 1 that indicates how fast the background model is
+    learnt. Negative parameter value makes the algorithm to use some automatically chosen learning
+    rate. 0 means that the background model is not updated at all, 1 means that the background model
+    is completely reinitialized from the last frame.
+     */
+
+    CV_WRAP virtual void apply(InputArray image, OutputArray fgmask, double learningRate=-1) CV_OVERRIDE = 0;
+
+    /** @brief Computes a foreground mask and skips known foreground in evaluation.
+
+    @param image Next video frame of type CV_8UC(n),CV_8SC(n),CV_16UC(n),CV_16SC(n),CV_32SC(n),CV_32FC(n),CV_64FC(n), where n is 1,2,3,4.
+    @param fgmask The output foreground mask as an 8-bit binary image.
+    @param knownForegroundMask The mask for inputting already known foreground, allows model to ignore learning known pixels.
+    @param learningRate The value between 0 and 1 that indicates how fast the background model is
+    learnt. Negative parameter value makes the algorithm to use some automatically chosen learning
+    rate. 0 means that the background model is not updated at all, 1 means that the background model
+    is completely reinitialized from the last frame.
+     */
+
+    CV_WRAP virtual void apply(InputArray image, InputArray knownForegroundMask, OutputArray fgmask, double learningRate=-1) CV_OVERRIDE = 0;
+
     CV_WRAP virtual int getHistory() const = 0;
     CV_WRAP virtual void setHistory(int nframes) = 0;
 
@@ -110,6 +136,22 @@ class CV_EXPORTS_W BackgroundSubtractorGMG : public BackgroundSubtractor
     is completely reinitialized from the last frame.
      */
     CV_WRAP virtual void apply(InputArray image, OutputArray fgmask, double learningRate=-1) CV_OVERRIDE = 0;
+
+    /** @brief Computes a foreground mask with known foreground mask input.
+
+    @param image Next video frame.
+    @param fgmask The output foreground mask as an 8-bit binary image.
+    @param knownForegroundMask The mask for inputting already known foreground.
+    @param learningRate The value between 0 and 1 that indicates how fast the background model is
+    learnt. Negative parameter value makes the algorithm to use some automatically chosen learning
+    rate. 0 means that the background model is not updated at all, 1 means that the background model
+    is completely reinitialized from the last frame.
+
+    @note This method has a default virtual implementation that throws a "not impemented" error.
+    Foreground masking may not be supported by all background subtractors.
+    */
+    CV_WRAP virtual void apply(InputArray image, InputArray knownForegroundMask, OutputArray fgmask, double learningRate=-1) CV_OVERRIDE = 0;
+
     CV_WRAP virtual void getBackgroundImage(OutputArray backgroundImage) const CV_OVERRIDE = 0;
 
     /** @brief Returns total number of distinct colors to maintain in histogram.
@@ -210,6 +252,22 @@ class CV_EXPORTS_W BackgroundSubtractorCNT  : public BackgroundSubtractor
 public:
     // BackgroundSubtractor interface
     CV_WRAP virtual void apply(InputArray image, OutputArray fgmask, double learningRate=-1) CV_OVERRIDE = 0;
+
+    /** @brief Computes a foreground mask with known foreground mask input.
+
+    @param image Next video frame.
+    @param knownForegroundMask The mask for inputting already known foreground.
+    @param fgmask The output foreground mask as an 8-bit binary image.
+    @param learningRate The value between 0 and 1 that indicates how fast the background model is
+    learnt. Negative parameter value makes the algorithm to use some automatically chosen learning
+    rate. 0 means that the background model is not updated at all, 1 means that the background model
+    is completely reinitialized from the last frame.
+
+    @note This method has a default virtual implementation that throws a "not impemented" error.
+    Foreground masking may not be supported by all background subtractors.
+    */
+    CV_WRAP virtual void apply(InputArray image, InputArray knownForegroundMask, OutputArray fgmask, double learningRate=-1) CV_OVERRIDE = 0;
+
     CV_WRAP virtual void getBackgroundImage(OutputArray backgroundImage) const CV_OVERRIDE = 0;
 
     /** @brief Returns number of frames with same pixel color to consider stable.
@@ -269,6 +327,7 @@ class CV_EXPORTS_W BackgroundSubtractorGSOC : public BackgroundSubtractor
 public:
     // BackgroundSubtractor interface
     CV_WRAP virtual void apply(InputArray image, OutputArray fgmask, double learningRate=-1) CV_OVERRIDE = 0;
+    CV_WRAP virtual void apply(InputArray image, InputArray knownForegroundMask, OutputArray fgmask, double learningRate=-1) CV_OVERRIDE = 0;
 
     CV_WRAP virtual void getBackgroundImage(OutputArray backgroundImage) const CV_OVERRIDE = 0;
 };
@@ -280,6 +339,7 @@ class CV_EXPORTS_W BackgroundSubtractorLSBP : public BackgroundSubtractor
 public:
     // BackgroundSubtractor interface
     CV_WRAP virtual void apply(InputArray image, OutputArray fgmask, double learningRate=-1) CV_OVERRIDE = 0;
+    CV_WRAP virtual void apply(InputArray image, InputArray knownForegroundMask, OutputArray fgmask, double learningRate=-1) CV_OVERRIDE = 0;
 
     CV_WRAP virtual void getBackgroundImage(OutputArray backgroundImage) const CV_OVERRIDE = 0;
 };

modules/bgsegm/src/bgfg_gaussmix.cpp

@@ -104,6 +104,8 @@ class BackgroundSubtractorMOGImpl CV_FINAL : public BackgroundSubtractorMOG
     //! the update operator
     virtual void apply(InputArray image, OutputArray fgmask, double learningRate=0) CV_OVERRIDE;
 
+    virtual void apply(InputArray image, InputArray knownForegroundMask, OutputArray fgmask, double learningRate) CV_OVERRIDE;
+
     //! re-initiaization method
     virtual void initialize(Size _frameSize, int _frameType)
     {
@@ -461,6 +463,15 @@ void BackgroundSubtractorMOGImpl::apply(InputArray _image, OutputArray _fgmask,
         CV_Error( Error::StsUnsupportedFormat, "Only 1- and 3-channel 8-bit images are supported in BackgroundSubtractorMOG" );
 }
 
+void BackgroundSubtractorMOGImpl::apply(InputArray _image, InputArray _knownForegroundMask, OutputArray _fgmask, double learningRate){
+    Mat knownForegroundMask = _knownForegroundMask.getMat();
+    if(!_knownForegroundMask.empty())
+    {
+        CV_Error( Error::StsNotImplemented, "Known Foreground Masking has not been implemented for this specific background subtractor, falling back to subtraction without known foreground");
+    }
+    apply(_image, _fgmask, learningRate);
+}
+
 Ptr<BackgroundSubtractorMOG> createBackgroundSubtractorMOG(int history, int nmixtures,
                                   double backgroundRatio, double noiseSigma)
 {

modules/bgsegm/src/bgfg_gmg.cpp

@@ -97,6 +97,7 @@ class BackgroundSubtractorGMGImpl CV_FINAL : public BackgroundSubtractorGMG
      * @param fgmask Output mask image representing foreground and background pixels
      */
     virtual void apply(InputArray image, OutputArray fgmask, double learningRate=-1.0) CV_OVERRIDE;
+    virtual void apply(InputArray image, InputArray knownForegroundMask, OutputArray fgmask, double learningRate) CV_OVERRIDE;
 
     /**
      * Releases all inner buffers.
@@ -473,6 +474,15 @@ void BackgroundSubtractorGMGImpl::apply(InputArray _frame, OutputArray _fgmask,
     ++frameNum_;
 }
 
+void BackgroundSubtractorGMGImpl::apply(InputArray _image, InputArray _knownForegroundMask, OutputArray _fgmask, double newLearningRate){
+    Mat knownForegroundMask = _knownForegroundMask.getMat();
+    if(!_knownForegroundMask.empty())
+    {
+        CV_Error( Error::StsNotImplemented, "Known Foreground Masking has not been implemented for this specific background subtractor, falling back to subtraction without known foreground");
+    }
+    apply(_image, _fgmask, newLearningRate);
+}
+
 void BackgroundSubtractorGMGImpl::release()
 {
     frameSize_ = Size();

modules/bgsegm/src/bgfg_gsoc.cpp

@@ -494,6 +494,7 @@ class BackgroundSubtractorGSOCImpl CV_FINAL : public BackgroundSubtractorGSOC {
                                  float noiseRemovalThresholdFacFG);
 
     CV_WRAP virtual void apply(InputArray image, OutputArray fgmask, double learningRate = -1) CV_OVERRIDE;
+    CV_WRAP virtual void apply(InputArray image, InputArray knownForegroundMask, OutputArray fgmask, double learningRate) CV_OVERRIDE;
 
     CV_WRAP virtual void getBackgroundImage(OutputArray backgroundImage) const CV_OVERRIDE;
 
@@ -542,6 +543,7 @@ class BackgroundSubtractorLSBPImpl CV_FINAL : public BackgroundSubtractorLSBP {
                                 );
 
     CV_WRAP virtual void apply(InputArray image, OutputArray fgmask, double learningRate = -1) CV_OVERRIDE;
+    CV_WRAP virtual void apply(InputArray image, InputArray knownForegroundMask, OutputArray fgmask, double learningRate) CV_OVERRIDE;
 
     CV_WRAP virtual void getBackgroundImage(OutputArray backgroundImage) const CV_OVERRIDE;
 
@@ -793,6 +795,15 @@ void BackgroundSubtractorGSOCImpl::apply(InputArray _image, OutputArray _fgmask,
     this->postprocessing(fgMask);
 }
 
+void BackgroundSubtractorGSOCImpl::apply(InputArray _image, InputArray _knownForegroundMask, OutputArray _fgmask, double learningRate){
+    Mat knownForegroundMask = _knownForegroundMask.getMat();
+    if(!_knownForegroundMask.empty())
+    {
+        CV_Error( Error::StsNotImplemented, "Known Foreground Masking has not been implemented for this specific background subtractor, falling back to subtraction without known foreground");
+    }
+    apply(_image, _fgmask, learningRate);
+}
+
 void BackgroundSubtractorGSOCImpl::getBackgroundImage(OutputArray _backgroundImage) const {
     CV_Assert(!backgroundModel.empty());
     const Size sz = backgroundModel->getSize();
@@ -928,6 +939,15 @@ void BackgroundSubtractorLSBPImpl::apply(InputArray _image, OutputArray _fgmask,
     this->postprocessing(fgMask);
 }
 
+void BackgroundSubtractorLSBPImpl::apply(InputArray _image, InputArray _knownForegroundMask, OutputArray _fgmask, double learningRate){
+    Mat knownForegroundMask = _knownForegroundMask.getMat();
+    if(!_knownForegroundMask.empty())
+    {
+        CV_Error( Error::StsNotImplemented, "Known Foreground Masking has not been implemented for this specific background subtractor, falling back to subtraction without known foreground");
+    }
+    apply(_image, _fgmask, learningRate);
+}
+
 void BackgroundSubtractorLSBPImpl::getBackgroundImage(OutputArray _backgroundImage) const {
     CV_Assert(!backgroundModel.empty());
     const Size sz = backgroundModel->getSize();

modules/bgsegm/src/bgfg_subcnt.cpp

@@ -61,6 +61,8 @@ class BackgroundSubtractorCNTImpl CV_FINAL : public BackgroundSubtractorCNT
 
     // BackgroundSubtractor interface
     virtual void apply(InputArray image, OutputArray fgmask, double learningRate) CV_OVERRIDE;
+    virtual void apply(InputArray image, InputArray knownForegroundMask, OutputArray fgmask, double learningRate) CV_OVERRIDE;
+
     virtual void getBackgroundImage(OutputArray backgroundImage) const CV_OVERRIDE;
 
     int getMinPixelStability() const CV_OVERRIDE;
@@ -409,6 +411,14 @@ void BackgroundSubtractorCNTImpl::apply(InputArray image, OutputArray _fgmask, d
     prevFrame = frame;
 }
 
+void BackgroundSubtractorCNTImpl::apply(InputArray _image, InputArray _knownForegroundMask, OutputArray _fgmask, double learningRate){
+    Mat knownForegroundMask = _knownForegroundMask.getMat();
+    if(!_knownForegroundMask.empty())
+    {
+        CV_Error( Error::StsNotImplemented, "Known Foreground Masking has not been implemented for this specific background subtractor, falling back to subtraction without known foreground");
+    }
+    apply(_image, _fgmask, learningRate);
+}
 
 Ptr<BackgroundSubtractorCNT> createBackgroundSubtractorCNT(int minPixelStability, bool useHistory, int maxStability, bool isParallel)
 {