convolve

Convolution Integral for any 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	convolve (const array &col_filter, const array &row_filter, const array &signal, const convMode mode=AF_CONV_DEFAULT)
	C++ Interface for separable convolution on two dimensional signals. More...
AFAPI af_err	af_convolve2_sep (af_array *out, const af_array col_filter, const af_array row_filter, const af_array signal, const af_conv_mode mode)
	C Interface for separable convolution on two dimensional signals. More...

Detailed Description

Convolution Integral for any 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 dimensions of the input signal and the filter signal, 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 dimension of Signal and Filter should not be the same.

For example, if the signal is two dimensional with m & n as sizes along the 0th & 1st dimensions respectively, then the possible batch operations are as follows.

Input Signal Dimensions	Filter Dimensions	Output Dimensions	Batch Mode	Explanation
[m n 1 1]	[m n 1 1]	[m n 1 1]	No Batch	Output will be a single convolve array
[m n 1 1]	[m n p 1]	[m n p 1]	Filter is Batched	p filters applied to same input
[m n p 1]	[m n 1 1]	[m n p 1]	Signal is Batched	1 filter applied to p inputs
[m n p 1]	[m n p 1]	[m n p 1]	Identical Batches	p filters applied to p inputs in one-to-one correspondence
[m n p 1]	[m n 1 q]	[m n p q]	Non-overlapping batches	q filters applied to p inputs in to produce p x q results
[m n 1 p]	[m n q 1]	[m n q p]	Non-overlapping batches	q filters applied to p inputs in to produce q x p results

Function Documentation

AFAPI af_err af_convolve2_sep	(	af_array *	out,
		const af_array	col_filter,
		const af_array	row_filter,
		const af_array	signal,
		const af_conv_mode	mode
	)

C Interface for separable convolution on two dimensional signals.

Parameters

[out]	out	is convolved array
[in]	col_filter	is filter that has to be applied along the coloumns
[in]	row_filter	is filter that has to be applied along the rows
[in]	signal	is the input array
[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.

Note

Separable convolution only supports two(ONE-to-ONE and MANY-to-ONE) batch modes from the ones described in the detailed description section.

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

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

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, image_processing/adaptive_thresholding.cpp, image_processing/binary_thresholding.cpp, image_processing/brain_segmentation.cpp, image_processing/edge.cpp, image_processing/filters.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.

AFAPI array af::convolve	(	const array &	col_filter,
		const array &	row_filter,
		const array &	signal,
		const convMode	mode = AF_CONV_DEFAULT
	)

C++ Interface for separable convolution on two dimensional signals.

    //vector<dim4> numDims;
    //vector<vector<float> > in;
    af::array signal(numDims[0], &(in[0].front()));
    //signal dims = [3 4 2 1]
    af::array cFilter(numDims[1], &(in[1].front()));
    //coloumn filter dims = [2 1 1 1]
    af::array rFilter(numDims[2], &(in[2].front()));
    //row filter dims = [3 1 1 1]

    af::array output = convolve(cFilter, rFilter, signal, AF_CONV_DEFAULT);
    //output signal dims = [3 4 2 1] - same as input since 'expand = false'
    //notice that the input signal is 3d array, therefore
    //batch mode will be automatically activated.
    //output will be 3d array with result of each 2d array convolution(with same filter)
    //stacked along the 3rd dimension

Parameters

[in]	signal	is the input signal
[in]	col_filter	is the signal that shall be along coloumns
[in]	row_filter	is the signal that shall be along rows
[in]	mode	indicates if the convolution should be expanded or not(where output size equals input)

Returns

the convolved array

Note

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

Separable convolution only supports two(ONE-to-ONE and MANY-to-ONE) batch modes from the ones described in the detailed description section.