Image Filtering¶

Functions and classes described in this section are used to perform various linear or non-linear filtering operations on 2D images (represented as 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.

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.

IplConvKernel¶

class IplConvKernel¶

An IplConvKernel is a rectangular convolution kernel, created by function CreateStructuringElementEx .

CopyMakeBorder¶

CopyMakeBorder(src, dst, offset, bordertype, value=(0, 0, 0, 0)) → None¶

Copies an image and makes a border around it.

Parameters:

src (CvArr) – The source image
dst (CvArr) – The destination image
offset (CvPoint) – 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
bordertype (int) –
Type of the border to create around the copied source image rectangle; types include:
- IPL_BORDER_CONSTANT border is filled with the fixed value, passed as last parameter of the function.
- IPL_BORDER_REPLICATE the pixels from the top and bottom rows, the left-most and right-most columns are replicated to fill the border.
(The other two border types from IPL, IPL_BORDER_REFLECT and IPL_BORDER_WRAP , are currently unsupported)
value (CvScalar) – Value of the border pixels if bordertype is IPL_BORDER_CONSTANT

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.

CreateStructuringElementEx¶

CreateStructuringElementEx(cols, rows, anchorX, anchorY, shape, values=None) → kernel¶

Creates a structuring element.

Parameters:

cols (int) – Number of columns in the structuring element
rows (int) – Number of rows in the structuring element
anchorX (int) – Relative horizontal offset of the anchor point
anchorY (int) – Relative vertical offset of the anchor point
shape (int) –
Shape of the structuring element; may have the following values:
- CV_SHAPE_RECT a rectangular element
- CV_SHAPE_CROSS a cross-shaped element
- CV_SHAPE_ELLIPSE an elliptic element
- CV_SHAPE_CUSTOM a user-defined element. In this case the parameter values specifies the mask, that is, which neighbors of the pixel must be considered
values (sequence of int) – 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 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 CV_SHAPE_CUSTOM

The function CreateStructuringElementEx allocates and fills the structure IplConvKernel , which can be used as a structuring element in the morphological operations.

Dilate¶

Dilate(src, dst, element=NULL, iterations=1) → None¶

Dilates an image by using a specific structuring element.

Parameters:	src (`CvArr`) – Source image dst (`CvArr`) – Destination image element (`IplConvKernel`) – Structuring element used for dilation. If it is `NULL` , a $3\times 3$ rectangular structuring element is used iterations (int) – Number of times dilation is applied

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:

$\max _{(x',y') \, in \, \texttt{element} }src(x+x',y+y')$

The function supports the in-place mode. Dilation can be applied several ( iterations ) times. For color images, each channel is processed independently.

Erode¶

Erode(src, dst, element=NULL, iterations=1) → None¶

Erodes an image by using a specific structuring element.

Parameters:	src (`CvArr`) – Source image dst (`CvArr`) – Destination image element (`IplConvKernel`) – Structuring element used for erosion. If it is `NULL` , a $3\times 3$ rectangular structuring element is used iterations (int) – Number of times erosion is applied

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:

$\min _{(x',y') \, in \, \texttt{element} }src(x+x',y+y')$

The function supports the in-place mode. Erosion can be applied several ( iterations ) times. For color images, each channel is processed independently.

Filter2D¶

Filter2D(src, dst, kernel, anchor=(-1, -1)) → None¶

Convolves an image with the kernel.

Parameters:

src (CvArr) – The source image
dst (CvArr) – The destination image
kernel (CvMat) – 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 Split and process them individually
anchor (CvPoint) – 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

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.

Laplace¶

Laplace(src, dst, apertureSize=3) → None¶

Calculates the Laplacian of an image.

Parameters:	src (`CvArr`) – Source image dst (`CvArr`) – Destination image apertureSize (int) – Aperture size (it has the same meaning as Sobel )

The function calculates the Laplacian of the source image by adding up the second x and y derivatives calculated using the Sobel operator:

$\texttt{dst} (x,y) = \frac{d^2 \texttt{src}}{dx^2} + \frac{d^2 \texttt{src}}{dy^2}$

Setting apertureSize = 1 gives the fastest variant that is equal to convolving the image with the following kernel:

$\vecthreethree {0}{1}{0}{1}{-4}{1}{0}{1}{0}$

Similar to the Sobel function, no scaling is done and the same combinations of input and output formats are supported.

MorphologyEx¶

MorphologyEx(src, dst, temp, element, operation, iterations=1) → None¶

Performs advanced morphological transformations.

Parameters:

src (CvArr) – Source image
dst (CvArr) – Destination image
temp (CvArr) – Temporary image, required in some cases
element (IplConvKernel) – Structuring element
operation (int) –
Type of morphological operation, one of the following:
- CV_MOP_OPEN opening
- CV_MOP_CLOSE closing
- CV_MOP_GRADIENT morphological gradient
- CV_MOP_TOPHAT “top hat”
- CV_MOP_BLACKHAT “black hat”
iterations (int) – Number of times erosion and dilation are applied

The function can perform advanced morphological transformations using erosion and dilation as basic operations.

Opening:

$dst=open(src,element)=dilate(erode(src,element),element)$

Closing:

$dst=close(src,element)=erode(dilate(src,element),element)$

Morphological gradient:

$dst=morph \_ grad(src,element)=dilate(src,element)-erode(src,element)$

“Top hat”:

$dst=tophat(src,element)=src-open(src,element)$

“Black hat”:

$dst=blackhat(src,element)=close(src,element)-src$

The temporary image temp is required for a morphological gradient and, in the case of in-place operation, for “top hat” and “black hat”.

PyrDown¶

PyrDown(src, dst, filter=CV_GAUSSIAN_5X5) → None¶

Downsamples an image.

Parameters:	src (`CvArr`) – The source image dst (`CvArr`) – The destination image, should have a half as large width and height than the source filter (int) – Type of the filter used for convolution; only `CV_GAUSSIAN_5x5` is currently supported

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.

Smooth¶

Smooth(src, dst, smoothtype=CV_GAUSSIAN, param1=3, param2=0, param3=0, param4=0) → None¶

Smooths the image in one of several ways.

Parameters:

src (CvArr) – The source image
dst (CvArr) – The destination image
smoothtype (int) –
Type of the smoothing:
- 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 Integral
- 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})$
- CV_GAUSSIAN linear convolution with a $\texttt{param1}\times\texttt{param2}$ Gaussian kernel
- CV_MEDIAN median filter with a $\texttt{param1}\times\texttt{param1}$ square aperture
- CV_BILATERAL bilateral filter with a $\texttt{param1}\times\texttt{param1}$ square aperture, color sigma= param3 and spatial sigma= param4 . If param1=0 , the aperture square side is set to cvRound(param4*1.5)*2+1 . Information about bilateral filtering can be found at http://www.dai.ed.ac.uk/CVonline/LOCAL_COPIES/MANDUCHI1/Bilateral_Filtering.html
param1 (int) – The first parameter of the smoothing operation, the aperture width. Must be a positive odd number (1, 3, 5, ...)
param2 (int) – The second parameter of the smoothing operation, the aperture height. Ignored by CV_MEDIAN and CV_BILATERAL methods. In the case of simple scaled/non-scaled and Gaussian blur if param2 is zero, it is set to param1 . Otherwise it must be a positive odd number.
param3 (float) –
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:

