1 \section{Miscellaneous Image Transformations}
5 \cvCPyFunc{AdaptiveThreshold}
6 Applies an adaptive threshold to an array.
9 void cvAdaptiveThreshold(
10 \par const CvArr* src,\par CvArr* dst,\par double maxValue,\par
11 int adaptive\_method=CV\_ADAPTIVE\_THRESH\_MEAN\_C,\par
12 int thresholdType=CV\_THRESH\_BINARY,\par
13 int blockSize=3,\par double param1=5 );
16 \cvdefPy{AdaptiveThreshold(src,dst,maxValue, adaptive\_method=CV\_ADAPTIVE\_THRESH\_MEAN\_C, thresholdType=CV\_THRESH\_BINARY,blockSize=3,param1=5)-> None}
19 \cvarg{src}{Source image}
20 \cvarg{dst}{Destination image}
21 \cvarg{maxValue}{Maximum value that is used with \texttt{CV\_THRESH\_BINARY} and \texttt{CV\_THRESH\_BINARY\_INV}}
22 \cvarg{adaptive\_method}{Adaptive thresholding algorithm to use: \texttt{CV\_ADAPTIVE\_THRESH\_MEAN\_C} or \texttt{CV\_ADAPTIVE\_THRESH\_GAUSSIAN\_C} (see the discussion)}
23 \cvarg{thresholdType}{Thresholding type; must be one of
25 \cvarg{CV\_THRESH\_BINARY}{xxx}
26 \cvarg{CV\_THRESH\_BINARY\_INV}{xxx}
28 \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}
29 \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}
32 The function transforms a grayscale image to a binary image according to the formulas:
35 \cvarg{CV\_THRESH\_BINARY}{\[ dst(x,y) = \fork{\texttt{maxValue}}{if $src(x,y) > T(x,y)$}{0}{otherwise} \]}
36 \cvarg{CV\_THRESH\_BINARY\_INV}{\[ dst(x,y) = \fork{0}{if $src(x,y) > T(x,y)$}{\texttt{maxValue}}{otherwise} \]}
39 where $T(x,y)$ is a threshold calculated individually for each pixel.
41 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}.
43 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}.
46 Converts an image from one color space to another.
50 \par const CvArr* src,
53 }\cvdefPy{CvtColor(src,dst,code)-> None}
56 \cvarg{src}{The source 8-bit (8u), 16-bit (16u) or single-precision floating-point (32f) image}
57 \cvarg{dst}{The destination image of the same data type as the source. The number of channels may be different}
58 \cvarg{code}{Color conversion operation that can be specifed using \texttt{CV\_ \textit{src\_color\_space} 2 \textit{dst\_color\_space}} constants (see below)}
61 The function converts the input image from one color
62 space to another. The function ignores the \texttt{colorModel} and
63 \texttt{channelSeq} fields of the \texttt{IplImage} header, so the
64 source image color space should be specified correctly (including
65 order of the channels in the case of RGB space. For example, BGR means 24-bit
66 format with $B_0, G_0, R_0, B_1, G_1, R_1, ...$ layout
67 whereas RGB means 24-format with $R_0, G_0, B_0, R_1, G_1, B_1, ...$
70 The conventional range for R,G,B channel values is:
73 \item 0 to 255 for 8-bit images
74 \item 0 to 65535 for 16-bit images and
75 \item 0 to 1 for floating-point images.
78 Of course, in the case of linear transformations the range can be
79 specific, but in order to get correct results in the case of non-linear
80 transformations, the input image should be scaled.
82 The function can do the following transformations:
85 \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:
87 \text{RGB[A] to Gray:} Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
91 \text{Gray to RGB[A]:} R \leftarrow Y, G \leftarrow Y, B \leftarrow Y, A \leftarrow 0
94 The conversion from a RGB image to gray is done with:
96 cvCvtColor(src ,bwsrc, CV_RGB2GRAY)
99 \item RGB $\leftrightarrow$ CIE XYZ.Rec 709 with D65 white point (\texttt{CV\_BGR2XYZ, CV\_RGB2XYZ, CV\_XYZ2BGR, CV\_XYZ2RGB}):
108 0.412453 & 0.357580 & 0.180423\\
109 0.212671 & 0.715160 & 0.072169\\
110 0.019334 & 0.119193 & 0.950227
127 3.240479 & -1.53715 & -0.498535\\
128 -0.969256 & 1.875991 & 0.041556\\
129 0.055648 & -0.204043 & 1.057311
138 $X$, $Y$ and $Z$ cover the whole value range (in the case of floating-point images $Z$ may exceed 1).
140 \item RGB $\leftrightarrow$ YCrCb JPEG (a.k.a. YCC) (\texttt{CV\_BGR2YCrCb, CV\_RGB2YCrCb, CV\_YCrCb2BGR, CV\_YCrCb2RGB})
141 \[ Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B \]
142 \[ Cr \leftarrow (R-Y) \cdot 0.713 + delta \]
143 \[ Cb \leftarrow (B-Y) \cdot 0.564 + delta \]
144 \[ R \leftarrow Y + 1.403 \cdot (Cr - delta) \]
145 \[ G \leftarrow Y - 0.344 \cdot (Cr - delta) - 0.714 \cdot (Cb - delta) \]
146 \[ B \leftarrow Y + 1.773 \cdot (Cb - delta) \]
151 128 & \mbox{for 8-bit images}\\
152 32768 & \mbox{for 16-bit images}\\
153 0.5 & \mbox{for floating-point images}
156 Y, Cr and Cb cover the whole value range.
158 \item RGB $\leftrightarrow$ HSV (\texttt{CV\_BGR2HSV, CV\_RGB2HSV, CV\_HSV2BGR, CV\_HSV2RGB})
159 in the case of 8-bit and 16-bit images
160 R, G and B are converted to floating-point format and scaled to fit the 0 to 1 range
161 \[ V \leftarrow max(R,G,B) \]
163 \[ S \leftarrow \fork{\frac{V-min(R,G,B)}{V}}{if $V \neq 0$}{0}{otherwise} \]
164 \[ H \leftarrow \forkthree
165 {{60(G - B)}/{S}}{if $V=R$}
166 {{120+60(B - R)}/{S}}{if $V=G$}
167 {{240+60(R - G)}/{S}}{if $V=B$} \]
168 if $H<0$ then $H \leftarrow H+360$
170 On output $0 \leq V \leq 1$, $0 \leq S \leq 1$, $0 \leq H \leq 360$.
172 The values are then converted to the destination data type:
175 \[ V \leftarrow 255 V, S \leftarrow 255 S, H \leftarrow H/2 \text{(to fit to 0 to 255)} \]
176 \item[16-bit images (currently not supported)]
177 \[ V <- 65535 V, S <- 65535 S, H <- H \]
179 H, S, V are left as is
182 \item RGB $\leftrightarrow$ HLS (\texttt{CV\_BGR2HLS, CV\_RGB2HLS, CV\_HLS2BGR, CV\_HLS2RGB}).
183 in the case of 8-bit and 16-bit images
184 R, G and B are converted to floating-point format and scaled to fit the 0 to 1 range.
185 \[ V_{max} \leftarrow {max}(R,G,B) \]
186 \[ V_{min} \leftarrow {min}(R,G,B) \]
187 \[ L \leftarrow \frac{V_{max} + V_{min}}{2} \]
188 \[ S \leftarrow \fork
189 {\frac{V_{max} - V_{min}}{V_{max} + V_{min}}}{if $L < 0.5$}
190 {\frac{V_{max} - V_{min}}{2 - (V_{max} + V_{min})}}{if $L \ge 0.5$} \]
191 \[ H \leftarrow \forkthree
192 {{60(G - B)}/{S}}{if $V_{max}=R$}
193 {{120+60(B - R)}/{S}}{if $V_{max}=G$}
194 {{240+60(R - G)}/{S}}{if $V_{max}=B$} \]
195 if $H<0$ then $H \leftarrow H+360$
196 On output $0 \leq L \leq 1$, $0 \leq S \leq 1$, $0 \leq H \leq 360$.
198 The values are then converted to the destination data type:
201 \[ V \leftarrow 255 V, S \leftarrow 255 S, H \leftarrow H/2 \text{(to fit to 0 to 255)} \]
202 \item[16-bit images (currently not supported)]
203 \[ V <- 65535 V, S <- 65535 S, H <- H \]
205 H, S, V are left as is
208 \item RGB $\leftrightarrow$ CIE L*a*b* (\texttt{CV\_BGR2Lab, CV\_RGB2Lab, CV\_Lab2BGR, CV\_Lab2RGB})
209 in the case of 8-bit and 16-bit images
210 R, G and B are converted to floating-point format and scaled to fit the 0 to 1 range
211 \[ \vecthree{X}{Y}{Z} \leftarrow \vecthreethree
212 {0.412453}{0.357580}{0.180423}
213 {0.212671}{0.715160}{0.072169}
214 {0.019334}{0.119193}{0.950227}
216 \vecthree{R}{G}{B} \]
217 \[ X \leftarrow X/X_n, \text{where} X_n = 0.950456 \]
218 \[ Z \leftarrow Z/Z_n, \text{where} Z_n = 1.088754 \]
219 \[ L \leftarrow \fork
220 {116*Y^{1/3}-16}{for $Y>0.008856$}
221 {903.3*Y}{for $Y \le 0.008856$} \]
222 \[ a \leftarrow 500 (f(X)-f(Y)) + delta \]
223 \[ b \leftarrow 200 (f(Y)-f(Z)) + delta \]
226 {t^{1/3}}{for $t>0.008856$}
227 {7.787 t+16/116}{for $t<=0.008856$} \]
229 \[ delta = \fork{128}{for 8-bit images}{0}{for floating-point images} \]
230 On output $0 \leq L \leq 100$, $-127 \leq a \leq 127$, $-127 \leq b \leq 127$
232 The values are then converted to the destination data type:
235 \[L \leftarrow L*255/100, a \leftarrow a + 128, b \leftarrow b + 128\]
236 \item[16-bit images] currently not supported
238 L, a, b are left as is
241 \item RGB $\leftrightarrow$ CIE L*u*v* (\texttt{CV\_BGR2Luv, CV\_RGB2Luv, CV\_Luv2BGR, CV\_Luv2RGB})
242 in the case of 8-bit and 16-bit images
243 R, G and B are converted to floating-point format and scaled to fit 0 to 1 range
244 \[ \vecthree{X}{Y}{Z} \leftarrow \vecthreethree
245 {0.412453}{0.357580}{0.180423}
246 {0.212671}{0.715160}{0.072169}
247 {0.019334}{0.119193}{0.950227}
249 \vecthree{R}{G}{B} \]
250 \[ L \leftarrow \fork
251 {116 Y^{1/3}}{for $Y>0.008856$}
252 {903.3 Y}{for $Y<=0.008856$} \]
253 \[ u' \leftarrow 4*X/(X + 15*Y + 3 Z) \]
254 \[ v' \leftarrow 9*Y/(X + 15*Y + 3 Z) \]
255 \[ u \leftarrow 13*L*(u' - u_n) \quad \text{where} \quad u_n=0.19793943 \]
256 \[ v \leftarrow 13*L*(v' - v_n) \quad \text{where} \quad v_n=0.46831096 \]
257 On output $0 \leq L \leq 100$, $-134 \leq u \leq 220$, $-140 \leq v \leq 122$.
259 The values are then converted to the destination data type:
262 \[L \leftarrow 255/100 L, u \leftarrow 255/354 (u + 134), v \leftarrow 255/256 (v + 140) \]
263 \item[16-bit images] currently not supported
264 \item[32-bit images] L, u, v are left as is
267 The above formulas for converting RGB to/from various color spaces have been taken from multiple sources on Web, primarily from
269 at the Charles Poynton site.
271 \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:
276 \newcommand{\Rcell}{\color{red}R}
277 \newcommand{\Gcell}{\color{green}G}
278 \newcommand{\Bcell}{\color{blue}B}
279 \definecolor{BackGray}{rgb}{0.8,0.8,0.8}
280 \begin{array}{ c c c c c }
281 \Rcell&\Gcell&\Rcell&\Gcell&\Rcell\\
282 \Gcell&\colorbox{BackGray}{\Bcell}&\colorbox{BackGray}{\Gcell}&\Bcell&\Gcell\\
283 \Rcell&\Gcell&\Rcell&\Gcell&\Rcell\\
284 \Gcell&\Bcell&\Gcell&\Bcell&\Gcell\\
285 \Rcell&\Gcell&\Rcell&\Gcell&\Rcell
289 The output RGB components of a pixel are interpolated from 1, 2 or
290 4 neighbors of the pixel having the same color. There are several
291 modifications of the above pattern that can be achieved by shifting
292 the pattern one pixel left and/or one pixel up. The two letters
294 in the conversion constants
295 \texttt{CV\_Bayer} $ C_1 C_2 $ \texttt{2BGR}
297 \texttt{CV\_Bayer} $ C_1 C_2 $ \texttt{2RGB}
298 indicate the particular pattern
299 type - these are components from the second row, second and third
300 columns, respectively. For example, the above pattern has very
304 \cvCPyFunc{DistTransform}
305 Calculates the distance to the closest zero pixel for all non-zero pixels of the source image.
308 void cvDistTransform( \par const CvArr* src,\par CvArr* dst,\par int distance\_type=CV\_DIST\_L2,\par int mask\_size=3,\par const float* mask=NULL,\par CvArr* labels=NULL );
310 \cvdefPy{DistTransform(src,dst,distance\_type=CV\_DIST\_L2,mask\_size=3,mask=None,labels=NULL)-> None}
313 \cvarg{src}{8-bit, single-channel (binary) source image}
314 \cvarg{dst}{Output image with calculated distances (32-bit floating-point, single-channel)}
315 \cvarg{distance\_type}{Type of distance; can be \texttt{CV\_DIST\_L1, CV\_DIST\_L2, CV\_DIST\_C} or \texttt{CV\_DIST\_USER}}
316 \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\times 3$ mask gives the same result as a $5\times 5 $ yet it is faster}
317 \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\times 3$ mask and 3 numbers (horizontal/vertical shift cost, diagonal shift cost, knight's move cost) in the case of a $5\times 5$ mask}
318 \cvarg{labels}{The optional output 2d array of integer type labels, the same size as \texttt{src} and \texttt{dst}}
321 The function calculates the approximated
322 distance from every binary image pixel to the nearest zero pixel.
323 For zero pixels the function sets the zero distance, for others it
324 finds the shortest path consisting of basic shifts: horizontal,
325 vertical, diagonal or knight's move (the latest is available for a
326 $5\times 5$ mask). The overall distance is calculated as a sum of these
327 basic distances. Because the distance function should be symmetric,
328 all of the horizontal and vertical shifts must have the same cost (that
329 is denoted as \texttt{a}), all the diagonal shifts must have the
330 same cost (denoted \texttt{b}), and all knight's moves must have
331 the same cost (denoted \texttt{c}). For \texttt{CV\_DIST\_C} and
332 \texttt{CV\_DIST\_L1} types the distance is calculated precisely,
333 whereas for \texttt{CV\_DIST\_L2} (Euclidian distance) the distance
334 can be calculated only with some relative error (a $5\times 5$ mask
335 gives more accurate results), OpenCV uses the values suggested in
339 \begin{tabular}{| c | c | c |}
341 \texttt{CV\_DIST\_C} & $(3\times 3)$ & a = 1, b = 1\\ \hline
342 \texttt{CV\_DIST\_L1} & $(3\times 3)$ & a = 1, b = 2\\ \hline
343 \texttt{CV\_DIST\_L2} & $(3\times 3)$ & a=0.955, b=1.3693\\ \hline
344 \texttt{CV\_DIST\_L2} & $(5\times 5)$ & a=1, b=1.4, c=2.1969\\ \hline
347 And below are samples of the distance field (black (0) pixel is in the middle of white square) in the case of a user-defined distance:
349 User-defined $3 \times 3$ mask (a=1, b=1.5)
351 \begin{tabular}{| c | c | c | c | c | c | c |}
353 4.5 & 4 & 3.5 & 3 & 3.5 & 4 & 4.5\\ \hline
354 4 & 3 & 2.5 & 2 & 2.5 & 3 & 4\\ \hline
355 3.5 & 2.5 & 1.5 & 1 & 1.5 & 2.5 & 3.5\\ \hline
356 3 & 2 & 1 & & 1 & 2 & 3\\ \hline
357 3.5 & 2.5 & 1.5 & 1 & 1.5 & 2.5 & 3.5\\ \hline
358 4 & 3 & 2.5 & 2 & 2.5 & 3 & 4\\ \hline
359 4.5 & 4 & 3.5 & 3 & 3.5 & 4 & 4.5\\ \hline
362 User-defined $5 \times 5$ mask (a=1, b=1.5, c=2)
364 \begin{tabular}{| c | c | c | c | c | c | c |}
366 4.5 & 3.5 & 3 & 3 & 3 & 3.5 & 4.5\\ \hline
367 3.5 & 3 & 2 & 2 & 2 & 3 & 3.5\\ \hline
368 3 & 2 & 1.5 & 1 & 1.5 & 2 & 3\\ \hline
369 3 & 2 & 1 & & 1 & 2 & 3\\ \hline
370 3 & 2 & 1.5 & 1 & 1.5 & 2 & 3\\ \hline
371 3.5 & 3 & 2 & 2 & 2 & 3 & 3.5\\ \hline
372 4 & 3.5 & 3 & 3 & 3 & 3.5 & 4\\ \hline
376 Typically, for a fast, coarse distance estimation \texttt{CV\_DIST\_L2},
377 a $3\times 3$ mask is used, and for a more accurate distance estimation
378 \texttt{CV\_DIST\_L2}, a $5\times 5$ mask is used.
380 When the output parameter \texttt{labels} is not \texttt{NULL}, for
381 every non-zero pixel the function also finds the nearest connected
382 component consisting of zero pixels. The connected components
383 themselves are found as contours in the beginning of the function.
385 In this mode the processing time is still O(N), where N is the number of
386 pixels. Thus, the function provides a very fast way to compute approximate
387 Voronoi diagram for the binary image.
389 \cvclass{CvConnectedComp}
393 typedef struct CvConnectedComp
395 double area; /* area of the segmented component */
396 CvScalar value; /* average color of the connected component */
397 CvRect rect; /* ROI of the segmented component */
398 CvSeq* contour; /* optional component boundary
399 (the contour might have child contours corresponding to the holes) */
406 Connected component, represented as a tuple (area, value, rect), where
407 area is the area of the component as a float, value is the average color
408 as a \cross{CvScalar}, and rect is the ROI of the component, as a \cross{CvRect}.
411 \cvCPyFunc{FloodFill}
412 Fills a connected component with the given color.
415 void cvFloodFill(\par CvArr* image,\par CvPoint seed\_point,\par CvScalar new\_val,\par
416 CvScalar lo\_diff=cvScalarAll(0),\par CvScalar up\_diff=cvScalarAll(0),\par
417 CvConnectedComp* comp=NULL,\par int flags=4,\par CvArr* mask=NULL );
420 \cvdefPy{FloodFill(image,seed\_point,new\_val,lo\_diff=(0,0,0,0),up\_diff=(0,0,0,0),flags=4,mask=NULL)-> comp}
424 \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)}
425 \cvarg{seed\_point}{The starting point}
426 \cvarg{new\_val}{New value of the repainted domain pixels}
427 \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}
428 \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}
430 \cvarg{comp}{Pointer to the structure that the function fills with the information about the repainted domain.
431 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}}
433 \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}}
435 \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:
437 \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)}
438 \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)}
440 \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)$ }
443 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:
447 \item[grayscale image, floating range] \[
448 src(x',y')-\texttt{lo\_diff} <= src(x,y) <= src(x',y')+\texttt{up\_diff} \]
450 \item[grayscale image, fixed range] \[
451 src(seed.x,seed.y)-\texttt{lo\_diff}<=src(x,y)<=src(seed.x,seed.y)+\texttt{up\_diff} \]
453 \item[color image, floating range]
454 \[ src(x',y')_r-\texttt{lo\_diff}_r<=src(x,y)_r<=src(x',y')_r+\texttt{up\_diff}_r \]
455 \[ src(x',y')_g-\texttt{lo\_diff}_g<=src(x,y)_g<=src(x',y')_g+\texttt{up\_diff}_g \]
456 \[ src(x',y')_b-\texttt{lo\_diff}_b<=src(x,y)_b<=src(x',y')_b+\texttt{up\_diff}_b \]
458 \item[color image, fixed range]
459 \[ src(seed.x,seed.y)_r-\texttt{lo\_diff}_r<=src(x,y)_r<=src(seed.x,seed.y)_r+\texttt{up\_diff}_r \]
460 \[ src(seed.x,seed.y)_g-\texttt{lo\_diff}_g<=src(x,y)_g<=src(seed.x,seed.y)_g+\texttt{up\_diff}_g \]
461 \[ src(seed.x,seed.y)_b-\texttt{lo\_diff}_b<=src(x,y)_b<=src(seed.x,seed.y)_b+\texttt{up\_diff}_b \]
464 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:
466 \item color/brightness of one of its neighbors that are already referred to the connected component in the case of floating range
467 \item color/brightness of the seed point in the case of fixed range.
471 Inpaints the selected region in the image.
474 void cvInpaint( \par const CvArr* src, \par const CvArr* mask, \par CvArr* dst,
475 \par double inpaintRadius, \par int flags);
477 }\cvdefPy{Inpaint(src,mask,dst,inpaintRadius,flags) -> None}
480 \cvarg{src}{The input 8-bit 1-channel or 3-channel image.}
481 \cvarg{mask}{The inpainting mask, 8-bit 1-channel image. Non-zero pixels indicate the area that needs to be inpainted.}
482 \cvarg{dst}{The output image of the same format and the same size as input.}
483 \cvarg{inpaintRadius}{The radius of circlular neighborhood of each point inpainted that is considered by the algorithm.}
484 \cvarg{flags}{The inpainting method, one of the following:
486 \cvarg{CV\_INPAINT\_NS}{Navier-Stokes based method.}
487 \cvarg{CV\_INPAINT\_TELEA}{The method by Alexandru Telea \cite{Telea04}}
491 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.
494 Calculates the integral of an image.
498 \par const CvArr* image,
500 \par CvArr* sqsum=NULL,
501 \par CvArr* tiltedSum=NULL );
502 }\cvdefPy{Integral(image,sum,sqsum=NULL,tiltedSum=NULL)-> None}
505 \cvarg{image}{The source image, $W\times H$, 8-bit or floating-point (32f or 64f)}
506 \cvarg{sum}{The integral image, $(W+1)\times (H+1)$, 32-bit integer or double precision floating-point (64f)}
507 \cvarg{sqsum}{The integral image for squared pixel values, $(W+1)\times (H+1)$, double precision floating-point (64f)}
508 \cvarg{tiltedSum}{The integral for the image rotated by 45 degrees, $(W+1)\times (H+1)$, the same data type as \texttt{sum}}
511 The function calculates one or more integral images for the source image as following:
514 \texttt{sum}(X,Y) = \sum_{x<X,y<Y} \texttt{image}(x,y)
518 \texttt{sqsum}(X,Y) = \sum_{x<X,y<Y} \texttt{image}(x,y)^2
522 \texttt{tiltedSum}(X,Y) = \sum_{y<Y,abs(x-X+1)\leq Y-y-1} \texttt{image}(x,y)
525 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:
528 \sum_{x_1<=x<x_2, \, y_1<=y<y_2} = \texttt{sum}(x_2,y_2)-\texttt{sum}(x_1,y_2)-\texttt{sum}(x_2,y_1)+\texttt{sum}(x_1,x_1)
531 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.
534 \cvCPyFunc{PyrMeanShiftFiltering}
535 Does meanshift image segmentation
539 void cvPyrMeanShiftFiltering( \par const CvArr* src, \par CvArr* dst,
540 \par double sp, \par double sr, \par int max\_level=1,
541 \par CvTermCriteria termcrit=\par cvTermCriteria(CV\_TERMCRIT\_ITER+CV\_TERMCRIT\_EPS,5,1));
543 }\cvdefPy{PyrMeanShiftFiltering(src,dst,sp,sr,max\_level=1,termcrit=(CV\_TERMCRIT\_ITER+CV\_TERMCRIT\_EPS,5,1))-> None}
546 \cvarg{src}{The source 8-bit, 3-channel image.}
547 \cvarg{dst}{The destination image of the same format and the same size as the source.}
548 \cvarg{sp}{The spatial window radius.}
549 \cvarg{sr}{The color window radius.}
550 \cvarg{max\_level}{Maximum level of the pyramid for the segmentation.}
551 \cvarg{termcrit}{Termination criteria: when to stop meanshift iterations.}
554 The function implements the filtering
555 stage of meanshift segmentation, that is, the output of the function is
556 the filtered "posterized" image with color gradients and fine-grain
557 texture flattened. At every pixel $(X,Y)$ of the input image (or
558 down-sized input image, see below) the function executes meanshift
559 iterations, that is, the pixel $(X,Y)$ neighborhood in the joint
560 space-color hyperspace is considered:
563 (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}
566 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:
568 $(X,Y)~(X',Y'), (R,G,B)~(R',G',B').$
570 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):
572 $I(X,Y) <- (R*,G*,B*)$
574 Then $\texttt{max\_level}>0$ , the gaussian pyramid of
575 $\texttt{max\_level}+1$ levels is built, and the above procedure is run
576 on the smallest layer. After that, the results are propagated to the
577 larger layer and the iterations are run again only on those pixels where
578 the layer colors differ much ( $>\texttt{sr}$ ) from the lower-resolution
579 layer, that is, the boundaries of the color regions are clarified. Note,
580 that the results will be actually different from the ones obtained by
581 running the meanshift procedure on the whole original image (i.e. when
582 $\texttt{max\_level}==0$ ).
584 \cvCPyFunc{PyrSegmentation}
585 Implements image segmentation by pyramids.
588 void cvPyrSegmentation(\par IplImage* src,\par IplImage* dst,\par
589 CvMemStorage* storage,\par CvSeq** comp,\par
590 int level,\par double threshold1,\par double threshold2 );
591 }\cvdefPy{PyrSegmentation(src,dst,storage,level,threshold1,threshold2)-> comp}
594 \cvarg{src}{The source image}
595 \cvarg{dst}{The destination image}
596 \cvarg{storage}{Storage; stores the resulting sequence of connected components}
597 \cvarg{comp}{Pointer to the output sequence of the segmented components}
598 \cvarg{level}{Maximum level of the pyramid for the segmentation}
599 \cvarg{threshold1}{Error threshold for establishing the links}
600 \cvarg{threshold2}{Error threshold for the segments clustering}
603 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
604 $p(c(a),c(b))<threshold1$.
605 After the connected components are defined, they are joined into several clusters.
606 Any two segments A and B belong to the same cluster, if $p(c(A),c(B))<threshold2$.
607 If the input image has only one channel, then $p(c^1,c^2)=|c^1-c^2|$.
608 If the input image has three channels (red, green and blue), then
610 p(c^1,c^2) = 0.30 (c^1_r - c^2_r) +
611 0.59 (c^1_g - c^2_g) +
612 0.11 (c^1_b - c^2_b).
615 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.
617 \cvCPyFunc{Threshold}
618 Applies a fixed-level threshold to array elements.
622 \par const CvArr* src,
624 \par double threshold,
625 \par double maxValue,
626 \par int thresholdType );
628 \cvdefPy{Threshold(src,dst,threshold,maxValue,thresholdType)-> None}
631 \cvarg{src}{Source array (single-channel, 8-bit or 32-bit floating point)}
632 \cvarg{dst}{Destination array; must be either the same type as \texttt{src} or 8-bit}
633 \cvarg{threshold}{Threshold value}
634 \cvarg{maxValue}{Maximum value to use with \texttt{CV\_THRESH\_BINARY} and \texttt{CV\_THRESH\_BINARY\_INV} thresholding types}
635 \cvarg{thresholdType}{Thresholding type (see the discussion)}
638 The function applies fixed-level thresholding
639 to a single-channel array. The function is typically used to get a
640 bi-level (binary) image out of a grayscale image (\cvCPyCross{CmpS} could
641 be also used for this purpose) or for removing a noise, i.e. filtering
642 out pixels with too small or too large values. There are several
643 types of thresholding that the function supports that are determined by
644 \texttt{thresholdType}:
647 \cvarg{CV\_THRESH\_BINARY}{\[ \texttt{dst}(x,y) = \fork{\texttt{maxValue}}{if $\texttt{src}(x,y) > \texttt{threshold}$}{0}{otherwise} \]}
648 \cvarg{CV\_THRESH\_BINARY\_INV}{\[ \texttt{dst}(x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{threshold}$}{\texttt{maxValue}}{otherwise} \]}
649 \cvarg{CV\_THRESH\_TRUNC}{\[ \texttt{dst}(x,y) = \fork{\texttt{threshold}}{if $\texttt{src}(x,y) > \texttt{threshold}$}{\texttt{src}(x,y)}{otherwise} \]}
650 \cvarg{CV\_THRESH\_TOZERO}{\[ \texttt{dst}(x,y) = \fork{\texttt{src}(x,y)}{if $\texttt{src}(x,y) > \texttt{threshold}$}{0}{otherwise} \]}
651 \cvarg{CV\_THRESH\_TOZERO\_INV}{\[ \texttt{dst}(x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{threshold}$}{\texttt{src}(x,y)}{otherwise} \]}
654 Also, the special value \texttt{CV\_THRESH\_OTSU} may be combined with
655 one of the above values. In this case the function determines the optimal threshold
656 value using Otsu's algorithm and uses it instead of the specified \texttt{thresh}.
657 The function returns the computed threshold value.
658 Currently, Otsu's method is implemented only for 8-bit images.
660 \includegraphics[width=0.5\textwidth]{pics/threshold.png}
667 \cvCppFunc{adaptiveThreshold}
668 Applies an adaptive threshold to an array.
670 \cvdefCpp{void adaptiveThreshold( const Mat\& src, Mat\& dst, double maxValue,\par
671 int adaptiveMethod, int thresholdType,\par
672 int blockSize, double C );}
674 \cvarg{src}{Source 8-bit single-channel image}
675 \cvarg{dst}{Destination image; will have the same size and the same type as \texttt{src}}
676 \cvarg{maxValue}{The non-zero value assigned to the pixels for which the condition is satisfied. See the discussion}
677 \cvarg{adaptiveMethod}{Adaptive thresholding algorithm to use,
678 \texttt{ADAPTIVE\_THRESH\_MEAN\_C} or \texttt{ADAPTIVE\_THRESH\_GAUSSIAN\_C} (see the discussion)}
679 \cvarg{thresholdType}{Thresholding type; must be one of \texttt{THRESH\_BINARY} or \texttt{THRESH\_BINARY\_INV}}
680 \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}
681 \cvarg{C}{The constant subtracted from the mean or weighted mean (see the discussion); normally, it's positive, but may be zero or negative as well}
684 The function transforms a grayscale image to a binary image according to the formulas:
687 \cvarg{THRESH\_BINARY}{\[ dst(x,y) = \fork{\texttt{maxValue}}{if $src(x,y) > T(x,y)$}{0}{otherwise} \]}
688 \cvarg{THRESH\_BINARY\_INV}{\[ dst(x,y) = \fork{0}{if $src(x,y) > T(x,y)$}{\texttt{maxValue}}{otherwise} \]}
691 where $T(x,y)$ is a threshold calculated individually for each pixel.
695 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}.
697 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}.
700 The function can process the image in-place.
702 See also: \cvCppCross{threshold}, \cvCppCross{blur}, \cvCppCross{GaussianBlur}
706 Converts image from one color space to another
708 \cvdefCpp{void cvtColor( const Mat\& src, Mat\& dst, int code, int dstCn=0 );}
710 \cvarg{src}{The source image, 8-bit unsigned, 16-bit unsigned (\texttt{CV\_16UC...}) or single-precision floating-point}
711 \cvarg{dst}{The destination image; will have the same size and the same depth as \texttt{src}}
712 \cvarg{code}{The color space conversion code; see the discussion}
713 \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}}
716 The function converts the input image from one color
717 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).
719 The conventional ranges for R, G and B channel values are:
722 \item 0 to 255 for \texttt{CV\_8U} images
723 \item 0 to 65535 for \texttt{CV\_16U} images and
724 \item 0 to 1 for \texttt{CV\_32F} images.
727 Of course, in the case of linear transformations the range does not matter,
728 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:
731 cvtColor(img, img, CV_BGR2Luv);
734 The function can do the following transformations:
737 \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:
739 \text{RGB[A] to Gray:}\quad Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
743 \text{Gray to RGB[A]:}\quad R \leftarrow Y, G \leftarrow Y, B \leftarrow Y, A \leftarrow 0
746 The conversion from a RGB image to gray is done with:
748 cvtColor(src, bwsrc, CV_RGB2GRAY);
751 Some more advanced channel reordering can also be done with \cvCppCross{mixChannels}.
753 \item RGB $\leftrightarrow$ CIE XYZ.Rec 709 with D65 white point (\texttt{CV\_BGR2XYZ, CV\_RGB2XYZ, CV\_XYZ2BGR, CV\_XYZ2RGB}):
762 0.412453 & 0.357580 & 0.180423\\
763 0.212671 & 0.715160 & 0.072169\\
764 0.019334 & 0.119193 & 0.950227
781 3.240479 & -1.53715 & -0.498535\\
782 -0.969256 & 1.875991 & 0.041556\\
783 0.055648 & -0.204043 & 1.057311
792 $X$, $Y$ and $Z$ cover the whole value range (in the case of floating-point images $Z$ may exceed 1).
794 \item RGB $\leftrightarrow$ YCrCb JPEG (a.k.a. YCC) (\texttt{CV\_BGR2YCrCb, CV\_RGB2YCrCb, CV\_YCrCb2BGR, CV\_YCrCb2RGB})
795 \[ Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B \]
796 \[ Cr \leftarrow (R-Y) \cdot 0.713 + delta \]
797 \[ Cb \leftarrow (B-Y) \cdot 0.564 + delta \]
798 \[ R \leftarrow Y + 1.403 \cdot (Cr - delta) \]
799 \[ G \leftarrow Y - 0.344 \cdot (Cr - delta) - 0.714 \cdot (Cb - delta) \]
800 \[ B \leftarrow Y + 1.773 \cdot (Cb - delta) \]
805 128 & \mbox{for 8-bit images}\\
806 32768 & \mbox{for 16-bit images}\\
807 0.5 & \mbox{for floating-point images}
810 Y, Cr and Cb cover the whole value range.
812 \item RGB $\leftrightarrow$ HSV (\texttt{CV\_BGR2HSV, CV\_RGB2HSV, CV\_HSV2BGR, CV\_HSV2RGB})
813 in the case of 8-bit and 16-bit images
814 R, G and B are converted to floating-point format and scaled to fit the 0 to 1 range
815 \[ V \leftarrow max(R,G,B) \]
817 \[ S \leftarrow \fork{\frac{V-min(R,G,B)}{V}}{if $V \neq 0$}{0}{otherwise} \]
818 \[ H \leftarrow \forkthree
819 {{60(G - B)}/{S}}{if $V=R$}
820 {{120+60(B - R)}/{S}}{if $V=G$}
821 {{240+60(R - G)}/{S}}{if $V=B$} \]
822 if $H<0$ then $H \leftarrow H+360$
824 On output $0 \leq V \leq 1$, $0 \leq S \leq 1$, $0 \leq H \leq 360$.
826 The values are then converted to the destination data type:
829 \[ V \leftarrow 255 V, S \leftarrow 255 S, H \leftarrow H/2 \text{(to fit to 0 to 255)} \]
830 \item[16-bit images (currently not supported)]
831 \[ V <- 65535 V, S <- 65535 S, H <- H \]
833 H, S, V are left as is
836 \item RGB $\leftrightarrow$ HLS (\texttt{CV\_BGR2HLS, CV\_RGB2HLS, CV\_HLS2BGR, CV\_HLS2RGB}).
837 in the case of 8-bit and 16-bit images
838 R, G and B are converted to floating-point format and scaled to fit the 0 to 1 range.
839 \[ V_{max} \leftarrow {max}(R,G,B) \]
840 \[ V_{min} \leftarrow {min}(R,G,B) \]
841 \[ L \leftarrow \frac{V_{max} + V_{min}}{2} \]
842 \[ S \leftarrow \fork
843 {\frac{V_{max} - V_{min}}{V_{max} + V_{min}}}{if $L < 0.5$}
844 {\frac{V_{max} - V_{min}}{2 - (V_{max} + V_{min})}}{if $L \ge 0.5$} \]
845 \[ H \leftarrow \forkthree
846 {{60(G - B)}/{S}}{if $V_{max}=R$}
847 {{120+60(B - R)}/{S}}{if $V_{max}=G$}
848 {{240+60(R - G)}/{S}}{if $V_{max}=B$} \]
849 if $H<0$ then $H \leftarrow H+360$
850 On output $0 \leq L \leq 1$, $0 \leq S \leq 1$, $0 \leq H \leq 360$.
852 The values are then converted to the destination data type:
855 \[ V \leftarrow 255\cdot V, S \leftarrow 255\cdot S, H \leftarrow H/2\; \text{(to fit to 0 to 255)} \]
856 \item[16-bit images (currently not supported)]
857 \[ V <- 65535\cdot V, S <- 65535\cdot S, H <- H \]
859 H, S, V are left as is
862 \item RGB $\leftrightarrow$ CIE L*a*b* (\texttt{CV\_BGR2Lab, CV\_RGB2Lab, CV\_Lab2BGR, CV\_Lab2RGB})
863 in the case of 8-bit and 16-bit images
864 R, G and B are converted to floating-point format and scaled to fit the 0 to 1 range
865 \[ \vecthree{X}{Y}{Z} \leftarrow \vecthreethree
866 {0.412453}{0.357580}{0.180423}
867 {0.212671}{0.715160}{0.072169}
868 {0.019334}{0.119193}{0.950227}
870 \vecthree{R}{G}{B} \]
871 \[ X \leftarrow X/X_n, \text{where} X_n = 0.950456 \]
872 \[ Z \leftarrow Z/Z_n, \text{where} Z_n = 1.088754 \]
873 \[ L \leftarrow \fork
874 {116*Y^{1/3}-16}{for $Y>0.008856$}
875 {903.3*Y}{for $Y \le 0.008856$} \]
876 \[ a \leftarrow 500 (f(X)-f(Y)) + delta \]
877 \[ b \leftarrow 200 (f(Y)-f(Z)) + delta \]
880 {t^{1/3}}{for $t>0.008856$}
881 {7.787 t+16/116}{for $t\leq 0.008856$} \]
883 \[ delta = \fork{128}{for 8-bit images}{0}{for floating-point images} \]
884 On output $0 \leq L \leq 100$, $-127 \leq a \leq 127$, $-127 \leq b \leq 127$
886 The values are then converted to the destination data type:
889 \[L \leftarrow L*255/100,\; a \leftarrow a + 128,\; b \leftarrow b + 128\]
890 \item[16-bit images] currently not supported
892 L, a, b are left as is
895 \item RGB $\leftrightarrow$ CIE L*u*v* (\texttt{CV\_BGR2Luv, CV\_RGB2Luv, CV\_Luv2BGR, CV\_Luv2RGB})
896 in the case of 8-bit and 16-bit images
897 R, G and B are converted to floating-point format and scaled to fit 0 to 1 range
898 \[ \vecthree{X}{Y}{Z} \leftarrow \vecthreethree
899 {0.412453}{0.357580}{0.180423}
900 {0.212671}{0.715160}{0.072169}
901 {0.019334}{0.119193}{0.950227}
903 \vecthree{R}{G}{B} \]
904 \[ L \leftarrow \fork
905 {116 Y^{1/3}}{for $Y>0.008856$}
906 {903.3 Y}{for $Y\leq 0.008856$} \]
907 \[ u' \leftarrow 4*X/(X + 15*Y + 3 Z) \]
908 \[ v' \leftarrow 9*Y/(X + 15*Y + 3 Z) \]
909 \[ u \leftarrow 13*L*(u' - u_n) \quad \text{where} \quad u_n=0.19793943 \]
910 \[ v \leftarrow 13*L*(v' - v_n) \quad \text{where} \quad v_n=0.46831096 \]
911 On output $0 \leq L \leq 100$, $-134 \leq u \leq 220$, $-140 \leq v \leq 122$.
913 The values are then converted to the destination data type:
916 \[L \leftarrow 255/100 L,\; u \leftarrow 255/354 (u + 134),\; v \leftarrow 255/256 (v + 140) \]
917 \item[16-bit images] currently not supported
918 \item[32-bit images] L, u, v are left as is
921 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}
923 \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:
926 \newcommand{\Rcell}{\color{red}R}
927 \newcommand{\Gcell}{\color{green}G}
928 \newcommand{\Bcell}{\color{blue}B}
929 \definecolor{BackGray}{rgb}{0.8,0.8,0.8}
930 \begin{array}{ c c c c c }
931 \Rcell&\Gcell&\Rcell&\Gcell&\Rcell\\
932 \Gcell&\colorbox{BackGray}{\Bcell}&\colorbox{BackGray}{\Gcell}&\Bcell&\Gcell\\
933 \Rcell&\Gcell&\Rcell&\Gcell&\Rcell\\
934 \Gcell&\Bcell&\Gcell&\Bcell&\Gcell\\
935 \Rcell&\Gcell&\Rcell&\Gcell&\Rcell
939 The output RGB components of a pixel are interpolated from 1, 2 or
940 4 neighbors of the pixel having the same color. There are several
941 modifications of the above pattern that can be achieved by shifting
942 the pattern one pixel left and/or one pixel up. The two letters
944 in the conversion constants
945 \texttt{CV\_Bayer} $ C_1 C_2 $ \texttt{2BGR}
947 \texttt{CV\_Bayer} $ C_1 C_2 $ \texttt{2RGB}
948 indicate the particular pattern
949 type - these are components from the second row, second and third
950 columns, respectively. For example, the above pattern has very
956 \cvCppFunc{distanceTransform}
957 Calculates the distance to the closest zero pixel for each pixel of the source image.
959 \cvdefCpp{void distanceTransform( const Mat\& src, Mat\& dst,\par
960 int distanceType, int maskSize );\newline
961 void distanceTransform( const Mat\& src, Mat\& dst, Mat\& labels,\par
962 int distanceType, int maskSize );}
964 \cvarg{src}{8-bit, single-channel (binary) source image}
965 \cvarg{dst}{Output image with calculated distances; will be 32-bit floating-point, single-channel image of the same size as \texttt{src}}
966 \cvarg{distanceType}{Type of distance; can be \texttt{CV\_DIST\_L1, CV\_DIST\_L2} or \texttt{CV\_DIST\_C}}
967 \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\times 3$ mask gives the same result as a $5\times 5$ or any larger aperture.}
968 \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}
971 The functions \texttt{distanceTransform} calculate the approximate or precise
972 distance from every binary image pixel to the nearest zero pixel.
973 (for zero image pixels the distance will obviously be zero).
975 When \texttt{maskSize == CV\_DIST\_MASK\_PRECISE} and \texttt{distanceType == CV\_DIST\_L2}, the function runs the algorithm described in \cite{Felzenszwalb04}.
977 In other cases the algorithm \cite{Borgefors86} is used, that is,
978 for pixel the function finds the shortest path to the nearest zero pixel
979 consisting of basic shifts: horizontal,
980 vertical, diagonal or knight's move (the latest is available for a
981 $5\times 5$ mask). The overall distance is calculated as a sum of these
982 basic distances. Because the distance function should be symmetric,
983 all of the horizontal and vertical shifts must have the same cost (that
984 is denoted as \texttt{a}), all the diagonal shifts must have the
985 same cost (denoted \texttt{b}), and all knight's moves must have
986 the same cost (denoted \texttt{c}). For \texttt{CV\_DIST\_C} and
987 \texttt{CV\_DIST\_L1} types the distance is calculated precisely,
988 whereas for \texttt{CV\_DIST\_L2} (Euclidian distance) the distance
989 can be calculated only with some relative error (a $5\times 5$ mask
990 gives more accurate results). For \texttt{a}, \texttt{b} and \texttt{c}
991 OpenCV uses the values suggested in the original paper:
994 \begin{tabular}{| c | c | c |}
996 \texttt{CV\_DIST\_C} & $(3\times 3)$ & a = 1, b = 1\\ \hline
997 \texttt{CV\_DIST\_L1} & $(3\times 3)$ & a = 1, b = 2\\ \hline
998 \texttt{CV\_DIST\_L2} & $(3\times 3)$ & a=0.955, b=1.3693\\ \hline
999 \texttt{CV\_DIST\_L2} & $(5\times 5)$ & a=1, b=1.4, c=2.1969\\ \hline
1003 Typically, for a fast, coarse distance estimation \texttt{CV\_DIST\_L2},
1004 a $3\times 3$ mask is used, and for a more accurate distance estimation
1005 \texttt{CV\_DIST\_L2}, a $5\times 5$ mask or the precise algorithm is used.
1006 Note that both the precise and the approximate algorithms are linear on the number of pixels.
1008 The second variant of the function does not only compute the minimum distance for each pixel $(x, y)$,
1009 but it also identifies the nearest the nearest connected
1010 component consisting of zero pixels. Index of the component is stored in $\texttt{labels}(x, y)$.
1011 The connected components of zero pixels are also found and marked by the function.
1013 In this mode the complexity is still linear.
1014 That is, the function provides a very fast way to compute Voronoi diagram for the binary image.
1015 Currently, this second variant can only use the approximate distance transform algorithm.
1018 \cvCppFunc{floodFill}
1019 Fills a connected component with the given color.
1021 \cvdefCpp{int floodFill( Mat\& image,\par
1022 Point seed, Scalar newVal, Rect* rect=0,\par
1023 Scalar loDiff=Scalar(), Scalar upDiff=Scalar(),\par
1024 int flags=4 );\newline
1025 int floodFill( Mat\& image, Mat\& mask,\par
1026 Point seed, Scalar newVal, Rect* rect=0,\par
1027 Scalar loDiff=Scalar(), Scalar upDiff=Scalar(),\par
1030 \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)}
1031 \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}}
1032 \cvarg{seed}{The starting point}
1033 \cvarg{newVal}{New value of the repainted domain pixels}
1034 \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}
1035 \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}
1036 \cvarg{rect}{The optional output parameter that the function sets to the minimum bounding rectangle of the repainted domain}
1037 \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:
1039 \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)}
1040 \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}
1044 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:
1048 \item[grayscale image, floating range] \[
1049 \texttt{src}(x',y')-\texttt{loDiff} \leq \texttt{src}(x,y) \leq \texttt{src}(x',y')+\texttt{upDiff} \]
1051 \item[grayscale image, fixed range] \[
1052 \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} \]
1054 \item[color image, floating range]
1055 \[ \texttt{src}(x',y')_r-\texttt{loDiff}_r\leq \texttt{src}(x,y)_r\leq \texttt{src}(x',y')_r+\texttt{upDiff}_r \]
1056 \[ \texttt{src}(x',y')_g-\texttt{loDiff}_g\leq \texttt{src}(x,y)_g\leq \texttt{src}(x',y')_g+\texttt{upDiff}_g \]
1057 \[ \texttt{src}(x',y')_b-\texttt{loDiff}_b\leq \texttt{src}(x,y)_b\leq \texttt{src}(x',y')_b+\texttt{upDiff}_b \]
1059 \item[color image, fixed range]
1060 \[ \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 \]
1061 \[ \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 \]
1062 \[ \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 \]
1065 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:
1067 \item color/brightness of one of its neighbors that are already referred to the connected component in the case of floating range
1068 \item color/brightness of the seed point in the case of fixed range.
1071 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.
1073 See also: \cvCppCross{findContours}
1077 Inpaints the selected region in the image.
1079 \cvdefCpp{void inpaint( const Mat\& src, const Mat\& inpaintMask,\par
1080 Mat\& dst, double inpaintRadius, int flags );}
1083 \cvarg{src}{The input 8-bit 1-channel or 3-channel image.}
1084 \cvarg{inpaintMask}{The inpainting mask, 8-bit 1-channel image. Non-zero pixels indicate the area that needs to be inpainted.}
1085 \cvarg{dst}{The output image; will have the same size and the same type as \texttt{src}}
1086 \cvarg{inpaintRadius}{The radius of a circlular neighborhood of each point inpainted that is considered by the algorithm.}
1087 \cvarg{flags}{The inpainting method, one of the following:
1089 \cvarg{INPAINT\_NS}{Navier-Stokes based method.}
1090 \cvarg{INPAINT\_TELEA}{The method by Alexandru Telea \cite{Telea04}}
1094 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.
1097 \cvCppFunc{integral}
1098 Calculates the integral of an image.
1100 \cvdefCpp{void integral( const Mat\& image, Mat\& sum, int sdepth=-1 );\newline
1101 void integral( const Mat\& image, Mat\& sum, Mat\& sqsum, int sdepth=-1 );\newline
1102 void integral( const Mat\& image, Mat\& sum, \par Mat\& sqsum, Mat\& tilted, int sdepth=-1 );}
1104 \cvarg{image}{The source image, $W \times H$, 8-bit or floating-point (32f or 64f)}
1105 \cvarg{sum}{The integral image, $(W+1)\times (H+1)$, 32-bit integer or floating-point (32f or 64f)}
1106 \cvarg{sqsum}{The integral image for squared pixel values, $(W+1)\times (H+1)$, double precision floating-point (64f)}
1107 \cvarg{tilted}{The integral for the image rotated by 45 degrees, $(W+1)\times (H+1)$, the same data type as \texttt{sum}}
1108 \cvarg{sdepth}{The desired depth of the integral and the tilted integral images, \texttt{CV\_32S}, \texttt{CV\_32F} or \texttt{CV\_64F}}
1111 The functions \texttt{integral} calculate one or more integral images for the source image as following:
1114 \texttt{sum}(X,Y) = \sum_{x<X,y<Y} \texttt{image}(x,y)
1118 \texttt{sqsum}(X,Y) = \sum_{x<X,y<Y} \texttt{image}(x,y)^2
1122 \texttt{tilted}(X,Y) = \sum_{y<Y,abs(x-X+1)\leq Y-y-1} \texttt{image}(x,y)
1125 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:
1128 \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)
1131 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.
1133 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}.
1135 \begin{center}\includegraphics[width=0.8\textwidth]{pics/integral.png}\end{center}
1137 \cvCppFunc{threshold}
1138 Applies a fixed-level threshold to each array element
1140 \cvdefCpp{double threshold( const Mat\& src, Mat\& dst, double thresh,\par
1141 double maxVal, int thresholdType );}
1143 \cvarg{src}{Source array (single-channel, 8-bit of 32-bit floating point)}
1144 \cvarg{dst}{Destination array; will have the same size and the same type as \texttt{src}}
1145 \cvarg{thresh}{Threshold value}
1146 \cvarg{maxVal}{Maximum value to use with \texttt{THRESH\_BINARY} and \texttt{THRESH\_BINARY\_INV} thresholding types}
1147 \cvarg{thresholdType}{Thresholding type (see the discussion)}
1150 The function applies fixed-level thresholding
1151 to a single-channel array. The function is typically used to get a
1152 bi-level (binary) image out of a grayscale image (\cvCppCross{compare} could
1153 be also used for this purpose) or for removing a noise, i.e. filtering
1154 out pixels with too small or too large values. There are several
1155 types of thresholding that the function supports that are determined by
1156 \texttt{thresholdType}:
1159 \cvarg{THRESH\_BINARY}{\[ \texttt{dst}(x,y) = \fork{\texttt{maxVal}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise} \]}
1160 \cvarg{THRESH\_BINARY\_INV}{\[ \texttt{dst}(x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{maxVal}}{otherwise} \]}
1161 \cvarg{THRESH\_TRUNC}{\[ \texttt{dst}(x,y) = \fork{\texttt{threshold}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise} \]}
1162 \cvarg{THRESH\_TOZERO}{\[ \texttt{dst}(x,y) = \fork{\texttt{src}(x,y)}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise} \]}
1163 \cvarg{THRESH\_TOZERO\_INV}{\[ \texttt{dst}(x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise} \]}
1166 Also, the special value \texttt{THRESH\_OTSU} may be combined with
1167 one of the above values. In this case the function determines the optimal threshold
1168 value using Otsu's algorithm and uses it instead of the specified \texttt{thresh}.
1169 The function returns the computed threshold value.
1170 Currently, Otsu's method is implemented only for 8-bit images.
1172 \includegraphics[width=0.5\textwidth]{pics/threshold.png}
1174 See also: \cvCppCross{adaptiveThreshold}, \cvCppCross{findContours}, \cvCppCross{compare}, \cvCppCross{min}, \cvCppCross{max}
1176 \cvCppFunc{watershed}
1177 Does marker-based image segmentation using watershed algrorithm
1179 \cvdefCpp{void watershed( const Mat\& image, Mat\& markers );}
1181 \cvarg{image}{The input 8-bit 3-channel image.}
1182 \cvarg{markers}{The input/output 32-bit single-channel image (map) of markers. It should have the same size as \texttt{image}}
1185 The function implements one of the variants
1186 of watershed, non-parametric marker-based segmentation algorithm,
1187 described in \cite{Meyer92}. Before passing the image to the
1188 function, user has to outline roughly the desired regions in the image
1189 \texttt{markers} with positive ($>0$) indices, i.e. every region is
1190 represented as one or more connected components with the pixel values
1191 1, 2, 3 etc (such markers can be retrieved from a binary mask
1192 using \cvCppCross{findContours}and \cvCppCross{drawContours}, see \texttt{watershed.cpp} demo).
1193 The markers will be "seeds" of the future image
1194 regions. All the other pixels in \texttt{markers}, which relation to the
1195 outlined regions is not known and should be defined by the algorithm,
1196 should be set to 0's. On the output of the function, each pixel in
1197 markers is set to one of values of the "seed" components, or to -1 at
1198 boundaries between the regions.
1200 Note, that it is not necessary that every two neighbor connected
1201 components are separated by a watershed boundary (-1's pixels), for
1202 example, in case when such tangent components exist in the initial
1203 marker image. Visual demonstration and usage example of the function
1204 can be found in OpenCV samples directory; see \texttt{watershed.cpp} demo.
1206 See also: \cvCppCross{findContours}