spaceToDepth

Rearrange spatial blocks of dlarray data along depth dimension

Since R2021a

Syntax

Y = spaceToDepth(X,blockSize)

Y = spaceToDepth(X,blockSize,'DataFormat',dataFormat)

Description

Y = spaceToDepth(X,blockSize) rearranges spatial blocks of the formatted dlarray object, X, along the depth dimension. The blocks of data have size blockSize.

Given an input feature map of size [H W C] and blocks of size [height width], the output feature map size is [floor(H/height) floor(W/width) C*height*width].

This function requires Deep Learning Toolbox™.

Y = spaceToDepth(X,blockSize,'DataFormat',dataFormat) rearranges spatial blocks of the unformatted dlarray object, X, along the depth dimension. dataFormat specifies the dimension labels.

Examples

Rearrange Formatted dlarray Data from Spatial to Depth Dimension

Create a numeric array with three channels that simulates a 4-by-4 RGB image.

X = reshape(1:48,4,4,3);

Create a dlarray object that contains the numeric data, specifying the format of the data as 'SSC' (spatial, spatial, channel).

X = dlarray(X,'SSC')

X = 
  4(S) x 4(S) x 3(C) dlarray


(:,:,1) =

     1     5     9    13
     2     6    10    14
     3     7    11    15
     4     8    12    16


(:,:,2) =

    17    21    25    29
    18    22    26    30
    19    23    27    31
    20    24    28    32


(:,:,3) =

    33    37    41    45
    34    38    42    46
    35    39    43    47
    36    40    44    48

Specify a 2-by-2 block size for reordering input activations.

blockSize = 2;

Rearrange blocks of data from the spatial dimension to the depth dimension.

Z = spaceToDepth(X,blockSize)

Z = 
  2(S) x 2(S) x 12(C) dlarray


(:,:,1) =

     1     9
     3    11


(:,:,2) =

    17    25
    19    27


(:,:,3) =

    33    41
    35    43


(:,:,4) =

     5    13
     7    15


(:,:,5) =

    21    29
    23    31


(:,:,6) =

    37    45
    39    47


(:,:,7) =

     2    10
     4    12


(:,:,8) =

    18    26
    20    28


(:,:,9) =

    34    42
    36    44


(:,:,10) =

     6    14
     8    16


(:,:,11) =

    22    30
    24    32


(:,:,12) =

    38    46
    40    48

  2(S) x 2(S) x 12(C) dlarray

Rearrange Unformatted Data from Spatial to Depth Dimension

Create a numeric array with three channels that simulates a 4-by-4 RGB image.

X = reshape(1:48,4,4,3);

Create an unformatted dlarray object that contains the numeric data.

dlX = dlarray(X);

Specify a 2-by-2 block size for reordering input activations.

blockSize = 2;

Rearrange blocks of data from the spatial dimension to the depth dimension. Specify the format of the input data as "SSC".

dlZ = spaceToDepth(dlX,blockSize,"DataFormat","SSC");

Compare the dimensions of the original and rearranged data.

whos dlX dlZ

  Name      Size              Bytes  Class      Attributes

  dlX       4x4x3               384  dlarray              
  dlZ       2x2x12              384  dlarray              

Input Arguments

X — Deep learning data to rearrange

dlarray object

Deep learning data to rearrange, specified as a dlarray (Deep Learning Toolbox) object.

blockSize — Block size to reorder input activation

positive integer | vector of two positive integers

Block size to reorder the input activation, specified as a positive integer or vector of two positive integers of the form [h w], where h is the height and w is the width. When you specify blockSize as a scalar, the function uses the same value for both dimensions.

Example: [2 4] specifies blocks of height 2 and width 4.

Example: 32 specifies blocks of height and width 32.

dataFormat — Dimension labels

string scalar | character vector

Dimension labels when the input deep learning data X is unlabeled, specified as a string scalar or character vector. The number of labels must match the number of dimensions of the input data, X. Each character in dataFormat must be one of these labels:

• S — Spatial

• C — Channel

• B — Batch observations

The "T" (time or sequence) and "U" (unspecified) labels are not supported. Do not specify the dataFormat argument when the input deep learning data is a formatted dlarray object.

Example: 'SSC' indicates the array has two spatial dimensions and one channel dimension, appropriate for 2-D RGB image data.

Data Types: char | string

Output Arguments

Y — Rearranged deep learning data

dlarray object

Rearranged deep learning data, returned as a dlarray (Deep Learning Toolbox) object.

Extended Capabilities

GPU Arrays

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

This function fully supports GPU arrays. For more information, see Image Processing on a GPU.

Version History

Introduced in R2021a