$\sigma = 0.3 (n/2 - 1) + 0.8 \quad \text{where} \quad n= \begin{array}{l l} \mbox{\texttt{param1} for horizontal kernel} \\ \mbox{\texttt{param2} for vertical kernel} \end{array}$

Using standard sigma for small kernels ( $3\times 3$ to $7\times 7$ ) gives better speed. If param3 is not zero, while param1 and param2 are zeros, the kernel size is calculated from the sigma (to provide accurate enough operation).

The function smooths an image using one of several methods. Every of the methods has some features and restrictions listed below

Blur with no scaling works with single-channel images only and supports accumulation of 8-bit to 16-bit format (similar to Sobel and Laplace ) and 32-bit floating point to 32-bit floating-point format.

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.

Median and bilateral filters work with 1- or 3-channel 8-bit images and can not process images in-place.

Sobel¶

Sobel(src, dst, xorder, yorder, apertureSize = 3) → None¶

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

Parameters:	src (`CvArr`) – Source image of type CvArr* dst (`CvArr`) – Destination image xorder (int) – Order of the derivative x yorder (int) – Order of the derivative y apertureSize (int) – Size of the extended Sobel kernel, must be 1, 3, 5 or 7

In all cases except 1, an $\texttt{apertureSize} \times \texttt{apertureSize}$ separable kernel will be used to calculate the derivative. For $\texttt{apertureSize} = 1$ a $3 \times 1$ or $1 \times 3$ a kernel is used (Gaussian smoothing is not done). There is also the special value CV_SCHARR (-1) that corresponds to a $3\times3$ Scharr filter that may give more accurate results than a $3\times3$ Sobel. 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 the image derivative by convolving the image with the appropriate kernel:

$\texttt{dst} (x,y) = \frac{d^{xorder+yorder} \texttt{src}}{dx^{xorder} \cdot dy^{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, apertureSize = 3) or ( xorder = 0, yorder = 1, apertureSize = 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}$

and the second one corresponds to a kernel of:

$\vecthreethree{-1}{-2}{-1}{0}{0}{0}{1}{2}{1}$

or a kernel of:

$\vecthreethree{1}{2}{1}{0}{0}{0}{-1}{2}{-1}$

depending on the image origin ( origin field of IplImage structure). No scaling is done, so the destination image usually has larger numbers (in absolute values) than the source image does. To avoid overflow, the function requires a 16-bit destination image if the source image is 8-bit. The result can be converted back to 8-bit using the ConvertScale or the ConvertScaleAbs function. Besides 8-bit images the function can process 32-bit floating-point images. Both the source and the destination must be single-channel images of equal size or equal ROI size.

Image Filtering¶

IplConvKernel¶

CopyMakeBorder¶

CreateStructuringElementEx¶

Dilate¶

Erode¶

Filter2D¶

Laplace¶

MorphologyEx¶

PyrDown¶

Smooth¶

Sobel¶

Help and Feedback

Table Of Contents

Previous topic

Next topic

This Page

Navigation

Image Filtering¶

IplConvKernel¶

CopyMakeBorder¶

CreateStructuringElementEx¶

Dilate¶

Erode¶

Filter2D¶

Laplace¶

MorphologyEx¶

PyrDown¶

Smooth¶

Sobel¶

Help and Feedback

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation