# fspecial

Create predefined 2-D filter

## Syntax

`h = fspecial(type)h = fspecial(type, parameters)`

## Description

`h = fspecial(type)` creates a two-dimensional filter `h` of the specified `type`. `fspecial` returns `h` as a correlation kernel, which is the appropriate form to use with `imfilter`. `type` is a string having one of these values.

Value

Description

`average`

Averaging filter

`disk`

Circular averaging filter (pillbox)

`gaussian`

Gaussian lowpass filter

`laplacian`

Approximates the two-dimensional Laplacian operator

`log`

Laplacian of Gaussian filter

`motion`

Approximates the linear motion of a camera

`prewitt`

Prewitt horizontal edge-emphasizing filter

`sobel`

Sobel horizontal edge-emphasizing filter

This function supports code generation (see Tips).

`h = fspecial(type, parameters)` accepts the filter specified by `type` plus additional modifying `parameters` particular to the type of filter chosen. If you omit these arguments, `fspecial` uses default values for the `parameters`.

The following list shows the syntax for each filter type. Where applicable, additional parameters are also shown.

• `h = fspecial('average', hsize)` returns an averaging filter `h` of size `hsize`. The argument `hsize` can be a vector specifying the number of rows and columns in `h`, or it can be a scalar, in which case `h` is a square matrix. The default value for `hsize` is `[3 3]`.

• `h = fspecial('disk', radius)` returns a circular averaging filter (pillbox) within the square matrix of size `2*radius+1`. The default `radius` is 5.

• ```h = fspecial('gaussian', hsize, sigma)``` returns a rotationally symmetric Gaussian lowpass filter of size `hsize` with standard deviation `sigma` (positive). `hsize` can be a vector specifying the number of rows and columns in `h`, or it can be a scalar, in which case `h` is a square matrix. The default value for `hsize` is ```[3 3]```; the default value for `sigma` is 0.5. Not recommended. Use `imgaussfilt` or `imguassfilt3` instead.

• `h = fspecial('laplacian', alpha)` returns a 3-by-3 filter approximating the shape of the two-dimensional Laplacian operator. The parameter `alpha` controls the shape of the Laplacian and must be in the range 0.0 to 1.0. The default value for `alpha` is 0.2.

• `h = fspecial('log', hsize, sigma)` returns a rotationally symmetric Laplacian of Gaussian filter of size `hsize` with standard deviation `sigma` (positive). `hsize` can be a vector specifying the number of rows and columns in `h`, or it can be a scalar, in which case `h` is a square matrix. The default value for `hsize` is ```[5 5]``` and `0.5` for `sigma`.

• ```h = fspecial('motion', len, theta)``` returns a filter to approximate, once convolved with an image, the linear motion of a camera by `len` pixels, with an angle of `theta` degrees in a counterclockwise direction. The filter becomes a vector for horizontal and vertical motions. The default `len` is 9 and the default `theta` is 0, which corresponds to a horizontal motion of nine pixels.

To compute the filter coefficients, `h`, for `'motion'`:

1. Construct an ideal line segment with the desired length and angle, centered at the center coefficient of `h`.

2. For each coefficient location `(i,j)`, compute the nearest distance between that location and the ideal line segment.

3. `h = max(1 - nearest_distance, 0);`

4. Normalize `h`:`h = h/(sum(h(:)))`

• `h = fspecial('prewitt')` returns the 3-by-3 filter `h` (shown below) that emphasizes horizontal edges by approximating a vertical gradient. If you need to emphasize vertical edges, transpose the filter `h'`.

```[ 1 1 1 0 0 0 -1 -1 -1 ]```

To find vertical edges, or for x-derivatives, use `h'`.

• `h = fspecial('sobel')` returns a 3-by-3 filter `h` (shown below) that emphasizes horizontal edges using the smoothing effect by approximating a vertical gradient. If you need to emphasize vertical edges, transpose the filter `h'`.

```[ 1 2 1 0 0 0 -1 -2 -1 ]```

## Class Support

`h` is of class `double`.

## Examples

collapse all

### Create Various Filters and Filter an Image

```I = imread('cameraman.tif'); imshow(I); ```

Create a motion filter and use it to blur the image. Display the blurred image.

```H = fspecial('motion',20,45); MotionBlur = imfilter(I,H,'replicate'); imshow(MotionBlur); ```

Create a disk filter and use it to blur the image. Display the blurred image.

```H = fspecial('disk',10); blurred = imfilter(I,H,'replicate'); imshow(blurred); ```

collapse all

### Tips

• This function supports the generation of C code using MATLAB® Coder™. For more information, see Code Generation for Image Processing.

When generating code, all inputs must be constants at compilation time.

### Algorithms

`fspecial` creates Gaussian filters using

${h}_{g}\left({n}_{1},{n}_{2}\right)={e}^{\frac{-\left({n}_{1}^{2}+{n}_{2}^{2}\right)}{2{\sigma }^{2}}}$

$h\left({n}_{1},{n}_{2}\right)=\frac{{h}_{g}\left({n}_{1},{n}_{2}\right)}{\sum _{{n}_{1}}\sum _{{n}_{2}}{h}_{g}}$

`fspecial` creates Laplacian filters using

${\nabla }^{2}=\frac{{\partial }^{2}}{\partial {x}^{2}}+\frac{{\partial }^{2}}{\partial {y}^{2}}$

${\nabla }^{2}=\frac{4}{\left(\alpha +1\right)}\left[\begin{array}{ccc}\frac{\alpha }{4}& \frac{1-\alpha }{4}& \frac{\alpha }{4}\\ \frac{1-\alpha }{4}& -1& \frac{1-\alpha }{4}\\ \frac{\alpha }{4}& \frac{1-\alpha }{4}& \frac{\alpha }{4}\end{array}\right]$

`fspecial` creates Laplacian of Gaussian (LoG) filters using

${h}_{g}\left({n}_{1},{n}_{2}\right)={e}^{\frac{-\left({n}_{1}^{2}+{n}_{2}^{2}\right)}{2{\sigma }^{2}}}$

$h\left({n}_{1},{n}_{2}\right)=\frac{\left({n}_{1}^{2}+{n}_{2}^{2}-2{\sigma }^{2}\right){h}_{g}\left({n}_{1},{n}_{2}\right)}{2\pi {\sigma }^{6}\sum _{{n}_{1}}\sum _{{n}_{2}}{h}_{g}}$

`fspecial` creates averaging filters using

```ones(n(1),n(2))/(n(1)*n(2)) ```