# image3dInputLayer

3-D image input layer

## Description

A 3-D image input layer inputs 3-D images or volumes to a neural network and applies data normalization.

For 2-D image input, use `imageInputLayer`

.

## Creation

### Description

sets optional properties using one or more name-value arguments.`layer`

= image3dInputLayer(`inputSize`

,`Name=Value`

)

### Input Arguments

`inputSize`

— Size of the input

row vector of integers

Size of the input data, specified as a row vector of integers ```
[h w d
c]
```

, where `h`

, `w`

,
`d`

, and `c`

correspond to the height, width, depth,
and number of channels respectively.

For grayscale input, specify a vector with

`c`

equal to`1`

.For RGB input, specify a vector with

`c`

equal to`3`

.For multispectral or hyperspectral input, specify a vector with

`c`

equal to the number of channels.

For 2-D image input, use `imageInputLayer`

.

**Example: **
`[132 132 116 3]`

**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: **`image3dInputLayer([132 132 116 3],Name="input")`

creates a
3-D image input layer for 132-by-132-by-116 color 3-D images with name
`'input'`

.

`Normalization`

— Data normalization

`"zerocenter"`

(default) | `"zscore"`

| `"rescale-symmetric"`

| `"rescale-zero-one"`

| `"none"`

| function handle

Data normalization to apply every time data is forward propagated through the input layer, specified as one of the following:

`"zerocenter"`

— Subtract the mean specified by`Mean`

.`"zscore"`

— Subtract the mean specified by`Mean`

and divide by`StandardDeviation`

.`"rescale-symmetric"`

— Rescale the input to be in the range [-1, 1] using the minimum and maximum values specified by`Min`

and`Max`

, respectively.`"rescale-zero-one"`

— Rescale the input to be in the range [0, 1] using the minimum and maximum values specified by`Min`

and`Max`

, respectively.`"none"`

— Do not normalize the input data.function handle — Normalize the data using the specified function. The function must be of the form

`Y = f(X)`

, where`X`

is the input data and the output`Y`

is the normalized data.

This layer supports complex-valued data.* (since R2024a)*
To input complex-valued data into the network, the
`Normalization`

option must be `"zerocenter"`

,
`"zscore"`

, `"none"`

, or a function
handle.

**Tip**

The software, by default, automatically calculates the normalization
statistics when you use the `trainnet`

function. To save time when training, specify the required
statistics for normalization and set the `ResetInputNormalization`

option in `trainingOptions`

to `0`

(`false`

).

The `Image3DInputLayer`

object stores the
`Normalization`

property as a character vector or a function
handle.

`NormalizationDimension`

— Normalization dimension

`"auto"`

(default) | `"channel"`

| `"element"`

| `"all"`

Normalization dimension, specified as one of the following:

`"auto"`

– If the`ResetInputNormalization`

training option is`0`

(`false`

) and you specify any of the normalization statistics (`Mean`

,`StandardDeviation`

,`Min`

, or`Max`

), then normalize over the dimensions matching the statistics. Otherwise, recalculate the statistics at training time and apply channel-wise normalization.`"channel"`

– Channel-wise normalization.`"element"`

– Element-wise normalization.`"all"`

– Normalize all values using scalar statistics.

The `Image3DInputLayer`

object stores the
`NormalizationDimension`

property as a character
vector.

`Mean`

— Mean for zero-center and z-score normalization

`[]`

(default) | 4-D array | numeric scalar

Mean for zero-center and z-score normalization, specified as a
*h*-by-*w*-by-*d*-by-*c*
array, a 1-by-1-by-1-by-*c* array of means per channel, a numeric
scalar, or `[]`

, where *h*, *w*,
*d*, and *c* correspond to the height, width,
depth, and the number of channels of the mean, respectively.

To specify the `Mean`

property, the `Normalization`

property must be
`"zerocenter"`

or `"zscore"`

. If `Mean`

is `[]`

, then the software
automatically sets the property at training or initialization time:

The

`trainnet`

function calculates the mean using the training data and uses the resulting value.The

`initialize`

function and the`dlnetwork`

function when the`Initialize`

option is`1`

(`true`

) sets the property to`0`

.

*Before R2024a: This option does not support
complex-valued data.*

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

**Complex Number Support: **Yes

`StandardDeviation`

— Standard deviation for z-score normalization

`[]`

(default) | 4-D array | numeric scalar

Standard deviation for z-score normalization, specified as a
*h*-by-*w*-by-*d*-by-*c*
array, a 1-by-1-by-1-by-*c* array of means per channel, a numeric
scalar, or `[]`

