What does the fspecial function do in MATLAB / RunMat?
fspecial(type, ...) constructs well-known 2-D filter kernels such as averaging, Gaussian, Laplacian,
Sobel, Prewitt, motion blur, Laplacian of Gaussian, unsharp masking, and disk (pillbox) filters.
These kernels are intended for use with correlation and convolution routines like imfilter and conv2,
and their outputs match MathWorks MATLAB behaviour for every supported option.
How does the fspecial function behave in MATLAB / RunMat?
- Uses MATLAB-compatible defaults for all optional parameters and validates scalar/vector inputs rigorously.
- Produces double-precision column-major tensors that match MATLAB sample outputs to machine precision.
- Normalises smoothing filters (average, disk, Gaussian, Laplacian of Gaussian, motion) to unit sum.
- Emits derivative-style operators (Sobel, Prewitt, Laplacian, unsharp) using MATLAB's historical scaling.
- Accepts scalar sizes or two-element vectors; zero/negative dimensions trigger MATLAB-style errors.
Supported filter types
"average": rectangular mean filter with optional size argument."disk": circular averaging filter parameterised by radius."gaussian": Gaussian low-pass filter with optional size and standard deviation."laplacian": 3×3 Laplacian operator controlled byalpha(0 ≤ alpha ≤ 1)."log": Laplacian of Gaussian with optional size andsigma."motion": motion blur kernel with controllable length and angle (rounded to odd kernel width)."prewitt": 3×3 horizontal Prewitt edge detector."sobel": 3×3 horizontal Sobel edge detector."unsharp": 3×3 unsharp masking filter with optionalalpha.
fspecial Function GPU Execution Behaviour
When an acceleration provider is active, fspecial can materialise supported kernels directly on the GPU.
Opt-in by setting RUNMAT_ACCEL_FSPECIAL_DEVICE=1. If the provider exports the fspecial hook (the
WGPU backend covers average, gaussian, laplacian, prewitt, sobel, and unsharp), the builtin returns a
gpuArray handle that remains device-resident for downstream fusion. Kernels without acceleration support
and providers lacking the hook automatically fall back to the host path with identical numerical results.
Examples of using the fspecial function in MATLAB / RunMat
Creating a box filter for local averaging
H = fspecial("average", 7); % 7x7 box filter with unit sum
Building a Gaussian smoothing kernel
H = fspecial("gaussian", [5 5], 1.0);
Generating a disk filter for circular blur
H = fspecial("disk", 4);
Constructing a Laplacian-of-Gaussian edge detector
H = fspecial("log", [9 9], 1.4);
Synthesising a motion blur kernel at 30 degrees
H = fspecial("motion", 15, 30);
Tuning an unsharp mask for edge enhancement
H = fspecial("unsharp", 0.6);
FAQ
Which filters does fspecial support?
All classic MATLAB filters are available: average, disk, Gaussian, Laplacian, Laplacian of Gaussian, motion, Prewitt, Sobel, and unsharp.
Does fspecial normalise the kernels?
All smoothing filters produce weights that sum to one. Derivative-style kernels follow MATLAB's scaling so that downstream edge detection behaves identically.
Can I generate a GPU-resident kernel directly?
Yes. Set RUNMAT_ACCEL_FSPECIAL_DEVICE=1 and ensure the active provider exposes the fspecial hook.
Unsupported filters or providers gather to host automatically, so results stay correct either way.
How do I specify the kernel size?
Most filters accept a scalar size or a two-element [rows cols] vector. When omitted, MATLAB-compatible
defaults are used (for example, 3×3 for average/gaussian/laplacian/prewitt/sobel/unsharp).
What happens if I provide invalid parameters?
fspecial raises MATLAB-compatible errors when arguments fall outside the documented range. Negative
lengths, radii, or sigmas, as well as noninteger dimensions, produce descriptive error messages.
Are the filters symmetric with MATLAB outputs?
Yes. Each kernel matches MATLAB (R2023b) outputs within floating-point precision, including motion blur and disk filters that rely on geometric integration.