filter2 — Apply 2-D correlation or convolution using MATLAB-compatible semantics.

filter2(H, X) performs a 2-D correlation of the image (or matrix) X with the kernel H. By default the operation returns an array the same size as X, mirroring MATLAB’s behaviour and matching the identity filter2(H, X) == conv2(X, rot90(H, 2), 'same').

How filter2 works in RunMat

• 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.
• Supplying 'conv' rotates the kernel by 180° so the operation matches MATLAB convolution. Use 'corr' for an explicit correlation request; it is the default.
• Inputs may be numeric or logical. Logical arrays are promoted to double precision prior to filtering.
• Both arguments may be gpuArray handles; RunMat keeps them on the device whenever the active acceleration provider exposes the imfilter hook.

How filter2 runs 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.1111

Requesting 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     0

Restricting 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   134

Switching 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    63

Filtering 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    13

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. If either argument is a gpuArray, RunMat forwards the computation to the active acceleration provider and only gathers the data when the provider hook is unavailable.

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 functions to explore

These functions work well alongside filter2. Each page has runnable examples you can try in the browser.

imfilter, fspecial, gpuArray, gather

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how filter2 works, line by line, in Rust.

• View filter2.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.

Getting started · Benchmarks · Pricing