Main Content

maxpool

Pool data to maximum value

Description

The maximum pooling operation performs downsampling by dividing the input into pooling regions and computing the maximum value of each region.

Note

This function applies the maximum pooling operation to dlarray data. If you want to apply maximum pooling within a layerGraph object or Layer array, use one of the following layers:

example

dlY = maxpool(dlX,poolsize) performs downsampling by dividing the input dlX into rectangular or cuboidal regions defined by poolsize and computing the maximum value of the data in each region. The input dlX is a formatted dlarray with dimension labels. Pooling acts on spatial dimensions labeled 'S'. The output dlY is a formatted dlarray with the same dimension labels as dlX.

[dlY,indx,inputSize] = maxpool(dlX,poolsize) also returns the linear indices of the maximum value within each pooled region and the size of the input feature map dlX for use with the maxunpool operation.

example

___ = maxpool(___,Name,Value) specifies options using one or more name-value pair arguments. For example, 'Stride',3 sets the stride of the pooling operation.

example

dlY = maxpool(dlX,'global') computes the global maximum over the spatial dimensions of the input dlX. This syntax is equivalent to setting poolsize in the previous syntaxes to the size of the 'S' dimensions of dlX.

example

___ = maxpool(___,'DataFormat',FMT) also specifies the dimension format FMT when dlX is not a formatted dlarray, in addition to the input arguments in previous syntaxes. The output dlY is an unformatted dlarray with the same dimension order as dlX.

Examples

collapse all

Pool data to maximum values over two spatial dimensions.

Create the input data as a single observation of random values with a height and width of six and a single channel.

height = 6;
width = 6;
channels = 1;
observations = 1;

X = rand(height,width,channels,observations);
dlX = dlarray(X,'SSCB')
dlX = 
  6(S) × 6(S) × 1(C) × 1(B) dlarray

    0.1781    0.8819    0.1564    0.4820    0.2518    0.7302
    0.1280    0.6692    0.8555    0.1206    0.2904    0.3439
    0.9991    0.1904    0.6448    0.5895    0.6171    0.5841
    0.1711    0.3689    0.3763    0.2262    0.2653    0.1078
    0.0326    0.4607    0.1909    0.3846    0.8244    0.9063
    0.5612    0.9816    0.4283    0.5830    0.9827    0.8797

Pool the data to maximum values over pooling regions of size 2 using a stride of 2.

dlY = maxpool(dlX,2,'Stride',2)
dlY = 
  3(S) × 3(S) × 1(C) × 1(B) dlarray

    0.8819    0.8555    0.7302
    0.9991    0.6448    0.6171
    0.9816    0.5830    0.9827

Pool data to its global maximum value.

Create the input data as an unformatted dlarray. The data contains a single observation of random values with a height of four, a width of six, and a single channel.

height = 4;
width = 6;
channels = 1;
observations = 1;

X = rand(height,width,channels,observations);
dlX = dlarray(X)
dlX = 
  4×6 dlarray

    0.8147    0.6324    0.9575    0.9572    0.4218    0.6557
    0.9058    0.0975    0.9649    0.4854    0.9157    0.0357
    0.1270    0.2785    0.1576    0.8003    0.7922    0.8491
    0.9134    0.5469    0.9706    0.1419    0.9595    0.9340

Pool the data to the global maximum value. Specify the dimension format of the input data.

dlY = maxpool(dlX,'global','DataFormat','SSCB')
dlY = 
  1×1 dlarray

    0.9706

Input Arguments

collapse all

Input data, specified as a dlarray with or without dimension labels. When dlX is not a formatted dlarray, you must specify the dimension label format using 'DataFormat',FMT.

Pooling acts on dimensions that you specify as spatial dimensions using the 'S' dimension label. dlX must have at least one 'S' dimension. You can specify up to three dimensions in dlX as 'S' dimensions. The maxpool operation divides the data along each 'S' dimension into regions defined by poolsize. The function computes the maximum of all values within each pooling region.

Data Types: single | double

Size of the pooling regions, specified as a numeric scalar or numeric vector. If you specify poolsize as a scalar, the pooling regions have the same size along all spatial dimensions. To use rectangular or cuboidal pooling regions that have different sizes along each spatial dimension, specify poolsize as a vector with the same length as the number of spatial dimensions.

Example: 3

Data Types: single | double

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'Stride',2 specifies the stride of the pooling regions as 2.

Dimension order of unformatted input data, specified as the comma-separated pair consisting of 'DataFormat' and a character array or string FMT that provides a label for each dimension of the data. Each character in FMT must be one of the following:

  • 'S' — Spatial

  • 'C' — Channel

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

  • 'T' — Time (for example, 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 specify 'DataFormat' when the input data dlX is not a formatted dlarray.

Example: 'DataFormat','SSCB'

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' as a scalar, the same value is used for all 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' is 1. If 'Stride' is less than poolsize in any dimension, then the pooling regions overlap.

The Stride parameter is not supported for global pooling using the 'global' option.

Example: 'Stride',3

Data Types: single | double

Size of padding applied to edges of data, specified as the comma-separated pair consisting of 'Padding' and one of the following:

  • 'same' — Padding size is set so that the output size is the same as the input size when the stride is 1. More generally, the output size of each spatial dimension is ceil(inputSize/stride), where inputSize is the size of the input along a spatial dimension.

  • Numeric scalar — The same amount of padding is applied to both ends of all spatial dimensions.

  • Numeric vector — A different amount of padding is applied along each spatial dimension. Use a vector of size d, where d is the number of spatial dimensions of the input data. The ith element of the vector specifies the size of padding applied to the start and the end along the ith spatial dimension.

  • Numeric matrix — A different amount of padding is applied to the start and end of each spatial dimension. Use a matrix of size 2-by-d, where d is the number of spatial dimensions of the input data. The element (1,d) specifies the size of padding applied to the start of spatial dimension d. The element (2,d) specifies the size of padding applied to the end of spatial dimension d. For example, in 2-D, the format is [top, left; bottom, right].

The 'Padding' parameter is not supported for global pooling using the 'global' option.

Example: 'Padding','same'

Data Types: single | double

Output Arguments

collapse all

Pooled data, returned as a dlarray. The output dlY has the same underlying data type as the input dlX.

If the input data dlX is a formatted dlarray, dlY has the same dimension labels as dlX. If the input data is not a formatted dlarray, dlY is an unformatted dlarray with the same dimension order as the input data.

Indices of maximum values in each pooled region, returned as a dlarray. Each value in indx represents the location of the corresponding maximum value in dlY, given as a linear index of the values in dlX.

If dlX is a formatted dlarray, indx has the same size and format as the output dlY.

If dlX is not a formatted dlarray, indx is an unformatted dlarray. In that case, indx is returned with the following dimension order: all 'S' dimensions, followed by 'C', 'B', and 'T' dimensions, then all 'U' dimensions. The size of indx matches the size of dlY when dlY is permuted to match the previously stated dimension order.

Use the indx output with the maxunpool function to unpool the output of maxpool.

indx output is not supported when using the 'global' option.

Size of the input feature map, returned as a numeric vector.

Use the inputSize output with the maxunpool function to unpool the output of maxpool.

inputSize output is not supported when using the 'global' option.

More About

collapse all

Maximum Pooling

The maxpool function pools the input data to maximum values over the spatial dimensions. For more information, see the definition of Max Pooling Layer on the maxPooling2dLayer reference page.

Compatibility Considerations

expand all

Behavior changed in R2020a

Extended Capabilities

Introduced in R2019b