1 /*M///////////////////////////////////////////////////////////////////////////////////////
2 //
3 // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
4 //
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.
8 //
9 //
10 // License Agreement
11 // For Open Source Computer Vision Library
12 //
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.
16 //
17 // Redistribution and use in source and binary forms, with or without modification,
18 // are permitted provided that the following conditions are met:
19 //
20 // * Redistribution's of source code must retain the above copyright notice,
21 // this list of conditions and the following disclaimer.
22 //
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.
26 //
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.
29 //
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.
40 //
41 //M*/
42
43 #ifndef OPENCV_IMGPROC_HPP
44 #define OPENCV_IMGPROC_HPP
45
46 #include "opencv2/core.hpp"
47
48 /**
49 @defgroup imgproc Image Processing
50
51 This module includes image-processing functions.
52
53 @{
54 @defgroup imgproc_filter Image Filtering
55
56 Functions and classes described in this section are used to perform various linear or non-linear
57 filtering operations on 2D images (represented as Mat's). It means that for each pixel location
58 \f$(x,y)\f$ in the source image (normally, rectangular), its neighborhood is considered and used to
59 compute the response. In case of a linear filter, it is a weighted sum of pixel values. In case of
60 morphological operations, it is the minimum or maximum values, and so on. The computed response is
61 stored in the destination image at the same location \f$(x,y)\f$. It means that the output image
62 will be of the same size as the input image. Normally, the functions support multi-channel arrays,
63 in which case every channel is processed independently. Therefore, the output image will also have
64 the same number of channels as the input one.
65
66 Another common feature of the functions and classes described in this section is that, unlike
67 simple arithmetic functions, they need to extrapolate values of some non-existing pixels. For
68 example, if you want to smooth an image using a Gaussian \f$3 \times 3\f$ filter, then, when
69 processing the left-most pixels in each row, you need pixels to the left of them, that is, outside
70 of the image. You can let these pixels be the same as the left-most image pixels ("replicated
71 border" extrapolation method), or assume that all the non-existing pixels are zeros ("constant
72 border" extrapolation method), and so on. OpenCV enables you to specify the extrapolation method.
73 For details, see #BorderTypes
74
75 @anchor filter_depths
76 ### Depth combinations
77 Input depth (src.depth()) | Output depth (ddepth)
78 --------------------------|----------------------
79 CV_8U | -1/CV_16S/CV_32F/CV_64F
80 CV_16U/CV_16S | -1/CV_32F/CV_64F
81 CV_32F | -1/CV_32F/CV_64F
82 CV_64F | -1/CV_64F
83
84 @note when ddepth=-1, the output image will have the same depth as the source.
85
86 @defgroup imgproc_transform Geometric Image Transformations
87
88 The functions in this section perform various geometrical transformations of 2D images. They do not
89 change the image content but deform the pixel grid and map this deformed grid to the destination
90 image. In fact, to avoid sampling artifacts, the mapping is done in the reverse order, from
91 destination to the source. That is, for each pixel \f$(x, y)\f$ of the destination image, the
92 functions compute coordinates of the corresponding "donor" pixel in the source image and copy the
93 pixel value:
94
95 \f[\texttt{dst} (x,y)= \texttt{src} (f_x(x,y), f_y(x,y))\f]
96
97 In case when you specify the forward mapping \f$\left<g_x, g_y\right>: \texttt{src} \rightarrow
98 \texttt{dst}\f$, the OpenCV functions first compute the corresponding inverse mapping
99 \f$\left<f_x, f_y\right>: \texttt{dst} \rightarrow \texttt{src}\f$ and then use the above formula.
100
101 The actual implementations of the geometrical transformations, from the most generic remap and to
102 the simplest and the fastest resize, need to solve two main problems with the above formula:
103
104 - Extrapolation of non-existing pixels. Similarly to the filtering functions described in the
105 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
106 of them may fall outside of the image. In this case, an extrapolation method needs to be used.
107 OpenCV provides the same selection of extrapolation methods as in the filtering functions. In
108 addition, it provides the method #BORDER_TRANSPARENT. This means that the corresponding pixels in
109 the destination image will not be modified at all.
110
111 - Interpolation of pixel values. Usually \f$f_x(x,y)\f$ and \f$f_y(x,y)\f$ are floating-point
112 numbers. This means that \f$\left<f_x, f_y\right>\f$ can be either an affine or perspective
113 transformation, or radial lens distortion correction, and so on. So, a pixel value at fractional
114 coordinates needs to be retrieved. In the simplest case, the coordinates can be just rounded to the
115 nearest integer coordinates and the corresponding pixel can be used. This is called a
116 nearest-neighbor interpolation. However, a better result can be achieved by using more
117 sophisticated [interpolation methods](http://en.wikipedia.org/wiki/Multivariate_interpolation) ,
118 where a polynomial function is fit into some neighborhood of the computed pixel \f$(f_x(x,y),
119 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
120 interpolated pixel value. In OpenCV, you can choose between several interpolation methods. See
121 resize for details.
122
123 @note The geometrical transformations do not work with `CV_8S` or `CV_32S` images.
124
125 @defgroup imgproc_misc Miscellaneous Image Transformations
126 @defgroup imgproc_draw Drawing Functions
127
128 Drawing functions work with matrices/images of arbitrary depth. The boundaries of the shapes can be
129 rendered with antialiasing (implemented only for 8-bit images for now). All the functions include
130 the parameter color that uses an RGB value (that may be constructed with the Scalar constructor )
131 for color images and brightness for grayscale images. For color images, the channel ordering is
132 normally *Blue, Green, Red*. This is what imshow, imread, and imwrite expect. So, if you form a
133 color using the Scalar constructor, it should look like:
134
135 \f[\texttt{Scalar} (blue \_ component, green \_ component, red \_ component[, alpha \_ component])\f]
136
137 If you are using your own image rendering and I/O functions, you can use any channel ordering. The
138 drawing functions process each channel independently and do not depend on the channel order or even
139 on the used color space. The whole image can be converted from BGR to RGB or to a different color
140 space using cvtColor .
141
142 If a drawn figure is partially or completely outside the image, the drawing functions clip it. Also,
143 many drawing functions can handle pixel coordinates specified with sub-pixel accuracy. This means
144 that the coordinates can be passed as fixed-point numbers encoded as integers. The number of
145 fractional bits is specified by the shift parameter and the real point coordinates are calculated as
146 \f$\texttt{Point}(x,y)\rightarrow\texttt{Point2f}(x*2^{-shift},y*2^{-shift})\f$ . This feature is
147 especially effective when rendering antialiased shapes.
148
149 @note The functions do not support alpha-transparency when the target image is 4-channel. In this
150 case, the color[3] is simply copied to the repainted pixels. Thus, if you want to paint
151 semi-transparent shapes, you can paint them in a separate buffer and then blend it with the main
152 image.
153
154 @defgroup imgproc_color_conversions Color Space Conversions
155 @defgroup imgproc_colormap ColorMaps in OpenCV
156
157 The human perception isn't built for observing fine changes in grayscale images. Human eyes are more
158 sensitive to observing changes between colors, so you often need to recolor your grayscale images to
159 get a clue about them. OpenCV now comes with various colormaps to enhance the visualization in your
160 computer vision application.
161
162 In OpenCV you only need applyColorMap to apply a colormap on a given image. The following sample
163 code reads the path to an image from command line, applies a Jet colormap on it and shows the
164 result:
165
166 @include snippets/imgproc_applyColorMap.cpp
167
168 @see #ColormapTypes
169
170 @defgroup imgproc_subdiv2d Planar Subdivision
171
172 The Subdiv2D class described in this section is used to perform various planar subdivision on
173 a set of 2D points (represented as vector of Point2f). OpenCV subdivides a plane into triangles
174 using the Delaunay's algorithm, which corresponds to the dual graph of the Voronoi diagram.
175 In the figure below, the Delaunay's triangulation is marked with black lines and the Voronoi
176 diagram with red lines.
177
178 ![Delaunay triangulation (black) and Voronoi (red)](pics/delaunay_voronoi.png)
179
180 The subdivisions can be used for the 3D piece-wise transformation of a plane, morphing, fast
181 location of points on the plane, building special graphs (such as NNG,RNG), and so forth.
182
183 @defgroup imgproc_hist Histograms
184 @defgroup imgproc_shape Structural Analysis and Shape Descriptors
185 @defgroup imgproc_motion Motion Analysis and Object Tracking
186 @defgroup imgproc_feature Feature Detection
187 @defgroup imgproc_object Object Detection
188 @defgroup imgproc_segmentation Image Segmentation
189 @defgroup imgproc_c C API
190 @defgroup imgproc_hal Hardware Acceleration Layer
191 @{
192 @defgroup imgproc_hal_functions Functions
193 @defgroup imgproc_hal_interface Interface
194 @}
195 @}
196 */
197
198 namespace cv
199 {
200
201 /** @addtogroup imgproc
202 @{
203 */
204
205 //! @addtogroup imgproc_filter
206 //! @{
207
208 enum SpecialFilter {
209 FILTER_SCHARR = -1
210 };
211
212 //! type of morphological operation
213 enum MorphTypes{
214 MORPH_ERODE = 0, //!< see #erode
215 MORPH_DILATE = 1, //!< see #dilate
216 MORPH_OPEN = 2, //!< an opening operation
217 //!< \f[\texttt{dst} = \mathrm{open} ( \texttt{src} , \texttt{element} )= \mathrm{dilate} ( \mathrm{erode} ( \texttt{src} , \texttt{element} ))\f]
218 MORPH_CLOSE = 3, //!< a closing operation
219 //!< \f[\texttt{dst} = \mathrm{close} ( \texttt{src} , \texttt{element} )= \mathrm{erode} ( \mathrm{dilate} ( \texttt{src} , \texttt{element} ))\f]
220 MORPH_GRADIENT = 4, //!< a morphological gradient
221 //!< \f[\texttt{dst} = \mathrm{morph\_grad} ( \texttt{src} , \texttt{element} )= \mathrm{dilate} ( \texttt{src} , \texttt{element} )- \mathrm{erode} ( \texttt{src} , \texttt{element} )\f]
222 MORPH_TOPHAT = 5, //!< "top hat"
223 //!< \f[\texttt{dst} = \mathrm{tophat} ( \texttt{src} , \texttt{element} )= \texttt{src} - \mathrm{open} ( \texttt{src} , \texttt{element} )\f]
224 MORPH_BLACKHAT = 6, //!< "black hat"
225 //!< \f[\texttt{dst} = \mathrm{blackhat} ( \texttt{src} , \texttt{element} )= \mathrm{close} ( \texttt{src} , \texttt{element} )- \texttt{src}\f]
226 MORPH_HITMISS = 7 //!< "hit or miss"
227 //!< .- Only supported for CV_8UC1 binary images. A tutorial can be found in the documentation
228 };
229
230 //! shape of the structuring element
231 enum MorphShapes {
232 MORPH_RECT = 0, //!< a rectangular structuring element: \f[E_{ij}=1\f]
233 MORPH_CROSS = 1, //!< a cross-shaped structuring element:
234 //!< \f[E_{ij} = \begin{cases} 1 & \texttt{if } {i=\texttt{anchor.y } {or } {j=\texttt{anchor.x}}} \\0 & \texttt{otherwise} \end{cases}\f]
235 MORPH_ELLIPSE = 2 //!< an elliptic structuring element, that is, a filled ellipse inscribed
236 //!< into the rectangle Rect(0, 0, esize.width, 0.esize.height)
237 };
238
239 //! @} imgproc_filter
240
241 //! @addtogroup imgproc_transform
242 //! @{
243
244 //! interpolation algorithm
245 enum InterpolationFlags{
246 /** nearest neighbor interpolation */
247 INTER_NEAREST = 0,
248 /** bilinear interpolation */
249 INTER_LINEAR = 1,
250 /** bicubic interpolation */
251 INTER_CUBIC = 2,
252 /** resampling using pixel area relation. It may be a preferred method for image decimation, as
253 it gives moire'-free results. But when the image is zoomed, it is similar to the INTER_NEAREST
254 method. */
255 INTER_AREA = 3,
256 /** Lanczos interpolation over 8x8 neighborhood */
257 INTER_LANCZOS4 = 4,
258 /** Bit exact bilinear interpolation */
259 INTER_LINEAR_EXACT = 5,
260 /** Bit exact nearest neighbor interpolation. This will produce same results as
261 the nearest neighbor method in PIL, scikit-image or Matlab. */
262 INTER_NEAREST_EXACT = 6,
263 /** mask for interpolation codes */
264 INTER_MAX = 7,
265 /** flag, fills all of the destination image pixels. If some of them correspond to outliers in the
266 source image, they are set to zero */
267 WARP_FILL_OUTLIERS = 8,
268 /** flag, inverse transformation
269
270 For example, #linearPolar or #logPolar transforms:
271 - flag is __not__ set: \f$dst( \rho , \phi ) = src(x,y)\f$
272 - flag is set: \f$dst(x,y) = src( \rho , \phi )\f$
273 */
274 WARP_INVERSE_MAP = 16
275 };
276
277 /** \brief Specify the polar mapping mode
278 @sa warpPolar
279 */
280 enum WarpPolarMode
281 {
282 WARP_POLAR_LINEAR = 0, ///< Remaps an image to/from polar space.
283 WARP_POLAR_LOG = 256 ///< Remaps an image to/from semilog-polar space.
284 };
285
286 enum InterpolationMasks {
287 INTER_BITS = 5,
288 INTER_BITS2 = INTER_BITS * 2,
289 INTER_TAB_SIZE = 1 << INTER_BITS,
290 INTER_TAB_SIZE2 = INTER_TAB_SIZE * INTER_TAB_SIZE
291 };
292
293 //! @} imgproc_transform
294
295 //! @addtogroup imgproc_misc
296 //! @{
297
298 //! Distance types for Distance Transform and M-estimators
299 //! @see distanceTransform, fitLine
300 enum DistanceTypes {
301 DIST_USER = -1, //!< User defined distance
302 DIST_L1 = 1, //!< distance = |x1-x2| + |y1-y2|
303 DIST_L2 = 2, //!< the simple euclidean distance
304 DIST_C = 3, //!< distance = max(|x1-x2|,|y1-y2|)
305 DIST_L12 = 4, //!< L1-L2 metric: distance = 2(sqrt(1+x*x/2) - 1))
306 DIST_FAIR = 5, //!< distance = c^2(|x|/c-log(1+|x|/c)), c = 1.3998
307 DIST_WELSCH = 6, //!< distance = c^2/2(1-exp(-(x/c)^2)), c = 2.9846
308 DIST_HUBER = 7 //!< distance = |x|<c ? x^2/2 : c(|x|-c/2), c=1.345
309 };
310
311 //! Mask size for distance transform
312 enum DistanceTransformMasks {
313 DIST_MASK_3 = 3, //!< mask=3
314 DIST_MASK_5 = 5, //!< mask=5
315 DIST_MASK_PRECISE = 0 //!<
316 };
317
318 //! type of the threshold operation
319 //! ![threshold types](pics/threshold.png)
320 enum ThresholdTypes {
321 THRESH_BINARY = 0, //!< \f[\texttt{dst} (x,y) = \fork{\texttt{maxval}}{if \(\texttt{src}(x,y) > \texttt{thresh}\)}{0}{otherwise}\f]
322 THRESH_BINARY_INV = 1, //!< \f[\texttt{dst} (x,y) = \fork{0}{if \(\texttt{src}(x,y) > \texttt{thresh}\)}{\texttt{maxval}}{otherwise}\f]
323 THRESH_TRUNC = 2, //!< \f[\texttt{dst} (x,y) = \fork{\texttt{threshold}}{if \(\texttt{src}(x,y) > \texttt{thresh}\)}{\texttt{src}(x,y)}{otherwise}\f]
324 THRESH_TOZERO = 3, //!< \f[\texttt{dst} (x,y) = \fork{\texttt{src}(x,y)}{if \(\texttt{src}(x,y) > \texttt{thresh}\)}{0}{otherwise}\f]
325 THRESH_TOZERO_INV = 4, //!< \f[\texttt{dst} (x,y) = \fork{0}{if \(\texttt{src}(x,y) > \texttt{thresh}\)}{\texttt{src}(x,y)}{otherwise}\f]
326 THRESH_MASK = 7,
327 THRESH_OTSU = 8, //!< flag, use Otsu algorithm to choose the optimal threshold value
328 THRESH_TRIANGLE = 16 //!< flag, use Triangle algorithm to choose the optimal threshold value
329 };
330
331 //! adaptive threshold algorithm
332 //! @see adaptiveThreshold
333 enum AdaptiveThresholdTypes {
334 /** the threshold value \f$T(x,y)\f$ is a mean of the \f$\texttt{blockSize} \times
335 \texttt{blockSize}\f$ neighborhood of \f$(x, y)\f$ minus C */
336 ADAPTIVE_THRESH_MEAN_C = 0,
337 /** the threshold value \f$T(x, y)\f$ is a weighted sum (cross-correlation with a Gaussian
338 window) of the \f$\texttt{blockSize} \times \texttt{blockSize}\f$ neighborhood of \f$(x, y)\f$
339 minus C . The default sigma (standard deviation) is used for the specified blockSize . See
340 #getGaussianKernel*/
341 ADAPTIVE_THRESH_GAUSSIAN_C = 1
342 };
343
344 //! class of the pixel in GrabCut algorithm
345 enum GrabCutClasses {
346 GC_BGD = 0, //!< an obvious background pixels
347 GC_FGD = 1, //!< an obvious foreground (object) pixel
348 GC_PR_BGD = 2, //!< a possible background pixel
349 GC_PR_FGD = 3 //!< a possible foreground pixel
350 };
351
352 //! GrabCut algorithm flags
353 enum GrabCutModes {
354 /** The function initializes the state and the mask using the provided rectangle. After that it
355 runs iterCount iterations of the algorithm. */
356 GC_INIT_WITH_RECT = 0,
357 /** The function initializes the state using the provided mask. Note that GC_INIT_WITH_RECT
358 and GC_INIT_WITH_MASK can be combined. Then, all the pixels outside of the ROI are
359 automatically initialized with GC_BGD .*/
360 GC_INIT_WITH_MASK = 1,
361 /** The value means that the algorithm should just resume. */
362 GC_EVAL = 2,
363 /** The value means that the algorithm should just run the grabCut algorithm (a single iteration) with the fixed model */
364 GC_EVAL_FREEZE_MODEL = 3
365 };
366
367 //! distanceTransform algorithm flags
368 enum DistanceTransformLabelTypes {
369 /** each connected component of zeros in src (as well as all the non-zero pixels closest to the
370 connected component) will be assigned the same label */
371 DIST_LABEL_CCOMP = 0,
372 /** each zero pixel (and all the non-zero pixels closest to it) gets its own label. */
373 DIST_LABEL_PIXEL = 1
374 };
375
376 //! floodfill algorithm flags
377 enum FloodFillFlags {
378 /** If set, the difference between the current pixel and seed pixel is considered. Otherwise,
379 the difference between neighbor pixels is considered (that is, the range is floating). */
380 FLOODFILL_FIXED_RANGE = 1 << 16,
381 /** If set, the function does not change the image ( newVal is ignored), and only fills the
382 mask with the value specified in bits 8-16 of flags as described above. This option only make
383 sense in function variants that have the mask parameter. */
384 FLOODFILL_MASK_ONLY = 1 << 17
385 };
386
387 //! @} imgproc_misc
388
389 //! @addtogroup imgproc_shape
390 //! @{
391
392 //! connected components statistics
393 enum ConnectedComponentsTypes {
394 CC_STAT_LEFT = 0, //!< The leftmost (x) coordinate which is the inclusive start of the bounding
395 //!< box in the horizontal direction.
396 CC_STAT_TOP = 1, //!< The topmost (y) coordinate which is the inclusive start of the bounding
397 //!< box in the vertical direction.
398 CC_STAT_WIDTH = 2, //!< The horizontal size of the bounding box
399 CC_STAT_HEIGHT = 3, //!< The vertical size of the bounding box
400 CC_STAT_AREA = 4, //!< The total area (in pixels) of the connected component
401 #ifndef CV_DOXYGEN
402 CC_STAT_MAX = 5 //!< Max enumeration value. Used internally only for memory allocation
403 #endif
404 };
405
406 //! connected components algorithm
407 enum ConnectedComponentsAlgorithmsTypes {
408 CCL_DEFAULT = -1, //!< BBDT @cite Grana2010 algorithm for 8-way connectivity, SAUF algorithm for 4-way connectivity. The parallel implementation described in @cite Bolelli2017 is available for both BBDT and SAUF.
409 CCL_WU = 0, //!< SAUF @cite Wu2009 algorithm for 8-way connectivity, SAUF algorithm for 4-way connectivity. The parallel implementation described in @cite Bolelli2017 is available for SAUF.
410 CCL_GRANA = 1, //!< BBDT @cite Grana2010 algorithm for 8-way connectivity, SAUF algorithm for 4-way connectivity. The parallel implementation described in @cite Bolelli2017 is available for both BBDT and SAUF.
411 CCL_BOLELLI = 2, //!< Spaghetti @cite Bolelli2019 algorithm for 8-way connectivity, SAUF algorithm for 4-way connectivity.
412 CCL_SAUF = 3, //!< Same as CCL_WU. It is preferable to use the flag with the name of the algorithm (CCL_SAUF) rather than the one with the name of the first author (CCL_WU).
413 CCL_BBDT = 4, //!< Same as CCL_GRANA. It is preferable to use the flag with the name of the algorithm (CCL_BBDT) rather than the one with the name of the first author (CCL_GRANA).
414 CCL_SPAGHETTI = 5, //!< Same as CCL_BOLELLI. It is preferable to use the flag with the name of the algorithm (CCL_SPAGHETTI) rather than the one with the name of the first author (CCL_BOLELLI).
415 };
416
417 //! mode of the contour retrieval algorithm
418 enum RetrievalModes {
419 /** retrieves only the extreme outer contours. It sets `hierarchy[i][2]=hierarchy[i][3]=-1` for
420 all the contours. */
421 RETR_EXTERNAL = 0,
422 /** retrieves all of the contours without establishing any hierarchical relationships. */
423 RETR_LIST = 1,
424 /** retrieves all of the contours and organizes them into a two-level hierarchy. At the top
425 level, there are external boundaries of the components. At the second level, there are
426 boundaries of the holes. If there is another contour inside a hole of a connected component, it
427 is still put at the top level. */
428 RETR_CCOMP = 2,
429 /** retrieves all of the contours and reconstructs a full hierarchy of nested contours.*/
430 RETR_TREE = 3,
431 RETR_FLOODFILL = 4 //!<
432 };
433
434 //! the contour approximation algorithm
435 enum ContourApproximationModes {
436 /** stores absolutely all the contour points. That is, any 2 subsequent points (x1,y1) and
437 (x2,y2) of the contour will be either horizontal, vertical or diagonal neighbors, that is,
438 max(abs(x1-x2),abs(y2-y1))==1. */
439 CHAIN_APPROX_NONE = 1,
440 /** compresses horizontal, vertical, and diagonal segments and leaves only their end points.
441 For example, an up-right rectangular contour is encoded with 4 points. */
442 CHAIN_APPROX_SIMPLE = 2,
443 /** applies one of the flavors of the Teh-Chin chain approximation algorithm @cite TehChin89 */
444 CHAIN_APPROX_TC89_L1 = 3,
445 /** applies one of the flavors of the Teh-Chin chain approximation algorithm @cite TehChin89 */
446 CHAIN_APPROX_TC89_KCOS = 4
447 };
448
449 /** @brief Shape matching methods
450
451 \f$A\f$ denotes object1,\f$B\f$ denotes object2
452
453 \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$
454
455 and \f$h^A_i, h^B_i\f$ are the Hu moments of \f$A\f$ and \f$B\f$ , respectively.
456 */
457 enum ShapeMatchModes {
458 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]
459 CONTOURS_MATCH_I2 =2, //!< \f[I_2(A,B) = \sum _{i=1...7} \left | m^A_i - m^B_i \right |\f]
460 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]
461 };
462
463 //! @} imgproc_shape
464
465 //! @addtogroup imgproc_feature
466 //! @{
467
468 //! Variants of a Hough transform
469 enum HoughModes {
470
471 /** classical or standard Hough transform. Every line is represented by two floating-point
472 numbers \f$(\rho, \theta)\f$ , where \f$\rho\f$ is a distance between (0,0) point and the line,
473 and \f$\theta\f$ is the angle between x-axis and the normal to the line. Thus, the matrix must
474 be (the created sequence will be) of CV_32FC2 type */
475 HOUGH_STANDARD = 0,
476 /** probabilistic Hough transform (more efficient in case if the picture contains a few long
477 linear segments). It returns line segments rather than the whole line. Each segment is
478 represented by starting and ending points, and the matrix must be (the created sequence will
479 be) of the CV_32SC4 type. */
480 HOUGH_PROBABILISTIC = 1,
481 /** multi-scale variant of the classical Hough transform. The lines are encoded the same way as
482 HOUGH_STANDARD. */
483 HOUGH_MULTI_SCALE = 2,
484 HOUGH_GRADIENT = 3, //!< basically *21HT*, described in @cite Yuen90
485 HOUGH_GRADIENT_ALT = 4, //!< variation of HOUGH_GRADIENT to get better accuracy
486 };
487
488 //! Variants of Line Segment %Detector
489 enum LineSegmentDetectorModes {
490 LSD_REFINE_NONE = 0, //!< No refinement applied
491 LSD_REFINE_STD = 1, //!< Standard refinement is applied. E.g. breaking arches into smaller straighter line approximations.
492 LSD_REFINE_ADV = 2 //!< Advanced refinement. Number of false alarms is calculated, lines are
493 //!< refined through increase of precision, decrement in size, etc.
494 };
495
496 //! @} imgproc_feature
497
498 /** Histogram comparison methods
499 @ingroup imgproc_hist
500 */
501 enum HistCompMethods {
502 /** Correlation
503 \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]
504 where
505 \f[\bar{H_k} = \frac{1}{N} \sum _J H_k(J)\f]
506 and \f$N\f$ is a total number of histogram bins. */
507 HISTCMP_CORREL = 0,
508 /** Chi-Square
509 \f[d(H_1,H_2) = \sum _I \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)}\f] */
510 HISTCMP_CHISQR = 1,
511 /** Intersection
512 \f[d(H_1,H_2) = \sum _I \min (H_1(I), H_2(I))\f] */
513 HISTCMP_INTERSECT = 2,
514 /** Bhattacharyya distance
515 (In fact, OpenCV computes Hellinger distance, which is related to Bhattacharyya coefficient.)
516 \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] */
517 HISTCMP_BHATTACHARYYA = 3,
518 HISTCMP_HELLINGER = HISTCMP_BHATTACHARYYA, //!< Synonym for HISTCMP_BHATTACHARYYA
519 /** Alternative Chi-Square
520 \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]
521 This alternative formula is regularly used for texture comparison. See e.g. @cite Puzicha1997 */
522 HISTCMP_CHISQR_ALT = 4,
523 /** Kullback-Leibler divergence
524 \f[d(H_1,H_2) = \sum _I H_1(I) \log \left(\frac{H_1(I)}{H_2(I)}\right)\f] */
525 HISTCMP_KL_DIV = 5
526 };
527
528 /** the color conversion codes
529 @see @ref imgproc_color_conversions
530 @ingroup imgproc_color_conversions
531 */
532 enum ColorConversionCodes {
533 COLOR_BGR2BGRA = 0, //!< add alpha channel to RGB or BGR image
534 COLOR_RGB2RGBA = COLOR_BGR2BGRA,
535
536 COLOR_BGRA2BGR = 1, //!< remove alpha channel from RGB or BGR image
537 COLOR_RGBA2RGB = COLOR_BGRA2BGR,
538
539 COLOR_BGR2RGBA = 2, //!< convert between RGB and BGR color spaces (with or without alpha channel)
540 COLOR_RGB2BGRA = COLOR_BGR2RGBA,
541
542 COLOR_RGBA2BGR = 3,
543 COLOR_BGRA2RGB = COLOR_RGBA2BGR,
544
545 COLOR_BGR2RGB = 4,
546 COLOR_RGB2BGR = COLOR_BGR2RGB,
547
548 COLOR_BGRA2RGBA = 5,
549 COLOR_RGBA2BGRA = COLOR_BGRA2RGBA,
550
551 COLOR_BGR2GRAY = 6, //!< convert between RGB/BGR and grayscale, @ref color_convert_rgb_gray "color conversions"
552 COLOR_RGB2GRAY = 7,
553 COLOR_GRAY2BGR = 8,
554 COLOR_GRAY2RGB = COLOR_GRAY2BGR,
555 COLOR_GRAY2BGRA = 9,
556 COLOR_GRAY2RGBA = COLOR_GRAY2BGRA,
557 COLOR_BGRA2GRAY = 10,
558 COLOR_RGBA2GRAY = 11,
559
560 COLOR_BGR2BGR565 = 12, //!< convert between RGB/BGR and BGR565 (16-bit images)
561 COLOR_RGB2BGR565 = 13,
562 COLOR_BGR5652BGR = 14,
563 COLOR_BGR5652RGB = 15,
564 COLOR_BGRA2BGR565 = 16,
565 COLOR_RGBA2BGR565 = 17,
566 COLOR_BGR5652BGRA = 18,
567 COLOR_BGR5652RGBA = 19,
568
569 COLOR_GRAY2BGR565 = 20, //!< convert between grayscale to BGR565 (16-bit images)
570 COLOR_BGR5652GRAY = 21,
571
572 COLOR_BGR2BGR555 = 22, //!< convert between RGB/BGR and BGR555 (16-bit images)
573 COLOR_RGB2BGR555 = 23,
574 COLOR_BGR5552BGR = 24,
575 COLOR_BGR5552RGB = 25,
576 COLOR_BGRA2BGR555 = 26,
577 COLOR_RGBA2BGR555 = 27,
578 COLOR_BGR5552BGRA = 28,
579 COLOR_BGR5552RGBA = 29,
580
581 COLOR_GRAY2BGR555 = 30, //!< convert between grayscale and BGR555 (16-bit images)
582 COLOR_BGR5552GRAY = 31,
583
584 COLOR_BGR2XYZ = 32, //!< convert RGB/BGR to CIE XYZ, @ref color_convert_rgb_xyz "color conversions"
585 COLOR_RGB2XYZ = 33,
586 COLOR_XYZ2BGR = 34,
587 COLOR_XYZ2RGB = 35,
588
589 COLOR_BGR2YCrCb = 36, //!< convert RGB/BGR to luma-chroma (aka YCC), @ref color_convert_rgb_ycrcb "color conversions"
590 COLOR_RGB2YCrCb = 37,
591 COLOR_YCrCb2BGR = 38,
592 COLOR_YCrCb2RGB = 39,
593
594 COLOR_BGR2HSV = 40, //!< convert RGB/BGR to HSV (hue saturation value) with H range 0..180 if 8 bit image, @ref color_convert_rgb_hsv "color conversions"
595 COLOR_RGB2HSV = 41,
596
597 COLOR_BGR2Lab = 44, //!< convert RGB/BGR to CIE Lab, @ref color_convert_rgb_lab "color conversions"
598 COLOR_RGB2Lab = 45,
599
600 COLOR_BGR2Luv = 50, //!< convert RGB/BGR to CIE Luv, @ref color_convert_rgb_luv "color conversions"
601 COLOR_RGB2Luv = 51,
602 COLOR_BGR2HLS = 52, //!< convert RGB/BGR to HLS (hue lightness saturation) with H range 0..180 if 8 bit image, @ref color_convert_rgb_hls "color conversions"
603 COLOR_RGB2HLS = 53,
604
605 COLOR_HSV2BGR = 54, //!< backward conversions HSV to RGB/BGR with H range 0..180 if 8 bit image
606 COLOR_HSV2RGB = 55,
607
608 COLOR_Lab2BGR = 56,
609 COLOR_Lab2RGB = 57,
610 COLOR_Luv2BGR = 58,
611 COLOR_Luv2RGB = 59,
612 COLOR_HLS2BGR = 60, //!< backward conversions HLS to RGB/BGR with H range 0..180 if 8 bit image
613 COLOR_HLS2RGB = 61,
614
615 COLOR_BGR2HSV_FULL = 66, //!< convert RGB/BGR to HSV (hue saturation value) with H range 0..255 if 8 bit image, @ref color_convert_rgb_hsv "color conversions"
616 COLOR_RGB2HSV_FULL = 67,
617 COLOR_BGR2HLS_FULL = 68, //!< convert RGB/BGR to HLS (hue lightness saturation) with H range 0..255 if 8 bit image, @ref color_convert_rgb_hls "color conversions"
618 COLOR_RGB2HLS_FULL = 69,
619
620 COLOR_HSV2BGR_FULL = 70, //!< backward conversions HSV to RGB/BGR with H range 0..255 if 8 bit image
621 COLOR_HSV2RGB_FULL = 71,
622 COLOR_HLS2BGR_FULL = 72, //!< backward conversions HLS to RGB/BGR with H range 0..255 if 8 bit image
623 COLOR_HLS2RGB_FULL = 73,
624
625 COLOR_LBGR2Lab = 74,
626 COLOR_LRGB2Lab = 75,
627 COLOR_LBGR2Luv = 76,
628 COLOR_LRGB2Luv = 77,
629
630 COLOR_Lab2LBGR = 78,
631 COLOR_Lab2LRGB = 79,
632 COLOR_Luv2LBGR = 80,
633 COLOR_Luv2LRGB = 81,
634
635 COLOR_BGR2YUV = 82, //!< convert between RGB/BGR and YUV
636 COLOR_RGB2YUV = 83,
637 COLOR_YUV2BGR = 84,
638 COLOR_YUV2RGB = 85,
639
640 //! YUV 4:2:0 family to RGB
641 COLOR_YUV2RGB_NV12 = 90,
642 COLOR_YUV2BGR_NV12 = 91,
643 COLOR_YUV2RGB_NV21 = 92,
644 COLOR_YUV2BGR_NV21 = 93,
645 COLOR_YUV420sp2RGB = COLOR_YUV2RGB_NV21,
646 COLOR_YUV420sp2BGR = COLOR_YUV2BGR_NV21,
647
648 COLOR_YUV2RGBA_NV12 = 94,
649 COLOR_YUV2BGRA_NV12 = 95,
650 COLOR_YUV2RGBA_NV21 = 96,
651 COLOR_YUV2BGRA_NV21 = 97,
652 COLOR_YUV420sp2RGBA = COLOR_YUV2RGBA_NV21,
653 COLOR_YUV420sp2BGRA = COLOR_YUV2BGRA_NV21,
654
655 COLOR_YUV2RGB_YV12 = 98,
656 COLOR_YUV2BGR_YV12 = 99,
657 COLOR_YUV2RGB_IYUV = 100,
658 COLOR_YUV2BGR_IYUV = 101,
659 COLOR_YUV2RGB_I420 = COLOR_YUV2RGB_IYUV,
660 COLOR_YUV2BGR_I420 = COLOR_YUV2BGR_IYUV,
661 COLOR_YUV420p2RGB = COLOR_YUV2RGB_YV12,
662 COLOR_YUV420p2BGR = COLOR_YUV2BGR_YV12,
663
664 COLOR_YUV2RGBA_YV12 = 102,
665 COLOR_YUV2BGRA_YV12 = 103,
666 COLOR_YUV2RGBA_IYUV = 104,
667 COLOR_YUV2BGRA_IYUV = 105,
668 COLOR_YUV2RGBA_I420 = COLOR_YUV2RGBA_IYUV,
669 COLOR_YUV2BGRA_I420 = COLOR_YUV2BGRA_IYUV,
670 COLOR_YUV420p2RGBA = COLOR_YUV2RGBA_YV12,
671 COLOR_YUV420p2BGRA = COLOR_YUV2BGRA_YV12,
672
673 COLOR_YUV2GRAY_420 = 106,
674 COLOR_YUV2GRAY_NV21 = COLOR_YUV2GRAY_420,
675 COLOR_YUV2GRAY_NV12 = COLOR_YUV2GRAY_420,
676 COLOR_YUV2GRAY_YV12 = COLOR_YUV2GRAY_420,
677 COLOR_YUV2GRAY_IYUV = COLOR_YUV2GRAY_420,
678 COLOR_YUV2GRAY_I420 = COLOR_YUV2GRAY_420,
679 COLOR_YUV420sp2GRAY = COLOR_YUV2GRAY_420,
680 COLOR_YUV420p2GRAY = COLOR_YUV2GRAY_420,
681
682 //! YUV 4:2:2 family to RGB
683 COLOR_YUV2RGB_UYVY = 107,
684 COLOR_YUV2BGR_UYVY = 108,
685 //COLOR_YUV2RGB_VYUY = 109,
686 //COLOR_YUV2BGR_VYUY = 110,
687 COLOR_YUV2RGB_Y422 = COLOR_YUV2RGB_UYVY,
688 COLOR_YUV2BGR_Y422 = COLOR_YUV2BGR_UYVY,
689 COLOR_YUV2RGB_UYNV = COLOR_YUV2RGB_UYVY,
690 COLOR_YUV2BGR_UYNV = COLOR_YUV2BGR_UYVY,
691
692 COLOR_YUV2RGBA_UYVY = 111,
693 COLOR_YUV2BGRA_UYVY = 112,
694 //COLOR_YUV2RGBA_VYUY = 113,
695 //COLOR_YUV2BGRA_VYUY = 114,
696 COLOR_YUV2RGBA_Y422 = COLOR_YUV2RGBA_UYVY,
697 COLOR_YUV2BGRA_Y422 = COLOR_YUV2BGRA_UYVY,
698 COLOR_YUV2RGBA_UYNV = COLOR_YUV2RGBA_UYVY,
699 COLOR_YUV2BGRA_UYNV = COLOR_YUV2BGRA_UYVY,
700
701 COLOR_YUV2RGB_YUY2 = 115,
702 COLOR_YUV2BGR_YUY2 = 116,
703 COLOR_YUV2RGB_YVYU = 117,
704 COLOR_YUV2BGR_YVYU = 118,
705 COLOR_YUV2RGB_YUYV = COLOR_YUV2RGB_YUY2,
706 COLOR_YUV2BGR_YUYV = COLOR_YUV2BGR_YUY2,
707 COLOR_YUV2RGB_YUNV = COLOR_YUV2RGB_YUY2,
708 COLOR_YUV2BGR_YUNV = COLOR_YUV2BGR_YUY2,
709
710 COLOR_YUV2RGBA_YUY2 = 119,
711 COLOR_YUV2BGRA_YUY2 = 120,
712 COLOR_YUV2RGBA_YVYU = 121,
713 COLOR_YUV2BGRA_YVYU = 122,
714 COLOR_YUV2RGBA_YUYV = COLOR_YUV2RGBA_YUY2,
715 COLOR_YUV2BGRA_YUYV = COLOR_YUV2BGRA_YUY2,
716 COLOR_YUV2RGBA_YUNV = COLOR_YUV2RGBA_YUY2,
717 COLOR_YUV2BGRA_YUNV = COLOR_YUV2BGRA_YUY2,
718
719 COLOR_YUV2GRAY_UYVY = 123,
720 COLOR_YUV2GRAY_YUY2 = 124,
721 //CV_YUV2GRAY_VYUY = CV_YUV2GRAY_UYVY,
722 COLOR_YUV2GRAY_Y422 = COLOR_YUV2GRAY_UYVY,
723 COLOR_YUV2GRAY_UYNV = COLOR_YUV2GRAY_UYVY,
724 COLOR_YUV2GRAY_YVYU = COLOR_YUV2GRAY_YUY2,
725 COLOR_YUV2GRAY_YUYV = COLOR_YUV2GRAY_YUY2,
726 COLOR_YUV2GRAY_YUNV = COLOR_YUV2GRAY_YUY2,
727
728 //! alpha premultiplication
729 COLOR_RGBA2mRGBA = 125,
730 COLOR_mRGBA2RGBA = 126,
731
732 //! RGB to YUV 4:2:0 family
733 COLOR_RGB2YUV_I420 = 127,
734 COLOR_BGR2YUV_I420 = 128,
735 COLOR_RGB2YUV_IYUV = COLOR_RGB2YUV_I420,
736 COLOR_BGR2YUV_IYUV = COLOR_BGR2YUV_I420,
737
738 COLOR_RGBA2YUV_I420 = 129,
739 COLOR_BGRA2YUV_I420 = 130,
740 COLOR_RGBA2YUV_IYUV = COLOR_RGBA2YUV_I420,
741 COLOR_BGRA2YUV_IYUV = COLOR_BGRA2YUV_I420,
742 COLOR_RGB2YUV_YV12 = 131,
743 COLOR_BGR2YUV_YV12 = 132,
744 COLOR_RGBA2YUV_YV12 = 133,
745 COLOR_BGRA2YUV_YV12 = 134,
746
747 //! Demosaicing
748 COLOR_BayerBG2BGR = 46,
749 COLOR_BayerGB2BGR = 47,
750 COLOR_BayerRG2BGR = 48,
751 COLOR_BayerGR2BGR = 49,
752
753 COLOR_BayerBG2RGB = COLOR_BayerRG2BGR,
754 COLOR_BayerGB2RGB = COLOR_BayerGR2BGR,
755 COLOR_BayerRG2RGB = COLOR_BayerBG2BGR,
756 COLOR_BayerGR2RGB = COLOR_BayerGB2BGR,
757
758 COLOR_BayerBG2GRAY = 86,
759 COLOR_BayerGB2GRAY = 87,
760 COLOR_BayerRG2GRAY = 88,
761 COLOR_BayerGR2GRAY = 89,
762
763 //! Demosaicing using Variable Number of Gradients
764 COLOR_BayerBG2BGR_VNG = 62,
765 COLOR_BayerGB2BGR_VNG = 63,
766 COLOR_BayerRG2BGR_VNG = 64,
767 COLOR_BayerGR2BGR_VNG = 65,
768
769 COLOR_BayerBG2RGB_VNG = COLOR_BayerRG2BGR_VNG,
770 COLOR_BayerGB2RGB_VNG = COLOR_BayerGR2BGR_VNG,
771 COLOR_BayerRG2RGB_VNG = COLOR_BayerBG2BGR_VNG,
772 COLOR_BayerGR2RGB_VNG = COLOR_BayerGB2BGR_VNG,
773
774 //! Edge-Aware Demosaicing
775 COLOR_BayerBG2BGR_EA = 135,
776 COLOR_BayerGB2BGR_EA = 136,
777 COLOR_BayerRG2BGR_EA = 137,
778 COLOR_BayerGR2BGR_EA = 138,
779
780 COLOR_BayerBG2RGB_EA = COLOR_BayerRG2BGR_EA,
781 COLOR_BayerGB2RGB_EA = COLOR_BayerGR2BGR_EA,
782 COLOR_BayerRG2RGB_EA = COLOR_BayerBG2BGR_EA,
783 COLOR_BayerGR2RGB_EA = COLOR_BayerGB2BGR_EA,
784
785 //! Demosaicing with alpha channel
786 COLOR_BayerBG2BGRA = 139,
787 COLOR_BayerGB2BGRA = 140,
788 COLOR_BayerRG2BGRA = 141,
789 COLOR_BayerGR2BGRA = 142,
790
791 COLOR_BayerBG2RGBA = COLOR_BayerRG2BGRA,
792 COLOR_BayerGB2RGBA = COLOR_BayerGR2BGRA,
793 COLOR_BayerRG2RGBA = COLOR_BayerBG2BGRA,
794 COLOR_BayerGR2RGBA = COLOR_BayerGB2BGRA,
795
796 COLOR_COLORCVT_MAX = 143
797 };
798
799 //! @addtogroup imgproc_shape
800 //! @{
801
802 //! types of intersection between rectangles
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
807 };
808
809 /** types of line
810 @ingroup imgproc_draw
811 */
812 enum LineTypes {
813 FILLED = -1,
814 LINE_4 = 4, //!< 4-connected line
815 LINE_8 = 8, //!< 8-connected line
816 LINE_AA = 16 //!< antialiased line
817 };
818
819 /** Only a subset of Hershey fonts <https://en.wikipedia.org/wiki/Hershey_fonts> are supported
820 @ingroup imgproc_draw
821 */
822 enum HersheyFonts {
823 FONT_HERSHEY_SIMPLEX = 0, //!< normal size sans-serif font
824 FONT_HERSHEY_PLAIN = 1, //!< small size sans-serif font
825 FONT_HERSHEY_DUPLEX = 2, //!< normal size sans-serif font (more complex than FONT_HERSHEY_SIMPLEX)
826 FONT_HERSHEY_COMPLEX = 3, //!< normal size serif font
827 FONT_HERSHEY_TRIPLEX = 4, //!< normal size serif font (more complex than FONT_HERSHEY_COMPLEX)
828 FONT_HERSHEY_COMPLEX_SMALL = 5, //!< smaller version of FONT_HERSHEY_COMPLEX
829 FONT_HERSHEY_SCRIPT_SIMPLEX = 6, //!< hand-writing style font
830 FONT_HERSHEY_SCRIPT_COMPLEX = 7, //!< more complex variant of FONT_HERSHEY_SCRIPT_SIMPLEX
831 FONT_ITALIC = 16 //!< flag for italic font
832 };
833
834 /** Possible set of marker types used for the cv::drawMarker function
835 @ingroup imgproc_draw
836 */
837 enum MarkerTypes
838 {
839 MARKER_CROSS = 0, //!< A crosshair marker shape
840 MARKER_TILTED_CROSS = 1, //!< A 45 degree tilted crosshair marker shape
841 MARKER_STAR = 2, //!< A star marker shape, combination of cross and tilted cross
842 MARKER_DIAMOND = 3, //!< A diamond marker shape
843 MARKER_SQUARE = 4, //!< A square marker shape
844 MARKER_TRIANGLE_UP = 5, //!< An upwards pointing triangle marker shape
845 MARKER_TRIANGLE_DOWN = 6 //!< A downwards pointing triangle marker shape
846 };
847
848 /** @brief finds arbitrary template in the grayscale image using Generalized Hough Transform
849 */
850 class CV_EXPORTS_W GeneralizedHough : public Algorithm
851 {
852 public:
853 //! set template to search
854 CV_WRAP virtual void setTemplate(InputArray templ, Point templCenter = Point(-1, -1)) = 0;
855 CV_WRAP virtual void setTemplate(InputArray edges, InputArray dx, InputArray dy, Point templCenter = Point(-1, -1)) = 0;
856
857 //! find template on image
858 CV_WRAP virtual void detect(InputArray image, OutputArray positions, OutputArray votes = noArray()) = 0;
859 CV_WRAP virtual void detect(InputArray edges, InputArray dx, InputArray dy, OutputArray positions, OutputArray votes = noArray()) = 0;
860
861 //! Canny low threshold.
862 CV_WRAP virtual void setCannyLowThresh(int cannyLowThresh) = 0;
863 CV_WRAP virtual int getCannyLowThresh() const = 0;
864
865 //! Canny high threshold.
866 CV_WRAP virtual void setCannyHighThresh(int cannyHighThresh) = 0;
867 CV_WRAP virtual int getCannyHighThresh() const = 0;
868
869 //! Minimum distance between the centers of the detected objects.
870 CV_WRAP virtual void setMinDist(double minDist) = 0;
871 CV_WRAP virtual double getMinDist() const = 0;
872
873 //! Inverse ratio of the accumulator resolution to the image resolution.
874 CV_WRAP virtual void setDp(double dp) = 0;
875 CV_WRAP virtual double getDp() const = 0;
876
877 //! Maximal size of inner buffers.
878 CV_WRAP virtual void setMaxBufferSize(int maxBufferSize) = 0;
879 CV_WRAP virtual int getMaxBufferSize() const = 0;
880 };
881
882 /** @brief finds arbitrary template in the grayscale image using Generalized Hough Transform
883
884 Detects position only without translation and rotation @cite Ballard1981 .
885 */
886 class CV_EXPORTS_W GeneralizedHoughBallard : public GeneralizedHough
887 {
888 public:
889 //! R-Table levels.
890 CV_WRAP virtual void setLevels(int levels) = 0;
891 CV_WRAP virtual int getLevels() const = 0;
892
893 //! The accumulator threshold for the template centers at the detection stage. The smaller it is, the more false positions may be detected.
894 CV_WRAP virtual void setVotesThreshold(int votesThreshold) = 0;
895 CV_WRAP virtual int getVotesThreshold() const = 0;
896 };
897
898 /** @brief finds arbitrary template in the grayscale image using Generalized Hough Transform
899
900 Detects position, translation and rotation @cite Guil1999 .
901 */
902 class CV_EXPORTS_W GeneralizedHoughGuil : public GeneralizedHough
903 {
904 public:
905 //! Angle difference in degrees between two points in feature.
906 CV_WRAP virtual void setXi(double xi) = 0;
907 CV_WRAP virtual double getXi() const = 0;
908
909 //! Feature table levels.
910 CV_WRAP virtual void setLevels(int levels) = 0;
911 CV_WRAP virtual int getLevels() const = 0;
912
913 //! Maximal difference between angles that treated as equal.
914 CV_WRAP virtual void setAngleEpsilon(double angleEpsilon) = 0;
915 CV_WRAP virtual double getAngleEpsilon() const = 0;
916
917 //! Minimal rotation angle to detect in degrees.
918 CV_WRAP virtual void setMinAngle(double minAngle) = 0;
919 CV_WRAP virtual double getMinAngle() const = 0;
920
921 //! Maximal rotation angle to detect in degrees.
922 CV_WRAP virtual void setMaxAngle(double maxAngle) = 0;
923 CV_WRAP virtual double getMaxAngle() const = 0;
924
925 //! Angle step in degrees.
926 CV_WRAP virtual void setAngleStep(double angleStep) = 0;
927 CV_WRAP virtual double getAngleStep() const = 0;
928
929 //! Angle votes threshold.
930 CV_WRAP virtual void setAngleThresh(int angleThresh) = 0;
931 CV_WRAP virtual int getAngleThresh() const = 0;
932
933 //! Minimal scale to detect.
934 CV_WRAP virtual void setMinScale(double minScale) = 0;
935 CV_WRAP virtual double getMinScale() const = 0;
936
937 //! Maximal scale to detect.
938 CV_WRAP virtual void setMaxScale(double maxScale) = 0;
939 CV_WRAP virtual double getMaxScale() const = 0;
940
941 //! Scale step.
942 CV_WRAP virtual void setScaleStep(double scaleStep) = 0;
943 CV_WRAP virtual double getScaleStep() const = 0;
944
945 //! Scale votes threshold.
946 CV_WRAP virtual void setScaleThresh(int scaleThresh) = 0;
947 CV_WRAP virtual int getScaleThresh() const = 0;
948
949 //! Position votes threshold.
950 CV_WRAP virtual void setPosThresh(int posThresh) = 0;
951 CV_WRAP virtual int getPosThresh() const = 0;
952 };
953
954 //! @} imgproc_shape
955
956 //! @addtogroup imgproc_hist
957 //! @{
958
959 /** @brief Base class for Contrast Limited Adaptive Histogram Equalization.
960 */
961 class CV_EXPORTS_W CLAHE : public Algorithm
962 {
963 public:
964 /** @brief Equalizes the histogram of a grayscale image using Contrast Limited Adaptive Histogram Equalization.
965
966 @param src Source image of type CV_8UC1 or CV_16UC1.
967 @param dst Destination image.
968 */
969 CV_WRAP virtual void apply(InputArray src, OutputArray dst) = 0;
970
971 /** @brief Sets threshold for contrast limiting.
972
973 @param clipLimit threshold value.
974 */
975 CV_WRAP virtual void setClipLimit(double clipLimit) = 0;
976
977 //! Returns threshold value for contrast limiting.
978 CV_WRAP virtual double getClipLimit() const = 0;
979
980 /** @brief Sets size of grid for histogram equalization. Input image will be divided into
981 equally sized rectangular tiles.
982
983 @param tileGridSize defines the number of tiles in row and column.
984 */
985 CV_WRAP virtual void setTilesGridSize(Size tileGridSize) = 0;
986
987 //!@brief Returns Size defines the number of tiles in row and column.
988 CV_WRAP virtual Size getTilesGridSize() const = 0;
989
990 CV_WRAP virtual void collectGarbage() = 0;
991 };
992
993 //! @} imgproc_hist
994
995 //! @addtogroup imgproc_subdiv2d
996 //! @{
997
998 class CV_EXPORTS_W Subdiv2D
999 {
1000 public:
1001 /** Subdiv2D point location cases */
1002 enum { PTLOC_ERROR = -2, //!< Point location error
1003 PTLOC_OUTSIDE_RECT = -1, //!< Point outside the subdivision bounding rect
1004 PTLOC_INSIDE = 0, //!< Point inside some facet
1005 PTLOC_VERTEX = 1, //!< Point coincides with one of the subdivision vertices
1006 PTLOC_ON_EDGE = 2 //!< Point on some edge
1007 };
1008
1009 /** Subdiv2D edge type navigation (see: getEdge()) */
1010 enum { NEXT_AROUND_ORG = 0x00,
1011 NEXT_AROUND_DST = 0x22,
1012 PREV_AROUND_ORG = 0x11,
1013 PREV_AROUND_DST = 0x33,
1014 NEXT_AROUND_LEFT = 0x13,
1015 NEXT_AROUND_RIGHT = 0x31,
1016 PREV_AROUND_LEFT = 0x20,
1017 PREV_AROUND_RIGHT = 0x02
1018 };
1019
1020 /** creates an empty Subdiv2D object.
1021 To create a new empty Delaunay subdivision you need to use the #initDelaunay function.
1022 */
1023 CV_WRAP Subdiv2D();
1024
1025 /** @overload
1026
1027 @param rect Rectangle that includes all of the 2D points that are to be added to the subdivision.
1028
1029 The function creates an empty Delaunay subdivision where 2D points can be added using the function
1030 insert() . All of the points to be added must be within the specified rectangle, otherwise a runtime
1031 error is raised.
1032 */
1033 CV_WRAP Subdiv2D(Rect rect);
1034
1035 /** @brief Creates a new empty Delaunay subdivision
1036
1037 @param rect Rectangle that includes all of the 2D points that are to be added to the subdivision.
1038
1039 */
1040 CV_WRAP void initDelaunay(Rect rect);
1041
1042 /** @brief Insert a single point into a Delaunay triangulation.
1043
1044 @param pt Point to insert.
1045
1046 The function inserts a single point into a subdivision and modifies the subdivision topology
1047 appropriately. If a point with the same coordinates exists already, no new point is added.
1048 @returns the ID of the point.
1049
1050 @note If the point is outside of the triangulation specified rect a runtime error is raised.
1051 */
1052 CV_WRAP int insert(Point2f pt);
1053
1054 /** @brief Insert multiple points into a Delaunay triangulation.
1055
1056 @param ptvec Points to insert.
1057
1058 The function inserts a vector of points into a subdivision and modifies the subdivision topology
1059 appropriately.
1060 */
1061 CV_WRAP void insert(const std::vector<Point2f>& ptvec);
1062
1063 /** @brief Returns the location of a point within a Delaunay triangulation.
1064
1065 @param pt Point to locate.
1066 @param edge Output edge that the point belongs to or is located to the right of it.
1067 @param vertex Optional output vertex the input point coincides with.
1068
1069 The function locates the input point within the subdivision and gives one of the triangle edges
1070 or vertices.
1071
1072 @returns an integer which specify one of the following five cases for point location:
1073 - The point falls into some facet. The function returns #PTLOC_INSIDE and edge will contain one of
1074 edges of the facet.
1075 - The point falls onto the edge. The function returns #PTLOC_ON_EDGE and edge will contain this edge.
1076 - The point coincides with one of the subdivision vertices. The function returns #PTLOC_VERTEX and
1077 vertex will contain a pointer to the vertex.
1078 - The point is outside the subdivision reference rectangle. The function returns #PTLOC_OUTSIDE_RECT
1079 and no pointers are filled.
1080 - One of input arguments is invalid. A runtime error is raised or, if silent or "parent" error
1081 processing mode is selected, #PTLOC_ERROR is returned.
1082 */
1083 CV_WRAP int locate(Point2f pt, CV_OUT int& edge, CV_OUT int& vertex);
1084
1085 /** @brief Finds the subdivision vertex closest to the given point.
1086
1087 @param pt Input point.
1088 @param nearestPt Output subdivision vertex point.
1089
1090 The function is another function that locates the input point within the subdivision. It finds the
1091 subdivision vertex that is the closest to the input point. It is not necessarily one of vertices
1092 of the facet containing the input point, though the facet (located using locate() ) is used as a
1093 starting point.
1094
1095 @returns vertex ID.
1096 */
1097 CV_WRAP int findNearest(Point2f pt, CV_OUT Point2f* nearestPt = 0);
1098
1099 /** @brief Returns a list of all edges.
1100
1101 @param edgeList Output vector.
1102
1103 The function gives each edge as a 4 numbers vector, where each two are one of the edge
1104 vertices. i.e. org_x = v[0], org_y = v[1], dst_x = v[2], dst_y = v[3].
1105 */
1106 CV_WRAP void getEdgeList(CV_OUT std::vector<Vec4f>& edgeList) const;
1107
1108 /** @brief Returns a list of the leading edge ID connected to each triangle.
1109
1110 @param leadingEdgeList Output vector.
1111
1112 The function gives one edge ID for each triangle.
1113 */
1114 CV_WRAP void getLeadingEdgeList(CV_OUT std::vector<int>& leadingEdgeList) const;
1115
1116 /** @brief Returns a list of all triangles.
1117
1118 @param triangleList Output vector.
1119
1120 The function gives each triangle as a 6 numbers vector, where each two are one of the triangle
1121 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].
1122 */
1123 CV_WRAP void getTriangleList(CV_OUT std::vector<Vec6f>& triangleList) const;
1124
1125 /** @brief Returns a list of all Voronoi facets.
1126
1127 @param idx Vector of vertices IDs to consider. For all vertices you can pass empty vector.
1128 @param facetList Output vector of the Voronoi facets.
1129 @param facetCenters Output vector of the Voronoi facets center points.
1130
1131 */
1132 CV_WRAP void getVoronoiFacetList(const std::vector<int>& idx, CV_OUT std::vector<std::vector<Point2f> >& facetList,
1133 CV_OUT std::vector<Point2f>& facetCenters);
1134
1135 /** @brief Returns vertex location from vertex ID.
1136
1137 @param vertex vertex ID.
1138 @param firstEdge Optional. The first edge ID which is connected to the vertex.
1139 @returns vertex (x,y)
1140
1141 */
1142 CV_WRAP Point2f getVertex(int vertex, CV_OUT int* firstEdge = 0) const;
1143
1144 /** @brief Returns one of the edges related to the given edge.
1145
1146 @param edge Subdivision edge ID.
1147 @param nextEdgeType Parameter specifying which of the related edges to return.
1148 The following values are possible:
1149 - NEXT_AROUND_ORG next around the edge origin ( eOnext on the picture below if e is the input edge)
1150 - NEXT_AROUND_DST next around the edge vertex ( eDnext )
1151 - PREV_AROUND_ORG previous around the edge origin (reversed eRnext )
1152 - PREV_AROUND_DST previous around the edge destination (reversed eLnext )
1153 - NEXT_AROUND_LEFT next around the left facet ( eLnext )
1154 - NEXT_AROUND_RIGHT next around the right facet ( eRnext )
1155 - PREV_AROUND_LEFT previous around the left facet (reversed eOnext )
1156 - PREV_AROUND_RIGHT previous around the right facet (reversed eDnext )
1157
1158 ![sample output](pics/quadedge.png)
1159
1160 @returns edge ID related to the input edge.
1161 */
1162 CV_WRAP int getEdge( int edge, int nextEdgeType ) const;
1163
1164 /** @brief Returns next edge around the edge origin.
1165
1166 @param edge Subdivision edge ID.
1167
1168 @returns an integer which is next edge ID around the edge origin: eOnext on the
1169 picture above if e is the input edge).
1170 */
1171 CV_WRAP int nextEdge(int edge) const;
1172
1173 /** @brief Returns another edge of the same quad-edge.
1174
1175 @param edge Subdivision edge ID.
1176 @param rotate Parameter specifying which of the edges of the same quad-edge as the input
1177 one to return. The following values are possible:
1178 - 0 - the input edge ( e on the picture below if e is the input edge)
1179 - 1 - the rotated edge ( eRot )
1180 - 2 - the reversed edge (reversed e (in green))
1181 - 3 - the reversed rotated edge (reversed eRot (in green))
1182
1183 @returns one of the edges ID of the same quad-edge as the input edge.
1184 */
1185 CV_WRAP int rotateEdge(int edge, int rotate) const;
1186 CV_WRAP int symEdge(int edge) const;
1187
1188 /** @brief Returns the edge origin.
1189
1190 @param edge Subdivision edge ID.
1191 @param orgpt Output vertex location.
1192
1193 @returns vertex ID.
1194 */
1195 CV_WRAP int edgeOrg(int edge, CV_OUT Point2f* orgpt = 0) const;
1196
1197 /** @brief Returns the edge destination.
1198
1199 @param edge Subdivision edge ID.
1200 @param dstpt Output vertex location.
1201
1202 @returns vertex ID.
1203 */
1204 CV_WRAP int edgeDst(int edge, CV_OUT Point2f* dstpt = 0) const;
1205
1206 protected:
1207 int newEdge();
1208 void deleteEdge(int edge);
1209 int newPoint(Point2f pt, bool isvirtual, int firstEdge = 0);
1210 void deletePoint(int vtx);
1211 void setEdgePoints( int edge, int orgPt, int dstPt );
1212 void splice( int edgeA, int edgeB );
1213 int connectEdges( int edgeA, int edgeB );
1214 void swapEdges( int edge );
1215 int isRightOf(Point2f pt, int edge) const;
1216 void calcVoronoi();
1217 void clearVoronoi();
1218 void checkSubdiv() const;
1219
1220 struct CV_EXPORTS Vertex
1221 {
1222 Vertex();
1223 Vertex(Point2f pt, bool isvirtual, int firstEdge=0);
1224 bool isvirtual() const;
1225 bool isfree() const;
1226
1227 int firstEdge;
1228 int type;
1229 Point2f pt;
1230 };
1231
1232 struct CV_EXPORTS QuadEdge
1233 {
1234 QuadEdge();
1235 QuadEdge(int edgeidx);
1236 bool isfree() const;
1237
1238 int next[4];
1239 int pt[4];
1240 };
1241
1242 //! All of the vertices
1243 std::vector<Vertex> vtx;
1244 //! All of the edges
1245 std::vector<QuadEdge> qedges;
1246 int freeQEdge;
1247 int freePoint;
1248 bool validGeometry;
1249
1250 int recentEdge;
1251 //! Top left corner of the bounding rect
1252 Point2f topLeft;
1253 //! Bottom right corner of the bounding rect
1254 Point2f bottomRight;
1255 };
1256
1257 //! @} imgproc_subdiv2d
1258
1259 //! @addtogroup imgproc_feature
1260 //! @{
1261
1262 /** @brief Line segment detector class
1263
1264 following the algorithm described at @cite Rafael12 .
1265
1266 @note Implementation has been removed due original code license conflict
1267
1268 */
1269 class CV_EXPORTS_W LineSegmentDetector : public Algorithm
1270 {
1271 public:
1272
1273 /** @brief Finds lines in the input image.
1274
1275 This is the output of the default parameters of the algorithm on the above shown image.
1276
1277 ![image](pics/building_lsd.png)
1278
1279 @param image A grayscale (CV_8UC1) input image. If only a roi needs to be selected, use:
1280 `lsd_ptr-\>detect(image(roi), lines, ...); lines += Scalar(roi.x, roi.y, roi.x, roi.y);`
1281 @param lines A vector of Vec4i or Vec4f elements specifying the beginning and ending point of a line. Where
1282 Vec4i/Vec4f is (x1, y1, x2, y2), point 1 is the start, point 2 - end. Returned lines are strictly
1283 oriented depending on the gradient.
1284 @param width Vector of widths of the regions, where the lines are found. E.g. Width of line.
1285 @param prec Vector of precisions with which the lines are found.
1286 @param nfa Vector containing number of false alarms in the line region, with precision of 10%. The
1287 bigger the value, logarithmically better the detection.
1288 - -1 corresponds to 10 mean false alarms
1289 - 0 corresponds to 1 mean false alarm
1290 - 1 corresponds to 0.1 mean false alarms
1291 This vector will be calculated only when the objects type is #LSD_REFINE_ADV.
1292 */
1293 CV_WRAP virtual void detect(InputArray image, OutputArray lines,
1294 OutputArray width = noArray(), OutputArray prec = noArray(),
1295 OutputArray nfa = noArray()) = 0;
1296
1297 /** @brief Draws the line segments on a given image.
1298 @param image The image, where the lines will be drawn. Should be bigger or equal to the image,
1299 where the lines were found.
1300 @param lines A vector of the lines that needed to be drawn.
1301 */
1302 CV_WRAP virtual void drawSegments(InputOutputArray image, InputArray lines) = 0;
1303
1304 /** @brief Draws two groups of lines in blue and red, counting the non overlapping (mismatching) pixels.
1305
1306 @param size The size of the image, where lines1 and lines2 were found.
1307 @param lines1 The first group of lines that needs to be drawn. It is visualized in blue color.
1308 @param lines2 The second group of lines. They visualized in red color.
1309 @param image Optional image, where the lines will be drawn. The image should be color(3-channel)
1310 in order for lines1 and lines2 to be drawn in the above mentioned colors.
1311 */
1312 CV_WRAP virtual int compareSegments(const Size& size, InputArray lines1, InputArray lines2, InputOutputArray image = noArray()) = 0;
1313
~LineSegmentDetector()1314 virtual ~LineSegmentDetector() { }
1315 };
1316
1317 /** @brief Creates a smart pointer to a LineSegmentDetector object and initializes it.
1318
1319 The LineSegmentDetector algorithm is defined using the standard values. Only advanced users may want
1320 to edit those, as to tailor it for their own application.
1321
1322 @param refine The way found lines will be refined, see #LineSegmentDetectorModes
1323 @param scale The scale of the image that will be used to find the lines. Range (0..1].
1324 @param sigma_scale Sigma for Gaussian filter. It is computed as sigma = sigma_scale/scale.
1325 @param quant Bound to the quantization error on the gradient norm.
1326 @param ang_th Gradient angle tolerance in degrees.
1327 @param log_eps Detection threshold: -log10(NFA) \> log_eps. Used only when advance refinement is chosen.
1328 @param density_th Minimal density of aligned region points in the enclosing rectangle.
1329 @param n_bins Number of bins in pseudo-ordering of gradient modulus.
1330
1331 @note Implementation has been removed due original code license conflict
1332 */
1333 CV_EXPORTS_W Ptr<LineSegmentDetector> createLineSegmentDetector(
1334 int refine = LSD_REFINE_STD, double scale = 0.8,
1335 double sigma_scale = 0.6, double quant = 2.0, double ang_th = 22.5,
1336 double log_eps = 0, double density_th = 0.7, int n_bins = 1024);
1337
1338 //! @} imgproc_feature
1339
1340 //! @addtogroup imgproc_filter
1341 //! @{
1342
1343 /** @brief Returns Gaussian filter coefficients.
1344
1345 The function computes and returns the \f$\texttt{ksize} \times 1\f$ matrix of Gaussian filter
1346 coefficients:
1347
1348 \f[G_i= \alpha *e^{-(i-( \texttt{ksize} -1)/2)^2/(2* \texttt{sigma}^2)},\f]
1349
1350 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$.
1351
1352 Two of such generated kernels can be passed to sepFilter2D. Those functions automatically recognize
1353 smoothing kernels (a symmetrical kernel with sum of weights equal to 1) and handle them accordingly.
1354 You may also use the higher-level GaussianBlur.
1355 @param ksize Aperture size. It should be odd ( \f$\texttt{ksize} \mod 2 = 1\f$ ) and positive.
1356 @param sigma Gaussian standard deviation. If it is non-positive, it is computed from ksize as
1357 `sigma = 0.3*((ksize-1)*0.5 - 1) + 0.8`.
1358 @param ktype Type of filter coefficients. It can be CV_32F or CV_64F .
1359 @sa sepFilter2D, getDerivKernels, getStructuringElement, GaussianBlur
1360 */
1361 CV_EXPORTS_W Mat getGaussianKernel( int ksize, double sigma, int ktype = CV_64F );
1362
1363 /** @brief Returns filter coefficients for computing spatial image derivatives.
1364
1365 The function computes and returns the filter coefficients for spatial image derivatives. When
1366 `ksize=FILTER_SCHARR`, the Scharr \f$3 \times 3\f$ kernels are generated (see #Scharr). Otherwise, Sobel
1367 kernels are generated (see #Sobel). The filters are normally passed to #sepFilter2D or to
1368
1369 @param kx Output matrix of row filter coefficients. It has the type ktype .
1370 @param ky Output matrix of column filter coefficients. It has the type ktype .
1371 @param dx Derivative order in respect of x.
1372 @param dy Derivative order in respect of y.
1373 @param ksize Aperture size. It can be FILTER_SCHARR, 1, 3, 5, or 7.
1374 @param normalize Flag indicating whether to normalize (scale down) the filter coefficients or not.
1375 Theoretically, the coefficients should have the denominator \f$=2^{ksize*2-dx-dy-2}\f$. If you are
1376 going to filter floating-point images, you are likely to use the normalized kernels. But if you
1377 compute derivatives of an 8-bit image, store the results in a 16-bit image, and wish to preserve
1378 all the fractional bits, you may want to set normalize=false .
1379 @param ktype Type of filter coefficients. It can be CV_32f or CV_64F .
1380 */
1381 CV_EXPORTS_W void getDerivKernels( OutputArray kx, OutputArray ky,
1382 int dx, int dy, int ksize,
1383 bool normalize = false, int ktype = CV_32F );
1384
1385 /** @brief Returns Gabor filter coefficients.
1386
1387 For more details about gabor filter equations and parameters, see: [Gabor
1388 Filter](http://en.wikipedia.org/wiki/Gabor_filter).
1389
1390 @param ksize Size of the filter returned.
1391 @param sigma Standard deviation of the gaussian envelope.
1392 @param theta Orientation of the normal to the parallel stripes of a Gabor function.
1393 @param lambd Wavelength of the sinusoidal factor.
1394 @param gamma Spatial aspect ratio.
1395 @param psi Phase offset.
1396 @param ktype Type of filter coefficients. It can be CV_32F or CV_64F .
1397 */
1398 CV_EXPORTS_W Mat getGaborKernel( Size ksize, double sigma, double theta, double lambd,
1399 double gamma, double psi = CV_PI*0.5, int ktype = CV_64F );
1400
1401 //! returns "magic" border value for erosion and dilation. It is automatically transformed to Scalar::all(-DBL_MAX) for dilation.
morphologyDefaultBorderValue()1402 static inline Scalar morphologyDefaultBorderValue() { return Scalar::all(DBL_MAX); }
1403
1404 /** @brief Returns a structuring element of the specified size and shape for morphological operations.
1405
1406 The function constructs and returns the structuring element that can be further passed to #erode,
1407 #dilate or #morphologyEx. But you can also construct an arbitrary binary mask yourself and use it as
1408 the structuring element.
1409
1410 @param shape Element shape that could be one of #MorphShapes
1411 @param ksize Size of the structuring element.
1412 @param anchor Anchor position within the element. The default value \f$(-1, -1)\f$ means that the
1413 anchor is at the center. Note that only the shape of a cross-shaped element depends on the anchor
1414 position. In other cases the anchor just regulates how much the result of the morphological
1415 operation is shifted.
1416 */
1417 CV_EXPORTS_W Mat getStructuringElement(int shape, Size ksize, Point anchor = Point(-1,-1));
1418
1419 /** @example samples/cpp/tutorial_code/ImgProc/Smoothing/Smoothing.cpp
1420 Sample code for simple filters
1421 ![Sample screenshot](Smoothing_Tutorial_Result_Median_Filter.jpg)
1422 Check @ref tutorial_gausian_median_blur_bilateral_filter "the corresponding tutorial" for more details
1423 */
1424
1425 /** @brief Blurs an image using the median filter.
1426
1427 The function smoothes an image using the median filter with the \f$\texttt{ksize} \times
1428 \texttt{ksize}\f$ aperture. Each channel of a multi-channel image is processed independently.
1429 In-place operation is supported.
1430
1431 @note The median filter uses #BORDER_REPLICATE internally to cope with border pixels, see #BorderTypes
1432
1433 @param src input 1-, 3-, or 4-channel image; when ksize is 3 or 5, the image depth should be
1434 CV_8U, CV_16U, or CV_32F, for larger aperture sizes, it can only be CV_8U.
1435 @param dst destination array of the same size and type as src.
1436 @param ksize aperture linear size; it must be odd and greater than 1, for example: 3, 5, 7 ...
1437 @sa bilateralFilter, blur, boxFilter, GaussianBlur
1438 */
1439 CV_EXPORTS_W void medianBlur( InputArray src, OutputArray dst, int ksize );
1440
1441 /** @brief Blurs an image using a Gaussian filter.
1442
1443 The function convolves the source image with the specified Gaussian kernel. In-place filtering is
1444 supported.
1445
1446 @param src input image; the image can have any number of channels, which are processed
1447 independently, but the depth should be CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
1448 @param dst output image of the same size and type as src.
1449 @param ksize Gaussian kernel size. ksize.width and ksize.height can differ but they both must be
1450 positive and odd. Or, they can be zero's and then they are computed from sigma.
1451 @param sigmaX Gaussian kernel standard deviation in X direction.
1452 @param sigmaY Gaussian kernel standard deviation in Y direction; if sigmaY is zero, it is set to be
1453 equal to sigmaX, if both sigmas are zeros, they are computed from ksize.width and ksize.height,
1454 respectively (see #getGaussianKernel for details); to fully control the result regardless of
1455 possible future modifications of all this semantics, it is recommended to specify all of ksize,
1456 sigmaX, and sigmaY.
1457 @param borderType pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
1458
1459 @sa sepFilter2D, filter2D, blur, boxFilter, bilateralFilter, medianBlur
1460 */
1461 CV_EXPORTS_W void GaussianBlur( InputArray src, OutputArray dst, Size ksize,
1462 double sigmaX, double sigmaY = 0,
1463 int borderType = BORDER_DEFAULT );
1464
1465 /** @brief Applies the bilateral filter to an image.
1466
1467 The function applies bilateral filtering to the input image, as described in
1468 http://www.dai.ed.ac.uk/CVonline/LOCAL_COPIES/MANDUCHI1/Bilateral_Filtering.html
1469 bilateralFilter can reduce unwanted noise very well while keeping edges fairly sharp. However, it is
1470 very slow compared to most filters.
1471
1472 _Sigma values_: For simplicity, you can set the 2 sigma values to be the same. If they are small (\<
1473 10), the filter will not have much effect, whereas if they are large (\> 150), they will have a very
1474 strong effect, making the image look "cartoonish".
1475
1476 _Filter size_: Large filters (d \> 5) are very slow, so it is recommended to use d=5 for real-time
1477 applications, and perhaps d=9 for offline applications that need heavy noise filtering.
1478
1479 This filter does not work inplace.
1480 @param src Source 8-bit or floating-point, 1-channel or 3-channel image.
1481 @param dst Destination image of the same size and type as src .
1482 @param d Diameter of each pixel neighborhood that is used during filtering. If it is non-positive,
1483 it is computed from sigmaSpace.
1484 @param sigmaColor Filter sigma in the color space. A larger value of the parameter means that
1485 farther colors within the pixel neighborhood (see sigmaSpace) will be mixed together, resulting
1486 in larger areas of semi-equal color.
1487 @param sigmaSpace Filter sigma in the coordinate space. A larger value of the parameter means that
1488 farther pixels will influence each other as long as their colors are close enough (see sigmaColor
1489 ). When d\>0, it specifies the neighborhood size regardless of sigmaSpace. Otherwise, d is
1490 proportional to sigmaSpace.
1491 @param borderType border mode used to extrapolate pixels outside of the image, see #BorderTypes
1492 */
1493 CV_EXPORTS_W void bilateralFilter( InputArray src, OutputArray dst, int d,
1494 double sigmaColor, double sigmaSpace,
1495 int borderType = BORDER_DEFAULT );
1496
1497 /** @brief Blurs an image using the box filter.
1498
1499 The function smooths an image using the kernel:
1500
1501 \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]
1502
1503 where
1504
1505 \f[\alpha = \begin{cases} \frac{1}{\texttt{ksize.width*ksize.height}} & \texttt{when } \texttt{normalize=true} \\1 & \texttt{otherwise}\end{cases}\f]
1506
1507 Unnormalized box filter is useful for computing various integral characteristics over each pixel
1508 neighborhood, such as covariance matrices of image derivatives (used in dense optical flow
1509 algorithms, and so on). If you need to compute pixel sums over variable-size windows, use #integral.
1510
1511 @param src input image.
1512 @param dst output image of the same size and type as src.
1513 @param ddepth the output image depth (-1 to use src.depth()).
1514 @param ksize blurring kernel size.
1515 @param anchor anchor point; default value Point(-1,-1) means that the anchor is at the kernel
1516 center.
1517 @param normalize flag, specifying whether the kernel is normalized by its area or not.
1518 @param borderType border mode used to extrapolate pixels outside of the image, see #BorderTypes. #BORDER_WRAP is not supported.
1519 @sa blur, bilateralFilter, GaussianBlur, medianBlur, integral
1520 */
1521 CV_EXPORTS_W void boxFilter( InputArray src, OutputArray dst, int ddepth,
1522 Size ksize, Point anchor = Point(-1,-1),
1523 bool normalize = true,
1524 int borderType = BORDER_DEFAULT );
1525
1526 /** @brief Calculates the normalized sum of squares of the pixel values overlapping the filter.
1527
1528 For every pixel \f$ (x, y) \f$ in the source image, the function calculates the sum of squares of those neighboring
1529 pixel values which overlap the filter placed over the pixel \f$ (x, y) \f$.
1530
1531 The unnormalized square box filter can be useful in computing local image statistics such as the the local
1532 variance and standard deviation around the neighborhood of a pixel.
1533
1534 @param src input image
1535 @param dst output image of the same size and type as src
1536 @param ddepth the output image depth (-1 to use src.depth())
1537 @param ksize kernel size
1538 @param anchor kernel anchor point. The default value of Point(-1, -1) denotes that the anchor is at the kernel
1539 center.
1540 @param normalize flag, specifying whether the kernel is to be normalized by it's area or not.
1541 @param borderType border mode used to extrapolate pixels outside of the image, see #BorderTypes. #BORDER_WRAP is not supported.
1542 @sa boxFilter
1543 */
1544 CV_EXPORTS_W void sqrBoxFilter( InputArray src, OutputArray dst, int ddepth,
1545 Size ksize, Point anchor = Point(-1, -1),
1546 bool normalize = true,
1547 int borderType = BORDER_DEFAULT );
1548
1549 /** @brief Blurs an image using the normalized box filter.
1550
1551 The function smooths an image using the kernel:
1552
1553 \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]
1554
1555 The call `blur(src, dst, ksize, anchor, borderType)` is equivalent to `boxFilter(src, dst, src.type(), ksize,
1556 anchor, true, borderType)`.
1557
1558 @param src input image; it can have any number of channels, which are processed independently, but
1559 the depth should be CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
1560 @param dst output image of the same size and type as src.
1561 @param ksize blurring kernel size.
1562 @param anchor anchor point; default value Point(-1,-1) means that the anchor is at the kernel
1563 center.
1564 @param borderType border mode used to extrapolate pixels outside of the image, see #BorderTypes. #BORDER_WRAP is not supported.
1565 @sa boxFilter, bilateralFilter, GaussianBlur, medianBlur
1566 */
1567 CV_EXPORTS_W void blur( InputArray src, OutputArray dst,
1568 Size ksize, Point anchor = Point(-1,-1),
1569 int borderType = BORDER_DEFAULT );
1570
1571 /** @brief Convolves an image with the kernel.
1572
1573 The function applies an arbitrary linear filter to an image. In-place operation is supported. When
1574 the aperture is partially outside the image, the function interpolates outlier pixel values
1575 according to the specified border mode.
1576
1577 The function does actually compute correlation, not the convolution:
1578
1579 \f[\texttt{dst} (x,y) = \sum _{ \substack{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]
1580
1581 That is, the kernel is not mirrored around the anchor point. If you need a real convolution, flip
1582 the kernel using #flip and set the new anchor to `(kernel.cols - anchor.x - 1, kernel.rows -
1583 anchor.y - 1)`.
1584
1585 The function uses the DFT-based algorithm in case of sufficiently large kernels (~`11 x 11` or
1586 larger) and the direct algorithm for small kernels.
1587
1588 @param src input image.
1589 @param dst output image of the same size and the same number of channels as src.
1590 @param ddepth desired depth of the destination image, see @ref filter_depths "combinations"
1591 @param kernel convolution kernel (or rather a correlation kernel), a single-channel floating point
1592 matrix; if you want to apply different kernels to different channels, split the image into
1593 separate color planes using split and process them individually.
1594 @param anchor anchor of the kernel that indicates the relative position of a filtered point within
1595 the kernel; the anchor should lie within the kernel; default value (-1,-1) means that the anchor
1596 is at the kernel center.
1597 @param delta optional value added to the filtered pixels before storing them in dst.
1598 @param borderType pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
1599 @sa sepFilter2D, dft, matchTemplate
1600 */
1601 CV_EXPORTS_W void filter2D( InputArray src, OutputArray dst, int ddepth,
1602 InputArray kernel, Point anchor = Point(-1,-1),
1603 double delta = 0, int borderType = BORDER_DEFAULT );
1604
1605 /** @brief Applies a separable linear filter to an image.
1606
1607 The function applies a separable linear filter to the image. That is, first, every row of src is
1608 filtered with the 1D kernel kernelX. Then, every column of the result is filtered with the 1D
1609 kernel kernelY. The final result shifted by delta is stored in dst .
1610
1611 @param src Source image.
1612 @param dst Destination image of the same size and the same number of channels as src .
1613 @param ddepth Destination image depth, see @ref filter_depths "combinations"
1614 @param kernelX Coefficients for filtering each row.
1615 @param kernelY Coefficients for filtering each column.
1616 @param anchor Anchor position within the kernel. The default value \f$(-1,-1)\f$ means that the anchor
1617 is at the kernel center.
1618 @param delta Value added to the filtered results before storing them.
1619 @param borderType Pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
1620 @sa filter2D, Sobel, GaussianBlur, boxFilter, blur
1621 */
1622 CV_EXPORTS_W void sepFilter2D( InputArray src, OutputArray dst, int ddepth,
1623 InputArray kernelX, InputArray kernelY,
1624 Point anchor = Point(-1,-1),
1625 double delta = 0, int borderType = BORDER_DEFAULT );
1626
1627 /** @example samples/cpp/tutorial_code/ImgTrans/Sobel_Demo.cpp
1628 Sample code using Sobel and/or Scharr OpenCV functions to make a simple Edge Detector
1629 ![Sample screenshot](Sobel_Derivatives_Tutorial_Result.jpg)
1630 Check @ref tutorial_sobel_derivatives "the corresponding tutorial" for more details
1631 */
1632
1633 /** @brief Calculates the first, second, third, or mixed image derivatives using an extended Sobel operator.
1634
1635 In all cases except one, the \f$\texttt{ksize} \times \texttt{ksize}\f$ separable kernel is used to
1636 calculate the derivative. When \f$\texttt{ksize = 1}\f$, the \f$3 \times 1\f$ or \f$1 \times 3\f$
1637 kernel is used (that is, no Gaussian smoothing is done). `ksize = 1` can only be used for the first
1638 or the second x- or y- derivatives.
1639
1640 There is also the special value `ksize = #FILTER_SCHARR (-1)` that corresponds to the \f$3\times3\f$ Scharr
1641 filter that may give more accurate results than the \f$3\times3\f$ Sobel. The Scharr aperture is
1642
1643 \f[\vecthreethree{-3}{0}{3}{-10}{0}{10}{-3}{0}{3}\f]
1644
1645 for the x-derivative, or transposed for the y-derivative.
1646
1647 The function calculates an image derivative by convolving the image with the appropriate kernel:
1648
1649 \f[\texttt{dst} = \frac{\partial^{xorder+yorder} \texttt{src}}{\partial x^{xorder} \partial y^{yorder}}\f]
1650
1651 The Sobel operators combine Gaussian smoothing and differentiation, so the result is more or less
1652 resistant to the noise. Most often, the function is called with ( xorder = 1, yorder = 0, ksize = 3)
1653 or ( xorder = 0, yorder = 1, ksize = 3) to calculate the first x- or y- image derivative. The first
1654 case corresponds to a kernel of:
1655
1656 \f[\vecthreethree{-1}{0}{1}{-2}{0}{2}{-1}{0}{1}\f]
1657
1658 The second case corresponds to a kernel of:
1659
1660 \f[\vecthreethree{-1}{-2}{-1}{0}{0}{0}{1}{2}{1}\f]
1661
1662 @param src input image.
1663 @param dst output image of the same size and the same number of channels as src .
1664 @param ddepth output image depth, see @ref filter_depths "combinations"; in the case of
1665 8-bit input images it will result in truncated derivatives.
1666 @param dx order of the derivative x.
1667 @param dy order of the derivative y.
1668 @param ksize size of the extended Sobel kernel; it must be 1, 3, 5, or 7.
1669 @param scale optional scale factor for the computed derivative values; by default, no scaling is
1670 applied (see #getDerivKernels for details).
1671 @param delta optional delta value that is added to the results prior to storing them in dst.
1672 @param borderType pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
1673 @sa Scharr, Laplacian, sepFilter2D, filter2D, GaussianBlur, cartToPolar
1674 */
1675 CV_EXPORTS_W void Sobel( InputArray src, OutputArray dst, int ddepth,
1676 int dx, int dy, int ksize = 3,
1677 double scale = 1, double delta = 0,
1678 int borderType = BORDER_DEFAULT );
1679
1680 /** @brief Calculates the first order image derivative in both x and y using a Sobel operator
1681
1682 Equivalent to calling:
1683
1684 @code
1685 Sobel( src, dx, CV_16SC1, 1, 0, 3 );
1686 Sobel( src, dy, CV_16SC1, 0, 1, 3 );
1687 @endcode
1688
1689 @param src input image.
1690 @param dx output image with first-order derivative in x.
1691 @param dy output image with first-order derivative in y.
1692 @param ksize size of Sobel kernel. It must be 3.
1693 @param borderType pixel extrapolation method, see #BorderTypes.
1694 Only #BORDER_DEFAULT=#BORDER_REFLECT_101 and #BORDER_REPLICATE are supported.
1695
1696 @sa Sobel
1697 */
1698
1699 CV_EXPORTS_W void spatialGradient( InputArray src, OutputArray dx,
1700 OutputArray dy, int ksize = 3,
1701 int borderType = BORDER_DEFAULT );
1702
1703 /** @brief Calculates the first x- or y- image derivative using Scharr operator.
1704
1705 The function computes the first x- or y- spatial image derivative using the Scharr operator. The
1706 call
1707
1708 \f[\texttt{Scharr(src, dst, ddepth, dx, dy, scale, delta, borderType)}\f]
1709
1710 is equivalent to
1711
1712 \f[\texttt{Sobel(src, dst, ddepth, dx, dy, FILTER_SCHARR, scale, delta, borderType)} .\f]
1713
1714 @param src input image.
1715 @param dst output image of the same size and the same number of channels as src.
1716 @param ddepth output image depth, see @ref filter_depths "combinations"
1717 @param dx order of the derivative x.
1718 @param dy order of the derivative y.
1719 @param scale optional scale factor for the computed derivative values; by default, no scaling is
1720 applied (see #getDerivKernels for details).
1721 @param delta optional delta value that is added to the results prior to storing them in dst.
1722 @param borderType pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
1723 @sa cartToPolar
1724 */
1725 CV_EXPORTS_W void Scharr( InputArray src, OutputArray dst, int ddepth,
1726 int dx, int dy, double scale = 1, double delta = 0,
1727 int borderType = BORDER_DEFAULT );
1728
1729 /** @example samples/cpp/laplace.cpp
1730 An example using Laplace transformations for edge detection
1731 */
1732
1733 /** @brief Calculates the Laplacian of an image.
1734
1735 The function calculates the Laplacian of the source image by adding up the second x and y
1736 derivatives calculated using the Sobel operator:
1737
1738 \f[\texttt{dst} = \Delta \texttt{src} = \frac{\partial^2 \texttt{src}}{\partial x^2} + \frac{\partial^2 \texttt{src}}{\partial y^2}\f]
1739
1740 This is done when `ksize > 1`. When `ksize == 1`, the Laplacian is computed by filtering the image
1741 with the following \f$3 \times 3\f$ aperture:
1742
1743 \f[\vecthreethree {0}{1}{0}{1}{-4}{1}{0}{1}{0}\f]
1744
1745 @param src Source image.
1746 @param dst Destination image of the same size and the same number of channels as src .
1747 @param ddepth Desired depth of the destination image.
1748 @param ksize Aperture size used to compute the second-derivative filters. See #getDerivKernels for
1749 details. The size must be positive and odd.
1750 @param scale Optional scale factor for the computed Laplacian values. By default, no scaling is
1751 applied. See #getDerivKernels for details.
1752 @param delta Optional delta value that is added to the results prior to storing them in dst .
1753 @param borderType Pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
1754 @sa Sobel, Scharr
1755 */
1756 CV_EXPORTS_W void Laplacian( InputArray src, OutputArray dst, int ddepth,
1757 int ksize = 1, double scale = 1, double delta = 0,
1758 int borderType = BORDER_DEFAULT );
1759
1760 //! @} imgproc_filter
1761
1762 //! @addtogroup imgproc_feature
1763 //! @{
1764
1765 /** @example samples/cpp/edge.cpp
1766 This program demonstrates usage of the Canny edge detector
1767
1768 Check @ref tutorial_canny_detector "the corresponding tutorial" for more details
1769 */
1770
1771 /** @brief Finds edges in an image using the Canny algorithm @cite Canny86 .
1772
1773 The function finds edges in the input image and marks them in the output map edges using the
1774 Canny algorithm. The smallest value between threshold1 and threshold2 is used for edge linking. The
1775 largest value is used to find initial segments of strong edges. See
1776 <http://en.wikipedia.org/wiki/Canny_edge_detector>
1777
1778 @param image 8-bit input image.
1779 @param edges output edge map; single channels 8-bit image, which has the same size as image .
1780 @param threshold1 first threshold for the hysteresis procedure.
1781 @param threshold2 second threshold for the hysteresis procedure.
1782 @param apertureSize aperture size for the Sobel operator.
1783 @param L2gradient a flag, indicating whether a more accurate \f$L_2\f$ norm
1784 \f$=\sqrt{(dI/dx)^2 + (dI/dy)^2}\f$ should be used to calculate the image gradient magnitude (
1785 L2gradient=true ), or whether the default \f$L_1\f$ norm \f$=|dI/dx|+|dI/dy|\f$ is enough (
1786 L2gradient=false ).
1787 */
1788 CV_EXPORTS_W void Canny( InputArray image, OutputArray edges,
1789 double threshold1, double threshold2,
1790 int apertureSize = 3, bool L2gradient = false );
1791
1792 /** \overload
1793
1794 Finds edges in an image using the Canny algorithm with custom image gradient.
1795
1796 @param dx 16-bit x derivative of input image (CV_16SC1 or CV_16SC3).
1797 @param dy 16-bit y derivative of input image (same type as dx).
1798 @param edges output edge map; single channels 8-bit image, which has the same size as image .
1799 @param threshold1 first threshold for the hysteresis procedure.
1800 @param threshold2 second threshold for the hysteresis procedure.
1801 @param L2gradient a flag, indicating whether a more accurate \f$L_2\f$ norm
1802 \f$=\sqrt{(dI/dx)^2 + (dI/dy)^2}\f$ should be used to calculate the image gradient magnitude (
1803 L2gradient=true ), or whether the default \f$L_1\f$ norm \f$=|dI/dx|+|dI/dy|\f$ is enough (
1804 L2gradient=false ).
1805 */
1806 CV_EXPORTS_W void Canny( InputArray dx, InputArray dy,
1807 OutputArray edges,
1808 double threshold1, double threshold2,
1809 bool L2gradient = false );
1810
1811 /** @brief Calculates the minimal eigenvalue of gradient matrices for corner detection.
1812
1813 The function is similar to cornerEigenValsAndVecs but it calculates and stores only the minimal
1814 eigenvalue of the covariance matrix of derivatives, that is, \f$\min(\lambda_1, \lambda_2)\f$ in terms
1815 of the formulae in the cornerEigenValsAndVecs description.
1816
1817 @param src Input single-channel 8-bit or floating-point image.
1818 @param dst Image to store the minimal eigenvalues. It has the type CV_32FC1 and the same size as
1819 src .
1820 @param blockSize Neighborhood size (see the details on #cornerEigenValsAndVecs ).
1821 @param ksize Aperture parameter for the Sobel operator.
1822 @param borderType Pixel extrapolation method. See #BorderTypes. #BORDER_WRAP is not supported.
1823 */
1824 CV_EXPORTS_W void cornerMinEigenVal( InputArray src, OutputArray dst,
1825 int blockSize, int ksize = 3,
1826 int borderType = BORDER_DEFAULT );
1827
1828 /** @brief Harris corner detector.
1829
1830 The function runs the Harris corner detector on the image. Similarly to cornerMinEigenVal and
1831 cornerEigenValsAndVecs , for each pixel \f$(x, y)\f$ it calculates a \f$2\times2\f$ gradient covariance
1832 matrix \f$M^{(x,y)}\f$ over a \f$\texttt{blockSize} \times \texttt{blockSize}\f$ neighborhood. Then, it
1833 computes the following characteristic:
1834
1835 \f[\texttt{dst} (x,y) = \mathrm{det} M^{(x,y)} - k \cdot \left ( \mathrm{tr} M^{(x,y)} \right )^2\f]
1836
1837 Corners in the image can be found as the local maxima of this response map.
1838
1839 @param src Input single-channel 8-bit or floating-point image.
1840 @param dst Image to store the Harris detector responses. It has the type CV_32FC1 and the same
1841 size as src .
1842 @param blockSize Neighborhood size (see the details on #cornerEigenValsAndVecs ).
1843 @param ksize Aperture parameter for the Sobel operator.
1844 @param k Harris detector free parameter. See the formula above.
1845 @param borderType Pixel extrapolation method. See #BorderTypes. #BORDER_WRAP is not supported.
1846 */
1847 CV_EXPORTS_W void cornerHarris( InputArray src, OutputArray dst, int blockSize,
1848 int ksize, double k,
1849 int borderType = BORDER_DEFAULT );
1850
1851 /** @brief Calculates eigenvalues and eigenvectors of image blocks for corner detection.
1852
1853 For every pixel \f$p\f$ , the function cornerEigenValsAndVecs considers a blockSize \f$\times\f$ blockSize
1854 neighborhood \f$S(p)\f$ . It calculates the covariation matrix of derivatives over the neighborhood as:
1855
1856 \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]
1857
1858 where the derivatives are computed using the Sobel operator.
1859
1860 After that, it finds eigenvectors and eigenvalues of \f$M\f$ and stores them in the destination image as
1861 \f$(\lambda_1, \lambda_2, x_1, y_1, x_2, y_2)\f$ where
1862
1863 - \f$\lambda_1, \lambda_2\f$ are the non-sorted eigenvalues of \f$M\f$
1864 - \f$x_1, y_1\f$ are the eigenvectors corresponding to \f$\lambda_1\f$
1865 - \f$x_2, y_2\f$ are the eigenvectors corresponding to \f$\lambda_2\f$
1866
1867 The output of the function can be used for robust edge or corner detection.
1868
1869 @param src Input single-channel 8-bit or floating-point image.
1870 @param dst Image to store the results. It has the same size as src and the type CV_32FC(6) .
1871 @param blockSize Neighborhood size (see details below).
1872 @param ksize Aperture parameter for the Sobel operator.
1873 @param borderType Pixel extrapolation method. See #BorderTypes. #BORDER_WRAP is not supported.
1874
1875 @sa cornerMinEigenVal, cornerHarris, preCornerDetect
1876 */
1877 CV_EXPORTS_W void cornerEigenValsAndVecs( InputArray src, OutputArray dst,
1878 int blockSize, int ksize,
1879 int borderType = BORDER_DEFAULT );
1880
1881 /** @brief Calculates a feature map for corner detection.
1882
1883 The function calculates the complex spatial derivative-based function of the source image
1884
1885 \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]
1886
1887 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
1888 derivatives, and \f$D_{xy}\f$ is the mixed derivative.
1889
1890 The corners can be found as local maximums of the functions, as shown below:
1891 @code
1892 Mat corners, dilated_corners;
1893 preCornerDetect(image, corners, 3);
1894 // dilation with 3x3 rectangular structuring element
1895 dilate(corners, dilated_corners, Mat(), 1);
1896 Mat corner_mask = corners == dilated_corners;
1897 @endcode
1898
1899 @param src Source single-channel 8-bit of floating-point image.
1900 @param dst Output image that has the type CV_32F and the same size as src .
1901 @param ksize %Aperture size of the Sobel .
1902 @param borderType Pixel extrapolation method. See #BorderTypes. #BORDER_WRAP is not supported.
1903 */
1904 CV_EXPORTS_W void preCornerDetect( InputArray src, OutputArray dst, int ksize,
1905 int borderType = BORDER_DEFAULT );
1906
1907 /** @brief Refines the corner locations.
1908
1909 The function iterates to find the sub-pixel accurate location of corners or radial saddle
1910 points as described in @cite forstner1987fast, and as shown on the figure below.
1911
1912 ![image](pics/cornersubpix.png)
1913
1914 Sub-pixel accurate corner locator is based on the observation that every vector from the center \f$q\f$
1915 to a point \f$p\f$ located within a neighborhood of \f$q\f$ is orthogonal to the image gradient at \f$p\f$
1916 subject to image and measurement noise. Consider the expression:
1917
1918 \f[\epsilon _i = {DI_{p_i}}^T \cdot (q - p_i)\f]
1919
1920 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
1921 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
1922 with \f$\epsilon_i\f$ set to zero:
1923
1924 \f[\sum _i(DI_{p_i} \cdot {DI_{p_i}}^T) \cdot q - \sum _i(DI_{p_i} \cdot {DI_{p_i}}^T \cdot p_i)\f]
1925
1926 where the gradients are summed within a neighborhood ("search window") of \f$q\f$ . Calling the first
1927 gradient term \f$G\f$ and the second gradient term \f$b\f$ gives:
1928
1929 \f[q = G^{-1} \cdot b\f]
1930
1931 The algorithm sets the center of the neighborhood window at this new center \f$q\f$ and then iterates
1932 until the center stays within a set threshold.
1933
1934 @param image Input single-channel, 8-bit or float image.
1935 @param corners Initial coordinates of the input corners and refined coordinates provided for
1936 output.
1937 @param winSize Half of the side length of the search window. For example, if winSize=Size(5,5) ,
1938 then a \f$(5*2+1) \times (5*2+1) = 11 \times 11\f$ search window is used.
1939 @param zeroZone Half of the size of the dead region in the middle of the search zone over which
1940 the summation in the formula below is not done. It is used sometimes to avoid possible
1941 singularities of the autocorrelation matrix. The value of (-1,-1) indicates that there is no such
1942 a size.
1943 @param criteria Criteria for termination of the iterative process of corner refinement. That is,
1944 the process of corner position refinement stops either after criteria.maxCount iterations or when
1945 the corner position moves by less than criteria.epsilon on some iteration.
1946 */
1947 CV_EXPORTS_W void cornerSubPix( InputArray image, InputOutputArray corners,
1948 Size winSize, Size zeroZone,
1949 TermCriteria criteria );
1950
1951 /** @brief Determines strong corners on an image.
1952
1953 The function finds the most prominent corners in the image or in the specified image region, as
1954 described in @cite Shi94
1955
1956 - Function calculates the corner quality measure at every source image pixel using the
1957 #cornerMinEigenVal or #cornerHarris .
1958 - Function performs a non-maximum suppression (the local maximums in *3 x 3* neighborhood are
1959 retained).
1960 - The corners with the minimal eigenvalue less than
1961 \f$\texttt{qualityLevel} \cdot \max_{x,y} qualityMeasureMap(x,y)\f$ are rejected.
1962 - The remaining corners are sorted by the quality measure in the descending order.
1963 - Function throws away each corner for which there is a stronger corner at a distance less than
1964 maxDistance.
1965
1966 The function can be used to initialize a point-based tracker of an object.
1967
1968 @note If the function is called with different values A and B of the parameter qualityLevel , and
1969 A \> B, the vector of returned corners with qualityLevel=A will be the prefix of the output vector
1970 with qualityLevel=B .
1971
1972 @param image Input 8-bit or floating-point 32-bit, single-channel image.
1973 @param corners Output vector of detected corners.
1974 @param maxCorners Maximum number of corners to return. If there are more corners than are found,
1975 the strongest of them is returned. `maxCorners <= 0` implies that no limit on the maximum is set
1976 and all detected corners are returned.
1977 @param qualityLevel Parameter characterizing the minimal accepted quality of image corners. The
1978 parameter value is multiplied by the best corner quality measure, which is the minimal eigenvalue
1979 (see #cornerMinEigenVal ) or the Harris function response (see #cornerHarris ). The corners with the
1980 quality measure less than the product are rejected. For example, if the best corner has the
1981 quality measure = 1500, and the qualityLevel=0.01 , then all the corners with the quality measure
1982 less than 15 are rejected.
1983 @param minDistance Minimum possible Euclidean distance between the returned corners.
1984 @param mask Optional region of interest. If the image is not empty (it needs to have the type
1985 CV_8UC1 and the same size as image ), it specifies the region in which the corners are detected.
1986 @param blockSize Size of an average block for computing a derivative covariation matrix over each
1987 pixel neighborhood. See cornerEigenValsAndVecs .
1988 @param useHarrisDetector Parameter indicating whether to use a Harris detector (see #cornerHarris)
1989 or #cornerMinEigenVal.
1990 @param k Free parameter of the Harris detector.
1991
1992 @sa cornerMinEigenVal, cornerHarris, calcOpticalFlowPyrLK, estimateRigidTransform,
1993 */
1994
1995 CV_EXPORTS_W void goodFeaturesToTrack( InputArray image, OutputArray corners,
1996 int maxCorners, double qualityLevel, double minDistance,
1997 InputArray mask = noArray(), int blockSize = 3,
1998 bool useHarrisDetector = false, double k = 0.04 );
1999
2000 CV_EXPORTS_W void goodFeaturesToTrack( InputArray image, OutputArray corners,
2001 int maxCorners, double qualityLevel, double minDistance,
2002 InputArray mask, int blockSize,
2003 int gradientSize, bool useHarrisDetector = false,
2004 double k = 0.04 );
2005
2006 /** @brief Same as above, but returns also quality measure of the detected corners.
2007
2008 @param image Input 8-bit or floating-point 32-bit, single-channel image.
2009 @param corners Output vector of detected corners.
2010 @param maxCorners Maximum number of corners to return. If there are more corners than are found,
2011 the strongest of them is returned. `maxCorners <= 0` implies that no limit on the maximum is set
2012 and all detected corners are returned.
2013 @param qualityLevel Parameter characterizing the minimal accepted quality of image corners. The
2014 parameter value is multiplied by the best corner quality measure, which is the minimal eigenvalue
2015 (see #cornerMinEigenVal ) or the Harris function response (see #cornerHarris ). The corners with the
2016 quality measure less than the product are rejected. For example, if the best corner has the
2017 quality measure = 1500, and the qualityLevel=0.01 , then all the corners with the quality measure
2018 less than 15 are rejected.
2019 @param minDistance Minimum possible Euclidean distance between the returned corners.
2020 @param mask Region of interest. If the image is not empty (it needs to have the type
2021 CV_8UC1 and the same size as image ), it specifies the region in which the corners are detected.
2022 @param cornersQuality Output vector of quality measure of the detected corners.
2023 @param blockSize Size of an average block for computing a derivative covariation matrix over each
2024 pixel neighborhood. See cornerEigenValsAndVecs .
2025 @param gradientSize Aperture parameter for the Sobel operator used for derivatives computation.
2026 See cornerEigenValsAndVecs .
2027 @param useHarrisDetector Parameter indicating whether to use a Harris detector (see #cornerHarris)
2028 or #cornerMinEigenVal.
2029 @param k Free parameter of the Harris detector.
2030 */
2031 CV_EXPORTS CV_WRAP_AS(goodFeaturesToTrackWithQuality) void goodFeaturesToTrack(
2032 InputArray image, OutputArray corners,
2033 int maxCorners, double qualityLevel, double minDistance,
2034 InputArray mask, OutputArray cornersQuality, int blockSize = 3,
2035 int gradientSize = 3, bool useHarrisDetector = false, double k = 0.04);
2036
2037 /** @example samples/cpp/tutorial_code/ImgTrans/houghlines.cpp
2038 An example using the Hough line detector
2039 ![Sample input image](Hough_Lines_Tutorial_Original_Image.jpg) ![Output image](Hough_Lines_Tutorial_Result.jpg)
2040 */
2041
2042 /** @brief Finds lines in a binary image using the standard Hough transform.
2043
2044 The function implements the standard or standard multi-scale Hough transform algorithm for line
2045 detection. See <http://homepages.inf.ed.ac.uk/rbf/HIPR2/hough.htm> for a good explanation of Hough
2046 transform.
2047
2048 @param image 8-bit, single-channel binary source image. The image may be modified by the function.
2049 @param lines Output vector of lines. Each line is represented by a 2 or 3 element vector
2050 \f$(\rho, \theta)\f$ or \f$(\rho, \theta, \textrm{votes})\f$ . \f$\rho\f$ is the distance from the coordinate origin \f$(0,0)\f$ (top-left corner of
2051 the image). \f$\theta\f$ is the line rotation angle in radians (
2052 \f$0 \sim \textrm{vertical line}, \pi/2 \sim \textrm{horizontal line}\f$ ).
2053 \f$\textrm{votes}\f$ is the value of accumulator.
2054 @param rho Distance resolution of the accumulator in pixels.
2055 @param theta Angle resolution of the accumulator in radians.
2056 @param threshold Accumulator threshold parameter. Only those lines are returned that get enough
2057 votes ( \f$>\texttt{threshold}\f$ ).
2058 @param srn For the multi-scale Hough transform, it is a divisor for the distance resolution rho .
2059 The coarse accumulator distance resolution is rho and the accurate accumulator resolution is
2060 rho/srn . If both srn=0 and stn=0 , the classical Hough transform is used. Otherwise, both these
2061 parameters should be positive.
2062 @param stn For the multi-scale Hough transform, it is a divisor for the distance resolution theta.
2063 @param min_theta For standard and multi-scale Hough transform, minimum angle to check for lines.
2064 Must fall between 0 and max_theta.
2065 @param max_theta For standard and multi-scale Hough transform, maximum angle to check for lines.
2066 Must fall between min_theta and CV_PI.
2067 */
2068 CV_EXPORTS_W void HoughLines( InputArray image, OutputArray lines,
2069 double rho, double theta, int threshold,
2070 double srn = 0, double stn = 0,
2071 double min_theta = 0, double max_theta = CV_PI );
2072
2073 /** @brief Finds line segments in a binary image using the probabilistic Hough transform.
2074
2075 The function implements the probabilistic Hough transform algorithm for line detection, described
2076 in @cite Matas00
2077
2078 See the line detection example below:
2079 @include snippets/imgproc_HoughLinesP.cpp
2080 This is a sample picture the function parameters have been tuned for:
2081
2082 ![image](pics/building.jpg)
2083
2084 And this is the output of the above program in case of the probabilistic Hough transform:
2085
2086 ![image](pics/houghp.png)
2087
2088 @param image 8-bit, single-channel binary source image. The image may be modified by the function.
2089 @param lines Output vector of lines. Each line is represented by a 4-element vector
2090 \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
2091 line segment.
2092 @param rho Distance resolution of the accumulator in pixels.
2093 @param theta Angle resolution of the accumulator in radians.
2094 @param threshold Accumulator threshold parameter. Only those lines are returned that get enough
2095 votes ( \f$>\texttt{threshold}\f$ ).
2096 @param minLineLength Minimum line length. Line segments shorter than that are rejected.
2097 @param maxLineGap Maximum allowed gap between points on the same line to link them.
2098
2099 @sa LineSegmentDetector
2100 */
2101 CV_EXPORTS_W void HoughLinesP( InputArray image, OutputArray lines,
2102 double rho, double theta, int threshold,
2103 double minLineLength = 0, double maxLineGap = 0 );
2104
2105 /** @brief Finds lines in a set of points using the standard Hough transform.
2106
2107 The function finds lines in a set of points using a modification of the Hough transform.
2108 @include snippets/imgproc_HoughLinesPointSet.cpp
2109 @param point Input vector of points. Each vector must be encoded as a Point vector \f$(x,y)\f$. Type must be CV_32FC2 or CV_32SC2.
2110 @param lines Output vector of found lines. Each vector is encoded as a vector<Vec3d> \f$(votes, rho, theta)\f$.
2111 The larger the value of 'votes', the higher the reliability of the Hough line.
2112 @param lines_max Max count of hough lines.
2113 @param threshold Accumulator threshold parameter. Only those lines are returned that get enough
2114 votes ( \f$>\texttt{threshold}\f$ )
2115 @param min_rho Minimum Distance value of the accumulator in pixels.
2116 @param max_rho Maximum Distance value of the accumulator in pixels.
2117 @param rho_step Distance resolution of the accumulator in pixels.
2118 @param min_theta Minimum angle value of the accumulator in radians.
2119 @param max_theta Maximum angle value of the accumulator in radians.
2120 @param theta_step Angle resolution of the accumulator in radians.
2121 */
2122 CV_EXPORTS_W void HoughLinesPointSet( InputArray point, OutputArray lines, int lines_max, int threshold,
2123 double min_rho, double max_rho, double rho_step,
2124 double min_theta, double max_theta, double theta_step );
2125
2126 /** @example samples/cpp/tutorial_code/ImgTrans/houghcircles.cpp
2127 An example using the Hough circle detector
2128 */
2129
2130 /** @brief Finds circles in a grayscale image using the Hough transform.
2131
2132 The function finds circles in a grayscale image using a modification of the Hough transform.
2133
2134 Example: :
2135 @include snippets/imgproc_HoughLinesCircles.cpp
2136
2137 @note Usually the function detects the centers of circles well. However, it may fail to find correct
2138 radii. You can assist to the function by specifying the radius range ( minRadius and maxRadius ) if
2139 you know it. Or, in the case of #HOUGH_GRADIENT method you may set maxRadius to a negative number
2140 to return centers only without radius search, and find the correct radius using an additional procedure.
2141
2142 It also helps to smooth image a bit unless it's already soft. For example,
2143 GaussianBlur() with 7x7 kernel and 1.5x1.5 sigma or similar blurring may help.
2144
2145 @param image 8-bit, single-channel, grayscale input image.
2146 @param circles Output vector of found circles. Each vector is encoded as 3 or 4 element
2147 floating-point vector \f$(x, y, radius)\f$ or \f$(x, y, radius, votes)\f$ .
2148 @param method Detection method, see #HoughModes. The available methods are #HOUGH_GRADIENT and #HOUGH_GRADIENT_ALT.
2149 @param dp Inverse ratio of the accumulator resolution to the image resolution. For example, if
2150 dp=1 , the accumulator has the same resolution as the input image. If dp=2 , the accumulator has
2151 half as big width and height. For #HOUGH_GRADIENT_ALT the recommended value is dp=1.5,
2152 unless some small very circles need to be detected.
2153 @param minDist Minimum distance between the centers of the detected circles. If the parameter is
2154 too small, multiple neighbor circles may be falsely detected in addition to a true one. If it is
2155 too large, some circles may be missed.
2156 @param param1 First method-specific parameter. In case of #HOUGH_GRADIENT and #HOUGH_GRADIENT_ALT,
2157 it is the higher threshold of the two passed to the Canny edge detector (the lower one is twice smaller).
2158 Note that #HOUGH_GRADIENT_ALT uses #Scharr algorithm to compute image derivatives, so the threshold value
2159 shough normally be higher, such as 300 or normally exposed and contrasty images.
2160 @param param2 Second method-specific parameter. In case of #HOUGH_GRADIENT, it is the
2161 accumulator threshold for the circle centers at the detection stage. The smaller it is, the more
2162 false circles may be detected. Circles, corresponding to the larger accumulator values, will be
2163 returned first. In the case of #HOUGH_GRADIENT_ALT algorithm, this is the circle "perfectness" measure.
2164 The closer it to 1, the better shaped circles algorithm selects. In most cases 0.9 should be fine.
2165 If you want get better detection of small circles, you may decrease it to 0.85, 0.8 or even less.
2166 But then also try to limit the search range [minRadius, maxRadius] to avoid many false circles.
2167 @param minRadius Minimum circle radius.
2168 @param maxRadius Maximum circle radius. If <= 0, uses the maximum image dimension. If < 0, #HOUGH_GRADIENT returns
2169 centers without finding the radius. #HOUGH_GRADIENT_ALT always computes circle radiuses.
2170
2171 @sa fitEllipse, minEnclosingCircle
2172 */
2173 CV_EXPORTS_W void HoughCircles( InputArray image, OutputArray circles,
2174 int method, double dp, double minDist,
2175 double param1 = 100, double param2 = 100,
2176 int minRadius = 0, int maxRadius = 0 );
2177
2178 //! @} imgproc_feature
2179
2180 //! @addtogroup imgproc_filter
2181 //! @{
2182
2183 /** @example samples/cpp/tutorial_code/ImgProc/Morphology_2.cpp
2184 Advanced morphology Transformations sample code
2185 ![Sample screenshot](Morphology_2_Tutorial_Result.jpg)
2186 Check @ref tutorial_opening_closing_hats "the corresponding tutorial" for more details
2187 */
2188
2189 /** @brief Erodes an image by using a specific structuring element.
2190
2191 The function erodes the source image using the specified structuring element that determines the
2192 shape of a pixel neighborhood over which the minimum is taken:
2193
2194 \f[\texttt{dst} (x,y) = \min _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')\f]
2195
2196 The function supports the in-place mode. Erosion can be applied several ( iterations ) times. In
2197 case of multi-channel images, each channel is processed independently.
2198
2199 @param src input image; the number of channels can be arbitrary, but the depth should be one of
2200 CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
2201 @param dst output image of the same size and type as src.
2202 @param kernel structuring element used for erosion; if `element=Mat()`, a `3 x 3` rectangular
2203 structuring element is used. Kernel can be created using #getStructuringElement.
2204 @param anchor position of the anchor within the element; default value (-1, -1) means that the
2205 anchor is at the element center.
2206 @param iterations number of times erosion is applied.
2207 @param borderType pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
2208 @param borderValue border value in case of a constant border
2209 @sa dilate, morphologyEx, getStructuringElement
2210 */
2211 CV_EXPORTS_W void erode( InputArray src, OutputArray dst, InputArray kernel,
2212 Point anchor = Point(-1,-1), int iterations = 1,
2213 int borderType = BORDER_CONSTANT,
2214 const Scalar& borderValue = morphologyDefaultBorderValue() );
2215
2216 /** @example samples/cpp/tutorial_code/ImgProc/Morphology_1.cpp
2217 Erosion and Dilation sample code
2218 ![Sample Screenshot-Erosion](Morphology_1_Tutorial_Erosion_Result.jpg)![Sample Screenshot-Dilation](Morphology_1_Tutorial_Dilation_Result.jpg)
2219 Check @ref tutorial_erosion_dilatation "the corresponding tutorial" for more details
2220 */
2221
2222 /** @brief Dilates an image by using a specific structuring element.
2223
2224 The function dilates the source image using the specified structuring element that determines the
2225 shape of a pixel neighborhood over which the maximum is taken:
2226 \f[\texttt{dst} (x,y) = \max _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')\f]
2227
2228 The function supports the in-place mode. Dilation can be applied several ( iterations ) times. In
2229 case of multi-channel images, each channel is processed independently.
2230
2231 @param src input image; the number of channels can be arbitrary, but the depth should be one of
2232 CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
2233 @param dst output image of the same size and type as src.
2234 @param kernel structuring element used for dilation; if elemenat=Mat(), a 3 x 3 rectangular
2235 structuring element is used. Kernel can be created using #getStructuringElement
2236 @param anchor position of the anchor within the element; default value (-1, -1) means that the
2237 anchor is at the element center.
2238 @param iterations number of times dilation is applied.
2239 @param borderType pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not suported.
2240 @param borderValue border value in case of a constant border
2241 @sa erode, morphologyEx, getStructuringElement
2242 */
2243 CV_EXPORTS_W void dilate( InputArray src, OutputArray dst, InputArray kernel,
2244 Point anchor = Point(-1,-1), int iterations = 1,
2245 int borderType = BORDER_CONSTANT,
2246 const Scalar& borderValue = morphologyDefaultBorderValue() );
2247
2248 /** @brief Performs advanced morphological transformations.
2249
2250 The function cv::morphologyEx can perform advanced morphological transformations using an erosion and dilation as
2251 basic operations.
2252
2253 Any of the operations can be done in-place. In case of multi-channel images, each channel is
2254 processed independently.
2255
2256 @param src Source image. The number of channels can be arbitrary. The depth should be one of
2257 CV_8U, CV_16U, CV_16S, CV_32F or CV_64F.
2258 @param dst Destination image of the same size and type as source image.
2259 @param op Type of a morphological operation, see #MorphTypes
2260 @param kernel Structuring element. It can be created using #getStructuringElement.
2261 @param anchor Anchor position with the kernel. Negative values mean that the anchor is at the
2262 kernel center.
2263 @param iterations Number of times erosion and dilation are applied.
2264 @param borderType Pixel extrapolation method, see #BorderTypes. #BORDER_WRAP is not supported.
2265 @param borderValue Border value in case of a constant border. The default value has a special
2266 meaning.
2267 @sa dilate, erode, getStructuringElement
2268 @note The number of iterations is the number of times erosion or dilatation operation will be applied.
2269 For instance, an opening operation (#MORPH_OPEN) with two iterations is equivalent to apply
2270 successively: erode -> erode -> dilate -> dilate (and not erode -> dilate -> erode -> dilate).
2271 */
2272 CV_EXPORTS_W void morphologyEx( InputArray src, OutputArray dst,
2273 int op, InputArray kernel,
2274 Point anchor = Point(-1,-1), int iterations = 1,
2275 int borderType = BORDER_CONSTANT,
2276 const Scalar& borderValue = morphologyDefaultBorderValue() );
2277
2278 //! @} imgproc_filter
2279
2280 //! @addtogroup imgproc_transform
2281 //! @{
2282
2283 /** @brief Resizes an image.
2284
2285 The function resize resizes the image src down to or up to the specified size. Note that the
2286 initial dst type or size are not taken into account. Instead, the size and type are derived from
2287 the `src`,`dsize`,`fx`, and `fy`. If you want to resize src so that it fits the pre-created dst,
2288 you may call the function as follows:
2289 @code
2290 // explicitly specify dsize=dst.size(); fx and fy will be computed from that.
2291 resize(src, dst, dst.size(), 0, 0, interpolation);
2292 @endcode
2293 If you want to decimate the image by factor of 2 in each direction, you can call the function this
2294 way:
2295 @code
2296 // specify fx and fy and let the function compute the destination image size.
2297 resize(src, dst, Size(), 0.5, 0.5, interpolation);
2298 @endcode
2299 To shrink an image, it will generally look best with #INTER_AREA interpolation, whereas to
2300 enlarge an image, it will generally look best with c#INTER_CUBIC (slow) or #INTER_LINEAR
2301 (faster but still looks OK).
2302
2303 @param src input image.
2304 @param dst output image; it has the size dsize (when it is non-zero) or the size computed from
2305 src.size(), fx, and fy; the type of dst is the same as of src.
2306 @param dsize output image size; if it equals zero, it is computed as:
2307 \f[\texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}\f]
2308 Either dsize or both fx and fy must be non-zero.
2309 @param fx scale factor along the horizontal axis; when it equals 0, it is computed as
2310 \f[\texttt{(double)dsize.width/src.cols}\f]
2311 @param fy scale factor along the vertical axis; when it equals 0, it is computed as
2312 \f[\texttt{(double)dsize.height/src.rows}\f]
2313 @param interpolation interpolation method, see #InterpolationFlags
2314
2315 @sa warpAffine, warpPerspective, remap
2316 */
2317 CV_EXPORTS_W void resize( InputArray src, OutputArray dst,
2318 Size dsize, double fx = 0, double fy = 0,
2319 int interpolation = INTER_LINEAR );
2320
2321 /** @brief Applies an affine transformation to an image.
2322
2323 The function warpAffine transforms the source image using the specified matrix:
2324
2325 \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]
2326
2327 when the flag #WARP_INVERSE_MAP is set. Otherwise, the transformation is first inverted
2328 with #invertAffineTransform and then put in the formula above instead of M. The function cannot
2329 operate in-place.
2330
2331 @param src input image.
2332 @param dst output image that has the size dsize and the same type as src .
2333 @param M \f$2\times 3\f$ transformation matrix.
2334 @param dsize size of the output image.
2335 @param flags combination of interpolation methods (see #InterpolationFlags) and the optional
2336 flag #WARP_INVERSE_MAP that means that M is the inverse transformation (
2337 \f$\texttt{dst}\rightarrow\texttt{src}\f$ ).
2338 @param borderMode pixel extrapolation method (see #BorderTypes); when
2339 borderMode=#BORDER_TRANSPARENT, it means that the pixels in the destination image corresponding to
2340 the "outliers" in the source image are not modified by the function.
2341 @param borderValue value used in case of a constant border; by default, it is 0.
2342
2343 @sa warpPerspective, resize, remap, getRectSubPix, transform
2344 */
2345 CV_EXPORTS_W void warpAffine( InputArray src, OutputArray dst,
2346 InputArray M, Size dsize,
2347 int flags = INTER_LINEAR,
2348 int borderMode = BORDER_CONSTANT,
2349 const Scalar& borderValue = Scalar());
2350
2351 /** @example samples/cpp/warpPerspective_demo.cpp
2352 An example program shows using cv::getPerspectiveTransform and cv::warpPerspective for image warping
2353 */
2354
2355 /** @brief Applies a perspective transformation to an image.
2356
2357 The function warpPerspective transforms the source image using the specified matrix:
2358
2359 \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}} ,
2360 \frac{M_{21} x + M_{22} y + M_{23}}{M_{31} x + M_{32} y + M_{33}} \right )\f]
2361
2362 when the flag #WARP_INVERSE_MAP is set. Otherwise, the transformation is first inverted with invert
2363 and then put in the formula above instead of M. The function cannot operate in-place.
2364
2365 @param src input image.
2366 @param dst output image that has the size dsize and the same type as src .
2367 @param M \f$3\times 3\f$ transformation matrix.
2368 @param dsize size of the output image.
2369 @param flags combination of interpolation methods (#INTER_LINEAR or #INTER_NEAREST) and the
2370 optional flag #WARP_INVERSE_MAP, that sets M as the inverse transformation (
2371 \f$\texttt{dst}\rightarrow\texttt{src}\f$ ).
2372 @param borderMode pixel extrapolation method (#BORDER_CONSTANT or #BORDER_REPLICATE).
2373 @param borderValue value used in case of a constant border; by default, it equals 0.
2374
2375 @sa warpAffine, resize, remap, getRectSubPix, perspectiveTransform
2376 */
2377 CV_EXPORTS_W void warpPerspective( InputArray src, OutputArray dst,
2378 InputArray M, Size dsize,
2379 int flags = INTER_LINEAR,
2380 int borderMode = BORDER_CONSTANT,
2381 const Scalar& borderValue = Scalar());
2382
2383 /** @brief Applies a generic geometrical transformation to an image.
2384
2385 The function remap transforms the source image using the specified map:
2386
2387 \f[\texttt{dst} (x,y) = \texttt{src} (map_x(x,y),map_y(x,y))\f]
2388
2389 where values of pixels with non-integer coordinates are computed using one of available
2390 interpolation methods. \f$map_x\f$ and \f$map_y\f$ can be encoded as separate floating-point maps
2391 in \f$map_1\f$ and \f$map_2\f$ respectively, or interleaved floating-point maps of \f$(x,y)\f$ in
2392 \f$map_1\f$, or fixed-point maps created by using convertMaps. The reason you might want to
2393 convert from floating to fixed-point representations of a map is that they can yield much faster
2394 (\~2x) remapping operations. In the converted case, \f$map_1\f$ contains pairs (cvFloor(x),
2395 cvFloor(y)) and \f$map_2\f$ contains indices in a table of interpolation coefficients.
2396
2397 This function cannot operate in-place.
2398
2399 @param src Source image.
2400 @param dst Destination image. It has the same size as map1 and the same type as src .
2401 @param map1 The first map of either (x,y) points or just x values having the type CV_16SC2 ,
2402 CV_32FC1, or CV_32FC2. See convertMaps for details on converting a floating point
2403 representation to fixed-point for speed.
2404 @param map2 The second map of y values having the type CV_16UC1, CV_32FC1, or none (empty map
2405 if map1 is (x,y) points), respectively.
2406 @param interpolation Interpolation method (see #InterpolationFlags). The methods #INTER_AREA
2407 and #INTER_LINEAR_EXACT are not supported by this function.
2408 @param borderMode Pixel extrapolation method (see #BorderTypes). When
2409 borderMode=#BORDER_TRANSPARENT, it means that the pixels in the destination image that
2410 corresponds to the "outliers" in the source image are not modified by the function.
2411 @param borderValue Value used in case of a constant border. By default, it is 0.
2412 @note
2413 Due to current implementation limitations the size of an input and output images should be less than 32767x32767.
2414 */
2415 CV_EXPORTS_W void remap( InputArray src, OutputArray dst,
2416 InputArray map1, InputArray map2,
2417 int interpolation, int borderMode = BORDER_CONSTANT,
2418 const Scalar& borderValue = Scalar());
2419
2420 /** @brief Converts image transformation maps from one representation to another.
2421
2422 The function converts a pair of maps for remap from one representation to another. The following
2423 options ( (map1.type(), map2.type()) \f$\rightarrow\f$ (dstmap1.type(), dstmap2.type()) ) are
2424 supported:
2425
2426 - \f$\texttt{(CV_32FC1, CV_32FC1)} \rightarrow \texttt{(CV_16SC2, CV_16UC1)}\f$. This is the
2427 most frequently used conversion operation, in which the original floating-point maps (see remap )
2428 are converted to a more compact and much faster fixed-point representation. The first output array
2429 contains the rounded coordinates and the second array (created only when nninterpolation=false )
2430 contains indices in the interpolation tables.
2431
2432 - \f$\texttt{(CV_32FC2)} \rightarrow \texttt{(CV_16SC2, CV_16UC1)}\f$. The same as above but
2433 the original maps are stored in one 2-channel matrix.
2434
2435 - Reverse conversion. Obviously, the reconstructed floating-point maps will not be exactly the same
2436 as the originals.
2437
2438 @param map1 The first input map of type CV_16SC2, CV_32FC1, or CV_32FC2 .
2439 @param map2 The second input map of type CV_16UC1, CV_32FC1, or none (empty matrix),
2440 respectively.
2441 @param dstmap1 The first output map that has the type dstmap1type and the same size as src .
2442 @param dstmap2 The second output map.
2443 @param dstmap1type Type of the first output map that should be CV_16SC2, CV_32FC1, or
2444 CV_32FC2 .
2445 @param nninterpolation Flag indicating whether the fixed-point maps are used for the
2446 nearest-neighbor or for a more complex interpolation.
2447
2448 @sa remap, undistort, initUndistortRectifyMap
2449 */
2450 CV_EXPORTS_W void convertMaps( InputArray map1, InputArray map2,
2451 OutputArray dstmap1, OutputArray dstmap2,
2452 int dstmap1type, bool nninterpolation = false );
2453
2454 /** @brief Calculates an affine matrix of 2D rotation.
2455
2456 The function calculates the following matrix:
2457
2458 \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]
2459
2460 where
2461
2462 \f[\begin{array}{l} \alpha = \texttt{scale} \cdot \cos \texttt{angle} , \\ \beta = \texttt{scale} \cdot \sin \texttt{angle} \end{array}\f]
2463
2464 The transformation maps the rotation center to itself. If this is not the target, adjust the shift.
2465
2466 @param center Center of the rotation in the source image.
2467 @param angle Rotation angle in degrees. Positive values mean counter-clockwise rotation (the
2468 coordinate origin is assumed to be the top-left corner).
2469 @param scale Isotropic scale factor.
2470
2471 @sa getAffineTransform, warpAffine, transform
2472 */
2473 CV_EXPORTS_W Mat getRotationMatrix2D(Point2f center, double angle, double scale);
2474
2475 /** @sa getRotationMatrix2D */
2476 CV_EXPORTS Matx23d getRotationMatrix2D_(Point2f center, double angle, double scale);
2477
2478 inline
getRotationMatrix2D(Point2f center,double angle,double scale)2479 Mat getRotationMatrix2D(Point2f center, double angle, double scale)
2480 {
2481 return Mat(getRotationMatrix2D_(center, angle, scale), true);
2482 }
2483
2484 /** @brief Calculates an affine transform from three pairs of the corresponding points.
2485
2486 The function calculates the \f$2 \times 3\f$ matrix of an affine transform so that:
2487
2488 \f[\begin{bmatrix} x'_i \\ y'_i \end{bmatrix} = \texttt{map_matrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix}\f]
2489
2490 where
2491
2492 \f[dst(i)=(x'_i,y'_i), src(i)=(x_i, y_i), i=0,1,2\f]
2493
2494 @param src Coordinates of triangle vertices in the source image.
2495 @param dst Coordinates of the corresponding triangle vertices in the destination image.
2496
2497 @sa warpAffine, transform
2498 */
2499 CV_EXPORTS Mat getAffineTransform( const Point2f src[], const Point2f dst[] );
2500
2501 /** @brief Inverts an affine transformation.
2502
2503 The function computes an inverse affine transformation represented by \f$2 \times 3\f$ matrix M:
2504
2505 \f[\begin{bmatrix} a_{11} & a_{12} & b_1 \\ a_{21} & a_{22} & b_2 \end{bmatrix}\f]
2506
2507 The result is also a \f$2 \times 3\f$ matrix of the same type as M.
2508
2509 @param M Original affine transformation.
2510 @param iM Output reverse affine transformation.
2511 */
2512 CV_EXPORTS_W void invertAffineTransform( InputArray M, OutputArray iM );
2513
2514 /** @brief Calculates a perspective transform from four pairs of the corresponding points.
2515
2516 The function calculates the \f$3 \times 3\f$ matrix of a perspective transform so that:
2517
2518 \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]
2519
2520 where
2521
2522 \f[dst(i)=(x'_i,y'_i), src(i)=(x_i, y_i), i=0,1,2,3\f]
2523
2524 @param src Coordinates of quadrangle vertices in the source image.
2525 @param dst Coordinates of the corresponding quadrangle vertices in the destination image.
2526 @param solveMethod method passed to cv::solve (#DecompTypes)
2527
2528 @sa findHomography, warpPerspective, perspectiveTransform
2529 */
2530 CV_EXPORTS_W Mat getPerspectiveTransform(InputArray src, InputArray dst, int solveMethod = DECOMP_LU);
2531
2532 /** @overload */
2533 CV_EXPORTS Mat getPerspectiveTransform(const Point2f src[], const Point2f dst[], int solveMethod = DECOMP_LU);
2534
2535
2536 CV_EXPORTS_W Mat getAffineTransform( InputArray src, InputArray dst );
2537
2538 /** @brief Retrieves a pixel rectangle from an image with sub-pixel accuracy.
2539
2540 The function getRectSubPix extracts pixels from src:
2541
2542 \f[patch(x, y) = src(x + \texttt{center.x} - ( \texttt{dst.cols} -1)*0.5, y + \texttt{center.y} - ( \texttt{dst.rows} -1)*0.5)\f]
2543
2544 where the values of the pixels at non-integer coordinates are retrieved using bilinear
2545 interpolation. Every channel of multi-channel images is processed independently. Also
2546 the image should be a single channel or three channel image. While the center of the
2547 rectangle must be inside the image, parts of the rectangle may be outside.
2548
2549 @param image Source image.
2550 @param patchSize Size of the extracted patch.
2551 @param center Floating point coordinates of the center of the extracted rectangle within the
2552 source image. The center must be inside the image.
2553 @param patch Extracted patch that has the size patchSize and the same number of channels as src .
2554 @param patchType Depth of the extracted pixels. By default, they have the same depth as src .
2555
2556 @sa warpAffine, warpPerspective
2557 */
2558 CV_EXPORTS_W void getRectSubPix( InputArray image, Size patchSize,
2559 Point2f center, OutputArray patch, int patchType = -1 );
2560
2561 /** @example samples/cpp/polar_transforms.cpp
2562 An example using the cv::linearPolar and cv::logPolar operations
2563 */
2564
2565 /** @brief Remaps an image to semilog-polar coordinates space.
2566
2567 @deprecated This function produces same result as cv::warpPolar(src, dst, src.size(), center, maxRadius, flags+WARP_POLAR_LOG);
2568
2569 @internal
2570 Transform the source image using the following transformation (See @ref polar_remaps_reference_image "Polar remaps reference image d)"):
2571 \f[\begin{array}{l}
2572 dst( \rho , \phi ) = src(x,y) \\
2573 dst.size() \leftarrow src.size()
2574 \end{array}\f]
2575
2576 where
2577 \f[\begin{array}{l}
2578 I = (dx,dy) = (x - center.x,y - center.y) \\
2579 \rho = M \cdot log_e(\texttt{magnitude} (I)) ,\\
2580 \phi = Kangle \cdot \texttt{angle} (I) \\
2581 \end{array}\f]
2582
2583 and
2584 \f[\begin{array}{l}
2585 M = src.cols / log_e(maxRadius) \\
2586 Kangle = src.rows / 2\Pi \\
2587 \end{array}\f]
2588
2589 The function emulates the human "foveal" vision and can be used for fast scale and
2590 rotation-invariant template matching, for object tracking and so forth.
2591 @param src Source image
2592 @param dst Destination image. It will have same size and type as src.
2593 @param center The transformation center; where the output precision is maximal
2594 @param M Magnitude scale parameter. It determines the radius of the bounding circle to transform too.
2595 @param flags A combination of interpolation methods, see #InterpolationFlags
2596
2597 @note
2598 - The function can not operate in-place.
2599 - To calculate magnitude and angle in degrees #cartToPolar is used internally thus angles are measured from 0 to 360 with accuracy about 0.3 degrees.
2600
2601 @sa cv::linearPolar
2602 @endinternal
2603 */
2604 CV_EXPORTS_W void logPolar( InputArray src, OutputArray dst,
2605 Point2f center, double M, int flags );
2606
2607 /** @brief Remaps an image to polar coordinates space.
2608
2609 @deprecated This function produces same result as cv::warpPolar(src, dst, src.size(), center, maxRadius, flags)
2610
2611 @internal
2612 Transform the source image using the following transformation (See @ref polar_remaps_reference_image "Polar remaps reference image c)"):
2613 \f[\begin{array}{l}
2614 dst( \rho , \phi ) = src(x,y) \\
2615 dst.size() \leftarrow src.size()
2616 \end{array}\f]
2617
2618 where
2619 \f[\begin{array}{l}
2620 I = (dx,dy) = (x - center.x,y - center.y) \\
2621 \rho = Kmag \cdot \texttt{magnitude} (I) ,\\
2622 \phi = angle \cdot \texttt{angle} (I)
2623 \end{array}\f]
2624
2625 and
2626 \f[\begin{array}{l}
2627 Kx = src.cols / maxRadius \\
2628 Ky = src.rows / 2\Pi
2629 \end{array}\f]
2630
2631
2632 @param src Source image
2633 @param dst Destination image. It will have same size and type as src.
2634 @param center The transformation center;
2635 @param maxRadius The radius of the bounding circle to transform. It determines the inverse magnitude scale parameter too.
2636 @param flags A combination of interpolation methods, see #InterpolationFlags
2637
2638 @note
2639 - The function can not operate in-place.
2640 - To calculate magnitude and angle in degrees #cartToPolar is used internally thus angles are measured from 0 to 360 with accuracy about 0.3 degrees.
2641
2642 @sa cv::logPolar
2643 @endinternal
2644 */
2645 CV_EXPORTS_W void linearPolar( InputArray src, OutputArray dst,
2646 Point2f center, double maxRadius, int flags );
2647
2648
2649 /** \brief Remaps an image to polar or semilog-polar coordinates space
2650
2651 @anchor polar_remaps_reference_image
2652 ![Polar remaps reference](pics/polar_remap_doc.png)
2653
2654 Transform the source image using the following transformation:
2655 \f[
2656 dst(\rho , \phi ) = src(x,y)
2657 \f]
2658
2659 where
2660 \f[
2661 \begin{array}{l}
2662 \vec{I} = (x - center.x, \;y - center.y) \\
2663 \phi = Kangle \cdot \texttt{angle} (\vec{I}) \\
2664 \rho = \left\{\begin{matrix}
2665 Klin \cdot \texttt{magnitude} (\vec{I}) & default \\
2666 Klog \cdot log_e(\texttt{magnitude} (\vec{I})) & if \; semilog \\
2667 \end{matrix}\right.
2668 \end{array}
2669 \f]
2670
2671 and
2672 \f[
2673 \begin{array}{l}
2674 Kangle = dsize.height / 2\Pi \\
2675 Klin = dsize.width / maxRadius \\
2676 Klog = dsize.width / log_e(maxRadius) \\
2677 \end{array}
2678 \f]
2679
2680
2681 \par Linear vs semilog mapping
2682
2683 Polar mapping can be linear or semi-log. Add one of #WarpPolarMode to `flags` to specify the polar mapping mode.
2684
2685 Linear is the default mode.
2686
2687 The semilog mapping emulates the human "foveal" vision that permit very high acuity on the line of sight (central vision)
2688 in contrast to peripheral vision where acuity is minor.
2689
2690 \par Option on `dsize`:
2691
2692 - if both values in `dsize <=0 ` (default),
2693 the destination image will have (almost) same area of source bounding circle:
2694 \f[\begin{array}{l}
2695 dsize.area \leftarrow (maxRadius^2 \cdot \Pi) \\
2696 dsize.width = \texttt{cvRound}(maxRadius) \\
2697 dsize.height = \texttt{cvRound}(maxRadius \cdot \Pi) \\
2698 \end{array}\f]
2699
2700
2701 - if only `dsize.height <= 0`,
2702 the destination image area will be proportional to the bounding circle area but scaled by `Kx * Kx`:
2703 \f[\begin{array}{l}
2704 dsize.height = \texttt{cvRound}(dsize.width \cdot \Pi) \\
2705 \end{array}
2706 \f]
2707
2708 - if both values in `dsize > 0 `,
2709 the destination image will have the given size therefore the area of the bounding circle will be scaled to `dsize`.
2710
2711
2712 \par Reverse mapping
2713
2714 You can get reverse mapping adding #WARP_INVERSE_MAP to `flags`
2715 \snippet polar_transforms.cpp InverseMap
2716
2717 In addiction, to calculate the original coordinate from a polar mapped coordinate \f$(rho, phi)->(x, y)\f$:
2718 \snippet polar_transforms.cpp InverseCoordinate
2719
2720 @param src Source image.
2721 @param dst Destination image. It will have same type as src.
2722 @param dsize The destination image size (see description for valid options).
2723 @param center The transformation center.
2724 @param maxRadius The radius of the bounding circle to transform. It determines the inverse magnitude scale parameter too.
2725 @param flags A combination of interpolation methods, #InterpolationFlags + #WarpPolarMode.
2726 - Add #WARP_POLAR_LINEAR to select linear polar mapping (default)
2727 - Add #WARP_POLAR_LOG to select semilog polar mapping
2728 - Add #WARP_INVERSE_MAP for reverse mapping.
2729 @note
2730 - The function can not operate in-place.
2731 - To calculate magnitude and angle in degrees #cartToPolar is used internally thus angles are measured from 0 to 360 with accuracy about 0.3 degrees.
2732 - This function uses #remap. Due to current implementation limitations the size of an input and output images should be less than 32767x32767.
2733
2734 @sa cv::remap
2735 */
2736 CV_EXPORTS_W void warpPolar(InputArray src, OutputArray dst, Size dsize,
2737 Point2f center, double maxRadius, int flags);
2738
2739
2740 //! @} imgproc_transform
2741
2742 //! @addtogroup imgproc_misc
2743 //! @{
2744
2745 /** @overload */
2746 CV_EXPORTS_W void integral( InputArray src, OutputArray sum, int sdepth = -1 );
2747
2748 /** @overload */
2749 CV_EXPORTS_AS(integral2) void integral( InputArray src, OutputArray sum,
2750 OutputArray sqsum, int sdepth = -1, int sqdepth = -1 );
2751
2752 /** @brief Calculates the integral of an image.
2753
2754 The function calculates one or more integral images for the source image as follows:
2755
2756 \f[\texttt{sum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)\f]
2757
2758 \f[\texttt{sqsum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)^2\f]
2759
2760 \f[\texttt{tilted} (X,Y) = \sum _{y<Y,abs(x-X+1) \leq Y-y-1} \texttt{image} (x,y)\f]
2761
2762 Using these integral images, you can calculate sum, mean, and standard deviation over a specific
2763 up-right or rotated rectangular region of the image in a constant time, for example:
2764
2765 \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]
2766
2767 It makes possible to do a fast blurring or fast block correlation with a variable window size, for
2768 example. In case of multi-channel images, sums for each channel are accumulated independently.
2769
2770 As a practical example, the next figure shows the calculation of the integral of a straight
2771 rectangle Rect(3,3,3,2) and of a tilted rectangle Rect(5,1,2,3) . The selected pixels in the
2772 original image are shown, as well as the relative pixels in the integral images sum and tilted .
2773
2774 ![integral calculation example](pics/integral.png)
2775
2776 @param src input image as \f$W \times H\f$, 8-bit or floating-point (32f or 64f).
2777 @param sum integral image as \f$(W+1)\times (H+1)\f$ , 32-bit integer or floating-point (32f or 64f).
2778 @param sqsum integral image for squared pixel values; it is \f$(W+1)\times (H+1)\f$, double-precision
2779 floating-point (64f) array.
2780 @param tilted integral for the image rotated by 45 degrees; it is \f$(W+1)\times (H+1)\f$ array with
2781 the same data type as sum.
2782 @param sdepth desired depth of the integral and the tilted integral images, CV_32S, CV_32F, or
2783 CV_64F.
2784 @param sqdepth desired depth of the integral image of squared pixel values, CV_32F or CV_64F.
2785 */
2786 CV_EXPORTS_AS(integral3) void integral( InputArray src, OutputArray sum,
2787 OutputArray sqsum, OutputArray tilted,
2788 int sdepth = -1, int sqdepth = -1 );
2789
2790 //! @} imgproc_misc
2791
2792 //! @addtogroup imgproc_motion
2793 //! @{
2794
2795 /** @brief Adds an image to the accumulator image.
2796
2797 The function adds src or some of its elements to dst :
2798
2799 \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]
2800
2801 The function supports multi-channel images. Each channel is processed independently.
2802
2803 The function cv::accumulate can be used, for example, to collect statistics of a scene background
2804 viewed by a still camera and for the further foreground-background segmentation.
2805
2806 @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.
2807 @param dst %Accumulator image with the same number of channels as input image, and a depth of CV_32F or CV_64F.
2808 @param mask Optional operation mask.
2809
2810 @sa accumulateSquare, accumulateProduct, accumulateWeighted
2811 */
2812 CV_EXPORTS_W void accumulate( InputArray src, InputOutputArray dst,
2813 InputArray mask = noArray() );
2814
2815 /** @brief Adds the square of a source image to the accumulator image.
2816
2817 The function adds the input image src or its selected region, raised to a power of 2, to the
2818 accumulator dst :
2819
2820 \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]
2821
2822 The function supports multi-channel images. Each channel is processed independently.
2823
2824 @param src Input image as 1- or 3-channel, 8-bit or 32-bit floating point.
2825 @param dst %Accumulator image with the same number of channels as input image, 32-bit or 64-bit
2826 floating-point.
2827 @param mask Optional operation mask.
2828
2829 @sa accumulateSquare, accumulateProduct, accumulateWeighted
2830 */
2831 CV_EXPORTS_W void accumulateSquare( InputArray src, InputOutputArray dst,
2832 InputArray mask = noArray() );
2833
2834 /** @brief Adds the per-element product of two input images to the accumulator image.
2835
2836 The function adds the product of two images or their selected regions to the accumulator dst :
2837
2838 \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]
2839
2840 The function supports multi-channel images. Each channel is processed independently.
2841
2842 @param src1 First input image, 1- or 3-channel, 8-bit or 32-bit floating point.
2843 @param src2 Second input image of the same type and the same size as src1 .
2844 @param dst %Accumulator image with the same number of channels as input images, 32-bit or 64-bit
2845 floating-point.
2846 @param mask Optional operation mask.
2847
2848 @sa accumulate, accumulateSquare, accumulateWeighted
2849 */
2850 CV_EXPORTS_W void accumulateProduct( InputArray src1, InputArray src2,
2851 InputOutputArray dst, InputArray mask=noArray() );
2852
2853 /** @brief Updates a running average.
2854
2855 The function calculates the weighted sum of the input image src and the accumulator dst so that dst
2856 becomes a running average of a frame sequence:
2857
2858 \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]
2859
2860 That is, alpha regulates the update speed (how fast the accumulator "forgets" about earlier images).
2861 The function supports multi-channel images. Each channel is processed independently.
2862
2863 @param src Input image as 1- or 3-channel, 8-bit or 32-bit floating point.
2864 @param dst %Accumulator image with the same number of channels as input image, 32-bit or 64-bit
2865 floating-point.
2866 @param alpha Weight of the input image.
2867 @param mask Optional operation mask.
2868
2869 @sa accumulate, accumulateSquare, accumulateProduct
2870 */
2871 CV_EXPORTS_W void accumulateWeighted( InputArray src, InputOutputArray dst,
2872 double alpha, InputArray mask = noArray() );
2873
2874 /** @brief The function is used to detect translational shifts that occur between two images.
2875
2876 The operation takes advantage of the Fourier shift theorem for detecting the translational shift in
2877 the frequency domain. It can be used for fast image registration as well as motion estimation. For
2878 more information please see <http://en.wikipedia.org/wiki/Phase_correlation>
2879
2880 Calculates the cross-power spectrum of two supplied source arrays. The arrays are padded if needed
2881 with getOptimalDFTSize.
2882
2883 The function performs the following equations:
2884 - First it applies a Hanning window (see <http://en.wikipedia.org/wiki/Hann_function>) to each
2885 image to remove possible edge effects. This window is cached until the array size changes to speed
2886 up processing time.
2887 - Next it computes the forward DFTs of each source array:
2888 \f[\mathbf{G}_a = \mathcal{F}\{src_1\}, \; \mathbf{G}_b = \mathcal{F}\{src_2\}\f]
2889 where \f$\mathcal{F}\f$ is the forward DFT.
2890 - It then computes the cross-power spectrum of each frequency domain array:
2891 \f[R = \frac{ \mathbf{G}_a \mathbf{G}_b^*}{|\mathbf{G}_a \mathbf{G}_b^*|}\f]
2892 - Next the cross-correlation is converted back into the time domain via the inverse DFT:
2893 \f[r = \mathcal{F}^{-1}\{R\}\f]
2894 - Finally, it computes the peak location and computes a 5x5 weighted centroid around the peak to
2895 achieve sub-pixel accuracy.
2896 \f[(\Delta x, \Delta y) = \texttt{weightedCentroid} \{\arg \max_{(x, y)}\{r\}\}\f]
2897 - If non-zero, the response parameter is computed as the sum of the elements of r within the 5x5
2898 centroid around the peak location. It is normalized to a maximum of 1 (meaning there is a single
2899 peak) and will be smaller when there are multiple peaks.
2900
2901 @param src1 Source floating point array (CV_32FC1 or CV_64FC1)
2902 @param src2 Source floating point array (CV_32FC1 or CV_64FC1)
2903 @param window Floating point array with windowing coefficients to reduce edge effects (optional).
2904 @param response Signal power within the 5x5 centroid around the peak, between 0 and 1 (optional).
2905 @returns detected phase shift (sub-pixel) between the two arrays.
2906
2907 @sa dft, getOptimalDFTSize, idft, mulSpectrums createHanningWindow
2908 */
2909 CV_EXPORTS_W Point2d phaseCorrelate(InputArray src1, InputArray src2,
2910 InputArray window = noArray(), CV_OUT double* response = 0);
2911
2912 /** @brief This function computes a Hanning window coefficients in two dimensions.
2913
2914 See (http://en.wikipedia.org/wiki/Hann_function) and (http://en.wikipedia.org/wiki/Window_function)
2915 for more information.
2916
2917 An example is shown below:
2918 @code
2919 // create hanning window of size 100x100 and type CV_32F
2920 Mat hann;
2921 createHanningWindow(hann, Size(100, 100), CV_32F);
2922 @endcode
2923 @param dst Destination array to place Hann coefficients in
2924 @param winSize The window size specifications (both width and height must be > 1)
2925 @param type Created array type
2926 */
2927 CV_EXPORTS_W void createHanningWindow(OutputArray dst, Size winSize, int type);
2928
2929 /** @brief Performs the per-element division of the first Fourier spectrum by the second Fourier spectrum.
2930
2931 The function cv::divSpectrums performs the per-element division of the first array by the second array.
2932 The arrays are CCS-packed or complex matrices that are results of a real or complex Fourier transform.
2933
2934 @param a first input array.
2935 @param b second input array of the same size and type as src1 .
2936 @param c output array of the same size and type as src1 .
2937 @param flags operation flags; currently, the only supported flag is cv::DFT_ROWS, which indicates that
2938 each row of src1 and src2 is an independent 1D Fourier spectrum. If you do not want to use this flag, then simply add a `0` as value.
2939 @param conjB optional flag that conjugates the second input array before the multiplication (true)
2940 or not (false).
2941 */
2942 CV_EXPORTS_W void divSpectrums(InputArray a, InputArray b, OutputArray c,
2943 int flags, bool conjB = false);
2944
2945 //! @} imgproc_motion
2946
2947 //! @addtogroup imgproc_misc
2948 //! @{
2949
2950 /** @brief Applies a fixed-level threshold to each array element.
2951
2952 The function applies fixed-level thresholding to a multiple-channel array. The function is typically
2953 used to get a bi-level (binary) image out of a grayscale image ( #compare could be also used for
2954 this purpose) or for removing a noise, that is, filtering out pixels with too small or too large
2955 values. There are several types of thresholding supported by the function. They are determined by
2956 type parameter.
2957
2958 Also, the special values #THRESH_OTSU or #THRESH_TRIANGLE may be combined with one of the
2959 above values. In these cases, the function determines the optimal threshold value using the Otsu's
2960 or Triangle algorithm and uses it instead of the specified thresh.
2961
2962 @note Currently, the Otsu's and Triangle methods are implemented only for 8-bit single-channel images.
2963
2964 @param src input array (multiple-channel, 8-bit or 32-bit floating point).
2965 @param dst output array of the same size and type and the same number of channels as src.
2966 @param thresh threshold value.
2967 @param maxval maximum value to use with the #THRESH_BINARY and #THRESH_BINARY_INV thresholding
2968 types.
2969 @param type thresholding type (see #ThresholdTypes).
2970 @return the computed threshold value if Otsu's or Triangle methods used.
2971
2972 @sa adaptiveThreshold, findContours, compare, min, max
2973 */
2974 CV_EXPORTS_W double threshold( InputArray src, OutputArray dst,
2975 double thresh, double maxval, int type );
2976
2977
2978 /** @brief Applies an adaptive threshold to an array.
2979
2980 The function transforms a grayscale image to a binary image according to the formulae:
2981 - **THRESH_BINARY**
2982 \f[dst(x,y) = \fork{\texttt{maxValue}}{if \(src(x,y) > T(x,y)\)}{0}{otherwise}\f]
2983 - **THRESH_BINARY_INV**
2984 \f[dst(x,y) = \fork{0}{if \(src(x,y) > T(x,y)\)}{\texttt{maxValue}}{otherwise}\f]
2985 where \f$T(x,y)\f$ is a threshold calculated individually for each pixel (see adaptiveMethod parameter).
2986
2987 The function can process the image in-place.
2988
2989 @param src Source 8-bit single-channel image.
2990 @param dst Destination image of the same size and the same type as src.
2991 @param maxValue Non-zero value assigned to the pixels for which the condition is satisfied
2992 @param adaptiveMethod Adaptive thresholding algorithm to use, see #AdaptiveThresholdTypes.
2993 The #BORDER_REPLICATE | #BORDER_ISOLATED is used to process boundaries.
2994 @param thresholdType Thresholding type that must be either #THRESH_BINARY or #THRESH_BINARY_INV,
2995 see #ThresholdTypes.
2996 @param blockSize Size of a pixel neighborhood that is used to calculate a threshold value for the
2997 pixel: 3, 5, 7, and so on.
2998 @param C Constant subtracted from the mean or weighted mean (see the details below). Normally, it
2999 is positive but may be zero or negative as well.
3000
3001 @sa threshold, blur, GaussianBlur
3002 */
3003 CV_EXPORTS_W void adaptiveThreshold( InputArray src, OutputArray dst,
3004 double maxValue, int adaptiveMethod,
3005 int thresholdType, int blockSize, double C );
3006
3007 //! @} imgproc_misc
3008
3009 //! @addtogroup imgproc_filter
3010 //! @{
3011
3012 /** @example samples/cpp/tutorial_code/ImgProc/Pyramids/Pyramids.cpp
3013 An example using pyrDown and pyrUp functions
3014 */
3015
3016 /** @brief Blurs an image and downsamples it.
3017
3018 By default, size of the output image is computed as `Size((src.cols+1)/2, (src.rows+1)/2)`, but in
3019 any case, the following conditions should be satisfied:
3020
3021 \f[\begin{array}{l} | \texttt{dstsize.width} *2-src.cols| \leq 2 \\ | \texttt{dstsize.height} *2-src.rows| \leq 2 \end{array}\f]
3022
3023 The function performs the downsampling step of the Gaussian pyramid construction. First, it
3024 convolves the source image with the kernel:
3025
3026 \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]
3027
3028 Then, it downsamples the image by rejecting even rows and columns.
3029
3030 @param src input image.
3031 @param dst output image; it has the specified size and the same type as src.
3032 @param dstsize size of the output image.
3033 @param borderType Pixel extrapolation method, see #BorderTypes (#BORDER_CONSTANT isn't supported)
3034 */
3035 CV_EXPORTS_W void pyrDown( InputArray src, OutputArray dst,
3036 const Size& dstsize = Size(), int borderType = BORDER_DEFAULT );
3037
3038 /** @brief Upsamples an image and then blurs it.
3039
3040 By default, size of the output image is computed as `Size(src.cols\*2, (src.rows\*2)`, but in any
3041 case, the following conditions should be satisfied:
3042
3043 \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]
3044
3045 The function performs the upsampling step of the Gaussian pyramid construction, though it can
3046 actually be used to construct the Laplacian pyramid. First, it upsamples the source image by
3047 injecting even zero rows and columns and then convolves the result with the same kernel as in
3048 pyrDown multiplied by 4.
3049
3050 @param src input image.
3051 @param dst output image. It has the specified size and the same type as src .
3052 @param dstsize size of the output image.
3053 @param borderType Pixel extrapolation method, see #BorderTypes (only #BORDER_DEFAULT is supported)
3054 */
3055 CV_EXPORTS_W void pyrUp( InputArray src, OutputArray dst,
3056 const Size& dstsize = Size(), int borderType = BORDER_DEFAULT );
3057
3058 /** @brief Constructs the Gaussian pyramid for an image.
3059
3060 The function constructs a vector of images and builds the Gaussian pyramid by recursively applying
3061 pyrDown to the previously built pyramid layers, starting from `dst[0]==src`.
3062
3063 @param src Source image. Check pyrDown for the list of supported types.
3064 @param dst Destination vector of maxlevel+1 images of the same type as src. dst[0] will be the
3065 same as src. dst[1] is the next pyramid layer, a smoothed and down-sized src, and so on.
3066 @param maxlevel 0-based index of the last (the smallest) pyramid layer. It must be non-negative.
3067 @param borderType Pixel extrapolation method, see #BorderTypes (#BORDER_CONSTANT isn't supported)
3068 */
3069 CV_EXPORTS void buildPyramid( InputArray src, OutputArrayOfArrays dst,
3070 int maxlevel, int borderType = BORDER_DEFAULT );
3071
3072 //! @} imgproc_filter
3073
3074 //! @addtogroup imgproc_hist
3075 //! @{
3076
3077 /** @example samples/cpp/demhist.cpp
3078 An example for creating histograms of an image
3079 */
3080
3081 /** @brief Calculates a histogram of a set of arrays.
3082
3083 The function cv::calcHist calculates the histogram of one or more arrays. The elements of a tuple used
3084 to increment a histogram bin are taken from the corresponding input arrays at the same location. The
3085 sample below shows how to compute a 2D Hue-Saturation histogram for a color image. :
3086 @include snippets/imgproc_calcHist.cpp
3087
3088 @param images Source arrays. They all should have the same depth, CV_8U, CV_16U or CV_32F , and the same
3089 size. Each of them can have an arbitrary number of channels.
3090 @param nimages Number of source images.
3091 @param channels List of the dims channels used to compute the histogram. The first array channels
3092 are numerated from 0 to images[0].channels()-1 , the second array channels are counted from
3093 images[0].channels() to images[0].channels() + images[1].channels()-1, and so on.
3094 @param mask Optional mask. If the matrix is not empty, it must be an 8-bit array of the same size
3095 as images[i] . The non-zero mask elements mark the array elements counted in the histogram.
3096 @param hist Output histogram, which is a dense or sparse dims -dimensional array.
3097 @param dims Histogram dimensionality that must be positive and not greater than CV_MAX_DIMS
3098 (equal to 32 in the current OpenCV version).
3099 @param histSize Array of histogram sizes in each dimension.
3100 @param ranges Array of the dims arrays of the histogram bin boundaries in each dimension. When the
3101 histogram is uniform ( uniform =true), then for each dimension i it is enough to specify the lower
3102 (inclusive) boundary \f$L_0\f$ of the 0-th histogram bin and the upper (exclusive) boundary
3103 \f$U_{\texttt{histSize}[i]-1}\f$ for the last histogram bin histSize[i]-1 . That is, in case of a
3104 uniform histogram each of ranges[i] is an array of 2 elements. When the histogram is not uniform (
3105 uniform=false ), then each of ranges[i] contains histSize[i]+1 elements:
3106 \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$
3107 . The array elements, that are not between \f$L_0\f$ and \f$U_{\texttt{histSize[i]}-1}\f$ , are not
3108 counted in the histogram.
3109 @param uniform Flag indicating whether the histogram is uniform or not (see above).
3110 @param accumulate Accumulation flag. If it is set, the histogram is not cleared in the beginning
3111 when it is allocated. This feature enables you to compute a single histogram from several sets of
3112 arrays, or to update the histogram in time.
3113 */
3114 CV_EXPORTS void calcHist( const Mat* images, int nimages,
3115 const int* channels, InputArray mask,
3116 OutputArray hist, int dims, const int* histSize,
3117 const float** ranges, bool uniform = true, bool accumulate = false );
3118
3119 /** @overload
3120
3121 this variant uses %SparseMat for output
3122 */
3123 CV_EXPORTS void calcHist( const Mat* images, int nimages,
3124 const int* channels, InputArray mask,
3125 SparseMat& hist, int dims,
3126 const int* histSize, const float** ranges,
3127 bool uniform = true, bool accumulate = false );
3128
3129 /** @overload */
3130 CV_EXPORTS_W void calcHist( InputArrayOfArrays images,
3131 const std::vector<int>& channels,
3132 InputArray mask, OutputArray hist,
3133 const std::vector<int>& histSize,
3134 const std::vector<float>& ranges,
3135 bool accumulate = false );
3136
3137 /** @brief Calculates the back projection of a histogram.
3138
3139 The function cv::calcBackProject calculates the back project of the histogram. That is, similarly to
3140 #calcHist , at each location (x, y) the function collects the values from the selected channels
3141 in the input images and finds the corresponding histogram bin. But instead of incrementing it, the
3142 function reads the bin value, scales it by scale , and stores in backProject(x,y) . In terms of
3143 statistics, the function computes probability of each element value in respect with the empirical
3144 probability distribution represented by the histogram. See how, for example, you can find and track
3145 a bright-colored object in a scene:
3146
3147 - Before tracking, show the object to the camera so that it covers almost the whole frame.
3148 Calculate a hue histogram. The histogram may have strong maximums, corresponding to the dominant
3149 colors in the object.
3150
3151 - When tracking, calculate a back projection of a hue plane of each input video frame using that
3152 pre-computed histogram. Threshold the back projection to suppress weak colors. It may also make
3153 sense to suppress pixels with non-sufficient color saturation and too dark or too bright pixels.
3154
3155 - Find connected components in the resulting picture and choose, for example, the largest
3156 component.
3157
3158 This is an approximate algorithm of the CamShift color object tracker.
3159
3160 @param images Source arrays. They all should have the same depth, CV_8U, CV_16U or CV_32F , and the same
3161 size. Each of them can have an arbitrary number of channels.
3162 @param nimages Number of source images.
3163 @param channels The list of channels used to compute the back projection. The number of channels
3164 must match the histogram dimensionality. The first array channels are numerated from 0 to
3165 images[0].channels()-1 , the second array channels are counted from images[0].channels() to
3166 images[0].channels() + images[1].channels()-1, and so on.
3167 @param hist Input histogram that can be dense or sparse.
3168 @param backProject Destination back projection array that is a single-channel array of the same
3169 size and depth as images[0] .
3170 @param ranges Array of arrays of the histogram bin boundaries in each dimension. See #calcHist .
3171 @param scale Optional scale factor for the output back projection.
3172 @param uniform Flag indicating whether the histogram is uniform or not (see above).
3173
3174 @sa calcHist, compareHist
3175 */
3176 CV_EXPORTS void calcBackProject( const Mat* images, int nimages,
3177 const int* channels, InputArray hist,
3178 OutputArray backProject, const float** ranges,
3179 double scale = 1, bool uniform = true );
3180
3181 /** @overload */
3182 CV_EXPORTS void calcBackProject( const Mat* images, int nimages,
3183 const int* channels, const SparseMat& hist,
3184 OutputArray backProject, const float** ranges,
3185 double scale = 1, bool uniform = true );
3186
3187 /** @overload */
3188 CV_EXPORTS_W void calcBackProject( InputArrayOfArrays images, const std::vector<int>& channels,
3189 InputArray hist, OutputArray dst,
3190 const std::vector<float>& ranges,
3191 double scale );
3192
3193 /** @brief Compares two histograms.
3194
3195 The function cv::compareHist compares two dense or two sparse histograms using the specified method.
3196
3197 The function returns \f$d(H_1, H_2)\f$ .
3198
3199 While the function works well with 1-, 2-, 3-dimensional dense histograms, it may not be suitable
3200 for high-dimensional sparse histograms. In such histograms, because of aliasing and sampling
3201 problems, the coordinates of non-zero histogram bins can slightly shift. To compare such histograms
3202 or more general sparse configurations of weighted points, consider using the #EMD function.
3203
3204 @param H1 First compared histogram.
3205 @param H2 Second compared histogram of the same size as H1 .
3206 @param method Comparison method, see #HistCompMethods
3207 */
3208 CV_EXPORTS_W double compareHist( InputArray H1, InputArray H2, int method );
3209
3210 /** @overload */
3211 CV_EXPORTS double compareHist( const SparseMat& H1, const SparseMat& H2, int method );
3212
3213 /** @brief Equalizes the histogram of a grayscale image.
3214
3215 The function equalizes the histogram of the input image using the following algorithm:
3216
3217 - Calculate the histogram \f$H\f$ for src .
3218 - Normalize the histogram so that the sum of histogram bins is 255.
3219 - Compute the integral of the histogram:
3220 \f[H'_i = \sum _{0 \le j < i} H(j)\f]
3221 - Transform the image using \f$H'\f$ as a look-up table: \f$\texttt{dst}(x,y) = H'(\texttt{src}(x,y))\f$
3222
3223 The algorithm normalizes the brightness and increases the contrast of the image.
3224
3225 @param src Source 8-bit single channel image.
3226 @param dst Destination image of the same size and type as src .
3227 */
3228 CV_EXPORTS_W void equalizeHist( InputArray src, OutputArray dst );
3229
3230 /** @brief Creates a smart pointer to a cv::CLAHE class and initializes it.
3231
3232 @param clipLimit Threshold for contrast limiting.
3233 @param tileGridSize Size of grid for histogram equalization. Input image will be divided into
3234 equally sized rectangular tiles. tileGridSize defines the number of tiles in row and column.
3235 */
3236 CV_EXPORTS_W Ptr<CLAHE> createCLAHE(double clipLimit = 40.0, Size tileGridSize = Size(8, 8));
3237
3238 /** @brief Computes the "minimal work" distance between two weighted point configurations.
3239
3240 The function computes the earth mover distance and/or a lower boundary of the distance between the
3241 two weighted point configurations. One of the applications described in @cite RubnerSept98,
3242 @cite Rubner2000 is multi-dimensional histogram comparison for image retrieval. EMD is a transportation
3243 problem that is solved using some modification of a simplex algorithm, thus the complexity is
3244 exponential in the worst case, though, on average it is much faster. In the case of a real metric
3245 the lower boundary can be calculated even faster (using linear-time algorithm) and it can be used
3246 to determine roughly whether the two signatures are far enough so that they cannot relate to the
3247 same object.
3248
3249 @param signature1 First signature, a \f$\texttt{size1}\times \texttt{dims}+1\f$ floating-point matrix.
3250 Each row stores the point weight followed by the point coordinates. The matrix is allowed to have
3251 a single column (weights only) if the user-defined cost matrix is used. The weights must be
3252 non-negative and have at least one non-zero value.
3253 @param signature2 Second signature of the same format as signature1 , though the number of rows
3254 may be different. The total weights may be different. In this case an extra "dummy" point is added
3255 to either signature1 or signature2. The weights must be non-negative and have at least one non-zero
3256 value.
3257 @param distType Used metric. See #DistanceTypes.
3258 @param cost User-defined \f$\texttt{size1}\times \texttt{size2}\f$ cost matrix. Also, if a cost matrix
3259 is used, lower boundary lowerBound cannot be calculated because it needs a metric function.
3260 @param lowerBound Optional input/output parameter: lower boundary of a distance between the two
3261 signatures that is a distance between mass centers. The lower boundary may not be calculated if
3262 the user-defined cost matrix is used, the total weights of point configurations are not equal, or
3263 if the signatures consist of weights only (the signature matrices have a single column). You
3264 **must** initialize \*lowerBound . If the calculated distance between mass centers is greater or
3265 equal to \*lowerBound (it means that the signatures are far enough), the function does not
3266 calculate EMD. In any case \*lowerBound is set to the calculated distance between mass centers on
3267 return. Thus, if you want to calculate both distance between mass centers and EMD, \*lowerBound
3268 should be set to 0.
3269 @param flow Resultant \f$\texttt{size1} \times \texttt{size2}\f$ flow matrix: \f$\texttt{flow}_{i,j}\f$ is
3270 a flow from \f$i\f$ -th point of signature1 to \f$j\f$ -th point of signature2 .
3271 */
3272 CV_EXPORTS float EMD( InputArray signature1, InputArray signature2,
3273 int distType, InputArray cost=noArray(),
3274 float* lowerBound = 0, OutputArray flow = noArray() );
3275
3276 CV_EXPORTS_AS(EMD) float wrapperEMD( InputArray signature1, InputArray signature2,
3277 int distType, InputArray cost=noArray(),
3278 CV_IN_OUT Ptr<float> lowerBound = Ptr<float>(), OutputArray flow = noArray() );
3279
3280 //! @} imgproc_hist
3281
3282 //! @addtogroup imgproc_segmentation
3283 //! @{
3284
3285 /** @example samples/cpp/watershed.cpp
3286 An example using the watershed algorithm
3287 */
3288
3289 /** @brief Performs a marker-based image segmentation using the watershed algorithm.
3290
3291 The function implements one of the variants of watershed, non-parametric marker-based segmentation
3292 algorithm, described in @cite Meyer92 .
3293
3294 Before passing the image to the function, you have to roughly outline the desired regions in the
3295 image markers with positive (\>0) indices. So, every region is represented as one or more connected
3296 components with the pixel values 1, 2, 3, and so on. Such markers can be retrieved from a binary
3297 mask using #findContours and #drawContours (see the watershed.cpp demo). The markers are "seeds" of
3298 the future image regions. All the other pixels in markers , whose relation to the outlined regions
3299 is not known and should be defined by the algorithm, should be set to 0's. In the function output,
3300 each pixel in markers is set to a value of the "seed" components or to -1 at boundaries between the
3301 regions.
3302
3303 @note Any two neighbor connected components are not necessarily separated by a watershed boundary
3304 (-1's pixels); for example, they can touch each other in the initial marker image passed to the
3305 function.
3306
3307 @param image Input 8-bit 3-channel image.
3308 @param markers Input/output 32-bit single-channel image (map) of markers. It should have the same
3309 size as image .
3310
3311 @sa findContours
3312 */
3313 CV_EXPORTS_W void watershed( InputArray image, InputOutputArray markers );
3314
3315 //! @} imgproc_segmentation
3316
3317 //! @addtogroup imgproc_filter
3318 //! @{
3319
3320 /** @brief Performs initial step of meanshift segmentation of an image.
3321
3322 The function implements the filtering stage of meanshift segmentation, that is, the output of the
3323 function is the filtered "posterized" image with color gradients and fine-grain texture flattened.
3324 At every pixel (X,Y) of the input image (or down-sized input image, see below) the function executes
3325 meanshift iterations, that is, the pixel (X,Y) neighborhood in the joint space-color hyperspace is
3326 considered:
3327
3328 \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]
3329
3330 where (R,G,B) and (r,g,b) are the vectors of color components at (X,Y) and (x,y), respectively
3331 (though, the algorithm does not depend on the color space used, so any 3-component color space can
3332 be used instead). Over the neighborhood the average spatial value (X',Y') and average color vector
3333 (R',G',B') are found and they act as the neighborhood center on the next iteration:
3334
3335 \f[(X,Y)~(X',Y'), (R,G,B)~(R',G',B').\f]
3336
3337 After the iterations over, the color components of the initial pixel (that is, the pixel from where
3338 the iterations started) are set to the final value (average color at the last iteration):
3339
3340 \f[I(X,Y) <- (R*,G*,B*)\f]
3341
3342 When maxLevel \> 0, the gaussian pyramid of maxLevel+1 levels is built, and the above procedure is
3343 run on the smallest layer first. After that, the results are propagated to the larger layer and the
3344 iterations are run again only on those pixels where the layer colors differ by more than sr from the
3345 lower-resolution layer of the pyramid. That makes boundaries of color regions sharper. Note that the
3346 results will be actually different from the ones obtained by running the meanshift procedure on the
3347 whole original image (i.e. when maxLevel==0).
3348
3349 @param src The source 8-bit, 3-channel image.
3350 @param dst The destination image of the same format and the same size as the source.
3351 @param sp The spatial window radius.
3352 @param sr The color window radius.
3353 @param maxLevel Maximum level of the pyramid for the segmentation.
3354 @param termcrit Termination criteria: when to stop meanshift iterations.
3355 */
3356 CV_EXPORTS_W void pyrMeanShiftFiltering( InputArray src, OutputArray dst,
3357 double sp, double sr, int maxLevel = 1,
3358 TermCriteria termcrit=TermCriteria(TermCriteria::MAX_ITER+TermCriteria::EPS,5,1) );
3359
3360 //! @}
3361
3362 //! @addtogroup imgproc_segmentation
3363 //! @{
3364
3365 /** @example samples/cpp/grabcut.cpp
3366 An example using the GrabCut algorithm
3367 ![Sample Screenshot](grabcut_output1.jpg)
3368 */
3369
3370 /** @brief Runs the GrabCut algorithm.
3371
3372 The function implements the [GrabCut image segmentation algorithm](http://en.wikipedia.org/wiki/GrabCut).
3373
3374 @param img Input 8-bit 3-channel image.
3375 @param mask Input/output 8-bit single-channel mask. The mask is initialized by the function when
3376 mode is set to #GC_INIT_WITH_RECT. Its elements may have one of the #GrabCutClasses.
3377 @param rect ROI containing a segmented object. The pixels outside of the ROI are marked as
3378 "obvious background". The parameter is only used when mode==#GC_INIT_WITH_RECT .
3379 @param bgdModel Temporary array for the background model. Do not modify it while you are
3380 processing the same image.
3381 @param fgdModel Temporary arrays for the foreground model. Do not modify it while you are
3382 processing the same image.
3383 @param iterCount Number of iterations the algorithm should make before returning the result. Note
3384 that the result can be refined with further calls with mode==#GC_INIT_WITH_MASK or
3385 mode==GC_EVAL .
3386 @param mode Operation mode that could be one of the #GrabCutModes
3387 */
3388 CV_EXPORTS_W void grabCut( InputArray img, InputOutputArray mask, Rect rect,
3389 InputOutputArray bgdModel, InputOutputArray fgdModel,
3390 int iterCount, int mode = GC_EVAL );
3391
3392 //! @} imgproc_segmentation
3393
3394 //! @addtogroup imgproc_misc
3395 //! @{
3396
3397 /** @example samples/cpp/distrans.cpp
3398 An example on using the distance transform
3399 */
3400
3401 /** @brief Calculates the distance to the closest zero pixel for each pixel of the source image.
3402
3403 The function cv::distanceTransform calculates the approximate or precise distance from every binary
3404 image pixel to the nearest zero pixel. For zero image pixels, the distance will obviously be zero.
3405
3406 When maskSize == #DIST_MASK_PRECISE and distanceType == #DIST_L2 , the function runs the
3407 algorithm described in @cite Felzenszwalb04 . This algorithm is parallelized with the TBB library.
3408
3409 In other cases, the algorithm @cite Borgefors86 is used. This means that for a pixel the function
3410 finds the shortest path to the nearest zero pixel consisting of basic shifts: horizontal, vertical,
3411 diagonal, or knight's move (the latest is available for a \f$5\times 5\f$ mask). The overall
3412 distance is calculated as a sum of these basic distances. Since the distance function should be
3413 symmetric, all of the horizontal and vertical shifts must have the same cost (denoted as a ), all
3414 the diagonal shifts must have the same cost (denoted as `b`), and all knight's moves must have the
3415 same cost (denoted as `c`). For the #DIST_C and #DIST_L1 types, the distance is calculated
3416 precisely, whereas for #DIST_L2 (Euclidean distance) the distance can be calculated only with a
3417 relative error (a \f$5\times 5\f$ mask gives more accurate results). For `a`,`b`, and `c`, OpenCV
3418 uses the values suggested in the original paper:
3419 - DIST_L1: `a = 1, b = 2`
3420 - DIST_L2:
3421 - `3 x 3`: `a=0.955, b=1.3693`
3422 - `5 x 5`: `a=1, b=1.4, c=2.1969`
3423 - DIST_C: `a = 1, b = 1`
3424
3425 Typically, for a fast, coarse distance estimation #DIST_L2, a \f$3\times 3\f$ mask is used. For a
3426 more accurate distance estimation #DIST_L2, a \f$5\times 5\f$ mask or the precise algorithm is used.
3427 Note that both the precise and the approximate algorithms are linear on the number of pixels.
3428
3429 This variant of the function does not only compute the minimum distance for each pixel \f$(x, y)\f$
3430 but also identifies the nearest connected component consisting of zero pixels
3431 (labelType==#DIST_LABEL_CCOMP) or the nearest zero pixel (labelType==#DIST_LABEL_PIXEL). Index of the
3432 component/pixel is stored in `labels(x, y)`. When labelType==#DIST_LABEL_CCOMP, the function
3433 automatically finds connected components of zero pixels in the input image and marks them with
3434 distinct labels. When labelType==#DIST_LABEL_PIXEL, the function scans through the input image and
3435 marks all the zero pixels with distinct labels.
3436
3437 In this mode, the complexity is still linear. That is, the function provides a very fast way to
3438 compute the Voronoi diagram for a binary image. Currently, the second variant can use only the
3439 approximate distance transform algorithm, i.e. maskSize=#DIST_MASK_PRECISE is not supported
3440 yet.
3441
3442 @param src 8-bit, single-channel (binary) source image.
3443 @param dst Output image with calculated distances. It is a 8-bit or 32-bit floating-point,
3444 single-channel image of the same size as src.
3445 @param labels Output 2D array of labels (the discrete Voronoi diagram). It has the type
3446 CV_32SC1 and the same size as src.
3447 @param distanceType Type of distance, see #DistanceTypes
3448 @param maskSize Size of the distance transform mask, see #DistanceTransformMasks.
3449 #DIST_MASK_PRECISE is not supported by this variant. In case of the #DIST_L1 or #DIST_C distance type,
3450 the parameter is forced to 3 because a \f$3\times 3\f$ mask gives the same result as \f$5\times
3451 5\f$ or any larger aperture.
3452 @param labelType Type of the label array to build, see #DistanceTransformLabelTypes.
3453 */
3454 CV_EXPORTS_AS(distanceTransformWithLabels) void distanceTransform( InputArray src, OutputArray dst,
3455 OutputArray labels, int distanceType, int maskSize,
3456 int labelType = DIST_LABEL_CCOMP );
3457
3458 /** @overload
3459 @param src 8-bit, single-channel (binary) source image.
3460 @param dst Output image with calculated distances. It is a 8-bit or 32-bit floating-point,
3461 single-channel image of the same size as src .
3462 @param distanceType Type of distance, see #DistanceTypes
3463 @param maskSize Size of the distance transform mask, see #DistanceTransformMasks. In case of the
3464 #DIST_L1 or #DIST_C distance type, the parameter is forced to 3 because a \f$3\times 3\f$ mask gives
3465 the same result as \f$5\times 5\f$ or any larger aperture.
3466 @param dstType Type of output image. It can be CV_8U or CV_32F. Type CV_8U can be used only for
3467 the first variant of the function and distanceType == #DIST_L1.
3468 */
3469 CV_EXPORTS_W void distanceTransform( InputArray src, OutputArray dst,
3470 int distanceType, int maskSize, int dstType=CV_32F);
3471
3472 /** @example samples/cpp/ffilldemo.cpp
3473 An example using the FloodFill technique
3474 */
3475
3476 /** @overload
3477
3478 variant without `mask` parameter
3479 */
3480 CV_EXPORTS int floodFill( InputOutputArray image,
3481 Point seedPoint, Scalar newVal, CV_OUT Rect* rect = 0,
3482 Scalar loDiff = Scalar(), Scalar upDiff = Scalar(),
3483 int flags = 4 );
3484
3485 /** @brief Fills a connected component with the given color.
3486
3487 The function cv::floodFill fills a connected component starting from the seed point with the specified
3488 color. The connectivity is determined by the color/brightness closeness of the neighbor pixels. The
3489 pixel at \f$(x,y)\f$ is considered to belong to the repainted domain if:
3490
3491 - in case of a grayscale image and floating range
3492 \f[\texttt{src} (x',y')- \texttt{loDiff} \leq \texttt{src} (x,y) \leq \texttt{src} (x',y')+ \texttt{upDiff}\f]
3493
3494
3495 - in case of a grayscale image and fixed range
3496 \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]
3497
3498
3499 - in case of a color image and floating range
3500 \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]
3501 \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 and
3503 \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]
3504
3505
3506 - in case of a color image and fixed range
3507 \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]
3508 \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 and
3510 \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]
3511
3512
3513 where \f$src(x',y')\f$ is the value of one of pixel neighbors that is already known to belong to the
3514 component. That is, to be added to the connected component, a color/brightness of the pixel should
3515 be close enough to:
3516 - Color/brightness of one of its neighbors that already belong to the connected component in case
3517 of a floating range.
3518 - Color/brightness of the seed point in case of a fixed range.
3519
3520 Use these functions to either mark a connected component with the specified color in-place, or build
3521 a mask and then extract the contour, or copy the region to another image, and so on.
3522
3523 @param image Input/output 1- or 3-channel, 8-bit, or floating-point image. It is modified by the
3524 function unless the #FLOODFILL_MASK_ONLY flag is set in the second variant of the function. See
3525 the details below.
3526 @param mask Operation mask that should be a single-channel 8-bit image, 2 pixels wider and 2 pixels
3527 taller than image. Since this is both an input and output parameter, you must take responsibility
3528 of initializing it. Flood-filling cannot go across non-zero pixels in the input mask. For example,
3529 an edge detector output can be used as a mask to stop filling at edges. On output, pixels in the
3530 mask corresponding to filled pixels in the image are set to 1 or to the a value specified in flags
3531 as described below. Additionally, the function fills the border of the mask with ones to simplify
3532 internal processing. It is therefore possible to use the same mask in multiple calls to the function
3533 to make sure the filled areas do not overlap.
3534 @param seedPoint Starting point.
3535 @param newVal New value of the repainted domain pixels.
3536 @param loDiff Maximal lower 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 upDiff Maximal upper brightness/color difference between the currently observed pixel and
3539 one of its neighbors belonging to the component, or a seed pixel being added to the component.
3540 @param rect Optional output parameter set by the function to the minimum bounding rectangle of the
3541 repainted domain.
3542 @param flags Operation flags. The first 8 bits contain a connectivity value. The default value of
3543 4 means that only the four nearest neighbor pixels (those that share an edge) are considered. A
3544 connectivity value of 8 means that the eight nearest neighbor pixels (those that share a corner)
3545 will be considered. The next 8 bits (8-16) contain a value between 1 and 255 with which to fill
3546 the mask (the default value is 1). For example, 4 | ( 255 \<\< 8 ) will consider 4 nearest
3547 neighbours and fill the mask with a value of 255. The following additional options occupy higher
3548 bits and therefore may be further combined with the connectivity and mask fill values using
3549 bit-wise or (|), see #FloodFillFlags.
3550
3551 @note Since the mask is larger than the filled image, a pixel \f$(x, y)\f$ in image corresponds to the
3552 pixel \f$(x+1, y+1)\f$ in the mask .
3553
3554 @sa findContours
3555 */
3556 CV_EXPORTS_W int floodFill( InputOutputArray image, InputOutputArray mask,
3557 Point seedPoint, Scalar newVal, CV_OUT Rect* rect=0,
3558 Scalar loDiff = Scalar(), Scalar upDiff = Scalar(),
3559 int flags = 4 );
3560
3561 //! Performs linear blending of two images:
3562 //! \f[ \texttt{dst}(i,j) = \texttt{weights1}(i,j)*\texttt{src1}(i,j) + \texttt{weights2}(i,j)*\texttt{src2}(i,j) \f]
3563 //! @param src1 It has a type of CV_8UC(n) or CV_32FC(n), where n is a positive integer.
3564 //! @param src2 It has the same type and size as src1.
3565 //! @param weights1 It has a type of CV_32FC1 and the same size with src1.
3566 //! @param weights2 It has a type of CV_32FC1 and the same size with src1.
3567 //! @param dst It is created if it does not have the same size and type with src1.
3568 CV_EXPORTS_W void blendLinear(InputArray src1, InputArray src2, InputArray weights1, InputArray weights2, OutputArray dst);
3569
3570 //! @} imgproc_misc
3571
3572 //! @addtogroup imgproc_color_conversions
3573 //! @{
3574
3575 /** @brief Converts an image from one color space to another.
3576
3577 The function converts an input image from one color space to another. In case of a transformation
3578 to-from RGB color space, the order of the channels should be specified explicitly (RGB or BGR). Note
3579 that the default color format in OpenCV is often referred to as RGB but it is actually BGR (the
3580 bytes are reversed). So the first byte in a standard (24-bit) color image will be an 8-bit Blue
3581 component, the second byte will be Green, and the third byte will be Red. The fourth, fifth, and
3582 sixth bytes would then be the second pixel (Blue, then Green, then Red), and so on.
3583
3584 The conventional ranges for R, G, and B channel values are:
3585 - 0 to 255 for CV_8U images
3586 - 0 to 65535 for CV_16U images
3587 - 0 to 1 for CV_32F images
3588
3589 In case of linear transformations, the range does not matter. But in case of a non-linear
3590 transformation, an input RGB image should be normalized to the proper value range to get the correct
3591 results, for example, for RGB \f$\rightarrow\f$ L\*u\*v\* transformation. For example, if you have a
3592 32-bit floating-point image directly converted from an 8-bit image without any scaling, then it will
3593 have the 0..255 value range instead of 0..1 assumed by the function. So, before calling #cvtColor ,
3594 you need first to scale the image down:
3595 @code
3596 img *= 1./255;
3597 cvtColor(img, img, COLOR_BGR2Luv);
3598 @endcode
3599 If you use #cvtColor with 8-bit images, the conversion will have some information lost. For many
3600 applications, this will not be noticeable but it is recommended to use 32-bit images in applications
3601 that need the full range of colors or that convert an image before an operation and then convert
3602 back.
3603
3604 If conversion adds the alpha channel, its value will set to the maximum of corresponding channel
3605 range: 255 for CV_8U, 65535 for CV_16U, 1 for CV_32F.
3606
3607 @param src input image: 8-bit unsigned, 16-bit unsigned ( CV_16UC... ), or single-precision
3608 floating-point.
3609 @param dst output image of the same size and depth as src.
3610 @param code color space conversion code (see #ColorConversionCodes).
3611 @param dstCn number of channels in the destination image; if the parameter is 0, the number of the
3612 channels is derived automatically from src and code.
3613
3614 @see @ref imgproc_color_conversions
3615 */
3616 CV_EXPORTS_W void cvtColor( InputArray src, OutputArray dst, int code, int dstCn = 0 );
3617
3618 /** @brief Converts an image from one color space to another where the source image is
3619 stored in two planes.
3620
3621 This function only supports YUV420 to RGB conversion as of now.
3622
3623 @param src1: 8-bit image (#CV_8U) of the Y plane.
3624 @param src2: image containing interleaved U/V plane.
3625 @param dst: output image.
3626 @param code: Specifies the type of conversion. It can take any of the following values:
3627 - #COLOR_YUV2BGR_NV12
3628 - #COLOR_YUV2RGB_NV12
3629 - #COLOR_YUV2BGRA_NV12
3630 - #COLOR_YUV2RGBA_NV12
3631 - #COLOR_YUV2BGR_NV21
3632 - #COLOR_YUV2RGB_NV21
3633 - #COLOR_YUV2BGRA_NV21
3634 - #COLOR_YUV2RGBA_NV21
3635 */
3636 CV_EXPORTS_W void cvtColorTwoPlane( InputArray src1, InputArray src2, OutputArray dst, int code );
3637
3638 /** @brief main function for all demosaicing processes
3639
3640 @param src input image: 8-bit unsigned or 16-bit unsigned.
3641 @param dst output image of the same size and depth as src.
3642 @param code Color space conversion code (see the description below).
3643 @param dstCn number of channels in the destination image; if the parameter is 0, the number of the
3644 channels is derived automatically from src and code.
3645
3646 The function can do the following transformations:
3647
3648 - Demosaicing using bilinear interpolation
3649
3650 #COLOR_BayerBG2BGR , #COLOR_BayerGB2BGR , #COLOR_BayerRG2BGR , #COLOR_BayerGR2BGR
3651
3652 #COLOR_BayerBG2GRAY , #COLOR_BayerGB2GRAY , #COLOR_BayerRG2GRAY , #COLOR_BayerGR2GRAY
3653
3654 - Demosaicing using Variable Number of Gradients.
3655
3656 #COLOR_BayerBG2BGR_VNG , #COLOR_BayerGB2BGR_VNG , #COLOR_BayerRG2BGR_VNG , #COLOR_BayerGR2BGR_VNG
3657
3658 - Edge-Aware Demosaicing.
3659
3660 #COLOR_BayerBG2BGR_EA , #COLOR_BayerGB2BGR_EA , #COLOR_BayerRG2BGR_EA , #COLOR_BayerGR2BGR_EA
3661
3662 - Demosaicing with alpha channel
3663
3664 #COLOR_BayerBG2BGRA , #COLOR_BayerGB2BGRA , #COLOR_BayerRG2BGRA , #COLOR_BayerGR2BGRA
3665
3666 @sa cvtColor
3667 */
3668 CV_EXPORTS_W void demosaicing(InputArray src, OutputArray dst, int code, int dstCn = 0);
3669
3670 //! @} imgproc_color_conversions
3671
3672 //! @addtogroup imgproc_shape
3673 //! @{
3674
3675 /** @brief Calculates all of the moments up to the third order of a polygon or rasterized shape.
3676
3677 The function computes moments, up to the 3rd order, of a vector shape or a rasterized shape. The
3678 results are returned in the structure cv::Moments.
3679
3680 @param array Raster image (single-channel, 8-bit or floating-point 2D array) or an array (
3681 \f$1 \times N\f$ or \f$N \times 1\f$ ) of 2D points (Point or Point2f ).
3682 @param binaryImage If it is true, all non-zero image pixels are treated as 1's. The parameter is
3683 used for images only.
3684 @returns moments.
3685
3686 @note Only applicable to contour moments calculations from Python bindings: Note that the numpy
3687 type for the input array should be either np.int32 or np.float32.
3688
3689 @sa contourArea, arcLength
3690 */
3691 CV_EXPORTS_W Moments moments( InputArray array, bool binaryImage = false );
3692
3693 /** @brief Calculates seven Hu invariants.
3694
3695 The function calculates seven Hu invariants (introduced in @cite Hu62; see also
3696 <http://en.wikipedia.org/wiki/Image_moment>) defined as:
3697
3698 \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]
3699
3700 where \f$\eta_{ji}\f$ stands for \f$\texttt{Moments::nu}_{ji}\f$ .
3701
3702 These values are proved to be invariants to the image scale, rotation, and reflection except the
3703 seventh one, whose sign is changed by reflection. This invariance is proved with the assumption of
3704 infinite image resolution. In case of raster images, the computed Hu invariants for the original and
3705 transformed images are a bit different.
3706
3707 @param moments Input moments computed with moments .
3708 @param hu Output Hu invariants.
3709
3710 @sa matchShapes
3711 */
3712 CV_EXPORTS void HuMoments( const Moments& moments, double hu[7] );
3713
3714 /** @overload */
3715 CV_EXPORTS_W void HuMoments( const Moments& m, OutputArray hu );
3716
3717 //! @} imgproc_shape
3718
3719 //! @addtogroup imgproc_object
3720 //! @{
3721
3722 //! type of the template matching operation
3723 enum TemplateMatchModes {
3724 TM_SQDIFF = 0, /*!< \f[R(x,y)= \sum _{x',y'} (T(x',y')-I(x+x',y+y'))^2\f]
3725 with mask:
3726 \f[R(x,y)= \sum _{x',y'} \left( (T(x',y')-I(x+x',y+y')) \cdot
3727 M(x',y') \right)^2\f] */
3728 TM_SQDIFF_NORMED = 1, /*!< \f[R(x,y)= \frac{\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2}{\sqrt{\sum_{
3729 x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}\f]
3730 with mask:
3731 \f[R(x,y)= \frac{\sum _{x',y'} \left( (T(x',y')-I(x+x',y+y')) \cdot
3732 M(x',y') \right)^2}{\sqrt{\sum_{x',y'} \left( T(x',y') \cdot
3733 M(x',y') \right)^2 \cdot \sum_{x',y'} \left( I(x+x',y+y') \cdot
3734 M(x',y') \right)^2}}\f] */
3735 TM_CCORR = 2, /*!< \f[R(x,y)= \sum _{x',y'} (T(x',y') \cdot I(x+x',y+y'))\f]
3736 with mask:
3737 \f[R(x,y)= \sum _{x',y'} (T(x',y') \cdot I(x+x',y+y') \cdot M(x',y')
3738 ^2)\f] */
3739 TM_CCORR_NORMED = 3, /*!< \f[R(x,y)= \frac{\sum_{x',y'} (T(x',y') \cdot I(x+x',y+y'))}{\sqrt{
3740 \sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}\f]
3741 with mask:
3742 \f[R(x,y)= \frac{\sum_{x',y'} (T(x',y') \cdot I(x+x',y+y') \cdot
3743 M(x',y')^2)}{\sqrt{\sum_{x',y'} \left( T(x',y') \cdot M(x',y')
3744 \right)^2 \cdot \sum_{x',y'} \left( I(x+x',y+y') \cdot M(x',y')
3745 \right)^2}}\f] */
3746 TM_CCOEFF = 4, /*!< \f[R(x,y)= \sum _{x',y'} (T'(x',y') \cdot I'(x+x',y+y'))\f]
3747 where
3748 \f[\begin{array}{l} T'(x',y')=T(x',y') - 1/(w \cdot h) \cdot \sum _{
3749 x'',y''} T(x'',y'') \\ I'(x+x',y+y')=I(x+x',y+y') - 1/(w \cdot h)
3750 \cdot \sum _{x'',y''} I(x+x'',y+y'') \end{array}\f]
3751 with mask:
3752 \f[\begin{array}{l} T'(x',y')=M(x',y') \cdot \left( T(x',y') -
3753 \frac{1}{\sum _{x'',y''} M(x'',y'')} \cdot \sum _{x'',y''}
3754 (T(x'',y'') \cdot M(x'',y'')) \right) \\ I'(x+x',y+y')=M(x',y')
3755 \cdot \left( I(x+x',y+y') - \frac{1}{\sum _{x'',y''} M(x'',y'')}
3756 \cdot \sum _{x'',y''} (I(x+x'',y+y'') \cdot M(x'',y'')) \right)
3757 \end{array} \f] */
3758 TM_CCOEFF_NORMED = 5 /*!< \f[R(x,y)= \frac{ \sum_{x',y'} (T'(x',y') \cdot I'(x+x',y+y')) }{
3759 \sqrt{\sum_{x',y'}T'(x',y')^2 \cdot \sum_{x',y'} I'(x+x',y+y')^2}
3760 }\f] */
3761 };
3762
3763 /** @example samples/cpp/tutorial_code/Histograms_Matching/MatchTemplate_Demo.cpp
3764 An example using Template Matching algorithm
3765 */
3766
3767 /** @brief Compares a template against overlapped image regions.
3768
3769 The function slides through image , compares the overlapped patches of size \f$w \times h\f$ against
3770 templ using the specified method and stores the comparison results in result . #TemplateMatchModes
3771 describes the formulae for the available comparison methods ( \f$I\f$ denotes image, \f$T\f$
3772 template, \f$R\f$ result, \f$M\f$ the optional mask ). The summation is done over template and/or
3773 the image patch: \f$x' = 0...w-1, y' = 0...h-1\f$
3774
3775 After the function finishes the comparison, the best matches can be found as global minimums (when
3776 #TM_SQDIFF was used) or maximums (when #TM_CCORR or #TM_CCOEFF was used) using the
3777 #minMaxLoc function. In case of a color image, template summation in the numerator and each sum in
3778 the denominator is done over all of the channels and separate mean values are used for each channel.
3779 That is, the function can take a color template and a color image. The result will still be a
3780 single-channel image, which is easier to analyze.
3781
3782 @param image Image where the search is running. It must be 8-bit or 32-bit floating-point.
3783 @param templ Searched template. It must be not greater than the source image and have the same
3784 data type.
3785 @param result Map of comparison results. It must be single-channel 32-bit floating-point. If image
3786 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$ .
3787 @param method Parameter specifying the comparison method, see #TemplateMatchModes
3788 @param mask Optional mask. It must have the same size as templ. It must either have the same number
3789 of channels as template or only one channel, which is then used for all template and
3790 image channels. If the data type is #CV_8U, the mask is interpreted as a binary mask,
3791 meaning only elements where mask is nonzero are used and are kept unchanged independent
3792 of the actual mask value (weight equals 1). For data tpye #CV_32F, the mask values are
3793 used as weights. The exact formulas are documented in #TemplateMatchModes.
3794 */
3795 CV_EXPORTS_W void matchTemplate( InputArray image, InputArray templ,
3796 OutputArray result, int method, InputArray mask = noArray() );
3797
3798 //! @}
3799
3800 //! @addtogroup imgproc_shape
3801 //! @{
3802
3803 /** @example samples/cpp/connected_components.cpp
3804 This program demonstrates connected components and use of the trackbar
3805 */
3806
3807 /** @brief computes the connected components labeled image of boolean image
3808
3809 image with 4 or 8 way connectivity - returns N, the total number of labels [0, N-1] where 0
3810 represents the background label. ltype specifies the output label image type, an important
3811 consideration based on the total number of labels or alternatively the total number of pixels in
3812 the source image. ccltype specifies the connected components labeling algorithm to use, currently
3813 Grana (BBDT) and Wu's (SAUF) @cite Wu2009 algorithms are supported, see the #ConnectedComponentsAlgorithmsTypes
3814 for details. Note that SAUF algorithm forces a row major ordering of labels while BBDT does not.
3815 This function uses parallel version of both Grana and Wu's algorithms if at least one allowed
3816 parallel framework is enabled and if the rows of the image are at least twice the number returned by #getNumberOfCPUs.
3817
3818 @param image the 8-bit single-channel image to be labeled
3819 @param labels destination labeled image
3820 @param connectivity 8 or 4 for 8-way or 4-way connectivity respectively
3821 @param ltype output image label type. Currently CV_32S and CV_16U are supported.
3822 @param ccltype connected components algorithm type (see the #ConnectedComponentsAlgorithmsTypes).
3823 */
3824 CV_EXPORTS_AS(connectedComponentsWithAlgorithm) int connectedComponents(InputArray image, OutputArray labels,
3825 int connectivity, int ltype, int ccltype);
3826
3827
3828 /** @overload
3829
3830 @param image the 8-bit single-channel image to be labeled
3831 @param labels destination labeled image
3832 @param connectivity 8 or 4 for 8-way or 4-way connectivity respectively
3833 @param ltype output image label type. Currently CV_32S and CV_16U are supported.
3834 */
3835 CV_EXPORTS_W int connectedComponents(InputArray image, OutputArray labels,
3836 int connectivity = 8, int ltype = CV_32S);
3837
3838
3839 /** @brief computes the connected components labeled image of boolean image and also produces a statistics output for each label
3840
3841 image with 4 or 8 way connectivity - returns N, the total number of labels [0, N-1] where 0
3842 represents the background label. ltype specifies the output label image type, an important
3843 consideration based on the total number of labels or alternatively the total number of pixels in
3844 the source image. ccltype specifies the connected components labeling algorithm to use, currently
3845 Grana's (BBDT) and Wu's (SAUF) @cite Wu2009 algorithms are supported, see the #ConnectedComponentsAlgorithmsTypes
3846 for details. Note that SAUF algorithm forces a row major ordering of labels while BBDT does not.
3847 This function uses parallel version of both Grana and Wu's algorithms (statistics included) if at least one allowed
3848 parallel framework is enabled and if the rows of the image are at least twice the number returned by #getNumberOfCPUs.
3849
3850 @param image the 8-bit single-channel image to be labeled
3851 @param labels destination labeled image
3852 @param stats statistics output for each label, including the background label.
3853 Statistics are accessed via stats(label, COLUMN) where COLUMN is one of
3854 #ConnectedComponentsTypes, selecting the statistic. The data type is CV_32S.
3855 @param centroids centroid output for each label, including the background label. Centroids are
3856 accessed via centroids(label, 0) for x and centroids(label, 1) for y. The data type CV_64F.
3857 @param connectivity 8 or 4 for 8-way or 4-way connectivity respectively
3858 @param ltype output image label type. Currently CV_32S and CV_16U are supported.
3859 @param ccltype connected components algorithm type (see #ConnectedComponentsAlgorithmsTypes).
3860 */
3861 CV_EXPORTS_AS(connectedComponentsWithStatsWithAlgorithm) int connectedComponentsWithStats(InputArray image, OutputArray labels,
3862 OutputArray stats, OutputArray centroids,
3863 int connectivity, int ltype, int ccltype);
3864
3865 /** @overload
3866 @param image the 8-bit single-channel image to be labeled
3867 @param labels destination labeled image
3868 @param stats statistics output for each label, including the background label.
3869 Statistics are accessed via stats(label, COLUMN) where COLUMN is one of
3870 #ConnectedComponentsTypes, selecting the statistic. The data type is CV_32S.
3871 @param centroids centroid output for each label, including the background label. Centroids are
3872 accessed via centroids(label, 0) for x and centroids(label, 1) for y. The data type CV_64F.
3873 @param connectivity 8 or 4 for 8-way or 4-way connectivity respectively
3874 @param ltype output image label type. Currently CV_32S and CV_16U are supported.
3875 */
3876 CV_EXPORTS_W int connectedComponentsWithStats(InputArray image, OutputArray labels,
3877 OutputArray stats, OutputArray centroids,
3878 int connectivity = 8, int ltype = CV_32S);
3879
3880
3881 /** @brief Finds contours in a binary image.
3882
3883 The function retrieves contours from the binary image using the algorithm @cite Suzuki85 . The contours
3884 are a useful tool for shape analysis and object detection and recognition. See squares.cpp in the
3885 OpenCV sample directory.
3886 @note Since opencv 3.2 source image is not modified by this function.
3887
3888 @param image Source, an 8-bit single-channel image. Non-zero pixels are treated as 1's. Zero
3889 pixels remain 0's, so the image is treated as binary . You can use #compare, #inRange, #threshold ,
3890 #adaptiveThreshold, #Canny, and others to create a binary image out of a grayscale or color one.
3891 If mode equals to #RETR_CCOMP or #RETR_FLOODFILL, the input can also be a 32-bit integer image of labels (CV_32SC1).
3892 @param contours Detected contours. Each contour is stored as a vector of points (e.g.
3893 std::vector<std::vector<cv::Point> >).
3894 @param hierarchy Optional output vector (e.g. std::vector<cv::Vec4i>), containing information about the image topology. It has
3895 as many elements as the number of contours. For each i-th contour contours[i], the elements
3896 hierarchy[i][0] , hierarchy[i][1] , hierarchy[i][2] , and hierarchy[i][3] are set to 0-based indices
3897 in contours of the next and previous contours at the same hierarchical level, the first child
3898 contour and the parent contour, respectively. If for the contour i there are no next, previous,
3899 parent, or nested contours, the corresponding elements of hierarchy[i] will be negative.
3900 @param mode Contour retrieval mode, see #RetrievalModes
3901 @param method Contour approximation method, see #ContourApproximationModes
3902 @param offset Optional offset by which every contour point is shifted. This is useful if the
3903 contours are extracted from the image ROI and then they should be analyzed in the whole image
3904 context.
3905 */
3906 CV_EXPORTS_W void findContours( InputArray image, OutputArrayOfArrays contours,
3907 OutputArray hierarchy, int mode,
3908 int method, Point offset = Point());
3909
3910 /** @overload */
3911 CV_EXPORTS void findContours( InputArray image, OutputArrayOfArrays contours,
3912 int mode, int method, Point offset = Point());
3913
3914 /** @example samples/cpp/squares.cpp
3915 A program using pyramid scaling, Canny, contours and contour simplification to find
3916 squares in a list of images (pic1-6.png). Returns sequence of squares detected on the image.
3917 */
3918
3919 /** @example samples/tapi/squares.cpp
3920 A program using pyramid scaling, Canny, contours and contour simplification to find
3921 squares in the input image.
3922 */
3923
3924 /** @brief Approximates a polygonal curve(s) with the specified precision.
3925
3926 The function cv::approxPolyDP approximates a curve or a polygon with another curve/polygon with less
3927 vertices so that the distance between them is less or equal to the specified precision. It uses the
3928 Douglas-Peucker algorithm <http://en.wikipedia.org/wiki/Ramer-Douglas-Peucker_algorithm>
3929
3930 @param curve Input vector of a 2D point stored in std::vector or Mat
3931 @param approxCurve Result of the approximation. The type should match the type of the input curve.
3932 @param epsilon Parameter specifying the approximation accuracy. This is the maximum distance
3933 between the original curve and its approximation.
3934 @param closed If true, the approximated curve is closed (its first and last vertices are
3935 connected). Otherwise, it is not closed.
3936 */
3937 CV_EXPORTS_W void approxPolyDP( InputArray curve,
3938 OutputArray approxCurve,
3939 double epsilon, bool closed );
3940
3941 /** @brief Calculates a contour perimeter or a curve length.
3942
3943 The function computes a curve length or a closed contour perimeter.
3944
3945 @param curve Input vector of 2D points, stored in std::vector or Mat.
3946 @param closed Flag indicating whether the curve is closed or not.
3947 */
3948 CV_EXPORTS_W double arcLength( InputArray curve, bool closed );
3949
3950 /** @brief Calculates the up-right bounding rectangle of a point set or non-zero pixels of gray-scale image.
3951
3952 The function calculates and returns the minimal up-right bounding rectangle for the specified point set or
3953 non-zero pixels of gray-scale image.
3954
3955 @param array Input gray-scale image or 2D point set, stored in std::vector or Mat.
3956 */
3957 CV_EXPORTS_W Rect boundingRect( InputArray array );
3958
3959 /** @brief Calculates a contour area.
3960
3961 The function computes a contour area. Similarly to moments , the area is computed using the Green
3962 formula. Thus, the returned area and the number of non-zero pixels, if you draw the contour using
3963 #drawContours or #fillPoly , can be different. Also, the function will most certainly give a wrong
3964 results for contours with self-intersections.
3965
3966 Example:
3967 @code
3968 vector<Point> contour;
3969 contour.push_back(Point2f(0, 0));
3970 contour.push_back(Point2f(10, 0));
3971 contour.push_back(Point2f(10, 10));
3972 contour.push_back(Point2f(5, 4));
3973
3974 double area0 = contourArea(contour);
3975 vector<Point> approx;
3976 approxPolyDP(contour, approx, 5, true);
3977 double area1 = contourArea(approx);
3978
3979 cout << "area0 =" << area0 << endl <<
3980 "area1 =" << area1 << endl <<
3981 "approx poly vertices" << approx.size() << endl;
3982 @endcode
3983 @param contour Input vector of 2D points (contour vertices), stored in std::vector or Mat.
3984 @param oriented Oriented area flag. If it is true, the function returns a signed area value,
3985 depending on the contour orientation (clockwise or counter-clockwise). Using this feature you can
3986 determine orientation of a contour by taking the sign of an area. By default, the parameter is
3987 false, which means that the absolute value is returned.
3988 */
3989 CV_EXPORTS_W double contourArea( InputArray contour, bool oriented = false );
3990
3991 /** @brief Finds a rotated rectangle of the minimum area enclosing the input 2D point set.
3992
3993 The function calculates and returns the minimum-area bounding rectangle (possibly rotated) for a
3994 specified point set. Developer should keep in mind that the returned RotatedRect can contain negative
3995 indices when data is close to the containing Mat element boundary.
3996
3997 @param points Input vector of 2D points, stored in std::vector\<\> or Mat
3998 */
3999 CV_EXPORTS_W RotatedRect minAreaRect( InputArray points );
4000
4001 /** @brief Finds the four vertices of a rotated rect. Useful to draw the rotated rectangle.
4002
4003 The function finds the four vertices of a rotated rectangle. This function is useful to draw the
4004 rectangle. In C++, instead of using this function, you can directly use RotatedRect::points method. Please
4005 visit the @ref tutorial_bounding_rotated_ellipses "tutorial on Creating Bounding rotated boxes and ellipses for contours" for more information.
4006
4007 @param box The input rotated rectangle. It may be the output of
4008 @param points The output array of four vertices of rectangles.
4009 */
4010 CV_EXPORTS_W void boxPoints(RotatedRect box, OutputArray points);
4011
4012 /** @brief Finds a circle of the minimum area enclosing a 2D point set.
4013
4014 The function finds the minimal enclosing circle of a 2D point set using an iterative algorithm.
4015
4016 @param points Input vector of 2D points, stored in std::vector\<\> or Mat
4017 @param center Output center of the circle.
4018 @param radius Output radius of the circle.
4019 */
4020 CV_EXPORTS_W void minEnclosingCircle( InputArray points,
4021 CV_OUT Point2f& center, CV_OUT float& radius );
4022
4023 /** @example samples/cpp/minarea.cpp
4024 */
4025
4026 /** @brief Finds a triangle of minimum area enclosing a 2D point set and returns its area.
4027
4028 The function finds a triangle of minimum area enclosing the given set of 2D points and returns its
4029 area. The output for a given 2D point set is shown in the image below. 2D points are depicted in
4030 *red* and the enclosing triangle in *yellow*.
4031
4032 ![Sample output of the minimum enclosing triangle function](pics/minenclosingtriangle.png)
4033
4034 The implementation of the algorithm is based on O'Rourke's @cite ORourke86 and Klee and Laskowski's
4035 @cite KleeLaskowski85 papers. O'Rourke provides a \f$\theta(n)\f$ algorithm for finding the minimal
4036 enclosing triangle of a 2D convex polygon with n vertices. Since the #minEnclosingTriangle function
4037 takes a 2D point set as input an additional preprocessing step of computing the convex hull of the
4038 2D point set is required. The complexity of the #convexHull function is \f$O(n log(n))\f$ which is higher
4039 than \f$\theta(n)\f$. Thus the overall complexity of the function is \f$O(n log(n))\f$.
4040
4041 @param points Input vector of 2D points with depth CV_32S or CV_32F, stored in std::vector\<\> or Mat
4042 @param triangle Output vector of three 2D points defining the vertices of the triangle. The depth
4043 of the OutputArray must be CV_32F.
4044 */
4045 CV_EXPORTS_W double minEnclosingTriangle( InputArray points, CV_OUT OutputArray triangle );
4046
4047 /** @brief Compares two shapes.
4048
4049 The function compares two shapes. All three implemented methods use the Hu invariants (see #HuMoments)
4050
4051 @param contour1 First contour or grayscale image.
4052 @param contour2 Second contour or grayscale image.
4053 @param method Comparison method, see #ShapeMatchModes
4054 @param parameter Method-specific parameter (not supported now).
4055 */
4056 CV_EXPORTS_W double matchShapes( InputArray contour1, InputArray contour2,
4057 int method, double parameter );
4058
4059 /** @example samples/cpp/convexhull.cpp
4060 An example using the convexHull functionality
4061 */
4062
4063 /** @brief Finds the convex hull of a point set.
4064
4065 The function cv::convexHull finds the convex hull of a 2D point set using the Sklansky's algorithm @cite Sklansky82
4066 that has *O(N logN)* complexity in the current implementation.
4067
4068 @param points Input 2D point set, stored in std::vector or Mat.
4069 @param hull Output convex hull. It is either an integer vector of indices or vector of points. In
4070 the first case, the hull elements are 0-based indices of the convex hull points in the original
4071 array (since the set of convex hull points is a subset of the original point set). In the second
4072 case, hull elements are the convex hull points themselves.
4073 @param clockwise Orientation flag. If it is true, the output convex hull is oriented clockwise.
4074 Otherwise, it is oriented counter-clockwise. The assumed coordinate system has its X axis pointing
4075 to the right, and its Y axis pointing upwards.
4076 @param returnPoints Operation flag. In case of a matrix, when the flag is true, the function
4077 returns convex hull points. Otherwise, it returns indices of the convex hull points. When the
4078 output array is std::vector, the flag is ignored, and the output depends on the type of the
4079 vector: std::vector\<int\> implies returnPoints=false, std::vector\<Point\> implies
4080 returnPoints=true.
4081
4082 @note `points` and `hull` should be different arrays, inplace processing isn't supported.
4083
4084 Check @ref tutorial_hull "the corresponding tutorial" for more details.
4085
4086 useful links:
4087
4088 https://www.learnopencv.com/convex-hull-using-opencv-in-python-and-c/
4089 */
4090 CV_EXPORTS_W void convexHull( InputArray points, OutputArray hull,
4091 bool clockwise = false, bool returnPoints = true );
4092
4093 /** @brief Finds the convexity defects of a contour.
4094
4095 The figure below displays convexity defects of a hand contour:
4096
4097 ![image](pics/defects.png)
4098
4099 @param contour Input contour.
4100 @param convexhull Convex hull obtained using convexHull that should contain indices of the contour
4101 points that make the hull.
4102 @param convexityDefects The output vector of convexity defects. In C++ and the new Python/Java
4103 interface each convexity defect is represented as 4-element integer vector (a.k.a. #Vec4i):
4104 (start_index, end_index, farthest_pt_index, fixpt_depth), where indices are 0-based indices
4105 in the original contour of the convexity defect beginning, end and the farthest point, and
4106 fixpt_depth is fixed-point approximation (with 8 fractional bits) of the distance between the
4107 farthest contour point and the hull. That is, to get the floating-point value of the depth will be
4108 fixpt_depth/256.0.
4109 */
4110 CV_EXPORTS_W void convexityDefects( InputArray contour, InputArray convexhull, OutputArray convexityDefects );
4111
4112 /** @brief Tests a contour convexity.
4113
4114 The function tests whether the input contour is convex or not. The contour must be simple, that is,
4115 without self-intersections. Otherwise, the function output is undefined.
4116
4117 @param contour Input vector of 2D points, stored in std::vector\<\> or Mat
4118 */
4119 CV_EXPORTS_W bool isContourConvex( InputArray contour );
4120
4121 /** @example samples/cpp/intersectExample.cpp
4122 Examples of how intersectConvexConvex works
4123 */
4124
4125 /** @brief Finds intersection of two convex polygons
4126
4127 @param p1 First polygon
4128 @param p2 Second polygon
4129 @param p12 Output polygon describing the intersecting area
4130 @param handleNested When true, an intersection is found if one of the polygons is fully enclosed in the other.
4131 When false, no intersection is found. If the polygons share a side or the vertex of one polygon lies on an edge
4132 of the other, they are not considered nested and an intersection will be found regardless of the value of handleNested.
4133
4134 @returns Absolute value of area of intersecting polygon
4135
4136 @note intersectConvexConvex doesn't confirm that both polygons are convex and will return invalid results if they aren't.
4137 */
4138 CV_EXPORTS_W float intersectConvexConvex( InputArray p1, InputArray p2,
4139 OutputArray p12, bool handleNested = true );
4140
4141 /** @example samples/cpp/fitellipse.cpp
4142 An example using the fitEllipse technique
4143 */
4144
4145 /** @brief Fits an ellipse around a set of 2D points.
4146
4147 The function calculates the ellipse that fits (in a least-squares sense) a set of 2D points best of
4148 all. It returns the rotated rectangle in which the ellipse is inscribed. The first algorithm described by @cite Fitzgibbon95
4149 is used. Developer should keep in mind that it is possible that the returned
4150 ellipse/rotatedRect data contains negative indices, due to the data points being close to the
4151 border of the containing Mat element.
4152
4153 @param points Input 2D point set, stored in std::vector\<\> or Mat
4154 */
4155 CV_EXPORTS_W RotatedRect fitEllipse( InputArray points );
4156
4157 /** @brief Fits an ellipse around a set of 2D points.
4158
4159 The function calculates the ellipse that fits a set of 2D points.
4160 It returns the rotated rectangle in which the ellipse is inscribed.
4161 The Approximate Mean Square (AMS) proposed by @cite Taubin1991 is used.
4162
4163 For an ellipse, this basis set is \f$ \chi= \left(x^2, x y, y^2, x, y, 1\right) \f$,
4164 which is a set of six free coefficients \f$ A^T=\left\{A_{\text{xx}},A_{\text{xy}},A_{\text{yy}},A_x,A_y,A_0\right\} \f$.
4165 However, to specify an ellipse, all that is needed is five numbers; the major and minor axes lengths \f$ (a,b) \f$,
4166 the position \f$ (x_0,y_0) \f$, and the orientation \f$ \theta \f$. This is because the basis set includes lines,
4167 quadratics, parabolic and hyperbolic functions as well as elliptical functions as possible fits.
4168 If the fit is found to be a parabolic or hyperbolic function then the standard #fitEllipse method is used.
4169 The AMS method restricts the fit to parabolic, hyperbolic and elliptical curves
4170 by imposing the condition that \f$ A^T ( D_x^T D_x + D_y^T D_y) A = 1 \f$ where
4171 the matrices \f$ Dx \f$ and \f$ Dy \f$ are the partial derivatives of the design matrix \f$ D \f$ with
4172 respect to x and y. The matrices are formed row by row applying the following to
4173 each of the points in the set:
4174 \f{align*}{
4175 D(i,:)&=\left\{x_i^2, x_i y_i, y_i^2, x_i, y_i, 1\right\} &
4176 D_x(i,:)&=\left\{2 x_i,y_i,0,1,0,0\right\} &
4177 D_y(i,:)&=\left\{0,x_i,2 y_i,0,1,0\right\}
4178 \f}
4179 The AMS method minimizes the cost function
4180 \f{equation*}{
4181 \epsilon ^2=\frac{ A^T D^T D A }{ A^T (D_x^T D_x + D_y^T D_y) A^T }
4182 \f}
4183
4184 The minimum cost is found by solving the generalized eigenvalue problem.
4185
4186 \f{equation*}{
4187 D^T D A = \lambda \left( D_x^T D_x + D_y^T D_y\right) A
4188 \f}
4189
4190 @param points Input 2D point set, stored in std::vector\<\> or Mat
4191 */
4192 CV_EXPORTS_W RotatedRect fitEllipseAMS( InputArray points );
4193
4194
4195 /** @brief Fits an ellipse around a set of 2D points.
4196
4197 The function calculates the ellipse that fits a set of 2D points.
4198 It returns the rotated rectangle in which the ellipse is inscribed.
4199 The Direct least square (Direct) method by @cite Fitzgibbon1999 is used.
4200
4201 For an ellipse, this basis set is \f$ \chi= \left(x^2, x y, y^2, x, y, 1\right) \f$,
4202 which is a set of six free coefficients \f$ A^T=\left\{A_{\text{xx}},A_{\text{xy}},A_{\text{yy}},A_x,A_y,A_0\right\} \f$.
4203 However, to specify an ellipse, all that is needed is five numbers; the major and minor axes lengths \f$ (a,b) \f$,
4204 the position \f$ (x_0,y_0) \f$, and the orientation \f$ \theta \f$. This is because the basis set includes lines,
4205 quadratics, parabolic and hyperbolic functions as well as elliptical functions as possible fits.
4206 The Direct method confines the fit to ellipses by ensuring that \f$ 4 A_{xx} A_{yy}- A_{xy}^2 > 0 \f$.
4207 The condition imposed is that \f$ 4 A_{xx} A_{yy}- A_{xy}^2=1 \f$ which satisfies the inequality
4208 and as the coefficients can be arbitrarily scaled is not overly restrictive.
4209
4210 \f{equation*}{
4211 \epsilon ^2= A^T D^T D A \quad \text{with} \quad A^T C A =1 \quad \text{and} \quad C=\left(\begin{matrix}
4212 0 & 0 & 2 & 0 & 0 & 0 \\
4213 0 & -1 & 0 & 0 & 0 & 0 \\
4214 2 & 0 & 0 & 0 & 0 & 0 \\
4215 0 & 0 & 0 & 0 & 0 & 0 \\
4216 0 & 0 & 0 & 0 & 0 & 0 \\
4217 0 & 0 & 0 & 0 & 0 & 0
4218 \end{matrix} \right)
4219 \f}
4220
4221 The minimum cost is found by solving the generalized eigenvalue problem.
4222
4223 \f{equation*}{
4224 D^T D A = \lambda \left( C\right) A
4225 \f}
4226
4227 The system produces only one positive eigenvalue \f$ \lambda\f$ which is chosen as the solution
4228 with its eigenvector \f$\mathbf{u}\f$. These are used to find the coefficients
4229
4230 \f{equation*}{
4231 A = \sqrt{\frac{1}{\mathbf{u}^T C \mathbf{u}}} \mathbf{u}
4232 \f}
4233 The scaling factor guarantees that \f$A^T C A =1\f$.
4234
4235 @param points Input 2D point set, stored in std::vector\<\> or Mat
4236 */
4237 CV_EXPORTS_W RotatedRect fitEllipseDirect( InputArray points );
4238
4239 /** @brief Fits a line to a 2D or 3D point set.
4240
4241 The function fitLine fits a line to a 2D or 3D point set by minimizing \f$\sum_i \rho(r_i)\f$ where
4242 \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
4243 of the following:
4244 - DIST_L2
4245 \f[\rho (r) = r^2/2 \quad \text{(the simplest and the fastest least-squares method)}\f]
4246 - DIST_L1
4247 \f[\rho (r) = r\f]
4248 - DIST_L12
4249 \f[\rho (r) = 2 \cdot ( \sqrt{1 + \frac{r^2}{2}} - 1)\f]
4250 - DIST_FAIR
4251 \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]
4252 - DIST_WELSCH
4253 \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]
4254 - DIST_HUBER
4255 \f[\rho (r) = \fork{r^2/2}{if \(r < C\)}{C \cdot (r-C/2)}{otherwise} \quad \text{where} \quad C=1.345\f]
4256
4257 The algorithm is based on the M-estimator ( <http://en.wikipedia.org/wiki/M-estimator> ) technique
4258 that iteratively fits the line using the weighted least-squares algorithm. After each iteration the
4259 weights \f$w_i\f$ are adjusted to be inversely proportional to \f$\rho(r_i)\f$ .
4260
4261 @param points Input vector of 2D or 3D points, stored in std::vector\<\> or Mat.
4262 @param line Output line parameters. In case of 2D fitting, it should be a vector of 4 elements
4263 (like Vec4f) - (vx, vy, x0, y0), where (vx, vy) is a normalized vector collinear to the line and
4264 (x0, y0) is a point on the line. In case of 3D fitting, it should be a vector of 6 elements (like
4265 Vec6f) - (vx, vy, vz, x0, y0, z0), where (vx, vy, vz) is a normalized vector collinear to the line
4266 and (x0, y0, z0) is a point on the line.
4267 @param distType Distance used by the M-estimator, see #DistanceTypes
4268 @param param Numerical parameter ( C ) for some types of distances. If it is 0, an optimal value
4269 is chosen.
4270 @param reps Sufficient accuracy for the radius (distance between the coordinate origin and the line).
4271 @param aeps Sufficient accuracy for the angle. 0.01 would be a good default value for reps and aeps.
4272 */
4273 CV_EXPORTS_W void fitLine( InputArray points, OutputArray line, int distType,
4274 double param, double reps, double aeps );
4275
4276 /** @brief Performs a point-in-contour test.
4277
4278 The function determines whether the point is inside a contour, outside, or lies on an edge (or
4279 coincides with a vertex). It returns positive (inside), negative (outside), or zero (on an edge)
4280 value, correspondingly. When measureDist=false , the return value is +1, -1, and 0, respectively.
4281 Otherwise, the return value is a signed distance between the point and the nearest contour edge.
4282
4283 See below a sample output of the function where each image pixel is tested against the contour:
4284
4285 ![sample output](pics/pointpolygon.png)
4286
4287 @param contour Input contour.
4288 @param pt Point tested against the contour.
4289 @param measureDist If true, the function estimates the signed distance from the point to the
4290 nearest contour edge. Otherwise, the function only checks if the point is inside a contour or not.
4291 */
4292 CV_EXPORTS_W double pointPolygonTest( InputArray contour, Point2f pt, bool measureDist );
4293
4294 /** @brief Finds out if there is any intersection between two rotated rectangles.
4295
4296 If there is then the vertices of the intersecting region are returned as well.
4297
4298 Below are some examples of intersection configurations. The hatched pattern indicates the
4299 intersecting region and the red vertices are returned by the function.
4300
4301 ![intersection examples](pics/intersection.png)
4302
4303 @param rect1 First rectangle
4304 @param rect2 Second rectangle
4305 @param intersectingRegion The output array of the vertices of the intersecting region. It returns
4306 at most 8 vertices. Stored as std::vector\<cv::Point2f\> or cv::Mat as Mx1 of type CV_32FC2.
4307 @returns One of #RectanglesIntersectTypes
4308 */
4309 CV_EXPORTS_W int rotatedRectangleIntersection( const RotatedRect& rect1, const RotatedRect& rect2, OutputArray intersectingRegion );
4310
4311 /** @brief Creates a smart pointer to a cv::GeneralizedHoughBallard class and initializes it.
4312 */
4313 CV_EXPORTS_W Ptr<GeneralizedHoughBallard> createGeneralizedHoughBallard();
4314
4315 /** @brief Creates a smart pointer to a cv::GeneralizedHoughGuil class and initializes it.
4316 */
4317 CV_EXPORTS_W Ptr<GeneralizedHoughGuil> createGeneralizedHoughGuil();
4318
4319 //! @} imgproc_shape
4320
4321 //! @addtogroup imgproc_colormap
4322 //! @{
4323
4324 //! GNU Octave/MATLAB equivalent colormaps
4325 enum ColormapTypes
4326 {
4327 COLORMAP_AUTUMN = 0, //!< ![autumn](pics/colormaps/colorscale_autumn.jpg)
4328 COLORMAP_BONE = 1, //!< ![bone](pics/colormaps/colorscale_bone.jpg)
4329 COLORMAP_JET = 2, //!< ![jet](pics/colormaps/colorscale_jet.jpg)
4330 COLORMAP_WINTER = 3, //!< ![winter](pics/colormaps/colorscale_winter.jpg)
4331 COLORMAP_RAINBOW = 4, //!< ![rainbow](pics/colormaps/colorscale_rainbow.jpg)
4332 COLORMAP_OCEAN = 5, //!< ![ocean](pics/colormaps/colorscale_ocean.jpg)
4333 COLORMAP_SUMMER = 6, //!< ![summer](pics/colormaps/colorscale_summer.jpg)
4334 COLORMAP_SPRING = 7, //!< ![spring](pics/colormaps/colorscale_spring.jpg)
4335 COLORMAP_COOL = 8, //!< ![cool](pics/colormaps/colorscale_cool.jpg)
4336 COLORMAP_HSV = 9, //!< ![HSV](pics/colormaps/colorscale_hsv.jpg)
4337 COLORMAP_PINK = 10, //!< ![pink](pics/colormaps/colorscale_pink.jpg)
4338 COLORMAP_HOT = 11, //!< ![hot](pics/colormaps/colorscale_hot.jpg)
4339 COLORMAP_PARULA = 12, //!< ![parula](pics/colormaps/colorscale_parula.jpg)
4340 COLORMAP_MAGMA = 13, //!< ![magma](pics/colormaps/colorscale_magma.jpg)
4341 COLORMAP_INFERNO = 14, //!< ![inferno](pics/colormaps/colorscale_inferno.jpg)
4342 COLORMAP_PLASMA = 15, //!< ![plasma](pics/colormaps/colorscale_plasma.jpg)
4343 COLORMAP_VIRIDIS = 16, //!< ![viridis](pics/colormaps/colorscale_viridis.jpg)
4344 COLORMAP_CIVIDIS = 17, //!< ![cividis](pics/colormaps/colorscale_cividis.jpg)
4345 COLORMAP_TWILIGHT = 18, //!< ![twilight](pics/colormaps/colorscale_twilight.jpg)
4346 COLORMAP_TWILIGHT_SHIFTED = 19, //!< ![twilight shifted](pics/colormaps/colorscale_twilight_shifted.jpg)
4347 COLORMAP_TURBO = 20, //!< ![turbo](pics/colormaps/colorscale_turbo.jpg)
4348 COLORMAP_DEEPGREEN = 21 //!< ![deepgreen](pics/colormaps/colorscale_deepgreen.jpg)
4349 };
4350
4351 /** @example samples/cpp/falsecolor.cpp
4352 An example using applyColorMap function
4353 */
4354
4355 /** @brief Applies a GNU Octave/MATLAB equivalent colormap on a given image.
4356
4357 @param src The source image, grayscale or colored of type CV_8UC1 or CV_8UC3.
4358 @param dst The result is the colormapped source image. Note: Mat::create is called on dst.
4359 @param colormap The colormap to apply, see #ColormapTypes
4360 */
4361 CV_EXPORTS_W void applyColorMap(InputArray src, OutputArray dst, int colormap);
4362
4363 /** @brief Applies a user colormap on a given image.
4364
4365 @param src The source image, grayscale or colored of type CV_8UC1 or CV_8UC3.
4366 @param dst The result is the colormapped source image. Note: Mat::create is called on dst.
4367 @param userColor The colormap to apply of type CV_8UC1 or CV_8UC3 and size 256
4368 */
4369 CV_EXPORTS_W void applyColorMap(InputArray src, OutputArray dst, InputArray userColor);
4370
4371 //! @} imgproc_colormap
4372
4373 //! @addtogroup imgproc_draw
4374 //! @{
4375
4376
4377 /** OpenCV color channel order is BGR[A] */
4378 #define CV_RGB(r, g, b) cv::Scalar((b), (g), (r), 0)
4379
4380 /** @brief Draws a line segment connecting two points.
4381
4382 The function line draws the line segment between pt1 and pt2 points in the image. The line is
4383 clipped by the image boundaries. For non-antialiased lines with integer coordinates, the 8-connected
4384 or 4-connected Bresenham algorithm is used. Thick lines are drawn with rounding endings. Antialiased
4385 lines are drawn using Gaussian filtering.
4386
4387 @param img Image.
4388 @param pt1 First point of the line segment.
4389 @param pt2 Second point of the line segment.
4390 @param color Line color.
4391 @param thickness Line thickness.
4392 @param lineType Type of the line. See #LineTypes.
4393 @param shift Number of fractional bits in the point coordinates.
4394 */
4395 CV_EXPORTS_W void line(InputOutputArray img, Point pt1, Point pt2, const Scalar& color,
4396 int thickness = 1, int lineType = LINE_8, int shift = 0);
4397
4398 /** @brief Draws a arrow segment pointing from the first point to the second one.
4399
4400 The function cv::arrowedLine draws an arrow between pt1 and pt2 points in the image. See also #line.
4401
4402 @param img Image.
4403 @param pt1 The point the arrow starts from.
4404 @param pt2 The point the arrow points to.
4405 @param color Line color.
4406 @param thickness Line thickness.
4407 @param line_type Type of the line. See #LineTypes
4408 @param shift Number of fractional bits in the point coordinates.
4409 @param tipLength The length of the arrow tip in relation to the arrow length
4410 */
4411 CV_EXPORTS_W void arrowedLine(InputOutputArray img, Point pt1, Point pt2, const Scalar& color,
4412 int thickness=1, int line_type=8, int shift=0, double tipLength=0.1);
4413
4414 /** @brief Draws a simple, thick, or filled up-right rectangle.
4415
4416 The function cv::rectangle draws a rectangle outline or a filled rectangle whose two opposite corners
4417 are pt1 and pt2.
4418
4419 @param img Image.
4420 @param pt1 Vertex of the rectangle.
4421 @param pt2 Vertex of the rectangle opposite to pt1 .
4422 @param color Rectangle color or brightness (grayscale image).
4423 @param thickness Thickness of lines that make up the rectangle. Negative values, like #FILLED,
4424 mean that the function has to draw a filled rectangle.
4425 @param lineType Type of the line. See #LineTypes
4426 @param shift Number of fractional bits in the point coordinates.
4427 */
4428 CV_EXPORTS_W void rectangle(InputOutputArray img, Point pt1, Point pt2,
4429 const Scalar& color, int thickness = 1,
4430 int lineType = LINE_8, int shift = 0);
4431
4432 /** @overload
4433
4434 use `rec` parameter as alternative specification of the drawn rectangle: `r.tl() and
4435 r.br()-Point(1,1)` are opposite corners
4436 */
4437 CV_EXPORTS_W void rectangle(InputOutputArray img, Rect rec,
4438 const Scalar& color, int thickness = 1,
4439 int lineType = LINE_8, int shift = 0);
4440
4441 /** @example samples/cpp/tutorial_code/ImgProc/basic_drawing/Drawing_2.cpp
4442 An example using drawing functions
4443 */
4444
4445 /** @brief Draws a circle.
4446
4447 The function cv::circle draws a simple or filled circle with a given center and radius.
4448 @param img Image where the circle is drawn.
4449 @param center Center of the circle.
4450 @param radius Radius of the circle.
4451 @param color Circle color.
4452 @param thickness Thickness of the circle outline, if positive. Negative values, like #FILLED,
4453 mean that a filled circle is to be drawn.
4454 @param lineType Type of the circle boundary. See #LineTypes
4455 @param shift Number of fractional bits in the coordinates of the center and in the radius value.
4456 */
4457 CV_EXPORTS_W void circle(InputOutputArray img, Point center, int radius,
4458 const Scalar& color, int thickness = 1,
4459 int lineType = LINE_8, int shift = 0);
4460
4461 /** @brief Draws a simple or thick elliptic arc or fills an ellipse sector.
4462
4463 The function cv::ellipse with more parameters draws an ellipse outline, a filled ellipse, an elliptic
4464 arc, or a filled ellipse sector. The drawing code uses general parametric form.
4465 A piecewise-linear curve is used to approximate the elliptic arc
4466 boundary. If you need more control of the ellipse rendering, you can retrieve the curve using
4467 #ellipse2Poly and then render it with #polylines or fill it with #fillPoly. If you use the first
4468 variant of the function and want to draw the whole ellipse, not an arc, pass `startAngle=0` and
4469 `endAngle=360`. If `startAngle` is greater than `endAngle`, they are swapped. The figure below explains
4470 the meaning of the parameters to draw the blue arc.
4471
4472 ![Parameters of Elliptic Arc](pics/ellipse.svg)
4473
4474 @param img Image.
4475 @param center Center of the ellipse.
4476 @param axes Half of the size of the ellipse main axes.
4477 @param angle Ellipse rotation angle in degrees.
4478 @param startAngle Starting angle of the elliptic arc in degrees.
4479 @param endAngle Ending angle of the elliptic arc in degrees.
4480 @param color Ellipse color.
4481 @param thickness Thickness of the ellipse arc outline, if positive. Otherwise, this indicates that
4482 a filled ellipse sector is to be drawn.
4483 @param lineType Type of the ellipse boundary. See #LineTypes
4484 @param shift Number of fractional bits in the coordinates of the center and values of axes.
4485 */
4486 CV_EXPORTS_W void ellipse(InputOutputArray img, Point center, Size axes,
4487 double angle, double startAngle, double endAngle,
4488 const Scalar& color, int thickness = 1,
4489 int lineType = LINE_8, int shift = 0);
4490
4491 /** @overload
4492 @param img Image.
4493 @param box Alternative ellipse representation via RotatedRect. This means that the function draws
4494 an ellipse inscribed in the rotated rectangle.
4495 @param color Ellipse color.
4496 @param thickness Thickness of the ellipse arc outline, if positive. Otherwise, this indicates that
4497 a filled ellipse sector is to be drawn.
4498 @param lineType Type of the ellipse boundary. See #LineTypes
4499 */
4500 CV_EXPORTS_W void ellipse(InputOutputArray img, const RotatedRect& box, const Scalar& color,
4501 int thickness = 1, int lineType = LINE_8);
4502
4503 /* ----------------------------------------------------------------------------------------- */
4504 /* ADDING A SET OF PREDEFINED MARKERS WHICH COULD BE USED TO HIGHLIGHT POSITIONS IN AN IMAGE */
4505 /* ----------------------------------------------------------------------------------------- */
4506
4507 /** @brief Draws a marker on a predefined position in an image.
4508
4509 The function cv::drawMarker draws a marker on a given position in the image. For the moment several
4510 marker types are supported, see #MarkerTypes for more information.
4511
4512 @param img Image.
4513 @param position The point where the crosshair is positioned.
4514 @param color Line color.
4515 @param markerType The specific type of marker you want to use, see #MarkerTypes
4516 @param thickness Line thickness.
4517 @param line_type Type of the line, See #LineTypes
4518 @param markerSize The length of the marker axis [default = 20 pixels]
4519 */
4520 CV_EXPORTS_W void drawMarker(InputOutputArray img, Point position, const Scalar& color,
4521 int markerType = MARKER_CROSS, int markerSize=20, int thickness=1,
4522 int line_type=8);
4523
4524 /* ----------------------------------------------------------------------------------------- */
4525 /* END OF MARKER SECTION */
4526 /* ----------------------------------------------------------------------------------------- */
4527
4528 /** @overload */
4529 CV_EXPORTS void fillConvexPoly(InputOutputArray img, const Point* pts, int npts,
4530 const Scalar& color, int lineType = LINE_8,
4531 int shift = 0);
4532
4533 /** @brief Fills a convex polygon.
4534
4535 The function cv::fillConvexPoly draws a filled convex polygon. This function is much faster than the
4536 function #fillPoly . It can fill not only convex polygons but any monotonic polygon without
4537 self-intersections, that is, a polygon whose contour intersects every horizontal line (scan line)
4538 twice at the most (though, its top-most and/or the bottom edge could be horizontal).
4539
4540 @param img Image.
4541 @param points Polygon vertices.
4542 @param color Polygon color.
4543 @param lineType Type of the polygon boundaries. See #LineTypes
4544 @param shift Number of fractional bits in the vertex coordinates.
4545 */
4546 CV_EXPORTS_W void fillConvexPoly(InputOutputArray img, InputArray points,
4547 const Scalar& color, int lineType = LINE_8,
4548 int shift = 0);
4549
4550 /** @overload */
4551 CV_EXPORTS void fillPoly(InputOutputArray img, const Point** pts,
4552 const int* npts, int ncontours,
4553 const Scalar& color, int lineType = LINE_8, int shift = 0,
4554 Point offset = Point() );
4555
4556 /** @example samples/cpp/tutorial_code/ImgProc/basic_drawing/Drawing_1.cpp
4557 An example using drawing functions
4558 Check @ref tutorial_random_generator_and_text "the corresponding tutorial" for more details
4559 */
4560
4561 /** @brief Fills the area bounded by one or more polygons.
4562
4563 The function cv::fillPoly fills an area bounded by several polygonal contours. The function can fill
4564 complex areas, for example, areas with holes, contours with self-intersections (some of their
4565 parts), and so forth.
4566
4567 @param img Image.
4568 @param pts Array of polygons where each polygon is represented as an array of points.
4569 @param color Polygon color.
4570 @param lineType Type of the polygon boundaries. See #LineTypes
4571 @param shift Number of fractional bits in the vertex coordinates.
4572 @param offset Optional offset of all points of the contours.
4573 */
4574 CV_EXPORTS_W void fillPoly(InputOutputArray img, InputArrayOfArrays pts,
4575 const Scalar& color, int lineType = LINE_8, int shift = 0,
4576 Point offset = Point() );
4577
4578 /** @overload */
4579 CV_EXPORTS void polylines(InputOutputArray img, const Point* const* pts, const int* npts,
4580 int ncontours, bool isClosed, const Scalar& color,
4581 int thickness = 1, int lineType = LINE_8, int shift = 0 );
4582
4583 /** @brief Draws several polygonal curves.
4584
4585 @param img Image.
4586 @param pts Array of polygonal curves.
4587 @param isClosed Flag indicating whether the drawn polylines are closed or not. If they are closed,
4588 the function draws a line from the last vertex of each curve to its first vertex.
4589 @param color Polyline color.
4590 @param thickness Thickness of the polyline edges.
4591 @param lineType Type of the line segments. See #LineTypes
4592 @param shift Number of fractional bits in the vertex coordinates.
4593
4594 The function cv::polylines draws one or more polygonal curves.
4595 */
4596 CV_EXPORTS_W void polylines(InputOutputArray img, InputArrayOfArrays pts,
4597 bool isClosed, const Scalar& color,
4598 int thickness = 1, int lineType = LINE_8, int shift = 0 );
4599
4600 /** @example samples/cpp/contours2.cpp
4601 An example program illustrates the use of cv::findContours and cv::drawContours
4602 \image html WindowsQtContoursOutput.png "Screenshot of the program"
4603 */
4604
4605 /** @example samples/cpp/segment_objects.cpp
4606 An example using drawContours to clean up a background segmentation result
4607 */
4608
4609 /** @brief Draws contours outlines or filled contours.
4610
4611 The function draws contour outlines in the image if \f$\texttt{thickness} \ge 0\f$ or fills the area
4612 bounded by the contours if \f$\texttt{thickness}<0\f$ . The example below shows how to retrieve
4613 connected components from the binary image and label them: :
4614 @include snippets/imgproc_drawContours.cpp
4615
4616 @param image Destination image.
4617 @param contours All the input contours. Each contour is stored as a point vector.
4618 @param contourIdx Parameter indicating a contour to draw. If it is negative, all the contours are drawn.
4619 @param color Color of the contours.
4620 @param thickness Thickness of lines the contours are drawn with. If it is negative (for example,
4621 thickness=#FILLED ), the contour interiors are drawn.
4622 @param lineType Line connectivity. See #LineTypes
4623 @param hierarchy Optional information about hierarchy. It is only needed if you want to draw only
4624 some of the contours (see maxLevel ).
4625 @param maxLevel Maximal level for drawn contours. If it is 0, only the specified contour is drawn.
4626 If it is 1, the function draws the contour(s) and all the nested contours. If it is 2, the function
4627 draws the contours, all the nested contours, all the nested-to-nested contours, and so on. This
4628 parameter is only taken into account when there is hierarchy available.
4629 @param offset Optional contour shift parameter. Shift all the drawn contours by the specified
4630 \f$\texttt{offset}=(dx,dy)\f$ .
4631 @note When thickness=#FILLED, the function is designed to handle connected components with holes correctly
4632 even when no hierarchy date is provided. This is done by analyzing all the outlines together
4633 using even-odd rule. This may give incorrect results if you have a joint collection of separately retrieved
4634 contours. In order to solve this problem, you need to call #drawContours separately for each sub-group
4635 of contours, or iterate over the collection using contourIdx parameter.
4636 */
4637 CV_EXPORTS_W void drawContours( InputOutputArray image, InputArrayOfArrays contours,
4638 int contourIdx, const Scalar& color,
4639 int thickness = 1, int lineType = LINE_8,
4640 InputArray hierarchy = noArray(),
4641 int maxLevel = INT_MAX, Point offset = Point() );
4642
4643 /** @brief Clips the line against the image rectangle.
4644
4645 The function cv::clipLine calculates a part of the line segment that is entirely within the specified
4646 rectangle. it returns false if the line segment is completely outside the rectangle. Otherwise,
4647 it returns true .
4648 @param imgSize Image size. The image rectangle is Rect(0, 0, imgSize.width, imgSize.height) .
4649 @param pt1 First line point.
4650 @param pt2 Second line point.
4651 */
4652 CV_EXPORTS bool clipLine(Size imgSize, CV_IN_OUT Point& pt1, CV_IN_OUT Point& pt2);
4653
4654 /** @overload
4655 @param imgSize Image size. The image rectangle is Rect(0, 0, imgSize.width, imgSize.height) .
4656 @param pt1 First line point.
4657 @param pt2 Second line point.
4658 */
4659 CV_EXPORTS bool clipLine(Size2l imgSize, CV_IN_OUT Point2l& pt1, CV_IN_OUT Point2l& pt2);
4660
4661 /** @overload
4662 @param imgRect Image rectangle.
4663 @param pt1 First line point.
4664 @param pt2 Second line point.
4665 */
4666 CV_EXPORTS_W bool clipLine(Rect imgRect, CV_OUT CV_IN_OUT Point& pt1, CV_OUT CV_IN_OUT Point& pt2);
4667
4668 /** @brief Approximates an elliptic arc with a polyline.
4669
4670 The function ellipse2Poly computes the vertices of a polyline that approximates the specified
4671 elliptic arc. It is used by #ellipse. If `arcStart` is greater than `arcEnd`, they are swapped.
4672
4673 @param center Center of the arc.
4674 @param axes Half of the size of the ellipse main axes. See #ellipse for details.
4675 @param angle Rotation angle of the ellipse in degrees. See #ellipse for details.
4676 @param arcStart Starting angle of the elliptic arc in degrees.
4677 @param arcEnd Ending angle of the elliptic arc in degrees.
4678 @param delta Angle between the subsequent polyline vertices. It defines the approximation
4679 accuracy.
4680 @param pts Output vector of polyline vertices.
4681 */
4682 CV_EXPORTS_W void ellipse2Poly( Point center, Size axes, int angle,
4683 int arcStart, int arcEnd, int delta,
4684 CV_OUT std::vector<Point>& pts );
4685
4686 /** @overload
4687 @param center Center of the arc.
4688 @param axes Half of the size of the ellipse main axes. See #ellipse for details.
4689 @param angle Rotation angle of the ellipse in degrees. See #ellipse for details.
4690 @param arcStart Starting angle of the elliptic arc in degrees.
4691 @param arcEnd Ending angle of the elliptic arc in degrees.
4692 @param delta Angle between the subsequent polyline vertices. It defines the approximation accuracy.
4693 @param pts Output vector of polyline vertices.
4694 */
4695 CV_EXPORTS void ellipse2Poly(Point2d center, Size2d axes, int angle,
4696 int arcStart, int arcEnd, int delta,
4697 CV_OUT std::vector<Point2d>& pts);
4698
4699 /** @brief Draws a text string.
4700
4701 The function cv::putText renders the specified text string in the image. Symbols that cannot be rendered
4702 using the specified font are replaced by question marks. See #getTextSize for a text rendering code
4703 example.
4704
4705 @param img Image.
4706 @param text Text string to be drawn.
4707 @param org Bottom-left corner of the text string in the image.
4708 @param fontFace Font type, see #HersheyFonts.
4709 @param fontScale Font scale factor that is multiplied by the font-specific base size.
4710 @param color Text color.
4711 @param thickness Thickness of the lines used to draw a text.
4712 @param lineType Line type. See #LineTypes
4713 @param bottomLeftOrigin When true, the image data origin is at the bottom-left corner. Otherwise,
4714 it is at the top-left corner.
4715 */
4716 CV_EXPORTS_W void putText( InputOutputArray img, const String& text, Point org,
4717 int fontFace, double fontScale, Scalar color,
4718 int thickness = 1, int lineType = LINE_8,
4719 bool bottomLeftOrigin = false );
4720
4721 /** @brief Calculates the width and height of a text string.
4722
4723 The function cv::getTextSize calculates and returns the size of a box that contains the specified text.
4724 That is, the following code renders some text, the tight box surrounding it, and the baseline: :
4725 @code
4726 String text = "Funny text inside the box";
4727 int fontFace = FONT_HERSHEY_SCRIPT_SIMPLEX;
4728 double fontScale = 2;
4729 int thickness = 3;
4730
4731 Mat img(600, 800, CV_8UC3, Scalar::all(0));
4732
4733 int baseline=0;
4734 Size textSize = getTextSize(text, fontFace,
4735 fontScale, thickness, &baseline);
4736 baseline += thickness;
4737
4738 // center the text
4739 Point textOrg((img.cols - textSize.width)/2,
4740 (img.rows + textSize.height)/2);
4741
4742 // draw the box
4743 rectangle(img, textOrg + Point(0, baseline),
4744 textOrg + Point(textSize.width, -textSize.height),
4745 Scalar(0,0,255));
4746 // ... and the baseline first
4747 line(img, textOrg + Point(0, thickness),
4748 textOrg + Point(textSize.width, thickness),
4749 Scalar(0, 0, 255));
4750
4751 // then put the text itself
4752 putText(img, text, textOrg, fontFace, fontScale,
4753 Scalar::all(255), thickness, 8);
4754 @endcode
4755
4756 @param text Input text string.
4757 @param fontFace Font to use, see #HersheyFonts.
4758 @param fontScale Font scale factor that is multiplied by the font-specific base size.
4759 @param thickness Thickness of lines used to render the text. See #putText for details.
4760 @param[out] baseLine y-coordinate of the baseline relative to the bottom-most text
4761 point.
4762 @return The size of a box that contains the specified text.
4763
4764 @see putText
4765 */
4766 CV_EXPORTS_W Size getTextSize(const String& text, int fontFace,
4767 double fontScale, int thickness,
4768 CV_OUT int* baseLine);
4769
4770
4771 /** @brief Calculates the font-specific size to use to achieve a given height in pixels.
4772
4773 @param fontFace Font to use, see cv::HersheyFonts.
4774 @param pixelHeight Pixel height to compute the fontScale for
4775 @param thickness Thickness of lines used to render the text.See putText for details.
4776 @return The fontSize to use for cv::putText
4777
4778 @see cv::putText
4779 */
4780 CV_EXPORTS_W double getFontScaleFromHeight(const int fontFace,
4781 const int pixelHeight,
4782 const int thickness = 1);
4783
4784 /** @brief Line iterator
4785
4786 The class is used to iterate over all the pixels on the raster line
4787 segment connecting two specified points.
4788
4789 The class LineIterator is used to get each pixel of a raster line. It
4790 can be treated as versatile implementation of the Bresenham algorithm
4791 where you can stop at each pixel and do some extra processing, for
4792 example, grab pixel values along the line or draw a line with an effect
4793 (for example, with XOR operation).
4794
4795 The number of pixels along the line is stored in LineIterator::count.
4796 The method LineIterator::pos returns the current position in the image:
4797
4798 @code{.cpp}
4799 // grabs pixels along the line (pt1, pt2)
4800 // from 8-bit 3-channel image to the buffer
4801 LineIterator it(img, pt1, pt2, 8);
4802 LineIterator it2 = it;
4803 vector<Vec3b> buf(it.count);
4804
4805 for(int i = 0; i < it.count; i++, ++it)
4806 buf[i] = *(const Vec3b*)*it;
4807
4808 // alternative way of iterating through the line
4809 for(int i = 0; i < it2.count; i++, ++it2)
4810 {
4811 Vec3b val = img.at<Vec3b>(it2.pos());
4812 CV_Assert(buf[i] == val);
4813 }
4814 @endcode
4815 */
4816 class CV_EXPORTS LineIterator
4817 {
4818 public:
4819 /** @brief initializes the iterator
4820
4821 creates iterators for the line connecting pt1 and pt2
4822 the line will be clipped on the image boundaries
4823 the line is 8-connected or 4-connected
4824 If leftToRight=true, then the iteration is always done
4825 from the left-most point to the right most,
4826 not to depend on the ordering of pt1 and pt2 parameters;
4827 */
LineIterator(const Mat & img,Point pt1,Point pt2,int connectivity=8,bool leftToRight=false)4828 LineIterator( const Mat& img, Point pt1, Point pt2,
4829 int connectivity = 8, bool leftToRight = false )
4830 {
4831 init(&img, Rect(0, 0, img.cols, img.rows), pt1, pt2, connectivity, leftToRight);
4832 ptmode = false;
4833 }
LineIterator(Point pt1,Point pt2,int connectivity=8,bool leftToRight=false)4834 LineIterator( Point pt1, Point pt2,
4835 int connectivity = 8, bool leftToRight = false )
4836 {
4837 init(0, Rect(std::min(pt1.x, pt2.x),
4838 std::min(pt1.y, pt2.y),
4839 std::max(pt1.x, pt2.x) - std::min(pt1.x, pt2.x) + 1,
4840 std::max(pt1.y, pt2.y) - std::min(pt1.y, pt2.y) + 1),
4841 pt1, pt2, connectivity, leftToRight);
4842 ptmode = true;
4843 }
LineIterator(Size boundingAreaSize,Point pt1,Point pt2,int connectivity=8,bool leftToRight=false)4844 LineIterator( Size boundingAreaSize, Point pt1, Point pt2,
4845 int connectivity = 8, bool leftToRight = false )
4846 {
4847 init(0, Rect(0, 0, boundingAreaSize.width, boundingAreaSize.height),
4848 pt1, pt2, connectivity, leftToRight);
4849 ptmode = true;
4850 }
LineIterator(Rect boundingAreaRect,Point pt1,Point pt2,int connectivity=8,bool leftToRight=false)4851 LineIterator( Rect boundingAreaRect, Point pt1, Point pt2,
4852 int connectivity = 8, bool leftToRight = false )
4853 {
4854 init(0, boundingAreaRect, pt1, pt2, connectivity, leftToRight);
4855 ptmode = true;
4856 }
4857 void init(const Mat* img, Rect boundingAreaRect, Point pt1, Point pt2, int connectivity, bool leftToRight);
4858
4859 /** @brief returns pointer to the current pixel
4860 */
4861 uchar* operator *();
4862 /** @brief prefix increment operator (++it). shifts iterator to the next pixel
4863 */
4864 LineIterator& operator ++();
4865 /** @brief postfix increment operator (it++). shifts iterator to the next pixel
4866 */
4867 LineIterator operator ++(int);
4868 /** @brief returns coordinates of the current pixel
4869 */
4870 Point pos() const;
4871
4872 uchar* ptr;
4873 const uchar* ptr0;
4874 int step, elemSize;
4875 int err, count;
4876 int minusDelta, plusDelta;
4877 int minusStep, plusStep;
4878 int minusShift, plusShift;
4879 Point p;
4880 bool ptmode;
4881 };
4882
4883 //! @cond IGNORED
4884
4885 // === LineIterator implementation ===
4886
4887 inline
operator *()4888 uchar* LineIterator::operator *()
4889 {
4890 return ptmode ? 0 : ptr;
4891 }
4892
4893 inline
operator ++()4894 LineIterator& LineIterator::operator ++()
4895 {
4896 int mask = err < 0 ? -1 : 0;
4897 err += minusDelta + (plusDelta & mask);
4898 if(!ptmode)
4899 {
4900 ptr += minusStep + (plusStep & mask);
4901 }
4902 else
4903 {
4904 p.x += minusShift + (plusShift & mask);
4905 p.y += minusStep + (plusStep & mask);
4906 }
4907 return *this;
4908 }
4909
4910 inline
operator ++(int)4911 LineIterator LineIterator::operator ++(int)
4912 {
4913 LineIterator it = *this;
4914 ++(*this);
4915 return it;
4916 }
4917
4918 inline
pos() const4919 Point LineIterator::pos() const
4920 {
4921 if(!ptmode)
4922 {
4923 size_t offset = (size_t)(ptr - ptr0);
4924 int y = (int)(offset/step);
4925 int x = (int)((offset - (size_t)y*step)/elemSize);
4926 return Point(x, y);
4927 }
4928 return p;
4929 }
4930
4931 //! @endcond
4932
4933 //! @} imgproc_draw
4934
4935 //! @} imgproc
4936
4937 } // cv
4938
4939
4940 #include "./imgproc/segmentation.hpp"
4941
4942
4943 #endif
4944