Main Content

dlconv

Deep learning convolution

collapse all in page

Syntax

dlY = dlconv(dlX,weights,bias)
dlY = dlconv(dlX,weights,bias,'DataFormat',FMT)
dlY = dlconv(___,Name,Value)

Description

The convolution operation applies sliding filters to the input data. Use thedlconvfunction for deep learning convolution, grouped convolution, and channel-wise separable convolution.

Thedlconvfunction applies the deep learning convolution operation todlarraydata.Usingdlarrayobjects makes working with high dimensional data easier by allowing you to label the dimensions. For example, you can label which dimensions correspond to spatial, time, channel, and batch dimensions using the"S","T","C", and"B"labels, respectively. For unspecified and other dimensions, use the“U"label. Fordlarrayobject functions that operate over particular dimensions, you can specify the dimension labels by formatting thedlarrayobject directly, or by using theDataFormatoption.

Note

To apply convolution within alayerGraphobject orLayerarray, use one of the following layers:

example

dlY= dlconv(dlX,weights,bias)applies the deep learning convolution operation to the formatteddlarrayobjectdlX. The function uses sliding convolutional filters defined byweightsand adds the constantbias. The outputdlYis a formatteddlarrayobject with the same format asdlX.

The function, by default, convolves over up to three dimensions ofdlXlabeled'S'(spatial). To convolve over dimensions labeled'T'(time), specifyweightswith a'T'dimension using a formatteddlarrayobject or by using the'WeightsFormat'option.

For unformatted input data, use the'DataFormat'option.

example

dlY= dlconv(dlX,weights,bias,'DataFormat',FMT)applies the deep learning convolution operation to the unformatteddlarrayobjectdlXwith format specified byFMTusing any of the previous syntaxes. The outputdlYis an unformatteddlarrayobject with dimensions in the same order asdlX. For example,'DataFormat','SSCB'specifies data for 2-D convolution with format'SSCB'(spatial, spatial, channel, batch).

example

dlY= dlconv(___,Name,Value)specifies options using one or more name-value pair arguments using any of the previous syntaxes. For example,'WeightsFormat','TCU'specifies weights for 1-D convolution with format'TCU'(time, channel, unspecified).

Examples

collapse all

Open Live Script

Create a formatteddlarrayobject containing a batch of 128 28-by-28 images with 3 channels. Specify the format'SSCB'(spatial, spatial, channel, batch).

miniBatchSize = 128; inputSize = [28 28]; numChannels = 3; X = rand(inputSize(1),inputSize(2),numChannels,miniBatchSize); dlX = dlarray(X,'SSCB');

View the size and format of the input data.

size(dlX)
ans =1×428 28 3 128
dims(dlX)
ans = 'SSCB'

Initialize the weights and bias for 2-D convolution. For the weights, specify 64 3-by-3 filters. For the bias, specify a vector of zeros.

filterSize = [3 3]; numFilters = 64; weights = rand(filterSize(1),filterSize(2),numChannels,numFilters); bias = zeros(1,numFilters);

Apply 2-D convolution using thedlconvfunction.

dlY = dlconv(dlX,weights,bias);

View the size and format of the output.

size(dlY)
ans =1×426 26 64 128
dims(dlY)
ans = 'SSCB'
Open Live Script

Convolve the input data in three groups of two channels each. Apply four filters per group.

Create the input data as 10 observations of size 100-by-100 with six channels.

height = 100; width = 100; channels = 6; numObservations = 10; X = rand(height,width,channels,numObservations); dlX = dlarray(X,'SSCB');

Initialize the convolutional filters. Specify three groups of convolutions that each apply four convolution filters to two channels of the input data.

filterHeight = 8; filterWidth = 8; numChannelsPerGroup = 2; numFiltersPerGroup = 4; numGroups = 3; weights = rand(filterHeight,filterWidth,numChannelsPerGroup,numFiltersPerGroup,numGroups);

Initialize the bias term.

bias = rand(numFiltersPerGroup*numGroups,1);

Perform the convolution.

dlY = dlconv(dlX,weights,bias); size(dlY)
ans =1×493 93 12 10
dims(dlY)
ans = 'SSCB'

The 12 channels of the convolution output represent the three groups of convolutions with four filters per group.

Open Live Script

Separate the input data into channels and perform convolution on each channel separately.

Create the input data as a single observation with a size of 64-by-64 and 10 channels. Create the data as an unformatteddlarray.

height = 64; width = 64; channels = 10; X = rand(height,width,channels); dlX = dlarray(X);

