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