filter2 — Apply 2-D correlation/convolution filters in MATLAB and RunMat.
filter2(H, X) performs 2-D correlation of matrix or image data X with kernel H. The documented compatibility surface accepts the same, full, and valid shape options. RunMat mode additionally exposes explicit conv and corr flags. The default matches conv2(X, rot90(H, 2), 'same').
Syntax
B = filter2(h, X)
B = filter2(h, X, options...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
h | Any | Yes | — | Filter kernel. |
X | Any | Yes | — | Input image/array. |
options | Any | Variadic | — | Optional filter2 flags: 'same'|'full'|'valid'|'conv'|'corr'. |
Returns
| Name | Type | Description |
|---|---|---|
B | NumericArray | Filtered output image/array. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:filter2:InvalidInput | Input/kernel tensors are invalid or cannot be converted. | filter2: invalid input |
RunMat:filter2:InvalidOption | One or more option flags are invalid. | filter2: invalid option |
RunMat:filter2:Internal | Internal filtering operation fails. | filter2: internal operation failed |
How filter2 works
- The first argument is the kernel and the second is the image or matrix being filtered.
- The default configuration performs correlation with zero padding and
'same'output sizing. - Passing
'full'or'valid'as the third argument switches the output size to the full convolution result or the strictly valid interior, respectively. - In RunMat extension mode, supplying
'conv'rotates the kernel by 180° and'corr'explicitly requests the default correlation behavior. These flags are not part of MATLAB'sfilter2signature. - Inputs may be numeric or logical. Logical arrays are promoted to double precision prior to filtering.
- Single- and double-precision arguments may be gpuArray handles. Integer and logical gpuArray inputs are separately gated RunMat extensions and gather before floating filtering; they never enter floating provider shaders as native integer buffers.
Does RunMat run filter2 on the GPU?
The builtin delegates to the same acceleration hook that powers imfilter. When the provider implements imfilter, filter2 uploads host-resident kernels on demand, keeps GPU-resident images on the device, and only downloads results when absolutely necessary. Providers that skip the hook trigger a transparent fallback: RunMat gathers the operands to the host and executes the shared reference implementation, guaranteeing MATLAB-compatible results without extra configuration.
GPU memory and residency
Usually not. When the acceleration provider exposes the imfilter hook, filter2 keeps the operands on the GPU and returns a GPU tensor. Host fallbacks are automatic; the builtin gathers data only when the required hook is missing or reports an error. Explicit gpuArray calls remain useful for deterministic residency or backwards compatibility with MATLAB scripts.
Examples
Averaging a matrix with a 3x3 kernel
H = ones(3) / 9;
X = [1 2 3; 4 5 6; 7 8 9];
Y = filter2(H, X)Expected output:
Y =
1.3333 2.3333 1.7778
3.0000 5.0000 3.6667
2.6667 4.3333 3.1111Requesting the full correlation result
H = [1 2; 3 4];
X = [4 1; 2 0];
Y = filter2(H, X, 'full')Expected output:
Y =
16 16 3
16 12 1
4 2 0Restricting the result to the valid interior
H = ones(3);
X = magic(5);
Y = filter2(H, X, 'valid')Expected output:
Y =
100 98 116
99 117 135
118 136 134Switching to convolution mode
H = [1 2; 3 4];
X = [1 2 3; 4 5 6; 7 8 9];
Y = filter2(H, X, 'conv')Expected output:
Y =
1 4 7
7 23 33
19 53 63Filtering data already on the GPU
H = gpuArray([1 0 -1; 1 0 -1; 1 0 -1]);
X = gpuArray([1 2 3; 4 5 6; 7 8 9]);
Y = filter2(H, X);
result = gather(Y)Expected output:
result =
-7 -4 7
-15 -6 15
-13 -4 13Using filter2 with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how filter2 changes the result.
Run a small filter2 example, explain the result, then change one input and compare the output.
FAQ
Can I pass string padding modes like imfilter?⌄
No. filter2 mirrors MATLAB and only accepts 'same', 'full', 'valid', 'corr', and 'conv'. For advanced padding control use imfilter.
Does the builtin normalise the kernel?⌄
No. The kernel is used exactly as supplied. Use helpers such as fspecial or manual scaling when you need a normalised filter.
What happens when the kernel is larger than the image?⌄
'same' still returns an output the same size as the input, padded with zeros where the kernel extends beyond the image. 'valid' returns an empty array whenever the kernel does not fully fit within the image.
Can I combine filter2 with gpuArray inputs?⌄
Yes. A resident image selects its owning provider. RunMat uploads or transfers the kernel to that provider when possible and gathers operands only when the provider hook cannot execute the operation.
Does filter2 support higher-dimensional arrays?⌄
MathWorks MATLAB defines filter2 for 2-D filtering. Use imfilter when you need explicit padding control or want to extend the operation to higher-dimensional arrays.
Does filter2 preserve logical inputs?⌄
Logical arrays are promoted to double precision before filtering, matching MATLAB behaviour.
How do I perform separable filtering efficiently?⌄
Apply successive 1-D filter2 calls with thin kernels or use imfilter for more control over padding and dimensionality.
Related Image functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how filter2 is executed, line by line, in Rust.
- View the source for filter2 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.