A high-performance general-purpose compute library

- Main Page
- Tutorials
- Release Notes
- Examples

Functions
convolve3
ArrayFire Functions | ArrayFire Functions by Category » Signal Processing » Convolutions

Convolution Integral for three dimensional data More...

## Functions
AFAPI array | convolve3 (const array &signal, const array &filter, const convMode mode=AF_CONV_DEFAULT, const convDomain domain=AF_CONV_AUTO)
| C++ Interface for convolution on three dimensional signals.
AFAPI array | fftConvolve3 (const array &signal, const array &filter, const convMode mode=AF_CONV_DEFAULT)
| C++ Interface for convolution on 3D signals using FFT.
AFAPI af_err | af_convolve3 (af_array *out, const af_array signal, const af_array filter, const af_conv_mode mode, af_conv_domain domain)
| C Interface for convolution on three dimensional signals.
AFAPI af_err | af_fft_convolve3 (af_array *out, const af_array signal, const af_array filter, const af_conv_mode mode)
| C Interface for convolution on 3D signals using FFT.

## Detailed Description

Convolution Integral for 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.

For three dimensional inputs with m, n & p sizes along the 0th, 1st & 2nd axes respectively, given below are the possible batch operations.

Signal Size | Filter Size | Output Size | Batch Mode | Description
--- | --- | --- | --- | ---
\( [m \ n \ p \ 1] \) | \( [a \ b \ c \ 1] \) | \( [m \ n \ p \ 1] \) | No Batch | Output will be a single convolve array
\( [m \ n \ p \ 1] \) | \( [a \ b \ c \ d] \) | \( [m \ n \ p \ d] \) | Filter is Batched | d filters applied to same input
\( [m \ n \ p \ q] \) | \( [a \ b \ c \ 1] \) | \( [m \ n \ p \ q] \) | Signal is Batched | 1 filter applied to q inputs
\( [m \ n \ p \ k] \) | \( [a \ b \ c \ k] \) | \( [m \ n \ p \ k] \) | Identical Batches | k filters applied to k inputs in one-to-one correspondence

Note
  For the above tabular illustrations, we assumed af_conv_mode is AF_CONV_DEFAULT.

## Function Documentation

## ◆ af_convolve3()

AFAPI af_err af_convolve3 | ( | af_array * | out,
|  | const af_array | signal,
|  | const af_array | filter,
|  | const af_conv_mode | mode,
|  | af_conv_domain | domain )

C Interface for convolution on three dimensional signals.

Parameters

  [out] | out | is convolved array
  [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
  AF_SUCCESS if the convolution is successful, otherwise an appropriate error code is returned.

Note
  The default parameter of `domain`, AF_CONV_AUTO, heuristically switches between frequency and spatial domain.

## ◆ af_fft_convolve3()

AFAPI af_err af_fft_convolve3 | ( | af_array * | out,
|  | const af_array | signal,
|  | const af_array | filter,
|  | const af_conv_mode | mode )

C Interface for convolution on 3D signals using FFT.

Parameters

  [out] | out | is convolved array
  [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
  AF_SUCCESS if the convolution is successful, otherwise an appropriate error code is returned.

## ◆ convolve3()

AFAPI array convolve3 | ( | const array & | signal,
|  | const array & | filter,
|  | const convMode | mode = AF_CONV_DEFAULT,
|  | const convDomain | domain = AF_CONV_AUTO )

C++ Interface for convolution on three dimensional signals.

// vector<dim4> numDims;
// vector<vector<float> > in;
array signal(numDims[0], &(in[0].front()));
// signal dims = [10 11 2 2]
array filter(numDims[1], &(in[1].front()));
// filter dims = [4 2 3 2]
array output = convolve3(signal, filter, AF_CONV_DEFAULT);
// output dims = [10 11 2 2] - same as input since expand(3rd argument is
// false) however, notice that the 4th dimension is > 1 for both signal and
// the filter, therefore many to many batch mode will be activated where
// each 3d signal is convolved with the corresponding 3d filter

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.

## ◆ fftConvolve3()

AFAPI array fftConvolve3 | ( | const array & | signal,
|  | const array & | filter,
|  | const convMode | mode = AF_CONV_DEFAULT )

C++ Interface for convolution on 3D signals using FFT.

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