convolve (Non-separable)

Convolution Integral for any(one through three) dimensional data. More...

## Functions

AFAPI array convolve (const array &signal, const array &filter, const convMode mode=AF_CONV_DEFAULT, const convDomain domain=AF_CONV_AUTO)
C++ Interface for convolution any(one through three) dimensional signals. More...

AFAPI array fftConvolve (const array &signal, const array &filter, const convMode mode=AF_CONV_DEFAULT)
C++ Interface for FFT-based convolution any(one through three) dimensional signals. More...

## Detailed Description

Convolution Integral for any(one through three) dimensional data.

A convolution is a common operation between a source array, a, and a filter (or kernel) array b. The answer to the convolution is the same as computing the coefficients in polynomial multiplication, if a and b are the coefficients.

Another way to think about it is that the filter kernel is centered on each pixel in a, and the output for that pixel or data point is the sum of the products.

Depending on the size of the signal and the filter, any one of the following batch mode convolutions take place.

• No Batch - Single filter applied to single input.
• Filter is Batched - Many filters applied on same input
• Signal is Batched - Single filter applied to a set of inputs.
• Identical Batches - A set of filters applied onto to a set of inputs in one-to-one correspondence.
• Non overlapping Batches - All batched filters are applied to all batched signals. The batch axis of Signal and Filter should not be the same.
Note
All non-overlapping(interleaved) convolutions default to frequency domain AF_CONV_FREQ irrespective of the provided convolution mode argument.

This version of convolution function delegates the call to respective 1D, 2D or 3D convolution functions internally.

Convolution dimensionality is $$\min (sd, fd)$$ where sd & fd are dimensionality of signal and filter respectively. This formulation only decides the dimensionality of convolution.

Given below are some examples on how convolution dimensionality is computed.

Signal Size Filter Size Input Rank Filter Rank Convolve Dimensionality
$$[m \ n \ 1 \ 1]$$ $$[m \ 1 \ 1 \ 1]$$ 2 1 $$min(2, 1) =>$$ 1D
$$[m \ 1 \ 1 \ 1]$$ $$[m \ n \ 1 \ 1]$$ 1 2 $$min(1, 2) =>$$ 1D
$$[m \ n \ 1 \ 1]$$ $$[m \ n \ 1 \ 1]$$ 2 2 $$min(2, 2) =>$$ 2D
$$[m \ n \ 1 \ 1]$$ $$[m \ n \ p \ 1]$$ 2 3 $$min(2, 3) =>$$ 2D
$$[m \ n \ 1 \ p]$$ $$[m \ n \ 1 \ q]$$ 4 4 3D
$$[m \ n \ p \ 1]$$ $$[m \ n \ q \ 1]$$ 3 3 $$min(3, 3) =>$$ 3D
Note
In the cases similar to the fifth row of the above table, signal and filter are of rank 4, the function delegates the operation to three dimensional convolution convolve3

If the operation you intend to perform doesn't align with what this function does, please check the rank specific convolve functions (hyperlinked below) documentation to find out more.

## ◆ convolve()

 AFAPI array af::convolve ( const array & signal, const array & filter, const convMode mode = AF_CONV_DEFAULT, const convDomain domain = AF_CONV_AUTO )

C++ Interface for convolution any(one through three) dimensional signals.

Example for convolution on one dimensional signal in one to one batch mode

array a = randu(10);
// af_print(a);
// a [10 1 1 1] = 0.0000 0.1315 0.7556 0.4587 0.5328 0.2190 0.0470 0.6789
// 0.6793 0.9347
array b = randu(4);
// af_print(b);
// b [4 1 1 1] = 0.3835 0.5194 0.8310 0.0346
array c = convolve(a, b);
// af_print(c);
// c [10 1 1 1] = 0.3581 0.6777 1.0750 0.7679 0.5903 0.4851 0.6598
// 1.2770 1.0734 0.8002
A multi dimensional data container.
Definition: array.h:37
AFAPI array randu(const dim4 &dims, const dtype ty, randomEngine &r)
AFAPI array convolve(const array &signal, const array &filter, const convMode mode=AF_CONV_DEFAULT, const convDomain domain=AF_CONV_AUTO)
C++ Interface for convolution any(one through three) dimensional signals.

