fspecial3

Create predefined 3-D filter

Syntax

h = fspecial3(type)

h = fspecial3('average',hsize)

h = fspecial3('ellipsoid',semiaxes)

h = fspecial3('gaussian',hsize,sigma)

h = fspecial3('laplacian',gamma1,gamma2)

h = fspecial3('log',hsize,sigma)

h = fspecial3('prewitt',direction)

h = fspecial3('sobel',direction)

Description

h = fspecial3(type) creates a three-dimensional filter h of the specified type. Some of the filter types have optional additional parameters, shown in the following syntaxes. fspecial3 returns h as a correlation kernel, which is the appropriate form to use with imfilter.

h = fspecial3('average',hsize) returns an averaging filter h of size hsize. Not recommended. Use imboxfilt3 instead.

h = fspecial3('ellipsoid',semiaxes) returns an ellipsoidal averaging filter with the length of the principal semiaxes specified by semiaxes. The filter h is returned in an array of size 2*ceil(semiaxes)+1.

h = fspecial3('gaussian',hsize,sigma) returns a Gaussian lowpass filter of size hsize with standard deviation sigma. Not recommended. Use imgaussfilt3 instead.

h = fspecial3('laplacian',gamma1,gamma2) returns a 3-by-3-by-3 filter approximating the shape of the three-dimensional Laplacian operator. gamma1 and gamma2 control the shape of the Laplacian [1][2].

h = fspecial3('log',hsize,sigma) returns a Laplacian of Gaussian filter of size hsize with standard deviation sigma.

h = fspecial3('prewitt',direction) returns a 3-by-3-by-3 filter that emphasizes gradients in the specified direction.

h = fspecial3('sobel',direction) returns a 3-by-3-by-3 filter that emphasizes gradients in the specified direction and smooths the other directions [3].

Examples

Smooth Volume Using 3-D Ellipsoidal Filter

Load a 3-D grayscale MRI volume. Display the planes of the volume.

load mristack;
montage(mristack,BackgroundColor="w")

Create a 3-D ellipsoidal filter. Specify a semiaxis length of 7 pixels in the y (rows) and x (columns) directions, and a semiaxis length of 3 pixels in the z (planes) direction.

H = fspecial3("ellipsoid",[7 7 3]);

Smooth the volume with the filter.

volSmooth = imfilter(mristack,H,"replicate");

Display the planes of the smoothed volume.

montage(volSmooth,BackgroundColor="w")

Detect Horizontal Edges Using 3-D Sobel Filter

Load an MRI volume. This volume is stored as a 4-D array with a singleton dimension. Create a 3-D grayscale volume by using the squeeze function to remove the singleton dimension.

load mri;
V = squeeze(D);

Display the planes of the volume.

montage(D,BackgroundColor="w")

Create a 3-D Sobel filter that detects horizontal edges in the volume. Horizontal edges appear where there is a large gradient magnitude in the y direction, so specify the direction of the Sobel filter as "Y". The Sobel filter smooths the gradient in the x and z directions.

H = fspecial3("sobel","Y");

Filter the volume with the 3-D Sobel filter.

edgesHor = imfilter(V,H,"replicate");

Display the planes of the filtered volume.

montage(edgesHor)

Input Arguments

type — Type of filter

'average' | 'ellipsoid' | 'gaussian' | 'laplacian' | 'log' | 'prewitt' | 'sobel'

Type of filter, specified as one of the following values:

Value	Description
'average'	Averaging filter. Not recommended. Use imboxfilt3 instead.
'ellipsoid'	Ellipsoidal averaging filter
'gaussian'	Gaussian lowpass filter. Not recommended. Use imgaussfilt3 instead.
'laplacian'	Approximates the three-dimensional Laplacian operator
'log'	Laplacian of Gaussian filter
'prewitt'	Prewitt edge-emphasizing filter
'sobel'	Sobel edge-emphasizing filter

Data Types: char | string

hsize — Size of the filter

[5 5 5] (default) | positive integer | 3-element vector of positive integers

Size of the filter, specified as a positive integer or 3-element vector of positive integers. Use a vector to specify the number of rows, columns, and planes in h. Use a scalar to specify the side length of a cube.

For the 'gaussian' and 'log' filter types, if you specify hsize as [], then fspecial3 creates a filter with a default size of 2*ceil(2*sigma)+1.

Data Types: double

semiaxes — Semiaxes length of ellipsoidal filter

5 (default) | positive number | 3-element vector of positive numbers

Semiaxes length of an ellipsoidal filter, specified as a positive number or 3-element vector of positive numbers. Use a vector to specify the length of the three principal semiaxes in rows, columns, and planes. These values correspond to length in the Cartesian y, x, and z directions, respectively. Use a scalar to specify the radius of a sphere.

Data Types: double

sigma — Standard deviation of Gaussian filter

1 (default) | positive number | 3-element vector of positive numbers

Standard deviation of Gaussian filter, specified as a positive number or 3-element vector of positive numbers. If you specify a scalar, then fspecial3 creates a cubic Gaussian kernel.

Data Types: double

gamma1, gamma2 — Shape of the Laplacian

0 (default) | scalar in the range [0 1]

Shape of the Laplacian, specified as a scalar in the range [0 1]. The sum of gamma1 and gamma2 must not exceed 1.

Data Types: double

direction — Direction of gradients

'X' (default) | 'Y' | 'Z'

Direction of gradients for Prewitt and Sobel filtering, specified as 'X', 'Y', or 'Z'.

Data Types: char | string

Output Arguments

h — Correlation kernel

numeric array

Correlation kernel, returned as a numeric array.

Data Types: double

References

[1] Lindeberg, T., Scale-Space Theory in Computer Vision. Boston, MA: Kluwer Academic Publishers, 1994.

[2] Geometry-Driven Diffusion in Computer Vision. Edited by B. M. ter Haar Romeny. Boston, MA: Kluwer Academic Publishers, 1994.

[3] Engel, K., M. Hadwiger, J. M. Kniss, C. Rezk-Salama, and D. Weiskopf. Real-Time Volume Graphics. Wellesley, MA: A K Peters, Ltd., 2006, pp. 112–114.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• fspecial3 supports the generation of C code (requires MATLAB^® Coder™). For more information, see Code Generation for Image Processing.

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

Version History

Introduced in R2018b