Initialize the convolutional filters. Specify an ungrouped convolution that applies a single convolution to all three channels of the input data.

filterHeight = 8; filterWidth = 8; numChannelsPerGroup = 1; numFiltersPerGroup = 1; numGroups = channels; weights = rand(filterHeight,filterWidth,numChannelsPerGroup,numFiltersPerGroup,numGroups);

Initialize the bias term.

bias = rand(numFiltersPerGroup*numGroups,1);

Perform the convolution. Specify the dimension labels of the input data using the'DataFormat'option.

dlY = dlconv(dlX,weights,bias,'DataFormat','SSC'); size(dlY)
ans =1×357 57 10

Each channel is convolved separately, so there are 10 channels in the output.

Open Live Script

Create a formatteddlarrayobject containing 128 sequences of length 512 containing 5 features. Specify the format'CBT'(channel, batch, time).

numChannels = 5; miniBatchSize = 128; sequenceLength = 512; X = rand(numChannels,miniBatchSize,sequenceLength); dlX = dlarray(X,'CBT');

Initialize the weights and bias for 1-D convolution. For the weights, specify 64 filters with a filter size of 3. For the bias, specify a vector of zeros.

filterSize = 3; numFilters = 64; weights = rand(filterSize,numChannels,numFilters); bias = zeros(1,numFilters);

Apply 1-D convolution using thedlconvfunction. To convolve over the'T'(time) dimension of the input data, specify the weights format'TCU'(time, channel, unspecified) using the'WeightsFormat'option.

dlY = dlconv(dlX,weights,bias,'WeightsFormat','TCU');

View the size and format of the output.

size(dlY)
ans =1×364 128 510
dims(dlY)
ans = 'CBT'

Input Arguments

collapse all

Input data, specified as a formatteddlarray, an unformatteddlarray, or a numeric array.

IfdlXis an unformatteddlarrayor a numeric array, then you must specify the format using the'DataFormat'option. IfdlXis a numeric array, then eitherweightsorbiasmust be adlarrayobject.

The function, by default, convolves over up to three dimensions ofdlXlabeled'S'(spatial). To convolve over dimensions labeled'T'(time), specifyweightswith a'T'dimension using a formatteddlarrayobject or by using the'WeightsFormat'option.

卷积过滤器,指定为一个格式化的dlarray, an unformatteddlarray, or a numeric array.

The size and format of the weights depends on the type of task. Ifweightsis an unformatteddlarrayor a numeric array, then the size and shape ofweightsdepends on the'WeightsFormat'option.

The following table describes the size and format of the weights for various tasks. You can specify an array with the dimensions in any order using formatteddlarrayobjects or by using the'WeightsFormat'option. When the weights has multiple dimensions with the same label (for example, multiple dimensions labeled'S'), then those dimensions must be in ordered as described in this table.

Task Required Dimensions 大小 Example
Weights Format
1-D convolution 'S'(spatial) or'T'(time) Filter size

filterSize-by-numChannels-by-numFiltersarray, wherefilterSizeis the size of the 1-D filters,numChannelsis the number of channels of the input data, andnumFiltersis the number of filters.

 'SCU'(spatial, channel, unspecified)
'C'(channel) Number of channels
'U'(unspecified) Number of filters
1-D grouped convolution 'S'(spatial) or'T'(time) Filter size

filterSize-by-numChannelsPerGroup-by-numFiltersPerGroup-by-numGroupsarray, wherefilterSizeis the size of the 1-D filters,numChannelsPerGroupis the number of channels per group of the input data, andnumFiltersPerGroupis the number of filters per group.

numChannelsPerGroupmust equal the number of the channels of the input data divided bynumGroups.

 'SCUU'(spatial, channel, unspecified, unspecified)
'C'(channel) Number of channels per group
First'U'(unspecified) Number of filters per group
Second'U'(unspecified) Number of groups
2-D convolution First'S'(spatial) Filter height

filterSize(1)-by-filterSize(2)-by-numChannels-by-numFiltersarray, wherefilterSize(1)andfilterSize(2)are the height and width of the 2-D filters, respectively,numChannelsis the number of channels of the input data, andnumFiltersis the number of filters.

 'SSCU'(spatial, spatial, channel, unspecified)
Second'S'(spatial) or'T'(time) Filter width
'C'(channel) Number of channels
'U'(unspecified) Number of filters
2-D grouped convolution First'S'(spatial) Filter height

