opencv/modules/imgproc/doc/miscellaneous_transformations.rst

794 lines
31 KiB
ReStructuredText
Raw Normal View History

Miscellaneous Image Transformations
===================================
.. highlight:: cpp
.. index:: adaptiveThreshold
2011-03-09 06:22:24 +08:00
.. _adaptiveThreshold:
adaptiveThreshold
---------------------
.. c:function:: void adaptiveThreshold( const Mat& src, Mat& dst, double maxValue, int adaptiveMethod, int thresholdType, int blockSize, double C )
Applies an adaptive threshold to an array.
2011-04-25 05:02:14 +08:00
:param src: Source 8-bit single-channel image.
2011-04-25 05:02:14 +08:00
:param dst: Destination image of the same size and the same type as ``src`` .
2011-04-25 05:02:14 +08:00
:param maxValue: Non-zero value assigned to the pixels for which the condition is satisfied. See the details below.
2011-04-25 05:02:14 +08:00
:param adaptiveMethod: Adaptive thresholding algorithm to use, ``ADAPTIVE_THRESH_MEAN_C`` or ``ADAPTIVE_THRESH_GAUSSIAN_C`` . See the details below.
2011-04-25 05:02:14 +08:00
:param thresholdType: Thresholding type that must be either ``THRESH_BINARY`` or ``THRESH_BINARY_INV`` .
:param blockSize: Size of a pixel neighborhood that is used to calculate a threshold value for the pixel: 3, 5, 7, and so on.
2011-04-25 05:02:14 +08:00
:param C: Constant subtracted from the mean or weighted mean (see the details below). Normally, it is positive but may be zero or negative as well.
2011-04-25 05:02:14 +08:00
The function transforms a grayscale image to a binary image according to the formulae:
2011-02-26 19:05:10 +08:00
* **THRESH_BINARY**
.. math::
2011-02-26 19:05:10 +08:00
dst(x,y) = \fork{\texttt{maxValue}}{if $src(x,y) > T(x,y)$}{0}{otherwise}
* **THRESH_BINARY_INV**
.. math::
2011-02-26 19:05:10 +08:00
dst(x,y) = \fork{0}{if $src(x,y) > T(x,y)$}{\texttt{maxValue}}{otherwise}
2011-02-26 19:05:10 +08:00
where
:math:`T(x,y)` is a threshold calculated individually for each pixel.
2011-04-25 05:02:14 +08:00
*
For the method ``ADAPTIVE_THRESH_MEAN_C`` , the threshold value
:math:`T(x,y)` is a mean of the
2011-02-26 19:05:10 +08:00
:math:`\texttt{blockSize} \times \texttt{blockSize}` neighborhood of
2011-04-25 05:02:14 +08:00
:math:`(x, y)` minus ``C`` .
2011-04-25 05:02:14 +08:00
*
For the method ``ADAPTIVE_THRESH_GAUSSIAN_C`` , the threshold value
:math:`T(x, y)` is a weighted sum (cross-correlation with a Gaussian window) of the
2011-02-26 19:05:10 +08:00
:math:`\texttt{blockSize} \times \texttt{blockSize}` neighborhood of
2011-04-25 05:02:14 +08:00
:math:`(x, y)` minus ``C`` . The default sigma (standard deviation) is used for the specified ``blockSize`` . See
2011-02-26 19:05:10 +08:00
:func:`getGaussianKernel` .
2011-02-26 19:05:10 +08:00
The function can process the image in-place.
2011-04-25 05:02:14 +08:00
See Also:
:func:`threshold`,
:func:`blur`,
:func:`GaussianBlur`
2011-03-09 06:22:24 +08:00
.. index:: cvtColor
2011-03-09 06:22:24 +08:00
.. _cvtColor:
cvtColor
------------
.. c:function:: void cvtColor( const Mat& src, Mat& dst, int code, int dstCn=0 )
2011-04-25 05:02:14 +08:00
Converts an image from one color space to another.
2011-04-25 05:02:14 +08:00
:param src: Source image: 8-bit unsigned, 16-bit unsigned ( ``CV_16UC...`` ), or single-precision floating-point.
2011-04-25 05:02:14 +08:00
:param dst: Destination image of the same size and depth as ``src`` .
:param code: Color space conversion code. See the details below.??/formatting/
2011-04-25 05:02:14 +08:00
:param dstCn: Number of channels in the destination image. If the parameter is 0, the number of the channels is derived automatically from ``src`` and ``code`` .
2011-04-25 05:02:14 +08:00
The function converts an input image from one color
space to another. In case of transformation to-from RGB color space, the order of the channels should be specified explicitly (RGB or BGR).
2011-04-25 05:02:14 +08:00
The conventional ranges for R, G, and B channel values are:
*
2011-02-26 19:05:10 +08:00
0 to 255 for ``CV_8U`` images
*
2011-04-25 05:02:14 +08:00
0 to 65535 for ``CV_16U`` images
*
2011-04-25 05:02:14 +08:00
0 to 1 for ``CV_32F`` images
2011-02-26 19:05:10 +08:00
2011-04-25 05:02:14 +08:00
In case of linear transformations, the range does not matter.
But in case of a non-linear transformation, an input RGB image should be normalized to the proper value range to get the correct results, for example, for RGB
:math:`\rightarrow` L*u*v* transformation. For example, if you have a 32-bit floating-point image directly converted from an 8-bit image without any scaling, then it will have the 0..255 value range, instead of 0..1 assumed by the function. So, before calling ``cvtColor`` , you need first to scale the image down: ::
img *= 1./255;
cvtColor(img, img, CV_BGR2Luv);
The function can do the following transformations:
*
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:
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\text{RGB[A] to Gray:} \quad Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
2011-02-26 19:05:10 +08:00
and
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\text{Gray to RGB[A]:} \quad R \leftarrow Y, G \leftarrow Y, B \leftarrow Y, A \leftarrow 0
2011-02-26 19:05:10 +08:00
The conversion from a RGB image to gray is done with:
2011-02-26 19:05:10 +08:00
::
2011-02-26 19:05:10 +08:00
cvtColor(src, bwsrc, CV_RGB2GRAY);
2011-02-26 19:05:10 +08:00
..
2011-02-26 19:05:10 +08:00
2011-04-25 05:02:14 +08:00
More advanced channel reordering can also be done with
2011-02-26 19:05:10 +08:00
:func:`mixChannels` .
*
2011-02-26 19:05:10 +08:00
RGB
:math:`\leftrightarrow` CIE XYZ.Rec 709 with D65 white point ( ``CV_BGR2XYZ, CV_RGB2XYZ, CV_XYZ2BGR, CV_XYZ2RGB`` ):
.. math::
2011-02-26 19:05:10 +08:00
\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
2011-02-26 19:05:10 +08:00
\end{bmatrix}
.. math::
2011-02-26 19:05:10 +08:00
\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
2011-02-26 19:05:10 +08:00
\end{bmatrix}
:math:`X`, :math:`Y` and
2011-04-25 05:02:14 +08:00
:math:`Z` cover the whole value range (in case of floating-point images,
2011-02-26 19:05:10 +08:00
:math:`Z` may exceed 1).
*
2011-02-26 19:05:10 +08:00
RGB
2011-04-25 05:02:14 +08:00
:math:`\leftrightarrow` YCrCb JPEG (or YCC) ( ``CV_BGR2YCrCb, CV_RGB2YCrCb, CV_YCrCb2BGR, CV_YCrCb2RGB`` )
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
.. math::
2011-02-26 19:05:10 +08:00
Cr \leftarrow (R-Y) \cdot 0.713 + delta
.. math::
2011-02-26 19:05:10 +08:00
Cb \leftarrow (B-Y) \cdot 0.564 + delta
.. math::
2011-02-26 19:05:10 +08:00
R \leftarrow Y + 1.403 \cdot (Cr - delta)
.. math::
2011-02-26 19:05:10 +08:00
G \leftarrow Y - 0.344 \cdot (Cr - delta) - 0.714 \cdot (Cb - delta)
.. math::
2011-02-26 19:05:10 +08:00
B \leftarrow Y + 1.773 \cdot (Cb - delta)
where
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
delta = \left \{ \begin{array}{l l} 128 & \mbox{for 8-bit images} \\ 32768 & \mbox{for 16-bit images} \\ 0.5 & \mbox{for floating-point images} \end{array} \right .
2011-02-26 19:05:10 +08:00
2011-04-25 05:02:14 +08:00
Y, Cr, and Cb cover the whole value range.
*
RGB :math:`\leftrightarrow` HSV ( ``CV_BGR2HSV, CV_RGB2HSV, CV_HSV2BGR, CV_HSV2RGB`` )
2011-04-25 05:02:14 +08:00
In case of 8-bit and 16-bit images,
R, G, and B are converted to the floating-point format and scaled to fit the 0 to 1 range.
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
V \leftarrow max(R,G,B)
.. math::
2011-02-26 19:05:10 +08:00
S \leftarrow \fork{\frac{V-min(R,G,B)}{V}}{if $V \neq 0$}{0}{otherwise}
.. math::
2011-02-26 19:05:10 +08:00
H \leftarrow \forkthree{{60(G - B)}/{S}}{if $V=R$}{{120+60(B - R)}/{S}}{if $V=G$}{{240+60(R - G)}/{S}}{if $V=B$}
2011-04-25 05:02:14 +08:00
If
2011-02-26 19:05:10 +08:00
:math:`H<0` then
2011-04-25 05:02:14 +08:00
:math:`H \leftarrow H+360` . On output
:math:`0 \leq V \leq 1`, :math:`0 \leq S \leq 1`, :math:`0 \leq H \leq 360` .??
2011-02-26 19:05:10 +08:00
The values are then converted to the destination data type:
2011-02-26 19:05:10 +08:00
* 8-bit images
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
V \leftarrow 255 V, S \leftarrow 255 S, H \leftarrow H/2 \text{(to fit to 0 to 255)}
* 16-bit images (currently not supported)
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
V <- 65535 V, S <- 65535 S, H <- H
* 32-bit images
2011-04-25 05:02:14 +08:00
H, S, and V are left as is
*
RGB :math:`\leftrightarrow` HLS ( ``CV_BGR2HLS, CV_RGB2HLS, CV_HLS2BGR, CV_HLS2RGB`` ).
2011-04-25 05:02:14 +08:00
In case of 8-bit and 16-bit images,
R, G, and B are converted to the floating-point format and scaled to fit the 0 to 1 range.
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
V_{max} \leftarrow {max}(R,G,B)
.. math::
2011-02-26 19:05:10 +08:00
V_{min} \leftarrow {min}(R,G,B)
.. math::
2011-02-26 19:05:10 +08:00
L \leftarrow \frac{V_{max} + V_{min}}{2}
.. math::
2011-02-26 19:05:10 +08:00
S \leftarrow \fork { \frac{V_{max} - V_{min}}{V_{max} + V_{min}} }{if $L < 0.5$ }
2011-02-26 19:05:10 +08:00
{ \frac{V_{max} - V_{min}}{2 - (V_{max} + V_{min})} }{if $L \ge 0.5$ }
.. math::
2011-02-26 19:05:10 +08:00
H \leftarrow \forkthree {{60(G - B)}/{S}}{if $V_{max}=R$ }
{{120+60(B - R)}/{S}}{if $V_{max}=G$ }
2011-02-26 19:05:10 +08:00
{{240+60(R - G)}/{S}}{if $V_{max}=B$ }
2011-04-25 05:02:14 +08:00
If
2011-02-26 19:05:10 +08:00
:math:`H<0` then
2011-04-25 05:02:14 +08:00
:math:`H \leftarrow H+360` . On output
2011-02-26 19:05:10 +08:00
:math:`0 \leq L \leq 1`, :math:`0 \leq S \leq 1`, :math:`0 \leq H \leq 360` .
The values are then converted to the destination data type:
2011-02-26 19:05:10 +08:00
* 8-bit images
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
V \leftarrow 255 \cdot V, S \leftarrow 255 \cdot S, H \leftarrow H/2 \; \text{(to fit to 0 to 255)}
* 16-bit images (currently not supported)
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
V <- 65535 \cdot V, S <- 65535 \cdot S, H <- H
* 32-bit images
H, S, V are left as is
*
2011-04-25 05:02:14 +08:00
RGB :math:`\leftrightarrow` CIE L*a*b* ( ``CV_BGR2Lab, CV_RGB2Lab, CV_Lab2BGR, CV_Lab2RGB`` ).
In case of 8-bit and 16-bit images,
R, G, and B are converted to the floating-point format and scaled to fit the 0 to 1 range.
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\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}
.. math::
2011-02-26 19:05:10 +08:00
X \leftarrow X/X_n, \text{where} X_n = 0.950456
.. math::
2011-02-26 19:05:10 +08:00
Z \leftarrow Z/Z_n, \text{where} Z_n = 1.088754
.. math::
2011-02-26 19:05:10 +08:00
L \leftarrow \fork{116*Y^{1/3}-16}{for $Y>0.008856$}{903.3*Y}{for $Y \le 0.008856$}
.. math::
2011-02-26 19:05:10 +08:00
a \leftarrow 500 (f(X)-f(Y)) + delta
.. math::
2011-02-26 19:05:10 +08:00
b \leftarrow 200 (f(Y)-f(Z)) + delta
where
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
f(t)= \fork{t^{1/3}}{for $t>0.008856$}{7.787 t+16/116}{for $t\leq 0.008856$}
and
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
delta = \fork{128}{for 8-bit images}{0}{for floating-point images}
2011-04-25 05:02:14 +08:00
This outputs
:math:`0 \leq L \leq 100`, :math:`-127 \leq a \leq 127`, :math:`-127 \leq b \leq 127` . The values are then converted to the destination data type:
2011-02-26 19:05:10 +08:00
* 8-bit images
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
L \leftarrow L*255/100, \; a \leftarrow a + 128, \; b \leftarrow b + 128
* 16-bit images
2011-04-25 05:02:14 +08:00
(currently not supported)
2011-02-26 19:05:10 +08:00
* 32-bit images
2011-04-25 05:02:14 +08:00
L, a, and b are left as is
*
2011-04-25 05:02:14 +08:00
RGB :math:`\leftrightarrow` CIE L*u*v* ( ``CV_BGR2Luv, CV_RGB2Luv, CV_Luv2BGR, CV_Luv2RGB`` ).
In case of 8-bit and 16-bit images,
R, G, and B are converted to the floating-point format and scaled to fit 0 to 1 range.
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\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}
.. math::
2011-02-26 19:05:10 +08:00
L \leftarrow \fork{116 Y^{1/3}}{for $Y>0.008856$}{903.3 Y}{for $Y\leq 0.008856$}
.. math::
2011-02-26 19:05:10 +08:00
u' \leftarrow 4*X/(X + 15*Y + 3 Z)
.. math::
2011-02-26 19:05:10 +08:00
v' \leftarrow 9*Y/(X + 15*Y + 3 Z)
.. math::
2011-02-26 19:05:10 +08:00
u \leftarrow 13*L*(u' - u_n) \quad \text{where} \quad u_n=0.19793943
.. math::
2011-02-26 19:05:10 +08:00
v \leftarrow 13*L*(v' - v_n) \quad \text{where} \quad v_n=0.46831096
2011-04-25 05:02:14 +08:00
This outputs
2011-02-26 19:05:10 +08:00
:math:`0 \leq L \leq 100`, :math:`-134 \leq u \leq 220`, :math:`-140 \leq v \leq 122` .
The values are then converted to the destination data type:
2011-02-26 19:05:10 +08:00
* 8-bit images
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
L \leftarrow 255/100 L, \; u \leftarrow 255/354 (u + 134), \; v \leftarrow 255/256 (v + 140)
* 16-bit images
2011-04-25 05:02:14 +08:00
(currently not supported)
2011-02-26 19:05:10 +08:00
* 32-bit images
2011-04-25 05:02:14 +08:00
L, u, and v are left as is
2011-02-26 19:05:10 +08:00
2011-04-25 05:02:14 +08:00
The above formulae for converting RGB to/from various color spaces have been taken from multiple sources on the web, primarily from the Charles Poynton site
http://www.poynton.com/ColorFAQ.html
*
2011-04-25 05:02:14 +08:00
Bayer :math:`\rightarrow` RGB ( ``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 enables you to get color pictures from a single plane where R,G, and B pixels (sensors of a particular component) are interleaved as follows:
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\newcommand{\Rcell}{\color{red}R} \newcommand{\Gcell}{\color{green}G} \newcommand{\Bcell}{\color{blue}B} \definecolor{BackGray}{rgb}{0.8,0.8,0.8} \begin{array}{ c c c c c } \Rcell & \Gcell & \Rcell & \Gcell & \Rcell \\ \Gcell & \colorbox{BackGray}{\Bcell} & \colorbox{BackGray}{\Gcell} & \Bcell & \Gcell \\ \Rcell & \Gcell & \Rcell & \Gcell & \Rcell \\ \Gcell & \Bcell & \Gcell & \Bcell & \Gcell \\ \Rcell & \Gcell & \Rcell & \Gcell & \Rcell \end{array}
2011-04-25 05:02:14 +08:00
The output RGB components of a pixel are interpolated from 1, 2, or
4 neighbors of the pixel having the same color. There are several
modifications of the above pattern that can be achieved by shifting
the pattern one pixel left and/or one pixel up. The two letters
2011-02-26 19:05:10 +08:00
:math:`C_1` and
:math:`C_2` in the conversion constants ``CV_Bayer`` :math:`C_1 C_2` ``2BGR`` and ``CV_Bayer`` :math:`C_1 C_2` ``2RGB`` indicate the particular pattern
2011-04-25 05:02:14 +08:00
type. These are components from the second row, second and third
columns, respectively. For example, the above pattern has a very
popular "BG" type.
.. index:: distanceTransform
2011-03-09 06:22:24 +08:00
.. _distanceTransform:
distanceTransform
---------------------
.. c:function:: void distanceTransform( const Mat& src, Mat& dst, int distanceType, int maskSize )
.. c:function:: void distanceTransform( const Mat& src, Mat& dst, Mat& labels, int distanceType, int maskSize )
Calculates the distance to the closest zero pixel for each pixel of the source image.
2011-04-25 05:02:14 +08:00
:param src: 8-bit, single-channel (binary) source image.
2011-04-25 05:02:14 +08:00
:param dst: Output image with calculated distances. It is a 32-bit floating-point, single-channel image of the same size as ``src`` .
:param distanceType: Type of distance. It can be ``CV_DIST_L1, CV_DIST_L2`` , or ``CV_DIST_C`` .
:param maskSize: Size of the distance transform mask. It can be 3, 5, or ``CV_DIST_MASK_PRECISE`` (the latter option is only supported by the first function??). In case of the ``CV_DIST_L1`` or ``CV_DIST_C`` distance type, the parameter is forced to 3 because a :math:`3\times 3` mask gives the same result as :math:`5\times 5` or any larger aperture.
2011-04-25 05:02:14 +08:00
:param labels: Optional output 2D array of labels (the discrete Voronoi diagram). It has the type ``CV_32SC1`` and the same size as ``src`` . See the details below.
2011-02-26 19:05:10 +08:00
The functions ``distanceTransform`` calculate the approximate or precise
distance from every binary image pixel to the nearest zero pixel.
2011-04-25 05:02:14 +08:00
For zero image pixels, the distance will obviously be zero.
2011-02-26 19:05:10 +08:00
When ``maskSize == CV_DIST_MASK_PRECISE`` and ``distanceType == CV_DIST_L2`` , the function runs the algorithm described in
2011-04-25 05:02:14 +08:00
Felzenszwalb04.
2011-04-25 05:02:14 +08:00
In other cases, the algorithm
Borgefors86
2011-04-25 05:02:14 +08:00
is used. This means that
for a pixel the function finds the shortest path to the nearest zero pixel
consisting of basic shifts: horizontal,
2011-04-25 05:02:14 +08:00
vertical, diagonal, or knight's move (the latest is available for a
2011-02-26 19:05:10 +08:00
:math:`5\times 5` mask). The overall distance is calculated as a sum of these
2011-04-25 05:02:14 +08:00
basic distances. Since the distance function should be symmetric,
all of the horizontal and vertical shifts must have the same cost (denoted as ``a`` ), all the diagonal shifts must have the
same cost (denoted as ``b`` ), and all knight's moves must have
the same cost (denoted as ``c`` ). For the ``CV_DIST_C`` and ``CV_DIST_L1`` types, the distance is calculated precisely,
2011-02-26 19:05:10 +08:00
whereas for ``CV_DIST_L2`` (Euclidian distance) the distance
2011-04-25 05:02:14 +08:00
can be calculated only with a relative error (a
2011-02-26 19:05:10 +08:00
:math:`5\times 5` mask
2011-04-25 05:02:14 +08:00
gives more accurate results). For ``a``,``b`` , and ``c`` , OpenCV uses the values suggested in the original paper:
.. table::
============== =================== ======================
``CV_DIST_C`` :math:`(3\times 3)` a = 1, b = 1 \
============== =================== ======================
``CV_DIST_L1`` :math:`(3\times 3)` a = 1, b = 2 \
``CV_DIST_L2`` :math:`(3\times 3)` a=0.955, b=1.3693 \
``CV_DIST_L2`` :math:`(5\times 5)` a=1, b=1.4, c=2.1969 \
============== =================== ======================
2011-02-26 19:05:10 +08:00
Typically, for a fast, coarse distance estimation ``CV_DIST_L2``,a
2011-04-25 05:02:14 +08:00
:math:`3\times 3` mask is used. For a more accurate distance estimation ``CV_DIST_L2`` , a
2011-02-26 19:05:10 +08:00
:math:`5\times 5` mask or the precise algorithm is used.
Note that both the precise and the approximate algorithms are linear on the number of pixels.
2011-02-26 19:05:10 +08:00
The second variant of the function does not only compute the minimum distance for each pixel
2011-04-25 05:02:14 +08:00
:math:`(x, y)` but also identifies the nearest connected
2011-02-26 19:05:10 +08:00
component consisting of zero pixels. Index of the component is stored in
:math:`\texttt{labels}(x, y)` .
The connected components of zero pixels are also found and marked by the function.
2011-04-25 05:02:14 +08:00
In this mode, the complexity is still linear.
That is, the function provides a very fast way to compute the Voronoi diagram for a binary image.
Currently, the second variant can use only the approximate distance transform algorithm.
.. index:: floodFill
2011-03-09 06:22:24 +08:00
.. _floodFill:
floodFill
-------------
.. c:function:: int floodFill( Mat& image, Point seed, Scalar newVal, Rect* rect=0, Scalar loDiff=Scalar(), Scalar upDiff=Scalar(), int flags=4 )
.. c:function:: int floodFill( Mat& image, Mat& mask, Point seed, Scalar newVal, Rect* rect=0, Scalar loDiff=Scalar(), Scalar upDiff=Scalar(), int flags=4 )
2011-02-26 19:05:10 +08:00
Fills a connected component with the given color.
2011-04-25 05:02:14 +08:00
:param image: Input/output 1- or 3-channel, 8-bit, or floating-point image. It is modified by the function unless the ``FLOODFILL_MASK_ONLY`` flag is set in the second variant of the function. See the details below.
2011-04-25 05:02:14 +08:00
:param mask: (For the second function only) Operation mask that should be a single-channel 8-bit image, 2 pixels wider and 2 pixels taller. 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.
**Note** : Since the mask is larger than the filled image, a pixel :math:`(x, y)` in ``image`` corresponds to the pixel :math:`(x+1, y+1)` in the ``mask`` .
:param seed: Starting point.
2011-04-25 05:02:14 +08:00
:param newVal: New value of the repainted domain pixels.
2011-04-25 05:02:14 +08:00
:param 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.
2011-04-25 05:02:14 +08:00
:param 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.
2011-04-25 05:02:14 +08:00
:param rect: Optional output parameter set by the function to the minimum bounding rectangle of the repainted domain.
2011-04-25 05:02:14 +08:00
:param flags: Operation flags. Lower bits contain a connectivity value, 4 (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:
2011-04-25 05:02:14 +08:00
* **FLOODFILL_FIXED_RANGE** If set, the difference between the current pixel and seed pixel is considered. Otherwise, the difference between neighbor pixels is considered (that is, the range is floating).
2011-04-25 05:02:14 +08:00
* **FLOODFILL_MASK_ONLY** If set, the function does not change the image ( ``newVal`` is ignored), but fills the mask. The flag can be used for the second variant only.
2011-02-26 19:05:10 +08:00
The functions ``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
2011-04-25 05:02:14 +08:00
:math:`(x,y)` is considered to belong to the repainted domain if??:
2011-04-25 05:02:14 +08:00
* Grayscale image, floating range
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\texttt{src} (x',y')- \texttt{loDiff} \leq \texttt{src} (x,y) \leq \texttt{src} (x',y')+ \texttt{upDiff}
2011-04-25 05:02:14 +08:00
* Grayscale image, fixed range
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\texttt{src} ( \texttt{seed} .x, \texttt{seed} .y)- \texttt{loDiff} \leq \texttt{src} (x,y) \leq \texttt{src} ( \texttt{seed} .x, \texttt{seed} .y)+ \texttt{upDiff}
2011-04-25 05:02:14 +08:00
* Color image, floating range
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\texttt{src} (x',y')_r- \texttt{loDiff} _r \leq \texttt{src} (x,y)_r \leq \texttt{src} (x',y')_r+ \texttt{upDiff} _r
.. math::
2011-02-26 19:05:10 +08:00
\texttt{src} (x',y')_g- \texttt{loDiff} _g \leq \texttt{src} (x,y)_g \leq \texttt{src} (x',y')_g+ \texttt{upDiff} _g
.. math::
2011-02-26 19:05:10 +08:00
\texttt{src} (x',y')_b- \texttt{loDiff} _b \leq \texttt{src} (x,y)_b \leq \texttt{src} (x',y')_b+ \texttt{upDiff} _b
2011-04-25 05:02:14 +08:00
* Color image, fixed range
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\texttt{src} ( \texttt{seed} .x, \texttt{seed} .y)_r- \texttt{loDiff} _r \leq \texttt{src} (x,y)_r \leq \texttt{src} ( \texttt{seed} .x, \texttt{seed} .y)_r+ \texttt{upDiff} _r
.. math::
2011-02-26 19:05:10 +08:00
\texttt{src} ( \texttt{seed} .x, \texttt{seed} .y)_g- \texttt{loDiff} _g \leq \texttt{src} (x,y)_g \leq \texttt{src} ( \texttt{seed} .x, \texttt{seed} .y)_g+ \texttt{upDiff} _g
.. math::
2011-02-26 19:05:10 +08:00
\texttt{src} ( \texttt{seed} .x, \texttt{seed} .y)_b- \texttt{loDiff} _b \leq \texttt{src} (x,y)_b \leq \texttt{src} ( \texttt{seed} .x, \texttt{seed} .y)_b+ \texttt{upDiff} _b
2011-02-26 19:05:10 +08:00
where
2011-04-25 05:02:14 +08:00
:math:`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 color/brightness of the pixel should be close enough to:
*
2011-04-25 05:02:14 +08:00
Color/brightness of one of its neighbors that are already referred to in?? the connected component in case of floating range.
*
2011-04-25 05:02:14 +08:00
Color/brightness of the seed point in case of fixed range.
2011-04-25 05:02:14 +08:00
Use these functions to 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, and so on. Various modes of the function are demonstrated in the ``floodfill.c`` sample.
2011-04-25 05:02:14 +08:00
See Also:
2011-02-26 19:05:10 +08:00
:func:`findContours`
2011-03-09 06:22:24 +08:00
.. index:: inpaint
2011-03-09 06:22:24 +08:00
.. _inpaint:
inpaint
-----------
.. c:function:: void inpaint( const Mat& src, const Mat& inpaintMask, Mat& dst, double inpaintRadius, int flags )
2011-04-25 05:02:14 +08:00
Removes?? the selected region in an image.
2011-04-25 05:02:14 +08:00
:param src: Input 8-bit 1-channel or 3-channel image.
2011-04-25 05:02:14 +08:00
:param inpaintMask: Inpainting mask, 8-bit 1-channel image. Non-zero pixels indicate the area that needs to be inpainted.
2011-04-25 05:02:14 +08:00
:param dst: Output image with the same size and type as ``src`` .
2011-04-25 05:02:14 +08:00
:param inpaintRadius: Radius of a circlular neighborhood of each point inpainted that is considered by the algorithm.
2011-04-25 05:02:14 +08:00
:param flags: Inpainting method that could be one of the following:
2011-04-25 05:02:14 +08:00
* **INPAINT_NS** Navier-Stokes based method.
2011-04-25 05:02:14 +08:00
* **INPAINT_TELEA** Method by Alexandru Telea Telea04.
2011-02-26 19:05:10 +08:00
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
http://en.wikipedia.org/wiki/Inpainting
for more details.
.. index:: integral
2011-03-09 06:22:24 +08:00
.. _integral:
integral
------------
.. c:function:: void integral( const Mat& image, Mat& sum, int sdepth=-1 )
.. c:function:: void integral( const Mat& image, Mat& sum, Mat& sqsum, int sdepth=-1 )
.. c:function:: void integral( const Mat& image, Mat& sum, Mat& sqsum, Mat& tilted, int sdepth=-1 )
Calculates the integral of an image.
2011-04-25 05:02:14 +08:00
:param image: Source image as :math:`W \times H` , 8-bit or floating-point (32f or 64f).
2011-04-25 05:02:14 +08:00
:param sum: Integral image as :math:`(W+1)\times (H+1)` , 32-bit integer or floating-point (32f or 64f).
2011-04-25 05:02:14 +08:00
:param sqsum: Integral image for squared pixel values represented as?? :math:`(W+1)\times (H+1)` , double precision floating-point (64f).
2011-04-25 05:02:14 +08:00
:param tilted: Integral for the image rotated by 45 degrees represented as :math:`(W+1)\times (H+1)` , with the same data type as ``sum`` .
2011-04-25 05:02:14 +08:00
:param sdepth: Desired depth of the integral and the tilted integral images, ``CV_32S`` , ``CV_32F`` , or ``CV_64F`` .
The functions calculate one or more integral images for the source image as following:
.. math::
2011-02-26 19:05:10 +08:00
\texttt{sum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)
.. math::
2011-02-26 19:05:10 +08:00
\texttt{sqsum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)^2
.. math::
2011-02-26 19:05:10 +08:00
\texttt{tilted} (X,Y) = \sum _{y<Y,abs(x-X+1) \leq Y-y-1} \texttt{image} (x,y)
2011-04-25 05:02:14 +08:00
Using these integral images, you can calculate sum, mean and standard deviation over a specific up-right or rotated rectangular region of the image in a constant time, for example:
.. math::
2011-02-26 19:05:10 +08:00
\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)
2011-04-25 05:02:14 +08:00
It makes possible to do a fast blurring or fast block correlation with a variable window size, for example. In case of multi-channel images, sums for each channel are accumulated independently.
2011-02-26 19:05:10 +08:00
As a practical example, the next figure shows the calculation of the integral of a straight rectangle ``Rect(3,3,3,2)`` and of a tilted rectangle ``Rect(5,1,2,3)`` . The selected pixels in the original ``image`` are shown, as well as the relative pixels in the integral images ``sum`` and ``tilted`` .
\begin{center}
.. image:: pics/integral.png
\end{center}
.. index:: threshold
2011-03-09 06:22:24 +08:00
.. _threshold:
threshold
-------------
.. c:function:: double threshold( const Mat& src, Mat& dst, double thresh, double maxVal, int thresholdType )
2011-04-25 05:02:14 +08:00
Applies a fixed-level threshold to each array element.
2011-02-26 19:05:10 +08:00
:param src: Source array (single-channel, 8-bit of 32-bit floating point)
2011-04-25 05:02:14 +08:00
:param dst: Destination array of the same size and type as ``src`` .
2011-04-25 05:02:14 +08:00
:param thresh: Threshold value.
2011-04-25 05:02:14 +08:00
:param maxVal: Maximum value to use with the ``THRESH_BINARY`` and ``THRESH_BINARY_INV`` thresholding types.
2011-04-25 05:02:14 +08:00
:param thresholdType: Thresholding type (see the details below).
The function applies fixed-level thresholding
to a single-channel array. The function is typically used to get a
bi-level (binary) image out of a grayscale image (
2011-02-26 19:05:10 +08:00
:func:`compare` could
2011-04-25 05:02:14 +08:00
be also used for this purpose) or for removing a noise, that is, filtering
out pixels with too small or too large values. There are several
2011-04-25 05:02:14 +08:00
types of thresholding supported by the function. They are determined by ``thresholdType`` :
2011-02-26 19:05:10 +08:00
* **THRESH_BINARY**
.. math::
2011-02-26 19:05:10 +08:00
\texttt{dst} (x,y) = \fork{\texttt{maxVal}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise}
2011-02-26 19:05:10 +08:00
* **THRESH_BINARY_INV**
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\texttt{dst} (x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{maxVal}}{otherwise}
2011-02-26 19:05:10 +08:00
* **THRESH_TRUNC**
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\texttt{dst} (x,y) = \fork{\texttt{threshold}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise}
2011-02-26 19:05:10 +08:00
* **THRESH_TOZERO**
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\texttt{dst} (x,y) = \fork{\texttt{src}(x,y)}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise}
2011-02-26 19:05:10 +08:00
* **THRESH_TOZERO_INV**
2011-02-26 19:05:10 +08:00
.. math::
2011-02-26 19:05:10 +08:00
\texttt{dst} (x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise}
2011-02-26 19:05:10 +08:00
Also, the special value ``THRESH_OTSU`` may be combined with
2011-04-25 05:02:14 +08:00
one of the above values. In this case, the function determines the optimal threshold
2011-02-26 19:05:10 +08:00
value using Otsu's algorithm and uses it instead of the specified ``thresh`` .
The function returns the computed threshold value.
Currently, Otsu's method is implemented only for 8-bit images.
.. image:: pics/threshold.png
2011-04-25 05:02:14 +08:00
See Also:
:func:`adaptiveThreshold`,
:func:`findContours`,
:func:`compare`,
:func:`min`,:func:`max`
2011-03-09 06:22:24 +08:00
2011-02-26 19:05:10 +08:00
.. index:: watershed
2011-03-09 06:22:24 +08:00
.. _watershed:
watershed
2011-02-26 19:05:10 +08:00
-------------
.. c:function:: void watershed( const Mat& image, Mat& markers )
2011-04-25 05:02:14 +08:00
Performs a marker-based image segmentation using the watershed algrorithm.
2011-04-25 05:02:14 +08:00
:param image: Input 8-bit 3-channel image.
2011-04-25 05:02:14 +08:00
:param markers: Input/output 32-bit single-channel image (map) of markers. It should have the same size as ``image`` .
The function implements one of the variants
of watershed, non-parametric marker-based segmentation algorithm,
2011-02-26 19:05:10 +08:00
described in
2011-04-25 05:02:14 +08:00
Meyer92??
. Before passing the image to the
2011-04-25 05:02:14 +08:00
function, you have to roughly outline the desired regions in the image ``markers`` with positive (
:math:`>0` ) indices. So, every region is
represented as one or more connected components with the pixel values
2011-04-25 05:02:14 +08:00
1, 2, 3, and so on. Such markers can be retrieved from a binary mask
2011-02-26 19:05:10 +08:00
using
:func:`findContours` and
2011-04-25 05:02:14 +08:00
:func:`drawContours` (see the ``watershed.cpp`` demo).
The markers are "seeds" of the future image
regions. All the other pixels in ``markers`` , whose relation to the
outlined regions is not known and should be defined by the algorithm,
2011-04-25 05:02:14 +08:00
should be set to 0's. In the function output, each pixel in
markers is set to a value of the "seed" components or to -1 at
boundaries between the regions.
2011-04-25 05:02:14 +08:00
**Note**: Every two neighbor connected
components are not necessarily separated by a watershed boundary (-1's pixels); for
example, when such tangent components exist in the initial
marker image. Visual demonstration and usage example of the function
2011-04-25 05:02:14 +08:00
can be found in the OpenCV samples directory (see the ``watershed.cpp`` demo).
2011-04-25 05:02:14 +08:00
See Also:
:func:`findContours`
2011-03-09 06:22:24 +08:00
.. index:: grabCut
2011-03-09 06:22:24 +08:00
.. _grabCut:
grabCut
2011-03-09 06:22:24 +08:00
-------
.. c:function:: void grabCut(const Mat& image, Mat& mask, Rect rect, Mat& bgdModel, Mat& fgdModel, int iterCount, int mode )
2011-04-25 05:02:14 +08:00
Runs the GrabCut algorithm.
2011-04-25 05:02:14 +08:00
:param image: Input 8-bit 3-channel image.
2011-04-25 05:02:14 +08:00
:param mask: Input/output 8-bit single-channel mask. Its elements may have one of four values. The mask is initialized when ``mode==GC_INIT_WITH_RECT`` .
* **GC_BGD** defines an obvious background pixel.??
2011-04-25 05:02:14 +08:00
* **GC_FGD** defines an obvious foreground (object) pixel.
2011-04-25 05:02:14 +08:00
* **GC_PR_BGD** defines a possible background pixel.
2011-04-25 05:02:14 +08:00
* **GC_PR_BGD** defines a possible foreground pixel.
2011-04-25 05:02:14 +08:00
:param rect: ROI containing a segmented object. The pixels outside of the ROI are marked as "obvious background"??. The parameter is only used when ``mode==GC_INIT_WITH_RECT`` .
2011-04-25 05:02:14 +08:00
:param bgdModel, fgdModel: Temporary arrays used for segmentation. Do not modify them while you are processing the same image.
2011-04-25 05:02:14 +08:00
:param iterCount: Number of iterations the algorithm should make before returning the result. Note that the result can be refined with further calls with ``mode==GC_INIT_WITH_MASK`` or ``mode==GC_EVAL`` .
2011-04-25 05:02:14 +08:00
:param mode: Operation mode that could be one of the following:
2011-04-25 05:02:14 +08:00
* **GC_INIT_WITH_RECT** The function initializes the state and the mask using the provided rectangle. After that it runs ``iterCount`` iterations of the algorithm.
2011-04-25 05:02:14 +08:00
* **GC_INIT_WITH_MASK** The function initializes the state using the provided mask. Note that ``GC_INIT_WITH_RECT`` and ``GC_INIT_WITH_MASK`` can be combined. Then, all the pixels outside of the ROI are automatically initialized with ``GC_BGD`` .
2011-02-26 19:05:10 +08:00
2011-04-25 05:02:14 +08:00
* **GC_EVAL** The value means that algorithm should just resume.
2011-02-26 19:05:10 +08:00
2011-03-09 06:22:24 +08:00
The function implements the `GrabCut image segmentation algorithm <http://en.wikipedia.org/wiki/GrabCut>`_.
2011-04-25 05:02:14 +08:00
See the sample grabcut.cpp to learn how to use the function.