fspecial — Generate classical 2-D correlation kernels used in MATLAB image processing workflows.
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 fspecial works in 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.
How fspecial runs on the GPU
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
Creating a box filter for local averaging
H = fspecial("average", 7); % 7x7 box filter with unit sumBuilding 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.
Related functions to explore
These functions work well alongside fspecial. Each page has runnable examples you can try in the browser.
imfilter, conv2, gpuArray, gather, filter2
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how fspecial works, line by line, in Rust.
- View fspecial.rs on GitHub
- Learn how the runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code — faster, on any GPU, with no license required.
- Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
- Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
- A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.