RunMat
GitHub

View all functions

CategoryImage: Filters

What does the imfilter function do in MATLAB / RunMat?

imfilter applies N-D linear filters (correlation or convolution) to numeric or logical arrays. It provides MATLAB-compatible padding modes ('replicate', 'symmetric', 'circular', 'fill'), supports 'same', 'full', and 'valid' output sizing, and can operate on GPU-resident tensors when RunMat Accelerate exposes the dedicated provider hook.

How does the imfilter function behave in MATLAB / RunMat?

  • By default it performs correlation ('corr') and returns an array the same size as the input ('same') using zero padding.
  • Passing 'fill' without an explicit value (or supplying a numeric scalar on its own) is equivalent to zero padding; the numeric argument can appear before or after the 'fill' flag.
  • Convolution mode is available via the 'conv' flag and matches convn semantics.
  • Padding modes control how out-of-bound indices are resolved: zero-fill (default 'fill'/'fill', 0 or a numeric pad value), 'replicate', 'symmetric', or 'circular'.
  • Output sizing options determine whether RunMat crops ('same'), keeps the full convolution result ('full'), or returns only pixels covered completely by the kernel ('valid').
  • Kernels may be generated by fspecial or authored manually; no automatic normalisation is applied.
  • Logical inputs are promoted to double precision (0.0/1.0) and all results are returned as double-precision tensors for MATLAB compatibility.
  • Multi-channel and higher-dimensional arrays are supported provided the filter dimensions are 1 along trailing axes that do not exist in the image.

imfilter Function GPU Execution Behaviour

When the active acceleration provider implements the custom imfilter hook, the builtin keeps the image and kernel on the device, honouring padding and size options without host round-trips. Mixed-residency inputs are handled automatically: device images cause host kernels to be uploaded on demand, and failures to upload or execute simply fall back to the reference path. Providers that do not yet expose this hook trigger a transparent fallback—RunMat gathers the operands to the host, executes the scalar reference implementation, and (when appropriate) returns a host tensor. This guarantees correctness while still allowing future GPU acceleration with no API surface changes.

Examples of using the imfilter function in MATLAB / RunMat

Smoothing an image with a 3x3 average filter

I = [1 2; 3 4];
H = ones(3) / 9;
J = imfilter(I, H);          % default zero padding, correlation

Expected output:

J =
    1.1111    1.1111
    1.1111    1.1111

Preserving borders with replicate padding

I = magic(3);
H = ones(3);
J = imfilter(I, H, 'replicate');

Expected output:

J =
    45    45    45
    45    45    45
    45    45    45

Computing the full convolution result

I = [1 2; 3 4];
H = [1 2; 3 4];
J = imfilter(I, H, 'full');

Expected output:

J =
     0     0     0
     0     4    11
     0    14    30

Switching to convolution mode

I = reshape(1:6, [3 2]);
H = [1 2; 3 4];
J = imfilter(I, H, 'conv');      % equivalent to convn(I, rot90(H,2), 'same')

Expected output:

J =
     1     6
     5    25
     9    35

Wrapping edges with circular padding

I = [1 2; 3 4];
H = [0 1; 1 0];
J = imfilter(I, H, 'circular');

Expected output:

J =
     5     5
     5     5

GPU residency in RunMat (Do I need gpuArray?)

RunMat automatically keeps tensors on the GPU when the acceleration provider implements the imfilter hook, so explicit gpuArray calls are rarely necessary. For backwards compatibility and manual residency control, you may still wrap inputs in gpuArray; the builtin forwards handles directly to the provider. When the hook is absent, RunMat gathers arrays to the host transparently, ensuring functional parity with MATLAB even without a GPU implementation.

FAQ

Which modes does imfilter support?

The builtin accepts 'corr' (default) or 'conv' to switch between correlation and convolution. Convolution is equivalent to correlating with the kernel rotated 180° in each dimension.

How do 'same', 'full', and 'valid' differ?

'same' crops the result to the input size, 'full' preserves every contribution from the convolution, and 'valid' keeps only elements where the kernel lies fully within the original array (possibly returning empty slices).

How does zero padding differ from 'fill'?

Passing a numeric scalar (or the 'fill', padval sequence) pads the image with that constant value. The default behaviour is equivalent to 'fill', 0.

Can I filter RGB or higher-dimensional arrays?

Yes. The kernel must either match each image dimension or use size 1 along trailing axes (e.g., a 3×3×1 filter applied independently to each colour channel).

Does imfilter normalise the kernel automatically?

No. The kernel is used exactly as supplied. Utilities such as fspecial('average', ...) or manual scaling should be used when normalisation is desired.

What happens when the kernel is larger than the image?

For 'same' and 'full', the builtin applies the filter with the chosen padding, producing sensible output. 'valid' returns an empty array for dimensions where the kernel exceeds the image size.

How does imfilter interact with the fusion planner?

The builtin registers a custom GPU spec rather than a fusion template. The planner treats it as a standalone op, enabling provider specialisation without attempting to fold it into generic fusion chains.

Is logical input supported?

Yes. Logical arrays are promoted to double precision (0.0/1.0) during filtering, mirroring MATLAB behaviour.

See Also

fspecial, gpuArray, gather

Source & Feedback