, where *h*, *w*,
*d*, and *c* correspond to the height, width,
depth, and the number of channels of the standard deviation, respectively.

To specify the `StandardDeviation`

property,
the `Normalization`

property must be
`"zscore"`

. If `StandardDeviation`

is `[]`

, then the software
automatically sets the property at training or initialization time:

The

`trainnet`

function calculates the standard deviation using the training data and uses the resulting value.The

`initialize`

function and the`dlnetwork`

function when the`Initialize`

option is`1`

(`true`

) sets the property to`1`

.

*Before R2024a: This option does not support
complex-valued data.*

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

**Complex Number Support: **Yes

`Min`

— Minimum value for rescaling

`[]`

(default) | 4-D array | numeric scalar

Minimum value for rescaling, specified as a
*h*-by-*w*-by-*d*-by-*c*
array, a 1-by-1-by-1-by-*c* array of minima per channel, a numeric
scalar, or `[]`

, where *h*, *w*,
*d*, and *c* correspond to the height, width,
depth, and the number of channels of the minima, respectively.

To specify the `Min`

property, the `Normalization`

must be
`"rescale-symmetric"`

or `"rescale-zero-one"`

.
If `Min`

is `[]`

, then the
software automatically sets the property at training or initialization time:

The

`trainnet`

function calculates the minimum value using the training data and uses the resulting value.The

`initialize`

function and the`dlnetwork`

function when the`Initialize`

option is`1`

(`true`

) sets the property to`-1`

and`0`

when`Normalization`

is`"rescale-symmetric"`

and`"rescale-zero-one"`

, respectively.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

`Max`

— Maximum value for rescaling

`[]`

(default) | 4-D array | numeric scalar

Maximum value for rescaling, specified as a
*h*-by-*w*-by-*d*-by-*c*
array, a 1-by-1-by-1-by-*c* array of maxima per channel, a numeric
scalar, or `[]`

, where *h*, *w*,
*d*, and *c* correspond to the height, width,
depth, and the number of channels of the maxima, respectively.

To specify the `Max`

property, the `Normalization`

must be
`"rescale-symmetric"`

or `"rescale-zero-one"`

.
If `Max`

is `[]`

, then the
software automatically sets the property at training or initialization time:

The

`trainnet`

function calculates the maximum value using the training data and uses the resulting value.The

`initialize`

function and the`dlnetwork`

function when the`Initialize`

option is`1`

(`true`

) sets the property to`1`

.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

`Name`

— Layer name

`""`

(default) | character vector | string scalar

## Properties

### 3-D Image Input

`InputSize`

— Size of the input

row vector of integers

Size of the input data, specified as a row vector of integers ```
[h w d
c]
```

, where `h`

, `w`

,
`d`

, and `c`

correspond to the height, width, depth,
and number of channels respectively.

For grayscale input, specify a vector with

`c`

equal to`1`

.For RGB input, specify a vector with

`c`

equal to`3`

.For multispectral or hyperspectral input, specify a vector with

`c`

equal to the number of channels.

For 2-D image input, use `imageInputLayer`

.

**Example: **
`[132 132 116 3]`

`Normalization`

— Data normalization

`"zerocenter"`

(default) | `"zscore"`

| `"rescale-symmetric"`

| `"rescale-zero-one"`

| `"none"`

| function handle

Data normalization to apply every time data is forward propagated through the input layer, specified as one of the following:

`"zerocenter"`

— Subtract the mean specified by`Mean`

.`"zscore"`

— Subtract the mean specified by`Mean`

and divide by`StandardDeviation`

.`"rescale-symmetric"`

— Rescale the input to be in the range [-1, 1] using the minimum and maximum values specified by`Min`

and`Max`

, respectively.`"rescale-zero-one"`

— Rescale the input to be in the range [0, 1] using the minimum and maximum values specified by`Min`

and`Max`

, respectively.`"none"`

— Do not normalize the input data.function handle — Normalize the data using the specified function. The function must be of the form

`Y = f(X)`

, where`X`

is the input data and the output`Y`

is the normalized data.

This layer supports complex-valued data.* (since R2024a)* To
input complex-valued data into the network, the `Normalization`

option must be `"zerocenter"`

, `"zscore"`

,
`"none"`

, or a function handle.

**Tip**

The software, by default, automatically calculates the normalization statistics
when you use the `trainnet`

function. To save time when training, specify the required statistics for
normalization and set the `ResetInputNormalization`

option in `trainingOptions`

to `0`

(`false`

).

The `Image3DInputLayer`

