opencv/doc/cv_image_filtering.tex

   1 \section{Image Filtering}
   2
   3 Functions and classes described in this section are used to perform various linear or non-linear filtering operations on 2D images (represented as \cvCppCross{Mat}'s), that is, for each pixel location $(x,y)$ in the source image some its (normally rectangular) neighborhood is considered and used to compute the response. In case of a linear filter it is a weighted sum of pixel values, in case of morphological operations it is the minimum or maximum etc. The computed response is stored to the destination image at the same location $(x,y)$. It means, that the output image will be of the same size as the input image. Normally, the functions supports multi-channel arrays, in which case every channel is processed independently, therefore the output image will also have the same number of channels as the input one.
   4
   5 Another common feature of the functions and classes described in this section is that, unlike simple arithmetic functions, they need to extrapolate values of some non-existing pixels. For example, if we want to smooth an image using a Gaussian $3 \times 3$ filter, then during the processing of the left-most pixels in each row we need pixels to the left of them, i.e. outside of the image. We can let those pixels be the same as the left-most image pixels (i.e. use "replicated border" extrapolation method), or assume that all the non-existing pixels are zeros ("contant border" extrapolation method) etc. \cvCpp{OpenCV let the user to specify the extrapolation method; see the function \cvCppCross{borderInterpolate} and discussion of \texttt{borderType} parameter in various functions below.}
   6
   7 \ifCPy
   8
   9 \cvclass{IplConvKernel}
  10
  11 An IplConvKernel is a rectangular convolution kernel, created by function \cross{CreateStructuringElementEx}.
  12
  13 \cvCPyFunc{CopyMakeBorder}
  14 Copies an image and makes a border around it.
  15
  16 \cvdefC{
  17 void cvCopyMakeBorder(
  18 \par const CvArr* src,
  19 \par CvArr* dst,
  20 \par CvPoint offset,
  21 \par int bordertype,
  22 \par CvScalar value=cvScalarAll(0) );}
  23 \cvdefPy{CopyMakeBorder(src,dst,offset,bordertype,value=(0,0,0,0))-> None}
  24
  25 \begin{description}
  26 \cvarg{src}{The source image}
  27 \cvarg{dst}{The destination image}
  28 \cvarg{offset}{Coordinates of the top-left corner (or bottom-left in the case of images with bottom-left origin) of the destination image rectangle where the source image (or its ROI) is copied. Size of the rectanlge matches the source image size/ROI size}
  29 \cvarg{bordertype}{Type of the border to create around the copied source image rectangle; types include:
  30 \begin{description}
  31 \cvarg{IPL\_BORDER\_CONSTANT}{border is filled with the fixed value, passed as last parameter of the function.}
  32 \cvarg{IPL\_BORDER\_REPLICATE}{the pixels from the top and bottom rows, the left-most and right-most columns are replicated to fill the border.}
  33 \end{description}
  34 (The other two border types from IPL, \texttt{IPL\_BORDER\_REFLECT} and \texttt{IPL\_BORDER\_WRAP}, are currently unsupported)}
  35 \cvarg{value}{Value of the border pixels if \texttt{bordertype} is \texttt{IPL\_BORDER\_CONSTANT}}
  36 \end{description}
  37
  38 The function copies the source 2D array into the interior of the destination array and makes a border of the specified type around the copied area. The function is useful when one needs to emulate border type that is different from the one embedded into a specific algorithm implementation. For example, morphological functions, as well as most of other filtering functions in OpenCV, internally use replication border type, while the user may need a zero border or a border, filled with 1's or 255's.
  39
  40 \cvCPyFunc{CreateStructuringElementEx}
  41 Creates a structuring element.
  42
  43 \cvdefC{IplConvKernel* cvCreateStructuringElementEx(\par int cols,
  44  \par int rows, \par int anchorX, \par int anchorY, \par int shape, \par int* values=NULL );}
  45 \cvdefPy{CreateStructuringElementEx(cols,rows,anchorX,anchorY,shape,values=None)-> kernel}
  46
  47 \begin{description}
  48 \cvarg{cols}{Number of columns in the structuring element}
  49 \cvarg{rows}{Number of rows in the structuring element}
  50 \cvarg{anchorX}{Relative horizontal offset of the anchor point}
  51 \cvarg{anchorY}{Relative vertical offset of the anchor point}
  52 \cvarg{shape}{Shape of the structuring element; may have the following values:
  53 \begin{description}
  54   \cvarg{CV\_SHAPE\_RECT}{a rectangular element}
  55   \cvarg{CV\_SHAPE\_CROSS}{a cross-shaped element}
  56   \cvarg{CV\_SHAPE\_ELLIPSE}{an elliptic element}
  57   \cvarg{CV\_SHAPE\_CUSTOM}{a user-defined element. In this case the parameter \texttt{values} specifies the mask, that is, which neighbors of the pixel must be considered}
  58 \end{description}}
  59 \cvarg{values}{Pointer to the structuring element data, a plane array, representing row-by-row scanning of the element matrix. Non-zero values indicate points that belong to the element. If the pointer is \texttt{NULL}, then all values are considered non-zero, that is, the element is of a rectangular shape. This parameter is considered only if the shape is \texttt{CV\_SHAPE\_CUSTOM} }
  60 \end{description}
  61
  62 The function CreateStructuringElementEx allocates and fills the structure \texttt{IplConvKernel}, which can be used as a structuring element in the morphological operations.
  63
  64 \cvCPyFunc{Dilate}
  65 Dilates an image by using a specific structuring element.
  66
  67 \cvdefC{void cvDilate(\par const CvArr* src,\par CvArr* dst,\par IplConvKernel* element=NULL,\par int iterations=1 );}
  68 \cvdefPy{Dilate(src,dst,element=NULL,iterations=1)-> None}
  69
  70 \begin{description}
  71 \cvarg{src}{Source image}
  72 \cvarg{dst}{Destination image}
  73 \cvarg{element}{Structuring element used for dilation. If it is \texttt{NULL}, a $3\times 3$ rectangular structuring element is used}
  74 \cvarg{iterations}{Number of times dilation is applied}
  75 \end{description}
  76
  77 The function dilates the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the maximum is taken:
  78
  79 \[
  80 \max_{(x',y') \, in \, \texttt{element}}src(x+x',y+y')
  81 \]
  82
  83 The function supports the in-place mode. Dilation can be applied several (\texttt{iterations}) times. For color images, each channel is processed independently.
  84
  85 \cvCPyFunc{Erode}
  86 Erodes an image by using a specific structuring element.
  87
  88 \cvdefC{void cvErode(\par const CvArr* src,\par  CvArr* dst,\par  IplConvKernel* element=NULL,\par  int iterations=1);}
  89 \cvdefPy{Erode(src,dst,element=NULL,iterations=1)-> None}
  90
  91 \begin{description}
  92 \cvarg{src}{Source image}
  93 \cvarg{dst}{Destination image}
  94 \cvarg{element}{Structuring element used for erosion. If it is \texttt{NULL}, a $3\times 3$ rectangular structuring element is used}
  95 \cvarg{iterations}{Number of times erosion is applied}
  96 \end{description}
  97
  98 The function erodes the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the minimum is taken:
  99
 100 \[
 101 \min_{(x',y') \, in \, \texttt{element}}src(x+x',y+y')
 102 \]
 103
 104 The function supports the in-place mode. Erosion can be applied several (\texttt{iterations}) times. For color images, each channel is processed independently.
 105
 106 \cvCPyFunc{Filter2D}
 107 Convolves an image with the kernel.
 108
 109 \cvdefC{void cvFilter2D(
 110 \par const CvArr* src,\par  CvArr* dst,\par  const CvMat* kernel,\par  CvPoint anchor=cvPoint(-1,-1));}
 111 \cvdefPy{Filter2D(src,dst,kernel,anchor=(-1,-1))-> None}
 112
 113 \begin{description}
 114 \cvarg{src}{The source image}
 115 \cvarg{dst}{The destination image}
 116 \cvarg{kernel}{Convolution kernel, a single-channel floating point matrix. If you want to apply different kernels to different channels, split the image into separate color planes using \cvCPyCross{Split} and process them individually}
 117 \cvarg{anchor}{The anchor of the kernel that indicates the relative position of a filtered point within the kernel. The anchor shoud lie within the kernel. The special default value (-1,-1) means that it is at the kernel center}
 118 \end{description}
 119
 120 The function applies an arbitrary linear filter to the image. In-place operation is supported. When the aperture is partially outside the image, the function interpolates outlier pixel values from the nearest pixels that are inside the image.
 121
 122 \cvCPyFunc{Laplace}
 123 Calculates the Laplacian of an image.
 124
 125 \cvdefC{void cvLaplace(\par const CvArr* src,\par  CvArr* dst,\par  int apertureSize=3);}
 126 \cvdefPy{Laplace(src,dst,apertureSize=3)-> None}
 127 \begin{description}
 128 \cvarg{src}{Source image}
 129 \cvarg{dst}{Destination image}
 130 \cvarg{apertureSize}{Aperture size (it has the same meaning as \cvCPyCross{Sobel})}
 131 \end{description}
 132
 133 The function calculates the Laplacian of the source image by adding up the second x and y derivatives calculated using the Sobel operator:
 134
 135 \[
 136 \texttt{dst}(x,y) = \frac{d^2 \texttt{src}}{dx^2} + \frac{d^2 \texttt{src}}{dy^2}
 137 \]
 138
 139 Setting \texttt{apertureSize} = 1 gives the fastest variant that is equal to convolving the image with the following kernel:
 140
 141 \[ \vecthreethree {0}{1}{0}{1}{-4}{1}{0}{1}{0} \]
 142
 143 Similar to the \cvCPyCross{Sobel} function, no scaling is done and the same combinations of input and output formats are supported.
 144
 145 \cvCPyFunc{MorphologyEx}
 146 Performs advanced morphological transformations.
 147
 148 \cvdefC{void cvMorphologyEx(
 149 \par const CvArr* src,\par  CvArr* dst,\par  CvArr* temp,\par  IplConvKernel* element,
 150 \par int operation,\par  int iterations=1 );}
 151 \cvdefPy{MorphologyEx(src,dst,temp,element,operation,iterations=1)-> None}
 152
 153 \begin{description}
 154 \cvarg{src}{Source image}
 155 \cvarg{dst}{Destination image}
 156 \cvarg{temp}{Temporary image, required in some cases}
 157 \cvarg{element}{Structuring element}
 158 \cvarg{operation}{Type of morphological operation, one of the following:
 159 \begin{description}
 160 \cvarg{CV\_MOP\_OPEN}{opening}
 161 \cvarg{CV\_MOP\_CLOSE}{closing}
 162 \cvarg{CV\_MOP\_GRADIENT}{morphological gradient}
 163 \cvarg{CV\_MOP\_TOPHAT}{"top hat"}
 164 \cvarg{CV\_MOP\_BLACKHAT}{"black hat"}
 165 \end{description}}
 166 \cvarg{iterations}{Number of times erosion and dilation are applied}
 167 \end{description}
 168
 169 The function can perform advanced morphological transformations using erosion and dilation as basic operations.
 170
 171 Opening:
 172
 173 \[
 174 dst=open(src,element)=dilate(erode(src,element),element)
 175 \]
 176
 177 Closing:
 178
 179 \[
 180 dst=close(src,element)=erode(dilate(src,element),element)
 181 \]
 182
 183 Morphological gradient:
 184
 185 \[
 186 dst=morph\_grad(src,element)=dilate(src,element)-erode(src,element)
 187 \]
 188
 189 "Top hat":
 190
 191 \[
 192 dst=tophat(src,element)=src-open(src,element)
 193 \]
 194
 195 "Black hat":
 196
 197 \[
 198 dst=blackhat(src,element)=close(src,element)-src
 199 \]
 200
 201 The temporary image \texttt{temp} is required for a morphological gradient and, in the case of in-place operation, for "top hat" and "black hat".
 202
 203 \cvCPyFunc{PyrDown}
 204 Downsamples an image.
 205
 206 \cvdefC{void cvPyrDown(\par const CvArr* src,\par CvArr* dst,\par int filter=CV\_GAUSSIAN\_5x5 );}
 207 \cvdefPy{PyrDown(src,dst,filter=CV\_GAUSSIAN\_5X5)-> None}
 208
 209 \begin{description}
 210 \cvarg{src}{The source image}
 211 \cvarg{dst}{The destination image, should have a half as large width and height than the source}
 212 \cvarg{filter}{Type of the filter used for convolution; only \texttt{CV\_GAUSSIAN\_5x5} is currently supported}
 213 \end{description}
 214
 215 The function performs the downsampling step of the Gaussian pyramid decomposition. First it convolves the source image with the specified filter and then downsamples the image by rejecting even rows and columns.
 216
 217 \ifC
 218 \cvCPyFunc{ReleaseStructuringElement}
 219 Deletes a structuring element.
 220
 221 \cvdefC{void cvReleaseStructuringElement( IplConvKernel** element );}
 222
 223 \begin{description}
 224 \cvarg{element}{Pointer to the deleted structuring element}
 225 \end{description}
 226
 227 The function releases the structure \texttt{IplConvKernel} that is no longer needed. If \texttt{*element} is \texttt{NULL}, the function has no effect.
 228 \fi
 229
 230 \cvCPyFunc{Smooth}
 231 Smooths the image in one of several ways.
 232
 233 \cvdefC{void cvSmooth(\par const CvArr* src,
 234 \par CvArr* dst,\par  int smoothtype=CV\_GAUSSIAN,\par  int param1=3,\par  int param2=0,\par  double param3=0, \par double param4=0);}
 235 \cvdefPy{Smooth(src,dst,smoothtype=CV\_GAUSSIAN,param1=3,param2=0,param3=0,param4=0)-> None}
 236
 237 \begin{description}
 238 \cvarg{src}{The source image}
 239 \cvarg{dst}{The destination image}
 240 \cvarg{smoothtype}{Type of the smoothing:
 241 \begin{description}
 242   \cvarg{CV\_BLUR\_NO\_SCALE}{linear convolution with $\texttt{param1}\times\texttt{param2}$ box kernel (all 1's). If you want to smooth different pixels with different-size box kernels, you can use the integral image that is computed using \cvCPyCross{Integral}}
 243   \cvarg{CV\_BLUR}{linear convolution with $\texttt{param1}\times\texttt{param2}$ box kernel (all 1's) with subsequent scaling by $1/(\texttt{param1}\cdot\texttt{param2})$}
 244   \cvarg{CV\_GAUSSIAN}{linear convolution with a $\texttt{param1}\times\texttt{param2}$ Gaussian kernel}
 245   \cvarg{CV\_MEDIAN}{median filter with a $\texttt{param1}\times\texttt{param1}$ square aperture}
 246   \cvarg{CV\_BILATERAL}{bilateral filter with a $\texttt{param1}\times\texttt{param1}$ square aperture, color sigma=\texttt{param3} and spatial sigma=\texttt{param4}. If \texttt{param1=0}, the aperture square side is set to \texttt{cvRound(param4*1.5)*2+1}. Information about bilateral filtering can be found at \url{http://www.dai.ed.ac.uk/CVonline/LOCAL\_COPIES/MANDUCHI1/Bilateral\_Filtering.html}}
 247 \end{description}}
 248 \cvarg{param1}{The first parameter of the smoothing operation, the aperture width. Must be a positive odd number (1, 3, 5, ...)}
 249 \cvarg{param2}{The second parameter of the smoothing operation, the aperture height. Ignored by \texttt{CV\_MEDIAN} and \texttt{CV\_BILATERAL} methods. In the case of simple scaled/non-scaled and Gaussian blur if \texttt{param2} is zero, it is set to \texttt{param1}. Otherwise it must be a positive odd number.}
 250 \cvarg{param3}{In the case of a Gaussian parameter this parameter may specify Gaussian $\sigma$ (standard deviation). If it is zero, it is calculated from the kernel size:
 251 \[
 252 \sigma = 0.3 (n/2 - 1) + 0.8 \quad \text{where} \quad n=
 253 \begin{array}{l l}
 254 \mbox{\texttt{param1} for horizontal kernel}\\
 255 \mbox{\texttt{param2} for vertical kernel}
 256 \end{array}
 257 \]
 258
 259 Using standard sigma for small kernels ($3\times 3$ to $7\times 7$) gives better speed. If \texttt{param3} is not zero, while \texttt{param1} and \texttt{param2} are zeros, the kernel size is calculated from the sigma (to provide accurate enough operation).}
 260 \end{description}
 261
 262 The function smooths an image using one of several methods. Every of the methods has some features and restrictions listed below
 263
 264 Blur with no scaling works with single-channel images only and supports accumulation of 8-bit to 16-bit format (similar to \cvCPyCross{Sobel} and \cvCPyCross{Laplace}) and 32-bit floating point to 32-bit floating-point format.
 265
 266 Simple blur and Gaussian blur support 1- or 3-channel, 8-bit and 32-bit floating point images. These two methods can process images in-place.
 267
 268 Median and bilateral filters work with 1- or 3-channel 8-bit images and can not process images in-place.
 269
 270 \cvCPyFunc{Sobel}
 271 Calculates the first, second, third or mixed image derivatives using an extended Sobel operator.
 272
 273 \cvdefC{void cvSobel(\par const CvArr* src,\par  CvArr* dst,\par  int xorder,\par  int yorder,\par  int apertureSize=3 );}
 274 \cvdefPy{Sobel(src,dst,xorder,yorder,apertureSize = 3)-> None}
 275
 276 \begin{description}
 277 \cvarg{src}{Source image of type CvArr*}
 278 \cvarg{dst}{Destination image}
 279 \cvarg{xorder}{Order of the derivative x}
 280 \cvarg{yorder}{Order of the derivative y}
 281 \cvarg{apertureSize}{Size of the extended Sobel kernel, must be 1, 3, 5 or 7}
 282 \end{description}
 283
 284 In all cases except 1, an $\texttt{apertureSize} \times
 285 \texttt{apertureSize}$ separable kernel will be used to calculate the
 286 derivative. For $\texttt{apertureSize} = 1$ a $3 \times 1$ or $1 \times 3$
 287 a kernel is used (Gaussian smoothing is not done). There is also the special
 288 value \texttt{CV\_SCHARR} (-1) that corresponds to a $3\times3$ Scharr
 289 filter that may give more accurate results than a $3\times3$ Sobel. Scharr
 290 aperture is
 291
 292 \[ \vecthreethree
 293 {-3}{0}{3}
 294 {-10}{0}{10}
 295 {-3}{0}{3}
 296 \]
 297
 298 for the x-derivative or transposed for the y-derivative.
 299
 300 The function calculates the image derivative by convolving the image with the appropriate kernel:
 301
 302 \[
 303 \texttt{dst}(x,y) = \frac{d^{xorder+yorder} \texttt{src}}{dx^{xorder} \cdot dy^{yorder}}
 304 \]
 305
 306 The Sobel operators combine Gaussian smoothing and differentiation
 307 so the result is more or less resistant to the noise. Most often,
 308 the function is called with (\texttt{xorder} = 1, \texttt{yorder} = 0,
 309 \texttt{apertureSize} = 3) or (\texttt{xorder} = 0, \texttt{yorder} = 1,
 310 \texttt{apertureSize} = 3) to calculate the first x- or y- image
 311 derivative. The first case corresponds to a kernel of:
 312
 313 \[ \vecthreethree
 314 {-1}{0}{1}
 315 {-2}{0}{2}
 316 {-1}{0}{1}
 317 \]
 318
 319 and the second one corresponds to a kernel of:
 320 \[ \vecthreethree
 321 {-1}{-2}{-1}
 322 {0}{0}{0}
 323 {1}{2}{1}
 324 \]
 325 or a kernel of:
 326 \[ \vecthreethree
 327 {1}{2}{1}
 328 {0}{0}{0}
 329 {-1}{2}{-1}
 330 \]
 331
 332 depending on the image origin (\texttt{origin} field of
 333 \texttt{IplImage} structure). No scaling is done, so the destination image
 334 usually has larger numbers (in absolute values) than the source image does. To
 335 avoid overflow, the function requires a 16-bit destination image if the
 336 source image is 8-bit. The result can be converted back to 8-bit using the
 337 \cvCPyCross{ConvertScale} or the \cvCPyCross{ConvertScaleAbs} function. Besides 8-bit images
 338 the function can process 32-bit floating-point images. Both the source and the
 339 destination must be single-channel images of equal size or equal ROI size.
 340
 341 \fi
 342
 343 \ifCpp
 344
 345 \cvCppFunc{BaseColumnFilter}
 346 Base class for filters with single-column kernels
 347
 348 \begin{lstlisting}
 349 class BaseColumnFilter
 350 {
 351 public:
 352     virtual ~BaseColumnFilter();
 353
 354     // To be overriden by the user.
 355     //
 356     // runs filtering operation on the set of rows,
 357     // "dstcount + ksize - 1" rows on input,
 358     // "dstcount" rows on output,
 359     // each input and output row has "width" elements
 360     // the filtered rows are written into "dst" buffer.
 361     virtual void operator()(const uchar** src, uchar* dst, int dststep,
 362                             int dstcount, int width) = 0;
 363     // resets the filter state (may be needed for IIR filters)
 364     virtual void reset();
 365
 366     int ksize; // the aperture size
 367     int anchor; // position of the anchor point,
 368                 // normally not used during the processing
 369 };
 370 \end{lstlisting}
 371
 372 The class \texttt{BaseColumnFilter} is the base class for filtering data using single-column kernels. The filtering does not have to be a linear operation. In general, it could be written as following:
 373
 374 \[\texttt{dst}(x,y) = F(\texttt{src}[y](x),\;\texttt{src}[y+1](x),\;...,\;\texttt{src}[y+\texttt{ksize}-1](x)\]
 375
 376 where $F$ is the filtering function, but, as it is represented as a class, it can produce any side effects, memorize previously processed data etc. The class only defines the interface and is not used directly. Instead, there are several functions in OpenCV (and you can add more) that return pointers to the derived classes that implement specific filtering operations. Those pointers are then passed to \cvCppCross{FilterEngine} constructor. While the filtering operation interface uses \texttt{uchar} type, a particular implementation is not limited to 8-bit data.
 377
 378 See also: \cvCppCross{BaseRowFilter}, \cvCppCross{BaseFilter}, \cvCppCross{FilterEngine},
 379     \cvCppCross{getColumnSumFilter}, \cvCppCross{getLinearColumnFilter}, \cvCppCross{getMorphologyColumnFilter}
 380
 381
 382 \cvCppFunc{BaseFilter}
 383 Base class for 2D image filters
 384
 385 \begin{lstlisting}
 386 class BaseFilter
 387 {
 388 public:
 389     virtual ~BaseFilter();
 390
 391     // To be overriden by the user.
 392     //
 393     // runs filtering operation on the set of rows,
 394     // "dstcount + ksize.height - 1" rows on input,
 395     // "dstcount" rows on output,
 396     // each input row has "(width + ksize.width-1)*cn" elements
 397     // each output row has "width*cn" elements.
 398     // the filtered rows are written into "dst" buffer.
 399     virtual void operator()(const uchar** src, uchar* dst, int dststep,
 400                             int dstcount, int width, int cn) = 0;
 401     // resets the filter state (may be needed for IIR filters)
 402     virtual void reset();
 403     Size ksize;
 404     Point anchor;
 405 };
 406 \end{lstlisting}
 407
 408 The class \texttt{BaseFilter} is the base class for filtering data using 2D kernels. The filtering does not have to be a linear operation. In general, it could be written as following:
 409
 410 \[
 411   \begin{array}{l}
 412   \texttt{dst}(x,y) = F( \texttt{src}[y](x),\;\texttt{src}[y](x+1),\;...,\;\texttt{src}[y](x+\texttt{ksize.width}-1), \\
 413   \texttt{src}[y+1](x),\;\texttt{src}[y+1](x+1),\;...,\;\texttt{src}[y+1](x+\texttt{ksize.width}-1), \\
 414   ......................................................................................... \\
 415   \texttt{src}[y+\texttt{ksize.height-1}](x),\\
 416   \texttt{src}[y+\texttt{ksize.height-1}](x+1),\\
 417   ...
 418   \texttt{src}[y+\texttt{ksize.height-1}](x+\texttt{ksize.width}-1))
 419   \end{array}
 420   \]
 421
 422 where $F$ is the filtering function. The class only defines the interface and is not used directly. Instead, there are several functions in OpenCV (and you can add more) that return pointers to the derived classes that implement specific filtering operations. Those pointers are then passed to \cvCppCross{FilterEngine} constructor. While the filtering operation interface uses \texttt{uchar} type, a particular implementation is not limited to 8-bit data.
 423
 424 See also: \cvCppCross{BaseColumnFilter}, \cvCppCross{BaseRowFilter}, \cvCppCross{FilterEngine},
 425     \cvCppCross{getLinearFilter}, \cvCppCross{getMorphologyFilter}
 426
 427 \cvCppFunc{BaseRowFilter}
 428 Base class for filters with single-row kernels
 429
 430 \begin{lstlisting}
 431 class BaseRowFilter
 432 {
 433 public:
 434     virtual ~BaseRowFilter();
 435
 436     // To be overriden by the user.
 437     //
 438     // runs filtering operation on the single input row
 439     // of "width" element, each element is has "cn" channels.
 440     // the filtered row is written into "dst" buffer.
 441     virtual void operator()(const uchar* src, uchar* dst,
 442                             int width, int cn) = 0;
 443     int ksize, anchor;
 444 };
 445 \end{lstlisting}
 446
 447 The class \texttt{BaseRowFilter} is the base class for filtering data using single-row kernels. The filtering does not have to be a linear operation. In general, it could be written as following:
 448
 449 \[\texttt{dst}(x,y) = F(\texttt{src}[y](x),\;\texttt{src}[y](x+1),\;...,\;\texttt{src}[y](x+\texttt{ksize.width}-1))\]
 450
 451 where $F$ is the filtering function. The class only defines the interface and is not used directly. Instead, there are several functions in OpenCV (and you can add more) that return pointers to the derived classes that implement specific filtering operations. Those pointers are then passed to \cvCppCross{FilterEngine} constructor. While the filtering operation interface uses \texttt{uchar} type, a particular implementation is not limited to 8-bit data.
 452
 453 See also: \cvCppCross{BaseColumnFilter}, \cvCppCross{Filter}, \cvCppCross{FilterEngine},
 454  \cvCppCross{getLinearRowFilter}, \cvCppCross{getMorphologyRowFilter}, \cvCppCross{getRowSumFilter}
 455
 456 \cvCppFunc{FilterEngine}
 457 Generic image filtering class
 458
 459 \begin{lstlisting}
 460 class FilterEngine
 461 {
 462 public:
 463     // empty constructor
 464     FilterEngine();
 465     // builds a 2D non-separable filter (!_filter2D.empty()) or
 466     // a separable filter (!_rowFilter.empty() && !_columnFilter.empty())
 467     // the input data type will be "srcType", the output data type will be "dstType",
 468     // the intermediate data type is "bufType".
 469     // _rowBorderType and _columnBorderType determine how the image
 470     // will be extrapolated beyond the image boundaries.
 471     // _borderValue is only used when _rowBorderType and/or _columnBorderType
 472     // == cv::BORDER_CONSTANT
 473     FilterEngine(const Ptr<BaseFilter>& _filter2D,
 474                  const Ptr<BaseRowFilter>& _rowFilter,
 475                  const Ptr<BaseColumnFilter>& _columnFilter,
 476                  int srcType, int dstType, int bufType,
 477                  int _rowBorderType=BORDER_REPLICATE,
 478                  int _columnBorderType=-1, // use _rowBorderType by default
 479                  const Scalar& _borderValue=Scalar());
 480     virtual ~FilterEngine();
 481     // separate function for the engine initialization
 482     void init(const Ptr<BaseFilter>& _filter2D,
 483               const Ptr<BaseRowFilter>& _rowFilter,
 484               const Ptr<BaseColumnFilter>& _columnFilter,
 485               int srcType, int dstType, int bufType,
 486               int _rowBorderType=BORDER_REPLICATE, int _columnBorderType=-1,
 487               const Scalar& _borderValue=Scalar());
 488     // starts filtering of the ROI in an image of size "wholeSize".
 489     // returns the starting y-position in the source image.
 490     virtual int start(Size wholeSize, Rect roi, int maxBufRows=-1);
 491     // alternative form of start that takes the image
 492     // itself instead of "wholeSize". Set isolated to true to pretend that
 493     // there are no real pixels outside of the ROI
 494     // (so that the pixels will be extrapolated using the specified border modes)
 495     virtual int start(const Mat& src, const Rect& srcRoi=Rect(0,0,-1,-1),
 496                       bool isolated=false, int maxBufRows=-1);
 497     // processes the next portion of the source image,
 498     // "srcCount" rows starting from "src" and
 499     // stores the results to "dst".
 500     // returns the number of produced rows
 501     virtual int proceed(const uchar* src, int srcStep, int srcCount,
 502                         uchar* dst, int dstStep);
 503     // higher-level function that processes the whole
 504     // ROI or the whole image with a single call
 505     virtual void apply( const Mat& src, Mat& dst,
 506                         const Rect& srcRoi=Rect(0,0,-1,-1),
 507                         Point dstOfs=Point(0,0),
 508                         bool isolated=false);
 509     bool isSeparable() const { return filter2D.empty(); }
 510     // how many rows from the input image are not yet processed
 511     int remainingInputRows() const;
 512     // how many output rows are not yet produced
 513     int remainingOutputRows() const;
 514     ...
 515     // the starting and the ending rows in the source image
 516     int startY, endY;
 517
 518     // pointers to the filters
 519     Ptr<BaseFilter> filter2D;
 520     Ptr<BaseRowFilter> rowFilter;
 521     Ptr<BaseColumnFilter> columnFilter;
 522 };
 523 \end{lstlisting}
 524
 525 The class \texttt{FilterEngine} can be used to apply an arbitrary filtering operation to an image.
 526 It contains all the necessary intermediate buffers, it computes extrapolated values
 527 of the "virtual" pixels outside of the image etc. Pointers to the initialized \texttt{FilterEngine} instances
 528 are returned by various \texttt{create*Filter} functions, see below, and they are used inside high-level functions such as \cvCppCross{filter2D}, \cvCppCross{erode}, \cvCppCross{dilate} etc, that is, the class is the workhorse in many of OpenCV filtering functions.
 529
 530 This class makes it easier (though, maybe not very easy yet) to combine filtering operations with other operations, such as color space conversions, thresholding, arithmetic operations, etc. By combining several operations together you can get much better performance because your data will stay in cache. For example, below is the implementation of Laplace operator for a floating-point images, which is a simplified implementation of \cvCppCross{Laplacian}:
 531
 532 \begin{lstlisting}
 533 void laplace_f(const Mat& src, Mat& dst)
 534 {
 535     CV_Assert( src.type() == CV_32F );
 536     dst.create(src.size(), src.type());
 537
 538     // get the derivative and smooth kernels for d2I/dx2.
 539     // for d2I/dy2 we could use the same kernels, just swapped
 540     Mat kd, ks;
 541     getSobelKernels( kd, ks, 2, 0, ksize, false, ktype );
 542
 543     // let's process 10 source rows at once
 544     int DELTA = std::min(10, src.rows);
 545     Ptr<FilterEngine> Fxx = createSeparableLinearFilter(src.type(),
 546         dst.type(), kd, ks, Point(-1,-1), 0, borderType, borderType, Scalar() );
 547     Ptr<FilterEngine> Fyy = createSeparableLinearFilter(src.type(),
 548         dst.type(), ks, kd, Point(-1,-1), 0, borderType, borderType, Scalar() );
 549
 550     int y = Fxx->start(src), dsty = 0, dy = 0;
 551     Fyy->start(src);
 552     const uchar* sptr = src.data + y*src.step;
 553
 554     // allocate the buffers for the spatial image derivatives;
 555     // the buffers need to have more than DELTA rows, because at the
 556     // last iteration the output may take max(kd.rows-1,ks.rows-1)
 557     // rows more than the input.
 558     Mat Ixx( DELTA + kd.rows - 1, src.cols, dst.type() );
 559     Mat Iyy( DELTA + kd.rows - 1, src.cols, dst.type() );
 560
 561     // inside the loop we always pass DELTA rows to the filter
 562     // (note that the "proceed" method takes care of possibe overflow, since
 563     // it was given the actual image height in the "start" method)
 564     // on output we can get:
 565     //  * < DELTA rows (the initial buffer accumulation stage)
 566     //  * = DELTA rows (settled state in the middle)
 567     //  * > DELTA rows (then the input image is over, but we generate
 568     //                  "virtual" rows using the border mode and filter them)
 569     // this variable number of output rows is dy.
 570     // dsty is the current output row.
 571     // sptr is the pointer to the first input row in the portion to process
 572     for( ; dsty < dst.rows; sptr += DELTA*src.step, dsty += dy )
 573     {
 574         Fxx->proceed( sptr, (int)src.step, DELTA, Ixx.data, (int)Ixx.step );
 575         dy = Fyy->proceed( sptr, (int)src.step, DELTA, d2y.data, (int)Iyy.step );
 576         if( dy > 0 )
 577         {
 578             Mat dstripe = dst.rowRange(dsty, dsty + dy);
 579             add(Ixx.rowRange(0, dy), Iyy.rowRange(0, dy), dstripe);
 580         }
 581     }
 582 }
 583 \end{lstlisting}
 584
 585 If you do not need that much control of the filtering process, you can simply use the \texttt{FilterEngine::apply} method. Here is how the method is actually implemented:
 586
 587 \begin{lstlisting}
 588 void FilterEngine::apply(const Mat& src, Mat& dst,
 589     const Rect& srcRoi, Point dstOfs, bool isolated)
 590 {
 591     // check matrix types
 592     CV_Assert( src.type() == srcType && dst.type() == dstType );
 593
 594     // handle the "whole image" case
 595     Rect _srcRoi = srcRoi;
 596     if( _srcRoi == Rect(0,0,-1,-1) )
 597         _srcRoi = Rect(0,0,src.cols,src.rows);
 598
 599     // check if the destination ROI is inside the dst.
 600     // and FilterEngine::start will check if the source ROI is inside src.
 601     CV_Assert( dstOfs.x >= 0 && dstOfs.y >= 0 &&
 602         dstOfs.x + _srcRoi.width <= dst.cols &&
 603         dstOfs.y + _srcRoi.height <= dst.rows );
 604
 605     // start filtering
 606     int y = start(src, _srcRoi, isolated);
 607
 608     // process the whole ROI. Note that "endY - startY" is the total number
 609     // of the source rows to process
 610     // (including the possible rows outside of srcRoi but inside the source image)
 611     proceed( src.data + y*src.step,
 612              (int)src.step, endY - startY,
 613              dst.data + dstOfs.y*dst.step +
 614              dstOfs.x*dst.elemSize(), (int)dst.step );
 615 }
 616 \end{lstlisting}
 617
 618 Unlike the earlier versions of OpenCV, now the filtering operations fully support the notion of image ROI, that is, pixels outside of the ROI but inside the image can be used in the filtering operations. For example, you can take a ROI of a single pixel and filter it - that will be a filter response at that particular pixel (however, it's possible to emulate the old behavior by passing \texttt{isolated=false} to \texttt{FilterEngine::start} or \texttt{FilterEngine::apply}). You can pass the ROI explicitly to \texttt{FilterEngine::apply}, or construct a new matrix headers:
 619
 620 \begin{lstlisting}
 621 // compute dI/dx derivative at src(x,y)
 622
 623 // method 1:
 624 // form a matrix header for a single value
 625 float val1 = 0;
 626 Mat dst1(1,1,CV_32F,&val1);
 627
 628 Ptr<FilterEngine> Fx = createDerivFilter(CV_32F, CV_32F,
 629                         1, 0, 3, BORDER_REFLECT_101);
 630 Fx->apply(src, Rect(x,y,1,1), Point(), dst1);
 631
 632 // method 2:
 633 // form a matrix header for a single value
 634 float val2 = 0;
 635 Mat dst2(1,1,CV_32F,&val2);
 636
 637 Mat pix_roi(src, Rect(x,y,1,1));
 638 Sobel(pix_roi, dst2, dst2.type(), 1, 0, 3, 1, 0, BORDER_REFLECT_101);
 639
 640 printf("method1 = %g, method2 = %g\n", val1, val2);
 641 \end{lstlisting}
 642
 643 Note on the data types. As it was mentioned in \cvCppCross{BaseFilter} description, the specific filters can process data of any type, despite that \texttt{Base*Filter::operator()} only takes \texttt{uchar} pointers and no information about the actual types. To make it all work, the following rules are used:
 644
 645 \begin{itemize}
 646     \item in case of separable filtering \texttt{FilterEngine::rowFilter} applied first. It transforms the input image data (of type \texttt{srcType}) to the intermediate results stored in the internal buffers (of type \texttt{bufType}). Then these intermediate results are processed \emph{as single-channel data} with \texttt{FilterEngine::columnFilter} and stored in the output image (of type \texttt{dstType}). Thus, the input type for \texttt{rowFilter} is \texttt{srcType} and the output type is \texttt{bufType}; the input type for \texttt{columnFilter} is \texttt{CV\_MAT\_DEPTH(bufType)} and the output type is \texttt{CV\_MAT\_DEPTH(dstType)}.
 647
 648     \item in case of non-separable filtering \texttt{bufType} must be the same as \texttt{srcType}. The source data is copied to the temporary buffer if needed and then just passed to \texttt{FilterEngine::filter2D}. That is, the input type for \texttt{filter2D} is \texttt{srcType} (=\texttt{bufType}) and the output type is \texttt{dstType}.
 649 \end{itemize}
 650
 651 See also: \cvCppCross{BaseColumnFilter}, \cvCppCross{BaseFilter}, \cvCppCross{BaseRowFilter}, \cvCppCross{createBoxFilter},
 652 \cvCppCross{createDerivFilter}, \cvCppCross{createGaussianFilter}, \cvCppCross{createLinearFilter},
 653 \cvCppCross{createMorphologyFilter}, \cvCppCross{createSeparableLinearFilter}
 654
 655 \cvCppFunc{bilateralFilter}
 656 Applies bilateral filter to the image
 657
 658 \cvdefCpp{void bilateralFilter( const Mat\& src, Mat\& dst, int d,\par
 659                       double sigmaColor, double sigmaSpace,\par
 660                       int borderType=BORDER\_DEFAULT );}
 661 \begin{description}
 662 \cvarg{src}{The source 8-bit or floating-point, 1-channel or 3-channel image}
 663 \cvarg{dst}{The destination image; will have the same size and the same type as \texttt{src}}
 664 \cvarg{d}{The diameter of each pixel neighborhood, that is used during filtering. If it is non-positive, it's computed from \texttt{sigmaSpace}}
 665 \cvarg{sigmaColor}{Filter sigma in the color space. Larger value of the parameter means that farther colors within the pixel neighborhood (see \texttt{sigmaSpace}) will be mixed together, resulting in larger areas of semi-equal color}
 666 \cvarg{sigmaSpace}{Filter sigma in the coordinate space. Larger value of the parameter means that farther pixels will influence each other (as long as their colors are close enough; see \texttt{sigmaColor}). Then \texttt{d>0}, it specifies the neighborhood size regardless of \texttt{sigmaSpace}, otherwise \texttt{d} is proportional to \texttt{sigmaSpace}}
 667 \end{description}
 668
 669 The function applies bilateral filtering to the input image, as described in
 670 \url{http://www.dai.ed.ac.uk/CVonline/LOCAL\_COPIES/MANDUCHI1/Bilateral\_Filtering.html}
 671
 672 \cvCppFunc{blur}
 673 Smoothes image using normalized box filter
 674
 675 \cvdefCpp{void blur( const Mat\& src, Mat\& dst,\par
 676            Size ksize, Point anchor=Point(-1,-1),\par
 677            int borderType=BORDER\_DEFAULT );}
 678 \begin{description}
 679 \cvarg{src}{The source image}
 680 \cvarg{dst}{The destination image; will have the same size and the same type as \texttt{src}}
 681 \cvarg{ksize}{The smoothing kernel size}
 682 \cvarg{anchor}{The anchor point. The default value \texttt{Point(-1,-1)} means that the anchor is at the kernel center}
 683 \cvarg{borderType}{The border mode used to extrapolate pixels outside of the image}
 684 \end{description}
 685
 686 The function smoothes the image using the kernel:
 687
 688 \[ \texttt{K} = \frac{1}{\texttt{ksize.width*ksize.height}}
 689 \begin{bmatrix}
 690 1 & 1 & 1 & \cdots & 1 & 1 \\
 691 1 & 1 & 1 & \cdots & 1 & 1 \\
 692 \hdotsfor{6} \\
 693 1 & 1 & 1 & \cdots & 1 & 1 \\
 694 \end{bmatrix}
 695 \]
 696
 697 The call \texttt{blur(src, dst, ksize, anchor, borderType)} is equivalent to
 698 \texttt{boxFilter(src, dst, src.type(), anchor, true, borderType)}.
 699
 700 See also: \cvCppCross{boxFilter}, \cvCppCross{bilateralFilter}, \cvCppCross{GaussianBlur}, \cvCppCross{medianBlur}.
 701
 702 \cvCppFunc{borderInterpolate}
 703 Computes source location of extrapolated pixel
 704
 705 \cvdefCpp{int borderInterpolate( int p, int len, int borderType );}
 706 \begin{description}
 707 \cvarg{p}{0-based coordinate of the extrapolated pixel along one of the axes, likely <0 or >=\texttt{len}}
 708 \cvarg{len}{length of the array along the corresponding axis}
 709 \cvarg{borderType}{the border type, one of the \texttt{BORDER\_*}, except for \texttt{BORDER\_TRANSPARENT} and \texttt{BORDER\_ISOLATED}. When \texttt{borderType==BORDER\_CONSTANT} the function always returns -1, regardless of \texttt{p} and \texttt{len}}
 710 \end{description}
 711
 712 The function computes and returns the coordinate of the donor pixel, corresponding to the specified extrapolated pixel when using the specified extrapolation border mode. For example, if we use \texttt{BORDER\_WRAP} mode in the horizontal direction, \texttt{BORDER\_REFLECT\_101} in the vertical direction and want to compute value of the "virtual" pixel \texttt{Point(-5, 100)} in a floating-point image \texttt{img}, it will be
 713
 714 \begin{lstlisting}
 715 float val = img.at<float>(borderInterpolate(100, img.rows, BORDER_REFLECT_101),
 716                           borderInterpolate(-5, img.cols, BORDER_WRAP));
 717 \end{lstlisting}
 718
 719 Normally, the function is not called directly; it is used inside \cvCppCross{FilterEngine} and \cvCppCross{copyMakeBorder} to compute tables for quick extrapolation.
 720
 721 See also: \cvCppCross{FilterEngine}, \cvCppCross{copyMakeBorder}
 722
 723 \cvCppFunc{boxFilter}
 724 Smoothes image using box filter
 725
 726 \cvdefCpp{void boxFilter( const Mat\& src, Mat\& dst, int ddepth,\par
 727                 Size ksize, Point anchor=Point(-1,-1),\par
 728                 bool normalize=true,\par
 729                 int borderType=BORDER\_DEFAULT );}
 730 \begin{description}
 731 \cvarg{src}{The source image}
 732 \cvarg{dst}{The destination image; will have the same size and the same type as \texttt{src}}
 733 \cvarg{ksize}{The smoothing kernel size}
 734 \cvarg{anchor}{The anchor point. The default value \texttt{Point(-1,-1)} means that the anchor is at the kernel center}
 735 \cvarg{normalize}{Indicates, whether the kernel is normalized by its area or not}
 736 \cvarg{borderType}{The border mode used to extrapolate pixels outside of the image}
 737 \end{description}
 738
 739 The function smoothes the image using the kernel:
 740
 741 \[ \texttt{K} = \alpha
 742 \begin{bmatrix}
 743 1 & 1 & 1 & \cdots & 1 & 1 \\
 744 1 & 1 & 1 & \cdots & 1 & 1 \\
 745 \hdotsfor{6} \\
 746 1 & 1 & 1 & \cdots & 1 & 1
 747 \end{bmatrix}
 748 \]
 749
 750 where
 751
 752 \[\alpha=\fork
 753 {\frac{1}{\texttt{ksize.width*ksize.height}}}{when \texttt{normalize=true}}
 754 {1}{otherwise} \]
 755
 756 Unnormalized box filter is useful for computing various integral characteristics over each pixel neighborhood, such as covariation matrices of image derivatives (used in dense optical flow algorithms, \hyperref[conerHarris]{Harris corner detector} etc.). If you need to compute pixel sums over variable-size windows, use \cvCppCross{integral}.
 757
 758 See also: \cvCppCross{boxFilter}, \cvCppCross{bilateralFilter}, \cvCppCross{GaussianBlur}, \cvCppCross{medianBlur}, \cvCppCross{integral}.
 759
 760 \cvCppFunc{buildPyramid}
 761 Constructs Gaussian pyramid for an image
 762
 763 \cvdefCpp{void buildPyramid( const Mat\& src, vector<Mat>\& dst, int maxlevel );}
 764 \begin{description}
 765 \cvarg{src}{The source image; check \cvCppCross{pyrDown} for the list of supported types}
 766 \cvarg{dst}{The destination vector of \texttt{maxlevel+1} images of the same type as \texttt{src};
 767 \texttt{dst[0]} will be the same as \texttt{src}, \texttt{dst[1]} is the next pyramid layer,
 768 a smoothed and down-sized \texttt{src} etc.}
 769 \cvarg{maxlevel}{The 0-based index of the last (i.e. the smallest) pyramid layer; it must be non-negative}
 770 \end{description}
 771
 772 The function constructs a vector of images and builds the gaussian pyramid by recursively applying \cvCppCross{pyrDown} to the previously built pyramid layers, starting from \texttt{dst[0]==src}.
 773
 774 \cvCppFunc{copyMakeBorder}
 775 Forms a border around the image
 776
 777 \cvdefCpp{void copyMakeBorder( const Mat\& src, Mat\& dst,\par
 778                     int top, int bottom, int left, int right,\par
 779                     int borderType, const Scalar\& value=Scalar() );}
 780 \begin{description}
 781 \cvarg{src}{The source image}
 782 \cvarg{dst}{The destination image; will have the same type as \texttt{src} and the size \texttt{Size(src.cols+left+right, src.rows+top+bottom)}}
 783 \cvarg{top, bottom, left, right}{Specify how much pixels in each direction from the source image rectangle one needs to extrapolate, e.g. \texttt{top=1, bottom=1, left=1, right=1} mean that 1 pixel-wide border needs to be built}
 784 \cvarg{borderType}{The border type; see \cvCppCross{borderInterpolate}}
 785 \cvarg{value}{The border value if \texttt{borderType==BORDER\_CONSTANT}}
 786 \end{description}
 787
 788 The function copies the source image into the middle of the destination image. The areas to the left, to the right, above and below the copied source image will be filled with extrapolated pixels. This is not what \cvCppCross{FilterEngine} or based on it filtering functions do (they extrapolate pixels on-fly), but what other more complex functions, including your own, may do to simplify image boundary handling.
 789
 790 The function supports the mode when \texttt{src} is already in the middle of \texttt{dst}. In this case the function does not copy \texttt{src} itself, but simply constructs the border, e.g.:
 791
 792 \begin{lstlisting}
 793 // let border be the same in all directions
 794 int border=2;
 795 // constructs a larger image to fit both the image and the border
 796 Mat gray_buf(rgb.rows + border*2, rgb.cols + border*2, rgb.depth());
 797 // select the middle part of it w/o copying data
 798 Mat gray(gray_canvas, Rect(border, border, rgb.cols, rgb.rows));
 799 // convert image from RGB to grayscale
 800 cvtColor(rgb, gray, CV_RGB2GRAY);
 801 // form a border in-place
 802 copyMakeBorder(gray, gray_buf, border, border,
 803                border, border, BORDER_REPLICATE);
 804 // now do some custom filtering ...
 805 ...
 806 \end{lstlisting}
 807
 808 See also: \cvCppCross{borderInterpolate}
 809
 810 \cvCppFunc{createBoxFilter}
 811 Returns box filter engine
 812
 813 \cvdefCpp{Ptr<FilterEngine> createBoxFilter( int srcType, int dstType,\par
 814                                  Size ksize, Point anchor=Point(-1,-1),\par
 815                                  bool normalize=true,\par
 816                                  int borderType=BORDER\_DEFAULT);\newline
 817 Ptr<BaseRowFilter> getRowSumFilter(int srcType, int sumType,\par
 818                                    int ksize, int anchor=-1);\newline
 819 Ptr<BaseColumnFilter> getColumnSumFilter(int sumType, int dstType,\par
 820                                    int ksize, int anchor=-1, double scale=1);}
 821 \begin{description}
 822 \cvarg{srcType}{The source image type}
 823 \cvarg{sumType}{The intermediate horizontal sum type; must have as many channels as \texttt{srcType}}
 824 \cvarg{dstType}{The destination image type; must have as many channels as \texttt{srcType}}
 825 \cvarg{ksize}{The aperture size}
 826 \cvarg{anchor}{The anchor position with the kernel; negative values mean that the anchor is at the kernel center}
 827 \cvarg{normalize}{Whether the sums are normalized or not; see \cvCppCross{boxFilter}}
 828 \cvarg{scale}{Another way to specify normalization in lower-level \texttt{getColumnSumFilter}}
 829 \cvarg{borderType}{Which border type to use; see \cvCppCross{borderInterpolate}}
 830 \end{description}
 831
 832 The function is a convenience function that retrieves horizontal sum primitive filter with \cvCppCross{getRowSumFilter}, vertical sum filter with \cvCppCross{getColumnSumFilter}, constructs new \cvCppCross{FilterEngine} and passes both of the primitive filters there. The constructed filter engine can be used for image filtering with normalized or unnormalized box filter.
 833
 834 The function itself is used by \cvCppCross{blur} and \cvCppCross{boxFilter}.
 835
 836 See also: \cvCppCross{FilterEngine}, \cvCppCross{blur}, \cvCppCross{boxFilter}.
 837
 838 \cvCppFunc{createDerivFilter}
 839 Returns engine for computing image derivatives
 840
 841 \cvdefCpp{Ptr<FilterEngine> createDerivFilter( int srcType, int dstType,\par
 842                                      int dx, int dy, int ksize,\par
 843                                      int borderType=BORDER\_DEFAULT );}
 844 \begin{description}
 845 \cvarg{srcType}{The source image type}
 846 \cvarg{dstType}{The destination image type; must have as many channels as \texttt{srcType}}
 847 \cvarg{dx}{The derivative order in respect with x}
 848 \cvarg{dy}{The derivative order in respect with y}
 849 \cvarg{ksize}{The aperture size; see \cvCppCross{getDerivKernels}}
 850 \cvarg{borderType}{Which border type to use; see \cvCppCross{borderInterpolate}}
 851 \end{description}
 852
 853 The function \cvCppCross{createDerivFilter} is a small convenience function that retrieves linear filter coefficients for computing image derivatives using \cvCppCross{getDerivKernels} and then creates a separable linear filter with \cvCppCross{createSeparableLinearFilter}. The function is used by \cvCppCross{Sobel} and \cvCppCross{Scharr}.
 854
 855 See also: \cvCppCross{createSeparableLinearFilter}, \cvCppCross{getDerivKernels}, \cvCppCross{Scharr}, \cvCppCross{Sobel}.
 856
 857 \cvCppFunc{createGaussianFilter}
 858 Returns engine for smoothing images with a Gaussian filter
 859
 860 \cvdefCpp{Ptr<FilterEngine> createGaussianFilter( int type, Size ksize,\par
 861                                    double sigmaX, double sigmaY=0,\par
 862                                    int borderType=BORDER\_DEFAULT);}
 863 \begin{description}
 864 \cvarg{type}{The source and the destination image type}
 865 \cvarg{ksize}{The aperture size; see \cvCppCross{getGaussianKernel}}
 866 \cvarg{sigmaX}{The Gaussian sigma in the horizontal direction; see \cvCppCross{getGaussianKernel}}
 867 \cvarg{sigmaY}{The Gaussian sigma in the vertical direction; if 0, then $\texttt{sigmaY}\leftarrow\texttt{sigmaX}$}
 868 \cvarg{borderType}{Which border type to use; see \cvCppCross{borderInterpolate}}
 869 \end{description}
 870
 871 The function \cvCppCross{createGaussianFilter} computes Gaussian kernel coefficients and then returns separable linear filter for that kernel. The function is used by \cvCppCross{GaussianBlur}. Note that while the function takes just one data type, both for input and output, you can pass by this limitation by calling \cvCppCross{getGaussianKernel} and then \cvCppCross{createSeparableFilter} directly.
 872
 873 See also: \cvCppCross{createSeparableLinearFilter}, \cvCppCross{getGaussianKernel}, \cvCppCross{GaussianBlur}.
 874
 875 \cvCppFunc{createLinearFilter}
 876 Creates non-separable linear filter engine
 877
 878 \cvdefCpp{Ptr<FilterEngine> createLinearFilter(int srcType, int dstType,\par
 879                const Mat\& kernel, Point \_anchor=Point(-1,-1),\par
 880                double delta=0, int rowBorderType=BORDER\_DEFAULT,\par
 881                int columnBorderType=-1, const Scalar\& borderValue=Scalar());\newline
 882 Ptr<BaseFilter> getLinearFilter(int srcType, int dstType,\par
 883                                const Mat\& kernel,\par
 884                                Point anchor=Point(-1,-1),\par
 885                                double delta=0, int bits=0);}
 886 \begin{description}
 887 \cvarg{srcType}{The source image type}
 888 \cvarg{dstType}{The destination image type; must have as many channels as \texttt{srcType}}
 889 \cvarg{kernel}{The 2D array of filter coefficients}
 890 \cvarg{anchor}{The anchor point within the kernel; special value \texttt{Point(-1,-1)} means that the anchor is at the kernel center}
 891 \cvarg{delta}{The value added to the filtered results before storing them}
 892 \cvarg{bits}{When the kernel is an integer matrix representing fixed-point filter coefficients,
 893              the parameter specifies the number of the fractional bits}
 894 \cvarg{rowBorderType, columnBorderType}{The pixel extrapolation methods in the horizontal and the vertical directions; see \cvCppCross{borderInterpolate}}
 895 \cvarg{borderValue}{Used in case of constant border}
 896 \end{description}
 897
 898 The function returns pointer to 2D linear filter for the specified kernel, the source array type and the destination array type. The function is a higher-level function that calls \texttt{getLinearFilter} and passes the retrieved 2D filter to \cvCppCross{FilterEngine} constructor.
 899
 900 See also: \cvCppCross{createSeparableLinearFilter}, \cvCppCross{FilterEngine}, \cvCppCross{filter2D}
 901
 902 \cvCppFunc{createMorphologyFilter}
 903 Creates engine for non-separable morphological operations
 904
 905 \cvdefCpp{Ptr<FilterEngine> createMorphologyFilter(int op, int type,\par
 906     const Mat\& element, Point anchor=Point(-1,-1),\par
 907     int rowBorderType=BORDER\_CONSTANT,\par
 908     int columnBorderType=-1,\par
 909     const Scalar\& borderValue=morphologyDefaultBorderValue());\newline
 910 Ptr<BaseFilter> getMorphologyFilter(int op, int type, const Mat\& element,\par
 911                                     Point anchor=Point(-1,-1));\newline
 912 Ptr<BaseRowFilter> getMorphologyRowFilter(int op, int type,\par
 913                                           int esize, int anchor=-1);\newline
 914 Ptr<BaseColumnFilter> getMorphologyColumnFilter(int op, int type,\par
 915                                                 int esize, int anchor=-1);\newline
 916 static inline Scalar morphologyDefaultBorderValue()\par
 917 { return Scalar::all(DBL\_MAX); }}
 918 \begin{description}
 919 \cvarg{op}{The morphology operation id, \texttt{MORPH\_ERODE} or \texttt{MORPH\_DILATE}}
 920 \cvarg{type}{The input/output image type}
 921 \cvarg{element}{The 2D 8-bit structuring element for the morphological operation. Non-zero elements indicate the pixels that belong to the element}
 922 \cvarg{esize}{The horizontal or vertical structuring element size for separable morphological operations}
 923 \cvarg{anchor}{The anchor position within the structuring element; negative values mean that the anchor is at the center}
 924 \cvarg{rowBorderType, columnBorderType}{The pixel extrapolation methods in the horizontal and the vertical directions; see \cvCppCross{borderInterpolate}}
 925 \cvarg{borderValue}{The border value in case of a constant border. The default value,\\ \texttt{morphologyDefaultBorderValue}, has the special meaning. It is transformed $+\inf$ for the erosion and to $-\inf$ for the dilation, which means that the minimum (maximum) is effectively computed only over the pixels that are inside the image.}
 926 \end{description}
 927
 928 The functions construct primitive morphological filtering operations or a filter engine based on them. Normally it's enough to use \cvCppCross{createMorphologyFilter} or even higher-level \cvCppCross{erode}, \cvCppCross{dilate} or \cvCppCross{morphologyEx}, Note, that \cvCppCross{createMorphologyFilter} analyses the structuring element shape and builds a separable morphological filter engine when the structuring element is square.
 929
 930 See also: \cvCppCross{erode}, \cvCppCross{dilate}, \cvCppCross{morphologyEx}, \cvCppCross{FilterEngine}
 931
 932 \cvCppFunc{createSeparableLinearFilter}
 933 Creates engine for separable linear filter
 934
 935 \cvdefCpp{Ptr<FilterEngine> createSeparableLinearFilter(int srcType, int dstType,\par
 936                          const Mat\& rowKernel, const Mat\& columnKernel,\par
 937                          Point anchor=Point(-1,-1), double delta=0,\par
 938                          int rowBorderType=BORDER\_DEFAULT,\par
 939                          int columnBorderType=-1,\par
 940                          const Scalar\& borderValue=Scalar());\newline
 941 Ptr<BaseColumnFilter> getLinearColumnFilter(int bufType, int dstType,\par
 942                          const Mat\& columnKernel, int anchor,\par
 943                          int symmetryType, double delta=0,\par
 944                          int bits=0);\newline
 945 Ptr<BaseRowFilter> getLinearRowFilter(int srcType, int bufType,\par
 946                          const Mat\& rowKernel, int anchor,\par
 947                          int symmetryType);}
 948 \begin{description}
 949 \cvarg{srcType}{The source array type}
 950 \cvarg{dstType}{The destination image type; must have as many channels as \texttt{srcType}}
 951 \cvarg{bufType}{The inermediate buffer type; must have as many channels as \texttt{srcType}}
 952 \cvarg{rowKernel}{The coefficients for filtering each row}
 953 \cvarg{columnKernel}{The coefficients for filtering each column}
 954 \cvarg{anchor}{The anchor position within the kernel; negative values mean that anchor is positioned at the aperture center}
 955 \cvarg{delta}{The value added to the filtered results before storing them}
 956 \cvarg{bits}{When the kernel is an integer matrix representing fixed-point filter coefficients,
 957              the parameter specifies the number of the fractional bits}
 958 \cvarg{rowBorderType, columnBorderType}{The pixel extrapolation methods in the horizontal and the vertical directions; see \cvCppCross{borderInterpolate}}
 959 \cvarg{borderValue}{Used in case of a constant border}
 960 \cvarg{symmetryType}{The type of each of the row and column kernel; see \cvCppCross{getKernelType}.}
 961 \end{description}
 962
 963 The functions construct primitive separable linear filtering operations or a filter engine based on them. Normally it's enough to use \cvCppCross{createSeparableLinearFilter} or even higher-level \cvCppCross{sepFilter2D}. The function \cvCppCross{createMorphologyFilter} is smart enough to figure out the \texttt{symmetryType} for each of the two kernels, the intermediate \texttt{bufType}, and, if the filtering can be done in integer arithmetics, the number of \texttt{bits} to encode the filter coefficients. If it does not work for you, it's possible to call \texttt{getLinearColumnFilter}, \texttt{getLinearRowFilter} directly and then pass them to \cvCppCross{FilterEngine} constructor.
 964
 965 See also: \cvCppCross{sepFilter2D}, \cvCppCross{createLinearFilter}, \cvCppCross{FilterEngine}, \cvCppCross{getKernelType}
 966
 967
 968 \cvCppFunc{dilate}
 969 Dilates an image by using a specific structuring element.
 970
 971 \cvdefCpp{void dilate( const Mat\& src, Mat\& dst, const Mat\& element,\par
 972              Point anchor=Point(-1,-1), int iterations=1,\par
 973              int borderType=BORDER\_CONSTANT,\par
 974              const Scalar\& borderValue=morphologyDefaultBorderValue() );}
 975 \begin{description}
 976 \cvarg{src}{The source image}
 977 \cvarg{dst}{The destination image. It will have the same size and the same type as \texttt{src}}
 978 \cvarg{element}{The structuring element used for dilation. If \texttt{element=Mat()}, a $3\times 3$ rectangular structuring element is used}
 979 \cvarg{anchor}{Position of the anchor within the element. The default value $(-1, -1)$ means that the anchor is at the element center}
 980 \cvarg{iterations}{The number of times dilation is applied}
 981 \cvarg{borderType}{The pixel extrapolation method; see \cvCppCross{borderInterpolate}}
 982 \cvarg{borderValue}{The border value in case of a constant border. The default value has a special meaning, see \cvCppCross{createMorphologyFilter}}
 983 \end{description}
 984
 985 The function dilates the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the maximum is taken:
 986
 987 \[
 988 \texttt{dst}(x,y) = \max_{(x',y'): \, \texttt{element}(x',y')\ne0}\texttt{src}(x+x',y+y')
 989 \]
 990
 991 The function supports the in-place mode. Dilation can be applied several (\texttt{iterations}) times. In the case of multi-channel images each channel is processed independently.
 992
 993 See also: \cvCppCross{erode}, \cvCppCross{morphologyEx}, \cvCppCross{createMorphologyFilter}
 994
 995 \cvCppFunc{erode}
 996 Erodes an image by using a specific structuring element.
 997
 998 \cvdefCpp{void erode( const Mat\& src, Mat\& dst, const Mat\& element,\par
 999             Point anchor=Point(-1,-1), int iterations=1,\par
1000             int borderType=BORDER\_CONSTANT,\par
1001             const Scalar\& borderValue=morphologyDefaultBorderValue() );}
1002 \begin{description}
1003 \cvarg{src}{The source image}
1004 \cvarg{dst}{The destination image. It will have the same size and the same type as \texttt{src}}
1005 \cvarg{element}{The structuring element used for dilation. If \texttt{element=Mat()}, a $3\times 3$ rectangular structuring element is used}
1006 \cvarg{anchor}{Position of the anchor within the element. The default value $(-1, -1)$ means that the anchor is at the element center}
1007 \cvarg{iterations}{The number of times erosion is applied}
1008 \cvarg{borderType}{The pixel extrapolation method; see \cvCppCross{borderInterpolate}}
1009 \cvarg{borderValue}{The border value in case of a constant border. The default value has a special meaning, see \cvCppCross{createMorphoogyFilter}}
1010 \end{description}
1011
1012 The function erodes the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the minimum is taken:
1013
1014 \[
1015 \texttt{dst}(x,y) = \min_{(x',y'): \, \texttt{element}(x',y')\ne0}\texttt{src}(x+x',y+y')
1016 \]
1017
1018 The function supports the in-place mode. Erosion can be applied several (\texttt{iterations}) times. In the case of multi-channel images each channel is processed independently.
1019
1020 See also: \cvCppCross{dilate}, \cvCppCross{morphologyEx}, \cvCppCross{createMorphologyFilter}
1021
1022 \cvCppFunc{filter2D}
1023 Convolves an image with the kernel
1024
1025 \cvdefCpp{void filter2D( const Mat\& src, Mat\& dst, int ddepth,\par
1026                const Mat\& kernel, Point anchor=Point(-1,-1),\par
1027                double delta=0, int borderType=BORDER\_DEFAULT );}
1028 \begin{description}
1029 \cvarg{src}{The source image}
1030 \cvarg{dst}{The destination image. It will have the same size and the same number of channels as \texttt{src}}
1031 \cvarg{ddepth}{The desired depth of the destination image. If it is negative, it will be the same as \texttt{src.depth()}}
1032 \cvarg{kernel}{Convolution kernel (or rather a correlation kernel), a single-channel floating point matrix. If you want to apply different kernels to different channels, split the image into separate color planes using \cvCppCross{split} and process them individually}
1033 \cvarg{anchor}{The anchor of the kernel that indicates the relative position of a filtered point within the kernel. The anchor should lie within the kernel. The special default value (-1,-1) means that the anchor is at the kernel center}
1034 \cvarg{delta}{The optional value added to the filtered pixels before storing them in \texttt{dst}}
1035 \cvarg{borderType}{The pixel extrapolation method; see \cvCppCross{borderInterpolate}}
1036 \end{description}
1037
1038 The function applies an arbitrary linear filter to the image. In-place operation is supported. When the aperture is partially outside the image, the function interpolates outlier pixel values according to the specified border mode.
1039
1040 The function does actually computes correlation, not the convolution:
1041
1042 \[
1043 \texttt{dst}(x,y) = \sum_{\stackrel{0\leq x' < \texttt{kernel.cols},}{0\leq y' < \texttt{kernel.rows}}} \texttt{kernel}(x',y')*\texttt{src}(x+x'-\texttt{anchor.x},y+y'-\texttt{anchor.y})
1044 \]
1045
1046 That is, the kernel is not mirrored around the anchor point. If you need a real convolution, flip the kernel using \cvCppCross{flip} and set the new anchor to \texttt{(kernel.cols - anchor.x - 1, kernel.rows - anchor.y - 1)}.
1047
1048 The function uses \hyperref[dft]{DFT}-based algorithm in case of sufficiently large kernels (~$11\times11$) and the direct algorithm (that uses the engine retrieved by \cvCppCross{createLinearFilter}) for small kernels.
1049
1050 See also: \cvCppCross{sepFilter2D}, \cvCppCross{createLinearFilter}, \cvCppCross{dft}, \cvCppCross{matchTemplate}
1051
1052 \cvCppFunc{GaussianBlur}
1053 Smoothes image using a Gaussian filter
1054
1055 \cvdefCpp{void GaussianBlur( const Mat\& src, Mat\& dst, Size ksize,\par
1056                    double sigmaX, double sigmaY=0,\par
1057                    int borderType=BORDER\_DEFAULT );}
1058 \begin{description}
1059 \cvarg{src}{The source image}
1060 \cvarg{dst}{The destination image; will have the same size and the same type as \texttt{src}}
1061 \cvarg{ksize}{The Gaussian kernel size; \texttt{ksize.width} and \texttt{ksize.height} can differ, but they both must be positive and odd. Or, they can be zero's, then they are computed from \texttt{sigma*}}
1062 \cvarg{sigmaX, sigmaY}{The Gaussian kernel standard deviations in X and Y direction. If \texttt{sigmaY} is zero, it is set to be equal to \texttt{sigmaX}. If they are both zeros, they are computed from \texttt{ksize.width} and \texttt{ksize.height}, respectively, see \cvCppCross{getGaussianKernel}. To fully control the result regardless of possible future modification of all this semantics, it is recommended to specify all of \texttt{ksize}, \texttt{sigmaX} and \texttt{sigmaY}}
1063 \cvarg{borderType}{The pixel extrapolation method; see \cvCppCross{borderInterpolate}}
1064 \end{description}
1065
1066 The function convolves the source image with the specified Gaussian kernel. In-place filtering is supported.
1067
1068 See also: \cvCppCross{sepFilter2D}, \cvCppCross{filter2D}, \cvCppCross{blur}, \cvCppCross{boxFilter}, \cvCppCross{bilateralFilter}, \cvCppCross{medianBlur}
1069
1070 \cvCppFunc{getDerivKernels}
1071 Returns filter coefficients for computing spatial image derivatives
1072
1073 \cvdefCpp{void getDerivKernels( Mat\& kx, Mat\& ky, int dx, int dy, int ksize,\par
1074                       bool normalize=false, int ktype=CV\_32F );}
1075 \begin{description}
1076 \cvarg{kx}{The output matrix of row filter coefficients; will have type \texttt{ktype}}
1077 \cvarg{ky}{The output matrix of column filter coefficients; will have type \texttt{ktype}}
1078 \cvarg{dx}{The derivative order in respect with x}
1079 \cvarg{dy}{The derivative order in respect with y}
1080 \cvarg{ksize}{The aperture size. It can be \texttt{CV\_SCHARR}, 1, 3, 5 or 7}
1081 \cvarg{normalize}{Indicates, whether to normalize (scale down) the filter coefficients or not. In theory the coefficients should have the denominator $=2^{ksize*2-dx-dy-2}$. If you are going to filter floating-point images, you will likely want to use the normalized kernels. But if you compute derivatives of a 8-bit image, store the results in 16-bit image and wish to preserve all the fractional bits, you may want to set \texttt{normalize=false}.}
1082 \cvarg{ktype}{The type of filter coefficients. It can be \texttt{CV\_32f} or \texttt{CV\_64F}}
1083 \end{description}
1084
1085 The function computes and returns the filter coefficients for spatial image derivatives. When \texttt{ksize=CV\_SCHARR}, the Scharr $3 \times 3$ kernels are generated, see \cvCppCross{Scharr}. Otherwise, Sobel kernels are generated, see \cvCppCross{Sobel}. The filters are normally passed to \cvCppCross{sepFilter2D} or to \cvCppCross{createSeparableLinearFilter}.
1086
1087 \cvCppFunc{getGaussianKernel}
1088 Returns Gaussian filter coefficients
1089
1090 \cvdefCpp{Mat getGaussianKernel( int ksize, double sigma, int ktype=CV\_64F );}
1091 \begin{description}
1092 \cvarg{ksize}{The aperture size. It should be odd ($\texttt{ksize} \mod 2 = 1$) and positive.}
1093 \cvarg{sigma}{The Gaussian standard deviation. If it is non-positive, it is computed from \texttt{ksize} as \\
1094 \texttt{sigma = 0.3*(ksize/2 - 1) + 0.8}}
1095 \cvarg{ktype}{The type of filter coefficients. It can be \texttt{CV\_32f} or \texttt{CV\_64F}}
1096 \end{description}
1097
1098 The function computes and returns the $\texttt{ksize} \times 1$ matrix of Gaussian filter coefficients:
1099
1100 \[G_i=\alpha*e^{-(i-(\texttt{ksize}-1)/2)^2/(2*\texttt{sigma})^2},\]
1101
1102 where $i=0..\texttt{ksize}-1$ and $\alpha$ is the scale factor chosen so that $\sum_i G_i=1$
1103
1104 Two of such generated kernels can be passed to \cvCppCross{sepFilter2D} or to \cvCppCross{createSeparableLinearFilter} that will automatically detect that these are smoothing kernels and handle them accordingly. Also you may use the higher-level \cvCppCross{GaussianBlur}.
1105
1106 See also: \cvCppCross{sepFilter2D}, \cvCppCross{createSeparableLinearFilter}, \cvCppCross{getDerivKernels}, \cvCppCross{getStructuringElement}, \cvCppCross{GaussianBlur}.
1107
1108 \cvCppFunc{getKernelType}
1109 Returns the kernel type
1110
1111 \cvdefCpp{int getKernelType(const Mat\& kernel, Point anchor);}
1112
1113 \begin{description}
1114 \cvarg{kernel}{1D array of the kernel coefficients to analyze}
1115 \cvarg{anchor}{The anchor position within the kernel}
1116 \end{description}
1117
1118 The function analyzes the kernel coefficients and returns the corresponding kernel type:
1119 \begin{description}
1120     \cvarg{KERNEL\_GENERAL}{Generic kernel - when there is no any type of symmetry or other properties}
1121     \cvarg{KERNEL\_SYMMETRICAL}{The kernel is symmetrical: $\texttt{kernel}_i == \texttt{kernel}_{ksize-i-1}$ and the anchor is at the center}
1122     \cvarg{KERNEL\_ASYMMETRICAL}{The kernel is asymmetrical: $\texttt{kernel}_i == -\texttt{kernel}_{ksize-i-1}$ and the anchor is at the center}
1123     \cvarg{KERNEL\_SMOOTH}{All the kernel elements are non-negative and sum to 1. E.g. the Gaussian kernel is both smooth kernel and symmetrical, so the function will return \texttt{KERNEL\_SMOOTH | KERNEL\_SYMMETRICAL}}
1124     \cvarg{KERNEL\_INTEGER}{Al the kernel coefficients are integer numbers. This flag can be combined with \texttt{KERNEL\_SYMMETRICAL} or \texttt{KERNEL\_ASYMMETRICAL}}
1125 \end{description}
1126
1127 \cvCppFunc{getStructuringElement}
1128 Returns the structuring element of the specified size and shape for morphological operations
1129
1130 \cvdefCpp{Mat getStructuringElement(int shape, Size esize,\par Point anchor=Point(-1,-1));}
1131
1132 \begin{description}
1133 \cvarg{shape}{The element shape, one of:
1134
1135     \begin{itemize}
1136         \item \texttt{MORPH\_RECT} - rectangular structuring element
1137             \[E_{ij}=1\]
1138
1139         \item \texttt{MORPH\_ELLIPSE} - elliptic structuring element, i.e. a filled
1140             ellipse inscribed into the rectangle
1141             \texttt{Rect(0, 0, esize.width, 0.esize.height)}
1142
1143         \item \texttt{MORPH\_CROSS} - cross-shaped structuring element:
1144             \[
1145             E_{ij} = \fork
1146             {1}{if i=\texttt{anchor.y} or j=\texttt{anchor.x}}
1147             {0}{otherwise}
1148             \]
1149
1150     \end{itemize}}
1151 \cvarg{esize}{Size of the structuring element}
1152 \cvarg{anchor}{The anchor position within the element. The default value $(-1, -1)$ means that the anchor is at the center. Note that only the cross-shaped element's shape depends on the anchor position; in other cases the anchor just regulates by how much the result of the morphological operation is shifted}
1153 \end{description}
1154
1155 The function constructs and returns the structuring element that can be then passed to \cvCppCross{createMorphologyFilter}, \cvCppCross{erode}, \cvCppCross{dilate} or \cvCppCross{morphologyEx}. But also you can construct an arbitrary binary mask yourself and use it as the structuring element.
1156
1157 \cvCppFunc{medianBlur}
1158 Smoothes image using median filter
1159
1160 \cvdefCpp{void medianBlur( const Mat\& src, Mat\& dst, int ksize );}
1161 \begin{description}
1162 \cvarg{src}{The source 1-, 3- or 4-channel image. When \texttt{ksize} is 3 or 5, the image depth should be \texttt{CV\_8U}, \texttt{CV\_16U} or \texttt{CV\_32F}. For larger aperture sizes it can only be \texttt{CV\_8U}}
1163 \cvarg{dst}{The destination array; will have the same size and the same type as \texttt{src}}
1164 \cvarg{ksize}{The aperture linear size. It must be odd and more than 1, i.e. 3, 5, 7 ...}
1165 \end{description}
1166
1167 The function smoothes image using the median filter with $\texttt{ksize} \times \texttt{ksize}$ aperture. Each channel of a multi-channel image is processed independently. In-place operation is supported.
1168
1169 See also: \cvCppCross{bilateralFilter}, \cvCppCross{blur}, \cvCppCross{boxFilter}, \cvCppCross{GaussianBlur}
1170
1171 \cvCppFunc{morphologyEx}
1172 Performs advanced morphological transformations
1173
1174 \cvdefCpp{void morphologyEx( const Mat\& src, Mat\& dst, \par
1175                    int op, const Mat\& element,\par
1176                    Point anchor=Point(-1,-1), int iterations=1,\par
1177                    int borderType=BORDER\_CONSTANT,\par
1178                    const Scalar\& borderValue=morphologyDefaultBorderValue() );}
1179 \begin{description}
1180 \cvarg{src}{Source image}
1181 \cvarg{dst}{Destination image. It will have the same size and the same type as \texttt{src}}
1182 \cvarg{element}{Structuring element}
1183 \cvarg{op}{Type of morphological operation, one of the following:
1184 \begin{description}
1185 \cvarg{MORPH\_OPEN}{opening}
1186 \cvarg{MORPH\_CLOSE}{closing}
1187 \cvarg{MORPH\_GRADIENT}{morphological gradient}
1188 \cvarg{MORPH\_TOPHAT}{"top hat"}
1189 \cvarg{MORPH\_BLACKHAT}{"black hat"}
1190 \end{description}}
1191 \cvarg{iterations}{Number of times erosion and dilation are applied}
1192 \cvarg{borderType}{The pixel extrapolation method; see \cvCppCross{borderInterpolate}}
1193 \cvarg{borderValue}{The border value in case of a constant border. The default value has a special meaning, see \cvCppCross{createMorphoogyFilter}}
1194 \end{description}
1195
1196 The function can perform advanced morphological transformations using erosion and dilation as basic operations.
1197
1198 Opening:
1199
1200 \[
1201 \texttt{dst}=\mathrm{open}(\texttt{src},\texttt{element})=\mathrm{dilate}(\mathrm{erode}(\texttt{src},\texttt{element}))
1202 \]
1203
1204 Closing:
1205
1206 \[
1207 \texttt{dst}=\mathrm{close}(\texttt{src},\texttt{element})=\mathrm{erode}(\mathrm{dilate}(\texttt{src},\texttt{element}))
1208 \]
1209
1210 Morphological gradient:
1211
1212 \[
1213 \texttt{dst}=\mathrm{morph\_grad}(\texttt{src},\texttt{element})=\mathrm{dilate}(\texttt{src},\texttt{element})-\mathrm{erode}(\texttt{src},\texttt{element})
1214 \]
1215
1216 "Top hat":
1217
1218 \[
1219 \texttt{dst}=\mathrm{tophat}(\texttt{src},\texttt{element})=\texttt{src}-\mathrm{open}(\texttt{src},\texttt{element})
1220 \]
1221
1222 "Black hat":
1223
1224 \[
1225 \texttt{dst}=\mathrm{blackhat}(\texttt{src},\texttt{element})=\mathrm{close}(\texttt{src},\texttt{element})-\texttt{src}
1226 \]
1227
1228 Any of the operations can be done in-place.
1229
1230 See also: \cvCppCross{dilate}, \cvCppCross{erode}, \cvCppCross{createMorphologyFilter}
1231
1232 \cvCppFunc{Laplacian}
1233 Calculates the Laplacian of an image
1234
1235 \cvdefCpp{void Laplacian( const Mat\& src, Mat\& dst, int ddepth,\par
1236                int ksize=1, double scale=1, double delta=0,\par
1237                int borderType=BORDER\_DEFAULT );}
1238 \begin{description}
1239 \cvarg{src}{Source image}
1240 \cvarg{dst}{Destination image; will have the same size and the same number of channels as \texttt{src}}
1241 \cvarg{ddepth}{The desired depth of the destination image}
1242 \cvarg{ksize}{The aperture size used to compute the second-derivative filters, see \cvCppCross{getDerivKernels}. It must be positive and odd}
1243 \cvarg{scale}{The optional scale factor for the computed Laplacian values (by default, no scaling is applied, see \cvCppCross{getDerivKernels})}
1244 \cvarg{delta}{The optional delta value, added to the results prior to storing them in \texttt{dst}}
1245 \cvarg{borderType}{The pixel extrapolation method, see \cvCppCross{borderInterpolate}}
1246 \end{description}
1247
1248 The function calculates the Laplacian of the source image by adding up the second x and y derivatives calculated using the Sobel operator:
1249
1250 \[
1251 \texttt{dst} = \Delta \texttt{src} = \frac{\partial^2 \texttt{src}}{\partial x^2} + \frac{\partial^2 \texttt{src}}{\partial y^2}
1252 \]
1253
1254
1255 This is done when \texttt{ksize > 1}. When \texttt{ksize == 1}, the Laplacian is computed by filtering the image with the following $3 \times 3$ aperture:
1256
1257 \[ \vecthreethree {0}{1}{0}{1}{-4}{1}{0}{1}{0} \]
1258
1259 See also: \cvCppCross{Sobel}, \cvCppCross{Scharr}
1260
1261 \cvCppFunc{pyrDown}
1262 Smoothes an image and downsamples it.
1263
1264 \cvdefCpp{void pyrDown( const Mat\& src, Mat\& dst, const Size\& dstsize=Size());}
1265 \begin{description}
1266 \cvarg{src}{The source image}
1267 \cvarg{dst}{The destination image. It will have the specified size and the same type as \texttt{src}}
1268 \cvarg{dstsize}{Size of the destination image. By default it is computed as \texttt{Size((src.cols+1)/2, (src.rows+1)/2)}. But in any case the following conditions should be satisfied:
1269 \[
1270 \begin{array}{l}
1271 |\texttt{dstsize.width}*2-src.cols|\leq 2 \\
1272 |\texttt{dstsize.height}*2-src.rows|\leq 2
1273 \end{array}
1274 \]
1275 }
1276 \end{description}
1277
1278 The function performs the downsampling step of the Gaussian pyramid construction. First it convolves the source image with the kernel:
1279
1280 \[\frac{1}{16}
1281 \begin{bmatrix}
1282     1 & 4 & 6 & 4 & 1 \\
1283     4 & 16 & 24 & 16 & 4 \\
1284     6 & 24 & 36 & 24 & 6 \\
1285     4 & 16 & 24 & 16 & 4 \\
1286     1 & 4 & 6 & 4 & 1
1287 \end{bmatrix}
1288 \]
1289
1290 and then downsamples the image by rejecting even rows and columns.
1291
1292 \cvCppFunc{pyrUp}
1293 Upsamples an image and then smoothes it
1294
1295 \cvdefCpp{void pyrUp( const Mat\& src, Mat\& dst, const Size\& dstsize=Size());}
1296 \begin{description}
1297 \cvarg{src}{The source image}
1298 \cvarg{dst}{The destination image. It will have the specified size and the same type as \texttt{src}}
1299 \cvarg{dstsize}{Size of the destination image. By default it is computed as \texttt{Size(src.cols*2, (src.rows*2)}. But in any case the following conditions should be satisfied:
1300 \[
1301 \begin{array}{l}
1302 |\texttt{dstsize.width}-src.cols*2|\leq (\texttt{dstsize.width} \mod 2) \\
1303 |\texttt{dstsize.height}-src.rows*2|\leq (\texttt{dstsize.height} \mod 2)
1304 \end{array}
1305 \]
1306 }
1307 \end{description}
1308
1309 The function performs the upsampling step of the Gaussian pyramid construction (it can actually be used to construct the Laplacian pyramid). First it upsamples the source image by injecting even zero rows and columns and then convolves the result with the same kernel as in \cvCppCross{pyrDown}, multiplied by 4.
1310
1311 \cvCppFunc{sepFilter2D}
1312 Applies separable linear filter to an image
1313
1314 \cvdefCpp{void sepFilter2D( const Mat\& src, Mat\& dst, int ddepth,\par
1315                   const Mat\& rowKernel, const Mat\& columnKernel,\par
1316                   Point anchor=Point(-1,-1),\par
1317                   double delta=0, int borderType=BORDER\_DEFAULT );}
1318 \begin{description}
1319 \cvarg{src}{The source image}
1320 \cvarg{dst}{The destination image; will have the same size and the same number of channels as \texttt{src}}
1321 \cvarg{ddepth}{The destination image depth}
1322 \cvarg{rowKernel}{The coefficients for filtering each row}
1323 \cvarg{columnKernel}{The coefficients for filtering each column}
1324 \cvarg{anchor}{The anchor position within the kernel; The default value $(-1, 1)$ means that the anchor is at the kernel center}
1325 \cvarg{delta}{The value added to the filtered results before storing them}
1326 \cvarg{borderType}{The pixel extrapolation method; see \cvCppCross{borderInterpolate}}
1327 \end{description}
1328
1329 The function applies a separable linear filter to the image. That is, first, every row of \texttt{src} is filtered with 1D kernel \texttt{rowKernel}. Then, every column of the result is filtered with 1D kernel \texttt{columnKernel} and the final result shifted by \texttt{delta} is stored in \texttt{dst}.
1330
1331 See also: \cvCppCross{createSeparableLinearFilter}, \cvCppCross{filter2D}, \cvCppCross{Sobel}, \cvCppCross{GaussianBlur}, \cvCppCross{boxFilter}, \cvCppCross{blur}.
1332
1333 \cvCppFunc{Sobel}
1334 Calculates the first, second, third or mixed image derivatives using an extended Sobel operator
1335
1336 \cvdefCpp{void Sobel( const Mat\& src, Mat\& dst, int ddepth,\par
1337             int xorder, int yorder, int ksize=3,\par
1338             double scale=1, double delta=0,\par
1339             int borderType=BORDER\_DEFAULT );}
1340 \begin{description}
1341 \cvarg{src}{The source image}
1342 \cvarg{dst}{The destination image; will have the same size and the same number of channels as \texttt{src}}
1343 \cvarg{ddepth}{The destination image depth}
1344 \cvarg{xorder}{Order of the derivative x}
1345 \cvarg{yorder}{Order of the derivative y}
1346 \cvarg{ksize}{Size of the extended Sobel kernel, must be 1, 3, 5 or 7}
1347 \cvarg{scale}{The optional scale factor for the computed derivative values (by default, no scaling is applied, see \cvCppCross{getDerivKernels})}
1348 \cvarg{delta}{The optional delta value, added to the results prior to storing them in \texttt{dst}}
1349 \cvarg{borderType}{The pixel extrapolation method, see \cvCppCross{borderInterpolate}}
1350 \end{description}
1351
1352 In all cases except 1, an $\texttt{ksize} \times
1353 \texttt{ksize}$ separable kernel will be used to calculate the
1354 derivative. When $\texttt{ksize = 1}$, a $ 3 \times 1$ or $ 1 \times 3$
1355 kernel will be used (i.e. no Gaussian smoothing is done). \texttt{ksize = 1} can only be used for the first or the second x- or y- derivatives.
1356
1357 There is also the special value \texttt{ksize = CV\_SCHARR} (-1) that corresponds to a $3\times3$ Scharr
1358 filter that may give more accurate results than a $3\times3$ Sobel. The Scharr
1359 aperture is
1360
1361 \[ \vecthreethree
1362 {-3}{0}{3}
1363 {-10}{0}{10}
1364 {-3}{0}{3}
1365 \]
1366
1367 for the x-derivative or transposed for the y-derivative.
1368
1369 The function calculates the image derivative by convolving the image with the appropriate kernel:
1370
1371 \[
1372 \texttt{dst} = \frac{\partial^{xorder+yorder} \texttt{src}}{\partial x^{xorder} \partial y^{yorder}}
1373 \]
1374
1375 The Sobel operators combine Gaussian smoothing and differentiation,
1376 so the result is more or less resistant to the noise. Most often,
1377 the function is called with (\texttt{xorder} = 1, \texttt{yorder} = 0,
1378 \texttt{ksize} = 3) or (\texttt{xorder} = 0, \texttt{yorder} = 1,
1379 \texttt{ksize} = 3) to calculate the first x- or y- image
1380 derivative. The first case corresponds to a kernel of:
1381
1382 \[ \vecthreethree
1383 {-1}{0}{1}
1384 {-2}{0}{2}
1385 {-1}{0}{1}
1386 \]
1387
1388 and the second one corresponds to a kernel of:
1389 \[ \vecthreethree
1390 {-1}{-2}{-1}
1391 {0}{0}{0}
1392 {1}{2}{1}
1393 \]
1394
1395 See also: \cvCppCross{Scharr}, \cvCppCross{Lapacian}, \cvCppCross{sepFilter2D}, \cvCppCross{filter2D}, \cvCppCross{GaussianBlur}
1396
1397 \cvCppFunc{Scharr}
1398 Calculates the first x- or y- image derivative using Scharr operator
1399
1400 \cvdefCpp{void Scharr( const Mat\& src, Mat\& dst, int ddepth,\par
1401             int xorder, int yorder,\par
1402             double scale=1, double delta=0,\par
1403             int borderType=BORDER\_DEFAULT );}
1404 \begin{description}
1405 \cvarg{src}{The source image}
1406 \cvarg{dst}{The destination image; will have the same size and the same number of channels as \texttt{src}}
1407 \cvarg{ddepth}{The destination image depth}
1408 \cvarg{xorder}{Order of the derivative x}
1409 \cvarg{yorder}{Order of the derivative y}
1410 \cvarg{scale}{The optional scale factor for the computed derivative values (by default, no scaling is applied, see \cvCppCross{getDerivKernels})}
1411 \cvarg{delta}{The optional delta value, added to the results prior to storing them in \texttt{dst}}
1412 \cvarg{borderType}{The pixel extrapolation method, see \cvCppCross{borderInterpolate}}
1413 \end{description}
1414
1415 The function computes the first x- or y- spatial image derivative using Scharr operator. The call
1416 \[\texttt{Scharr(src, dst, ddepth, xorder, yorder, scale, delta, borderType)}\]
1417 is equivalent to
1418 \[\texttt{Sobel(src, dst, ddepth, xorder, yorder, CV\_SCHARR, scale, delta, borderType)}.\]
1419
1420 \fi