OpenCV floodfill with mask - opencv

Question

The documentation for OpenCV's floodfill function states:
The function uses and updates the mask, so you take responsibility of
initializing the mask content. Flood-filling cannot go across non-zero
pixels in the mask. For example, an edge detector output can be used
as a mask to stop filling at edges. It is possible to use the same
mask in multiple calls to the function to make sure the filled area
does not overlap.
How does the function update the mask? Does it set all the pixels within the floodfill to some non-zero value?

Answer 1

All zero-valued pixels in the same connected component as the seed point of the mask are replaced by the value you specify. This value must be added to the flags parameter, left-shifted by 8 bits:
uchar fillValue = 128;
cv::floodFill(img, mask, seed, cv::Scalar(255) ,0, cv::Scalar(), cv::Scalar(), 4 | cv::FLOODFILL_MASK_ONLY | (fillValue << 8));
A simple, but perhaps enlightening example follows. Creating an image like so:
//Create simple input image
cv::Point seed(4,4);
cv::Mat img = cv::Mat::zeros(100,100,CV_8UC1);
cv::circle(img, seed, 20, cv::Scalar(128),3);
Results in this image:
Then, creating a mask and flood-filling it:
//Create a mask from edges in the original image
cv::Mat mask;
cv::Canny(img, mask, 100, 200);
cv::copyMakeBorder(mask, mask, 1, 1, 1, 1, cv::BORDER_REPLICATE);
//Fill mask with value 128
uchar fillValue = 128;
cv::floodFill(img, mask, seed, cv::Scalar(255) ,0, cv::Scalar(), cv::Scalar(), 4 | cv::FLOODFILL_MASK_ONLY | (fillValue << 8));
Gives this result:
The white pixels in the mask are the result of edge detection, while the grey pixels are the result of the flood-fill.
UPDATE:
In response to the comment, flag value 4 specifies the pixel neighborhood with which to compare the color value difference. From the documentation:
Lower bits contain a connectivity value, 4 (default) or 8, used within the function. Connectivity determines which neighbors of a pixel are considered.
When the cv::FLOODFILL_MASK_ONLY flag is not passed, both the image and the mask are updated, but the flood filling will stop at at any nonzero mask values.

Answer 2

And a python version
im = cv2.imread("seagull.jpg")
h,w,chn = im.shape
seed = (w/2,h/2)
mask = np.zeros((h+2,w+2),np.uint8)
floodflags = 4
floodflags |= cv2.FLOODFILL_MASK_ONLY
floodflags |= (255 << 8)
num,im,mask,rect = cv2.floodFill(im, mask, seed, (255,0,0), (10,)*3, (10,)*3, floodflags)
cv2.imwrite("seagull_flood.png", mask)
(Seagull image from Wikimedia: https://commons.wikimedia.org/wiki/Commons:Quality_images#/media/File:Gull_portrait_ca_usa.jpg)
Result:

Answer 3

Per Aurelius' answer, the mask needs to be zeroed.
Checking comment in the source, it stated that
Since this is both an input and output parameter, you must take responsibility
of initializing it. Flood-filling cannot go across non-zero pixels in the input mask.
The mask will impact the result so need to be zeroed before use:
cv::Mat mask;
mask = cv::Mat::zeros(img.rows + 2, img.cols + 2, CV_8UC1);