depthToSpace

Rearrange dlarray data from depth dimension into spatial blocks

Syntax

Y = depthToSpace(X,blockSize)

Y = depthToSpace(X,blockSize,Name,Value)

Description

Y = depthToSpace(X,blockSize) rearranges data of the formatted dlarray object, X, from the depth dimension into spatial blocks of size blockSize.

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

This function requires Deep Learning Toolbox™.

Y = depthToSpace(X,blockSize,Name,Value) modifies aspects of the depth-to-space rearranging operation using name-value arguments. If X is an unformatted dlarray, then you must specify the DataFormat name-value pair argument.

Examples

Rearrange Formatted dlarray Data from Depth to Spatial Dimension

Create a numeric array of height 2 and width 2 that simulates the depthwise concatenation of blocks of size 2-by-2.

X = reshape(1:48,2,2,12);

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 = 
  2(S) x 2(S) x 12(C) dlarray


(:,:,1) =

     1     3
     2     4


(:,:,2) =

     5     7
     6     8


(:,:,3) =

     9    11
    10    12


(:,:,4) =

    13    15
    14    16


(:,:,5) =

    17    19
    18    20


(:,:,6) =

    21    23
    22    24


(:,:,7) =

    25    27
    26    28


(:,:,8) =

    29    31
    30    32


(:,:,9) =

    33    35
    34    36


(:,:,10) =

    37    39
    38    40


(:,:,11) =

    41    43
    42    44


(:,:,12) =

    45    47
    46    48

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

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

blockSize = 2;

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

Z = depthToSpace(X,blockSize)

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


(:,:,1) =

     1    13     3    15
    25    37    27    39
     2    14     4    16
    26    38    28    40


(:,:,2) =

     5    17     7    19
    29    41    31    43
     6    18     8    20
    30    42    32    44


(:,:,3) =

     9    21    11    23
    33    45    35    47
    10    22    12    24
    34    46    36    48

Rearrange Unformatted Data from Depth to Spatial Dimensions

Create a numeric array of height 2 and width 2 that simulates the depthwise concatenation of blocks of size 2-by-2.

X = reshape(1:48,2,2,12);

Create an unfomratted 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 depth dimension to the spatial dimensions, specifying the data format. Order the data by column, row, and then depth.

dlZ = depthToSpace(dlX,blockSize,"DataFormat","SSC","Mode","CRD")

dlZ = 
  4x4x3 dlarray


(:,:,1) =

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


(:,:,2) =

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


(:,:,3) =

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

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.

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: 'DataFormat',"SSC" specifies an array with two spatial dimensions and one channel dimension, appropriate for 2-D RGB image data.

'DataFormat' — Dimension labels

"SSCB" (default) | 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: "SSCB" indicates the array has two spatial dimensions, one channel dimension, and one batch dimension.

Data Types: char | string

'Mode' — Order of rearranged dimensions

"DCR" (default) | "CRD"

Order of rearranged dimensions from the input deep learning data X, specified as "DCR" or "CRD". When you specify "DCR", the function orders data by depth, column, and then row. When you specify "CRD", the function orders data by column, row, and then depth.

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.