RunMat
GitHub

View all functions

CategoryMath: Signal
GPUYes

conv2 — Two-dimensional convolution with MATLAB-compatible padding modes.

conv2 performs two-dimensional linear convolution. By default it returns the *full* convolution (size(A) + size(B) - 1), but it can also return the *same* or *valid* regions so results match MATLAB exactly. The builtin accepts real or complex inputs, logical arrays (promoted to double), and the separable form conv2(hcol, hrow, A) that is common in image processing pipelines.

How does the conv2 function behave in MATLAB / RunMat?

  • conv2(A, B) returns the full 2-D convolution of A and B.
  • conv2(A, B, 'same') slices the central part of the full convolution so the output matches the shape of A.
  • For even-sized kernels with 'same', alignment follows MATLAB's top-left convention in each even dimension.
  • conv2(A, B, 'valid') returns only those points where B overlaps A completely.
  • conv2(hcol, hrow, A) is syntactic sugar for conv2(hcol(:) * hrow(:)', A).
  • Scalars are treated as 1×1 matrices and preserve the orientation of the other input.
  • Empty inputs follow MATLAB’s rules: conv2([], X) and conv2(X, []) return empty matrices (or zero-sized slices for 'same').
  • Logical inputs are promoted to double precision before computation; complex inputs preserve their imaginary part throughout the convolution.

GPU behavior

RunMat Accelerate keeps tensors on the GPU when the active provider implements a conv2d hook (the in-process provider uses the host implementation and returns a GPU handle; the WGPU backend will adopt a native kernel). When the hook is unavailable, RunMat gathers GPU inputs to the host, performs the convolution on the CPU, and returns a host tensor. Documentation and the GPU metadata make this fallback explicit so providers can add native implementations without changing this builtin.

Examples of using conv2 in MATLAB / RunMat

Smoothing an image patch with a 3×3 averaging kernel

A = [1 2 3; 4 5 6; 7 8 9];
h = ones(3) / 9;
smoothed = conv2(A, h, 'same')

Expected output:

smoothed =
    1.3333    2.3333    1.7778
    3.0000    5.0000    3.6667
    2.6667    4.3333    3.1111

Computing the full convolution of two small kernels

K1 = [1 2; 3 4];
K2 = [1 1; 1 1];
C = conv2(K1, K2)

Expected output:

C =
     1     3     2
     4    10     6
     3     7     4

Extracting the same-sized result to preserve dimensions

edge = conv2([1 2 3; 4 5 6; 7 8 9], [1 0 -1; 1 0 -1; 1 0 -1], 'same')

Expected output:

edge =
    -7    -4     7
   -15    -6    15
   -13    -4    13

Valid convolution for sliding-window statistics

block = magic(4);
kernel = ones(2);
valid = conv2(block, kernel, 'valid')

Expected output:

valid =
    34    26    34
    32    34    36
    34    42    34

Using the separable form with column and row vectors

hcol = [1; 2; 1];
hrow = [1 0 -1];
A = [3 4 5; 6 7 8; 9 10 11];
gx = conv2(hcol, hrow, A, 'same')

Expected output:

gx =
    27    -6   -27
    28    -8   -28
    15    -6   -15

Convolving gpuArray inputs with transparent fallbacks

G = gpuArray(rand(128, 128));
H = gpuArray([1 2 1; 0 0 0; -1 -2 -1]);
gx = conv2(G, H, 'same');
result = gather(gx)

FAQ

Does conv2 support the three MATLAB shape modes?

Yes. Pass 'full', 'same', or 'valid' as the final argument and RunMat will mirror MATLAB’s output sizes and edge handling precisely.

How do I use the separable form?

Call conv2(hcol, hrow, A) (optionally with a shape argument). RunMat converts the vectors into an outer-product kernel internally so it behaves exactly like MATLAB.

What happens if one input is empty?

An empty input produces an empty output (or a zero-sized slice for 'same'). This follows MATLAB’s behaviour and avoids surprising dimension growth.

Do logical inputs work?

Yes. Logical arrays are promoted to double precision before convolution so the result is numeric.

Will the result stay on the GPU?

If the active provider exposes the conv2d hook the result stays device-resident. Otherwise RunMat falls back to the CPU path and returns a host tensor; this fallback is documented so providers can add native kernels without breaking compatibility.

See also

conv, filter2, imfilter, gpuArray, gather

Source & Feedback