object stores this property as a character vector or a
function handle.

`NormalizationDimension`

— Normalization dimension

`"auto"`

(default) | `"channel"`

| `"element"`

| `"all"`

Normalization dimension, specified as one of the following:

`"auto"`

– If the`ResetInputNormalization`

training option is`0`

(`false`

) and you specify any of the normalization statistics (`Mean`

,`StandardDeviation`

,`Min`

, or`Max`

), then normalize over the dimensions matching the statistics. Otherwise, recalculate the statistics at training time and apply channel-wise normalization.`"channel"`

– Channel-wise normalization.`"element"`

– Element-wise normalization.`"all"`

– Normalize all values using scalar statistics.

The `Image3DInputLayer`

object stores this property as a character vector.

`Mean`

— Mean for zero-center and z-score normalization

`[]`

(default) | 4-D array | numeric scalar

Mean for zero-center and z-score normalization, specified as a
*h*-by-*w*-by-*d*-by-*c*
array, a 1-by-1-by-1-by-*c* array of means per channel, a numeric
scalar, or `[]`

, where *h*, *w*,
*d*, and *c* correspond to the height, width,
depth, and the number of channels of the mean, respectively.

To specify the `Mean`

property, the `Normalization`

property must be `"zerocenter"`

or `"zscore"`

. If `Mean`

is
`[]`

, then the software automatically sets the property at training or
initialization time:

The

`trainnet`

function calculates the mean using the training data and uses the resulting value.The

`initialize`

function and the`dlnetwork`

function when the`Initialize`

option is`1`

(`true`

) sets the property to`0`

.

*Before R2024a: This option does not support complex-valued
data.*

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

**Complex Number Support: **Yes

`StandardDeviation`

— Standard deviation for z-score normalization

`[]`

(default) | 4-D array | numeric scalar

Standard deviation for z-score normalization, specified as a
*h*-by-*w*-by-*d*-by-*c*
array, a 1-by-1-by-1-by-*c* array of means per channel, a numeric
scalar, or `[]`

, where *h*, *w*,
*d*, and *c* correspond to the height, width,
depth, and the number of channels of the standard deviation, respectively.

To specify the `StandardDeviation`

property, the
`Normalization`

property must be
`"zscore"`

. If `StandardDeviation`

is
`[]`

, then the software automatically sets the property at training or
initialization time:

The

`trainnet`

function calculates the standard deviation using the training data and uses the resulting value.The

`initialize`

function and the`dlnetwork`

function when the`Initialize`

option is`1`

(`true`

) sets the property to`1`

.

*Before R2024a: This option does not support complex-valued
data.*

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

**Complex Number Support: **Yes

`Min`

— Minimum value for rescaling

`[]`

(default) | 4-D array | numeric scalar

Minimum value for rescaling, specified as a
*h*-by-*w*-by-*d*-by-*c*
array, a 1-by-1-by-1-by-*c* array of minima per channel, a numeric
scalar, or `[]`

, where *h*, *w*,
*d*, and *c* correspond to the height, width,
depth, and the number of channels of the minima, respectively.

To specify the `Min`

property, the `Normalization`

must be `"rescale-symmetric"`

or
`"rescale-zero-one"`

. If `Min`

is
`[]`

, then the software automatically sets the property at training or
initialization time:

The

`trainnet`

function calculates the minimum value using the training data and uses the resulting value.The

`initialize`

function and the`dlnetwork`

function when the`Initialize`

option is`1`

(`true`

) sets the property to`-1`

and`0`

when`Normalization`

is`"rescale-symmetric"`

and`"rescale-zero-one"`

, respectively.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

`Max`

— Maximum value for rescaling

`[]`

(default) | 4-D array | numeric scalar

Maximum value for rescaling, specified as a
*h*-by-*w*-by-*d*-by-*c*
array, a 1-by-1-by-1-by-*c* array of maxima per channel, a numeric
scalar, or `[]`

, where *h*, *w*,
*d*, and *c* correspond to the height, width,
depth, and the number of channels of the maxima, respectively.

To specify the `Max`

property, the `Normalization`

must be `"rescale-symmetric"`

or
`"rescale-zero-one"`

. If `Max`

is
`[]`

, then the software automatically sets the property at training or
initialization time:

The

`trainnet`

function calculates the maximum value using the training data and uses the resulting value.`initialize`

function and the`dlnetwork`

function when the`Initialize`

option is`1`

(`true`

) sets the property to`1`

.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

### Layer

`Name`

— Layer name

`""`

(default) | character vector | string scalar

`NumInputs`

