OpenCV  4.0.0-beta
Open Source Computer Vision
Functions
Graph API: Image filters

Functions

GAPI_EXPORTS GMat cv::gapi::blur (const GMat &src, const Size &ksize, const Point &anchor=Point(-1,-1), int borderType=BORDER_DEFAULT, const Scalar &borderValue=Scalar(0))
 Blurs an image using the normalized box filter. More...
 
GAPI_EXPORTS GMat cv::gapi::boxFilter (const GMat &src, int dtype, const Size &ksize, const Point &anchor=Point(-1,-1), bool normalize=true, int borderType=BORDER_DEFAULT, const Scalar &borderValue=Scalar(0))
 Blurs an image using the box filter. More...
 
GAPI_EXPORTS GMat cv::gapi::Canny (const GMat &image, double threshold1, double threshold2, int apertureSize=3, bool L2gradient=false)
 Finds edges in an image using the Canny algorithm. More...
 
GAPI_EXPORTS GMat cv::gapi::dilate (const GMat &src, const Mat &kernel, const Point &anchor=Point(-1,-1), int iterations=1, int borderType=BORDER_CONSTANT, const Scalar &borderValue=morphologyDefaultBorderValue())
 Dilates an image by using a specific structuring element. More...
 
GAPI_EXPORTS GMat cv::gapi::dilate3x3 (const GMat &src, int iterations=1, int borderType=BORDER_CONSTANT, const Scalar &borderValue=morphologyDefaultBorderValue())
 Dilates an image by using 3 by 3 rectangular structuring element. More...
 
GAPI_EXPORTS GMat cv::gapi::equalizeHist (const GMat &src)
 Equalizes the histogram of a grayscale image. More...
 
GAPI_EXPORTS GMat cv::gapi::erode (const GMat &src, const Mat &kernel, const Point &anchor=Point(-1,-1), int iterations=1, int borderType=BORDER_CONSTANT, const Scalar &borderValue=morphologyDefaultBorderValue())
 Erodes an image by using a specific structuring element. More...
 
GAPI_EXPORTS GMat cv::gapi::erode3x3 (const GMat &src, int iterations=1, int borderType=BORDER_CONSTANT, const Scalar &borderValue=morphologyDefaultBorderValue())
 Erodes an image by using 3 by 3 rectangular structuring element. More...
 
GAPI_EXPORTS GMat cv::gapi::filter2D (const GMat &src, int ddepth, const Mat &kernel, const Point &anchor=Point(-1,-1), const Scalar &delta=Scalar(0), int borderType=BORDER_DEFAULT, const Scalar &borderValue=Scalar(0))
 Convolves an image with the kernel. More...
 
GAPI_EXPORTS GMat cv::gapi::gaussianBlur (const GMat &src, const Size &ksize, double sigmaX, double sigmaY=0, int borderType=BORDER_DEFAULT, const Scalar &borderValue=Scalar(0))
 Blurs an image using a Gaussian filter. More...
 
GAPI_EXPORTS GMat cv::gapi::medianBlur (const GMat &src, int ksize)
 Blurs an image using the median filter. More...
 
GAPI_EXPORTS GMat cv::gapi::sepFilter (const GMat &src, int ddepth, const Mat &kernelX, const Mat &kernelY, const Point &anchor, const Scalar &delta, int borderType=BORDER_DEFAULT, const Scalar &borderValue=Scalar(0))
 Applies a separable linear filter to a matrix(image). More...
 
GAPI_EXPORTS GMat cv::gapi::sobel (const GMat &src, int ddepth, int dx, int dy, int ksize=3, double scale=1, double delta=0, int borderType=BORDER_DEFAULT, const Scalar &borderValue=Scalar(0))
 Calculates the first, second, third, or mixed image derivatives using an extended Sobel operator. More...
 

Detailed Description

Function Documentation

§ blur()

GAPI_EXPORTS GMat cv::gapi::blur ( const GMat src,
const Size ksize,
const Point anchor = Point(-1,-1),
int  borderType = BORDER_DEFAULT,
const Scalar borderValue = Scalar(0) 
)

Blurs an image using the normalized box filter.

The function smooths an image using the kernel:

\[\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}\]

The call blur(src, dst, ksize, anchor, borderType) is equivalent to boxFilter(src, dst, src.type(), anchor, true, borderType).

