pixelClassificationLayer - (To be removed) Create pixel classification layer for semantic

        segmentation - MATLAB ([original](https://in.mathworks.com/help/vision/ref/nnet.cnn.layer.pixelclassificationlayer.html)) ([raw](?raw))

(To be removed) Create pixel classification layer for semantic segmentation

The pixelClassificationLayer object will be removed in a future release. Use the trainnet (Deep Learning Toolbox) function and specify the loss using the crossentropy (Deep Learning Toolbox) function. For more information, see Version History.

Description

A pixel classification layer provides a categorical label for each image pixel or voxel.

Creation

Syntax

Description

`layer` = pixelClassificationLayer creates a pixel classification output layer for semantic image segmentation networks. The layer outputs the categorical label for each image pixel or voxel processed by a CNN. The layer automatically ignores undefined pixel labels during training.

example

`layer` = pixelClassificationLayer(Name=Value) returns a pixel classification output layer using one or more name-value arguments to set the optional [Classes](nnet.cnn.layer.pixelclassificationlayer.html#mw%5F783aebd8-1ff1-4bc6-8508-90c8b71fca32%5Fsep%5Fmw%5F42597d56-e35c-46d1-b5b1-aacec63315c2), [ClassWeights](nnet.cnn.layer.pixelclassificationlayer.html#mw%5Fcfa1db40-b267-44ae-b2b3-aa58d495fb20), and [Name](nnet.cnn.layer.pixelclassificationlayer.html#mw%5F783aebd8-1ff1-4bc6-8508-90c8b71fca32%5Fsep%5Fshared-cnn-layer-name). For example, pixelClassificationLayer(Name="pixclass") creates a pixel classification layer with the name pixclass.

example

Properties

expand all

Classes of the output layer, specified as a categorical vector, string array, cell array of character vectors, or "auto". IfClasses is "auto", then the software automatically sets the classes at training time. If you specify the string array or cell array of character vectors str, then the software sets the classes of the output layer tocategorical(str,str).

Data Types: char | categorical | string | cell

Class weights, specified as "none" or as a vector of real scalar. The elements of the vector correspond to the classes in[Classes](nnet.cnn.layer.pixelclassificationlayer.html#mw%5F783aebd8-1ff1-4bc6-8508-90c8b71fca32%5Fsep%5Fmw%5F42597d56-e35c-46d1-b5b1-aacec63315c2). If you specify`ClassWeights`, then you must specify `Classes`.

Use class weighting to balance classes when there are underrepresented classes in the training data.

This property is read-only.

The output size of the layer. The value is "auto" prior to training, and is specified as a numeric value at training time.

This property is read-only.

Loss function used for training, specified as"crossentropyex".

Data Types: char | string

This property is read-only.

Number of inputs to the layer, stored as 1. This layer accepts a single input only.

Data Types: double

This property is read-only.

Input names, stored as {'in'}. This layer accepts a single input only.

Data Types: cell

Examples

collapse all

Predict the categorical label of every pixel in an input image.

layers = [ imageInputLayer([32 32 3]) convolution2dLayer(3,16,Stride=2,Padding=1) reluLayer transposedConv2dLayer(3,1,Stride=2,Cropping=1) softmaxLayer pixelClassificationLayer ]

layers = 6×1 Layer array with layers:

 1   ''   Image Input                  32×32×3 images with 'zerocenter' normalization
 2   ''   2-D Convolution              16 3×3 convolutions with stride [2  2] and padding [1  1  1  1]
 3   ''   ReLU                         ReLU
 4   ''   2-D Transposed Convolution   1 3×3 transposed convolutions with stride [2  2] and cropping [1  1  1  1]
 5   ''   Softmax                      softmax
 6   ''   Pixel Classification Layer   Cross-entropy loss

Balance classes using inverse class frequency weighting when some classes are underrepresented in the training data. First, count class frequencies over the training data using pixelLabelDatastore. Then, set the 'ClassWeights' in pixelClassificationLayer to the computed inverse class frequencies.

Set the location of image and pixel label data.

dataDir = fullfile(toolboxdir("vision"),"visiondata"); imDir = fullfile(dataDir,"building"); pxDir = fullfile(dataDir,"buildingPixelLabels");

Create a pixel label image datastore using the ground truth images in imds and the pixel labeled images in pxds.

imds = imageDatastore(imDir); classNames = ["sky" "grass" "building" "sidewalk"]; pixelLabelID = [1 2 3 4]; pxds = pixelLabelDatastore(pxDir,classNames,pixelLabelID);

Tabulate class distribution in dataset.

tbl = countEachLabel(pxds)

tbl=4×3 table Name PixelCount ImagePixelCount ____________ __________ _______________

{'sky'     }    3.1485e+05       1.536e+06   
{'grass'   }    1.5979e+05       1.536e+06   
{'building'}    1.0312e+06       1.536e+06   
{'sidewalk'}         25313       9.216e+05

Calculate inverse frequency class weights.

totalNumberOfPixels = sum(tbl.PixelCount); frequency = tbl.PixelCount / totalNumberOfPixels; inverseFrequency = 1./frequency

inverseFrequency = 4×1

4.8632
9.5827
1.4848

60.4900

Set 'ClassWeights' to the inverse class frequencies.

layer = pixelClassificationLayer(... Classes=tbl.Name,ClassWeights=inverseFrequency)

layer = PixelClassificationLayer with properties:

        Name: ''
     Classes: [sky    grass    building    sidewalk]
ClassWeights: [4×1 double]
  OutputSize: 'auto'

Hyperparameters LossFunction: 'crossentropyex'

Extended Capabilities

expand all

Usage notes and limitations:

The code generator represents characters in an 8-bit ASCII codeset that the locale setting determines. Therefore, the use of non-ASCII characters in class names, layer names, layer description, or network names might result in errors. For more information, see Encoding of Characters in Code Generation (MATLAB Coder).

Usage notes and limitations:

To generate CUDA® or C++ code by using GPU Coder™, you must first construct and train a deep neural network. Once the network is trained and evaluated, you can configure the code generator to generate code and deploy the convolutional neural network on platforms that use NVIDIA® or ARM® GPU processors. For more information, see Deep Learning with GPU Coder (GPU Coder).
For this layer, you can generate code that takes advantage of the NVIDIA CUDA deep neural network library (cuDNN), NVIDIA TensorRT™ high performance inference library, or the ARMCompute Library for Mali GPU.
The code generator represents characters in an 8-bit ASCII codeset that the locale setting determines. Therefore, the use of non-ASCII characters in class names, layer names, layer description, or network names might result in errors. For more information, see Encoding of Characters in Code Generation (MATLAB Coder).

Version History

Introduced in R2017b

collapse all

The pixelClassificationLayer object will be removed in a future release. Follow these steps to update your code:

Define your network as a dlnetwork (Deep Learning Toolbox) object. You can use functions such as addLayers (Deep Learning Toolbox) and connectLayers (Deep Learning Toolbox) to build the network. Do not include output layers in the network.
Define a custom loss function that uses the crossentropy (Deep Learning Toolbox) function. Here is a sample loss function appropriate for pixel classification:
function loss = modelLoss(Y,T)
mask = ~isnan(T);
targets(isnan(T)) = 0;
loss = crossentropy(Y,T,Mask=mask,NormalizationFactor="mask-included");
end
Train the network using the trainnet (Deep Learning Toolbox) function with the custom loss function. For example, this code trains a dlnetwork network callednet using the training dataimages and the custom loss functionmodelLoss.
netTrained = trainnet(images,net,@modelLoss,options);