— Number of inputs

0 (default)

This property is read-only.

Number of inputs of the layer. The layer has no inputs.

**Data Types: **`double`

`InputNames`

— Input names

`{}`

(default)

This property is read-only.

Input names of the layer. The layer has no inputs.

**Data Types: **`cell`

`NumOutputs`

— Number of outputs

`1`

(default)

This property is read-only.

Number of outputs from the layer, returned as `1`

. This layer has a
single output only.

**Data Types: **`double`

`OutputNames`

— Output names

`{'out'}`

(default)

This property is read-only.

Output names, returned as `{'out'}`

. This layer has a single output
only.

**Data Types: **`cell`

## Examples

### Create 3-D Image Input Layer

Create a 3-D image input layer for 132-by-132-by-116 color 3-D images

layer = image3dInputLayer([132 132 116])

layer = Image3DInputLayer with properties: Name: '' InputSize: [132 132 116 1] Hyperparameters Normalization: 'zerocenter' NormalizationDimension: 'auto' Mean: []

Include a 3-D image input layer in a `Layer`

array.

layers = [ image3dInputLayer([28 28 28 3]) convolution3dLayer(5,16,Stride=4) reluLayer maxPooling3dLayer(2,Stride=4) fullyConnectedLayer(10) softmaxLayer]

layers = 6x1 Layer array with layers: 1 '' 3-D Image Input 28x28x28x3 images with 'zerocenter' normalization 2 '' 3-D Convolution 16 5x5x5 convolutions with stride [4 4 4] and padding [0 0 0; 0 0 0] 3 '' ReLU ReLU 4 '' 3-D Max Pooling 2x2x2 max pooling with stride [4 4 4] and padding [0 0 0; 0 0 0] 5 '' Fully Connected 10 fully connected layer 6 '' Softmax softmax

## Algorithms

### Layer Output Formats

Layers in a layer array or layer graph pass data to subsequent layers as formatted `dlarray`

objects.
The format of a `dlarray`

object is a string of characters in which each
character describes the corresponding dimension of the data. The formats consist of one or
more of these characters:

`"S"`

— Spatial`"C"`

— Channel`"B"`

— Batch`"T"`

— Time`"U"`

— Unspecified

For example, you can describe 2-D image data that is represented as a 4-D array, where the
first two dimensions correspond to the spatial dimensions of the images, the third
dimension corresponds to the channels of the images, and the fourth dimension
corresponds to the batch dimension, as having the format `"SSCB"`

(spatial, spatial, channel, batch).

The input layer of a network specifies the layout of the data that the network expects. If you have data in a different layout, then specify the layout using the `InputDataFormats`

training option.

The layer inputs
*h*-by-*w*-by-*d*-by-*c*-by-*N*
arrays to the network, where *h*, *w*,
*d*, and *c* are the height, width, depth, and number of
channels of the images, respectively, and *N* is the number of images. Data
in this layout has the data format `"SSSCB"`

(spatial, spatial, spatial,
channel, batch).

### Complex Numbers

`Image3DInputLayer`

objects support passing
complex-valued data to subsequent layers.* (since R2024a)*

If the input data is complex-valued, then the `Normalization`

option
must be `"zerocenter"`

, `"zscore"`

,
`"none"`

, or a function handle. The `Mean`

and
`StandardDeviation`

properties of the layer also support complex-valued
data for `"zerocenter"`

and `"zscore"`

normalization
options.

For an example showing how to train a network with complex-valued data, see Train Network with Complex-Valued Data.

## Version History

**Introduced in R2019a**

### R2024a: Complex-valued outputs

For complex-valued input to the neural network, the layer passes complex-valued data to subsequent layers.

If the input data is complex-valued, then the `Normalization`

option
must be `"zerocenter"`

, `"zscore"`

,
`"none"`

, or a function handle. The `Mean`

and
`StandardDeviation`

properties of the layer also support complex-valued
data for `"zerocenter"`

and `"zscore"`

normalization
options.

### R2019b: `AverageImage`

property will be removed

`AverageImage`

will be removed. Use `Mean`

instead. To update your code, replace all instances of `AverageImage`

with `Mean`

.
There are no differences between the properties that require additional updates to your
code.

### R2019b: `imageInputLayer`

and `image3dInputLayer`

, by default, use channel-wise normalization

Starting in R2019b, `imageInputLayer`

and `image3dInputLayer`

,
by default, use channel-wise normalization. In previous versions, these layers use
element-wise normalization. To reproduce this behavior, set the `NormalizationDimension`

option of these layers to
`'element'`

.

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)