Supported input matrix data types are CV_8UC1, CV_8UC3, CV_16UC1, CV_16SC1, CV_32FC1. Output image must have the same type, size, and number of channels as the input image.

Note
Rounding to nearest even is procedeed if hardware supports it, if not - to nearest.
Function textual ID is "org.opencv.imgproc.filters.blur"
Parameters
srcSource image.
ksizeblurring kernel size.
anchoranchor point; default value Point(-1,-1) means that the anchor is at the kernel center.
borderTypeborder mode used to extrapolate pixels outside of the image, see cv::BorderTypes
borderValueborder value in case of constant border type
See also
boxFilter, bilateralFilter, GaussianBlur, medianBlur

§ boxFilter()

GAPI_EXPORTS GMat cv::gapi::boxFilter ( const GMat src,
int  dtype,
const Size ksize,
const Point anchor = Point(-1,-1),
bool  normalize = true,
int  borderType = BORDER_DEFAULT,
const Scalar borderValue = Scalar(0) 
)

Blurs an image using the box filter.

The function smooths an image using the kernel:

\[\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}\]

where

\[\alpha = \fork{\frac{1}{\texttt{ksize.width*ksize.height}}}{when \texttt{normalize=true}}{1}{otherwise}\]

Unnormalized box filter is useful for computing various integral characteristics over each pixel neighborhood, such as covariance matrices of image derivatives (used in dense optical flow algorithms, and so on). If you need to compute pixel sums over variable-size windows, use cv::integral.

Supported input matrix data types are CV_8UC1, CV_8UC3, CV_16UC1, CV_16SC1, CV_32FC1. Output image must have the same type, size, and number of channels as the input image.

Note
Rounding to nearest even is procedeed if hardware supports it, if not - to nearest.
Function textual ID is "org.opencv.imgproc.filters.boxfilter"
Parameters
srcSource image.
dtypethe output image depth (-1 to set the input image data type).
ksizeblurring kernel size.
anchorAnchor position within the kernel. The default value \((-1,-1)\) means that the anchor is at the kernel center.
normalizeflag, specifying whether the kernel is normalized by its area or not.
borderTypePixel extrapolation method, see cv::BorderTypes
borderValueborder value in case of constant border type
See also
sepFilter, gaussianBlur, medianBlur, integral

§ Canny()

GAPI_EXPORTS GMat cv::gapi::Canny ( const GMat image,
double  threshold1,
double  threshold2,
int  apertureSize = 3,
bool  L2gradient = false 
)

Finds edges in an image using the Canny algorithm.

The function finds edges in the input image and marks them in the output map edges using the Canny algorithm. The smallest value between threshold1 and threshold2 is used for edge linking. The largest value is used to find initial segments of strong edges. See http://en.wikipedia.org/wiki/Canny_edge_detector

Note
Function textual ID is "org.opencv.imgproc.filters.canny"
Parameters
image8-bit input image.
threshold1first threshold for the hysteresis procedure.
threshold2second threshold for the hysteresis procedure.
apertureSizeaperture size for the Sobel operator.
L2gradienta flag, indicating whether a more accurate \(L_2\) norm \(=\sqrt{(dI/dx)^2 + (dI/dy)^2}\) should be used to calculate the image gradient magnitude ( L2gradient=true ), or whether the default \(L_1\) norm \(=|dI/dx|+|dI/dy|\) is enough ( L2gradient=false ).

§ dilate()

GAPI_EXPORTS GMat cv::gapi::dilate ( const GMat src,
const Mat kernel,
const Point anchor = Point(-1,-1),
int  iterations = 1,
int  borderType = BORDER_CONSTANT,
const Scalar borderValue = morphologyDefaultBorderValue() 
)

Dilates an image by using a specific structuring element.

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:

