Main Content

image3dInputLayer

3-D image input layer

expand all in page

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 optional properties using one or more name-value arguments.

example

Input Arguments

expand all

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

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.

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

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

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

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

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

The Image3DInputLayer object stores the Name property as a character vector.

Data Types: char | string

Properties

expand all

3-D Image Input

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]

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.

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

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

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

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

Layer

Layer name, specified as a character vector or string scalar. For Layer array input, the trainnet 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

This property is read-only.

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

Data Types: double

This property is read-only.

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

Data Types: cell

This property is read-only.

Number of outputs from the layer, returned as 1. This layer has a single output only.

Data Types: double

This property is read-only.

Output names, returned as {'out'}. This layer has a single output only.

Data Types: cell

Examples

collapse all

Open Live Script

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

expand all

Version History

Introduced in R2019a

expand all

See Also

| | | | | | | | | | | | |

Topics