fspecial — Generate standard 2-D filter kernels in MATLAB and RunMat.
fspecial(type, ...) constructs standard 2-D filter kernels such as average, Gaussian, Laplacian, Sobel, Prewitt, motion, LoG, unsharp, and disk variants. Kernel parameterization and output shapes follow MATLAB semantics for use with imfilter, filter2, or conv2.
Syntax
H = fspecial(type)
H = fspecial(type, arg1)
H = fspecial(type, arg1, arg2)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
type | StringScalar | Yes | — | Filter name: 'average'|'disk'|'gaussian'|'laplacian'|'log'|'motion'|'prewitt'|'sobel'|'unsharp'. |
arg1 | Any | No | — | Filter-specific parameter (size/radius/lengths/alpha/length depending on type). |
arg1 | Any | No | — | First filter-specific parameter (for example lengths or motion length). |
arg2 | Any | No | — | Second filter-specific parameter (for example sigma or motion angle). |
Returns
| Name | Type | Description |
|---|---|---|
H | NumericArray | Generated 2-D correlation kernel. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:fspecial:InvalidArgument | Filter name or argument count shape is invalid for the selected filter type. | fspecial: invalid argument |
RunMat:fspecial:InvalidInput | Filter parameters have invalid values or unsupported input types. | fspecial: invalid input |
RunMat:fspecial:Internal | Kernel generation fails internally. | fspecial: internal kernel generation failure |
How fspecial works
- 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.
Does RunMat run fspecial 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)Using fspecial with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how fspecial changes the result.
Run a small fspecial example, explain the result, then change one input and compare the output.
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 Image functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how fspecial is executed, line by line, in Rust.
- View the source for fspecial in Rust on GitHub
- Learn how the RunMat 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 blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.