image3dInputLayer

3-D image input layer

Since R2019a

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

Syntax

layer = image3dInputLayer(inputSize)

layer = image3dInputLayer(inputSize,Name,Value)

Description

layer = image3dInputLayer(inputSize) returns a 3-D image input layer and specifies the InputSize property.

layer = image3dInputLayer(inputSize,Name,Value) sets the optional properties using name-value pairs. You can specify multiple name-value pairs. Enclose each property name in single quotes.

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

This property is read-only.

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 = func(X), where X is the input data and the output Y is the normalized data.

Tip

The software, by default, automatically calculates the normalization statistics when using the trainnet and trainNetwork functions. To save time when training, specify the required statistics for normalization and set the ResetInputNormalization option in trainingOptions to 0 (false).

NormalizationDimension — Normalization dimension

'auto' (default) | 'channel' | 'element' | 'all'

Normalization dimension, specified as one of the following:

• 'auto' – If the training option is 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.

Data Types: char | string

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.

If you specify the Mean property, then Normalization must be 'zerocenter' or 'zscore'. If Mean is [], then the trainnet and trainNetwork functions calculate the mean. To train a dlnetwork object using a custom training loop or assemble a network without training it using the assembleNetwork function, you must set the Mean property to a numeric scalar or a numeric array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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.

If you specify the StandardDeviation property, then Normalization must be 'zscore'. If StandardDeviation is [], then the trainnet and trainNetwork functions calculate the standard deviation. To train a dlnetwork object using a custom training loop or assemble a network without training it using the assembleNetwork function, you must set the StandardDeviation property to a numeric scalar or a numeric array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

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.

If you specify the Min property, then Normalization must be 'rescale-symmetric' or 'rescale-zero-one'. If Min is [], then the trainnet and trainNetwork functions calculate the minima. To train a dlnetwork object using a custom training loop or assemble a network without training it using the assembleNetwork function, you must set the Min property to a numeric scalar or a numeric array.

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.

If you specify the Max property, then Normalization must be 'rescale-symmetric' or 'rescale-zero-one'. If Max is [], then the trainnet and trainNetwork functions calculate the maxima. To train a dlnetwork object using a custom training loop or assemble a network without training it using the assembleNetwork function, you must set the Max property to a numeric scalar or a numeric array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Layer

Name — Layer name

"" (default) | character vector | string scalar

Layer name, specified as a character vector or a string scalar. For Layer array input, the trainnet, trainNetwork, assembleNetwork, layerGraph, and dlnetwork functions automatically assign names to layers with the name "".

The Image3DInputLayer object stores this property as a character vector.

Data Types: char | string

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 with name 'input'. By default, the layer performs data normalization by subtracting the mean image of the training set from every input image.

layer = image3dInputLayer([132 132 116],'Name','input')

layer = 
  Image3DInputLayer with properties:

                      Name: 'input'
                 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
    classificationLayer]

layers = 
  7x1 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
     7   ''   Classification Output   crossentropyex

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 consists of one or more of these characters:

• "S" — Spatial

• "C" — Channel

• "B" — Batch

• "T" — Time

• "U" — Unspecified

For example, 2-D image data 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, can be described 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).

Version History

Introduced in R2019a

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