Example for convolution on two dimensional signal in one to one batch mode

array d = constant(0.5, 5, 5);
// af_print(d);
// d [5 5 1 1]
// 0.5000 0.5000 0.5000 0.5000 0.5000
// 0.5000 0.5000 0.5000 0.5000 0.5000
// 0.5000 0.5000 0.5000 0.5000 0.5000
// 0.5000 0.5000 0.5000 0.5000 0.5000
// 0.5000 0.5000 0.5000 0.5000 0.5000
array e = constant(1, 2, 2);
// af_print(e);
// e [2 2 1 1]
// 1.0000 1.0000
// 1.0000 1.0000
array f = convolve(d, e);
// af_print(f);
// f [5 5 1 1]
// 2.0000 2.0000 2.0000 2.0000 1.0000
// 2.0000 2.0000 2.0000 2.0000 1.0000
// 2.0000 2.0000 2.0000 2.0000 1.0000
// 2.0000 2.0000 2.0000 2.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000 0.5000
array constant(T val, const dim4 &dims, const dtype ty=(af_dtype) dtype_traits< T >::ctype)

Example for convolution on three dimensional signal in one to one batch mode

array g = constant(1, 4, 4, 4);
// af_print(g);
// g [4 4 4 1]
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
// 1.0000 1.0000 1.0000 1.0000
array h = constant(0.5, 2, 2, 2);
// af_print(h);
// h [2 2 2 1]
// 0.5000 0.5000
// 0.5000 0.5000
// 0.5000 0.5000
// 0.5000 0.5000
array i = convolve(g, h);
// af_print(i);
// i [4 4 4 1]
// 4.0000 4.0000 4.0000 2.0000
// 4.0000 4.0000 4.0000 2.0000
// 4.0000 4.0000 4.0000 2.0000
// 2.0000 2.0000 2.0000 1.0000
// 4.0000 4.0000 4.0000 2.0000
// 4.0000 4.0000 4.0000 2.0000
// 4.0000 4.0000 4.0000 2.0000
// 2.0000 2.0000 2.0000 1.0000
// 4.0000 4.0000 4.0000 2.0000
// 4.0000 4.0000 4.0000 2.0000
// 4.0000 4.0000 4.0000 2.0000
// 2.0000 2.0000 2.0000 1.0000
// 2.0000 2.0000 2.0000 1.0000
// 2.0000 2.0000 2.0000 1.0000
// 2.0000 2.0000 2.0000 1.0000
// 1.0000 1.0000 1.0000 0.5000
Parameters
 [in] signal is the input signal [in] filter is the signal that shall be flipped for the convolution operation [in] mode indicates if the convolution should be expanded or not(where output size equals input) [in] domain specifies if the convolution should be performed in frequency os spatial domain
Returns
the convolved array
Note
The default parameter of domain, AF_CONV_AUTO, heuristically switches between frequency and spatial domain.
Examples
computer_vision/harris.cpp, getting_started/convolve.cpp, graphics/conway.cpp, graphics/conway_pretty.cpp, graphics/gravity_sim.cpp, image_processing/adaptive_thresholding.cpp, image_processing/binary_thresholding.cpp, image_processing/brain_segmentation.cpp, image_processing/deconvolution.cpp, image_processing/edge.cpp, image_processing/filters.cpp, image_processing/gradient_diffusion.cpp, image_processing/image_demo.cpp, image_processing/image_editing.cpp, image_processing/morphing.cpp, image_processing/optical_flow.cpp, image_processing/pyramids.cpp, and pde/swe.cpp.

## ◆ fftConvolve()

 AFAPI array af::fftConvolve ( const array & signal, const array & filter, const convMode mode = AF_CONV_DEFAULT )

C++ Interface for FFT-based convolution any(one through three) dimensional signals.

Parameters
 [in] signal is the input signal [in] filter is the signal that shall be used for the convolution operation [in] mode indicates if the convolution should be expanded or not(where output size equals input)
Returns
the convolved array