filterSize(1)-by-filterSize(2)-by-numChannelsPerGroup-by-numFiltersPerGroup-by-numGroupsarray, wherefilterSize(1)andfilterSize(2)are the height and width of the 2-D filters, respectively,numChannelsPerGroupis the number of channels per group of the input data, andnumFiltersPerGroupis the number of filters per group.

numChannelsPerGroupmust equal the number of the channels of the input data divided bynumGroups.

 'SSCUU'(spatial, spatial, channel, unspecified, unspecified)
Second'S'(spatial) or'T'(time) Filter width
'C'(channel) Number of channels per group
First'U'(unspecified) Number of filters per group
Second'U'(unspecified) Number of groups
3-D convolution First'S'(spatial) Filter height

filterSize(1)-by-filterSize(2)-by-filterSize(3)-by-numChannels-by-numFiltersarray, wherefilterSize(1),filterSize(2), andfilterSize(3)are the height, width, and depth of the 3-D filters, respectively,numChannelsis the number of channels of the input data, andnumFiltersis the number of filters.

 'SSSCU'(spatial, spatial, spatial, channel, unspecified)
Second'S'(spatial) Filter width
Third'S'(spatial) or'T'(time) Filter depth
'C'(channel) Number of channels
'U'(unspecified) Number of filters

channel-wise分离(也称为depth-wise separable) convolution, use grouped convolution with number of groups equal to the number of channels.

Tip

The function, by default, convolves over up to three dimensions ofdlXlabeled'S'(spatial). To convolve over dimensions labeled'T'(time), specifyweightswith a'T'dimension using a formatteddlarrayobject or by using the'WeightsFormat'option.

Bias constant, specified as a formatteddlarray, an unformatteddlarray, a numeric vector, or a numeric scalar.

  • Ifbiasis a scalar, then the same bias is applied to each output.

  • Ifbiashas a nonsingleton dimension, then each element ofbiasis the bias applied to the corresponding convolutional filter specified byweights. The number of elements ofbiasmust match the number of filters specified byweights.

  • Ifbiasis0, then the bias term is disabled and no bias is added during the convolution operation.

Ifbiasis a formatteddlarray, then the nonsingleton dimension must be a channel dimension with label'C'(channel).

Name-Value Arguments

Specify optional comma-separated pairs ofName,Valuearguments.Nameis the argument name andValueis the corresponding value.Namemust appear inside quotes. You can specify several name and value pair arguments in any order asName1,Value1,...,NameN,ValueN.

Example:'DilationFactor',2sets the dilation factor for each convolutional filter to2.

Dimension order of unformatted input data, specified as a character vector or string scalarFMTthat provides a label for each dimension of the data.

When you specify the format of adlarrayobject, each character provides a label for each dimension of the data and must be one of the following:

  • "S"— Spatial

  • "C"— Channel

  • "B"— Batch (for example, samples and observations)

  • "T"— Time (for example, time steps of sequences)

  • “U"— Unspecified

You can specify multiple dimensions labeled"S"or“U". You can use the labels"C","B", and"T"at most once.

You must specifyDataFormat当输入哒ta is not a formatteddlarray.

Data Types:char|string

Dimension order of the weights, specified as the comma-separated pair consisting of'WeightsFormat'and a character vector or string scalar that provides a label for each dimension of the weights.

The default value of'WeightsFormat'depends on the task:

Task Default
1-D convolution 'SCU'(spatial, channel, unspecified)
1-D grouped convolution 'SCUU'(spatial, channel, unspecified, unspecified)
2-D convolution 'SSCU'(spatial, spatial, channel, unspecified)
2-D grouped convolution 'SSCUU'(spatial, spatial, channel, unspecified, unspecified)
3-D convolution 'SSSCU'(spatial, spatial, spatial, channel, unspecified)

The supported combinations of dimension labels depends on the type of convolution, for more information, see theweightsargument.

Tip

The function, by default, convolves over up to three dimensions ofdlXlabeled'S'(spatial). To convolve over dimensions labeled'T'(time), specifyweightswith a'T'dimension using a formatteddlarrayobject or by using the'WeightsFormat'option.

Example:'WeightsFormat','TCU'

Data Types:char|string

Step size for traversing the input data, specified as the comma-separated pair consisting of'Stride'and a numeric scalar or numeric vector. If you specify'Stride'作为一个标量,相同的值是用于所有spatial dimensions. If you specify'Stride'as a vector of the same size as the number of spatial dimensions of the input data, the vector values are used for the corresponding spatial dimensions.

