\cvarg{maxValue}{Maximum value that is used with \texttt{CV\_THRESH\_BINARY} and \texttt{CV\_THRESH\_BINARY\_INV}}
\cvarg{adaptive\_method}{Adaptive thresholding algorithm to use: \texttt{CV\_ADAPTIVE\_THRESH\_MEAN\_C} or \texttt{CV\_ADAPTIVE\_THRESH\_GAUSSIAN\_C} (see the discussion)}
\cvarg{thresholdType}{Thresholding type; must be one of
\begin{description}
\cvarg{CV\_THRESH\_BINARY}{xxx}
\cvarg{CV\_THRESH\_BINARY\_INV}{xxx}
\end{description}}
\cvarg{blockSize}{The size of a pixel neighborhood that is used to calculate a threshold value for the pixel: 3, 5, 7, and so on}
\cvarg{param1}{The method-dependent parameter. For the methods \texttt{CV\_ADAPTIVE\_THRESH\_MEAN\_C} and \texttt{CV\_ADAPTIVE\_THRESH\_GAUSSIAN\_C} it is a constant subtracted from the mean or weighted mean (see the discussion), though it may be negative}
\end{description}
The function transforms a grayscale image to a binary image according to the formulas:
where $T(x,y)$ is a threshold calculated individually for each pixel.
For the method \texttt{CV\_ADAPTIVE\_THRESH\_MEAN\_C} it is the mean of a $\texttt{blockSize}\times\texttt{blockSize}$ pixel neighborhood, minus \texttt{param1}.
For the method \texttt{CV\_ADAPTIVE\_THRESH\_GAUSSIAN\_C} it is the weighted sum (gaussian) of a $\texttt{blockSize}\times\texttt{blockSize}$ pixel neighborhood, minus \texttt{param1}.
\cvCPyFunc{CvtColor}
Converts an image from one color space to another.
\cvarg{dst}{The destination image of the same data type as the source. The number of channels may be different}
\cvarg{code}{Color conversion operation that can be specifed using \texttt{CV\_\textit{src\_color\_space} 2 \textit{dst\_color\_space}} constants (see below)}
\end{description}
The function converts the input image from one color
space to another. The function ignores the \texttt{colorModel} and
\texttt{channelSeq} fields of the \texttt{IplImage} header, so the
source image color space should be specified correctly (including
order of the channels in the case of RGB space. For example, BGR means 24-bit
format with $B_0, G_0, R_0, B_1, G_1, R_1, ...$ layout
whereas RGB means 24-format with $R_0, G_0, B_0, R_1, G_1, B_1, ...$
layout).
The conventional range for R,G,B channel values is:
\begin{itemize}
\item 0 to 255 for 8-bit images
\item 0 to 65535 for 16-bit images and
\item 0 to 1 for floating-point images.
\end{itemize}
Of course, in the case of linear transformations the range can be
specific, but in order to get correct results in the case of non-linear
transformations, the input image should be scaled.
The function can do the following transformations:
\begin{itemize}
\item Transformations within RGB space like adding/removing the alpha channel, reversing the channel order, conversion to/from 16-bit RGB color (R5:G6:B5 or R5:G5:B5), as well as conversion to/from grayscale using:
\[
\text{RGB[A] to Gray:} Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
\]
and
\[
\text{Gray to RGB[A]:} R \leftarrow Y, G \leftarrow Y, B \leftarrow Y, A \leftarrow 0
\]
The conversion from a RGB image to gray is done with:
\begin{lstlisting}
cvCvtColor(src ,bwsrc, CV_RGB2GRAY)
\end{lstlisting}
\item RGB $\leftrightarrow$ CIE XYZ.Rec 709 with D65 white point (\texttt{CV\_BGR2XYZ, CV\_RGB2XYZ, CV\_XYZ2BGR, CV\_XYZ2RGB}):
\[
\begin{bmatrix}
X \\
Y \\
Z
\end{bmatrix}
\leftarrow
\begin{bmatrix}
0.412453 & 0.357580 & 0.180423\\
0.212671 & 0.715160 & 0.072169\\
0.019334 & 0.119193 & 0.950227
\end{bmatrix}
\cdot
\begin{bmatrix}
R \\
G \\
B
\end{bmatrix}
\]
\[
\begin{bmatrix}
R \\
G \\
B
\end{bmatrix}
\leftarrow
\begin{bmatrix}
3.240479 & -1.53715 & -0.498535\\
-0.969256 & 1.875991 & 0.041556\\
0.055648 & -0.204043 & 1.057311
\end{bmatrix}
\cdot
\begin{bmatrix}
X \\
Y \\
Z
\end{bmatrix}
\]
$X$, $Y$ and $Z$ cover the whole value range (in the case of floating-point images $Z$ may exceed 1).
R, G and B are converted to floating-point format and scaled to fit 0 to 1 range
\[\vecthree{X}{Y}{Z}\leftarrow\vecthreethree
{0.412453}{0.357580}{0.180423}
{0.212671}{0.715160}{0.072169}
{0.019334}{0.119193}{0.950227}
\cdot
\vecthree{R}{G}{B}\]
\[ L \leftarrow\fork
{116 Y^{1/3}}{for $Y>0.008856$}
{903.3 Y}{for $Y<=0.008856$}\]
\[ u' \leftarrow4*X/(X +15*Y +3 Z)\]
\[ v' \leftarrow9*Y/(X +15*Y +3 Z)\]
\[ u \leftarrow13*L*(u' - u_n)\quad\text{where}\quad u_n=0.19793943\]
\[ v \leftarrow13*L*(v' - v_n)\quad\text{where}\quad v_n=0.46831096\]
On output $0\leq L \leq100$, $-134\leq u \leq220$, $-140\leq v \leq122$.
The values are then converted to the destination data type:
\begin{description}
\item[8-bit images]
\[L \leftarrow255/100 L, u \leftarrow255/354(u +134), v \leftarrow255/256(v +140)\]
\item[16-bit images] currently not supported
\item[32-bit images] L, u, v are left as is
\end{description}
The above formulas for converting RGB to/from various color spaces have been taken from multiple sources on Web, primarily from
the Ford98
at the Charles Poynton site.
\item Bayer $\rightarrow$ RGB (\texttt{CV\_BayerBG2BGR, CV\_BayerGB2BGR, CV\_BayerRG2BGR, CV\_BayerGR2BGR, CV\_BayerBG2RGB, CV\_BayerGB2RGB, CV\_BayerRG2RGB, CV\_BayerGR2RGB}) The Bayer pattern is widely used in CCD and CMOS cameras. It allows one to get color pictures from a single plane where R,G and B pixels (sensors of a particular component) are interleaved like this:
\cvarg{dst}{Output image with calculated distances (32-bit floating-point, single-channel)}
\cvarg{distance\_type}{Type of distance; can be \texttt{CV\_DIST\_L1, CV\_DIST\_L2, CV\_DIST\_C} or \texttt{CV\_DIST\_USER}}
\cvarg{mask\_size}{Size of the distance transform mask; can be 3 or 5. in the case of \texttt{CV\_DIST\_L1} or \texttt{CV\_DIST\_C} the parameter is forced to 3, because a $3\times3$ mask gives the same result as a $5\times5$ yet it is faster}
\cvarg{mask}{User-defined mask in the case of a user-defined distance, it consists of 2 numbers (horizontal/vertical shift cost, diagonal shift cost) in the case ofa $3\times3$ mask and 3 numbers (horizontal/vertical shift cost, diagonal shift cost, knight's move cost) in the case of a $5\times5$ mask}
\cvarg{labels}{The optional output 2d array of integer type labels, the same size as \texttt{src} and \texttt{dst}}
\end{description}
The function calculates the approximated
distance from every binary image pixel to the nearest zero pixel.
For zero pixels the function sets the zero distance, for others it
finds the shortest path consisting of basic shifts: horizontal,
vertical, diagonal or knight's move (the latest is available for a
$5\times5$ mask). The overall distance is calculated as a sum of these
basic distances. Because the distance function should be symmetric,
all of the horizontal and vertical shifts must have the same cost (that
is denoted as \texttt{a}), all the diagonal shifts must have the
same cost (denoted \texttt{b}), and all knight's moves must have
the same cost (denoted \texttt{c}). For \texttt{CV\_DIST\_C} and
\texttt{CV\_DIST\_L1} types the distance is calculated precisely,
whereas for \texttt{CV\_DIST\_L2} (Euclidian distance) the distance
can be calculated only with some relative error (a $5\times5$ mask
gives more accurate results), OpenCV uses the values suggested in
\cite{Borgefors86}:
\begin{tabular}{| c | c | c |}
\hline
\texttt{CV\_DIST\_C}&$(3\times3)$& a = 1, b = 1\\\hline
\texttt{CV\_DIST\_L1}&$(3\times3)$& a = 1, b = 2\\\hline
\cvarg{image}{Input 1- or 3-channel, 8-bit or floating-point image. It is modified by the function unless the \texttt{CV\_FLOODFILL\_MASK\_ONLY} flag is set (see below)}
\cvarg{seed\_point}{The starting point}
\cvarg{new\_val}{New value of the repainted domain pixels}
\cvarg{lo\_diff}{Maximal lower brightness/color difference between the currently observed pixel and one of its neighbors belonging to the component, or a seed pixel being added to the component. In the case of 8-bit color images it is a packed value}
\cvarg{up\_diff}{Maximal upper brightness/color difference between the currently observed pixel and one of its neighbors belonging to the component, or a seed pixel being added to the component. In the case of 8-bit color images it is a packed value}
\ifC% {
\cvarg{comp}{Pointer to the structure that the function fills with the information about the repainted domain.
Note that the function does not fill \texttt{comp->contour} field. The boundary of the filled component can be retrieved from the output mask image using \cvCPyCross{FindContours}}
\else% }{
\cvarg{comp}{Returned connected component for the repainted domain. Note that the function does not fill \texttt{comp->contour} field. The boundary of the filled component can be retrieved from the output mask image using \cvCPyCross{FindContours}}
\fi% }
\cvarg{flags}{The operation flags. Lower bits contain connectivity value, 4 (by default) or 8, used within the function. Connectivity determines which neighbors of a pixel are considered. Upper bits can be 0 or a combination of the following flags:
\begin{description}
\cvarg{CV\_FLOODFILL\_FIXED\_RANGE}{if set, the difference between the current pixel and seed pixel is considered, otherwise the difference between neighbor pixels is considered (the range is floating)}
\cvarg{CV\_FLOODFILL\_MASK\_ONLY}{if set, the function does not fill the image (\texttt{new\_val} is ignored), but fills the mask (that must be non-NULL in this case)}
\end{description}}
\cvarg{mask}{Operation mask, should be a single-channel 8-bit image, 2 pixels wider and 2 pixels taller than \texttt{image}. If not NULL, the function uses and updates the mask, so the user takes responsibility of initializing the \texttt{mask} content. Floodfilling can't 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 do not overlap. \textbf{Note}: because the mask is larger than the filled image, a pixel in \texttt{mask} that corresponds to $(x,y)$ pixel in \texttt{image} will have coordinates $(x+1,y+1)$}
\end{description}
The function fills a connected component starting from the seed point with the specified color. The connectivity is determined by the closeness of pixel values. The pixel at $(x,y)$ is considered to belong to the repainted domain if:
where $src(x',y')$ is the value of one of pixel neighbors. That is, to be added to the connected component, a pixel's color/brightness should be close enough to the:
\begin{itemize}
\item color/brightness of one of its neighbors that are already referred to the connected component in the case of floating range
\item color/brightness of the seed point in the case of fixed range.
\cvarg{src}{The input 8-bit 1-channel or 3-channel image.}
\cvarg{mask}{The inpainting mask, 8-bit 1-channel image. Non-zero pixels indicate the area that needs to be inpainted.}
\cvarg{dst}{The output image of the same format and the same size as input.}
\cvarg{inpaintRadius}{The radius of circlular neighborhood of each point inpainted that is considered by the algorithm.}
\cvarg{flags}{The inpainting method, one of the following:
\begin{description}
\cvarg{CV\_INPAINT\_NS}{Navier-Stokes based method.}
\cvarg{CV\_INPAINT\_TELEA}{The method by Alexandru Telea \cite{Telea04}}
\end{description}}
\end{description}
The function reconstructs the selected image area from the pixel near the area boundary. The function may be used to remove dust and scratches from a scanned photo, or to remove undesirable objects from still images or video.
Using these integral images, one may calculate sum, mean and standard deviation over a specific up-right or rotated rectangular region of the image in a constant time, for example:
It makes possible to do a fast blurring or fast block correlation with variable window size, for example. In the case of multi-channel images, sums for each channel are accumulated independently.
\cvarg{dst}{The destination image of the same format and the same size as the source.}
\cvarg{sp}{The spatial window radius.}
\cvarg{sr}{The color window radius.}
\cvarg{max\_level}{Maximum level of the pyramid for the segmentation.}
\cvarg{termcrit}{Termination criteria: when to stop meanshift iterations.}
\end{description}
The function implements the filtering
stage of meanshift segmentation, that is, the output of the function is
the filtered "posterized" image with color gradients and fine-grain
texture flattened. At every pixel $(X,Y)$ of the input image (or
down-sized input image, see below) the function executes meanshift
iterations, that is, the pixel $(X,Y)$ neighborhood in the joint
space-color hyperspace is considered:
\[
(x,y): X-\texttt{sp}\le x \le X+\texttt{sp} , Y-\texttt{sp}\le y \le Y+\texttt{sp} , ||(R,G,B)-(r,g,b)|| \le\texttt{sr}
\]
where \texttt{(R,G,B)} and \texttt{(r,g,b)} are the vectors of color components at \texttt{(X,Y)} and \texttt{(x,y)}, respectively (though, the algorithm does not depend on the color space used, so any 3-component color space can be used instead). Over the neighborhood the average spatial value \texttt{(X',Y')} and average color vector \texttt{(R',G',B')} are found and they act as the neighborhood center on the next iteration:
$(X,Y)~(X',Y'), (R,G,B)~(R',G',B').$
After the iterations over, the color components of the initial pixel (that is, the pixel from where the iterations started) are set to the final value (average color at the last iteration):
$I(X,Y) <-(R*,G*,B*)$
Then $\texttt{max\_level}>0$ , the gaussian pyramid of
$\texttt{max\_level}+1$ levels is built, and the above procedure is run
on the smallest layer. After that, the results are propagated to the
larger layer and the iterations are run again only on those pixels where
the layer colors differ much ( $>\texttt{sr}$ ) from the lower-resolution
layer, that is, the boundaries of the color regions are clarified. Note,
that the results will be actually different from the ones obtained by
running the meanshift procedure on the whole original image (i.e. when
\cvarg{storage}{Storage; stores the resulting sequence of connected components}
\cvarg{comp}{Pointer to the output sequence of the segmented components}
\cvarg{level}{Maximum level of the pyramid for the segmentation}
\cvarg{threshold1}{Error threshold for establishing the links}
\cvarg{threshold2}{Error threshold for the segments clustering}
\end{description}
The function implements image segmentation by pyramids. The pyramid builds up to the level \texttt{level}. The links between any pixel \texttt{a} on level \texttt{i} and its candidate father pixel \texttt{b} on the adjacent level are established if
$p(c(a),c(b))<threshold1$.
After the connected components are defined, they are joined into several clusters.
Any two segments A and B belong to the same cluster, if $p(c(A),c(B))<threshold2$.
If the input image has only one channel, then $p(c^1,c^2)=|c^1-c^2|$.
If the input image has three channels (red, green and blue), then
\[
p(c^1,c^2) = 0.30 (c^1_r - c^2_r) +
0.59 (c^1_g - c^2_g) +
0.11 (c^1_b - c^2_b).
\]
There may be more than one connected component per a cluster. The images \texttt{src} and \texttt{dst} should be 8-bit single-channel or 3-channel images or equal size.
\cvCPyFunc{Threshold}
Applies a fixed-level threshold to array elements.
where $T(x,y)$ is a threshold calculated individually for each pixel.
\begin{enumerate}
\item
For the method \texttt{ADAPTIVE\_THRESH\_MEAN\_C} the threshold value $T(x,y)$ is the mean of a $\texttt{blockSize}\times\texttt{blockSize}$ neighborhood of $(x, y)$, minus \texttt{C}.
\item
For the method \texttt{ADAPTIVE\_THRESH\_GAUSSIAN\_C} the threshold value $T(x, y)$ is the weighted sum (i.e. cross-correlation with a Gaussian window) of a $\texttt{blockSize}\times\texttt{blockSize}$ neighborhood of $(x, y)$, minus \texttt{C}. The default sigma (standard deviation) is used for the specified \texttt{blockSize}, see \cvCppCross{getGaussianKernel}.
\end{enumerate}
The function can process the image in-place.
See also: \cvCppCross{threshold}, \cvCppCross{blur}, \cvCppCross{GaussianBlur}
\cvCppFunc{cvtColor}
Converts image from one color space to another
\cvdefCpp{void cvtColor( const Mat\& src, Mat\& dst, int code, int dstCn=0 );}
\cvarg{dst}{The destination image; will have the same size and the same depth as \texttt{src}}
\cvarg{code}{The color space conversion code; see the discussion}
\cvarg{dstCn}{The number of channels in the destination image; if the parameter is 0, the number of the channels will be derived automatically from \texttt{src} and the \texttt{code}}
\end{description}
The function converts the input image from one color
space to another. In the case of transformation to-from RGB color space the ordering of the channels should be specified explicitly (RGB or BGR).
The conventional ranges for R, G and B channel values are:
\begin{itemize}
\item 0 to 255 for \texttt{CV\_8U} images
\item 0 to 65535 for \texttt{CV\_16U} images and
\item 0 to 1 for \texttt{CV\_32F} images.
\end{itemize}
Of course, in the case of linear transformations the range does not matter,
but in the non-linear cases the input RGB image should be normalized to the proper value range in order to get the correct results, e.g. for RGB$\rightarrow$L*u*v* transformation. For example, if you have a 32-bit floating-point image directly converted from 8-bit image without any scaling, then it will have 0..255 value range, instead of the assumed by the function 0..1. So, before calling \texttt{cvtColor}, you need first to scale the image down:
\begin{lstlisting}
img *= 1./255;
cvtColor(img, img, CV_BGR2Luv);
\end{lstlisting}
The function can do the following transformations:
\begin{itemize}
\item Transformations within RGB space like adding/removing the alpha channel, reversing the channel order, conversion to/from 16-bit RGB color (R5:G6:B5 or R5:G5:B5), as well as conversion to/from grayscale using:
\[
\text{RGB[A] to Gray:}\quad Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
\]
and
\[
\text{Gray to RGB[A]:}\quad R \leftarrow Y, G \leftarrow Y, B \leftarrow Y, A \leftarrow 0
\]
The conversion from a RGB image to gray is done with:
\begin{lstlisting}
cvtColor(src, bwsrc, CV_RGB2GRAY);
\end{lstlisting}
Some more advanced channel reordering can also be done with \cvCppCross{mixChannels}.
\item RGB $\leftrightarrow$ CIE XYZ.Rec 709 with D65 white point (\texttt{CV\_BGR2XYZ, CV\_RGB2XYZ, CV\_XYZ2BGR, CV\_XYZ2RGB}):
\[
\begin{bmatrix}
X \\
Y \\
Z
\end{bmatrix}
\leftarrow
\begin{bmatrix}
0.412453 & 0.357580 & 0.180423\\
0.212671 & 0.715160 & 0.072169\\
0.019334 & 0.119193 & 0.950227
\end{bmatrix}
\cdot
\begin{bmatrix}
R \\
G \\
B
\end{bmatrix}
\]
\[
\begin{bmatrix}
R \\
G \\
B
\end{bmatrix}
\leftarrow
\begin{bmatrix}
3.240479 & -1.53715 & -0.498535\\
-0.969256 & 1.875991 & 0.041556\\
0.055648 & -0.204043 & 1.057311
\end{bmatrix}
\cdot
\begin{bmatrix}
X \\
Y \\
Z
\end{bmatrix}
\]
$X$, $Y$ and $Z$ cover the whole value range (in the case of floating-point images $Z$ may exceed 1).
R, G and B are converted to floating-point format and scaled to fit 0 to 1 range
\[\vecthree{X}{Y}{Z}\leftarrow\vecthreethree
{0.412453}{0.357580}{0.180423}
{0.212671}{0.715160}{0.072169}
{0.019334}{0.119193}{0.950227}
\cdot
\vecthree{R}{G}{B}\]
\[ L \leftarrow\fork
{116 Y^{1/3}}{for $Y>0.008856$}
{903.3 Y}{for $Y\leq0.008856$}\]
\[ u' \leftarrow4*X/(X +15*Y +3 Z)\]
\[ v' \leftarrow9*Y/(X +15*Y +3 Z)\]
\[ u \leftarrow13*L*(u' - u_n)\quad\text{where}\quad u_n=0.19793943\]
\[ v \leftarrow13*L*(v' - v_n)\quad\text{where}\quad v_n=0.46831096\]
On output $0\leq L \leq100$, $-134\leq u \leq220$, $-140\leq v \leq122$.
The values are then converted to the destination data type:
\begin{description}
\item[8-bit images]
\[L \leftarrow255/100 L,\; u \leftarrow255/354(u +134),\; v \leftarrow255/256(v +140)\]
\item[16-bit images] currently not supported
\item[32-bit images] L, u, v are left as is
\end{description}
The above formulas for converting RGB to/from various color spaces have been taken from multiple sources on Web, primarily from the Charles Poynton site \url{http://www.poynton.com/ColorFAQ.html}
\item Bayer $\rightarrow$ RGB (\texttt{CV\_BayerBG2BGR, CV\_BayerGB2BGR, CV\_BayerRG2BGR, CV\_BayerGR2BGR, CV\_BayerBG2RGB, CV\_BayerGB2RGB, CV\_BayerRG2RGB, CV\_BayerGR2RGB}) The Bayer pattern is widely used in CCD and CMOS cameras. It allows one to get color pictures from a single plane where R,G and B pixels (sensors of a particular component) are interleaved like this:
\cvarg{dst}{Output image with calculated distances; will be 32-bit floating-point, single-channel image of the same size as \texttt{src}}
\cvarg{distanceType}{Type of distance; can be \texttt{CV\_DIST\_L1, CV\_DIST\_L2} or \texttt{CV\_DIST\_C}}
\cvarg{maskSize}{Size of the distance transform mask; can be 3, 5 or \texttt{CV\_DIST\_MASK\_PRECISE} (the latter option is only supported by the first of the functions). In the case of \texttt{CV\_DIST\_L1} or \texttt{CV\_DIST\_C} distance type the parameter is forced to 3, because a $3\times3$ mask gives the same result as a $5\times5$ or any larger aperture.}
\cvarg{labels}{The optional output 2d array of labels - the discrete Voronoi diagram; will have type \texttt{CV\_32SC1} and the same size as \texttt{src}. See the discussion}
\end{description}
The functions \texttt{distanceTransform} calculate the approximate or precise
distance from every binary image pixel to the nearest zero pixel.
(for zero image pixels the distance will obviously be zero).
When \texttt{maskSize == CV\_DIST\_MASK\_PRECISE} and \texttt{distanceType == CV\_DIST\_L2}, the function runs the algorithm described in \cite{Felzenszwalb04}.
In other cases the algorithm \cite{Borgefors86} is used, that is,
for pixel the function finds the shortest path to the nearest zero pixel
consisting of basic shifts: horizontal,
vertical, diagonal or knight's move (the latest is available for a
$5\times5$ mask). The overall distance is calculated as a sum of these
basic distances. Because the distance function should be symmetric,
all of the horizontal and vertical shifts must have the same cost (that
is denoted as \texttt{a}), all the diagonal shifts must have the
same cost (denoted \texttt{b}), and all knight's moves must have
the same cost (denoted \texttt{c}). For \texttt{CV\_DIST\_C} and
\texttt{CV\_DIST\_L1} types the distance is calculated precisely,
whereas for \texttt{CV\_DIST\_L2} (Euclidian distance) the distance
can be calculated only with some relative error (a $5\times5$ mask
gives more accurate results). For \texttt{a}, \texttt{b} and \texttt{c}
OpenCV uses the values suggested in the original paper:
\begin{tabular}{| c | c | c |}
\hline
\texttt{CV\_DIST\_C}&$(3\times3)$& a = 1, b = 1\\\hline
\texttt{CV\_DIST\_L1}&$(3\times3)$& a = 1, b = 2\\\hline
\cvarg{image}{Input/output 1- or 3-channel, 8-bit or floating-point image. It is modified by the function unless the \texttt{FLOODFILL\_MASK\_ONLY} flag is set (in the second variant of the function; see below)}
\cvarg{mask}{(For the second function only) Operation mask, should be a single-channel 8-bit image, 2 pixels wider and 2 pixels taller. The function uses and updates the mask, so the user takes responsibility of initializing the \texttt{mask} content. Flood-filling can't 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 do not overlap. \textbf{Note}: because the mask is larger than the filled image, a pixel $(x, y)$ in \texttt{image} will correspond to the pixel $(x+1, y+1)$ in the \texttt{mask}}
\cvarg{seed}{The starting point}
\cvarg{newVal}{New value of the repainted domain pixels}
\cvarg{loDiff}{Maximal lower brightness/color difference between the currently observed pixel and one of its neighbors belonging to the component, or a seed pixel being added to the component}
\cvarg{upDiff}{Maximal upper brightness/color difference between the currently observed pixel and one of its neighbors belonging to the component, or a seed pixel being added to the component}
\cvarg{rect}{The optional output parameter that the function sets to the minimum bounding rectangle of the repainted domain}
\cvarg{flags}{The operation flags. Lower bits contain connectivity value, 4 (by default) or 8, used within the function. Connectivity determines which neighbors of a pixel are considered. Upper bits can be 0 or a combination of the following flags:
\begin{description}
\cvarg{FLOODFILL\_FIXED\_RANGE}{if set, the difference between the current pixel and seed pixel is considered, otherwise the difference between neighbor pixels is considered (i.e. the range is floating)}
\cvarg{FLOODFILL\_MASK\_ONLY}{(for the second variant only) if set, the function does not change the image (\texttt{newVal} is ignored), but fills the mask}
\end{description}}
\end{description}
The functions \texttt{floodFill} fill a connected component starting from the seed point with the specified color. The connectivity is determined by the color/brightness closeness of the neighbor pixels. The pixel at $(x,y)$ is considered to belong to the repainted domain if:
where $src(x',y')$ is the value of one of pixel neighbors that is already known to belong to the component. That is, to be added to the connected component, a pixel's color/brightness should be close enough to the:
\begin{itemize}
\item color/brightness of one of its neighbors that are already referred to the connected component in the case of floating range
\item color/brightness of the seed point in the case of fixed range.
\end{itemize}
By using these functions you can either mark a connected component with the specified color in-place, or build a mask and then extract the contour or copy the region to another image etc. Various modes of the function are demonstrated in \texttt{floodfill.c} sample.
\cvarg{src}{The input 8-bit 1-channel or 3-channel image.}
\cvarg{inpaintMask}{The inpainting mask, 8-bit 1-channel image. Non-zero pixels indicate the area that needs to be inpainted.}
\cvarg{dst}{The output image; will have the same size and the same type as \texttt{src}}
\cvarg{inpaintRadius}{The radius of a circlular neighborhood of each point inpainted that is considered by the algorithm.}
\cvarg{flags}{The inpainting method, one of the following:
\begin{description}
\cvarg{INPAINT\_NS}{Navier-Stokes based method.}
\cvarg{INPAINT\_TELEA}{The method by Alexandru Telea \cite{Telea04}}
\end{description}}
\end{description}
The function reconstructs the selected image area from the pixel near the area boundary. The function may be used to remove dust and scratches from a scanned photo, or to remove undesirable objects from still images or video. See \url{http://en.wikipedia.org/wiki/Inpainting} for more details.
\cvCppFunc{integral}
Calculates the integral of an image.
\cvdefCpp{void integral( const Mat\& image, Mat\& sum, int sdepth=-1 );\newline
Using these integral images, one may calculate sum, mean and standard deviation over a specific up-right or rotated rectangular region of the image in a constant time, for example:
\[
\sum_{x_1\leq x < x_2, \, y_1 \leq y < y_2}\texttt{image}(x,y) = \texttt{sum}(x_2,y_2)-\texttt{sum}(x_1,y_2)-\texttt{sum}(x_2,y_1)+\texttt{sum}(x_1,x_1)
\]
It makes possible to do a fast blurring or fast block correlation with variable window size, for example. In the case of multi-channel images, sums for each channel are accumulated independently.
As a practical example, the next figure shows the calculation of the integral of a straight rectangle \texttt{Rect(3,3,3,2)} and of a tilted rectangle \texttt{Rect(5,1,2,3)}. The selected pixels in the original \texttt{image} are shown, as well as the relative pixels in the integral images \texttt{sum} and \texttt{tilted}.
\cvdefCpp{void grabCut(const Mat\& image, Mat\& mask, Rect rect,\par
Mat\& bgdModel, Mat\& fgdModel,\par int iterCount, int mode );}
\begin{description}
\cvarg{image}{The input 8-bit 3-channel image.}
\cvarg{mask}{The input/output 8-bit single-channel mask. Its elements may have one of four values. The mask is initialize when \texttt{mode==GC\_INIT\_WITH\_RECT}}
\begin{description}
\cvarg{GC\_BGD}{Certainly a background pixel}
\cvarg{GC\_FGD}{Certainly a foreground (object) pixel}
\cvarg{GC\_PR\_BGD}{Likely a background pixel}
\cvarg{GC\_PR\_BGD}{Likely a foreground pixel}
\end{description}
\cvarg{rect}{The ROI containing the segmented object. The pixels outside of the ROI are marked as "certainly a background". The parameter is only used when \texttt{mode==GC\_INIT\_WITH\_RECT}}
\cvarg{bgdModel, fgdModel}{Temporary arrays used for segmentation. Do not modify them while you are processing the same image}
\cvarg{iterCount}{The number of iterations the algorithm should do before returning the result. Note that the result can be refined with further calls with the \texttt{mode==GC\_INIT\_WITH\_MASK} or \texttt{mode==GC\_EVAL}}
\cvarg{mode}{The operation mode}
\begin{description}
\cvarg{GC\_INIT\_WITH\_RECT}{The function initializes the state and the mask using the provided rectangle. After that it runs \texttt{iterCount} iterations of the algorithm}
\cvarg{GC\_INIT\_WITH\_MASK}{The function initializes the state using the provided mask. Note that \texttt{GC\_INIT\_WITH\_RECT} and \texttt{GC\_INIT\_WITH\_MASK} can be combined, then all the pixels outside of the ROI are automatically initialized with \texttt{GC\_BGD}}.
\cvarg{GC\_EVAL}{The value means that algorithm should just resume.}
\end{description}
\end{description}
The function implements the \href{http://en.wikipedia.org/wiki/GrabCut}{GrabCut} image segmentation algorithm.
See the sample grabcut.cpp on how to use the function.
