RunMat
GitHub

View all functions

CategoryImage: Filters
GPUYes

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 does the filter2 function behave in MATLAB / 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.

GPU behavior

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 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 of using filter2 in MATLAB / RunMat

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.

See also

imfilter, fspecial, gpuArray, gather

Source & Feedback