\[\texttt{dst} (x,y) = \max _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')\]

Dilation can be applied several (iterations) times. In case of multi-channel images, each channel is processed independently. Supported input matrix data types are CV_8UC1, CV_8UC3, CV_16UC1, CV_16SC1, and CV_32FC1. Output image must have the same type, size, and number of channels as the input image.

Note
Rounding to nearest even is procedeed if hardware supports it, if not - to nearest.
Function textual ID is "org.opencv.imgproc.filters.dilate"
Parameters
srcinput image.
kernelstructuring element used for dilation; if elemenat=Mat(), a 3 x 3 rectangular structuring element is used. Kernel can be created using getStructuringElement
anchorposition of the anchor within the element; default value (-1, -1) means that the anchor is at the element center.
iterationsnumber of times dilation is applied.
borderTypepixel extrapolation method, see cv::BorderTypes
borderValueborder value in case of a constant border
See also
erode, morphologyEx, getStructuringElement

§ dilate3x3()

GAPI_EXPORTS GMat cv::gapi::dilate3x3 ( const GMat src,
int  iterations = 1,
int  borderType = BORDER_CONSTANT,
const Scalar borderValue = morphologyDefaultBorderValue() 
)

Dilates an image by using 3 by 3 rectangular structuring element.

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:

\[\texttt{dst} (x,y) = \max _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')\]

Dilation can be applied several (iterations) times. In case of multi-channel images, each channel is processed independently. Supported input matrix data types are CV_8UC1, CV_8UC3, CV_16UC1, CV_16SC1, and CV_32FC1. Output image must have the same type, size, and number of channels as the input image.

Note
Rounding to nearest even is procedeed if hardware supports it, if not - to nearest.
Function textual ID is "org.opencv.imgproc.filters.dilate"
Parameters
srcinput image.
iterationsnumber of times dilation is applied.
borderTypepixel extrapolation method, see cv::BorderTypes
borderValueborder value in case of a constant border
See also
dilate, erode3x3

§ equalizeHist()

GAPI_EXPORTS GMat cv::gapi::equalizeHist ( const GMat src)

Equalizes the histogram of a grayscale image.

The function equalizes the histogram of the input image using the following algorithm:

  • Calculate the histogram \(H\) for src .
  • Normalize the histogram so that the sum of histogram bins is 255.
  • Compute the integral of the histogram:

    \[H'_i = \sum _{0 \le j < i} H(j)\]

  • Transform the image using \(H'\) as a look-up table: \(\texttt{dst}(x,y) = H'(\texttt{src}(x,y))\)

The algorithm normalizes the brightness and increases the contrast of the image.

Note
The returned image is of the same size and type as input.
Function textual ID is "org.opencv.imgproc.equalizeHist"
Parameters
srcSource 8-bit single channel image.

§ erode()

GAPI_EXPORTS GMat cv::gapi::erode ( const GMat src,
const Mat kernel,
const Point anchor = Point(-1,-1),
int  iterations = 1,
int  borderType = BORDER_CONSTANT,
const Scalar borderValue = morphologyDefaultBorderValue() 
)

Erodes an image by using a specific structuring element.

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:

\[\texttt{dst} (x,y) = \min _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')\]

Erosion can be applied several (iterations) times. In case of multi-channel images, each channel is processed independently. Supported input matrix data types are CV_8UC1, CV_8UC3, CV_16UC1, CV_16SC1, and CV_32FC1. Output image must have the same type, size, and number of channels as the input image.

Note
Rounding to nearest even is procedeed if hardware supports it, if not - to nearest.
Function textual ID is "org.opencv.imgproc.filters.erode"
Parameters
srcinput image
kernelstructuring element used for erosion; if element=Mat(), a 3 x 3 rectangular structuring element is used. Kernel can be created using getStructuringElement.
anchorposition of the anchor within the element; default value (-1, -1) means that the anchor is at the element center.
iterationsnumber of times erosion is applied.
borderTypepixel extrapolation method, see cv::BorderTypes
borderValueborder value in case of a constant border
See also
dilate

§ erode3x3()

GAPI_EXPORTS GMat cv::gapi::erode3x3 ( const GMat src,
int  iterations = 1,
int  borderType = BORDER_CONSTANT,
const Scalar borderValue = morphologyDefaultBorderValue() 
)

Erodes an image by using 3 by 3 rectangular structuring element.

The function erodes the source image using the rectangular structuring element with rectangle center as an anchor. Erosion can be applied several (iterations) times. In case of multi-channel images, each channel is processed independently. Supported input matrix data types are CV_8UC1, CV_8UC3, CV_16UC1, CV_16SC1, and CV_32FC1. Output image must have the same type, size, and number of channels as the input image.

Note
Rounding to nearest even is procedeed if hardware supports it, if not - to nearest.
Parameters
srcinput image
iterationsnumber of times erosion is applied.
borderTypepixel extrapolation method, see cv::BorderTypes
borderValueborder value in case of a constant border
See also
erode, dilate3x3

§ filter2D()

GAPI_EXPORTS GMat cv::gapi::filter2D ( const GMat src,
int  ddepth,
const Mat kernel,
const Point anchor = Point(-1,-1),
const Scalar delta = Scalar(0),
int  borderType = BORDER_DEFAULT,
const Scalar borderValue = Scalar(0) 
)

Convolves an image with the kernel.

The function applies an arbitrary linear filter to an image. When the aperture is partially outside the image, the function interpolates outlier pixel values according to the specified border mode.

The function does actually compute correlation, not the convolution:

\[\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} )\]

That is, the kernel is not mirrored around the anchor point. If you need a real convolution, flip the kernel using flip and set the new anchor to (kernel.cols - anchor.x - 1, kernel.rows - anchor.y - 1).

Supported matrix data types are CV_8UC1, CV_8UC3, CV_16UC1, CV_16SC1, CV_32FC1. Output image must have the same size and number of channels an input image.

Note
Rounding to nearest even is procedeed if hardware supports it, if not - to nearest.
Function textual ID is "org.opencv.imgproc.filters.filter2D"
Parameters
srcinput image.
ddepthdesired depth of the destination image
kernelconvolution 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 split and process them individually.
anchoranchor of the kernel that indicates the relative position of a filtered point within the kernel; the anchor should lie within the kernel; default value (-1,-1) means that the anchor is at the kernel center.
deltaoptional value added to the filtered pixels before storing them in dst.
borderTypepixel extrapolation method, see cv::BorderTypes
borderValueborder value in case of constant border type
See also
sepFilter

§ gaussianBlur()

GAPI_EXPORTS GMat cv::gapi::gaussianBlur ( const GMat src,
const Size ksize,
double  sigmaX,
double  sigmaY = 0,
int  borderType = BORDER_DEFAULT,
const Scalar borderValue = Scalar(0) 
)

Blurs an image using a Gaussian filter.

The function filter2Ds the source image with the specified Gaussian kernel. Output image must have the same type and number of channels an input image.

Supported input matrix data types are CV_8UC1, CV_8UC3, CV_16UC1, CV_16SC1, CV_32FC1. Output image must have the same type, size, and number of channels as the input image.

Note
Rounding to nearest even is procedeed if hardware supports it, if not - to nearest.
Function textual ID is "org.opencv.imgproc.filters.gaussianBlur"
Parameters
srcinput image;
ksizeGaussian kernel size. ksize.width and ksize.height can differ but they both must be positive and odd. Or, they can be zero's and then they are computed from sigma.
sigmaXGaussian kernel standard deviation in X direction.
sigmaYGaussian kernel standard deviation in Y direction; if sigmaY is zero, it is set to be equal to sigmaX, if both sigmas are zeros, they are computed from ksize.width and ksize.height, respectively (see cv::getGaussianKernel for details); to fully control the result regardless of possible future modifications of all this semantics, it is recommended to specify all of ksize, sigmaX, and sigmaY.
borderTypepixel extrapolation method, see cv::BorderTypes
borderValueborder value in case of constant border type
See also
sepFilter, boxFilter, medianBlur

§ medianBlur()

GAPI_EXPORTS GMat cv::gapi::medianBlur ( const GMat src,
int  ksize 
)

Blurs an image using the median filter.

The function smoothes an image using the median filter with the \(\texttt{ksize} \times \texttt{ksize}\) aperture. Each channel of a multi-channel image is processed independently. Output image must have the same type, size, and number of channels as the input image.

Note
Rounding to nearest even is procedeed if hardware supports it, if not - to nearest. The median filter uses cv::BORDER_REPLICATE internally to cope with border pixels, see cv::BorderTypes
Function textual ID is "org.opencv.imgproc.filters.medianBlur"
Parameters
srcinput matrix (image)
ksizeaperture linear size; it must be odd and greater than 1, for example: 3, 5, 7 ...
See also
boxFilter, gaussianBlur

§ sepFilter()

GAPI_EXPORTS GMat cv::gapi::sepFilter ( const GMat src,
int  ddepth,
const Mat kernelX,
const Mat kernelY,
const Point anchor,
const Scalar delta,
int  borderType = BORDER_DEFAULT,
const Scalar borderValue = Scalar(0) 
)

Applies a separable linear filter to a matrix(image).

The function applies a separable linear filter to the matrix. That is, first, every row of src is filtered with the 1D kernel kernelX. Then, every column of the result is filtered with the 1D kernel kernelY. The final result is returned.

Supported matrix data types are CV_8UC1, CV_8UC3, CV_16UC1, CV_16SC1, CV_32FC1. Output image must have the same type, size, and number of channels as the input image.

Note
In case of floating-point computation, rounding to nearest even is procedeed if hardware supports it (if not - to nearest value).
Function textual ID is "org.opencv.imgproc.filters.sepfilter"
Parameters
srcSource image.
ddepthdesired depth of the destination image (the following combinations of src.depth() and ddepth are supported:
    src.depth() = CV_8U, ddepth = -1/CV_16S/CV_32F/CV_64F
    src.depth() = CV_16U/CV_16S, ddepth = -1/CV_32F/CV_64F
    src.depth() = CV_32F, ddepth = -1/CV_32F/CV_64F
    src.depth() = CV_64F, ddepth = -1/CV_64F

when ddepth=-1, the output image will have the same depth as the source)

Parameters
kernelXCoefficients for filtering each row.
kernelYCoefficients for filtering each column.
anchorAnchor position within the kernel. The default value \((-1,-1)\) means that the anchor is at the kernel center.
deltaValue added to the filtered results before storing them.
borderTypePixel extrapolation method, see cv::BorderTypes
borderValueborder value in case of constant border type
See also
boxFilter, gaussianBlur, medianBlur

§ sobel()

GAPI_EXPORTS GMat cv::gapi::sobel ( const GMat src,
int  ddepth,
int  dx,
int  dy,
int  ksize = 3,
double  scale = 1,
double  delta = 0,
int  borderType = BORDER_DEFAULT,
const Scalar borderValue = Scalar(0) 
)

Calculates the first, second, third, or mixed image derivatives using an extended Sobel operator.

In all cases except one, the \(\texttt{ksize} \times \texttt{ksize}\) separable kernel is used to calculate the derivative. When \(\texttt{ksize = 1}\), the \(3 \times 1\) or \(1 \times 3\) kernel is used (that is, no Gaussian smoothing is done). ksize = 1 can only be used for the first or the second x- or y- derivatives.

There is also the special value ksize = CV_SCHARR (-1) that corresponds to the \(3\times3\) Scharr filter that may give more accurate results than the \(3\times3\) Sobel. The Scharr aperture is

\[\vecthreethree{-3}{0}{3}{-10}{0}{10}{-3}{0}{3}\]

for the x-derivative, or transposed for the y-derivative.

The function calculates an image derivative by convolving the image with the appropriate kernel:

\[\texttt{dst} = \frac{\partial^{xorder+yorder} \texttt{src}}{\partial x^{xorder} \partial y^{yorder}}\]

The Sobel operators combine Gaussian smoothing and differentiation, so the result is more or less resistant to the noise. Most often, the function is called with ( xorder = 1, yorder = 0, ksize = 3) or ( xorder = 0, yorder = 1, ksize = 3) to calculate the first x- or y- image derivative. The first case corresponds to a kernel of:

\[\vecthreethree{-1}{0}{1}{-2}{0}{2}{-1}{0}{1}\]

The second case corresponds to a kernel of:

\[\vecthreethree{-1}{-2}{-1}{0}{0}{0}{1}{2}{1}\]

Note
Rounding to nearest even is procedeed if hardware supports it, if not - to nearest.
Function textual ID is "org.opencv.imgproc.filters.sobel"
Parameters
srcinput image.
ddepthoutput image depth, see combinations; in the case of 8-bit input images it will result in truncated derivatives.
dxorder of the derivative x.
dyorder of the derivative y.
ksizesize of the extended Sobel kernel; it must be odd.
scaleoptional scale factor for the computed derivative values; by default, no scaling is applied (see cv::getDerivKernels for details).
deltaoptional delta value that is added to the results prior to storing them in dst.
borderTypepixel extrapolation method, see cv::BorderTypes
borderValueborder value in case of constant border type
See also
filter2D, gaussianBlur, cartToPolar