The default value of'Stride'is1.

Example:'Stride',3

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64

Filter dilation factor, specified as the comma-separated pair consisting of'DilationFactor'and one of the following.

  • Numeric scalar — The same dilation factor value is applied for all spatial dimensions.

  • Numeric vector — A different dilation factor value is applied along each spatial dimension. Use a vector of sized, wheredis the number of spatial dimensions of the input data. Theith element of the vector specifies the dilation factor applied to theith spatial dimension.

Use the dilation factor to increase the receptive field of the filter (the area of the input that the filter can see) on the input data. Using a dilation factor corresponds to an effective filter size offilterSize + (filterSize-1)*(dilationFactor-1).

Example:'DilationFactor',2

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64

大小of padding applied to the'S'and'T'dimensions given by the format of the weights, specified as the comma-separated pair consisting of'Padding'and one of the following:

  • 'same'— Apply padding such that the output dimension sizes areceil(inputSize/stride), whereinputSizeis the size of the corresponding input dimension. WhenStrideis1, the output is the same size as the input.

  • 'causal'– Apply left padding with size(FilterSize - 1).*DilationFactor. This option supports convolving over a single time or spatial dimension only. WhenStrideis1, the output is the same size as the input.

  • Nonnegative integersz— Add padding of sizeszto both ends of the'S'or'T'dimensions given by the format of the weights.

  • Vector of integerssz— Add padding of sizesz(i)to both ends of theith'S'or'T'dimensions given by the format of the weights. The number of elements ofszmust match the number of'S'or'T'dimensions of the weights.

  • Matrix of integerssz— Add padding of sizesz(1,i)andsz(2,i)to the start and end of theith'S'or'T'dimensions given by the format of the weights. For example, for 2-D input,[t l; b r]applies padding of sizet,b,l, andrto the top, bottom, left, and right of the input, respectively.

Example:'Padding','same'

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64|char|string

Value to pad data, specified as one of the following:

PaddingValue Description Example
Scalar Pad with the specified scalar value.

[ 3 1 4 1 5 9 2 6 5 ] → [ 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3 1 4 0 0 0 0 1 5 9 0 0 0 0 2 6 5 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 ]

'symmetric-include-edge' Pad using mirrored values of the input, including the edge values.

[ 3 1 4 1 5 9 2 6 5 ] → [ 5 1 1 5 9 9 5 1 3 3 1 4 4 1 1 3 3 1 4 4 1 5 1 1 5 9 9 5 6 2 2 6 5 5 6 6 2 2 6 5 5 6 5 1 1 5 9 9 5 ]

'symmetric-exclude-edge' Pad using mirrored values of the input, excluding the edge values.

[ 3 1 4 1 5 9 2 6 5 ] → [ 5 6 2 6 5 6 2 9 5 1 5 9 5 1 4 1 3 1 4 1 3 9 5 1 5 9 5 1 5 6 2 6 5 6 2 9 5 1 5 9 5 1 4 1 3 1 4 1 3 ]

'replicate' Pad using repeated border elements of the input

[ 3 1 4 1 5 9 2 6 5 ] → [ 3 3 3 1 4 4 4 3 3 3 1 4 4 4 3 3 3 1 4 4 4 1 1 1 5 9 9 9 2 2 2 6 5 5 5 2 2 2 6 5 5 5 2 2 2 6 5 5 5 ]

Data Types:single|double|int8|int16|int32|int64|uint8|uint16|uint32|uint64|char|string

Output Arguments

collapse all

Convolved feature map, returned as adlarraywith the same underlying data type asdlX.

If the input datadlXis a formatteddlarray, thendlYhas the same format asdlX. If the input data is not a formatteddlarray, thendlYis an unformatteddlarraywith the same dimension order as the input data.

The size of the'C'(channel) dimension ofdlYdepends on the task.

Task 大小of'C'Dimension
Convolution Number of filters
Grouped convolution Number of filters per group multiplied by the number of groups

More About

collapse all

Deep Learning Convolution

Thedlconvfunction applies sliding convolution filters to the input data. Thedlconvfunction supports convolution in one, two, or three spatial dimensions or one time dimension. To learn more about deep learning convolution, see the definition ofconvolutional layeron theconvolution2dLayerreference page.

Extended Capabilities

See Also

||||||

Topics

Introduced in R2019b

Deep Learning Toolbox Documentation

金宝app

Introducing Deep Learning with MATLAB

Introducing Deep Learning with MATLAB

Download ebook