# depthToSpace

Rearrange `dlarray` data from depth dimension into spatial blocks

## Syntax

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

## Description

example

````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™.```

example

````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

collapse all

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 ```

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 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 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

collapse all

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

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 Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Example: `'DataFormat',"SSC"` specifies an array with two spatial dimensions and one channel dimension, appropriate for 2-D RGB image data.

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`

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

collapse all

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

## Version History

Introduced in R2021a