convn

N-D convolution

Syntax

C = convn(A,B)

C = convn(A,B,shape)

Description

C = convn(A,B) returns the N-dimensional convolution of arrays A and B.

C = convn(A,B,shape) returns a subsection of the convolution according to shape. For example, C = convn(A,B,'same') returns the central part of the convolution, which is the same size as A.

Examples

3-D Convolution

You can control the size of the output of the convn function. For example, the 'same' option trims the outer part of the convolution and returns only the central part, which is the same size as the input.

Convolve a random 2-by-3-by-2 array A with a 2-by-2-by-2 kernel B. The result is a 3-by-4-by-3 array, which is size(A) + size(B) - 1.

A = rand(2,3,2);
B = 0.25*ones(2,2,2);
C = convn(A,B)

C = 
C(:,:,1) =

    0.2037    0.2354    0.1898    0.1581
    0.4301    0.6902    0.4426    0.1825
    0.2264    0.4548    0.2527    0.0244


C(:,:,2) =

    0.2733    0.5444    0.4686    0.1975
    0.6365    1.3772    1.2052    0.4645
    0.3632    0.8327    0.7366    0.2670


C(:,:,3) =

    0.0696    0.3090    0.2788    0.0394
    0.2063    0.6869    0.7627    0.2821
    0.1367    0.3779    0.4839    0.2426

sizeC = size(A) + size(B) - 1

sizeC = 1×3

     3     4     3

Return the central part of the convolution, which is the same size as A.

C = convn(A,B,'same')

C = 
C(:,:,1) =

    1.3772    1.2052    0.4645
    0.8327    0.7366    0.2670


C(:,:,2) =

    0.6869    0.7627    0.2821
    0.3779    0.4839    0.2426

Input Arguments

A — Input array

vector | matrix | multidimensional array

Input array, specified as vector, a matrix, or a multidimensional array.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical
Complex Number Support: Yes

B — Second input array

vector | matrix | multidimensional array

Second input array, specified as a vector, a matrix, or a multidimensional array to convolve with A. The array B does not have to be the same size as A.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical
Complex Number Support: Yes

shape — Subsection of convolution

'full' (default) | 'same' | 'valid'

Subsection of the convolution, specified as one of these values:

• 'full' — Return the full N-D convolution.

• 'same' — Return the central part of the convolution, which is the same size as A.

• 'valid' — Return only parts of the convolution that are computed without zero-padded edges.

Output Arguments

C — N-D convolution

vector | matrix | multidimensional array

N-D convolution, returned as a vector, a matrix, or a multidimensional array. If A and B have the same number of dimensions, the full convolution C = convn(A,B) has size size(A)+size(B)-1.

When one or both of A and B are of type single, then the output is of type single. Otherwise, convn converts inputs to type double and returns type double.

Data Types: double | single

More About

N-D Convolution

For discrete, N-dimensional arrays A and B, the following equation defines the convolution of A and B:

$$C(j_1,j_2,\mathrm{...},j_N)={\displaystyle \sum _{k_1}{\displaystyle \sum _{k_2}\mathrm{...}{\displaystyle \sum _{k_N}A(k_1,k_2,\mathrm{...},k_N)B}}}(j_1-k_1+1,j_2-k_2+1,\mathrm{...},j_N-k_N+1)$$

Each k_i runs over all values that lead to legal subscripts of A and B.

Using this definition, convn calculates the direct convolution of two N-dimensional arrays, rather than the FFT-based convolution.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The convn function supports tall arrays with the following usage notes and limitations:

• If shape is 'full' (default), then the inputs A and B must not be empty and only one them can be a tall array.

• If shape is 'same' or 'valid', then B cannot be a tall array.

For more information, see Tall Arrays.

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The convn function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a