1 Miscellaneous Image Transformations
2 ===================================
9 Applies an adaptive threshold to an array.
11 .. ocv:function:: void adaptiveThreshold( InputArray src, OutputArray dst, double maxValue, int adaptiveMethod, int thresholdType, int blockSize, double C )
13 .. ocv:pyfunction:: cv2.adaptiveThreshold(src, maxValue, adaptiveMethod, thresholdType, blockSize, C[, dst]) -> dst
15 .. ocv:cfunction:: void cvAdaptiveThreshold( const CvArr* src, CvArr* dst, double max_value, int adaptive_method=CV_ADAPTIVE_THRESH_MEAN_C, int threshold_type=CV_THRESH_BINARY, int block_size=3, double param1=5 )
17 .. ocv:pyoldfunction:: cv.AdaptiveThreshold(src, dst, maxValue, adaptive_method=CV_ADAPTIVE_THRESH_MEAN_C, thresholdType=CV_THRESH_BINARY, blockSize=3, param1=5)-> None
19 :param src: Source 8-bit single-channel image.
21 :param dst: Destination image of the same size and the same type as ``src`` .
23 :param maxValue: Non-zero value assigned to the pixels for which the condition is satisfied. See the details below.
25 :param adaptiveMethod: Adaptive thresholding algorithm to use, ``ADAPTIVE_THRESH_MEAN_C`` or ``ADAPTIVE_THRESH_GAUSSIAN_C`` . See the details below.
27 :param thresholdType: Thresholding type that must be either ``THRESH_BINARY`` or ``THRESH_BINARY_INV`` .
29 :param blockSize: Size of a pixel neighborhood that is used to calculate a threshold value for the pixel: 3, 5, 7, and so on.
31 :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.
33 The function transforms a grayscale image to a binary image according to the formulae:
39 dst(x,y) = \fork{\texttt{maxValue}}{if $src(x,y) > T(x,y)$}{0}{otherwise}
41 * **THRESH_BINARY_INV**
45 dst(x,y) = \fork{0}{if $src(x,y) > T(x,y)$}{\texttt{maxValue}}{otherwise}
48 :math:`T(x,y)` is a threshold calculated individually for each pixel.
51 For the method ``ADAPTIVE_THRESH_MEAN_C`` , the threshold value
52 :math:`T(x,y)` is a mean of the
53 :math:`\texttt{blockSize} \times \texttt{blockSize}` neighborhood of
54 :math:`(x, y)` minus ``C`` .
57 For the method ``ADAPTIVE_THRESH_GAUSSIAN_C`` , the threshold value
58 :math:`T(x, y)` is a weighted sum (cross-correlation with a Gaussian window) of the
59 :math:`\texttt{blockSize} \times \texttt{blockSize}` neighborhood of
60 :math:`(x, y)` minus ``C`` . The default sigma (standard deviation) is used for the specified ``blockSize`` . See
61 :ocv:func:`getGaussianKernel` .
63 The function can process the image in-place.
67 :ocv:func:`threshold`,
69 :ocv:func:`GaussianBlur`
75 Converts an image from one color space to another.
77 .. ocv:function:: void cvtColor( InputArray src, OutputArray dst, int code, int dstCn=0 )
79 .. ocv:pyfunction:: cv2.cvtColor(src, code[, dst[, dstCn]]) -> dst
81 .. ocv:cfunction:: void cvCvtColor( const CvArr* src, CvArr* dst, int code )
82 .. ocv:pyoldfunction:: cv.CvtColor(src, dst, code)-> None
84 :param src: input image: 8-bit unsigned, 16-bit unsigned ( ``CV_16UC...`` ), or single-precision floating-point.
86 :param dst: output image of the same size and depth as ``src``.
88 :param code: color space conversion code (see the description below).
90 :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`` .
92 The function converts an input image from one color
93 space to another. In case of a transformation to-from RGB color space, the order of the channels should be specified explicitly (RGB or BGR).
94 Note that the default color format in OpenCV is often referred to as RGB but it is actually BGR (the bytes are reversed). So the first byte in a standard (24-bit) color image will be an 8-bit Blue component, the second byte will be Green, and the third byte will be Red. The fourth, fifth, and sixth bytes would then be the second pixel (Blue, then Green, then Red), and so on.
96 The conventional ranges for R, G, and B channel values are:
99 0 to 255 for ``CV_8U`` images
102 0 to 65535 for ``CV_16U`` images
105 0 to 1 for ``CV_32F`` images
107 In case of linear transformations, the range does not matter.
108 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
109 :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: ::
112 cvtColor(img, img, CV_BGR2Luv);
114 If you use ``cvtColor`` with 8-bit images, the conversion will have some information lost. For many applications, this will not be noticeable but it is recommended to use 32-bit images in applications that need the full range of colors or that convert an image before an operation and then convert back.
116 The function can do the following transformations:
119 RGB :math:`\leftrightarrow` GRAY ( ``CV_BGR2GRAY, CV_RGB2GRAY, CV_GRAY2BGR, CV_GRAY2RGB`` )
120 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:
124 \text{RGB[A] to Gray:} \quad Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
130 \text{Gray to RGB[A]:} \quad R \leftarrow Y, G \leftarrow Y, B \leftarrow Y, A \leftarrow 0
132 The conversion from a RGB image to gray is done with:
136 cvtColor(src, bwsrc, CV_RGB2GRAY);
140 More advanced channel reordering can also be done with
141 :ocv:func:`mixChannels` .
145 :math:`\leftrightarrow` CIE XYZ.Rec 709 with D65 white point ( ``CV_BGR2XYZ, CV_RGB2XYZ, CV_XYZ2BGR, CV_XYZ2RGB`` ):
149 \begin{bmatrix} X \\ Y \\ Z
150 \end{bmatrix} \leftarrow \begin{bmatrix} 0.412453 & 0.357580 & 0.180423 \\ 0.212671 & 0.715160 & 0.072169 \\ 0.019334 & 0.119193 & 0.950227
151 \end{bmatrix} \cdot \begin{bmatrix} R \\ G \\ B
156 \begin{bmatrix} R \\ G \\ B
157 \end{bmatrix} \leftarrow \begin{bmatrix} 3.240479 & -1.53715 & -0.498535 \\ -0.969256 & 1.875991 & 0.041556 \\ 0.055648 & -0.204043 & 1.057311
158 \end{bmatrix} \cdot \begin{bmatrix} X \\ Y \\ Z
161 :math:`X`, :math:`Y` and
162 :math:`Z` cover the whole value range (in case of floating-point images,
163 :math:`Z` may exceed 1).
167 :math:`\leftrightarrow` YCrCb JPEG (or YCC) ( ``CV_BGR2YCrCb, CV_RGB2YCrCb, CV_YCrCb2BGR, CV_YCrCb2RGB`` )
171 Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
175 Cr \leftarrow (R-Y) \cdot 0.713 + delta
179 Cb \leftarrow (B-Y) \cdot 0.564 + delta
183 R \leftarrow Y + 1.403 \cdot (Cr - delta)
187 G \leftarrow Y - 0.714 \cdot (Cr - delta) - 0.344 \cdot (Cb - delta)
191 B \leftarrow Y + 1.773 \cdot (Cb - delta)
197 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 .
199 Y, Cr, and Cb cover the whole value range.
202 RGB :math:`\leftrightarrow` HSV ( ``CV_BGR2HSV, CV_RGB2HSV, CV_HSV2BGR, CV_HSV2RGB`` )
203 In case of 8-bit and 16-bit images,
204 R, G, and B are converted to the floating-point format and scaled to fit the 0 to 1 range.
208 V \leftarrow max(R,G,B)
212 S \leftarrow \fork{\frac{V-min(R,G,B)}{V}}{if $V \neq 0$}{0}{otherwise}
216 H \leftarrow \forkthree{{60(G - B)}/{(V-min(R,G,B))}}{if $V=R$}{{120+60(B - R)}/{(V-min(R,G,B))}}{if $V=G$}{{240+60(R - G)}/{(V-min(R,G,B))}}{if $V=B$}
220 :math:`H \leftarrow H+360` . On output
221 :math:`0 \leq V \leq 1`, :math:`0 \leq S \leq 1`, :math:`0 \leq H \leq 360` .
223 The values are then converted to the destination data type:
229 V \leftarrow 255 V, S \leftarrow 255 S, H \leftarrow H/2 \text{(to fit to 0 to 255)}
231 * 16-bit images (currently not supported)
235 V <- 65535 V, S <- 65535 S, H <- H
238 H, S, and V are left as is
241 RGB :math:`\leftrightarrow` HLS ( ``CV_BGR2HLS, CV_RGB2HLS, CV_HLS2BGR, CV_HLS2RGB`` ).
242 In case of 8-bit and 16-bit images,
243 R, G, and B are converted to the floating-point format and scaled to fit the 0 to 1 range.
247 V_{max} \leftarrow {max}(R,G,B)
251 V_{min} \leftarrow {min}(R,G,B)
255 L \leftarrow \frac{V_{max} + V_{min}}{2}
259 S \leftarrow \fork { \frac{V_{max} - V_{min}}{V_{max} + V_{min}} }{if $L < 0.5$ }
260 { \frac{V_{max} - V_{min}}{2 - (V_{max} + V_{min})} }{if $L \ge 0.5$ }
264 H \leftarrow \forkthree {{60(G - B)}/{S}}{if $V_{max}=R$ }
265 {{120+60(B - R)}/{S}}{if $V_{max}=G$ }
266 {{240+60(R - G)}/{S}}{if $V_{max}=B$ }
270 :math:`H \leftarrow H+360` . On output
271 :math:`0 \leq L \leq 1`, :math:`0 \leq S \leq 1`, :math:`0 \leq H \leq 360` .
273 The values are then converted to the destination data type:
279 V \leftarrow 255 \cdot V, S \leftarrow 255 \cdot S, H \leftarrow H/2 \; \text{(to fit to 0 to 255)}
281 * 16-bit images (currently not supported)
285 V <- 65535 \cdot V, S <- 65535 \cdot S, H <- H
288 H, S, V are left as is
291 RGB :math:`\leftrightarrow` CIE L*a*b* ( ``CV_BGR2Lab, CV_RGB2Lab, CV_Lab2BGR, CV_Lab2RGB`` ).
292 In case of 8-bit and 16-bit images,
293 R, G, and B are converted to the floating-point format and scaled to fit the 0 to 1 range.
297 \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}
301 X \leftarrow X/X_n, \text{where} X_n = 0.950456
305 Z \leftarrow Z/Z_n, \text{where} Z_n = 1.088754
309 L \leftarrow \fork{116*Y^{1/3}-16}{for $Y>0.008856$}{903.3*Y}{for $Y \le 0.008856$}
313 a \leftarrow 500 (f(X)-f(Y)) + delta
317 b \leftarrow 200 (f(Y)-f(Z)) + delta
323 f(t)= \fork{t^{1/3}}{for $t>0.008856$}{7.787 t+16/116}{for $t\leq 0.008856$}
329 delta = \fork{128}{for 8-bit images}{0}{for floating-point images}
332 :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:
338 L \leftarrow L*255/100, \; a \leftarrow a + 128, \; b \leftarrow b + 128
341 (currently not supported)
344 L, a, and b are left as is
347 RGB :math:`\leftrightarrow` CIE L*u*v* ( ``CV_BGR2Luv, CV_RGB2Luv, CV_Luv2BGR, CV_Luv2RGB`` ).
348 In case of 8-bit and 16-bit images,
349 R, G, and B are converted to the floating-point format and scaled to fit 0 to 1 range.
353 \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}
357 L \leftarrow \fork{116 Y^{1/3}}{for $Y>0.008856$}{903.3 Y}{for $Y\leq 0.008856$}
361 u' \leftarrow 4*X/(X + 15*Y + 3 Z)
365 v' \leftarrow 9*Y/(X + 15*Y + 3 Z)
369 u \leftarrow 13*L*(u' - u_n) \quad \text{where} \quad u_n=0.19793943
373 v \leftarrow 13*L*(v' - v_n) \quad \text{where} \quad v_n=0.46831096
376 :math:`0 \leq L \leq 100`, :math:`-134 \leq u \leq 220`, :math:`-140 \leq v \leq 122` .
378 The values are then converted to the destination data type:
384 L \leftarrow 255/100 L, \; u \leftarrow 255/354 (u + 134), \; v \leftarrow 255/256 (v + 140)
387 (currently not supported)
390 L, u, and v are left as is
392 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
393 http://www.poynton.com/ColorFAQ.html
396 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:
398 .. image:: pics/bayer.png
400 The output RGB components of a pixel are interpolated from 1, 2, or
401 4 neighbors of the pixel having the same color. There are several
402 modifications of the above pattern that can be achieved by shifting
403 the pattern one pixel left and/or one pixel up. The two letters
405 :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
406 type. These are components from the second row, second and third
407 columns, respectively. For example, the above pattern has a very
413 Calculates the distance to the closest zero pixel for each pixel of the source image.
415 .. ocv:function:: void distanceTransform( InputArray src, OutputArray dst, int distanceType, int maskSize )
417 .. ocv:function:: void distanceTransform( InputArray src, OutputArray dst, OutputArray labels, int distanceType, int maskSize, int labelType=DIST_LABEL_CCOMP )
419 .. ocv:pyfunction:: cv2.distanceTransform(src, distanceType, maskSize[, dst]) -> dst
421 .. ocv:cfunction:: void cvDistTransform( const CvArr* src, CvArr* dst, int distance_type=CV_DIST_L2, int mask_size=3, const float* mask=NULL, CvArr* labels=NULL, int labelType=CV_DIST_LABEL_CCOMP )
423 .. ocv:pyoldfunction:: cv.DistTransform(src, dst, distance_type=CV_DIST_L2, mask_size=3, mask=None, labels=None) -> None
425 :param src: 8-bit, single-channel (binary) source image.
427 :param dst: Output image with calculated distances. It is a 32-bit floating-point, single-channel image of the same size as ``src`` .
429 :param distanceType: Type of distance. It can be ``CV_DIST_L1, CV_DIST_L2`` , or ``CV_DIST_C`` .
431 :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.
433 :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.
435 :param labelType: Type of the label array to build. If ``labelType==DIST_LABEL_CCOMP`` then each connected component of zeros in ``src`` (as well as all the non-zero pixels closest to the connected component) will be assigned the same label. If ``labelType==DIST_LABEL_PIXEL`` then each zero pixel (and all the non-zero pixels closest to it) gets its own label.
437 The functions ``distanceTransform`` calculate the approximate or precise
438 distance from every binary image pixel to the nearest zero pixel.
439 For zero image pixels, the distance will obviously be zero.
441 When ``maskSize == CV_DIST_MASK_PRECISE`` and ``distanceType == CV_DIST_L2`` , the function runs the algorithm described in [Felzenszwalb04]_. This algorithm is parallelized with the TBB library.
443 In other cases, the algorithm
445 is used. This means that
446 for a pixel the function finds the shortest path to the nearest zero pixel
447 consisting of basic shifts: horizontal,
448 vertical, diagonal, or knight's move (the latest is available for a
449 :math:`5\times 5` mask). The overall distance is calculated as a sum of these
450 basic distances. Since the distance function should be symmetric,
451 all of the horizontal and vertical shifts must have the same cost (denoted as ``a`` ), all the diagonal shifts must have the
452 same cost (denoted as ``b`` ), and all knight's moves must have
453 the same cost (denoted as ``c`` ). For the ``CV_DIST_C`` and ``CV_DIST_L1`` types, the distance is calculated precisely,
454 whereas for ``CV_DIST_L2`` (Euclidean distance) the distance
455 can be calculated only with a relative error (a
456 :math:`5\times 5` mask
457 gives more accurate results). For ``a``,``b`` , and ``c`` , OpenCV uses the values suggested in the original paper:
461 ============== =================== ======================
462 ``CV_DIST_C`` :math:`(3\times 3)` a = 1, b = 1 \
463 ============== =================== ======================
464 ``CV_DIST_L1`` :math:`(3\times 3)` a = 1, b = 2 \
465 ``CV_DIST_L2`` :math:`(3\times 3)` a=0.955, b=1.3693 \
466 ``CV_DIST_L2`` :math:`(5\times 5)` a=1, b=1.4, c=2.1969 \
467 ============== =================== ======================
469 Typically, for a fast, coarse distance estimation ``CV_DIST_L2``, a
470 :math:`3\times 3` mask is used. For a more accurate distance estimation ``CV_DIST_L2`` , a
471 :math:`5\times 5` mask or the precise algorithm is used.
472 Note that both the precise and the approximate algorithms are linear on the number of pixels.
474 The second variant of the function does not only compute the minimum distance for each pixel
475 :math:`(x, y)` but also identifies the nearest connected
476 component consisting of zero pixels (``labelType==DIST_LABEL_CCOMP``) or the nearest zero pixel (``labelType==DIST_LABEL_PIXEL``). Index of the component/pixel is stored in
477 :math:`\texttt{labels}(x, y)` .
478 When ``labelType==DIST_LABEL_CCOMP``, the function automatically finds connected components of zero pixels in the input image and marks them with distinct labels. When ``labelType==DIST_LABEL_CCOMP``, the function scans through the input image and marks all the zero pixels with distinct labels.
480 In this mode, the complexity is still linear.
481 That is, the function provides a very fast way to compute the Voronoi diagram for a binary image.
482 Currently, the second variant can use only the approximate distance transform algorithm, i.e. ``maskSize=CV_DIST_MASK_PRECISE`` is not supported yet.
486 Fills a connected component with the given color.
488 .. ocv:function:: int floodFill( InputOutputArray image, Point seedPoint, Scalar newVal, Rect* rect=0, Scalar loDiff=Scalar(), Scalar upDiff=Scalar(), int flags=4 )
490 .. ocv:function:: int floodFill( InputOutputArray image, InputOutputArray mask, Point seedPoint, Scalar newVal, Rect* rect=0, Scalar loDiff=Scalar(), Scalar upDiff=Scalar(), int flags=4 )
492 .. ocv:pyfunction:: cv2.floodFill(image, mask, seedPoint, newVal[, loDiff[, upDiff[, flags]]]) -> retval, rect
494 .. ocv:cfunction:: void cvFloodFill( CvArr* image, CvPoint seed_point, CvScalar new_val, CvScalar lo_diff=cvScalarAll(0), CvScalar up_diff=cvScalarAll(0), CvConnectedComp* comp=NULL, int flags=4, CvArr* mask=NULL )
495 .. ocv:pyoldfunction:: cv.FloodFill(image, seed_point, new_val, lo_diff=(0, 0, 0, 0), up_diff=(0, 0, 0, 0), flags=4, mask=None)-> comp
497 :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.
499 :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.
501 .. 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`` .
503 :param seedPoint: Starting point.
505 :param newVal: New value of the repainted domain pixels.
507 :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.
509 :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.
511 :param rect: Optional output parameter set by the function to the minimum bounding rectangle of the repainted domain.
513 :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:
515 * **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).
517 * **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.
519 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
520 :math:`(x,y)` is considered to belong to the repainted domain if:
525 \texttt{src} (x',y')- \texttt{loDiff} \leq \texttt{src} (x,y) \leq \texttt{src} (x',y')+ \texttt{upDiff}
527 in case of a grayscale image and floating range
533 \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)- \texttt{loDiff} \leq \texttt{src} (x,y) \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)+ \texttt{upDiff}
535 in case of a grayscale image and fixed range
541 \texttt{src} (x',y')_r- \texttt{loDiff} _r \leq \texttt{src} (x,y)_r \leq \texttt{src} (x',y')_r+ \texttt{upDiff} _r,
545 \texttt{src} (x',y')_g- \texttt{loDiff} _g \leq \texttt{src} (x,y)_g \leq \texttt{src} (x',y')_g+ \texttt{upDiff} _g
551 \texttt{src} (x',y')_b- \texttt{loDiff} _b \leq \texttt{src} (x,y)_b \leq \texttt{src} (x',y')_b+ \texttt{upDiff} _b
553 in case of a color image and floating range
560 \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_r- \texttt{loDiff} _r \leq \texttt{src} (x,y)_r \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_r+ \texttt{upDiff} _r,
564 \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_g- \texttt{loDiff} _g \leq \texttt{src} (x,y)_g \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_g+ \texttt{upDiff} _g
570 \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_b- \texttt{loDiff} _b \leq \texttt{src} (x,y)_b \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_b+ \texttt{upDiff} _b
572 in case of a color image and fixed range
575 :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:
578 Color/brightness of one of its neighbors that already belong to the connected component in case of a floating range.
581 Color/brightness of the seed point in case of a fixed range.
583 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.cpp`` sample.
585 .. seealso:: :ocv:func:`findContours`
591 Calculates the integral of an image.
593 .. ocv:function:: void integral( InputArray src, OutputArray sum, int sdepth=-1 )
595 .. ocv:function:: void integral( InputArray src, OutputArray sum, OutputArray sqsum, int sdepth=-1 )
597 .. ocv:function:: void integral( InputArray src, OutputArray sum, OutputArray sqsum, OutputArray tilted, int sdepth=-1 )
599 .. ocv:pyfunction:: cv2.integral(src[, sum[, sdepth]]) -> sum
601 .. ocv:pyfunction:: cv2.integral2(src[, sum[, sqsum[, sdepth]]]) -> sum, sqsum
603 .. ocv:pyfunction:: cv2.integral3(src[, sum[, sqsum[, tilted[, sdepth]]]]) -> sum, sqsum, tilted
605 .. ocv:cfunction:: void cvIntegral( const CvArr* image, CvArr* sum, CvArr* sqsum=NULL, CvArr* tilted_sum=NULL )
607 .. ocv:pyoldfunction:: cv.Integral(image, sum, sqsum=None, tiltedSum=None)-> None
609 :param image: input image as :math:`W \times H`, 8-bit or floating-point (32f or 64f).
611 :param sum: integral image as :math:`(W+1)\times (H+1)` , 32-bit integer or floating-point (32f or 64f).
613 :param sqsum: integral image for squared pixel values; it is :math:`(W+1)\times (H+1)`, double-precision floating-point (64f) array.
615 :param tilted: integral for the image rotated by 45 degrees; it is :math:`(W+1)\times (H+1)` array with the same data type as ``sum``.
617 :param sdepth: desired depth of the integral and the tilted integral images, ``CV_32S``, ``CV_32F``, or ``CV_64F``.
619 The functions calculate one or more integral images for the source image as follows:
623 \texttt{sum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)
627 \texttt{sqsum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)^2
631 \texttt{tilted} (X,Y) = \sum _{y<Y,abs(x-X+1) \leq Y-y-1} \texttt{image} (x,y)
633 Using these integral images, you can calculate sa um, mean, and standard deviation over a specific up-right or rotated rectangular region of the image in a constant time, for example:
637 \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,y_1)
639 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.
641 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`` .
643 .. image:: pics/integral.png
651 Applies a fixed-level threshold to each array element.
653 .. ocv:function:: double threshold( InputArray src, OutputArray dst, double thresh, double maxval, int type )
655 .. ocv:pyfunction:: cv2.threshold(src, thresh, maxval, type[, dst]) -> retval, dst
657 .. ocv:cfunction:: double cvThreshold( const CvArr* src, CvArr* dst, double threshold, double max_value, int threshold_type )
659 .. ocv:pyoldfunction:: cv.Threshold(src, dst, threshold, maxValue, thresholdType)-> None
661 :param src: input array (single-channel, 8-bit or 32-bit floating point).
663 :param dst: output array of the same size and type as ``src``.
665 :param thresh: threshold value.
667 :param maxval: maximum value to use with the ``THRESH_BINARY`` and ``THRESH_BINARY_INV`` thresholding types.
669 :param type: thresholding type (see the details below).
671 The function applies fixed-level thresholding
672 to a single-channel array. The function is typically used to get a
673 bi-level (binary) image out of a grayscale image (
674 :ocv:func:`compare` could
675 be also used for this purpose) or for removing a noise, that is, filtering
676 out pixels with too small or too large values. There are several
677 types of thresholding supported by the function. They are determined by ``type`` :
683 \texttt{dst} (x,y) = \fork{\texttt{maxval}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise}
685 * **THRESH_BINARY_INV**
689 \texttt{dst} (x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{maxval}}{otherwise}
695 \texttt{dst} (x,y) = \fork{\texttt{threshold}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise}
701 \texttt{dst} (x,y) = \fork{\texttt{src}(x,y)}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise}
703 * **THRESH_TOZERO_INV**
707 \texttt{dst} (x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise}
709 Also, the special value ``THRESH_OTSU`` may be combined with
710 one of the above values. In this case, the function determines the optimal threshold
711 value using the Otsu's algorithm and uses it instead of the specified ``thresh`` .
712 The function returns the computed threshold value.
713 Currently, the Otsu's method is implemented only for 8-bit images.
716 .. image:: pics/threshold.png
720 :ocv:func:`adaptiveThreshold`,
721 :ocv:func:`findContours`,
729 Performs a marker-based image segmentation using the watershed algorithm.
731 .. ocv:function:: void watershed( InputArray image, InputOutputArray markers )
733 .. ocv:cfunction:: void cvWatershed( const CvArr* image, CvArr* markers )
735 .. ocv:pyfunction:: cv2.watershed(image, markers) -> None
737 :param image: Input 8-bit 3-channel image.
739 :param markers: Input/output 32-bit single-channel image (map) of markers. It should have the same size as ``image`` .
741 The function implements one of the variants of watershed, non-parametric marker-based segmentation algorithm, described in [Meyer92]_.
743 Before passing the image to the function, you have to roughly outline the desired regions in the image ``markers`` with positive (``>0``) indices. So, every region is represented as one or more connected components with the pixel values 1, 2, 3, and so on. Such markers can be retrieved from a binary mask using :ocv:func:`findContours` and :ocv: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, 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.
745 Visual demonstration and usage example of the function can be found in the OpenCV samples directory (see the ``watershed.cpp`` demo).
747 .. note:: Any two neighbor connected components are not necessarily separated by a watershed boundary (-1's pixels); for example, they can touch each other in the initial marker image passed to the function.
749 .. seealso:: :ocv:func:`findContours`
753 Runs the GrabCut algorithm.
755 .. ocv:function:: void grabCut( InputArray img, InputOutputArray mask, Rect rect, InputOutputArray bgdModel, InputOutputArray fgdModel, int iterCount, int mode=GC_EVAL )
757 .. ocv:pyfunction:: cv2.grabCut(img, mask, rect, bgdModel, fgdModel, iterCount[, mode]) -> None
759 :param img: Input 8-bit 3-channel image.
761 :param mask: Input/output 8-bit single-channel mask. The mask is initialized by the function when ``mode`` is set to ``GC_INIT_WITH_RECT``. Its elements may have one of following values:
763 * **GC_BGD** defines an obvious background pixels.
765 * **GC_FGD** defines an obvious foreground (object) pixel.
767 * **GC_PR_BGD** defines a possible background pixel.
769 * **GC_PR_FGD** defines a possible foreground pixel.
771 :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`` .
773 :param bgdModel: Temporary array for the background model. Do not modify it while you are processing the same image.
775 :param fgdModel: Temporary arrays for the foreground model. Do not modify it while you are processing the same image.
777 :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`` .
779 :param mode: Operation mode that could be one of the following:
781 * **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.
783 * **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`` .
785 * **GC_EVAL** The value means that the algorithm should just resume.
787 The function implements the `GrabCut image segmentation algorithm <http://en.wikipedia.org/wiki/GrabCut>`_.
788 See the sample ``grabcut.cpp`` to learn how to use the function.
790 .. [Borgefors86] Borgefors, Gunilla, *Distance transformations in digital images*. Comput. Vision Graph. Image Process. 34 3, pp 344–371 (1986)
792 .. [Felzenszwalb04] Felzenszwalb, Pedro F. and Huttenlocher, Daniel P. *Distance Transforms of Sampled Functions*, TR2004-1963, TR2004-1963 (2004)
794 .. [Meyer92] Meyer, F. *Color Image Segmentation*, ICIP92, 1992
796 .. [Telea04] Alexandru Telea, *An Image Inpainting Technique Based on the Fast Marching Method*. Journal of Graphics, GPU, and Game Tools 9 1, pp 23-34 (2004)