filter2 — Apply two-dimensional correlation or convolution to an image.
filter2(H,X) correlates an image with a kernel using zero padding and same-size output. It is equivalent to conv2(X,rot90(H,2),'same') for the default real-valued form.
Syntax
B = filter2(h, X)
B = filter2(h, X, options...)Inputs
h- Type
Any- Required
- Yes
- Description
- Filter kernel.
X- Type
Any- Required
- Yes
- Description
- Input image/array.
options- Type
Any- Required
- Variadic
- Description
- Optional filter2 flags: 'same'|'full'|'valid'|'conv'|'corr'.
Returns
B- Type
NumericArray- Description
- Filtered output image/array.
Errors
RunMat:filter2:InvalidInput- When
- Input/kernel tensors are invalid or cannot be converted.
- Message
filter2: invalid input
RunMat:filter2:InvalidOption- When
- One or more option flags are invalid.
- Message
filter2: invalid option
RunMat:filter2:Internal- When
- Internal filtering operation fails.
- Message
filter2: internal operation failed
Forms and options
The first argument H is the kernel and the second X is the image. same is the default output shape; full includes every overlap and valid includes only complete overlaps. A kernel larger than the image yields an empty valid result. Options are processed left to right; the last shape or mode flag wins.
RunMat-gated conv rotates the kernel by 180 degrees and corr explicitly selects default correlation. More than one trailing option and inputs above rank two are separately gated extensions. For advanced padding use imfilter.
Real numeric and logical host inputs are admitted. Logical values enter double computation; a single operand makes the output single, otherwise the output is double. MATLAB-compatible gpuArray operands are floating single/double; integer/logical gpuArray forms have separate RunMat gates and materialize before floating computation.
Resident execution
A resident image selects its exact provider owner. The optional imfilter hook may execute the complete filter and publish a new resident result; unsupported hooks use the host implementation. Operational provider failures retain their source and do not silently replay. A resident kernel with a host image is gathered for the host result.
The operation is a fusion boundary. Invalid options and known-invalid image/kernel geometry are rejected before resident transfer or kernel upload. Provider outputs must have the expected shape, floating class, live allocation, and exact owner, and must not alias either input.
Examples
Correlate with a box kernel
H = ones(3)/9; X = [1 2 3;4 5 6;7 8 9]; Y = filter2(H,X); size(Y)Expected output:
ans = [3 3]Full correlation extent
H = [1 2;3 4]; X = [4 1;2 0]; Y = filter2(H,X,'full'); size(Y)Expected output:
ans = [3 3]Valid interior
H = ones(3); X = magic(5); Y = filter2(H,X,'valid'); size(Y)Expected output:
ans = [3 3]Convolution extension
H = [1 2;3 4]; X = [1 2 3;4 5 6;7 8 9]; Y = filter2(H,X,'conv'); size(Y)Expected output:
ans = [3 3]Filter a resident image
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); size(result)Expected output:
ans = [3 3]Using 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
Does filter2 normalize H?⌄
No. H is used exactly as supplied; fspecial can generate normalized smoothing kernels.
Can H be larger than X?⌄
Yes. same keeps X's shape; valid has a zero-length axis when H cannot fit.
Can I use imfilter padding names?⌄
No. filter2 accepts same, full, valid and RunMat-gated conv/corr. Use imfilter for replicate, symmetric, circular, or fill padding.
Can I filter gpuArray data?⌄
Yes. Floating resident X may use its owning provider's imfilter hook. A typed unsupported hook may gather for host computation; other provider failures propagate.
Does filter2 preserve logical class?⌄
No. Logical input enters the double computation domain.
How should I do separable filtering?⌄
Apply thin one-dimensional kernels in successive calls or use imfilter for explicit padding control.
Related Image functions
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.