1 /*M///////////////////////////////////////////////////////////////////////////////////////
3 // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
5 // By downloading, copying, installing or using the software you agree to this license.
6 // If you do not agree to this license, do not download, install,
7 // copy or use the software.
11 // For Open Source Computer Vision Library
13 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
14 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
15 // Third party copyrights are property of their respective owners.
17 // Redistribution and use in source and binary forms, with or without modification,
18 // are permitted provided that the following conditions are met:
20 // * Redistribution's of source code must retain the above copyright notice,
21 // this list of conditions and the following disclaimer.
23 // * Redistribution's in binary form must reproduce the above copyright notice,
24 // this list of conditions and the following disclaimer in the documentation
25 // and/or other materials provided with the distribution.
27 // * The name of the copyright holders may not be used to endorse or promote products
28 // derived from this software without specific prior written permission.
30 // This software is provided by the copyright holders and contributors "as is" and
31 // any express or implied warranties, including, but not limited to, the implied
32 // warranties of merchantability and fitness for a particular purpose are disclaimed.
33 // In no event shall the Intel Corporation or contributors be liable for any direct,
34 // indirect, incidental, special, exemplary, or consequential damages
35 // (including, but not limited to, procurement of substitute goods or services;
36 // loss of use, data, or profits; or business interruption) however caused
37 // and on any theory of liability, whether in contract, strict liability,
38 // or tort (including negligence or otherwise) arising in any way out of
39 // the use of this software, even if advised of the possibility of such damage.
43 #ifndef OPENCV_IMGPROC_HPP
44 #define OPENCV_IMGPROC_HPP
46 #include "opencv2/core.hpp"
49 @defgroup imgproc Image processing
51 @defgroup imgproc_filter Image Filtering
53 Functions and classes described in this section are used to perform various linear or non-linear
54 filtering operations on 2D images (represented as Mat's). It means that for each pixel location
55 \f$(x,y)\f$ in the source image (normally, rectangular), its neighborhood is considered and used to
56 compute the response. In case of a linear filter, it is a weighted sum of pixel values. In case of
57 morphological operations, it is the minimum or maximum values, and so on. The computed response is
58 stored in the destination image at the same location \f$(x,y)\f$. It means that the output image
59 will be of the same size as the input image. Normally, the functions support multi-channel arrays,
60 in which case every channel is processed independently. Therefore, the output image will also have
61 the same number of channels as the input one.
63 Another common feature of the functions and classes described in this section is that, unlike
64 simple arithmetic functions, they need to extrapolate values of some non-existing pixels. For
65 example, if you want to smooth an image using a Gaussian \f$3 \times 3\f$ filter, then, when
66 processing the left-most pixels in each row, you need pixels to the left of them, that is, outside
67 of the image. You can let these pixels be the same as the left-most image pixels ("replicated
68 border" extrapolation method), or assume that all the non-existing pixels are zeros ("constant
69 border" extrapolation method), and so on. OpenCV enables you to specify the extrapolation method.
70 For details, see cv::BorderTypes
73 ### Depth combinations
74 Input depth (src.depth()) | Output depth (ddepth)
75 --------------------------|----------------------
76 CV_8U | -1/CV_16S/CV_32F/CV_64F
77 CV_16U/CV_16S | -1/CV_32F/CV_64F
78 CV_32F | -1/CV_32F/CV_64F
81 @note when ddepth=-1, the output image will have the same depth as the source.
83 @defgroup imgproc_transform Geometric Image Transformations
85 The functions in this section perform various geometrical transformations of 2D images. They do not
86 change the image content but deform the pixel grid and map this deformed grid to the destination
87 image. In fact, to avoid sampling artifacts, the mapping is done in the reverse order, from
88 destination to the source. That is, for each pixel \f$(x, y)\f$ of the destination image, the
89 functions compute coordinates of the corresponding "donor" pixel in the source image and copy the
92 \f[\texttt{dst} (x,y)= \texttt{src} (f_x(x,y), f_y(x,y))\f]
94 In case when you specify the forward mapping \f$\left<g_x, g_y\right>: \texttt{src} \rightarrow
95 \texttt{dst}\f$, the OpenCV functions first compute the corresponding inverse mapping
96 \f$\left<f_x, f_y\right>: \texttt{dst} \rightarrow \texttt{src}\f$ and then use the above formula.
98 The actual implementations of the geometrical transformations, from the most generic remap and to
99 the simplest and the fastest resize, need to solve two main problems with the above formula:
101 - Extrapolation of non-existing pixels. Similarly to the filtering functions described in the
102 previous section, for some \f$(x,y)\f$, either one of \f$f_x(x,y)\f$, or \f$f_y(x,y)\f$, or both
103 of them may fall outside of the image. In this case, an extrapolation method needs to be used.
104 OpenCV provides the same selection of extrapolation methods as in the filtering functions. In
105 addition, it provides the method BORDER_TRANSPARENT. This means that the corresponding pixels in
106 the destination image will not be modified at all.
108 - Interpolation of pixel values. Usually \f$f_x(x,y)\f$ and \f$f_y(x,y)\f$ are floating-point
109 numbers. This means that \f$\left<f_x, f_y\right>\f$ can be either an affine or perspective
110 transformation, or radial lens distortion correction, and so on. So, a pixel value at fractional
111 coordinates needs to be retrieved. In the simplest case, the coordinates can be just rounded to the
112 nearest integer coordinates and the corresponding pixel can be used. This is called a
113 nearest-neighbor interpolation. However, a better result can be achieved by using more
114 sophisticated [interpolation methods](http://en.wikipedia.org/wiki/Multivariate_interpolation) ,
115 where a polynomial function is fit into some neighborhood of the computed pixel \f$(f_x(x,y),
116 f_y(x,y))\f$, and then the value of the polynomial at \f$(f_x(x,y), f_y(x,y))\f$ is taken as the
117 interpolated pixel value. In OpenCV, you can choose between several interpolation methods. See
120 @defgroup imgproc_misc Miscellaneous Image Transformations
121 @defgroup imgproc_draw Drawing Functions
123 Drawing functions work with matrices/images of arbitrary depth. The boundaries of the shapes can be
124 rendered with antialiasing (implemented only for 8-bit images for now). All the functions include
125 the parameter color that uses an RGB value (that may be constructed with the Scalar constructor )
126 for color images and brightness for grayscale images. For color images, the channel ordering is
127 normally *Blue, Green, Red*. This is what imshow, imread, and imwrite expect. So, if you form a
128 color using the Scalar constructor, it should look like:
130 \f[\texttt{Scalar} (blue \_ component, green \_ component, red \_ component[, alpha \_ component])\f]
132 If you are using your own image rendering and I/O functions, you can use any channel ordering. The
133 drawing functions process each channel independently and do not depend on the channel order or even
134 on the used color space. The whole image can be converted from BGR to RGB or to a different color
135 space using cvtColor .
137 If a drawn figure is partially or completely outside the image, the drawing functions clip it. Also,
138 many drawing functions can handle pixel coordinates specified with sub-pixel accuracy. This means
139 that the coordinates can be passed as fixed-point numbers encoded as integers. The number of
140 fractional bits is specified by the shift parameter and the real point coordinates are calculated as
141 \f$\texttt{Point}(x,y)\rightarrow\texttt{Point2f}(x*2^{-shift},y*2^{-shift})\f$ . This feature is
142 especially effective when rendering antialiased shapes.
144 @note The functions do not support alpha-transparency when the target image is 4-channel. In this
145 case, the color[3] is simply copied to the repainted pixels. Thus, if you want to paint
146 semi-transparent shapes, you can paint them in a separate buffer and then blend it with the main
149 @defgroup imgproc_colormap ColorMaps in OpenCV
151 The human perception isn't built for observing fine changes in grayscale images. Human eyes are more
152 sensitive to observing changes between colors, so you often need to recolor your grayscale images to
153 get a clue about them. OpenCV now comes with various colormaps to enhance the visualization in your
154 computer vision application.
156 In OpenCV you only need applyColorMap to apply a colormap on a given image. The following sample
157 code reads the path to an image from command line, applies a Jet colormap on it and shows the
161 #include <opencv2/core.hpp>
162 #include <opencv2/imgproc.hpp>
163 #include <opencv2/imgcodecs.hpp>
164 #include <opencv2/highgui.hpp>
170 int main(int argc, const char *argv[])
172 // We need an input image. (can be grayscale or color)
175 cerr << "We need an image to process here. Please run: colorMap [path_to_image]" << endl;
178 Mat img_in = imread(argv[1]);
181 cerr << "Sample image (" << argv[1] << ") is empty. Please adjust your path, so it points to a valid input image!" << endl;
184 // Holds the colormap version of the image:
186 // Apply the colormap:
187 applyColorMap(img_in, img_color, COLORMAP_JET);
189 imshow("colorMap", img_color);
195 @see cv::ColormapTypes
197 @defgroup imgproc_subdiv2d Planar Subdivision
199 The Subdiv2D class described in this section is used to perform various planar subdivision on
200 a set of 2D points (represented as vector of Point2f). OpenCV subdivides a plane into triangles
201 using the Delaunay’s algorithm, which corresponds to the dual graph of the Voronoi diagram.
202 In the figure below, the Delaunay’s triangulation is marked with black lines and the Voronoi
203 diagram with red lines.
205 ![Delaunay triangulation (black) and Voronoi (red)](pics/delaunay_voronoi.png)
207 The subdivisions can be used for the 3D piece-wise transformation of a plane, morphing, fast
208 location of points on the plane, building special graphs (such as NNG,RNG), and so forth.
210 @defgroup imgproc_hist Histograms
211 @defgroup imgproc_shape Structural Analysis and Shape Descriptors
212 @defgroup imgproc_motion Motion Analysis and Object Tracking
213 @defgroup imgproc_feature Feature Detection
214 @defgroup imgproc_object Object Detection
215 @defgroup imgproc_c C API
216 @defgroup imgproc_hal Hardware Acceleration Layer
218 @defgroup imgproc_hal_functions Functions
219 @defgroup imgproc_hal_interface Interface
227 /** @addtogroup imgproc
231 //! @addtogroup imgproc_filter
234 //! type of morphological operation
236 MORPH_ERODE = 0, //!< see cv::erode
237 MORPH_DILATE = 1, //!< see cv::dilate
238 MORPH_OPEN = 2, //!< an opening operation
239 //!< \f[\texttt{dst} = \mathrm{open} ( \texttt{src} , \texttt{element} )= \mathrm{dilate} ( \mathrm{erode} ( \texttt{src} , \texttt{element} ))\f]
240 MORPH_CLOSE = 3, //!< a closing operation
241 //!< \f[\texttt{dst} = \mathrm{close} ( \texttt{src} , \texttt{element} )= \mathrm{erode} ( \mathrm{dilate} ( \texttt{src} , \texttt{element} ))\f]
242 MORPH_GRADIENT = 4, //!< a morphological gradient
243 //!< \f[\texttt{dst} = \mathrm{morph\_grad} ( \texttt{src} , \texttt{element} )= \mathrm{dilate} ( \texttt{src} , \texttt{element} )- \mathrm{erode} ( \texttt{src} , \texttt{element} )\f]
244 MORPH_TOPHAT = 5, //!< "top hat"
245 //!< \f[\texttt{dst} = \mathrm{tophat} ( \texttt{src} , \texttt{element} )= \texttt{src} - \mathrm{open} ( \texttt{src} , \texttt{element} )\f]
246 MORPH_BLACKHAT = 6, //!< "black hat"
247 //!< \f[\texttt{dst} = \mathrm{blackhat} ( \texttt{src} , \texttt{element} )= \mathrm{close} ( \texttt{src} , \texttt{element} )- \texttt{src}\f]
248 MORPH_HITMISS = 7 //!< "hit or miss"
249 //!< .- Only supported for CV_8UC1 binary images. A tutorial can be found in the documentation
252 //! shape of the structuring element
254 MORPH_RECT = 0, //!< a rectangular structuring element: \f[E_{ij}=1\f]
255 MORPH_CROSS = 1, //!< a cross-shaped structuring element:
256 //!< \f[E_{ij} = \fork{1}{if i=\texttt{anchor.y} or j=\texttt{anchor.x}}{0}{otherwise}\f]
257 MORPH_ELLIPSE = 2 //!< an elliptic structuring element, that is, a filled ellipse inscribed
258 //!< into the rectangle Rect(0, 0, esize.width, 0.esize.height)
261 //! @} imgproc_filter
263 //! @addtogroup imgproc_transform
266 //! interpolation algorithm
267 enum InterpolationFlags{
268 /** nearest neighbor interpolation */
270 /** bilinear interpolation */
272 /** bicubic interpolation */
274 /** resampling using pixel area relation. It may be a preferred method for image decimation, as
275 it gives moire'-free results. But when the image is zoomed, it is similar to the INTER_NEAREST
278 /** Lanczos interpolation over 8x8 neighborhood */
280 /** mask for interpolation codes */
282 /** flag, fills all of the destination image pixels. If some of them correspond to outliers in the
283 source image, they are set to zero */
284 WARP_FILL_OUTLIERS = 8,
285 /** flag, inverse transformation
287 For example, @ref cv::linearPolar or @ref cv::logPolar transforms:
288 - flag is __not__ set: \f$dst( \rho , \phi ) = src(x,y)\f$
289 - flag is set: \f$dst(x,y) = src( \rho , \phi )\f$
291 WARP_INVERSE_MAP = 16
294 enum InterpolationMasks {
296 INTER_BITS2 = INTER_BITS * 2,
297 INTER_TAB_SIZE = 1 << INTER_BITS,
298 INTER_TAB_SIZE2 = INTER_TAB_SIZE * INTER_TAB_SIZE
301 //! @} imgproc_transform
303 //! @addtogroup imgproc_misc
306 //! Distance types for Distance Transform and M-estimators
307 //! @see cv::distanceTransform, cv::fitLine
309 DIST_USER = -1, //!< User defined distance
310 DIST_L1 = 1, //!< distance = |x1-x2| + |y1-y2|
311 DIST_L2 = 2, //!< the simple euclidean distance
312 DIST_C = 3, //!< distance = max(|x1-x2|,|y1-y2|)
313 DIST_L12 = 4, //!< L1-L2 metric: distance = 2(sqrt(1+x*x/2) - 1))
314 DIST_FAIR = 5, //!< distance = c^2(|x|/c-log(1+|x|/c)), c = 1.3998
315 DIST_WELSCH = 6, //!< distance = c^2/2(1-exp(-(x/c)^2)), c = 2.9846
316 DIST_HUBER = 7 //!< distance = |x|<c ? x^2/2 : c(|x|-c/2), c=1.345
319 //! Mask size for distance transform
320 enum DistanceTransformMasks {
321 DIST_MASK_3 = 3, //!< mask=3
322 DIST_MASK_5 = 5, //!< mask=5
323 DIST_MASK_PRECISE = 0 //!<
326 //! type of the threshold operation
327 //! ![threshold types](pics/threshold.png)
328 enum ThresholdTypes {
329 THRESH_BINARY = 0, //!< \f[\texttt{dst} (x,y) = \fork{\texttt{maxval}}{if \(\texttt{src}(x,y) > \texttt{thresh}\)}{0}{otherwise}\f]
330 THRESH_BINARY_INV = 1, //!< \f[\texttt{dst} (x,y) = \fork{0}{if \(\texttt{src}(x,y) > \texttt{thresh}\)}{\texttt{maxval}}{otherwise}\f]
331 THRESH_TRUNC = 2, //!< \f[\texttt{dst} (x,y) = \fork{\texttt{threshold}}{if \(\texttt{src}(x,y) > \texttt{thresh}\)}{\texttt{src}(x,y)}{otherwise}\f]
332 THRESH_TOZERO = 3, //!< \f[\texttt{dst} (x,y) = \fork{\texttt{src}(x,y)}{if \(\texttt{src}(x,y) > \texttt{thresh}\)}{0}{otherwise}\f]
333 THRESH_TOZERO_INV = 4, //!< \f[\texttt{dst} (x,y) = \fork{0}{if \(\texttt{src}(x,y) > \texttt{thresh}\)}{\texttt{src}(x,y)}{otherwise}\f]
335 THRESH_OTSU = 8, //!< flag, use Otsu algorithm to choose the optimal threshold value
336 THRESH_TRIANGLE = 16 //!< flag, use Triangle algorithm to choose the optimal threshold value
339 //! adaptive threshold algorithm
340 //! see cv::adaptiveThreshold
341 enum AdaptiveThresholdTypes {
342 /** the threshold value \f$T(x,y)\f$ is a mean of the \f$\texttt{blockSize} \times
343 \texttt{blockSize}\f$ neighborhood of \f$(x, y)\f$ minus C */
344 ADAPTIVE_THRESH_MEAN_C = 0,
345 /** the threshold value \f$T(x, y)\f$ is a weighted sum (cross-correlation with a Gaussian
346 window) of the \f$\texttt{blockSize} \times \texttt{blockSize}\f$ neighborhood of \f$(x, y)\f$
347 minus C . The default sigma (standard deviation) is used for the specified blockSize . See
348 cv::getGaussianKernel*/
349 ADAPTIVE_THRESH_GAUSSIAN_C = 1
352 //! cv::undistort mode
353 enum UndistortTypes {
354 PROJ_SPHERICAL_ORTHO = 0,
355 PROJ_SPHERICAL_EQRECT = 1
358 //! class of the pixel in GrabCut algorithm
359 enum GrabCutClasses {
360 GC_BGD = 0, //!< an obvious background pixels
361 GC_FGD = 1, //!< an obvious foreground (object) pixel
362 GC_PR_BGD = 2, //!< a possible background pixel
363 GC_PR_FGD = 3 //!< a possible foreground pixel
366 //! GrabCut algorithm flags
368 /** The function initializes the state and the mask using the provided rectangle. After that it
369 runs iterCount iterations of the algorithm. */
370 GC_INIT_WITH_RECT = 0,
371 /** The function initializes the state using the provided mask. Note that GC_INIT_WITH_RECT
372 and GC_INIT_WITH_MASK can be combined. Then, all the pixels outside of the ROI are
373 automatically initialized with GC_BGD .*/
374 GC_INIT_WITH_MASK = 1,
375 /** The value means that the algorithm should just resume. */
379 //! distanceTransform algorithm flags
380 enum DistanceTransformLabelTypes {
381 /** each connected component of zeros in src (as well as all the non-zero pixels closest to the
382 connected component) will be assigned the same label */
383 DIST_LABEL_CCOMP = 0,
384 /** each zero pixel (and all the non-zero pixels closest to it) gets its own label. */
388 //! floodfill algorithm flags
389 enum FloodFillFlags {
390 /** If set, the difference between the current pixel and seed pixel is considered. Otherwise,
391 the difference between neighbor pixels is considered (that is, the range is floating). */
392 FLOODFILL_FIXED_RANGE = 1 << 16,
393 /** If set, the function does not change the image ( newVal is ignored), and only fills the
394 mask with the value specified in bits 8-16 of flags as described above. This option only make
395 sense in function variants that have the mask parameter. */
396 FLOODFILL_MASK_ONLY = 1 << 17
401 //! @addtogroup imgproc_shape
404 //! connected components algorithm output formats
405 enum ConnectedComponentsTypes {
406 CC_STAT_LEFT = 0, //!< The leftmost (x) coordinate which is the inclusive start of the bounding
407 //!< box in the horizontal direction.
408 CC_STAT_TOP = 1, //!< The topmost (y) coordinate which is the inclusive start of the bounding
409 //!< box in the vertical direction.
410 CC_STAT_WIDTH = 2, //!< The horizontal size of the bounding box
411 CC_STAT_HEIGHT = 3, //!< The vertical size of the bounding box
412 CC_STAT_AREA = 4, //!< The total area (in pixels) of the connected component
416 //! connected components algorithm
417 enum ConnectedComponentsAlgorithmsTypes {
418 CCL_WU = 0, //!< SAUF algorithm for 8-way connectivity, SAUF algorithm for 4-way connectivity
419 CCL_DEFAULT = -1, //!< BBDT algorithm for 8-way connectivity, SAUF algorithm for 4-way connectivity
420 CCL_GRANA = 1 //!< BBDT algorithm for 8-way connectivity, SAUF algorithm for 4-way connectivity
423 //! mode of the contour retrieval algorithm
424 enum RetrievalModes {
425 /** retrieves only the extreme outer contours. It sets `hierarchy[i][2]=hierarchy[i][3]=-1` for
428 /** retrieves all of the contours without establishing any hierarchical relationships. */
430 /** retrieves all of the contours and organizes them into a two-level hierarchy. At the top
431 level, there are external boundaries of the components. At the second level, there are
432 boundaries of the holes. If there is another contour inside a hole of a connected component, it
433 is still put at the top level. */
435 /** retrieves all of the contours and reconstructs a full hierarchy of nested contours.*/
437 RETR_FLOODFILL = 4 //!<
440 //! the contour approximation algorithm
441 enum ContourApproximationModes {
442 /** stores absolutely all the contour points. That is, any 2 subsequent points (x1,y1) and
443 (x2,y2) of the contour will be either horizontal, vertical or diagonal neighbors, that is,
444 max(abs(x1-x2),abs(y2-y1))==1. */
445 CHAIN_APPROX_NONE = 1,
446 /** compresses horizontal, vertical, and diagonal segments and leaves only their end points.
447 For example, an up-right rectangular contour is encoded with 4 points. */
448 CHAIN_APPROX_SIMPLE = 2,
449 /** applies one of the flavors of the Teh-Chin chain approximation algorithm @cite TehChin89 */
450 CHAIN_APPROX_TC89_L1 = 3,
451 /** applies one of the flavors of the Teh-Chin chain approximation algorithm @cite TehChin89 */
452 CHAIN_APPROX_TC89_KCOS = 4
455 /** @brief Shape matching methods
457 \f$A\f$ denotes object1,\f$B\f$ denotes object2
459 \f$\begin{array}{l} m^A_i = \mathrm{sign} (h^A_i) \cdot \log{h^A_i} \\ m^B_i = \mathrm{sign} (h^B_i) \cdot \log{h^B_i} \end{array}\f$
461 and \f$h^A_i, h^B_i\f$ are the Hu moments of \f$A\f$ and \f$B\f$ , respectively.
463 enum ShapeMatchModes {
464 CONTOURS_MATCH_I1 =1, //!< \f[I_1(A,B) = \sum _{i=1...7} \left | \frac{1}{m^A_i} - \frac{1}{m^B_i} \right |\f]
465 CONTOURS_MATCH_I2 =2, //!< \f[I_2(A,B) = \sum _{i=1...7} \left | m^A_i - m^B_i \right |\f]
466 CONTOURS_MATCH_I3 =3 //!< \f[I_3(A,B) = \max _{i=1...7} \frac{ \left| m^A_i - m^B_i \right| }{ \left| m^A_i \right| }\f]
471 //! Variants of a Hough transform
474 /** classical or standard Hough transform. Every line is represented by two floating-point
475 numbers \f$(\rho, \theta)\f$ , where \f$\rho\f$ is a distance between (0,0) point and the line,
476 and \f$\theta\f$ is the angle between x-axis and the normal to the line. Thus, the matrix must
477 be (the created sequence will be) of CV_32FC2 type */
479 /** probabilistic Hough transform (more efficient in case if the picture contains a few long
480 linear segments). It returns line segments rather than the whole line. Each segment is
481 represented by starting and ending points, and the matrix must be (the created sequence will
482 be) of the CV_32SC4 type. */
483 HOUGH_PROBABILISTIC = 1,
484 /** multi-scale variant of the classical Hough transform. The lines are encoded the same way as
486 HOUGH_MULTI_SCALE = 2,
487 HOUGH_GRADIENT = 3 //!< basically *21HT*, described in @cite Yuen90
490 //! Variants of Line Segment %Detector
491 //! @ingroup imgproc_feature
492 enum LineSegmentDetectorModes {
493 LSD_REFINE_NONE = 0, //!< No refinement applied
494 LSD_REFINE_STD = 1, //!< Standard refinement is applied. E.g. breaking arches into smaller straighter line approximations.
495 LSD_REFINE_ADV = 2 //!< Advanced refinement. Number of false alarms is calculated, lines are
496 //!< refined through increase of precision, decrement in size, etc.
499 /** Histogram comparison methods
500 @ingroup imgproc_hist
502 enum HistCompMethods {
504 \f[d(H_1,H_2) = \frac{\sum_I (H_1(I) - \bar{H_1}) (H_2(I) - \bar{H_2})}{\sqrt{\sum_I(H_1(I) - \bar{H_1})^2 \sum_I(H_2(I) - \bar{H_2})^2}}\f]
506 \f[\bar{H_k} = \frac{1}{N} \sum _J H_k(J)\f]
507 and \f$N\f$ is a total number of histogram bins. */
510 \f[d(H_1,H_2) = \sum _I \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)}\f] */
513 \f[d(H_1,H_2) = \sum _I \min (H_1(I), H_2(I))\f] */
514 HISTCMP_INTERSECT = 2,
515 /** Bhattacharyya distance
516 (In fact, OpenCV computes Hellinger distance, which is related to Bhattacharyya coefficient.)
517 \f[d(H_1,H_2) = \sqrt{1 - \frac{1}{\sqrt{\bar{H_1} \bar{H_2} N^2}} \sum_I \sqrt{H_1(I) \cdot H_2(I)}}\f] */
518 HISTCMP_BHATTACHARYYA = 3,
519 HISTCMP_HELLINGER = HISTCMP_BHATTACHARYYA, //!< Synonym for HISTCMP_BHATTACHARYYA
520 /** Alternative Chi-Square
521 \f[d(H_1,H_2) = 2 * \sum _I \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)+H_2(I)}\f]
522 This alternative formula is regularly used for texture comparison. See e.g. @cite Puzicha1997 */
523 HISTCMP_CHISQR_ALT = 4,
524 /** Kullback-Leibler divergence
525 \f[d(H_1,H_2) = \sum _I H_1(I) \log \left(\frac{H_1(I)}{H_2(I)}\right)\f] */
529 /** the color conversion code
530 @see @ref imgproc_color_conversions
531 @ingroup imgproc_misc
533 enum ColorConversionCodes {
534 COLOR_BGR2BGRA = 0, //!< add alpha channel to RGB or BGR image
535 COLOR_RGB2RGBA = COLOR_BGR2BGRA,
537 COLOR_BGRA2BGR = 1, //!< remove alpha channel from RGB or BGR image
538 COLOR_RGBA2RGB = COLOR_BGRA2BGR,
540 COLOR_BGR2RGBA = 2, //!< convert between RGB and BGR color spaces (with or without alpha channel)
541 COLOR_RGB2BGRA = COLOR_BGR2RGBA,
544 COLOR_BGRA2RGB = COLOR_RGBA2BGR,
547 COLOR_RGB2BGR = COLOR_BGR2RGB,
550 COLOR_RGBA2BGRA = COLOR_BGRA2RGBA,
552 COLOR_BGR2GRAY = 6, //!< convert between RGB/BGR and grayscale, @ref color_convert_rgb_gray "color conversions"
555 COLOR_GRAY2RGB = COLOR_GRAY2BGR,
557 COLOR_GRAY2RGBA = COLOR_GRAY2BGRA,
558 COLOR_BGRA2GRAY = 10,
559 COLOR_RGBA2GRAY = 11,
561 COLOR_BGR2BGR565 = 12, //!< convert between RGB/BGR and BGR565 (16-bit images)
562 COLOR_RGB2BGR565 = 13,
563 COLOR_BGR5652BGR = 14,
564 COLOR_BGR5652RGB = 15,
565 COLOR_BGRA2BGR565 = 16,
566 COLOR_RGBA2BGR565 = 17,
567 COLOR_BGR5652BGRA = 18,
568 COLOR_BGR5652RGBA = 19,
570 COLOR_GRAY2BGR565 = 20, //!< convert between grayscale to BGR565 (16-bit images)
571 COLOR_BGR5652GRAY = 21,
573 COLOR_BGR2BGR555 = 22, //!< convert between RGB/BGR and BGR555 (16-bit images)
574 COLOR_RGB2BGR555 = 23,
575 COLOR_BGR5552BGR = 24,
576 COLOR_BGR5552RGB = 25,
577 COLOR_BGRA2BGR555 = 26,
578 COLOR_RGBA2BGR555 = 27,
579 COLOR_BGR5552BGRA = 28,
580 COLOR_BGR5552RGBA = 29,
582 COLOR_GRAY2BGR555 = 30, //!< convert between grayscale and BGR555 (16-bit images)
583 COLOR_BGR5552GRAY = 31,
585 COLOR_BGR2XYZ = 32, //!< convert RGB/BGR to CIE XYZ, @ref color_convert_rgb_xyz "color conversions"
590 COLOR_BGR2YCrCb = 36, //!< convert RGB/BGR to luma-chroma (aka YCC), @ref color_convert_rgb_ycrcb "color conversions"
591 COLOR_RGB2YCrCb = 37,
592 COLOR_YCrCb2BGR = 38,
593 COLOR_YCrCb2RGB = 39,
595 COLOR_BGR2HSV = 40, //!< convert RGB/BGR to HSV (hue saturation value), @ref color_convert_rgb_hsv "color conversions"
598 COLOR_BGR2Lab = 44, //!< convert RGB/BGR to CIE Lab, @ref color_convert_rgb_lab "color conversions"
601 COLOR_BGR2Luv = 50, //!< convert RGB/BGR to CIE Luv, @ref color_convert_rgb_luv "color conversions"
603 COLOR_BGR2HLS = 52, //!< convert RGB/BGR to HLS (hue lightness saturation), @ref color_convert_rgb_hls "color conversions"
606 COLOR_HSV2BGR = 54, //!< backward conversions to RGB/BGR
616 COLOR_BGR2HSV_FULL = 66, //!<
617 COLOR_RGB2HSV_FULL = 67,
618 COLOR_BGR2HLS_FULL = 68,
619 COLOR_RGB2HLS_FULL = 69,
621 COLOR_HSV2BGR_FULL = 70,
622 COLOR_HSV2RGB_FULL = 71,
623 COLOR_HLS2BGR_FULL = 72,
624 COLOR_HLS2RGB_FULL = 73,
636 COLOR_BGR2YUV = 82, //!< convert between RGB/BGR and YUV
641 //! YUV 4:2:0 family to RGB
642 COLOR_YUV2RGB_NV12 = 90,
643 COLOR_YUV2BGR_NV12 = 91,
644 COLOR_YUV2RGB_NV21 = 92,
645 COLOR_YUV2BGR_NV21 = 93,
646 COLOR_YUV420sp2RGB = COLOR_YUV2RGB_NV21,
647 COLOR_YUV420sp2BGR = COLOR_YUV2BGR_NV21,
649 COLOR_YUV2RGBA_NV12 = 94,
650 COLOR_YUV2BGRA_NV12 = 95,
651 COLOR_YUV2RGBA_NV21 = 96,
652 COLOR_YUV2BGRA_NV21 = 97,
653 COLOR_YUV420sp2RGBA = COLOR_YUV2RGBA_NV21,
654 COLOR_YUV420sp2BGRA = COLOR_YUV2BGRA_NV21,
656 COLOR_YUV2RGB_YV12 = 98,
657 COLOR_YUV2BGR_YV12 = 99,
658 COLOR_YUV2RGB_IYUV = 100,
659 COLOR_YUV2BGR_IYUV = 101,
660 COLOR_YUV2RGB_I420 = COLOR_YUV2RGB_IYUV,
661 COLOR_YUV2BGR_I420 = COLOR_YUV2BGR_IYUV,
662 COLOR_YUV420p2RGB = COLOR_YUV2RGB_YV12,
663 COLOR_YUV420p2BGR = COLOR_YUV2BGR_YV12,
665 COLOR_YUV2RGBA_YV12 = 102,
666 COLOR_YUV2BGRA_YV12 = 103,
667 COLOR_YUV2RGBA_IYUV = 104,
668 COLOR_YUV2BGRA_IYUV = 105,
669 COLOR_YUV2RGBA_I420 = COLOR_YUV2RGBA_IYUV,
670 COLOR_YUV2BGRA_I420 = COLOR_YUV2BGRA_IYUV,
671 COLOR_YUV420p2RGBA = COLOR_YUV2RGBA_YV12,
672 COLOR_YUV420p2BGRA = COLOR_YUV2BGRA_YV12,
674 COLOR_YUV2GRAY_420 = 106,
675 COLOR_YUV2GRAY_NV21 = COLOR_YUV2GRAY_420,
676 COLOR_YUV2GRAY_NV12 = COLOR_YUV2GRAY_420,
677 COLOR_YUV2GRAY_YV12 = COLOR_YUV2GRAY_420,
678 COLOR_YUV2GRAY_IYUV = COLOR_YUV2GRAY_420,
679 COLOR_YUV2GRAY_I420 = COLOR_YUV2GRAY_420,
680 COLOR_YUV420sp2GRAY = COLOR_YUV2GRAY_420,
681 COLOR_YUV420p2GRAY = COLOR_YUV2GRAY_420,
683 //! YUV 4:2:2 family to RGB
684 COLOR_YUV2RGB_UYVY = 107,
685 COLOR_YUV2BGR_UYVY = 108,
686 //COLOR_YUV2RGB_VYUY = 109,
687 //COLOR_YUV2BGR_VYUY = 110,
688 COLOR_YUV2RGB_Y422 = COLOR_YUV2RGB_UYVY,
689 COLOR_YUV2BGR_Y422 = COLOR_YUV2BGR_UYVY,
690 COLOR_YUV2RGB_UYNV = COLOR_YUV2RGB_UYVY,
691 COLOR_YUV2BGR_UYNV = COLOR_YUV2BGR_UYVY,
693 COLOR_YUV2RGBA_UYVY = 111,
694 COLOR_YUV2BGRA_UYVY = 112,
695 //COLOR_YUV2RGBA_VYUY = 113,
696 //COLOR_YUV2BGRA_VYUY = 114,
697 COLOR_YUV2RGBA_Y422 = COLOR_YUV2RGBA_UYVY,
698 COLOR_YUV2BGRA_Y422 = COLOR_YUV2BGRA_UYVY,
699 COLOR_YUV2RGBA_UYNV = COLOR_YUV2RGBA_UYVY,
700 COLOR_YUV2BGRA_UYNV = COLOR_YUV2BGRA_UYVY,
702 COLOR_YUV2RGB_YUY2 = 115,
703 COLOR_YUV2BGR_YUY2 = 116,
704 COLOR_YUV2RGB_YVYU = 117,
705 COLOR_YUV2BGR_YVYU = 118,
706 COLOR_YUV2RGB_YUYV = COLOR_YUV2RGB_YUY2,
707 COLOR_YUV2BGR_YUYV = COLOR_YUV2BGR_YUY2,
708 COLOR_YUV2RGB_YUNV = COLOR_YUV2RGB_YUY2,
709 COLOR_YUV2BGR_YUNV = COLOR_YUV2BGR_YUY2,
711 COLOR_YUV2RGBA_YUY2 = 119,
712 COLOR_YUV2BGRA_YUY2 = 120,
713 COLOR_YUV2RGBA_YVYU = 121,
714 COLOR_YUV2BGRA_YVYU = 122,
715 COLOR_YUV2RGBA_YUYV = COLOR_YUV2RGBA_YUY2,
716 COLOR_YUV2BGRA_YUYV = COLOR_YUV2BGRA_YUY2,
717 COLOR_YUV2RGBA_YUNV = COLOR_YUV2RGBA_YUY2,
718 COLOR_YUV2BGRA_YUNV = COLOR_YUV2BGRA_YUY2,
720 COLOR_YUV2GRAY_UYVY = 123,
721 COLOR_YUV2GRAY_YUY2 = 124,
722 //CV_YUV2GRAY_VYUY = CV_YUV2GRAY_UYVY,
723 COLOR_YUV2GRAY_Y422 = COLOR_YUV2GRAY_UYVY,
724 COLOR_YUV2GRAY_UYNV = COLOR_YUV2GRAY_UYVY,
725 COLOR_YUV2GRAY_YVYU = COLOR_YUV2GRAY_YUY2,
726 COLOR_YUV2GRAY_YUYV = COLOR_YUV2GRAY_YUY2,
727 COLOR_YUV2GRAY_YUNV = COLOR_YUV2GRAY_YUY2,
729 //! alpha premultiplication
730 COLOR_RGBA2mRGBA = 125,
731 COLOR_mRGBA2RGBA = 126,
733 //! RGB to YUV 4:2:0 family
734 COLOR_RGB2YUV_I420 = 127,
735 COLOR_BGR2YUV_I420 = 128,
736 COLOR_RGB2YUV_IYUV = COLOR_RGB2YUV_I420,
737 COLOR_BGR2YUV_IYUV = COLOR_BGR2YUV_I420,
739 COLOR_RGBA2YUV_I420 = 129,
740 COLOR_BGRA2YUV_I420 = 130,
741 COLOR_RGBA2YUV_IYUV = COLOR_RGBA2YUV_I420,
742 COLOR_BGRA2YUV_IYUV = COLOR_BGRA2YUV_I420,
743 COLOR_RGB2YUV_YV12 = 131,
744 COLOR_BGR2YUV_YV12 = 132,
745 COLOR_RGBA2YUV_YV12 = 133,
746 COLOR_BGRA2YUV_YV12 = 134,
749 COLOR_BayerBG2BGR = 46,
750 COLOR_BayerGB2BGR = 47,
751 COLOR_BayerRG2BGR = 48,
752 COLOR_BayerGR2BGR = 49,
754 COLOR_BayerBG2RGB = COLOR_BayerRG2BGR,
755 COLOR_BayerGB2RGB = COLOR_BayerGR2BGR,
756 COLOR_BayerRG2RGB = COLOR_BayerBG2BGR,
757 COLOR_BayerGR2RGB = COLOR_BayerGB2BGR,
759 COLOR_BayerBG2GRAY = 86,
760 COLOR_BayerGB2GRAY = 87,
761 COLOR_BayerRG2GRAY = 88,
762 COLOR_BayerGR2GRAY = 89,
764 //! Demosaicing using Variable Number of Gradients
765 COLOR_BayerBG2BGR_VNG = 62,
766 COLOR_BayerGB2BGR_VNG = 63,
767 COLOR_BayerRG2BGR_VNG = 64,
768 COLOR_BayerGR2BGR_VNG = 65,
770 COLOR_BayerBG2RGB_VNG = COLOR_BayerRG2BGR_VNG,
771 COLOR_BayerGB2RGB_VNG = COLOR_BayerGR2BGR_VNG,
772 COLOR_BayerRG2RGB_VNG = COLOR_BayerBG2BGR_VNG,
773 COLOR_BayerGR2RGB_VNG = COLOR_BayerGB2BGR_VNG,
775 //! Edge-Aware Demosaicing
776 COLOR_BayerBG2BGR_EA = 135,
777 COLOR_BayerGB2BGR_EA = 136,
778 COLOR_BayerRG2BGR_EA = 137,
779 COLOR_BayerGR2BGR_EA = 138,
781 COLOR_BayerBG2RGB_EA = COLOR_BayerRG2BGR_EA,
782 COLOR_BayerGB2RGB_EA = COLOR_BayerGR2BGR_EA,
783 COLOR_BayerRG2RGB_EA = COLOR_BayerBG2BGR_EA,
784 COLOR_BayerGR2RGB_EA = COLOR_BayerGB2BGR_EA,
786 //! Demosaicing with alpha channel
787 COLOR_BayerBG2BGRA = 139,
788 COLOR_BayerGB2BGRA = 140,
789 COLOR_BayerRG2BGRA = 141,
790 COLOR_BayerGR2BGRA = 142,
792 COLOR_BayerBG2RGBA = COLOR_BayerRG2BGRA,
793 COLOR_BayerGB2RGBA = COLOR_BayerGR2BGRA,
794 COLOR_BayerRG2RGBA = COLOR_BayerBG2BGRA,
795 COLOR_BayerGR2RGBA = COLOR_BayerGB2BGRA,
797 COLOR_COLORCVT_MAX = 143
800 /** types of intersection between rectangles
801 @ingroup imgproc_shape
803 enum RectanglesIntersectTypes {
804 INTERSECT_NONE = 0, //!< No intersection
805 INTERSECT_PARTIAL = 1, //!< There is a partial intersection
806 INTERSECT_FULL = 2 //!< One of the rectangle is fully enclosed in the other
809 //! finds arbitrary template in the grayscale image using Generalized Hough Transform
810 class CV_EXPORTS GeneralizedHough : public Algorithm
813 //! set template to search
814 virtual void setTemplate(InputArray templ, Point templCenter = Point(-1, -1)) = 0;
815 virtual void setTemplate(InputArray edges, InputArray dx, InputArray dy, Point templCenter = Point(-1, -1)) = 0;
817 //! find template on image
818 virtual void detect(InputArray image, OutputArray positions, OutputArray votes = noArray()) = 0;
819 virtual void detect(InputArray edges, InputArray dx, InputArray dy, OutputArray positions, OutputArray votes = noArray()) = 0;
821 //! Canny low threshold.
822 virtual void setCannyLowThresh(int cannyLowThresh) = 0;
823 virtual int getCannyLowThresh() const = 0;
825 //! Canny high threshold.
826 virtual void setCannyHighThresh(int cannyHighThresh) = 0;
827 virtual int getCannyHighThresh() const = 0;
829 //! Minimum distance between the centers of the detected objects.
830 virtual void setMinDist(double minDist) = 0;
831 virtual double getMinDist() const = 0;
833 //! Inverse ratio of the accumulator resolution to the image resolution.
834 virtual void setDp(double dp) = 0;
835 virtual double getDp() const = 0;
837 //! Maximal size of inner buffers.
838 virtual void setMaxBufferSize(int maxBufferSize) = 0;
839 virtual int getMaxBufferSize() const = 0;
842 //! Ballard, D.H. (1981). Generalizing the Hough transform to detect arbitrary shapes. Pattern Recognition 13 (2): 111-122.
843 //! Detects position only without translation and rotation
844 class CV_EXPORTS GeneralizedHoughBallard : public GeneralizedHough
848 virtual void setLevels(int levels) = 0;
849 virtual int getLevels() const = 0;
851 //! The accumulator threshold for the template centers at the detection stage. The smaller it is, the more false positions may be detected.
852 virtual void setVotesThreshold(int votesThreshold) = 0;
853 virtual int getVotesThreshold() const = 0;
856 //! Guil, N., González-Linares, J.M. and Zapata, E.L. (1999). Bidimensional shape detection using an invariant approach. Pattern Recognition 32 (6): 1025-1038.
857 //! Detects position, translation and rotation
858 class CV_EXPORTS GeneralizedHoughGuil : public GeneralizedHough
861 //! Angle difference in degrees between two points in feature.
862 virtual void setXi(double xi) = 0;
863 virtual double getXi() const = 0;
865 //! Feature table levels.
866 virtual void setLevels(int levels) = 0;
867 virtual int getLevels() const = 0;
869 //! Maximal difference between angles that treated as equal.
870 virtual void setAngleEpsilon(double angleEpsilon) = 0;
871 virtual double getAngleEpsilon() const = 0;
873 //! Minimal rotation angle to detect in degrees.
874 virtual void setMinAngle(double minAngle) = 0;
875 virtual double getMinAngle() const = 0;
877 //! Maximal rotation angle to detect in degrees.
878 virtual void setMaxAngle(double maxAngle) = 0;
879 virtual double getMaxAngle() const = 0;
881 //! Angle step in degrees.
882 virtual void setAngleStep(double angleStep) = 0;
883 virtual double getAngleStep() const = 0;
885 //! Angle votes threshold.
886 virtual void setAngleThresh(int angleThresh) = 0;
887 virtual int getAngleThresh() const = 0;
889 //! Minimal scale to detect.
890 virtual void setMinScale(double minScale) = 0;
891 virtual double getMinScale() const = 0;
893 //! Maximal scale to detect.
894 virtual void setMaxScale(double maxScale) = 0;
895 virtual double getMaxScale() const = 0;
898 virtual void setScaleStep(double scaleStep) = 0;
899 virtual double getScaleStep() const = 0;
901 //! Scale votes threshold.
902 virtual void setScaleThresh(int scaleThresh) = 0;
903 virtual int getScaleThresh() const = 0;
905 //! Position votes threshold.
906 virtual void setPosThresh(int posThresh) = 0;
907 virtual int getPosThresh() const = 0;
911 class CV_EXPORTS_W CLAHE : public Algorithm
914 CV_WRAP virtual void apply(InputArray src, OutputArray dst) = 0;
916 CV_WRAP virtual void setClipLimit(double clipLimit) = 0;
917 CV_WRAP virtual double getClipLimit() const = 0;
919 CV_WRAP virtual void setTilesGridSize(Size tileGridSize) = 0;
920 CV_WRAP virtual Size getTilesGridSize() const = 0;
922 CV_WRAP virtual void collectGarbage() = 0;
926 //! @addtogroup imgproc_subdiv2d
929 class CV_EXPORTS_W Subdiv2D
932 /** Subdiv2D point location cases */
933 enum { PTLOC_ERROR = -2, //!< Point location error
934 PTLOC_OUTSIDE_RECT = -1, //!< Point outside the subdivision bounding rect
935 PTLOC_INSIDE = 0, //!< Point inside some facet
936 PTLOC_VERTEX = 1, //!< Point coincides with one of the subdivision vertices
937 PTLOC_ON_EDGE = 2 //!< Point on some edge
940 /** Subdiv2D edge type navigation (see: getEdge()) */
941 enum { NEXT_AROUND_ORG = 0x00,
942 NEXT_AROUND_DST = 0x22,
943 PREV_AROUND_ORG = 0x11,
944 PREV_AROUND_DST = 0x33,
945 NEXT_AROUND_LEFT = 0x13,
946 NEXT_AROUND_RIGHT = 0x31,
947 PREV_AROUND_LEFT = 0x20,
948 PREV_AROUND_RIGHT = 0x02
951 /** creates an empty Subdiv2D object.
952 To create a new empty Delaunay subdivision you need to use the initDelaunay() function.
958 @param rect – Rectangle that includes all of the 2D points that are to be added to the subdivision.
960 The function creates an empty Delaunay subdivision where 2D points can be added using the function
961 insert() . All of the points to be added must be within the specified rectangle, otherwise a runtime
964 CV_WRAP Subdiv2D(Rect rect);
966 /** @brief Creates a new empty Delaunay subdivision
968 @param rect – Rectangle that includes all of the 2D points that are to be added to the subdivision.
971 CV_WRAP void initDelaunay(Rect rect);
973 /** @brief Insert a single point into a Delaunay triangulation.
975 @param pt – Point to insert.
977 The function inserts a single point into a subdivision and modifies the subdivision topology
978 appropriately. If a point with the same coordinates exists already, no new point is added.
979 @returns the ID of the point.
981 @note If the point is outside of the triangulation specified rect a runtime error is raised.
983 CV_WRAP int insert(Point2f pt);
985 /** @brief Insert multiple points into a Delaunay triangulation.
987 @param ptvec – Points to insert.
989 The function inserts a vector of points into a subdivision and modifies the subdivision topology
992 CV_WRAP void insert(const std::vector<Point2f>& ptvec);
994 /** @brief Returns the location of a point within a Delaunay triangulation.
996 @param pt – Point to locate.
997 @param edge – Output edge that the point belongs to or is located to the right of it.
998 @param vertex – Optional output vertex the input point coincides with.
1000 The function locates the input point within the subdivision and gives one of the triangle edges
1003 @returns an integer which specify one of the following five cases for point location:
1004 - The point falls into some facet. The function returns PTLOC_INSIDE and edge will contain one of
1006 - The point falls onto the edge. The function returns PTLOC_ON_EDGE and edge will contain this edge.
1007 - The point coincides with one of the subdivision vertices. The function returns PTLOC_VERTEX and
1008 vertex will contain a pointer to the vertex.
1009 - The point is outside the subdivision reference rectangle. The function returns PTLOC_OUTSIDE_RECT
1010 and no pointers are filled.
1011 - One of input arguments is invalid. A runtime error is raised or, if silent or “parent” error
1012 processing mode is selected, CV_PTLOC_ERROR is returned.
1014 CV_WRAP int locate(Point2f pt, CV_OUT int& edge, CV_OUT int& vertex);
1016 /** @brief Finds the subdivision vertex closest to the given point.
1018 @param pt – Input point.
1019 @param nearestPt – Output subdivision vertex point.
1021 The function is another function that locates the input point within the subdivision. It finds the
1022 subdivision vertex that is the closest to the input point. It is not necessarily one of vertices
1023 of the facet containing the input point, though the facet (located using locate() ) is used as a
1028 CV_WRAP int findNearest(Point2f pt, CV_OUT Point2f* nearestPt = 0);
1030 /** @brief Returns a list of all edges.
1032 @param edgeList – Output vector.
1034 The function gives each edge as a 4 numbers vector, where each two are one of the edge
1035 vertices. i.e. org_x = v[0], org_y = v[1], dst_x = v[2], dst_y = v[3].
1037 CV_WRAP void getEdgeList(CV_OUT std::vector<Vec4f>& edgeList) const;
1039 /** @brief Returns a list of the leading edge ID connected to each triangle.
1041 @param leadingEdgeList – Output vector.
1043 The function gives one edge ID for each triangle.
1045 CV_WRAP void getLeadingEdgeList(CV_OUT std::vector<int>& leadingEdgeList) const;
1047 /** @brief Returns a list of all triangles.
1049 @param triangleList – Output vector.
1051 The function gives each triangle as a 6 numbers vector, where each two are one of the triangle
1052 vertices. i.e. p1_x = v[0], p1_y = v[1], p2_x = v[2], p2_y = v[3], p3_x = v[4], p3_y = v[5].
1054 CV_WRAP void getTriangleList(CV_OUT std::vector<Vec6f>& triangleList) const;
1056 /** @brief Returns a list of all Voroni facets.
1058 @param idx – Vector of vertices IDs to consider. For all vertices you can pass empty vector.
1059 @param facetList – Output vector of the Voroni facets.
1060 @param facetCenters – Output vector of the Voroni facets center points.
1063 CV_WRAP void getVoronoiFacetList(const std::vector<int>& idx, CV_OUT std::vector<std::vector<Point2f> >& facetList,
1064 CV_OUT std::vector<Point2f>& facetCenters);
1066 /** @brief Returns vertex location from vertex ID.
1068 @param vertex – vertex ID.
1069 @param firstEdge – Optional. The first edge ID which is connected to the vertex.
1070 @returns vertex (x,y)
1073 CV_WRAP Point2f getVertex(int vertex, CV_OUT int* firstEdge = 0) const;
1075 /** @brief Returns one of the edges related to the given edge.
1077 @param edge – Subdivision edge ID.
1078 @param nextEdgeType - Parameter specifying which of the related edges to return.
1079 The following values are possible:
1080 - NEXT_AROUND_ORG next around the edge origin ( eOnext on the picture below if e is the input edge)
1081 - NEXT_AROUND_DST next around the edge vertex ( eDnext )
1082 - PREV_AROUND_ORG previous around the edge origin (reversed eRnext )
1083 - PREV_AROUND_DST previous around the edge destination (reversed eLnext )
1084 - NEXT_AROUND_LEFT next around the left facet ( eLnext )
1085 - NEXT_AROUND_RIGHT next around the right facet ( eRnext )
1086 - PREV_AROUND_LEFT previous around the left facet (reversed eOnext )
1087 - PREV_AROUND_RIGHT previous around the right facet (reversed eDnext )
1089 ![sample output](pics/quadedge.png)
1091 @returns edge ID related to the input edge.
1093 CV_WRAP int getEdge( int edge, int nextEdgeType ) const;
1095 /** @brief Returns next edge around the edge origin.
1097 @param edge – Subdivision edge ID.
1099 @returns an integer which is next edge ID around the edge origin: eOnext on the
1100 picture above if e is the input edge).
1102 CV_WRAP int nextEdge(int edge) const;
1104 /** @brief Returns another edge of the same quad-edge.
1106 @param edge – Subdivision edge ID.
1107 @param rotate - Parameter specifying which of the edges of the same quad-edge as the input
1108 one to return. The following values are possible:
1109 - 0 - the input edge ( e on the picture below if e is the input edge)
1110 - 1 - the rotated edge ( eRot )
1111 - 2 - the reversed edge (reversed e (in green))
1112 - 3 - the reversed rotated edge (reversed eRot (in green))
1114 @returns one of the edges ID of the same quad-edge as the input edge.
1116 CV_WRAP int rotateEdge(int edge, int rotate) const;
1117 CV_WRAP int symEdge(int edge) const;
1119 /** @brief Returns the edge origin.
1121 @param edge – Subdivision edge ID.
1122 @param orgpt – Output vertex location.
1126 CV_WRAP int edgeOrg(int edge, CV_OUT Point2f* orgpt = 0) const;
1128 /** @brief Returns the edge destination.
1130 @param edge – Subdivision edge ID.
1131 @param dstpt – Output vertex location.
1135 CV_WRAP int edgeDst(int edge, CV_OUT Point2f* dstpt = 0) const;
1139 void deleteEdge(int edge);
1140 int newPoint(Point2f pt, bool isvirtual, int firstEdge = 0);
1141 void deletePoint(int vtx);
1142 void setEdgePoints( int edge, int orgPt, int dstPt );
1143 void splice( int edgeA, int edgeB );
1144 int connectEdges( int edgeA, int edgeB );
1145 void swapEdges( int edge );
1146 int isRightOf(Point2f pt, int edge) const;
1148 void clearVoronoi();
1149 void checkSubdiv() const;
1151 struct CV_EXPORTS Vertex
1154 Vertex(Point2f pt, bool _isvirtual, int _firstEdge=0);
1155 bool isvirtual() const;
1156 bool isfree() const;
1163 struct CV_EXPORTS QuadEdge
1166 QuadEdge(int edgeidx);
1167 bool isfree() const;
1173 //! All of the vertices
1174 std::vector<Vertex> vtx;
1175 //! All of the edges
1176 std::vector<QuadEdge> qedges;
1182 //! Top left corner of the bounding rect
1184 //! Bottom right corner of the bounding rect
1185 Point2f bottomRight;
1188 //! @} imgproc_subdiv2d
1190 //! @addtogroup imgproc_feature
1193 /** @example lsd_lines.cpp
1194 An example using the LineSegmentDetector
1197 /** @brief Line segment detector class
1199 following the algorithm described at @cite Rafael12 .
1201 class CV_EXPORTS_W LineSegmentDetector : public Algorithm
1205 /** @brief Finds lines in the input image.
1207 This is the output of the default parameters of the algorithm on the above shown image.
1209 ![image](pics/building_lsd.png)
1211 @param _image A grayscale (CV_8UC1) input image. If only a roi needs to be selected, use:
1212 `lsd_ptr-\>detect(image(roi), lines, ...); lines += Scalar(roi.x, roi.y, roi.x, roi.y);`
1213 @param _lines A vector of Vec4i or Vec4f elements specifying the beginning and ending point of a line. Where
1214 Vec4i/Vec4f is (x1, y1, x2, y2), point 1 is the start, point 2 - end. Returned lines are strictly
1215 oriented depending on the gradient.
1216 @param width Vector of widths of the regions, where the lines are found. E.g. Width of line.
1217 @param prec Vector of precisions with which the lines are found.
1218 @param nfa Vector containing number of false alarms in the line region, with precision of 10%. The
1219 bigger the value, logarithmically better the detection.
1220 - -1 corresponds to 10 mean false alarms
1221 - 0 corresponds to 1 mean false alarm
1222 - 1 corresponds to 0.1 mean false alarms
1223 This vector will be calculated only when the objects type is LSD_REFINE_ADV.
1225 CV_WRAP virtual void detect(InputArray _image, OutputArray _lines,
1226 OutputArray width = noArray(), OutputArray prec = noArray(),
1227 OutputArray nfa = noArray()) = 0;
1229 /** @brief Draws the line segments on a given image.
1230 @param _image The image, where the liens will be drawn. Should be bigger or equal to the image,
1231 where the lines were found.
1232 @param lines A vector of the lines that needed to be drawn.
1234 CV_WRAP virtual void drawSegments(InputOutputArray _image, InputArray lines) = 0;
1236 /** @brief Draws two groups of lines in blue and red, counting the non overlapping (mismatching) pixels.
1238 @param size The size of the image, where lines1 and lines2 were found.
1239 @param lines1 The first group of lines that needs to be drawn. It is visualized in blue color.
1240 @param lines2 The second group of lines. They visualized in red color.
1241 @param _image Optional image, where the lines will be drawn. The image should be color(3-channel)
1242 in order for lines1 and lines2 to be drawn in the above mentioned colors.
1244 CV_WRAP virtual int compareSegments(const Size& size, InputArray lines1, InputArray lines2, InputOutputArray _image = noArray()) = 0;
1246 virtual ~LineSegmentDetector() { }
1249 /** @brief Creates a smart pointer to a LineSegmentDetector object and initializes it.
1251 The LineSegmentDetector algorithm is defined using the standard values. Only advanced users may want
1252 to edit those, as to tailor it for their own application.
1254 @param _refine The way found lines will be refined, see cv::LineSegmentDetectorModes
1255 @param _scale The scale of the image that will be used to find the lines. Range (0..1].
1256 @param _sigma_scale Sigma for Gaussian filter. It is computed as sigma = _sigma_scale/_scale.
1257 @param _quant Bound to the quantization error on the gradient norm.
1258 @param _ang_th Gradient angle tolerance in degrees.
1259 @param _log_eps Detection threshold: -log10(NFA) \> log_eps. Used only when advancent refinement
1261 @param _density_th Minimal density of aligned region points in the enclosing rectangle.
1262 @param _n_bins Number of bins in pseudo-ordering of gradient modulus.
1264 CV_EXPORTS_W Ptr<LineSegmentDetector> createLineSegmentDetector(
1265 int _refine = LSD_REFINE_STD, double _scale = 0.8,
1266 double _sigma_scale = 0.6, double _quant = 2.0, double _ang_th = 22.5,
1267 double _log_eps = 0, double _density_th = 0.7, int _n_bins = 1024);
1269 //! @} imgproc_feature
1271 //! @addtogroup imgproc_filter
1274 /** @brief Returns Gaussian filter coefficients.
1276 The function computes and returns the \f$\texttt{ksize} \times 1\f$ matrix of Gaussian filter
1279 \f[G_i= \alpha *e^{-(i-( \texttt{ksize} -1)/2)^2/(2* \texttt{sigma}^2)},\f]
1281 where \f$i=0..\texttt{ksize}-1\f$ and \f$\alpha\f$ is the scale factor chosen so that \f$\sum_i G_i=1\f$.
1283 Two of such generated kernels can be passed to sepFilter2D. Those functions automatically recognize
1284 smoothing kernels (a symmetrical kernel with sum of weights equal to 1) and handle them accordingly.
1285 You may also use the higher-level GaussianBlur.
1286 @param ksize Aperture size. It should be odd ( \f$\texttt{ksize} \mod 2 = 1\f$ ) and positive.
1287 @param sigma Gaussian standard deviation. If it is non-positive, it is computed from ksize as
1288 `sigma = 0.3\*((ksize-1)\*0.5 - 1) + 0.8`.
1289 @param ktype Type of filter coefficients. It can be CV_32F or CV_64F .
1290 @sa sepFilter2D, getDerivKernels, getStructuringElement, GaussianBlur
1292 CV_EXPORTS_W Mat getGaussianKernel( int ksize, double sigma, int ktype = CV_64F );
1294 /** @brief Returns filter coefficients for computing spatial image derivatives.
1296 The function computes and returns the filter coefficients for spatial image derivatives. When
1297 `ksize=CV_SCHARR`, the Scharr \f$3 \times 3\f$ kernels are generated (see cv::Scharr). Otherwise, Sobel
1298 kernels are generated (see cv::Sobel). The filters are normally passed to sepFilter2D or to
1300 @param kx Output matrix of row filter coefficients. It has the type ktype .
1301 @param ky Output matrix of column filter coefficients. It has the type ktype .
1302 @param dx Derivative order in respect of x.
1303 @param dy Derivative order in respect of y.
1304 @param ksize Aperture size. It can be CV_SCHARR, 1, 3, 5, or 7.
1305 @param normalize Flag indicating whether to normalize (scale down) the filter coefficients or not.
1306 Theoretically, the coefficients should have the denominator \f$=2^{ksize*2-dx-dy-2}\f$. If you are
1307 going to filter floating-point images, you are likely to use the normalized kernels. But if you
1308 compute derivatives of an 8-bit image, store the results in a 16-bit image, and wish to preserve
1309 all the fractional bits, you may want to set normalize=false .
1310 @param ktype Type of filter coefficients. It can be CV_32f or CV_64F .
1312 CV_EXPORTS_W void getDerivKernels( OutputArray kx, OutputArray ky,
1313 int dx, int dy, int ksize,
1314 bool normalize = false, int ktype = CV_32F );
1316 /** @brief Returns Gabor filter coefficients.
1318 For more details about gabor filter equations and parameters, see: [Gabor
1319 Filter](http://en.wikipedia.org/wiki/Gabor_filter).
1321 @param ksize Size of the filter returned.
1322 @param sigma Standard deviation of the gaussian envelope.
1323 @param theta Orientation of the normal to the parallel stripes of a Gabor function.
1324 @param lambd Wavelength of the sinusoidal factor.
1325 @param gamma Spatial aspect ratio.
1326 @param psi Phase offset.
1327 @param ktype Type of filter coefficients. It can be CV_32F or CV_64F .
1329 CV_EXPORTS_W Mat getGaborKernel( Size ksize, double sigma, double theta, double lambd,
1330 double gamma, double psi = CV_PI*0.5, int ktype = CV_64F );
1332 //! returns "magic" border value for erosion and dilation. It is automatically transformed to Scalar::all(-DBL_MAX) for dilation.
1333 static inline Scalar morphologyDefaultBorderValue() { return Scalar::all(DBL_MAX); }
1335 /** @brief Returns a structuring element of the specified size and shape for morphological operations.
1337 The function constructs and returns the structuring element that can be further passed to cv::erode,
1338 cv::dilate or cv::morphologyEx. But you can also construct an arbitrary binary mask yourself and use it as
1339 the structuring element.
1341 @param shape Element shape that could be one of cv::MorphShapes
1342 @param ksize Size of the structuring element.
1343 @param anchor Anchor position within the element. The default value \f$(-1, -1)\f$ means that the
1344 anchor is at the center. Note that only the shape of a cross-shaped element depends on the anchor
1345 position. In other cases the anchor just regulates how much the result of the morphological
1346 operation is shifted.
1348 CV_EXPORTS_W Mat getStructuringElement(int shape, Size ksize, Point anchor = Point(-1,-1));
1350 /** @brief Blurs an image using the median filter.
1352 The function smoothes an image using the median filter with the \f$\texttt{ksize} \times
1353 \texttt{ksize}\f$ aperture. Each channel of a multi-channel image is processed independently.
1354 In-place operation is supported.
1356 @note The median filter uses BORDER_REPLICATE internally to cope with border pixels, see cv::BorderTypes
1358 @param src input 1-, 3-, or 4-channel image; when ksize is 3 or 5, the image depth should be
1359 CV_8U, CV_16U, or CV_32F, for larger aperture sizes, it can only be CV_8U.
1360 @param dst destination array of the same size and type as src.
1361 @param ksize aperture linear size; it must be odd and greater than 1, for example: 3, 5, 7 ...
1362 @sa bilateralFilter, blur, boxFilter, GaussianBlur
1364 CV_EXPORTS_W void medianBlur( InputArray src, OutputArray dst, int ksize );
1366 /** @brief Blurs an image using a Gaussian filter.
1368 The function convolves the source image with the specified Gaussian kernel. In-place filtering is
1371 @param src input image; the image can have any number of channels, which are processed
1372 independently, but the depth should be CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
1373 @param dst output image of the same size and type as src.
1374 @param ksize Gaussian kernel size. ksize.width and ksize.height can differ but they both must be
1375 positive and odd. Or, they can be zero's and then they are computed from sigma.
1376 @param sigmaX Gaussian kernel standard deviation in X direction.
1377 @param sigmaY Gaussian kernel standard deviation in Y direction; if sigmaY is zero, it is set to be
1378 equal to sigmaX, if both sigmas are zeros, they are computed from ksize.width and ksize.height,
1379 respectively (see cv::getGaussianKernel for details); to fully control the result regardless of
1380 possible future modifications of all this semantics, it is recommended to specify all of ksize,
1382 @param borderType pixel extrapolation method, see cv::BorderTypes
1384 @sa sepFilter2D, filter2D, blur, boxFilter, bilateralFilter, medianBlur
1386 CV_EXPORTS_W void GaussianBlur( InputArray src, OutputArray dst, Size ksize,
1387 double sigmaX, double sigmaY = 0,
1388 int borderType = BORDER_DEFAULT );
1390 /** @brief Applies the bilateral filter to an image.
1392 The function applies bilateral filtering to the input image, as described in
1393 http://www.dai.ed.ac.uk/CVonline/LOCAL_COPIES/MANDUCHI1/Bilateral_Filtering.html
1394 bilateralFilter can reduce unwanted noise very well while keeping edges fairly sharp. However, it is
1395 very slow compared to most filters.
1397 _Sigma values_: For simplicity, you can set the 2 sigma values to be the same. If they are small (\<
1398 10), the filter will not have much effect, whereas if they are large (\> 150), they will have a very
1399 strong effect, making the image look "cartoonish".
1401 _Filter size_: Large filters (d \> 5) are very slow, so it is recommended to use d=5 for real-time
1402 applications, and perhaps d=9 for offline applications that need heavy noise filtering.
1404 This filter does not work inplace.
1405 @param src Source 8-bit or floating-point, 1-channel or 3-channel image.
1406 @param dst Destination image of the same size and type as src .
1407 @param d Diameter of each pixel neighborhood that is used during filtering. If it is non-positive,
1408 it is computed from sigmaSpace.
1409 @param sigmaColor Filter sigma in the color space. A larger value of the parameter means that
1410 farther colors within the pixel neighborhood (see sigmaSpace) will be mixed together, resulting
1411 in larger areas of semi-equal color.
1412 @param sigmaSpace Filter sigma in the coordinate space. A larger value of the parameter means that
1413 farther pixels will influence each other as long as their colors are close enough (see sigmaColor
1414 ). When d\>0, it specifies the neighborhood size regardless of sigmaSpace. Otherwise, d is
1415 proportional to sigmaSpace.
1416 @param borderType border mode used to extrapolate pixels outside of the image, see cv::BorderTypes
1418 CV_EXPORTS_W void bilateralFilter( InputArray src, OutputArray dst, int d,
1419 double sigmaColor, double sigmaSpace,
1420 int borderType = BORDER_DEFAULT );
1422 /** @brief Blurs an image using the box filter.
1424 The function smooths an image using the kernel:
1426 \f[\texttt{K} = \alpha \begin{bmatrix} 1 & 1 & 1 & \cdots & 1 & 1 \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \hdotsfor{6} \\ 1 & 1 & 1 & \cdots & 1 & 1 \end{bmatrix}\f]
1430 \f[\alpha = \fork{\frac{1}{\texttt{ksize.width*ksize.height}}}{when \texttt{normalize=true}}{1}{otherwise}\f]
1432 Unnormalized box filter is useful for computing various integral characteristics over each pixel
1433 neighborhood, such as covariance matrices of image derivatives (used in dense optical flow
1434 algorithms, and so on). If you need to compute pixel sums over variable-size windows, use cv::integral.
1436 @param src input image.
1437 @param dst output image of the same size and type as src.
1438 @param ddepth the output image depth (-1 to use src.depth()).
1439 @param ksize blurring kernel size.
1440 @param anchor anchor point; default value Point(-1,-1) means that the anchor is at the kernel
1442 @param normalize flag, specifying whether the kernel is normalized by its area or not.
1443 @param borderType border mode used to extrapolate pixels outside of the image, see cv::BorderTypes
1444 @sa blur, bilateralFilter, GaussianBlur, medianBlur, integral
1446 CV_EXPORTS_W void boxFilter( InputArray src, OutputArray dst, int ddepth,
1447 Size ksize, Point anchor = Point(-1,-1),
1448 bool normalize = true,
1449 int borderType = BORDER_DEFAULT );
1451 /** @brief Calculates the normalized sum of squares of the pixel values overlapping the filter.
1453 For every pixel \f$ (x, y) \f$ in the source image, the function calculates the sum of squares of those neighboring
1454 pixel values which overlap the filter placed over the pixel \f$ (x, y) \f$.
1456 The unnormalized square box filter can be useful in computing local image statistics such as the the local
1457 variance and standard deviation around the neighborhood of a pixel.
1459 @param _src input image
1460 @param _dst output image of the same size and type as _src
1461 @param ddepth the output image depth (-1 to use src.depth())
1462 @param ksize kernel size
1463 @param anchor kernel anchor point. The default value of Point(-1, -1) denotes that the anchor is at the kernel
1465 @param normalize flag, specifying whether the kernel is to be normalized by it's area or not.
1466 @param borderType border mode used to extrapolate pixels outside of the image, see cv::BorderTypes
1469 CV_EXPORTS_W void sqrBoxFilter( InputArray _src, OutputArray _dst, int ddepth,
1470 Size ksize, Point anchor = Point(-1, -1),
1471 bool normalize = true,
1472 int borderType = BORDER_DEFAULT );
1474 /** @brief Blurs an image using the normalized box filter.
1476 The function smooths an image using the kernel:
1478 \f[\texttt{K} = \frac{1}{\texttt{ksize.width*ksize.height}} \begin{bmatrix} 1 & 1 & 1 & \cdots & 1 & 1 \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \hdotsfor{6} \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \end{bmatrix}\f]
1480 The call `blur(src, dst, ksize, anchor, borderType)` is equivalent to `boxFilter(src, dst, src.type(),
1481 anchor, true, borderType)`.
1483 @param src input image; it can have any number of channels, which are processed independently, but
1484 the depth should be CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
1485 @param dst output image of the same size and type as src.
1486 @param ksize blurring kernel size.
1487 @param anchor anchor point; default value Point(-1,-1) means that the anchor is at the kernel
1489 @param borderType border mode used to extrapolate pixels outside of the image, see cv::BorderTypes
1490 @sa boxFilter, bilateralFilter, GaussianBlur, medianBlur
1492 CV_EXPORTS_W void blur( InputArray src, OutputArray dst,
1493 Size ksize, Point anchor = Point(-1,-1),
1494 int borderType = BORDER_DEFAULT );
1496 /** @brief Convolves an image with the kernel.
1498 The function applies an arbitrary linear filter to an image. In-place operation is supported. When
1499 the aperture is partially outside the image, the function interpolates outlier pixel values
1500 according to the specified border mode.
1502 The function does actually compute correlation, not the convolution:
1504 \f[\texttt{dst} (x,y) = \sum _{ \stackrel{0\leq x' < \texttt{kernel.cols},}{0\leq y' < \texttt{kernel.rows}} } \texttt{kernel} (x',y')* \texttt{src} (x+x'- \texttt{anchor.x} ,y+y'- \texttt{anchor.y} )\f]
1506 That is, the kernel is not mirrored around the anchor point. If you need a real convolution, flip
1507 the kernel using cv::flip and set the new anchor to `(kernel.cols - anchor.x - 1, kernel.rows -
1510 The function uses the DFT-based algorithm in case of sufficiently large kernels (~`11 x 11` or
1511 larger) and the direct algorithm for small kernels.
1513 @param src input image.
1514 @param dst output image of the same size and the same number of channels as src.
1515 @param ddepth desired depth of the destination image, see @ref filter_depths "combinations"
1516 @param kernel convolution kernel (or rather a correlation kernel), a single-channel floating point
1517 matrix; if you want to apply different kernels to different channels, split the image into
1518 separate color planes using split and process them individually.
1519 @param anchor anchor of the kernel that indicates the relative position of a filtered point within
1520 the kernel; the anchor should lie within the kernel; default value (-1,-1) means that the anchor
1521 is at the kernel center.
1522 @param delta optional value added to the filtered pixels before storing them in dst.
1523 @param borderType pixel extrapolation method, see cv::BorderTypes
1524 @sa sepFilter2D, dft, matchTemplate
1526 CV_EXPORTS_W void filter2D( InputArray src, OutputArray dst, int ddepth,
1527 InputArray kernel, Point anchor = Point(-1,-1),
1528 double delta = 0, int borderType = BORDER_DEFAULT );
1530 /** @brief Applies a separable linear filter to an image.
1532 The function applies a separable linear filter to the image. That is, first, every row of src is
1533 filtered with the 1D kernel kernelX. Then, every column of the result is filtered with the 1D
1534 kernel kernelY. The final result shifted by delta is stored in dst .
1536 @param src Source image.
1537 @param dst Destination image of the same size and the same number of channels as src .
1538 @param ddepth Destination image depth, see @ref filter_depths "combinations"
1539 @param kernelX Coefficients for filtering each row.
1540 @param kernelY Coefficients for filtering each column.
1541 @param anchor Anchor position within the kernel. The default value \f$(-1,-1)\f$ means that the anchor
1542 is at the kernel center.
1543 @param delta Value added to the filtered results before storing them.
1544 @param borderType Pixel extrapolation method, see cv::BorderTypes
1545 @sa filter2D, Sobel, GaussianBlur, boxFilter, blur
1547 CV_EXPORTS_W void sepFilter2D( InputArray src, OutputArray dst, int ddepth,
1548 InputArray kernelX, InputArray kernelY,
1549 Point anchor = Point(-1,-1),
1550 double delta = 0, int borderType = BORDER_DEFAULT );
1552 /** @brief Calculates the first, second, third, or mixed image derivatives using an extended Sobel operator.
1554 In all cases except one, the \f$\texttt{ksize} \times \texttt{ksize}\f$ separable kernel is used to
1555 calculate the derivative. When \f$\texttt{ksize = 1}\f$, the \f$3 \times 1\f$ or \f$1 \times 3\f$
1556 kernel is used (that is, no Gaussian smoothing is done). `ksize = 1` can only be used for the first
1557 or the second x- or y- derivatives.
1559 There is also the special value `ksize = CV_SCHARR (-1)` that corresponds to the \f$3\times3\f$ Scharr
1560 filter that may give more accurate results than the \f$3\times3\f$ Sobel. The Scharr aperture is
1562 \f[\vecthreethree{-3}{0}{3}{-10}{0}{10}{-3}{0}{3}\f]
1564 for the x-derivative, or transposed for the y-derivative.
1566 The function calculates an image derivative by convolving the image with the appropriate kernel:
1568 \f[\texttt{dst} = \frac{\partial^{xorder+yorder} \texttt{src}}{\partial x^{xorder} \partial y^{yorder}}\f]
1570 The Sobel operators combine Gaussian smoothing and differentiation, so the result is more or less
1571 resistant to the noise. Most often, the function is called with ( xorder = 1, yorder = 0, ksize = 3)
1572 or ( xorder = 0, yorder = 1, ksize = 3) to calculate the first x- or y- image derivative. The first
1573 case corresponds to a kernel of:
1575 \f[\vecthreethree{-1}{0}{1}{-2}{0}{2}{-1}{0}{1}\f]
1577 The second case corresponds to a kernel of:
1579 \f[\vecthreethree{-1}{-2}{-1}{0}{0}{0}{1}{2}{1}\f]
1581 @param src input image.
1582 @param dst output image of the same size and the same number of channels as src .
1583 @param ddepth output image depth, see @ref filter_depths "combinations"; in the case of
1584 8-bit input images it will result in truncated derivatives.
1585 @param dx order of the derivative x.
1586 @param dy order of the derivative y.
1587 @param ksize size of the extended Sobel kernel; it must be 1, 3, 5, or 7.
1588 @param scale optional scale factor for the computed derivative values; by default, no scaling is
1589 applied (see cv::getDerivKernels for details).
1590 @param delta optional delta value that is added to the results prior to storing them in dst.
1591 @param borderType pixel extrapolation method, see cv::BorderTypes
1592 @sa Scharr, Laplacian, sepFilter2D, filter2D, GaussianBlur, cartToPolar
1594 CV_EXPORTS_W void Sobel( InputArray src, OutputArray dst, int ddepth,
1595 int dx, int dy, int ksize = 3,
1596 double scale = 1, double delta = 0,
1597 int borderType = BORDER_DEFAULT );
1599 /** @brief Calculates the first order image derivative in both x and y using a Sobel operator
1601 Equivalent to calling:
1604 Sobel( src, dx, CV_16SC1, 1, 0, 3 );
1605 Sobel( src, dy, CV_16SC1, 0, 1, 3 );
1608 @param src input image.
1609 @param dx output image with first-order derivative in x.
1610 @param dy output image with first-order derivative in y.
1611 @param ksize size of Sobel kernel. It must be 3.
1612 @param borderType pixel extrapolation method, see cv::BorderTypes
1617 CV_EXPORTS_W void spatialGradient( InputArray src, OutputArray dx,
1618 OutputArray dy, int ksize = 3,
1619 int borderType = BORDER_DEFAULT );
1621 /** @brief Calculates the first x- or y- image derivative using Scharr operator.
1623 The function computes the first x- or y- spatial image derivative using the Scharr operator. The
1626 \f[\texttt{Scharr(src, dst, ddepth, dx, dy, scale, delta, borderType)}\f]
1630 \f[\texttt{Sobel(src, dst, ddepth, dx, dy, CV\_SCHARR, scale, delta, borderType)} .\f]
1632 @param src input image.
1633 @param dst output image of the same size and the same number of channels as src.
1634 @param ddepth output image depth, see @ref filter_depths "combinations"
1635 @param dx order of the derivative x.
1636 @param dy order of the derivative y.
1637 @param scale optional scale factor for the computed derivative values; by default, no scaling is
1638 applied (see getDerivKernels for details).
1639 @param delta optional delta value that is added to the results prior to storing them in dst.
1640 @param borderType pixel extrapolation method, see cv::BorderTypes
1643 CV_EXPORTS_W void Scharr( InputArray src, OutputArray dst, int ddepth,
1644 int dx, int dy, double scale = 1, double delta = 0,
1645 int borderType = BORDER_DEFAULT );
1647 /** @example laplace.cpp
1648 An example using Laplace transformations for edge detection
1651 /** @brief Calculates the Laplacian of an image.
1653 The function calculates the Laplacian of the source image by adding up the second x and y
1654 derivatives calculated using the Sobel operator:
1656 \f[\texttt{dst} = \Delta \texttt{src} = \frac{\partial^2 \texttt{src}}{\partial x^2} + \frac{\partial^2 \texttt{src}}{\partial y^2}\f]
1658 This is done when `ksize > 1`. When `ksize == 1`, the Laplacian is computed by filtering the image
1659 with the following \f$3 \times 3\f$ aperture:
1661 \f[\vecthreethree {0}{1}{0}{1}{-4}{1}{0}{1}{0}\f]
1663 @param src Source image.
1664 @param dst Destination image of the same size and the same number of channels as src .
1665 @param ddepth Desired depth of the destination image.
1666 @param ksize Aperture size used to compute the second-derivative filters. See getDerivKernels for
1667 details. The size must be positive and odd.
1668 @param scale Optional scale factor for the computed Laplacian values. By default, no scaling is
1669 applied. See getDerivKernels for details.
1670 @param delta Optional delta value that is added to the results prior to storing them in dst .
1671 @param borderType Pixel extrapolation method, see cv::BorderTypes
1674 CV_EXPORTS_W void Laplacian( InputArray src, OutputArray dst, int ddepth,
1675 int ksize = 1, double scale = 1, double delta = 0,
1676 int borderType = BORDER_DEFAULT );
1678 //! @} imgproc_filter
1680 //! @addtogroup imgproc_feature
1683 /** @example edge.cpp
1684 An example on using the canny edge detector
1687 /** @brief Finds edges in an image using the Canny algorithm @cite Canny86 .
1689 The function finds edges in the input image image and marks them in the output map edges using the
1690 Canny algorithm. The smallest value between threshold1 and threshold2 is used for edge linking. The
1691 largest value is used to find initial segments of strong edges. See
1692 <http://en.wikipedia.org/wiki/Canny_edge_detector>
1694 @param image 8-bit input image.
1695 @param edges output edge map; single channels 8-bit image, which has the same size as image .
1696 @param threshold1 first threshold for the hysteresis procedure.
1697 @param threshold2 second threshold for the hysteresis procedure.
1698 @param apertureSize aperture size for the Sobel operator.
1699 @param L2gradient a flag, indicating whether a more accurate \f$L_2\f$ norm
1700 \f$=\sqrt{(dI/dx)^2 + (dI/dy)^2}\f$ should be used to calculate the image gradient magnitude (
1701 L2gradient=true ), or whether the default \f$L_1\f$ norm \f$=|dI/dx|+|dI/dy|\f$ is enough (
1704 CV_EXPORTS_W void Canny( InputArray image, OutputArray edges,
1705 double threshold1, double threshold2,
1706 int apertureSize = 3, bool L2gradient = false );
1710 Finds edges in an image using the Canny algorithm with custom image gradient.
1712 @param dx 16-bit x derivative of input image (CV_16SC1 or CV_16SC3).
1713 @param dy 16-bit y derivative of input image (same type as dx).
1714 @param edges,threshold1,threshold2,L2gradient See cv::Canny
1716 CV_EXPORTS_W void Canny( InputArray dx, InputArray dy,
1718 double threshold1, double threshold2,
1719 bool L2gradient = false );
1721 /** @brief Calculates the minimal eigenvalue of gradient matrices for corner detection.
1723 The function is similar to cornerEigenValsAndVecs but it calculates and stores only the minimal
1724 eigenvalue of the covariance matrix of derivatives, that is, \f$\min(\lambda_1, \lambda_2)\f$ in terms
1725 of the formulae in the cornerEigenValsAndVecs description.
1727 @param src Input single-channel 8-bit or floating-point image.
1728 @param dst Image to store the minimal eigenvalues. It has the type CV_32FC1 and the same size as
1730 @param blockSize Neighborhood size (see the details on cornerEigenValsAndVecs ).
1731 @param ksize Aperture parameter for the Sobel operator.
1732 @param borderType Pixel extrapolation method. See cv::BorderTypes.
1734 CV_EXPORTS_W void cornerMinEigenVal( InputArray src, OutputArray dst,
1735 int blockSize, int ksize = 3,
1736 int borderType = BORDER_DEFAULT );
1738 /** @brief Harris corner detector.
1740 The function runs the Harris corner detector on the image. Similarly to cornerMinEigenVal and
1741 cornerEigenValsAndVecs , for each pixel \f$(x, y)\f$ it calculates a \f$2\times2\f$ gradient covariance
1742 matrix \f$M^{(x,y)}\f$ over a \f$\texttt{blockSize} \times \texttt{blockSize}\f$ neighborhood. Then, it
1743 computes the following characteristic:
1745 \f[\texttt{dst} (x,y) = \mathrm{det} M^{(x,y)} - k \cdot \left ( \mathrm{tr} M^{(x,y)} \right )^2\f]
1747 Corners in the image can be found as the local maxima of this response map.
1749 @param src Input single-channel 8-bit or floating-point image.
1750 @param dst Image to store the Harris detector responses. It has the type CV_32FC1 and the same
1752 @param blockSize Neighborhood size (see the details on cornerEigenValsAndVecs ).
1753 @param ksize Aperture parameter for the Sobel operator.
1754 @param k Harris detector free parameter. See the formula below.
1755 @param borderType Pixel extrapolation method. See cv::BorderTypes.
1757 CV_EXPORTS_W void cornerHarris( InputArray src, OutputArray dst, int blockSize,
1758 int ksize, double k,
1759 int borderType = BORDER_DEFAULT );
1761 /** @brief Calculates eigenvalues and eigenvectors of image blocks for corner detection.
1763 For every pixel \f$p\f$ , the function cornerEigenValsAndVecs considers a blockSize \f$\times\f$ blockSize
1764 neighborhood \f$S(p)\f$ . It calculates the covariation matrix of derivatives over the neighborhood as:
1766 \f[M = \begin{bmatrix} \sum _{S(p)}(dI/dx)^2 & \sum _{S(p)}dI/dx dI/dy \\ \sum _{S(p)}dI/dx dI/dy & \sum _{S(p)}(dI/dy)^2 \end{bmatrix}\f]
1768 where the derivatives are computed using the Sobel operator.
1770 After that, it finds eigenvectors and eigenvalues of \f$M\f$ and stores them in the destination image as
1771 \f$(\lambda_1, \lambda_2, x_1, y_1, x_2, y_2)\f$ where
1773 - \f$\lambda_1, \lambda_2\f$ are the non-sorted eigenvalues of \f$M\f$
1774 - \f$x_1, y_1\f$ are the eigenvectors corresponding to \f$\lambda_1\f$
1775 - \f$x_2, y_2\f$ are the eigenvectors corresponding to \f$\lambda_2\f$
1777 The output of the function can be used for robust edge or corner detection.
1779 @param src Input single-channel 8-bit or floating-point image.
1780 @param dst Image to store the results. It has the same size as src and the type CV_32FC(6) .
1781 @param blockSize Neighborhood size (see details below).
1782 @param ksize Aperture parameter for the Sobel operator.
1783 @param borderType Pixel extrapolation method. See cv::BorderTypes.
1785 @sa cornerMinEigenVal, cornerHarris, preCornerDetect
1787 CV_EXPORTS_W void cornerEigenValsAndVecs( InputArray src, OutputArray dst,
1788 int blockSize, int ksize,
1789 int borderType = BORDER_DEFAULT );
1791 /** @brief Calculates a feature map for corner detection.
1793 The function calculates the complex spatial derivative-based function of the source image
1795 \f[\texttt{dst} = (D_x \texttt{src} )^2 \cdot D_{yy} \texttt{src} + (D_y \texttt{src} )^2 \cdot D_{xx} \texttt{src} - 2 D_x \texttt{src} \cdot D_y \texttt{src} \cdot D_{xy} \texttt{src}\f]
1797 where \f$D_x\f$,\f$D_y\f$ are the first image derivatives, \f$D_{xx}\f$,\f$D_{yy}\f$ are the second image
1798 derivatives, and \f$D_{xy}\f$ is the mixed derivative.
1800 The corners can be found as local maximums of the functions, as shown below:
1802 Mat corners, dilated_corners;
1803 preCornerDetect(image, corners, 3);
1804 // dilation with 3x3 rectangular structuring element
1805 dilate(corners, dilated_corners, Mat(), 1);
1806 Mat corner_mask = corners == dilated_corners;
1809 @param src Source single-channel 8-bit of floating-point image.
1810 @param dst Output image that has the type CV_32F and the same size as src .
1811 @param ksize %Aperture size of the Sobel .
1812 @param borderType Pixel extrapolation method. See cv::BorderTypes.
1814 CV_EXPORTS_W void preCornerDetect( InputArray src, OutputArray dst, int ksize,
1815 int borderType = BORDER_DEFAULT );
1817 /** @brief Refines the corner locations.
1819 The function iterates to find the sub-pixel accurate location of corners or radial saddle points, as
1820 shown on the figure below.
1822 ![image](pics/cornersubpix.png)
1824 Sub-pixel accurate corner locator is based on the observation that every vector from the center \f$q\f$
1825 to a point \f$p\f$ located within a neighborhood of \f$q\f$ is orthogonal to the image gradient at \f$p\f$
1826 subject to image and measurement noise. Consider the expression:
1828 \f[\epsilon _i = {DI_{p_i}}^T \cdot (q - p_i)\f]
1830 where \f${DI_{p_i}}\f$ is an image gradient at one of the points \f$p_i\f$ in a neighborhood of \f$q\f$ . The
1831 value of \f$q\f$ is to be found so that \f$\epsilon_i\f$ is minimized. A system of equations may be set up
1832 with \f$\epsilon_i\f$ set to zero:
1834 \f[\sum _i(DI_{p_i} \cdot {DI_{p_i}}^T) - \sum _i(DI_{p_i} \cdot {DI_{p_i}}^T \cdot p_i)\f]
1836 where the gradients are summed within a neighborhood ("search window") of \f$q\f$ . Calling the first
1837 gradient term \f$G\f$ and the second gradient term \f$b\f$ gives:
1839 \f[q = G^{-1} \cdot b\f]
1841 The algorithm sets the center of the neighborhood window at this new center \f$q\f$ and then iterates
1842 until the center stays within a set threshold.
1844 @param image Input image.
1845 @param corners Initial coordinates of the input corners and refined coordinates provided for
1847 @param winSize Half of the side length of the search window. For example, if winSize=Size(5,5) ,
1848 then a \f$5*2+1 \times 5*2+1 = 11 \times 11\f$ search window is used.
1849 @param zeroZone Half of the size of the dead region in the middle of the search zone over which
1850 the summation in the formula below is not done. It is used sometimes to avoid possible
1851 singularities of the autocorrelation matrix. The value of (-1,-1) indicates that there is no such
1853 @param criteria Criteria for termination of the iterative process of corner refinement. That is,
1854 the process of corner position refinement stops either after criteria.maxCount iterations or when
1855 the corner position moves by less than criteria.epsilon on some iteration.
1857 CV_EXPORTS_W void cornerSubPix( InputArray image, InputOutputArray corners,
1858 Size winSize, Size zeroZone,
1859 TermCriteria criteria );
1861 /** @brief Determines strong corners on an image.
1863 The function finds the most prominent corners in the image or in the specified image region, as
1864 described in @cite Shi94
1866 - Function calculates the corner quality measure at every source image pixel using the
1867 cornerMinEigenVal or cornerHarris .
1868 - Function performs a non-maximum suppression (the local maximums in *3 x 3* neighborhood are
1870 - The corners with the minimal eigenvalue less than
1871 \f$\texttt{qualityLevel} \cdot \max_{x,y} qualityMeasureMap(x,y)\f$ are rejected.
1872 - The remaining corners are sorted by the quality measure in the descending order.
1873 - Function throws away each corner for which there is a stronger corner at a distance less than
1876 The function can be used to initialize a point-based tracker of an object.
1878 @note If the function is called with different values A and B of the parameter qualityLevel , and
1879 A \> B, the vector of returned corners with qualityLevel=A will be the prefix of the output vector
1880 with qualityLevel=B .
1882 @param image Input 8-bit or floating-point 32-bit, single-channel image.
1883 @param corners Output vector of detected corners.
1884 @param maxCorners Maximum number of corners to return. If there are more corners than are found,
1885 the strongest of them is returned. `maxCorners <= 0` implies that no limit on the maximum is set
1886 and all detected corners are returned.
1887 @param qualityLevel Parameter characterizing the minimal accepted quality of image corners. The
1888 parameter value is multiplied by the best corner quality measure, which is the minimal eigenvalue
1889 (see cornerMinEigenVal ) or the Harris function response (see cornerHarris ). The corners with the
1890 quality measure less than the product are rejected. For example, if the best corner has the
1891 quality measure = 1500, and the qualityLevel=0.01 , then all the corners with the quality measure
1892 less than 15 are rejected.
1893 @param minDistance Minimum possible Euclidean distance between the returned corners.
1894 @param mask Optional region of interest. If the image is not empty (it needs to have the type
1895 CV_8UC1 and the same size as image ), it specifies the region in which the corners are detected.
1896 @param blockSize Size of an average block for computing a derivative covariation matrix over each
1897 pixel neighborhood. See cornerEigenValsAndVecs .
1898 @param useHarrisDetector Parameter indicating whether to use a Harris detector (see cornerHarris)
1899 or cornerMinEigenVal.
1900 @param k Free parameter of the Harris detector.
1902 @sa cornerMinEigenVal, cornerHarris, calcOpticalFlowPyrLK, estimateRigidTransform,
1904 CV_EXPORTS_W void goodFeaturesToTrack( InputArray image, OutputArray corners,
1905 int maxCorners, double qualityLevel, double minDistance,
1906 InputArray mask = noArray(), int blockSize = 3,
1907 bool useHarrisDetector = false, double k = 0.04 );
1909 /** @example houghlines.cpp
1910 An example using the Hough line detector
1913 /** @brief Finds lines in a binary image using the standard Hough transform.
1915 The function implements the standard or standard multi-scale Hough transform algorithm for line
1916 detection. See <http://homepages.inf.ed.ac.uk/rbf/HIPR2/hough.htm> for a good explanation of Hough
1919 @param image 8-bit, single-channel binary source image. The image may be modified by the function.
1920 @param lines Output vector of lines. Each line is represented by a two-element vector
1921 \f$(\rho, \theta)\f$ . \f$\rho\f$ is the distance from the coordinate origin \f$(0,0)\f$ (top-left corner of
1922 the image). \f$\theta\f$ is the line rotation angle in radians (
1923 \f$0 \sim \textrm{vertical line}, \pi/2 \sim \textrm{horizontal line}\f$ ).
1924 @param rho Distance resolution of the accumulator in pixels.
1925 @param theta Angle resolution of the accumulator in radians.
1926 @param threshold Accumulator threshold parameter. Only those lines are returned that get enough
1927 votes ( \f$>\texttt{threshold}\f$ ).
1928 @param srn For the multi-scale Hough transform, it is a divisor for the distance resolution rho .
1929 The coarse accumulator distance resolution is rho and the accurate accumulator resolution is
1930 rho/srn . If both srn=0 and stn=0 , the classical Hough transform is used. Otherwise, both these
1931 parameters should be positive.
1932 @param stn For the multi-scale Hough transform, it is a divisor for the distance resolution theta.
1933 @param min_theta For standard and multi-scale Hough transform, minimum angle to check for lines.
1934 Must fall between 0 and max_theta.
1935 @param max_theta For standard and multi-scale Hough transform, maximum angle to check for lines.
1936 Must fall between min_theta and CV_PI.
1938 CV_EXPORTS_W void HoughLines( InputArray image, OutputArray lines,
1939 double rho, double theta, int threshold,
1940 double srn = 0, double stn = 0,
1941 double min_theta = 0, double max_theta = CV_PI );
1943 /** @brief Finds line segments in a binary image using the probabilistic Hough transform.
1945 The function implements the probabilistic Hough transform algorithm for line detection, described
1948 See the line detection example below:
1951 #include <opencv2/imgproc.hpp>
1952 #include <opencv2/highgui.hpp>
1955 using namespace std;
1957 int main(int argc, char** argv)
1959 Mat src, dst, color_dst;
1960 if( argc != 2 || !(src=imread(argv[1], 0)).data)
1963 Canny( src, dst, 50, 200, 3 );
1964 cvtColor( dst, color_dst, COLOR_GRAY2BGR );
1967 vector<Vec2f> lines;
1968 HoughLines( dst, lines, 1, CV_PI/180, 100 );
1970 for( size_t i = 0; i < lines.size(); i++ )
1972 float rho = lines[i][0];
1973 float theta = lines[i][1];
1974 double a = cos(theta), b = sin(theta);
1975 double x0 = a*rho, y0 = b*rho;
1976 Point pt1(cvRound(x0 + 1000*(-b)),
1977 cvRound(y0 + 1000*(a)));
1978 Point pt2(cvRound(x0 - 1000*(-b)),
1979 cvRound(y0 - 1000*(a)));
1980 line( color_dst, pt1, pt2, Scalar(0,0,255), 3, 8 );
1983 vector<Vec4i> lines;
1984 HoughLinesP( dst, lines, 1, CV_PI/180, 80, 30, 10 );
1985 for( size_t i = 0; i < lines.size(); i++ )
1987 line( color_dst, Point(lines[i][0], lines[i][1]),
1988 Point(lines[i][2], lines[i][3]), Scalar(0,0,255), 3, 8 );
1991 namedWindow( "Source", 1 );
1992 imshow( "Source", src );
1994 namedWindow( "Detected Lines", 1 );
1995 imshow( "Detected Lines", color_dst );
2001 This is a sample picture the function parameters have been tuned for:
2003 ![image](pics/building.jpg)
2005 And this is the output of the above program in case of the probabilistic Hough transform:
2007 ![image](pics/houghp.png)
2009 @param image 8-bit, single-channel binary source image. The image may be modified by the function.
2010 @param lines Output vector of lines. Each line is represented by a 4-element vector
2011 \f$(x_1, y_1, x_2, y_2)\f$ , where \f$(x_1,y_1)\f$ and \f$(x_2, y_2)\f$ are the ending points of each detected
2013 @param rho Distance resolution of the accumulator in pixels.
2014 @param theta Angle resolution of the accumulator in radians.
2015 @param threshold Accumulator threshold parameter. Only those lines are returned that get enough
2016 votes ( \f$>\texttt{threshold}\f$ ).
2017 @param minLineLength Minimum line length. Line segments shorter than that are rejected.
2018 @param maxLineGap Maximum allowed gap between points on the same line to link them.
2020 @sa LineSegmentDetector
2022 CV_EXPORTS_W void HoughLinesP( InputArray image, OutputArray lines,
2023 double rho, double theta, int threshold,
2024 double minLineLength = 0, double maxLineGap = 0 );
2026 /** @example houghcircles.cpp
2027 An example using the Hough circle detector
2030 /** @brief Finds circles in a grayscale image using the Hough transform.
2032 The function finds circles in a grayscale image using a modification of the Hough transform.
2036 #include <opencv2/imgproc.hpp>
2037 #include <opencv2/highgui.hpp>
2041 using namespace std;
2043 int main(int argc, char** argv)
2046 if( argc != 2 || !(img=imread(argv[1], 1)).data)
2048 cvtColor(img, gray, COLOR_BGR2GRAY);
2049 // smooth it, otherwise a lot of false circles may be detected
2050 GaussianBlur( gray, gray, Size(9, 9), 2, 2 );
2051 vector<Vec3f> circles;
2052 HoughCircles(gray, circles, HOUGH_GRADIENT,
2053 2, gray.rows/4, 200, 100 );
2054 for( size_t i = 0; i < circles.size(); i++ )
2056 Point center(cvRound(circles[i][0]), cvRound(circles[i][1]));
2057 int radius = cvRound(circles[i][2]);
2058 // draw the circle center
2059 circle( img, center, 3, Scalar(0,255,0), -1, 8, 0 );
2060 // draw the circle outline
2061 circle( img, center, radius, Scalar(0,0,255), 3, 8, 0 );
2063 namedWindow( "circles", 1 );
2064 imshow( "circles", img );
2071 @note Usually the function detects the centers of circles well. However, it may fail to find correct
2072 radii. You can assist to the function by specifying the radius range ( minRadius and maxRadius ) if
2073 you know it. Or, you may ignore the returned radius, use only the center, and find the correct
2074 radius using an additional procedure.
2076 @param image 8-bit, single-channel, grayscale input image.
2077 @param circles Output vector of found circles. Each vector is encoded as a 3-element
2078 floating-point vector \f$(x, y, radius)\f$ .
2079 @param method Detection method, see cv::HoughModes. Currently, the only implemented method is HOUGH_GRADIENT
2080 @param dp Inverse ratio of the accumulator resolution to the image resolution. For example, if
2081 dp=1 , the accumulator has the same resolution as the input image. If dp=2 , the accumulator has
2082 half as big width and height.
2083 @param minDist Minimum distance between the centers of the detected circles. If the parameter is
2084 too small, multiple neighbor circles may be falsely detected in addition to a true one. If it is
2085 too large, some circles may be missed.
2086 @param param1 First method-specific parameter. In case of CV_HOUGH_GRADIENT , it is the higher
2087 threshold of the two passed to the Canny edge detector (the lower one is twice smaller).
2088 @param param2 Second method-specific parameter. In case of CV_HOUGH_GRADIENT , it is the
2089 accumulator threshold for the circle centers at the detection stage. The smaller it is, the more
2090 false circles may be detected. Circles, corresponding to the larger accumulator values, will be
2092 @param minRadius Minimum circle radius.
2093 @param maxRadius Maximum circle radius.
2095 @sa fitEllipse, minEnclosingCircle
2097 CV_EXPORTS_W void HoughCircles( InputArray image, OutputArray circles,
2098 int method, double dp, double minDist,
2099 double param1 = 100, double param2 = 100,
2100 int minRadius = 0, int maxRadius = 0 );
2102 //! @} imgproc_feature
2104 //! @addtogroup imgproc_filter
2107 /** @example morphology2.cpp
2108 An example using the morphological operations
2111 /** @brief Erodes an image by using a specific structuring element.
2113 The function erodes the source image using the specified structuring element that determines the
2114 shape of a pixel neighborhood over which the minimum is taken:
2116 \f[\texttt{dst} (x,y) = \min _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')\f]
2118 The function supports the in-place mode. Erosion can be applied several ( iterations ) times. In
2119 case of multi-channel images, each channel is processed independently.
2121 @param src input image; the number of channels can be arbitrary, but the depth should be one of
2122 CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
2123 @param dst output image of the same size and type as src.
2124 @param kernel structuring element used for erosion; if `element=Mat()`, a `3 x 3` rectangular
2125 structuring element is used. Kernel can be created using getStructuringElement.
2126 @param anchor position of the anchor within the element; default value (-1, -1) means that the
2127 anchor is at the element center.
2128 @param iterations number of times erosion is applied.
2129 @param borderType pixel extrapolation method, see cv::BorderTypes
2130 @param borderValue border value in case of a constant border
2131 @sa dilate, morphologyEx, getStructuringElement
2133 CV_EXPORTS_W void erode( InputArray src, OutputArray dst, InputArray kernel,
2134 Point anchor = Point(-1,-1), int iterations = 1,
2135 int borderType = BORDER_CONSTANT,
2136 const Scalar& borderValue = morphologyDefaultBorderValue() );
2138 /** @brief Dilates an image by using a specific structuring element.
2140 The function dilates the source image using the specified structuring element that determines the
2141 shape of a pixel neighborhood over which the maximum is taken:
2142 \f[\texttt{dst} (x,y) = \max _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')\f]
2144 The function supports the in-place mode. Dilation can be applied several ( iterations ) times. In
2145 case of multi-channel images, each channel is processed independently.
2147 @param src input image; the number of channels can be arbitrary, but the depth should be one of
2148 CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
2149 @param dst output image of the same size and type as src\`.
2150 @param kernel structuring element used for dilation; if elemenat=Mat(), a 3 x 3 rectangular
2151 structuring element is used. Kernel can be created using getStructuringElement
2152 @param anchor position of the anchor within the element; default value (-1, -1) means that the
2153 anchor is at the element center.
2154 @param iterations number of times dilation is applied.
2155 @param borderType pixel extrapolation method, see cv::BorderTypes
2156 @param borderValue border value in case of a constant border
2157 @sa erode, morphologyEx, getStructuringElement
2159 CV_EXPORTS_W void dilate( InputArray src, OutputArray dst, InputArray kernel,
2160 Point anchor = Point(-1,-1), int iterations = 1,
2161 int borderType = BORDER_CONSTANT,
2162 const Scalar& borderValue = morphologyDefaultBorderValue() );
2164 /** @brief Performs advanced morphological transformations.
2166 The function morphologyEx can perform advanced morphological transformations using an erosion and dilation as
2169 Any of the operations can be done in-place. In case of multi-channel images, each channel is
2170 processed independently.
2172 @param src Source image. The number of channels can be arbitrary. The depth should be one of
2173 CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
2174 @param dst Destination image of the same size and type as source image.
2175 @param op Type of a morphological operation, see cv::MorphTypes
2176 @param kernel Structuring element. It can be created using cv::getStructuringElement.
2177 @param anchor Anchor position with the kernel. Negative values mean that the anchor is at the
2179 @param iterations Number of times erosion and dilation are applied.
2180 @param borderType Pixel extrapolation method, see cv::BorderTypes
2181 @param borderValue Border value in case of a constant border. The default value has a special
2183 @sa dilate, erode, getStructuringElement
2185 CV_EXPORTS_W void morphologyEx( InputArray src, OutputArray dst,
2186 int op, InputArray kernel,
2187 Point anchor = Point(-1,-1), int iterations = 1,
2188 int borderType = BORDER_CONSTANT,
2189 const Scalar& borderValue = morphologyDefaultBorderValue() );
2191 //! @} imgproc_filter
2193 //! @addtogroup imgproc_transform
2196 /** @brief Resizes an image.
2198 The function resize resizes the image src down to or up to the specified size. Note that the
2199 initial dst type or size are not taken into account. Instead, the size and type are derived from
2200 the `src`,`dsize`,`fx`, and `fy`. If you want to resize src so that it fits the pre-created dst,
2201 you may call the function as follows:
2203 // explicitly specify dsize=dst.size(); fx and fy will be computed from that.
2204 resize(src, dst, dst.size(), 0, 0, interpolation);
2206 If you want to decimate the image by factor of 2 in each direction, you can call the function this
2209 // specify fx and fy and let the function compute the destination image size.
2210 resize(src, dst, Size(), 0.5, 0.5, interpolation);
2212 To shrink an image, it will generally look best with cv::INTER_AREA interpolation, whereas to
2213 enlarge an image, it will generally look best with cv::INTER_CUBIC (slow) or cv::INTER_LINEAR
2214 (faster but still looks OK).
2216 @param src input image.
2217 @param dst output image; it has the size dsize (when it is non-zero) or the size computed from
2218 src.size(), fx, and fy; the type of dst is the same as of src.
2219 @param dsize output image size; if it equals zero, it is computed as:
2220 \f[\texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}\f]
2221 Either dsize or both fx and fy must be non-zero.
2222 @param fx scale factor along the horizontal axis; when it equals 0, it is computed as
2223 \f[\texttt{(double)dsize.width/src.cols}\f]
2224 @param fy scale factor along the vertical axis; when it equals 0, it is computed as
2225 \f[\texttt{(double)dsize.height/src.rows}\f]
2226 @param interpolation interpolation method, see cv::InterpolationFlags
2228 @sa warpAffine, warpPerspective, remap
2230 CV_EXPORTS_W void resize( InputArray src, OutputArray dst,
2231 Size dsize, double fx = 0, double fy = 0,
2232 int interpolation = INTER_LINEAR );
2234 /** @brief Applies an affine transformation to an image.
2236 The function warpAffine transforms the source image using the specified matrix:
2238 \f[\texttt{dst} (x,y) = \texttt{src} ( \texttt{M} _{11} x + \texttt{M} _{12} y + \texttt{M} _{13}, \texttt{M} _{21} x + \texttt{M} _{22} y + \texttt{M} _{23})\f]
2240 when the flag WARP_INVERSE_MAP is set. Otherwise, the transformation is first inverted
2241 with cv::invertAffineTransform and then put in the formula above instead of M. The function cannot
2244 @param src input image.
2245 @param dst output image that has the size dsize and the same type as src .
2246 @param M \f$2\times 3\f$ transformation matrix.
2247 @param dsize size of the output image.
2248 @param flags combination of interpolation methods (see cv::InterpolationFlags) and the optional
2249 flag WARP_INVERSE_MAP that means that M is the inverse transformation (
2250 \f$\texttt{dst}\rightarrow\texttt{src}\f$ ).
2251 @param borderMode pixel extrapolation method (see cv::BorderTypes); when
2252 borderMode=BORDER_TRANSPARENT, it means that the pixels in the destination image corresponding to
2253 the "outliers" in the source image are not modified by the function.
2254 @param borderValue value used in case of a constant border; by default, it is 0.
2256 @sa warpPerspective, resize, remap, getRectSubPix, transform
2258 CV_EXPORTS_W void warpAffine( InputArray src, OutputArray dst,
2259 InputArray M, Size dsize,
2260 int flags = INTER_LINEAR,
2261 int borderMode = BORDER_CONSTANT,
2262 const Scalar& borderValue = Scalar());
2264 /** @brief Applies a perspective transformation to an image.
2266 The function warpPerspective transforms the source image using the specified matrix:
2268 \f[\texttt{dst} (x,y) = \texttt{src} \left ( \frac{M_{11} x + M_{12} y + M_{13}}{M_{31} x + M_{32} y + M_{33}} ,
2269 \frac{M_{21} x + M_{22} y + M_{23}}{M_{31} x + M_{32} y + M_{33}} \right )\f]
2271 when the flag WARP_INVERSE_MAP is set. Otherwise, the transformation is first inverted with invert
2272 and then put in the formula above instead of M. The function cannot operate in-place.
2274 @param src input image.
2275 @param dst output image that has the size dsize and the same type as src .
2276 @param M \f$3\times 3\f$ transformation matrix.
2277 @param dsize size of the output image.
2278 @param flags combination of interpolation methods (INTER_LINEAR or INTER_NEAREST) and the
2279 optional flag WARP_INVERSE_MAP, that sets M as the inverse transformation (
2280 \f$\texttt{dst}\rightarrow\texttt{src}\f$ ).
2281 @param borderMode pixel extrapolation method (BORDER_CONSTANT or BORDER_REPLICATE).
2282 @param borderValue value used in case of a constant border; by default, it equals 0.
2284 @sa warpAffine, resize, remap, getRectSubPix, perspectiveTransform
2286 CV_EXPORTS_W void warpPerspective( InputArray src, OutputArray dst,
2287 InputArray M, Size dsize,
2288 int flags = INTER_LINEAR,
2289 int borderMode = BORDER_CONSTANT,
2290 const Scalar& borderValue = Scalar());
2292 /** @brief Applies a generic geometrical transformation to an image.
2294 The function remap transforms the source image using the specified map:
2296 \f[\texttt{dst} (x,y) = \texttt{src} (map_x(x,y),map_y(x,y))\f]
2298 where values of pixels with non-integer coordinates are computed using one of available
2299 interpolation methods. \f$map_x\f$ and \f$map_y\f$ can be encoded as separate floating-point maps
2300 in \f$map_1\f$ and \f$map_2\f$ respectively, or interleaved floating-point maps of \f$(x,y)\f$ in
2301 \f$map_1\f$, or fixed-point maps created by using convertMaps. The reason you might want to
2302 convert from floating to fixed-point representations of a map is that they can yield much faster
2303 (\~2x) remapping operations. In the converted case, \f$map_1\f$ contains pairs (cvFloor(x),
2304 cvFloor(y)) and \f$map_2\f$ contains indices in a table of interpolation coefficients.
2306 This function cannot operate in-place.
2308 @param src Source image.
2309 @param dst Destination image. It has the same size as map1 and the same type as src .
2310 @param map1 The first map of either (x,y) points or just x values having the type CV_16SC2 ,
2311 CV_32FC1, or CV_32FC2. See convertMaps for details on converting a floating point
2312 representation to fixed-point for speed.
2313 @param map2 The second map of y values having the type CV_16UC1, CV_32FC1, or none (empty map
2314 if map1 is (x,y) points), respectively.
2315 @param interpolation Interpolation method (see cv::InterpolationFlags). The method INTER_AREA is
2316 not supported by this function.
2317 @param borderMode Pixel extrapolation method (see cv::BorderTypes). When
2318 borderMode=BORDER_TRANSPARENT, it means that the pixels in the destination image that
2319 corresponds to the "outliers" in the source image are not modified by the function.
2320 @param borderValue Value used in case of a constant border. By default, it is 0.
2322 Due to current implementaion limitations the size of an input and output images should be less than 32767x32767.
2324 CV_EXPORTS_W void remap( InputArray src, OutputArray dst,
2325 InputArray map1, InputArray map2,
2326 int interpolation, int borderMode = BORDER_CONSTANT,
2327 const Scalar& borderValue = Scalar());
2329 /** @brief Converts image transformation maps from one representation to another.
2331 The function converts a pair of maps for remap from one representation to another. The following
2332 options ( (map1.type(), map2.type()) \f$\rightarrow\f$ (dstmap1.type(), dstmap2.type()) ) are
2335 - \f$\texttt{(CV_32FC1, CV_32FC1)} \rightarrow \texttt{(CV_16SC2, CV_16UC1)}\f$. This is the
2336 most frequently used conversion operation, in which the original floating-point maps (see remap )
2337 are converted to a more compact and much faster fixed-point representation. The first output array
2338 contains the rounded coordinates and the second array (created only when nninterpolation=false )
2339 contains indices in the interpolation tables.
2341 - \f$\texttt{(CV_32FC2)} \rightarrow \texttt{(CV_16SC2, CV_16UC1)}\f$. The same as above but
2342 the original maps are stored in one 2-channel matrix.
2344 - Reverse conversion. Obviously, the reconstructed floating-point maps will not be exactly the same
2347 @param map1 The first input map of type CV_16SC2, CV_32FC1, or CV_32FC2 .
2348 @param map2 The second input map of type CV_16UC1, CV_32FC1, or none (empty matrix),
2350 @param dstmap1 The first output map that has the type dstmap1type and the same size as src .
2351 @param dstmap2 The second output map.
2352 @param dstmap1type Type of the first output map that should be CV_16SC2, CV_32FC1, or
2354 @param nninterpolation Flag indicating whether the fixed-point maps are used for the
2355 nearest-neighbor or for a more complex interpolation.
2357 @sa remap, undistort, initUndistortRectifyMap
2359 CV_EXPORTS_W void convertMaps( InputArray map1, InputArray map2,
2360 OutputArray dstmap1, OutputArray dstmap2,
2361 int dstmap1type, bool nninterpolation = false );
2363 /** @brief Calculates an affine matrix of 2D rotation.
2365 The function calculates the following matrix:
2367 \f[\begin{bmatrix} \alpha & \beta & (1- \alpha ) \cdot \texttt{center.x} - \beta \cdot \texttt{center.y} \\ - \beta & \alpha & \beta \cdot \texttt{center.x} + (1- \alpha ) \cdot \texttt{center.y} \end{bmatrix}\f]
2371 \f[\begin{array}{l} \alpha = \texttt{scale} \cdot \cos \texttt{angle} , \\ \beta = \texttt{scale} \cdot \sin \texttt{angle} \end{array}\f]
2373 The transformation maps the rotation center to itself. If this is not the target, adjust the shift.
2375 @param center Center of the rotation in the source image.
2376 @param angle Rotation angle in degrees. Positive values mean counter-clockwise rotation (the
2377 coordinate origin is assumed to be the top-left corner).
2378 @param scale Isotropic scale factor.
2380 @sa getAffineTransform, warpAffine, transform
2382 CV_EXPORTS_W Mat getRotationMatrix2D( Point2f center, double angle, double scale );
2384 //! returns 3x3 perspective transformation for the corresponding 4 point pairs.
2385 CV_EXPORTS Mat getPerspectiveTransform( const Point2f src[], const Point2f dst[] );
2387 /** @brief Calculates an affine transform from three pairs of the corresponding points.
2389 The function calculates the \f$2 \times 3\f$ matrix of an affine transform so that:
2391 \f[\begin{bmatrix} x'_i \\ y'_i \end{bmatrix} = \texttt{map_matrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix}\f]
2395 \f[dst(i)=(x'_i,y'_i), src(i)=(x_i, y_i), i=0,1,2\f]
2397 @param src Coordinates of triangle vertices in the source image.
2398 @param dst Coordinates of the corresponding triangle vertices in the destination image.
2400 @sa warpAffine, transform
2402 CV_EXPORTS Mat getAffineTransform( const Point2f src[], const Point2f dst[] );
2404 /** @brief Inverts an affine transformation.
2406 The function computes an inverse affine transformation represented by \f$2 \times 3\f$ matrix M:
2408 \f[\begin{bmatrix} a_{11} & a_{12} & b_1 \\ a_{21} & a_{22} & b_2 \end{bmatrix}\f]
2410 The result is also a \f$2 \times 3\f$ matrix of the same type as M.
2412 @param M Original affine transformation.
2413 @param iM Output reverse affine transformation.
2415 CV_EXPORTS_W void invertAffineTransform( InputArray M, OutputArray iM );
2417 /** @brief Calculates a perspective transform from four pairs of the corresponding points.
2419 The function calculates the \f$3 \times 3\f$ matrix of a perspective transform so that:
2421 \f[\begin{bmatrix} t_i x'_i \\ t_i y'_i \\ t_i \end{bmatrix} = \texttt{map_matrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix}\f]
2425 \f[dst(i)=(x'_i,y'_i), src(i)=(x_i, y_i), i=0,1,2,3\f]
2427 @param src Coordinates of quadrangle vertices in the source image.
2428 @param dst Coordinates of the corresponding quadrangle vertices in the destination image.
2430 @sa findHomography, warpPerspective, perspectiveTransform
2432 CV_EXPORTS_W Mat getPerspectiveTransform( InputArray src, InputArray dst );
2434 CV_EXPORTS_W Mat getAffineTransform( InputArray src, InputArray dst );
2436 /** @brief Retrieves a pixel rectangle from an image with sub-pixel accuracy.
2438 The function getRectSubPix extracts pixels from src:
2440 \f[dst(x, y) = src(x + \texttt{center.x} - ( \texttt{dst.cols} -1)*0.5, y + \texttt{center.y} - ( \texttt{dst.rows} -1)*0.5)\f]
2442 where the values of the pixels at non-integer coordinates are retrieved using bilinear
2443 interpolation. Every channel of multi-channel images is processed independently. While the center of
2444 the rectangle must be inside the image, parts of the rectangle may be outside. In this case, the
2445 replication border mode (see cv::BorderTypes) is used to extrapolate the pixel values outside of
2448 @param image Source image.
2449 @param patchSize Size of the extracted patch.
2450 @param center Floating point coordinates of the center of the extracted rectangle within the
2451 source image. The center must be inside the image.
2452 @param patch Extracted patch that has the size patchSize and the same number of channels as src .
2453 @param patchType Depth of the extracted pixels. By default, they have the same depth as src .
2455 @sa warpAffine, warpPerspective
2457 CV_EXPORTS_W void getRectSubPix( InputArray image, Size patchSize,
2458 Point2f center, OutputArray patch, int patchType = -1 );
2460 /** @example polar_transforms.cpp
2461 An example using the cv::linearPolar and cv::logPolar operations
2464 /** @brief Remaps an image to semilog-polar coordinates space.
2466 Transform the source image using the following transformation (See @ref polar_remaps_reference_image "Polar remaps reference image"):
2468 dst( \rho , \phi ) = src(x,y) \\
2469 dst.size() \leftarrow src.size()
2474 I = (dx,dy) = (x - center.x,y - center.y) \\
2475 \rho = M \cdot log_e(\texttt{magnitude} (I)) ,\\
2476 \phi = Ky \cdot \texttt{angle} (I)_{0..360 deg} \\
2481 M = src.cols / log_e(maxRadius) \\
2482 Ky = src.rows / 360 \\
2485 The function emulates the human "foveal" vision and can be used for fast scale and
2486 rotation-invariant template matching, for object tracking and so forth.
2487 @param src Source image
2488 @param dst Destination image. It will have same size and type as src.
2489 @param center The transformation center; where the output precision is maximal
2490 @param M Magnitude scale parameter. It determines the radius of the bounding circle to transform too.
2491 @param flags A combination of interpolation methods, see cv::InterpolationFlags
2494 - The function can not operate in-place.
2495 - To calculate magnitude and angle in degrees @ref cv::cartToPolar is used internally thus angles are measured from 0 to 360 with accuracy about 0.3 degrees.
2497 CV_EXPORTS_W void logPolar( InputArray src, OutputArray dst,
2498 Point2f center, double M, int flags );
2500 /** @brief Remaps an image to polar coordinates space.
2502 @anchor polar_remaps_reference_image
2503 ![Polar remaps reference](pics/polar_remap_doc.png)
2505 Transform the source image using the following transformation:
2507 dst( \rho , \phi ) = src(x,y) \\
2508 dst.size() \leftarrow src.size()
2513 I = (dx,dy) = (x - center.x,y - center.y) \\
2514 \rho = Kx \cdot \texttt{magnitude} (I) ,\\
2515 \phi = Ky \cdot \texttt{angle} (I)_{0..360 deg}
2520 Kx = src.cols / maxRadius \\
2525 @param src Source image
2526 @param dst Destination image. It will have same size and type as src.
2527 @param center The transformation center;
2528 @param maxRadius The radius of the bounding circle to transform. It determines the inverse magnitude scale parameter too.
2529 @param flags A combination of interpolation methods, see cv::InterpolationFlags
2532 - The function can not operate in-place.
2533 - To calculate magnitude and angle in degrees @ref cv::cartToPolar is used internally thus angles are measured from 0 to 360 with accuracy about 0.3 degrees.
2536 CV_EXPORTS_W void linearPolar( InputArray src, OutputArray dst,
2537 Point2f center, double maxRadius, int flags );
2539 //! @} imgproc_transform
2541 //! @addtogroup imgproc_misc
2545 CV_EXPORTS_W void integral( InputArray src, OutputArray sum, int sdepth = -1 );
2548 CV_EXPORTS_AS(integral2) void integral( InputArray src, OutputArray sum,
2549 OutputArray sqsum, int sdepth = -1, int sqdepth = -1 );
2551 /** @brief Calculates the integral of an image.
2553 The function calculates one or more integral images for the source image as follows:
2555 \f[\texttt{sum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)\f]
2557 \f[\texttt{sqsum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)^2\f]
2559 \f[\texttt{tilted} (X,Y) = \sum _{y<Y,abs(x-X+1) \leq Y-y-1} \texttt{image} (x,y)\f]
2561 Using these integral images, you can calculate sum, mean, and standard deviation over a specific
2562 up-right or rotated rectangular region of the image in a constant time, for example:
2564 \f[\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)\f]
2566 It makes possible to do a fast blurring or fast block correlation with a variable window size, for
2567 example. In case of multi-channel images, sums for each channel are accumulated independently.
2569 As a practical example, the next figure shows the calculation of the integral of a straight
2570 rectangle Rect(3,3,3,2) and of a tilted rectangle Rect(5,1,2,3) . The selected pixels in the
2571 original image are shown, as well as the relative pixels in the integral images sum and tilted .
2573 ![integral calculation example](pics/integral.png)
2575 @param src input image as \f$W \times H\f$, 8-bit or floating-point (32f or 64f).
2576 @param sum integral image as \f$(W+1)\times (H+1)\f$ , 32-bit integer or floating-point (32f or 64f).
2577 @param sqsum integral image for squared pixel values; it is \f$(W+1)\times (H+1)\f$, double-precision
2578 floating-point (64f) array.
2579 @param tilted integral for the image rotated by 45 degrees; it is \f$(W+1)\times (H+1)\f$ array with
2580 the same data type as sum.
2581 @param sdepth desired depth of the integral and the tilted integral images, CV_32S, CV_32F, or
2583 @param sqdepth desired depth of the integral image of squared pixel values, CV_32F or CV_64F.
2585 CV_EXPORTS_AS(integral3) void integral( InputArray src, OutputArray sum,
2586 OutputArray sqsum, OutputArray tilted,
2587 int sdepth = -1, int sqdepth = -1 );
2591 //! @addtogroup imgproc_motion
2594 /** @brief Adds an image to the accumulator.
2596 The function adds src or some of its elements to dst :
2598 \f[\texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0\f]
2600 The function supports multi-channel images. Each channel is processed independently.
2602 The functions accumulate\* can be used, for example, to collect statistics of a scene background
2603 viewed by a still camera and for the further foreground-background segmentation.
2605 @param src Input image of type CV_8UC(n), CV_16UC(n), CV_32FC(n) or CV_64FC(n), where n is a positive integer.
2606 @param dst %Accumulator image with the same number of channels as input image, and a depth of CV_32F or CV_64F.
2607 @param mask Optional operation mask.
2609 @sa accumulateSquare, accumulateProduct, accumulateWeighted
2611 CV_EXPORTS_W void accumulate( InputArray src, InputOutputArray dst,
2612 InputArray mask = noArray() );
2614 /** @brief Adds the square of a source image to the accumulator.
2616 The function adds the input image src or its selected region, raised to a power of 2, to the
2619 \f[\texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src} (x,y)^2 \quad \text{if} \quad \texttt{mask} (x,y) \ne 0\f]
2621 The function supports multi-channel images. Each channel is processed independently.
2623 @param src Input image as 1- or 3-channel, 8-bit or 32-bit floating point.
2624 @param dst %Accumulator image with the same number of channels as input image, 32-bit or 64-bit
2626 @param mask Optional operation mask.
2628 @sa accumulateSquare, accumulateProduct, accumulateWeighted
2630 CV_EXPORTS_W void accumulateSquare( InputArray src, InputOutputArray dst,
2631 InputArray mask = noArray() );
2633 /** @brief Adds the per-element product of two input images to the accumulator.
2635 The function adds the product of two images or their selected regions to the accumulator dst :
2637 \f[\texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src1} (x,y) \cdot \texttt{src2} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0\f]
2639 The function supports multi-channel images. Each channel is processed independently.
2641 @param src1 First input image, 1- or 3-channel, 8-bit or 32-bit floating point.
2642 @param src2 Second input image of the same type and the same size as src1 .
2643 @param dst %Accumulator with the same number of channels as input images, 32-bit or 64-bit
2645 @param mask Optional operation mask.
2647 @sa accumulate, accumulateSquare, accumulateWeighted
2649 CV_EXPORTS_W void accumulateProduct( InputArray src1, InputArray src2,
2650 InputOutputArray dst, InputArray mask=noArray() );
2652 /** @brief Updates a running average.
2654 The function calculates the weighted sum of the input image src and the accumulator dst so that dst
2655 becomes a running average of a frame sequence:
2657 \f[\texttt{dst} (x,y) \leftarrow (1- \texttt{alpha} ) \cdot \texttt{dst} (x,y) + \texttt{alpha} \cdot \texttt{src} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0\f]
2659 That is, alpha regulates the update speed (how fast the accumulator "forgets" about earlier images).
2660 The function supports multi-channel images. Each channel is processed independently.
2662 @param src Input image as 1- or 3-channel, 8-bit or 32-bit floating point.
2663 @param dst %Accumulator image with the same number of channels as input image, 32-bit or 64-bit
2665 @param alpha Weight of the input image.
2666 @param mask Optional operation mask.
2668 @sa accumulate, accumulateSquare, accumulateProduct
2670 CV_EXPORTS_W void accumulateWeighted( InputArray src, InputOutputArray dst,
2671 double alpha, InputArray mask = noArray() );
2673 /** @brief The function is used to detect translational shifts that occur between two images.
2675 The operation takes advantage of the Fourier shift theorem for detecting the translational shift in
2676 the frequency domain. It can be used for fast image registration as well as motion estimation. For
2677 more information please see <http://en.wikipedia.org/wiki/Phase_correlation>
2679 Calculates the cross-power spectrum of two supplied source arrays. The arrays are padded if needed
2680 with getOptimalDFTSize.
2682 The function performs the following equations:
2683 - First it applies a Hanning window (see <http://en.wikipedia.org/wiki/Hann_function>) to each
2684 image to remove possible edge effects. This window is cached until the array size changes to speed
2686 - Next it computes the forward DFTs of each source array:
2687 \f[\mathbf{G}_a = \mathcal{F}\{src_1\}, \; \mathbf{G}_b = \mathcal{F}\{src_2\}\f]
2688 where \f$\mathcal{F}\f$ is the forward DFT.
2689 - It then computes the cross-power spectrum of each frequency domain array:
2690 \f[R = \frac{ \mathbf{G}_a \mathbf{G}_b^*}{|\mathbf{G}_a \mathbf{G}_b^*|}\f]
2691 - Next the cross-correlation is converted back into the time domain via the inverse DFT:
2692 \f[r = \mathcal{F}^{-1}\{R\}\f]
2693 - Finally, it computes the peak location and computes a 5x5 weighted centroid around the peak to
2694 achieve sub-pixel accuracy.
2695 \f[(\Delta x, \Delta y) = \texttt{weightedCentroid} \{\arg \max_{(x, y)}\{r\}\}\f]
2696 - If non-zero, the response parameter is computed as the sum of the elements of r within the 5x5
2697 centroid around the peak location. It is normalized to a maximum of 1 (meaning there is a single
2698 peak) and will be smaller when there are multiple peaks.
2700 @param src1 Source floating point array (CV_32FC1 or CV_64FC1)
2701 @param src2 Source floating point array (CV_32FC1 or CV_64FC1)
2702 @param window Floating point array with windowing coefficients to reduce edge effects (optional).
2703 @param response Signal power within the 5x5 centroid around the peak, between 0 and 1 (optional).
2704 @returns detected phase shift (sub-pixel) between the two arrays.
2706 @sa dft, getOptimalDFTSize, idft, mulSpectrums createHanningWindow
2708 CV_EXPORTS_W Point2d phaseCorrelate(InputArray src1, InputArray src2,
2709 InputArray window = noArray(), CV_OUT double* response = 0);
2711 /** @brief This function computes a Hanning window coefficients in two dimensions.
2713 See (http://en.wikipedia.org/wiki/Hann_function) and (http://en.wikipedia.org/wiki/Window_function)
2714 for more information.
2716 An example is shown below:
2718 // create hanning window of size 100x100 and type CV_32F
2720 createHanningWindow(hann, Size(100, 100), CV_32F);
2722 @param dst Destination array to place Hann coefficients in
2723 @param winSize The window size specifications
2724 @param type Created array type
2726 CV_EXPORTS_W void createHanningWindow(OutputArray dst, Size winSize, int type);
2728 //! @} imgproc_motion
2730 //! @addtogroup imgproc_misc
2733 /** @brief Applies a fixed-level threshold to each array element.
2735 The function applies fixed-level thresholding to a multiple-channel array. The function is typically
2736 used to get a bi-level (binary) image out of a grayscale image ( cv::compare could be also used for
2737 this purpose) or for removing a noise, that is, filtering out pixels with too small or too large
2738 values. There are several types of thresholding supported by the function. They are determined by
2741 Also, the special values cv::THRESH_OTSU or cv::THRESH_TRIANGLE may be combined with one of the
2742 above values. In these cases, the function determines the optimal threshold value using the Otsu's
2743 or Triangle algorithm and uses it instead of the specified thresh . The function returns the
2744 computed threshold value. Currently, the Otsu's and Triangle methods are implemented only for 8-bit
2747 @note Input image should be single channel only in case of CV_THRESH_OTSU or CV_THRESH_TRIANGLE flags
2749 @param src input array (multiple-channel, 8-bit or 32-bit floating point).
2750 @param dst output array of the same size and type and the same number of channels as src.
2751 @param thresh threshold value.
2752 @param maxval maximum value to use with the THRESH_BINARY and THRESH_BINARY_INV thresholding
2754 @param type thresholding type (see the cv::ThresholdTypes).
2756 @sa adaptiveThreshold, findContours, compare, min, max
2758 CV_EXPORTS_W double threshold( InputArray src, OutputArray dst,
2759 double thresh, double maxval, int type );
2762 /** @brief Applies an adaptive threshold to an array.
2764 The function transforms a grayscale image to a binary image according to the formulae:
2766 \f[dst(x,y) = \fork{\texttt{maxValue}}{if \(src(x,y) > T(x,y)\)}{0}{otherwise}\f]
2767 - **THRESH_BINARY_INV**
2768 \f[dst(x,y) = \fork{0}{if \(src(x,y) > T(x,y)\)}{\texttt{maxValue}}{otherwise}\f]
2769 where \f$T(x,y)\f$ is a threshold calculated individually for each pixel (see adaptiveMethod parameter).
2771 The function can process the image in-place.
2773 @param src Source 8-bit single-channel image.
2774 @param dst Destination image of the same size and the same type as src.
2775 @param maxValue Non-zero value assigned to the pixels for which the condition is satisfied
2776 @param adaptiveMethod Adaptive thresholding algorithm to use, see cv::AdaptiveThresholdTypes
2777 @param thresholdType Thresholding type that must be either THRESH_BINARY or THRESH_BINARY_INV,
2778 see cv::ThresholdTypes.
2779 @param blockSize Size of a pixel neighborhood that is used to calculate a threshold value for the
2780 pixel: 3, 5, 7, and so on.
2781 @param C Constant subtracted from the mean or weighted mean (see the details below). Normally, it
2782 is positive but may be zero or negative as well.
2784 @sa threshold, blur, GaussianBlur
2786 CV_EXPORTS_W void adaptiveThreshold( InputArray src, OutputArray dst,
2787 double maxValue, int adaptiveMethod,
2788 int thresholdType, int blockSize, double C );
2792 //! @addtogroup imgproc_filter
2795 /** @brief Blurs an image and downsamples it.
2797 By default, size of the output image is computed as `Size((src.cols+1)/2, (src.rows+1)/2)`, but in
2798 any case, the following conditions should be satisfied:
2800 \f[\begin{array}{l} | \texttt{dstsize.width} *2-src.cols| \leq 2 \\ | \texttt{dstsize.height} *2-src.rows| \leq 2 \end{array}\f]
2802 The function performs the downsampling step of the Gaussian pyramid construction. First, it
2803 convolves the source image with the kernel:
2805 \f[\frac{1}{256} \begin{bmatrix} 1 & 4 & 6 & 4 & 1 \\ 4 & 16 & 24 & 16 & 4 \\ 6 & 24 & 36 & 24 & 6 \\ 4 & 16 & 24 & 16 & 4 \\ 1 & 4 & 6 & 4 & 1 \end{bmatrix}\f]
2807 Then, it downsamples the image by rejecting even rows and columns.
2809 @param src input image.
2810 @param dst output image; it has the specified size and the same type as src.
2811 @param dstsize size of the output image.
2812 @param borderType Pixel extrapolation method, see cv::BorderTypes (BORDER_CONSTANT isn't supported)
2814 CV_EXPORTS_W void pyrDown( InputArray src, OutputArray dst,
2815 const Size& dstsize = Size(), int borderType = BORDER_DEFAULT );
2817 /** @brief Upsamples an image and then blurs it.
2819 By default, size of the output image is computed as `Size(src.cols\*2, (src.rows\*2)`, but in any
2820 case, the following conditions should be satisfied:
2822 \f[\begin{array}{l} | \texttt{dstsize.width} -src.cols*2| \leq ( \texttt{dstsize.width} \mod 2) \\ | \texttt{dstsize.height} -src.rows*2| \leq ( \texttt{dstsize.height} \mod 2) \end{array}\f]
2824 The function performs the upsampling step of the Gaussian pyramid construction, though it can
2825 actually be used to construct the Laplacian pyramid. First, it upsamples the source image by
2826 injecting even zero rows and columns and then convolves the result with the same kernel as in
2827 pyrDown multiplied by 4.
2829 @param src input image.
2830 @param dst output image. It has the specified size and the same type as src .
2831 @param dstsize size of the output image.
2832 @param borderType Pixel extrapolation method, see cv::BorderTypes (only BORDER_DEFAULT is supported)
2834 CV_EXPORTS_W void pyrUp( InputArray src, OutputArray dst,
2835 const Size& dstsize = Size(), int borderType = BORDER_DEFAULT );
2837 /** @brief Constructs the Gaussian pyramid for an image.
2839 The function constructs a vector of images and builds the Gaussian pyramid by recursively applying
2840 pyrDown to the previously built pyramid layers, starting from `dst[0]==src`.
2842 @param src Source image. Check pyrDown for the list of supported types.
2843 @param dst Destination vector of maxlevel+1 images of the same type as src. dst[0] will be the
2844 same as src. dst[1] is the next pyramid layer, a smoothed and down-sized src, and so on.
2845 @param maxlevel 0-based index of the last (the smallest) pyramid layer. It must be non-negative.
2846 @param borderType Pixel extrapolation method, see cv::BorderTypes (BORDER_CONSTANT isn't supported)
2848 CV_EXPORTS void buildPyramid( InputArray src, OutputArrayOfArrays dst,
2849 int maxlevel, int borderType = BORDER_DEFAULT );
2851 //! @} imgproc_filter
2853 //! @addtogroup imgproc_transform
2856 /** @brief Transforms an image to compensate for lens distortion.
2858 The function transforms an image to compensate radial and tangential lens distortion.
2860 The function is simply a combination of cv::initUndistortRectifyMap (with unity R ) and cv::remap
2861 (with bilinear interpolation). See the former function for details of the transformation being
2864 Those pixels in the destination image, for which there is no correspondent pixels in the source
2865 image, are filled with zeros (black color).
2867 A particular subset of the source image that will be visible in the corrected image can be regulated
2868 by newCameraMatrix. You can use cv::getOptimalNewCameraMatrix to compute the appropriate
2869 newCameraMatrix depending on your requirements.
2871 The camera matrix and the distortion parameters can be determined using cv::calibrateCamera. If
2872 the resolution of images is different from the resolution used at the calibration stage, \f$f_x,
2873 f_y, c_x\f$ and \f$c_y\f$ need to be scaled accordingly, while the distortion coefficients remain
2876 @param src Input (distorted) image.
2877 @param dst Output (corrected) image that has the same size and type as src .
2878 @param cameraMatrix Input camera matrix \f$A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\f$ .
2879 @param distCoeffs Input vector of distortion coefficients
2880 \f$(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6[, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\f$
2881 of 4, 5, 8, 12 or 14 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
2882 @param newCameraMatrix Camera matrix of the distorted image. By default, it is the same as
2883 cameraMatrix but you may additionally scale and shift the result by using a different matrix.
2885 CV_EXPORTS_W void undistort( InputArray src, OutputArray dst,
2886 InputArray cameraMatrix,
2887 InputArray distCoeffs,
2888 InputArray newCameraMatrix = noArray() );
2890 /** @brief Computes the undistortion and rectification transformation map.
2892 The function computes the joint undistortion and rectification transformation and represents the
2893 result in the form of maps for remap. The undistorted image looks like original, as if it is
2894 captured with a camera using the camera matrix =newCameraMatrix and zero distortion. In case of a
2895 monocular camera, newCameraMatrix is usually equal to cameraMatrix, or it can be computed by
2896 cv::getOptimalNewCameraMatrix for a better control over scaling. In case of a stereo camera,
2897 newCameraMatrix is normally set to P1 or P2 computed by cv::stereoRectify .
2899 Also, this new camera is oriented differently in the coordinate space, according to R. That, for
2900 example, helps to align two heads of a stereo camera so that the epipolar lines on both images
2901 become horizontal and have the same y- coordinate (in case of a horizontally aligned stereo camera).
2903 The function actually builds the maps for the inverse mapping algorithm that is used by remap. That
2904 is, for each pixel \f$(u, v)\f$ in the destination (corrected and rectified) image, the function
2905 computes the corresponding coordinates in the source image (that is, in the original image from
2906 camera). The following process is applied:
2909 x \leftarrow (u - {c'}_x)/{f'}_x \\
2910 y \leftarrow (v - {c'}_y)/{f'}_y \\
2911 {[X\,Y\,W]} ^T \leftarrow R^{-1}*[x \, y \, 1]^T \\
2912 x' \leftarrow X/W \\
2913 y' \leftarrow Y/W \\
2914 r^2 \leftarrow x'^2 + y'^2 \\
2915 x'' \leftarrow x' \frac{1 + k_1 r^2 + k_2 r^4 + k_3 r^6}{1 + k_4 r^2 + k_5 r^4 + k_6 r^6}
2916 + 2p_1 x' y' + p_2(r^2 + 2 x'^2) + s_1 r^2 + s_2 r^4\\
2917 y'' \leftarrow y' \frac{1 + k_1 r^2 + k_2 r^4 + k_3 r^6}{1 + k_4 r^2 + k_5 r^4 + k_6 r^6}
2918 + p_1 (r^2 + 2 y'^2) + 2 p_2 x' y' + s_3 r^2 + s_4 r^4 \\
2919 s\vecthree{x'''}{y'''}{1} =
2920 \vecthreethree{R_{33}(\tau_x, \tau_y)}{0}{-R_{13}((\tau_x, \tau_y)}
2921 {0}{R_{33}(\tau_x, \tau_y)}{-R_{23}(\tau_x, \tau_y)}
2922 {0}{0}{1} R(\tau_x, \tau_y) \vecthree{x''}{y''}{1}\\
2923 map_x(u,v) \leftarrow x''' f_x + c_x \\
2924 map_y(u,v) \leftarrow y''' f_y + c_y
2927 where \f$(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6[, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\f$
2928 are the distortion coefficients.
2930 In case of a stereo camera, this function is called twice: once for each camera head, after
2931 stereoRectify, which in its turn is called after cv::stereoCalibrate. But if the stereo camera
2932 was not calibrated, it is still possible to compute the rectification transformations directly from
2933 the fundamental matrix using cv::stereoRectifyUncalibrated. For each camera, the function computes
2934 homography H as the rectification transformation in a pixel domain, not a rotation matrix R in 3D
2935 space. R can be computed from H as
2936 \f[\texttt{R} = \texttt{cameraMatrix} ^{-1} \cdot \texttt{H} \cdot \texttt{cameraMatrix}\f]
2937 where cameraMatrix can be chosen arbitrarily.
2939 @param cameraMatrix Input camera matrix \f$A=\vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\f$ .
2940 @param distCoeffs Input vector of distortion coefficients
2941 \f$(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6[, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\f$
2942 of 4, 5, 8, 12 or 14 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
2943 @param R Optional rectification transformation in the object space (3x3 matrix). R1 or R2 ,
2944 computed by stereoRectify can be passed here. If the matrix is empty, the identity transformation
2945 is assumed. In cvInitUndistortMap R assumed to be an identity matrix.
2946 @param newCameraMatrix New camera matrix \f$A'=\vecthreethree{f_x'}{0}{c_x'}{0}{f_y'}{c_y'}{0}{0}{1}\f$.
2947 @param size Undistorted image size.
2948 @param m1type Type of the first output map that can be CV_32FC1, CV_32FC2 or CV_16SC2, see cv::convertMaps
2949 @param map1 The first output map.
2950 @param map2 The second output map.
2952 CV_EXPORTS_W void initUndistortRectifyMap( InputArray cameraMatrix, InputArray distCoeffs,
2953 InputArray R, InputArray newCameraMatrix,
2954 Size size, int m1type, OutputArray map1, OutputArray map2 );
2956 //! initializes maps for cv::remap() for wide-angle
2957 CV_EXPORTS_W float initWideAngleProjMap( InputArray cameraMatrix, InputArray distCoeffs,
2958 Size imageSize, int destImageWidth,
2959 int m1type, OutputArray map1, OutputArray map2,
2960 int projType = PROJ_SPHERICAL_EQRECT, double alpha = 0);
2962 /** @brief Returns the default new camera matrix.
2964 The function returns the camera matrix that is either an exact copy of the input cameraMatrix (when
2965 centerPrinicipalPoint=false ), or the modified one (when centerPrincipalPoint=true).
2967 In the latter case, the new camera matrix will be:
2969 \f[\begin{bmatrix} f_x && 0 && ( \texttt{imgSize.width} -1)*0.5 \\ 0 && f_y && ( \texttt{imgSize.height} -1)*0.5 \\ 0 && 0 && 1 \end{bmatrix} ,\f]
2971 where \f$f_x\f$ and \f$f_y\f$ are \f$(0,0)\f$ and \f$(1,1)\f$ elements of cameraMatrix, respectively.
2973 By default, the undistortion functions in OpenCV (see initUndistortRectifyMap, undistort) do not
2974 move the principal point. However, when you work with stereo, it is important to move the principal
2975 points in both views to the same y-coordinate (which is required by most of stereo correspondence
2976 algorithms), and may be to the same x-coordinate too. So, you can form the new camera matrix for
2977 each view where the principal points are located at the center.
2979 @param cameraMatrix Input camera matrix.
2980 @param imgsize Camera view image size in pixels.
2981 @param centerPrincipalPoint Location of the principal point in the new camera matrix. The
2982 parameter indicates whether this location should be at the image center or not.
2984 CV_EXPORTS_W Mat getDefaultNewCameraMatrix( InputArray cameraMatrix, Size imgsize = Size(),
2985 bool centerPrincipalPoint = false );
2987 /** @brief Computes the ideal point coordinates from the observed point coordinates.
2989 The function is similar to cv::undistort and cv::initUndistortRectifyMap but it operates on a
2990 sparse set of points instead of a raster image. Also the function performs a reverse transformation
2991 to projectPoints. In case of a 3D object, it does not reconstruct its 3D coordinates, but for a
2992 planar object, it does, up to a translation vector, if the proper R is specified.
2994 For each observed point coordinate \f$(u, v)\f$ the function computes:
2997 x^{"} \leftarrow (u - c_x)/f_x \\
2998 y^{"} \leftarrow (v - c_y)/f_y \\
2999 (x',y') = undistort(x^{"},y^{"}, \texttt{distCoeffs}) \\
3000 {[X\,Y\,W]} ^T \leftarrow R*[x' \, y' \, 1]^T \\
3003 \text{only performed if P is specified:} \\
3004 u' \leftarrow x {f'}_x + {c'}_x \\
3005 v' \leftarrow y {f'}_y + {c'}_y
3009 where *undistort* is an approximate iterative algorithm that estimates the normalized original
3010 point coordinates out of the normalized distorted point coordinates ("normalized" means that the
3011 coordinates do not depend on the camera matrix).
3013 The function can be used for both a stereo camera head or a monocular camera (when R is empty).
3015 @param src Observed point coordinates, 1xN or Nx1 2-channel (CV_32FC2 or CV_64FC2).
3016 @param dst Output ideal point coordinates after undistortion and reverse perspective
3017 transformation. If matrix P is identity or omitted, dst will contain normalized point coordinates.
3018 @param cameraMatrix Camera matrix \f$\vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}\f$ .
3019 @param distCoeffs Input vector of distortion coefficients
3020 \f$(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6[, s_1, s_2, s_3, s_4[, \tau_x, \tau_y]]]])\f$
3021 of 4, 5, 8, 12 or 14 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
3022 @param R Rectification transformation in the object space (3x3 matrix). R1 or R2 computed by
3023 cv::stereoRectify can be passed here. If the matrix is empty, the identity transformation is used.
3024 @param P New camera matrix (3x3) or new projection matrix (3x4) \f$\begin{bmatrix} {f'}_x & 0 & {c'}_x & t_x \\ 0 & {f'}_y & {c'}_y & t_y \\ 0 & 0 & 1 & t_z \end{bmatrix}\f$. P1 or P2 computed by
3025 cv::stereoRectify can be passed here. If the matrix is empty, the identity new camera matrix is used.
3027 CV_EXPORTS_W void undistortPoints( InputArray src, OutputArray dst,
3028 InputArray cameraMatrix, InputArray distCoeffs,
3029 InputArray R = noArray(), InputArray P = noArray());
3031 //! @} imgproc_transform
3033 //! @addtogroup imgproc_hist
3036 /** @example demhist.cpp
3037 An example for creating histograms of an image
3040 /** @brief Calculates a histogram of a set of arrays.
3042 The function cv::calcHist calculates the histogram of one or more arrays. The elements of a tuple used
3043 to increment a histogram bin are taken from the corresponding input arrays at the same location. The
3044 sample below shows how to compute a 2D Hue-Saturation histogram for a color image. :
3046 #include <opencv2/imgproc.hpp>
3047 #include <opencv2/highgui.hpp>
3051 int main( int argc, char** argv )
3054 if( argc != 2 || !(src=imread(argv[1], 1)).data )
3057 cvtColor(src, hsv, COLOR_BGR2HSV);
3059 // Quantize the hue to 30 levels
3060 // and the saturation to 32 levels
3061 int hbins = 30, sbins = 32;
3062 int histSize[] = {hbins, sbins};
3063 // hue varies from 0 to 179, see cvtColor
3064 float hranges[] = { 0, 180 };
3065 // saturation varies from 0 (black-gray-white) to
3066 // 255 (pure spectrum color)
3067 float sranges[] = { 0, 256 };
3068 const float* ranges[] = { hranges, sranges };
3070 // we compute the histogram from the 0-th and 1-st channels
3071 int channels[] = {0, 1};
3073 calcHist( &hsv, 1, channels, Mat(), // do not use mask
3074 hist, 2, histSize, ranges,
3075 true, // the histogram is uniform
3078 minMaxLoc(hist, 0, &maxVal, 0, 0);
3081 Mat histImg = Mat::zeros(sbins*scale, hbins*10, CV_8UC3);
3083 for( int h = 0; h < hbins; h++ )
3084 for( int s = 0; s < sbins; s++ )
3086 float binVal = hist.at<float>(h, s);
3087 int intensity = cvRound(binVal*255/maxVal);
3088 rectangle( histImg, Point(h*scale, s*scale),
3089 Point( (h+1)*scale - 1, (s+1)*scale - 1),
3090 Scalar::all(intensity),
3094 namedWindow( "Source", 1 );
3095 imshow( "Source", src );
3097 namedWindow( "H-S Histogram", 1 );
3098 imshow( "H-S Histogram", histImg );
3103 @param images Source arrays. They all should have the same depth, CV_8U, CV_16U or CV_32F , and the same
3104 size. Each of them can have an arbitrary number of channels.
3105 @param nimages Number of source images.
3106 @param channels List of the dims channels used to compute the histogram. The first array channels
3107 are numerated from 0 to images[0].channels()-1 , the second array channels are counted from
3108 images[0].channels() to images[0].channels() + images[1].channels()-1, and so on.
3109 @param mask Optional mask. If the matrix is not empty, it must be an 8-bit array of the same size
3110 as images[i] . The non-zero mask elements mark the array elements counted in the histogram.
3111 @param hist Output histogram, which is a dense or sparse dims -dimensional array.
3112 @param dims Histogram dimensionality that must be positive and not greater than CV_MAX_DIMS
3113 (equal to 32 in the current OpenCV version).
3114 @param histSize Array of histogram sizes in each dimension.
3115 @param ranges Array of the dims arrays of the histogram bin boundaries in each dimension. When the
3116 histogram is uniform ( uniform =true), then for each dimension i it is enough to specify the lower
3117 (inclusive) boundary \f$L_0\f$ of the 0-th histogram bin and the upper (exclusive) boundary
3118 \f$U_{\texttt{histSize}[i]-1}\f$ for the last histogram bin histSize[i]-1 . That is, in case of a
3119 uniform histogram each of ranges[i] is an array of 2 elements. When the histogram is not uniform (
3120 uniform=false ), then each of ranges[i] contains histSize[i]+1 elements:
3121 \f$L_0, U_0=L_1, U_1=L_2, ..., U_{\texttt{histSize[i]}-2}=L_{\texttt{histSize[i]}-1}, U_{\texttt{histSize[i]}-1}\f$
3122 . The array elements, that are not between \f$L_0\f$ and \f$U_{\texttt{histSize[i]}-1}\f$ , are not
3123 counted in the histogram.
3124 @param uniform Flag indicating whether the histogram is uniform or not (see above).
3125 @param accumulate Accumulation flag. If it is set, the histogram is not cleared in the beginning
3126 when it is allocated. This feature enables you to compute a single histogram from several sets of
3127 arrays, or to update the histogram in time.
3129 CV_EXPORTS void calcHist( const Mat* images, int nimages,
3130 const int* channels, InputArray mask,
3131 OutputArray hist, int dims, const int* histSize,
3132 const float** ranges, bool uniform = true, bool accumulate = false );
3136 this variant uses cv::SparseMat for output
3138 CV_EXPORTS void calcHist( const Mat* images, int nimages,
3139 const int* channels, InputArray mask,
3140 SparseMat& hist, int dims,
3141 const int* histSize, const float** ranges,
3142 bool uniform = true, bool accumulate = false );
3145 CV_EXPORTS_W void calcHist( InputArrayOfArrays images,
3146 const std::vector<int>& channels,
3147 InputArray mask, OutputArray hist,
3148 const std::vector<int>& histSize,
3149 const std::vector<float>& ranges,
3150 bool accumulate = false );
3152 /** @brief Calculates the back projection of a histogram.
3154 The function cv::calcBackProject calculates the back project of the histogram. That is, similarly to
3155 cv::calcHist , at each location (x, y) the function collects the values from the selected channels
3156 in the input images and finds the corresponding histogram bin. But instead of incrementing it, the
3157 function reads the bin value, scales it by scale , and stores in backProject(x,y) . In terms of
3158 statistics, the function computes probability of each element value in respect with the empirical
3159 probability distribution represented by the histogram. See how, for example, you can find and track
3160 a bright-colored object in a scene:
3162 - Before tracking, show the object to the camera so that it covers almost the whole frame.
3163 Calculate a hue histogram. The histogram may have strong maximums, corresponding to the dominant
3164 colors in the object.
3166 - When tracking, calculate a back projection of a hue plane of each input video frame using that
3167 pre-computed histogram. Threshold the back projection to suppress weak colors. It may also make
3168 sense to suppress pixels with non-sufficient color saturation and too dark or too bright pixels.
3170 - Find connected components in the resulting picture and choose, for example, the largest
3173 This is an approximate algorithm of the CamShift color object tracker.
3175 @param images Source arrays. They all should have the same depth, CV_8U, CV_16U or CV_32F , and the same
3176 size. Each of them can have an arbitrary number of channels.
3177 @param nimages Number of source images.
3178 @param channels The list of channels used to compute the back projection. The number of channels
3179 must match the histogram dimensionality. The first array channels are numerated from 0 to
3180 images[0].channels()-1 , the second array channels are counted from images[0].channels() to
3181 images[0].channels() + images[1].channels()-1, and so on.
3182 @param hist Input histogram that can be dense or sparse.
3183 @param backProject Destination back projection array that is a single-channel array of the same
3184 size and depth as images[0] .
3185 @param ranges Array of arrays of the histogram bin boundaries in each dimension. See cv::calcHist .
3186 @param scale Optional scale factor for the output back projection.
3187 @param uniform Flag indicating whether the histogram is uniform or not (see above).
3189 @sa cv::calcHist, cv::compareHist
3191 CV_EXPORTS void calcBackProject( const Mat* images, int nimages,
3192 const int* channels, InputArray hist,
3193 OutputArray backProject, const float** ranges,
3194 double scale = 1, bool uniform = true );
3197 CV_EXPORTS void calcBackProject( const Mat* images, int nimages,
3198 const int* channels, const SparseMat& hist,
3199 OutputArray backProject, const float** ranges,
3200 double scale = 1, bool uniform = true );
3203 CV_EXPORTS_W void calcBackProject( InputArrayOfArrays images, const std::vector<int>& channels,
3204 InputArray hist, OutputArray dst,
3205 const std::vector<float>& ranges,
3208 /** @brief Compares two histograms.
3210 The function cv::compareHist compares two dense or two sparse histograms using the specified method.
3212 The function returns \f$d(H_1, H_2)\f$ .
3214 While the function works well with 1-, 2-, 3-dimensional dense histograms, it may not be suitable
3215 for high-dimensional sparse histograms. In such histograms, because of aliasing and sampling
3216 problems, the coordinates of non-zero histogram bins can slightly shift. To compare such histograms
3217 or more general sparse configurations of weighted points, consider using the cv::EMD function.
3219 @param H1 First compared histogram.
3220 @param H2 Second compared histogram of the same size as H1 .
3221 @param method Comparison method, see cv::HistCompMethods
3223 CV_EXPORTS_W double compareHist( InputArray H1, InputArray H2, int method );
3226 CV_EXPORTS double compareHist( const SparseMat& H1, const SparseMat& H2, int method );
3228 /** @brief Equalizes the histogram of a grayscale image.
3230 The function equalizes the histogram of the input image using the following algorithm:
3232 - Calculate the histogram \f$H\f$ for src .
3233 - Normalize the histogram so that the sum of histogram bins is 255.
3234 - Compute the integral of the histogram:
3235 \f[H'_i = \sum _{0 \le j < i} H(j)\f]
3236 - Transform the image using \f$H'\f$ as a look-up table: \f$\texttt{dst}(x,y) = H'(\texttt{src}(x,y))\f$
3238 The algorithm normalizes the brightness and increases the contrast of the image.
3240 @param src Source 8-bit single channel image.
3241 @param dst Destination image of the same size and type as src .
3243 CV_EXPORTS_W void equalizeHist( InputArray src, OutputArray dst );
3245 /** @brief Computes the "minimal work" distance between two weighted point configurations.
3247 The function computes the earth mover distance and/or a lower boundary of the distance between the
3248 two weighted point configurations. One of the applications described in @cite RubnerSept98,
3249 @cite Rubner2000 is multi-dimensional histogram comparison for image retrieval. EMD is a transportation
3250 problem that is solved using some modification of a simplex algorithm, thus the complexity is
3251 exponential in the worst case, though, on average it is much faster. In the case of a real metric
3252 the lower boundary can be calculated even faster (using linear-time algorithm) and it can be used
3253 to determine roughly whether the two signatures are far enough so that they cannot relate to the
3256 @param signature1 First signature, a \f$\texttt{size1}\times \texttt{dims}+1\f$ floating-point matrix.
3257 Each row stores the point weight followed by the point coordinates. The matrix is allowed to have
3258 a single column (weights only) if the user-defined cost matrix is used. The weights must be
3259 non-negative and have at least one non-zero value.
3260 @param signature2 Second signature of the same format as signature1 , though the number of rows
3261 may be different. The total weights may be different. In this case an extra "dummy" point is added
3262 to either signature1 or signature2. The weights must be non-negative and have at least one non-zero
3264 @param distType Used metric. See cv::DistanceTypes.
3265 @param cost User-defined \f$\texttt{size1}\times \texttt{size2}\f$ cost matrix. Also, if a cost matrix
3266 is used, lower boundary lowerBound cannot be calculated because it needs a metric function.
3267 @param lowerBound Optional input/output parameter: lower boundary of a distance between the two
3268 signatures that is a distance between mass centers. The lower boundary may not be calculated if
3269 the user-defined cost matrix is used, the total weights of point configurations are not equal, or
3270 if the signatures consist of weights only (the signature matrices have a single column). You
3271 **must** initialize \*lowerBound . If the calculated distance between mass centers is greater or
3272 equal to \*lowerBound (it means that the signatures are far enough), the function does not
3273 calculate EMD. In any case \*lowerBound is set to the calculated distance between mass centers on
3274 return. Thus, if you want to calculate both distance between mass centers and EMD, \*lowerBound
3276 @param flow Resultant \f$\texttt{size1} \times \texttt{size2}\f$ flow matrix: \f$\texttt{flow}_{i,j}\f$ is
3277 a flow from \f$i\f$ -th point of signature1 to \f$j\f$ -th point of signature2 .
3279 CV_EXPORTS float EMD( InputArray signature1, InputArray signature2,
3280 int distType, InputArray cost=noArray(),
3281 float* lowerBound = 0, OutputArray flow = noArray() );
3283 CV_EXPORTS_AS(EMD) float wrapperEMD( InputArray signature1, InputArray signature2,
3284 int distType, InputArray cost=noArray(),
3285 CV_IN_OUT Ptr<float> lowerBound = Ptr<float>(), OutputArray flow = noArray() );
3289 /** @example watershed.cpp
3290 An example using the watershed algorithm
3293 /** @brief Performs a marker-based image segmentation using the watershed algorithm.
3295 The function implements one of the variants of watershed, non-parametric marker-based segmentation
3296 algorithm, described in @cite Meyer92 .
3298 Before passing the image to the function, you have to roughly outline the desired regions in the
3299 image markers with positive (\>0) indices. So, every region is represented as one or more connected
3300 components with the pixel values 1, 2, 3, and so on. Such markers can be retrieved from a binary
3301 mask using findContours and drawContours (see the watershed.cpp demo). The markers are "seeds" of
3302 the future image regions. All the other pixels in markers , whose relation to the outlined regions
3303 is not known and should be defined by the algorithm, should be set to 0's. In the function output,
3304 each pixel in markers is set to a value of the "seed" components or to -1 at boundaries between the
3307 @note Any two neighbor connected components are not necessarily separated by a watershed boundary
3308 (-1's pixels); for example, they can touch each other in the initial marker image passed to the
3311 @param image Input 8-bit 3-channel image.
3312 @param markers Input/output 32-bit single-channel image (map) of markers. It should have the same
3317 @ingroup imgproc_misc
3319 CV_EXPORTS_W void watershed( InputArray image, InputOutputArray markers );
3321 //! @addtogroup imgproc_filter
3324 /** @brief Performs initial step of meanshift segmentation of an image.
3326 The function implements the filtering stage of meanshift segmentation, that is, the output of the
3327 function is the filtered "posterized" image with color gradients and fine-grain texture flattened.
3328 At every pixel (X,Y) of the input image (or down-sized input image, see below) the function executes
3329 meanshift iterations, that is, the pixel (X,Y) neighborhood in the joint space-color hyperspace is
3332 \f[(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}\f]
3334 where (R,G,B) and (r,g,b) are the vectors of color components at (X,Y) and (x,y), respectively
3335 (though, the algorithm does not depend on the color space used, so any 3-component color space can
3336 be used instead). Over the neighborhood the average spatial value (X',Y') and average color vector
3337 (R',G',B') are found and they act as the neighborhood center on the next iteration:
3339 \f[(X,Y)~(X',Y'), (R,G,B)~(R',G',B').\f]
3341 After the iterations over, the color components of the initial pixel (that is, the pixel from where
3342 the iterations started) are set to the final value (average color at the last iteration):
3344 \f[I(X,Y) <- (R*,G*,B*)\f]
3346 When maxLevel \> 0, the gaussian pyramid of maxLevel+1 levels is built, and the above procedure is
3347 run on the smallest layer first. After that, the results are propagated to the larger layer and the
3348 iterations are run again only on those pixels where the layer colors differ by more than sr from the
3349 lower-resolution layer of the pyramid. That makes boundaries of color regions sharper. Note that the
3350 results will be actually different from the ones obtained by running the meanshift procedure on the
3351 whole original image (i.e. when maxLevel==0).
3353 @param src The source 8-bit, 3-channel image.
3354 @param dst The destination image of the same format and the same size as the source.
3355 @param sp The spatial window radius.
3356 @param sr The color window radius.
3357 @param maxLevel Maximum level of the pyramid for the segmentation.
3358 @param termcrit Termination criteria: when to stop meanshift iterations.
3360 CV_EXPORTS_W void pyrMeanShiftFiltering( InputArray src, OutputArray dst,
3361 double sp, double sr, int maxLevel = 1,
3362 TermCriteria termcrit=TermCriteria(TermCriteria::MAX_ITER+TermCriteria::EPS,5,1) );
3366 //! @addtogroup imgproc_misc
3369 /** @example grabcut.cpp
3370 An example using the GrabCut algorithm
3373 /** @brief Runs the GrabCut algorithm.
3375 The function implements the [GrabCut image segmentation algorithm](http://en.wikipedia.org/wiki/GrabCut).
3377 @param img Input 8-bit 3-channel image.
3378 @param mask Input/output 8-bit single-channel mask. The mask is initialized by the function when
3379 mode is set to GC_INIT_WITH_RECT. Its elements may have one of the cv::GrabCutClasses.
3380 @param rect ROI containing a segmented object. The pixels outside of the ROI are marked as
3381 "obvious background". The parameter is only used when mode==GC_INIT_WITH_RECT .
3382 @param bgdModel Temporary array for the background model. Do not modify it while you are
3383 processing the same image.
3384 @param fgdModel Temporary arrays for the foreground model. Do not modify it while you are
3385 processing the same image.
3386 @param iterCount Number of iterations the algorithm should make before returning the result. Note
3387 that the result can be refined with further calls with mode==GC_INIT_WITH_MASK or
3389 @param mode Operation mode that could be one of the cv::GrabCutModes
3391 CV_EXPORTS_W void grabCut( InputArray img, InputOutputArray mask, Rect rect,
3392 InputOutputArray bgdModel, InputOutputArray fgdModel,
3393 int iterCount, int mode = GC_EVAL );
3395 /** @example distrans.cpp
3396 An example on using the distance transform\
3400 /** @brief Calculates the distance to the closest zero pixel for each pixel of the source image.
3402 The function cv::distanceTransform calculates the approximate or precise distance from every binary
3403 image pixel to the nearest zero pixel. For zero image pixels, the distance will obviously be zero.
3405 When maskSize == DIST_MASK_PRECISE and distanceType == DIST_L2 , the function runs the
3406 algorithm described in @cite Felzenszwalb04 . This algorithm is parallelized with the TBB library.
3408 In other cases, the algorithm @cite Borgefors86 is used. This means that for a pixel the function
3409 finds the shortest path to the nearest zero pixel consisting of basic shifts: horizontal, vertical,
3410 diagonal, or knight's move (the latest is available for a \f$5\times 5\f$ mask). The overall
3411 distance is calculated as a sum of these basic distances. Since the distance function should be
3412 symmetric, all of the horizontal and vertical shifts must have the same cost (denoted as a ), all
3413 the diagonal shifts must have the same cost (denoted as `b`), and all knight's moves must have the
3414 same cost (denoted as `c`). For the cv::DIST_C and cv::DIST_L1 types, the distance is calculated
3415 precisely, whereas for cv::DIST_L2 (Euclidean distance) the distance can be calculated only with a
3416 relative error (a \f$5\times 5\f$ mask gives more accurate results). For `a`,`b`, and `c`, OpenCV
3417 uses the values suggested in the original paper:
3418 - DIST_L1: `a = 1, b = 2`
3420 - `3 x 3`: `a=0.955, b=1.3693`
3421 - `5 x 5`: `a=1, b=1.4, c=2.1969`
3422 - DIST_C: `a = 1, b = 1`
3424 Typically, for a fast, coarse distance estimation DIST_L2, a \f$3\times 3\f$ mask is used. For a
3425 more accurate distance estimation DIST_L2, a \f$5\times 5\f$ mask or the precise algorithm is used.
3426 Note that both the precise and the approximate algorithms are linear on the number of pixels.
3428 This variant of the function does not only compute the minimum distance for each pixel \f$(x, y)\f$
3429 but also identifies the nearest connected component consisting of zero pixels
3430 (labelType==DIST_LABEL_CCOMP) or the nearest zero pixel (labelType==DIST_LABEL_PIXEL). Index of the
3431 component/pixel is stored in `labels(x, y)`. When labelType==DIST_LABEL_CCOMP, the function
3432 automatically finds connected components of zero pixels in the input image and marks them with
3433 distinct labels. When labelType==DIST_LABEL_CCOMP, the function scans through the input image and
3434 marks all the zero pixels with distinct labels.
3436 In this mode, the complexity is still linear. That is, the function provides a very fast way to
3437 compute the Voronoi diagram for a binary image. Currently, the second variant can use only the
3438 approximate distance transform algorithm, i.e. maskSize=DIST_MASK_PRECISE is not supported
3441 @param src 8-bit, single-channel (binary) source image.
3442 @param dst Output image with calculated distances. It is a 8-bit or 32-bit floating-point,
3443 single-channel image of the same size as src.
3444 @param labels Output 2D array of labels (the discrete Voronoi diagram). It has the type
3445 CV_32SC1 and the same size as src.
3446 @param distanceType Type of distance, see cv::DistanceTypes
3447 @param maskSize Size of the distance transform mask, see cv::DistanceTransformMasks.
3448 DIST_MASK_PRECISE is not supported by this variant. In case of the DIST_L1 or DIST_C distance type,
3449 the parameter is forced to 3 because a \f$3\times 3\f$ mask gives the same result as \f$5\times
3450 5\f$ or any larger aperture.
3451 @param labelType Type of the label array to build, see cv::DistanceTransformLabelTypes.
3453 CV_EXPORTS_AS(distanceTransformWithLabels) void distanceTransform( InputArray src, OutputArray dst,
3454 OutputArray labels, int distanceType, int maskSize,
3455 int labelType = DIST_LABEL_CCOMP );
3458 @param src 8-bit, single-channel (binary) source image.
3459 @param dst Output image with calculated distances. It is a 8-bit or 32-bit floating-point,
3460 single-channel image of the same size as src .
3461 @param distanceType Type of distance, see cv::DistanceTypes
3462 @param maskSize Size of the distance transform mask, see cv::DistanceTransformMasks. In case of the
3463 DIST_L1 or DIST_C distance type, the parameter is forced to 3 because a \f$3\times 3\f$ mask gives
3464 the same result as \f$5\times 5\f$ or any larger aperture.
3465 @param dstType Type of output image. It can be CV_8U or CV_32F. Type CV_8U can be used only for
3466 the first variant of the function and distanceType == DIST_L1.
3468 CV_EXPORTS_W void distanceTransform( InputArray src, OutputArray dst,
3469 int distanceType, int maskSize, int dstType=CV_32F);
3471 /** @example ffilldemo.cpp
3472 An example using the FloodFill technique
3477 variant without `mask` parameter
3479 CV_EXPORTS int floodFill( InputOutputArray image,
3480 Point seedPoint, Scalar newVal, CV_OUT Rect* rect = 0,
3481 Scalar loDiff = Scalar(), Scalar upDiff = Scalar(),
3484 /** @brief Fills a connected component with the given color.
3486 The function cv::floodFill fills a connected component starting from the seed point with the specified
3487 color. The connectivity is determined by the color/brightness closeness of the neighbor pixels. The
3488 pixel at \f$(x,y)\f$ is considered to belong to the repainted domain if:
3490 - in case of a grayscale image and floating range
3491 \f[\texttt{src} (x',y')- \texttt{loDiff} \leq \texttt{src} (x,y) \leq \texttt{src} (x',y')+ \texttt{upDiff}\f]
3494 - in case of a grayscale image and fixed range
3495 \f[\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}\f]
3498 - in case of a color image and floating range
3499 \f[\texttt{src} (x',y')_r- \texttt{loDiff} _r \leq \texttt{src} (x,y)_r \leq \texttt{src} (x',y')_r+ \texttt{upDiff} _r,\f]
3500 \f[\texttt{src} (x',y')_g- \texttt{loDiff} _g \leq \texttt{src} (x,y)_g \leq \texttt{src} (x',y')_g+ \texttt{upDiff} _g\f]
3502 \f[\texttt{src} (x',y')_b- \texttt{loDiff} _b \leq \texttt{src} (x,y)_b \leq \texttt{src} (x',y')_b+ \texttt{upDiff} _b\f]
3505 - in case of a color image and fixed range
3506 \f[\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,\f]
3507 \f[\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\f]
3509 \f[\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\f]
3512 where \f$src(x',y')\f$ is the value of one of pixel neighbors that is already known to belong to the
3513 component. That is, to be added to the connected component, a color/brightness of the pixel should
3515 - Color/brightness of one of its neighbors that already belong to the connected component in case
3516 of a floating range.
3517 - Color/brightness of the seed point in case of a fixed range.
3519 Use these functions to either mark a connected component with the specified color in-place, or build
3520 a mask and then extract the contour, or copy the region to another image, and so on.
3522 @param image Input/output 1- or 3-channel, 8-bit, or floating-point image. It is modified by the
3523 function unless the FLOODFILL_MASK_ONLY flag is set in the second variant of the function. See
3525 @param mask Operation mask that should be a single-channel 8-bit image, 2 pixels wider and 2 pixels
3526 taller than image. Since this is both an input and output parameter, you must take responsibility
3527 of initializing it. Flood-filling cannot go across non-zero pixels in the input mask. For example,
3528 an edge detector output can be used as a mask to stop filling at edges. On output, pixels in the
3529 mask corresponding to filled pixels in the image are set to 1 or to the a value specified in flags
3530 as described below. It is therefore possible to use the same mask in multiple calls to the function
3531 to make sure the filled areas do not overlap.
3532 @param seedPoint Starting point.
3533 @param newVal New value of the repainted domain pixels.
3534 @param loDiff Maximal lower brightness/color difference between the currently observed pixel and
3535 one of its neighbors belonging to the component, or a seed pixel being added to the component.
3536 @param upDiff Maximal upper brightness/color difference between the currently observed pixel and
3537 one of its neighbors belonging to the component, or a seed pixel being added to the component.
3538 @param rect Optional output parameter set by the function to the minimum bounding rectangle of the
3540 @param flags Operation flags. The first 8 bits contain a connectivity value. The default value of
3541 4 means that only the four nearest neighbor pixels (those that share an edge) are considered. A
3542 connectivity value of 8 means that the eight nearest neighbor pixels (those that share a corner)
3543 will be considered. The next 8 bits (8-16) contain a value between 1 and 255 with which to fill
3544 the mask (the default value is 1). For example, 4 | ( 255 \<\< 8 ) will consider 4 nearest
3545 neighbours and fill the mask with a value of 255. The following additional options occupy higher
3546 bits and therefore may be further combined with the connectivity and mask fill values using
3547 bit-wise or (|), see cv::FloodFillFlags.
3549 @note Since the mask is larger than the filled image, a pixel \f$(x, y)\f$ in image corresponds to the
3550 pixel \f$(x+1, y+1)\f$ in the mask .
3554 CV_EXPORTS_W int floodFill( InputOutputArray image, InputOutputArray mask,
3555 Point seedPoint, Scalar newVal, CV_OUT Rect* rect=0,
3556 Scalar loDiff = Scalar(), Scalar upDiff = Scalar(),
3559 /** @brief Converts an image from one color space to another.
3561 The function converts an input image from one color space to another. In case of a transformation
3562 to-from RGB color space, the order of the channels should be specified explicitly (RGB or BGR). Note
3563 that the default color format in OpenCV is often referred to as RGB but it is actually BGR (the
3564 bytes are reversed). So the first byte in a standard (24-bit) color image will be an 8-bit Blue
3565 component, the second byte will be Green, and the third byte will be Red. The fourth, fifth, and
3566 sixth bytes would then be the second pixel (Blue, then Green, then Red), and so on.
3568 The conventional ranges for R, G, and B channel values are:
3569 - 0 to 255 for CV_8U images
3570 - 0 to 65535 for CV_16U images
3571 - 0 to 1 for CV_32F images
3573 In case of linear transformations, the range does not matter. But in case of a non-linear
3574 transformation, an input RGB image should be normalized to the proper value range to get the correct
3575 results, for example, for RGB \f$\rightarrow\f$ L\*u\*v\* transformation. For example, if you have a
3576 32-bit floating-point image directly converted from an 8-bit image without any scaling, then it will
3577 have the 0..255 value range instead of 0..1 assumed by the function. So, before calling cvtColor ,
3578 you need first to scale the image down:
3581 cvtColor(img, img, COLOR_BGR2Luv);
3583 If you use cvtColor with 8-bit images, the conversion will have some information lost. For many
3584 applications, this will not be noticeable but it is recommended to use 32-bit images in applications
3585 that need the full range of colors or that convert an image before an operation and then convert
3588 If conversion adds the alpha channel, its value will set to the maximum of corresponding channel
3589 range: 255 for CV_8U, 65535 for CV_16U, 1 for CV_32F.
3591 @param src input image: 8-bit unsigned, 16-bit unsigned ( CV_16UC... ), or single-precision
3593 @param dst output image of the same size and depth as src.
3594 @param code color space conversion code (see cv::ColorConversionCodes).
3595 @param dstCn number of channels in the destination image; if the parameter is 0, the number of the
3596 channels is derived automatically from src and code.
3598 @see @ref imgproc_color_conversions
3600 CV_EXPORTS_W void cvtColor( InputArray src, OutputArray dst, int code, int dstCn = 0 );
3604 // main function for all demosaicing processes
3605 CV_EXPORTS_W void demosaicing(InputArray _src, OutputArray _dst, int code, int dcn = 0);
3607 //! @addtogroup imgproc_shape
3610 /** @brief Calculates all of the moments up to the third order of a polygon or rasterized shape.
3612 The function computes moments, up to the 3rd order, of a vector shape or a rasterized shape. The
3613 results are returned in the structure cv::Moments.
3615 @param array Raster image (single-channel, 8-bit or floating-point 2D array) or an array (
3616 \f$1 \times N\f$ or \f$N \times 1\f$ ) of 2D points (Point or Point2f ).
3617 @param binaryImage If it is true, all non-zero image pixels are treated as 1's. The parameter is
3618 used for images only.
3621 @note Only applicable to contour moments calculations from Python bindings: Note that the numpy
3622 type for the input array should be either np.int32 or np.float32.
3624 @sa contourArea, arcLength
3626 CV_EXPORTS_W Moments moments( InputArray array, bool binaryImage = false );
3628 /** @brief Calculates seven Hu invariants.
3630 The function calculates seven Hu invariants (introduced in @cite Hu62; see also
3631 <http://en.wikipedia.org/wiki/Image_moment>) defined as:
3633 \f[\begin{array}{l} hu[0]= \eta _{20}+ \eta _{02} \\ hu[1]=( \eta _{20}- \eta _{02})^{2}+4 \eta _{11}^{2} \\ hu[2]=( \eta _{30}-3 \eta _{12})^{2}+ (3 \eta _{21}- \eta _{03})^{2} \\ hu[3]=( \eta _{30}+ \eta _{12})^{2}+ ( \eta _{21}+ \eta _{03})^{2} \\ hu[4]=( \eta _{30}-3 \eta _{12})( \eta _{30}+ \eta _{12})[( \eta _{30}+ \eta _{12})^{2}-3( \eta _{21}+ \eta _{03})^{2}]+(3 \eta _{21}- \eta _{03})( \eta _{21}+ \eta _{03})[3( \eta _{30}+ \eta _{12})^{2}-( \eta _{21}+ \eta _{03})^{2}] \\ hu[5]=( \eta _{20}- \eta _{02})[( \eta _{30}+ \eta _{12})^{2}- ( \eta _{21}+ \eta _{03})^{2}]+4 \eta _{11}( \eta _{30}+ \eta _{12})( \eta _{21}+ \eta _{03}) \\ hu[6]=(3 \eta _{21}- \eta _{03})( \eta _{21}+ \eta _{03})[3( \eta _{30}+ \eta _{12})^{2}-( \eta _{21}+ \eta _{03})^{2}]-( \eta _{30}-3 \eta _{12})( \eta _{21}+ \eta _{03})[3( \eta _{30}+ \eta _{12})^{2}-( \eta _{21}+ \eta _{03})^{2}] \\ \end{array}\f]
3635 where \f$\eta_{ji}\f$ stands for \f$\texttt{Moments::nu}_{ji}\f$ .
3637 These values are proved to be invariants to the image scale, rotation, and reflection except the
3638 seventh one, whose sign is changed by reflection. This invariance is proved with the assumption of
3639 infinite image resolution. In case of raster images, the computed Hu invariants for the original and
3640 transformed images are a bit different.
3642 @param moments Input moments computed with moments .
3643 @param hu Output Hu invariants.
3647 CV_EXPORTS void HuMoments( const Moments& moments, double hu[7] );
3650 CV_EXPORTS_W void HuMoments( const Moments& m, OutputArray hu );
3652 //! @} imgproc_shape
3654 //! @addtogroup imgproc_object
3657 //! type of the template matching operation
3658 enum TemplateMatchModes {
3659 TM_SQDIFF = 0, //!< \f[R(x,y)= \sum _{x',y'} (T(x',y')-I(x+x',y+y'))^2\f]
3660 TM_SQDIFF_NORMED = 1, //!< \f[R(x,y)= \frac{\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}\f]
3661 TM_CCORR = 2, //!< \f[R(x,y)= \sum _{x',y'} (T(x',y') \cdot I(x+x',y+y'))\f]
3662 TM_CCORR_NORMED = 3, //!< \f[R(x,y)= \frac{\sum_{x',y'} (T(x',y') \cdot I(x+x',y+y'))}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}\f]
3663 TM_CCOEFF = 4, //!< \f[R(x,y)= \sum _{x',y'} (T'(x',y') \cdot I'(x+x',y+y'))\f]
3665 //!< \f[\begin{array}{l} T'(x',y')=T(x',y') - 1/(w \cdot h) \cdot \sum _{x'',y''} T(x'',y'') \\ I'(x+x',y+y')=I(x+x',y+y') - 1/(w \cdot h) \cdot \sum _{x'',y''} I(x+x'',y+y'') \end{array}\f]
3666 TM_CCOEFF_NORMED = 5 //!< \f[R(x,y)= \frac{ \sum_{x',y'} (T'(x',y') \cdot I'(x+x',y+y')) }{ \sqrt{\sum_{x',y'}T'(x',y')^2 \cdot \sum_{x',y'} I'(x+x',y+y')^2} }\f]
3669 /** @brief Compares a template against overlapped image regions.
3671 The function slides through image , compares the overlapped patches of size \f$w \times h\f$ against
3672 templ using the specified method and stores the comparison results in result . Here are the formulae
3673 for the available comparison methods ( \f$I\f$ denotes image, \f$T\f$ template, \f$R\f$ result ). The summation
3674 is done over template and/or the image patch: \f$x' = 0...w-1, y' = 0...h-1\f$
3676 After the function finishes the comparison, the best matches can be found as global minimums (when
3677 TM_SQDIFF was used) or maximums (when TM_CCORR or TM_CCOEFF was used) using the
3678 minMaxLoc function. In case of a color image, template summation in the numerator and each sum in
3679 the denominator is done over all of the channels and separate mean values are used for each channel.
3680 That is, the function can take a color template and a color image. The result will still be a
3681 single-channel image, which is easier to analyze.
3683 @param image Image where the search is running. It must be 8-bit or 32-bit floating-point.
3684 @param templ Searched template. It must be not greater than the source image and have the same
3686 @param result Map of comparison results. It must be single-channel 32-bit floating-point. If image
3687 is \f$W \times H\f$ and templ is \f$w \times h\f$ , then result is \f$(W-w+1) \times (H-h+1)\f$ .
3688 @param method Parameter specifying the comparison method, see cv::TemplateMatchModes
3689 @param mask Mask of searched template. It must have the same datatype and size with templ. It is
3692 CV_EXPORTS_W void matchTemplate( InputArray image, InputArray templ,
3693 OutputArray result, int method, InputArray mask = noArray() );
3697 //! @addtogroup imgproc_shape
3700 /** @brief computes the connected components labeled image of boolean image
3702 image with 4 or 8 way connectivity - returns N, the total number of labels [0, N-1] where 0
3703 represents the background label. ltype specifies the output label image type, an important
3704 consideration based on the total number of labels or alternatively the total number of pixels in
3705 the source image. ccltype specifies the connected components labeling algorithm to use, currently
3706 Grana's (BBDT) and Wu's (SAUF) algorithms are supported, see the cv::ConnectedComponentsAlgorithmsTypes
3707 for details. Note that SAUF algorithm forces a row major ordering of labels while BBDT does not.
3709 @param image the 8-bit single-channel image to be labeled
3710 @param labels destination labeled image
3711 @param connectivity 8 or 4 for 8-way or 4-way connectivity respectively
3712 @param ltype output image label type. Currently CV_32S and CV_16U are supported.
3713 @param ccltype connected components algorithm type (see the cv::ConnectedComponentsAlgorithmsTypes).
3715 CV_EXPORTS_AS(connectedComponentsWithAlgorithm) int connectedComponents(InputArray image, OutputArray labels,
3716 int connectivity, int ltype, int ccltype);
3721 @param image the 8-bit single-channel image to be labeled
3722 @param labels destination labeled image
3723 @param connectivity 8 or 4 for 8-way or 4-way connectivity respectively
3724 @param ltype output image label type. Currently CV_32S and CV_16U are supported.
3726 CV_EXPORTS_W int connectedComponents(InputArray image, OutputArray labels,
3727 int connectivity = 8, int ltype = CV_32S);
3730 /** @brief computes the connected components labeled image of boolean image and also produces a statistics output for each label
3732 image with 4 or 8 way connectivity - returns N, the total number of labels [0, N-1] where 0
3733 represents the background label. ltype specifies the output label image type, an important
3734 consideration based on the total number of labels or alternatively the total number of pixels in
3735 the source image. ccltype specifies the connected components labeling algorithm to use, currently
3736 Grana's (BBDT) and Wu's (SAUF) algorithms are supported, see the cv::ConnectedComponentsAlgorithmsTypes
3737 for details. Note that SAUF algorithm forces a row major ordering of labels while BBDT does not.
3740 @param image the 8-bit single-channel image to be labeled
3741 @param labels destination labeled image
3742 @param stats statistics output for each label, including the background label, see below for
3743 available statistics. Statistics are accessed via stats(label, COLUMN) where COLUMN is one of
3744 cv::ConnectedComponentsTypes. The data type is CV_32S.
3745 @param centroids centroid output for each label, including the background label. Centroids are
3746 accessed via centroids(label, 0) for x and centroids(label, 1) for y. The data type CV_64F.
3747 @param connectivity 8 or 4 for 8-way or 4-way connectivity respectively
3748 @param ltype output image label type. Currently CV_32S and CV_16U are supported.
3749 @param ccltype connected components algorithm type (see the cv::ConnectedComponentsAlgorithmsTypes).
3751 CV_EXPORTS_AS(connectedComponentsWithStatsWithAlgorithm) int connectedComponentsWithStats(InputArray image, OutputArray labels,
3752 OutputArray stats, OutputArray centroids,
3753 int connectivity, int ltype, int ccltype);
3756 @param image the 8-bit single-channel image to be labeled
3757 @param labels destination labeled image
3758 @param stats statistics output for each label, including the background label, see below for
3759 available statistics. Statistics are accessed via stats(label, COLUMN) where COLUMN is one of
3760 cv::ConnectedComponentsTypes. The data type is CV_32S.
3761 @param centroids centroid output for each label, including the background label. Centroids are
3762 accessed via centroids(label, 0) for x and centroids(label, 1) for y. The data type CV_64F.
3763 @param connectivity 8 or 4 for 8-way or 4-way connectivity respectively
3764 @param ltype output image label type. Currently CV_32S and CV_16U are supported.
3766 CV_EXPORTS_W int connectedComponentsWithStats(InputArray image, OutputArray labels,
3767 OutputArray stats, OutputArray centroids,
3768 int connectivity = 8, int ltype = CV_32S);
3771 /** @brief Finds contours in a binary image.
3773 The function retrieves contours from the binary image using the algorithm @cite Suzuki85 . The contours
3774 are a useful tool for shape analysis and object detection and recognition. See squares.cpp in the
3775 OpenCV sample directory.
3776 @note Since opencv 3.2 source image is not modified by this function.
3778 @param image Source, an 8-bit single-channel image. Non-zero pixels are treated as 1's. Zero
3779 pixels remain 0's, so the image is treated as binary . You can use cv::compare, cv::inRange, cv::threshold ,
3780 cv::adaptiveThreshold, cv::Canny, and others to create a binary image out of a grayscale or color one.
3781 If mode equals to cv::RETR_CCOMP or cv::RETR_FLOODFILL, the input can also be a 32-bit integer image of labels (CV_32SC1).
3782 @param contours Detected contours. Each contour is stored as a vector of points (e.g.
3783 std::vector<std::vector<cv::Point> >).
3784 @param hierarchy Optional output vector (e.g. std::vector<cv::Vec4i>), containing information about the image topology. It has
3785 as many elements as the number of contours. For each i-th contour contours[i], the elements
3786 hierarchy[i][0] , hierarchy[i][1] , hierarchy[i][2] , and hierarchy[i][3] are set to 0-based indices
3787 in contours of the next and previous contours at the same hierarchical level, the first child
3788 contour and the parent contour, respectively. If for the contour i there are no next, previous,
3789 parent, or nested contours, the corresponding elements of hierarchy[i] will be negative.
3790 @param mode Contour retrieval mode, see cv::RetrievalModes
3791 @param method Contour approximation method, see cv::ContourApproximationModes
3792 @param offset Optional offset by which every contour point is shifted. This is useful if the
3793 contours are extracted from the image ROI and then they should be analyzed in the whole image
3796 CV_EXPORTS_W void findContours( InputOutputArray image, OutputArrayOfArrays contours,
3797 OutputArray hierarchy, int mode,
3798 int method, Point offset = Point());
3801 CV_EXPORTS void findContours( InputOutputArray image, OutputArrayOfArrays contours,
3802 int mode, int method, Point offset = Point());
3804 /** @brief Approximates a polygonal curve(s) with the specified precision.
3806 The function cv::approxPolyDP approximates a curve or a polygon with another curve/polygon with less
3807 vertices so that the distance between them is less or equal to the specified precision. It uses the
3808 Douglas-Peucker algorithm <http://en.wikipedia.org/wiki/Ramer-Douglas-Peucker_algorithm>
3810 @param curve Input vector of a 2D point stored in std::vector or Mat
3811 @param approxCurve Result of the approximation. The type should match the type of the input curve.
3812 @param epsilon Parameter specifying the approximation accuracy. This is the maximum distance
3813 between the original curve and its approximation.
3814 @param closed If true, the approximated curve is closed (its first and last vertices are
3815 connected). Otherwise, it is not closed.
3817 CV_EXPORTS_W void approxPolyDP( InputArray curve,
3818 OutputArray approxCurve,
3819 double epsilon, bool closed );
3821 /** @brief Calculates a contour perimeter or a curve length.
3823 The function computes a curve length or a closed contour perimeter.
3825 @param curve Input vector of 2D points, stored in std::vector or Mat.
3826 @param closed Flag indicating whether the curve is closed or not.
3828 CV_EXPORTS_W double arcLength( InputArray curve, bool closed );
3830 /** @brief Calculates the up-right bounding rectangle of a point set.
3832 The function calculates and returns the minimal up-right bounding rectangle for the specified point set.
3834 @param points Input 2D point set, stored in std::vector or Mat.
3836 CV_EXPORTS_W Rect boundingRect( InputArray points );
3838 /** @brief Calculates a contour area.
3840 The function computes a contour area. Similarly to moments , the area is computed using the Green
3841 formula. Thus, the returned area and the number of non-zero pixels, if you draw the contour using
3842 drawContours or fillPoly , can be different. Also, the function will most certainly give a wrong
3843 results for contours with self-intersections.
3847 vector<Point> contour;
3848 contour.push_back(Point2f(0, 0));
3849 contour.push_back(Point2f(10, 0));
3850 contour.push_back(Point2f(10, 10));
3851 contour.push_back(Point2f(5, 4));
3853 double area0 = contourArea(contour);
3854 vector<Point> approx;
3855 approxPolyDP(contour, approx, 5, true);
3856 double area1 = contourArea(approx);
3858 cout << "area0 =" << area0 << endl <<
3859 "area1 =" << area1 << endl <<
3860 "approx poly vertices" << approx.size() << endl;
3862 @param contour Input vector of 2D points (contour vertices), stored in std::vector or Mat.
3863 @param oriented Oriented area flag. If it is true, the function returns a signed area value,
3864 depending on the contour orientation (clockwise or counter-clockwise). Using this feature you can
3865 determine orientation of a contour by taking the sign of an area. By default, the parameter is
3866 false, which means that the absolute value is returned.
3868 CV_EXPORTS_W double contourArea( InputArray contour, bool oriented = false );
3870 /** @brief Finds a rotated rectangle of the minimum area enclosing the input 2D point set.
3872 The function calculates and returns the minimum-area bounding rectangle (possibly rotated) for a
3873 specified point set. See the OpenCV sample minarea.cpp . Developer should keep in mind that the
3874 returned rotatedRect can contain negative indices when data is close to the containing Mat element
3877 @param points Input vector of 2D points, stored in std::vector\<\> or Mat
3879 CV_EXPORTS_W RotatedRect minAreaRect( InputArray points );
3881 /** @brief Finds the four vertices of a rotated rect. Useful to draw the rotated rectangle.
3883 The function finds the four vertices of a rotated rectangle. This function is useful to draw the
3884 rectangle. In C++, instead of using this function, you can directly use box.points() method. Please
3885 visit the [tutorial on bounding
3886 rectangle](http://docs.opencv.org/doc/tutorials/imgproc/shapedescriptors/bounding_rects_circles/bounding_rects_circles.html#bounding-rects-circles)
3887 for more information.
3889 @param box The input rotated rectangle. It may be the output of
3890 @param points The output array of four vertices of rectangles.
3892 CV_EXPORTS_W void boxPoints(RotatedRect box, OutputArray points);
3894 /** @brief Finds a circle of the minimum area enclosing a 2D point set.
3896 The function finds the minimal enclosing circle of a 2D point set using an iterative algorithm. See
3897 the OpenCV sample minarea.cpp .
3899 @param points Input vector of 2D points, stored in std::vector\<\> or Mat
3900 @param center Output center of the circle.
3901 @param radius Output radius of the circle.
3903 CV_EXPORTS_W void minEnclosingCircle( InputArray points,
3904 CV_OUT Point2f& center, CV_OUT float& radius );
3906 /** @example minarea.cpp
3909 /** @brief Finds a triangle of minimum area enclosing a 2D point set and returns its area.
3911 The function finds a triangle of minimum area enclosing the given set of 2D points and returns its
3912 area. The output for a given 2D point set is shown in the image below. 2D points are depicted in
3913 *red* and the enclosing triangle in *yellow*.
3915 ![Sample output of the minimum enclosing triangle function](pics/minenclosingtriangle.png)
3917 The implementation of the algorithm is based on O'Rourke's @cite ORourke86 and Klee and Laskowski's
3918 @cite KleeLaskowski85 papers. O'Rourke provides a \f$\theta(n)\f$ algorithm for finding the minimal
3919 enclosing triangle of a 2D convex polygon with n vertices. Since the minEnclosingTriangle function
3920 takes a 2D point set as input an additional preprocessing step of computing the convex hull of the
3921 2D point set is required. The complexity of the convexHull function is \f$O(n log(n))\f$ which is higher
3922 than \f$\theta(n)\f$. Thus the overall complexity of the function is \f$O(n log(n))\f$.
3924 @param points Input vector of 2D points with depth CV_32S or CV_32F, stored in std::vector\<\> or Mat
3925 @param triangle Output vector of three 2D points defining the vertices of the triangle. The depth
3926 of the OutputArray must be CV_32F.
3928 CV_EXPORTS_W double minEnclosingTriangle( InputArray points, CV_OUT OutputArray triangle );
3930 /** @brief Compares two shapes.
3932 The function compares two shapes. All three implemented methods use the Hu invariants (see cv::HuMoments)
3934 @param contour1 First contour or grayscale image.
3935 @param contour2 Second contour or grayscale image.
3936 @param method Comparison method, see cv::ShapeMatchModes
3937 @param parameter Method-specific parameter (not supported now).
3939 CV_EXPORTS_W double matchShapes( InputArray contour1, InputArray contour2,
3940 int method, double parameter );
3942 /** @example convexhull.cpp
3943 An example using the convexHull functionality
3946 /** @brief Finds the convex hull of a point set.
3948 The function cv::convexHull finds the convex hull of a 2D point set using the Sklansky's algorithm @cite Sklansky82
3949 that has *O(N logN)* complexity in the current implementation. See the OpenCV sample convexhull.cpp
3950 that demonstrates the usage of different function variants.
3952 @param points Input 2D point set, stored in std::vector or Mat.
3953 @param hull Output convex hull. It is either an integer vector of indices or vector of points. In
3954 the first case, the hull elements are 0-based indices of the convex hull points in the original
3955 array (since the set of convex hull points is a subset of the original point set). In the second
3956 case, hull elements are the convex hull points themselves.
3957 @param clockwise Orientation flag. If it is true, the output convex hull is oriented clockwise.
3958 Otherwise, it is oriented counter-clockwise. The assumed coordinate system has its X axis pointing
3959 to the right, and its Y axis pointing upwards.
3960 @param returnPoints Operation flag. In case of a matrix, when the flag is true, the function
3961 returns convex hull points. Otherwise, it returns indices of the convex hull points. When the
3962 output array is std::vector, the flag is ignored, and the output depends on the type of the
3963 vector: std::vector\<int\> implies returnPoints=false, std::vector\<Point\> implies
3966 CV_EXPORTS_W void convexHull( InputArray points, OutputArray hull,
3967 bool clockwise = false, bool returnPoints = true );
3969 /** @brief Finds the convexity defects of a contour.
3971 The figure below displays convexity defects of a hand contour:
3973 ![image](pics/defects.png)
3975 @param contour Input contour.
3976 @param convexhull Convex hull obtained using convexHull that should contain indices of the contour
3977 points that make the hull.
3978 @param convexityDefects The output vector of convexity defects. In C++ and the new Python/Java
3979 interface each convexity defect is represented as 4-element integer vector (a.k.a. cv::Vec4i):
3980 (start_index, end_index, farthest_pt_index, fixpt_depth), where indices are 0-based indices
3981 in the original contour of the convexity defect beginning, end and the farthest point, and
3982 fixpt_depth is fixed-point approximation (with 8 fractional bits) of the distance between the
3983 farthest contour point and the hull. That is, to get the floating-point value of the depth will be
3986 CV_EXPORTS_W void convexityDefects( InputArray contour, InputArray convexhull, OutputArray convexityDefects );
3988 /** @brief Tests a contour convexity.
3990 The function tests whether the input contour is convex or not. The contour must be simple, that is,
3991 without self-intersections. Otherwise, the function output is undefined.
3993 @param contour Input vector of 2D points, stored in std::vector\<\> or Mat
3995 CV_EXPORTS_W bool isContourConvex( InputArray contour );
3997 //! finds intersection of two convex polygons
3998 CV_EXPORTS_W float intersectConvexConvex( InputArray _p1, InputArray _p2,
3999 OutputArray _p12, bool handleNested = true );
4001 /** @example fitellipse.cpp
4002 An example using the fitEllipse technique
4005 /** @brief Fits an ellipse around a set of 2D points.
4007 The function calculates the ellipse that fits (in a least-squares sense) a set of 2D points best of
4008 all. It returns the rotated rectangle in which the ellipse is inscribed. The first algorithm described by @cite Fitzgibbon95
4009 is used. Developer should keep in mind that it is possible that the returned
4010 ellipse/rotatedRect data contains negative indices, due to the data points being close to the
4011 border of the containing Mat element.
4013 @param points Input 2D point set, stored in std::vector\<\> or Mat
4015 CV_EXPORTS_W RotatedRect fitEllipse( InputArray points );
4017 /** @brief Fits a line to a 2D or 3D point set.
4019 The function fitLine fits a line to a 2D or 3D point set by minimizing \f$\sum_i \rho(r_i)\f$ where
4020 \f$r_i\f$ is a distance between the \f$i^{th}\f$ point, the line and \f$\rho(r)\f$ is a distance function, one
4023 \f[\rho (r) = r^2/2 \quad \text{(the simplest and the fastest least-squares method)}\f]
4027 \f[\rho (r) = 2 \cdot ( \sqrt{1 + \frac{r^2}{2}} - 1)\f]
4029 \f[\rho \left (r \right ) = C^2 \cdot \left ( \frac{r}{C} - \log{\left(1 + \frac{r}{C}\right)} \right ) \quad \text{where} \quad C=1.3998\f]
4031 \f[\rho \left (r \right ) = \frac{C^2}{2} \cdot \left ( 1 - \exp{\left(-\left(\frac{r}{C}\right)^2\right)} \right ) \quad \text{where} \quad C=2.9846\f]
4033 \f[\rho (r) = \fork{r^2/2}{if \(r < C\)}{C \cdot (r-C/2)}{otherwise} \quad \text{where} \quad C=1.345\f]
4035 The algorithm is based on the M-estimator ( <http://en.wikipedia.org/wiki/M-estimator> ) technique
4036 that iteratively fits the line using the weighted least-squares algorithm. After each iteration the
4037 weights \f$w_i\f$ are adjusted to be inversely proportional to \f$\rho(r_i)\f$ .
4039 @param points Input vector of 2D or 3D points, stored in std::vector\<\> or Mat.
4040 @param line Output line parameters. In case of 2D fitting, it should be a vector of 4 elements
4041 (like Vec4f) - (vx, vy, x0, y0), where (vx, vy) is a normalized vector collinear to the line and
4042 (x0, y0) is a point on the line. In case of 3D fitting, it should be a vector of 6 elements (like
4043 Vec6f) - (vx, vy, vz, x0, y0, z0), where (vx, vy, vz) is a normalized vector collinear to the line
4044 and (x0, y0, z0) is a point on the line.
4045 @param distType Distance used by the M-estimator, see cv::DistanceTypes
4046 @param param Numerical parameter ( C ) for some types of distances. If it is 0, an optimal value
4048 @param reps Sufficient accuracy for the radius (distance between the coordinate origin and the line).
4049 @param aeps Sufficient accuracy for the angle. 0.01 would be a good default value for reps and aeps.
4051 CV_EXPORTS_W void fitLine( InputArray points, OutputArray line, int distType,
4052 double param, double reps, double aeps );
4054 /** @brief Performs a point-in-contour test.
4056 The function determines whether the point is inside a contour, outside, or lies on an edge (or
4057 coincides with a vertex). It returns positive (inside), negative (outside), or zero (on an edge)
4058 value, correspondingly. When measureDist=false , the return value is +1, -1, and 0, respectively.
4059 Otherwise, the return value is a signed distance between the point and the nearest contour edge.
4061 See below a sample output of the function where each image pixel is tested against the contour:
4063 ![sample output](pics/pointpolygon.png)
4065 @param contour Input contour.
4066 @param pt Point tested against the contour.
4067 @param measureDist If true, the function estimates the signed distance from the point to the
4068 nearest contour edge. Otherwise, the function only checks if the point is inside a contour or not.
4070 CV_EXPORTS_W double pointPolygonTest( InputArray contour, Point2f pt, bool measureDist );
4072 /** @brief Finds out if there is any intersection between two rotated rectangles.
4074 If there is then the vertices of the intersecting region are returned as well.
4076 Below are some examples of intersection configurations. The hatched pattern indicates the
4077 intersecting region and the red vertices are returned by the function.
4079 ![intersection examples](pics/intersection.png)
4081 @param rect1 First rectangle
4082 @param rect2 Second rectangle
4083 @param intersectingRegion The output array of the verticies of the intersecting region. It returns
4084 at most 8 vertices. Stored as std::vector\<cv::Point2f\> or cv::Mat as Mx1 of type CV_32FC2.
4085 @returns One of cv::RectanglesIntersectTypes
4087 CV_EXPORTS_W int rotatedRectangleIntersection( const RotatedRect& rect1, const RotatedRect& rect2, OutputArray intersectingRegion );
4089 //! @} imgproc_shape
4091 CV_EXPORTS_W Ptr<CLAHE> createCLAHE(double clipLimit = 40.0, Size tileGridSize = Size(8, 8));
4093 //! Ballard, D.H. (1981). Generalizing the Hough transform to detect arbitrary shapes. Pattern Recognition 13 (2): 111-122.
4094 //! Detects position only without translation and rotation
4095 CV_EXPORTS Ptr<GeneralizedHoughBallard> createGeneralizedHoughBallard();
4097 //! Guil, N., González-Linares, J.M. and Zapata, E.L. (1999). Bidimensional shape detection using an invariant approach. Pattern Recognition 32 (6): 1025-1038.
4098 //! Detects position, translation and rotation
4099 CV_EXPORTS Ptr<GeneralizedHoughGuil> createGeneralizedHoughGuil();
4101 //! Performs linear blending of two images:
4102 //! \f[ \texttt{dst}(i,j) = \texttt{weights1}(i,j)*\texttt{src1}(i,j) + \texttt{weights2}(i,j)*\texttt{src2}(i,j) \f]
4103 //! @param src1 It has a type of CV_8UC(n) or CV_32FC(n), where n is a positive integer.
4104 //! @param src2 It has the same type and size as src1.
4105 //! @param weights1 It has a type of CV_32FC1 and the same size with src1.
4106 //! @param weights2 It has a type of CV_32FC1 and the same size with src1.
4107 //! @param dst It is created if it does not have the same size and type with src1.
4108 CV_EXPORTS void blendLinear(InputArray src1, InputArray src2, InputArray weights1, InputArray weights2, OutputArray dst);
4110 //! @addtogroup imgproc_colormap
4113 //! GNU Octave/MATLAB equivalent colormaps
4116 COLORMAP_AUTUMN = 0, //!< ![autumn](pics/colormaps/colorscale_autumn.jpg)
4117 COLORMAP_BONE = 1, //!< ![bone](pics/colormaps/colorscale_bone.jpg)
4118 COLORMAP_JET = 2, //!< ![jet](pics/colormaps/colorscale_jet.jpg)
4119 COLORMAP_WINTER = 3, //!< ![winter](pics/colormaps/colorscale_winter.jpg)
4120 COLORMAP_RAINBOW = 4, //!< ![rainbow](pics/colormaps/colorscale_rainbow.jpg)
4121 COLORMAP_OCEAN = 5, //!< ![ocean](pics/colormaps/colorscale_ocean.jpg)
4122 COLORMAP_SUMMER = 6, //!< ![summer](pics/colormaps/colorscale_summer.jpg)
4123 COLORMAP_SPRING = 7, //!< ![spring](pics/colormaps/colorscale_spring.jpg)
4124 COLORMAP_COOL = 8, //!< ![cool](pics/colormaps/colorscale_cool.jpg)
4125 COLORMAP_HSV = 9, //!< ![HSV](pics/colormaps/colorscale_hsv.jpg)
4126 COLORMAP_PINK = 10, //!< ![pink](pics/colormaps/colorscale_pink.jpg)
4127 COLORMAP_HOT = 11, //!< ![hot](pics/colormaps/colorscale_hot.jpg)
4128 COLORMAP_PARULA = 12 //!< ![parula](pics/colormaps/colorscale_parula.jpg)
4131 /** @brief Applies a GNU Octave/MATLAB equivalent colormap on a given image.
4133 @param src The source image, grayscale or colored of type CV_8UC1 or CV_8UC3.
4134 @param dst The result is the colormapped source image. Note: Mat::create is called on dst.
4135 @param colormap The colormap to apply, see cv::ColormapTypes
4137 CV_EXPORTS_W void applyColorMap(InputArray src, OutputArray dst, int colormap);
4139 //! @} imgproc_colormap
4141 //! @addtogroup imgproc_draw
4144 /** @brief Draws a line segment connecting two points.
4146 The function line draws the line segment between pt1 and pt2 points in the image. The line is
4147 clipped by the image boundaries. For non-antialiased lines with integer coordinates, the 8-connected
4148 or 4-connected Bresenham algorithm is used. Thick lines are drawn with rounding endings. Antialiased
4149 lines are drawn using Gaussian filtering.
4152 @param pt1 First point of the line segment.
4153 @param pt2 Second point of the line segment.
4154 @param color Line color.
4155 @param thickness Line thickness.
4156 @param lineType Type of the line, see cv::LineTypes.
4157 @param shift Number of fractional bits in the point coordinates.
4159 CV_EXPORTS_W void line(InputOutputArray img, Point pt1, Point pt2, const Scalar& color,
4160 int thickness = 1, int lineType = LINE_8, int shift = 0);
4162 /** @brief Draws a arrow segment pointing from the first point to the second one.
4164 The function arrowedLine draws an arrow between pt1 and pt2 points in the image. See also cv::line.
4167 @param pt1 The point the arrow starts from.
4168 @param pt2 The point the arrow points to.
4169 @param color Line color.
4170 @param thickness Line thickness.
4171 @param line_type Type of the line, see cv::LineTypes
4172 @param shift Number of fractional bits in the point coordinates.
4173 @param tipLength The length of the arrow tip in relation to the arrow length
4175 CV_EXPORTS_W void arrowedLine(InputOutputArray img, Point pt1, Point pt2, const Scalar& color,
4176 int thickness=1, int line_type=8, int shift=0, double tipLength=0.1);
4178 /** @brief Draws a simple, thick, or filled up-right rectangle.
4180 The function rectangle draws a rectangle outline or a filled rectangle whose two opposite corners
4184 @param pt1 Vertex of the rectangle.
4185 @param pt2 Vertex of the rectangle opposite to pt1 .
4186 @param color Rectangle color or brightness (grayscale image).
4187 @param thickness Thickness of lines that make up the rectangle. Negative values, like CV_FILLED ,
4188 mean that the function has to draw a filled rectangle.
4189 @param lineType Type of the line. See the line description.
4190 @param shift Number of fractional bits in the point coordinates.
4192 CV_EXPORTS_W void rectangle(InputOutputArray img, Point pt1, Point pt2,
4193 const Scalar& color, int thickness = 1,
4194 int lineType = LINE_8, int shift = 0);
4198 use `rec` parameter as alternative specification of the drawn rectangle: `r.tl() and
4199 r.br()-Point(1,1)` are opposite corners
4201 CV_EXPORTS void rectangle(CV_IN_OUT Mat& img, Rect rec,
4202 const Scalar& color, int thickness = 1,
4203 int lineType = LINE_8, int shift = 0);
4205 /** @brief Draws a circle.
4207 The function circle draws a simple or filled circle with a given center and radius.
4208 @param img Image where the circle is drawn.
4209 @param center Center of the circle.
4210 @param radius Radius of the circle.
4211 @param color Circle color.
4212 @param thickness Thickness of the circle outline, if positive. Negative thickness means that a
4213 filled circle is to be drawn.
4214 @param lineType Type of the circle boundary. See the line description.
4215 @param shift Number of fractional bits in the coordinates of the center and in the radius value.
4217 CV_EXPORTS_W void circle(InputOutputArray img, Point center, int radius,
4218 const Scalar& color, int thickness = 1,
4219 int lineType = LINE_8, int shift = 0);
4221 /** @brief Draws a simple or thick elliptic arc or fills an ellipse sector.
4223 The function cv::ellipse with less parameters draws an ellipse outline, a filled ellipse, an elliptic
4224 arc, or a filled ellipse sector. The drawing code uses general parametric form.
4225 A piecewise-linear curve is used to approximate the elliptic arc
4226 boundary. If you need more control of the ellipse rendering, you can retrieve the curve using
4227 cv::ellipse2Poly and then render it with polylines or fill it with cv::fillPoly. If you use the first
4228 variant of the function and want to draw the whole ellipse, not an arc, pass `startAngle=0` and
4229 `endAngle=360`. The figure below explains the meaning of the parameters to draw the blue arc.
4231 ![Parameters of Elliptic Arc](pics/ellipse.svg)
4234 @param center Center of the ellipse.
4235 @param axes Half of the size of the ellipse main axes.
4236 @param angle Ellipse rotation angle in degrees.
4237 @param startAngle Starting angle of the elliptic arc in degrees.
4238 @param endAngle Ending angle of the elliptic arc in degrees.
4239 @param color Ellipse color.
4240 @param thickness Thickness of the ellipse arc outline, if positive. Otherwise, this indicates that
4241 a filled ellipse sector is to be drawn.
4242 @param lineType Type of the ellipse boundary. See the line description.
4243 @param shift Number of fractional bits in the coordinates of the center and values of axes.
4245 CV_EXPORTS_W void ellipse(InputOutputArray img, Point center, Size axes,
4246 double angle, double startAngle, double endAngle,
4247 const Scalar& color, int thickness = 1,
4248 int lineType = LINE_8, int shift = 0);
4252 @param box Alternative ellipse representation via RotatedRect. This means that the function draws
4253 an ellipse inscribed in the rotated rectangle.
4254 @param color Ellipse color.
4255 @param thickness Thickness of the ellipse arc outline, if positive. Otherwise, this indicates that
4256 a filled ellipse sector is to be drawn.
4257 @param lineType Type of the ellipse boundary. See the line description.
4259 CV_EXPORTS_W void ellipse(InputOutputArray img, const RotatedRect& box, const Scalar& color,
4260 int thickness = 1, int lineType = LINE_8);
4262 /* ----------------------------------------------------------------------------------------- */
4263 /* ADDING A SET OF PREDEFINED MARKERS WHICH COULD BE USED TO HIGHLIGHT POSITIONS IN AN IMAGE */
4264 /* ----------------------------------------------------------------------------------------- */
4266 //! Possible set of marker types used for the cv::drawMarker function
4269 MARKER_CROSS = 0, //!< A crosshair marker shape
4270 MARKER_TILTED_CROSS = 1, //!< A 45 degree tilted crosshair marker shape
4271 MARKER_STAR = 2, //!< A star marker shape, combination of cross and tilted cross
4272 MARKER_DIAMOND = 3, //!< A diamond marker shape
4273 MARKER_SQUARE = 4, //!< A square marker shape
4274 MARKER_TRIANGLE_UP = 5, //!< An upwards pointing triangle marker shape
4275 MARKER_TRIANGLE_DOWN = 6 //!< A downwards pointing triangle marker shape
4278 /** @brief Draws a marker on a predefined position in an image.
4280 The function drawMarker draws a marker on a given position in the image. For the moment several
4281 marker types are supported, see cv::MarkerTypes for more information.
4284 @param position The point where the crosshair is positioned.
4285 @param color Line color.
4286 @param markerType The specific type of marker you want to use, see cv::MarkerTypes
4287 @param thickness Line thickness.
4288 @param line_type Type of the line, see cv::LineTypes
4289 @param markerSize The length of the marker axis [default = 20 pixels]
4291 CV_EXPORTS_W void drawMarker(CV_IN_OUT Mat& img, Point position, const Scalar& color,
4292 int markerType = MARKER_CROSS, int markerSize=20, int thickness=1,
4295 /* ----------------------------------------------------------------------------------------- */
4296 /* END OF MARKER SECTION */
4297 /* ----------------------------------------------------------------------------------------- */
4300 CV_EXPORTS void fillConvexPoly(Mat& img, const Point* pts, int npts,
4301 const Scalar& color, int lineType = LINE_8,
4304 /** @brief Fills a convex polygon.
4306 The function fillConvexPoly draws a filled convex polygon. This function is much faster than the
4307 function cv::fillPoly . It can fill not only convex polygons but any monotonic polygon without
4308 self-intersections, that is, a polygon whose contour intersects every horizontal line (scan line)
4309 twice at the most (though, its top-most and/or the bottom edge could be horizontal).
4312 @param points Polygon vertices.
4313 @param color Polygon color.
4314 @param lineType Type of the polygon boundaries. See the line description.
4315 @param shift Number of fractional bits in the vertex coordinates.
4317 CV_EXPORTS_W void fillConvexPoly(InputOutputArray img, InputArray points,
4318 const Scalar& color, int lineType = LINE_8,
4322 CV_EXPORTS void fillPoly(Mat& img, const Point** pts,
4323 const int* npts, int ncontours,
4324 const Scalar& color, int lineType = LINE_8, int shift = 0,
4325 Point offset = Point() );
4327 /** @brief Fills the area bounded by one or more polygons.
4329 The function fillPoly fills an area bounded by several polygonal contours. The function can fill
4330 complex areas, for example, areas with holes, contours with self-intersections (some of their
4331 parts), and so forth.
4334 @param pts Array of polygons where each polygon is represented as an array of points.
4335 @param color Polygon color.
4336 @param lineType Type of the polygon boundaries. See the line description.
4337 @param shift Number of fractional bits in the vertex coordinates.
4338 @param offset Optional offset of all points of the contours.
4340 CV_EXPORTS_W void fillPoly(InputOutputArray img, InputArrayOfArrays pts,
4341 const Scalar& color, int lineType = LINE_8, int shift = 0,
4342 Point offset = Point() );
4345 CV_EXPORTS void polylines(Mat& img, const Point* const* pts, const int* npts,
4346 int ncontours, bool isClosed, const Scalar& color,
4347 int thickness = 1, int lineType = LINE_8, int shift = 0 );
4349 /** @brief Draws several polygonal curves.
4352 @param pts Array of polygonal curves.
4353 @param isClosed Flag indicating whether the drawn polylines are closed or not. If they are closed,
4354 the function draws a line from the last vertex of each curve to its first vertex.
4355 @param color Polyline color.
4356 @param thickness Thickness of the polyline edges.
4357 @param lineType Type of the line segments. See the line description.
4358 @param shift Number of fractional bits in the vertex coordinates.
4360 The function polylines draws one or more polygonal curves.
4362 CV_EXPORTS_W void polylines(InputOutputArray img, InputArrayOfArrays pts,
4363 bool isClosed, const Scalar& color,
4364 int thickness = 1, int lineType = LINE_8, int shift = 0 );
4366 /** @example contours2.cpp
4367 An example using the drawContour functionality
4370 /** @example segment_objects.cpp
4371 An example using drawContours to clean up a background segmentation result
4374 /** @brief Draws contours outlines or filled contours.
4376 The function draws contour outlines in the image if \f$\texttt{thickness} \ge 0\f$ or fills the area
4377 bounded by the contours if \f$\texttt{thickness}<0\f$ . The example below shows how to retrieve
4378 connected components from the binary image and label them: :
4380 #include "opencv2/imgproc.hpp"
4381 #include "opencv2/highgui.hpp"
4384 using namespace std;
4386 int main( int argc, char** argv )
4389 // the first command-line parameter must be a filename of the binary
4390 // (black-n-white) image
4391 if( argc != 2 || !(src=imread(argv[1], 0)).data)
4394 Mat dst = Mat::zeros(src.rows, src.cols, CV_8UC3);
4397 namedWindow( "Source", 1 );
4398 imshow( "Source", src );
4400 vector<vector<Point> > contours;
4401 vector<Vec4i> hierarchy;
4403 findContours( src, contours, hierarchy,
4404 RETR_CCOMP, CHAIN_APPROX_SIMPLE );
4406 // iterate through all the top-level contours,
4407 // draw each connected component with its own random color
4409 for( ; idx >= 0; idx = hierarchy[idx][0] )
4411 Scalar color( rand()&255, rand()&255, rand()&255 );
4412 drawContours( dst, contours, idx, color, FILLED, 8, hierarchy );
4415 namedWindow( "Components", 1 );
4416 imshow( "Components", dst );
4421 @param image Destination image.
4422 @param contours All the input contours. Each contour is stored as a point vector.
4423 @param contourIdx Parameter indicating a contour to draw. If it is negative, all the contours are drawn.
4424 @param color Color of the contours.
4425 @param thickness Thickness of lines the contours are drawn with. If it is negative (for example,
4426 thickness=CV_FILLED ), the contour interiors are drawn.
4427 @param lineType Line connectivity. See cv::LineTypes.
4428 @param hierarchy Optional information about hierarchy. It is only needed if you want to draw only
4429 some of the contours (see maxLevel ).
4430 @param maxLevel Maximal level for drawn contours. If it is 0, only the specified contour is drawn.
4431 If it is 1, the function draws the contour(s) and all the nested contours. If it is 2, the function
4432 draws the contours, all the nested contours, all the nested-to-nested contours, and so on. This
4433 parameter is only taken into account when there is hierarchy available.
4434 @param offset Optional contour shift parameter. Shift all the drawn contours by the specified
4435 \f$\texttt{offset}=(dx,dy)\f$ .
4437 CV_EXPORTS_W void drawContours( InputOutputArray image, InputArrayOfArrays contours,
4438 int contourIdx, const Scalar& color,
4439 int thickness = 1, int lineType = LINE_8,
4440 InputArray hierarchy = noArray(),
4441 int maxLevel = INT_MAX, Point offset = Point() );
4443 /** @brief Clips the line against the image rectangle.
4445 The function cv::clipLine calculates a part of the line segment that is entirely within the specified
4446 rectangle. it returns false if the line segment is completely outside the rectangle. Otherwise,
4448 @param imgSize Image size. The image rectangle is Rect(0, 0, imgSize.width, imgSize.height) .
4449 @param pt1 First line point.
4450 @param pt2 Second line point.
4452 CV_EXPORTS bool clipLine(Size imgSize, CV_IN_OUT Point& pt1, CV_IN_OUT Point& pt2);
4455 @param imgSize Image size. The image rectangle is Rect(0, 0, imgSize.width, imgSize.height) .
4456 @param pt1 First line point.
4457 @param pt2 Second line point.
4459 CV_EXPORTS bool clipLine(Size2l imgSize, CV_IN_OUT Point2l& pt1, CV_IN_OUT Point2l& pt2);
4462 @param imgRect Image rectangle.
4463 @param pt1 First line point.
4464 @param pt2 Second line point.
4466 CV_EXPORTS_W bool clipLine(Rect imgRect, CV_OUT CV_IN_OUT Point& pt1, CV_OUT CV_IN_OUT Point& pt2);
4468 /** @brief Approximates an elliptic arc with a polyline.
4470 The function ellipse2Poly computes the vertices of a polyline that approximates the specified
4471 elliptic arc. It is used by cv::ellipse.
4473 @param center Center of the arc.
4474 @param axes Half of the size of the ellipse main axes. See the ellipse for details.
4475 @param angle Rotation angle of the ellipse in degrees. See the ellipse for details.
4476 @param arcStart Starting angle of the elliptic arc in degrees.
4477 @param arcEnd Ending angle of the elliptic arc in degrees.
4478 @param delta Angle between the subsequent polyline vertices. It defines the approximation
4480 @param pts Output vector of polyline vertices.
4482 CV_EXPORTS_W void ellipse2Poly( Point center, Size axes, int angle,
4483 int arcStart, int arcEnd, int delta,
4484 CV_OUT std::vector<Point>& pts );
4487 @param center Center of the arc.
4488 @param axes Half of the size of the ellipse main axes. See the ellipse for details.
4489 @param angle Rotation angle of the ellipse in degrees. See the ellipse for details.
4490 @param arcStart Starting angle of the elliptic arc in degrees.
4491 @param arcEnd Ending angle of the elliptic arc in degrees.
4492 @param delta Angle between the subsequent polyline vertices. It defines the approximation
4494 @param pts Output vector of polyline vertices.
4496 CV_EXPORTS void ellipse2Poly(Point2d center, Size2d axes, int angle,
4497 int arcStart, int arcEnd, int delta,
4498 CV_OUT std::vector<Point2d>& pts);
4500 /** @brief Draws a text string.
4502 The function putText renders the specified text string in the image. Symbols that cannot be rendered
4503 using the specified font are replaced by question marks. See getTextSize for a text rendering code
4507 @param text Text string to be drawn.
4508 @param org Bottom-left corner of the text string in the image.
4509 @param fontFace Font type, see cv::HersheyFonts.
4510 @param fontScale Font scale factor that is multiplied by the font-specific base size.
4511 @param color Text color.
4512 @param thickness Thickness of the lines used to draw a text.
4513 @param lineType Line type. See the line for details.
4514 @param bottomLeftOrigin When true, the image data origin is at the bottom-left corner. Otherwise,
4515 it is at the top-left corner.
4517 CV_EXPORTS_W void putText( InputOutputArray img, const String& text, Point org,
4518 int fontFace, double fontScale, Scalar color,
4519 int thickness = 1, int lineType = LINE_8,
4520 bool bottomLeftOrigin = false );
4522 /** @brief Calculates the width and height of a text string.
4524 The function getTextSize calculates and returns the size of a box that contains the specified text.
4525 That is, the following code renders some text, the tight box surrounding it, and the baseline: :
4527 String text = "Funny text inside the box";
4528 int fontFace = FONT_HERSHEY_SCRIPT_SIMPLEX;
4529 double fontScale = 2;
4532 Mat img(600, 800, CV_8UC3, Scalar::all(0));
4535 Size textSize = getTextSize(text, fontFace,
4536 fontScale, thickness, &baseline);
4537 baseline += thickness;
4540 Point textOrg((img.cols - textSize.width)/2,
4541 (img.rows + textSize.height)/2);
4544 rectangle(img, textOrg + Point(0, baseline),
4545 textOrg + Point(textSize.width, -textSize.height),
4547 // ... and the baseline first
4548 line(img, textOrg + Point(0, thickness),
4549 textOrg + Point(textSize.width, thickness),
4552 // then put the text itself
4553 putText(img, text, textOrg, fontFace, fontScale,
4554 Scalar::all(255), thickness, 8);
4557 @param text Input text string.
4558 @param fontFace Font to use, see cv::HersheyFonts.
4559 @param fontScale Font scale factor that is multiplied by the font-specific base size.
4560 @param thickness Thickness of lines used to render the text. See putText for details.
4561 @param[out] baseLine y-coordinate of the baseline relative to the bottom-most text
4563 @return The size of a box that contains the specified text.
4567 CV_EXPORTS_W Size getTextSize(const String& text, int fontFace,
4568 double fontScale, int thickness,
4569 CV_OUT int* baseLine);
4571 /** @brief Line iterator
4573 The class is used to iterate over all the pixels on the raster line
4574 segment connecting two specified points.
4576 The class LineIterator is used to get each pixel of a raster line. It
4577 can be treated as versatile implementation of the Bresenham algorithm
4578 where you can stop at each pixel and do some extra processing, for
4579 example, grab pixel values along the line or draw a line with an effect
4580 (for example, with XOR operation).
4582 The number of pixels along the line is stored in LineIterator::count.
4583 The method LineIterator::pos returns the current position in the image:
4586 // grabs pixels along the line (pt1, pt2)
4587 // from 8-bit 3-channel image to the buffer
4588 LineIterator it(img, pt1, pt2, 8);
4589 LineIterator it2 = it;
4590 vector<Vec3b> buf(it.count);
4592 for(int i = 0; i < it.count; i++, ++it)
4593 buf[i] = *(const Vec3b)*it;
4595 // alternative way of iterating through the line
4596 for(int i = 0; i < it2.count; i++, ++it2)
4598 Vec3b val = img.at<Vec3b>(it2.pos());
4599 CV_Assert(buf[i] == val);
4603 class CV_EXPORTS LineIterator
4606 /** @brief intializes the iterator
4608 creates iterators for the line connecting pt1 and pt2
4609 the line will be clipped on the image boundaries
4610 the line is 8-connected or 4-connected
4611 If leftToRight=true, then the iteration is always done
4612 from the left-most point to the right most,
4613 not to depend on the ordering of pt1 and pt2 parameters
4615 LineIterator( const Mat& img, Point pt1, Point pt2,
4616 int connectivity = 8, bool leftToRight = false );
4617 /** @brief returns pointer to the current pixel
4619 uchar* operator *();
4620 /** @brief prefix increment operator (++it). shifts iterator to the next pixel
4622 LineIterator& operator ++();
4623 /** @brief postfix increment operator (it++). shifts iterator to the next pixel
4625 LineIterator operator ++(int);
4626 /** @brief returns coordinates of the current pixel
4634 int minusDelta, plusDelta;
4635 int minusStep, plusStep;
4640 // === LineIterator implementation ===
4643 uchar* LineIterator::operator *()
4649 LineIterator& LineIterator::operator ++()
4651 int mask = err < 0 ? -1 : 0;
4652 err += minusDelta + (plusDelta & mask);
4653 ptr += minusStep + (plusStep & mask);
4658 LineIterator LineIterator::operator ++(int)
4660 LineIterator it = *this;
4666 Point LineIterator::pos() const
4669 p.y = (int)((ptr - ptr0)/step);
4670 p.x = (int)(((ptr - ptr0) - p.y*step)/elemSize);
4682 #ifndef DISABLE_OPENCV_24_COMPATIBILITY
4683 #include "opencv2/imgproc/imgproc_c.h"