Main Content

importKerasNetwork

(To be removed) Import pretrained Keras network and weights

collapse all in page

importKerasNetwork will be removed in a future release. Use importNetworkFromTensorFlow instead. (since R2023b) For more information about updating your code, see Version History.

Syntax

net = importKerasNetwork(modelfile)
net = importKerasNetwork(modelfile,Name,Value)

Description

net = importKerasNetwork(modelfile) imports a pretrained TensorFlow™-Keras network and its weights from modelfile.

This function requires the Deep Learning Toolbox™ Converter for TensorFlow Models support package. If this support package is not installed, the function provides a download link.

example

net = importKerasNetwork(modelfile,Name,Value) imports a pretrained TensorFlow-Keras network and its weights with additional options specified by one or more name-value pair arguments.

For example, importKerasNetwork(modelfile,'WeightFile',weights) imports the network from the model file modelfile and weights from the weight file weights. In this case, modelfile can be in HDF5 or JSON format, and the weight file must be in HDF5 format.

Examples

collapse all

This example uses:

Open Live Script

Download and install the Deep Learning Toolbox Converter for TensorFlow Models support package.

Type importKerasNetwork at the command line.

importKerasNetwork

If the Deep Learning Toolbox Converter for TensorFlow Models support package is not installed, then the function provides a link to the required support package in the Add-On Explorer. To install the support package, click the link, and then click Install. Check that the installation is successful by importing the network from the model file 'digitsDAGnet.h5' at the command line. If the required support package is installed, then the function returns a DAGNetwork object.

modelfile = 'digitsDAGnet.h5';
net = importKerasNetwork(modelfile)
Warning: Saved Keras networks do not include classes. Classes will be set to categorical(1:N), where N is the number of classes in the classification output layer of the network.  To specify classes, use the 'Classes' argument.

net = 
  DAGNetwork with properties:

         Layers: [13×1 nnet.cnn.layer.Layer]
    Connections: [13×2 table]
     InputNames: {'input_1'}
    OutputNames: {'ClassificationLayer_activation_1'}

This example uses:

Open Live Script

Specify the file to import. The file digitsDAGnet.h5 contains a directed acyclic graph convolutional neural network that classifies images of digits.

modelfile = 'digitsDAGnet.h5';

Import the network.

net = importKerasNetwork(modelfile)
Warning: Saved Keras networks do not include classes. Classes will be set to categorical(1:N), where N is the number of classes in the classification output layer of the network.  To specify classes, use the 'Classes' argument.

net = 
  DAGNetwork with properties:

         Layers: [13×1 nnet.cnn.layer.Layer]
    Connections: [13×2 table]
     InputNames: {'input_1'}
    OutputNames: {'ClassificationLayer_activation_1'}

Plot the network architecture.

plot(net)
title('DAG Network Architecture')

This example uses:

Open Live Script

Specify the network and the weight files to import.

modelfile = 'digitsDAGnet.json';
weights = 'digitsDAGnet.weights.h5';

This is a directed acyclic graph convolutional neural network trained on the digits data.

Import network architecture and import the weights from separate files. The .json file does not have an output layer or information on the cost function. Specify the output layer type when you import the files.

net = importKerasNetwork(modelfile,'WeightFile',weights, ...
      'OutputLayerType','classification')
Warning: Saved Keras networks do not include classes. Classes will be set to categorical(1:N), where N is the number of classes in the classification output layer of the network.  To specify classes, use the 'Classes' argument.

net = 
  DAGNetwork with properties:

         Layers: [13×1 nnet.cnn.layer.Layer]
    Connections: [13×2 table]
     InputNames: {'input_1'}
    OutputNames: {'ClassificationLayer_activation_1'}

This example uses:

Open Live Script

Specify the model file.

modelfile = 'digitsDAGnet.h5';

Specify class names.

classNames = {'0','1','2','3','4','5','6','7','8','9'};

Import the Keras network with the class names.

net = importKerasNetwork(modelfile,'Classes',classNames);

Read the image to classify.

digitDatasetPath = fullfile(toolboxdir('nnet'),'nndemos','nndatasets','DigitDataset');
I = imread(fullfile(digitDatasetPath,'5','image4009.png'));

Classify the image using the pretrained network.

label = classify(net,I);

Display the image and the classification result.

imshow(I)
title(['Classification result: ' char(label)])

Input Arguments

collapse all

Name of the model file containing the network architecture, and possibly the weights, specified as a character vector or a string scalar. The file must be in the current folder, in a folder on the MATLAB® path, or you must include a full or relative path to the file.

If modelfile includes

  • The network architecture and weights, then it must be in HDF5 (.h5) format.

  • Only the network architecture, then it can be in HDF5 or JSON (.json) format.

If modelfile includes only the network architecture, then you must supply the weights in an HDF5 file, using the 'WeightFile' name-value pair argument.

Example: 'digitsnet.h5'

Data Types: char | string

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: importKerasNetwork(modelfile,'OutputLayerType','classification','Classes',classes) imports a network from the model file modelfile, adds an output layer for a classification problem at the end of the Keras layers, and specifies classes as the classes of the output layer.

Name of file containing weights, specified as a character vector or a string scalar. WeightFile must be in the current folder, in a folder on the MATLAB path, or you must include a full or relative path to the file.

Example: 'WeightFile','weights.h5'

Type of output layer that the function appends to the end of the imported network architecture when modelfile does not specify a loss function, specified as 'classification', 'regression', or 'pixelclassification'. Appending a pixelClassificationLayer (Computer Vision Toolbox) object requires Computer Vision Toolbox™.

If a network in modelfile has multiple outputs, then you cannot specify the output layer types using this argument. Use importKerasLayers instead. importKerasLayers inserts placeholder layers for the outputs. After importing, you can find and replace the placeholder layers by using findPlaceholderLayers and replaceLayer, respectively.

Example: 'OutputLayerType','regression'

Size of the input images for the network, specified as a vector of two or three numerical values corresponding to [height,width] for grayscale images and [height,width,channels] for color images, respectively. The network uses this information when the modelfile does not specify the input size.

If a network in modelfile has multiple inputs, then you cannot specify the input sizes using this argument. Use importKerasLayers instead. importKerasLayers inserts placeholder layers for the inputs. After importing, you can find and replace the placeholder layers by using findPlaceholderLayers and replaceLayer, respectively.

Example: 'ImageInputSize',[28 28]

Classes of the output layer, specified as a categorical vector, string array, cell array of character vectors, or 'auto'. If you specify a string array or cell array of character vectors str, then the software sets the classes of the output layer to categorical(str,str). If Classes is 'auto', then the function sets the classes to categorical(1:N), where N is the number of classes.

Data Types: char | categorical | string | cell

Output Arguments

collapse all

Pretrained Keras network, returned as one of the following:

  • If the Keras network is of type Sequential, then net is a SeriesNetwork object.

  • If the Keras network is of type Model, then net is a DAGNetwork object.

Limitations

  • importKerasNetwork supports TensorFlow-Keras versions as follows:

    • The function fully supports TensorFlow-Keras versions up to 2.2.4.

    • The function offers limited support for TensorFlow-Keras versions 2.2.5 to 2.4.0.

More About

collapse all

Supported Keras Layers

importKerasNetwork supports the following TensorFlow-Keras layer types for conversion into built-in MATLAB layers, with some limitations.

TensorFlow-Keras LayerCorresponding Deep Learning Toolbox Layer
AddadditionLayer

Activation, with activation names:

  • elu

  • gelu

  • relu

  • linear

  • softmax

  • sigmoid

  • swish

  • tanh

Layers:

Advanced activations:

  • ELU

  • Softmax

  • ReLU

  • LeakyReLU

  • PReLu*

Layers:

AveragePooling1DaveragePooling1dLayer with PaddingValue specified as 'mean'
AveragePooling2DaveragePooling2dLayer with PaddingValue specified as 'mean'
BatchNormalizationbatchNormalizationLayer
Bidirectional(LSTM(__))bilstmLayer
ConcatenatedepthConcatenationLayer
Conv1Dconvolution1dLayer
Conv2Dconvolution2dLayer
Conv2DTransposetransposedConv2dLayer
CuDNNGRUgruLayer
CuDNNLSTMlstmLayer
DensefullyConnectedLayer
DepthwiseConv2DgroupedConvolution2dLayer
DropoutdropoutLayer
EmbeddingwordEmbeddingLayer (Text Analytics Toolbox)
Flattennnet.keras.layer.FlattenCStyleLayer
GlobalAveragePooling1DglobalAveragePooling1dLayer
GlobalAveragePooling2DglobalAveragePooling2dLayer
GlobalMaxPool1DglobalMaxPooling1dLayer
GlobalMaxPool2DglobalMaxPooling2dLayer
GRUgruLayer
InputimageInputLayer, sequenceInputLayer, or featureInputLayer
LSTMlstmLayer
MaxPool1DmaxPooling1dLayer
MaxPool2DmaxPooling2dLayer
MultiplymultiplicationLayer
SeparableConv2DgroupedConvolution2dLayer or convolution2dLayer
TimeDistributedsequenceFoldingLayer before the wrapped layer, and sequenceUnfoldingLayer after the wrapped layer
UpSampling2Dresize2dLayer (Image Processing Toolbox)
UpSampling3Dresize3dLayer (Image Processing Toolbox)
ZeroPadding1Dnnet.keras.layer.ZeroPadding1DLayer
ZeroPadding2Dnnet.keras.layer.ZeroPadding2DLayer

* For a PReLU layer, importKerasNetwork replaces a vector-valued scaling parameter with the average of the vector elements. You can change the parameter back to a vector after import. For an example, see Import Keras PReLU Layer.

Supported Keras Loss Functions

importKerasNetwork supports the following Keras loss functions:

  • mean_squared_error

  • categorical_crossentropy

  • sparse_categorical_crossentropy

  • binary_crossentropy

Generate Code for Imported Network

You can use MATLAB Coder™ or GPU Coder™ together with Deep Learning Toolbox to generate MEX, standalone CPU, CUDA® MEX, or standalone CUDA code for an imported network. For more information, see Code Generation.

  • Use MATLAB Coder with Deep Learning Toolbox to generate MEX or standalone CPU code that runs on desktop or embedded targets. You can deploy generated standalone code that uses the Intel® MKL-DNN library or the ARM® Compute library. Alternatively, you can generate generic C or C++ code that does not call third-party library functions. For more information, see Deep Learning with MATLAB Coder (MATLAB Coder).

  • Use GPU Coder with Deep Learning Toolbox to generate CUDA MEX or standalone CUDA code that runs on desktop or embedded targets. You can deploy generated standalone CUDA code that uses the CUDA deep neural network library (cuDNN), the TensorRT™ high performance inference library, or the ARM Compute library for Mali GPU. For more information, see Deep Learning with GPU Coder (GPU Coder).

importKerasNetwork returns the network net as a DAGNetwork or SeriesNetwork object. Both these objects support code generation. For more information on MATLAB Coder and GPU Coder support for Deep Learning Toolbox objects, see Supported Classes (MATLAB Coder) and Supported Classes (GPU Coder), respectively.

You can generate code for any imported network whose layers support code generation. For lists of the layers that support code generation with MATLAB Coder and GPU Coder, see Supported Layers (MATLAB Coder) and Supported Layers (GPU Coder), respectively. For more information on the code generation capabilities and limitations of each built-in MATLAB layer, see the Extended Capabilities section of the layer. For example, see Code Generation and GPU Code Generation of imageInputLayer.

Use Imported Network on GPU

importKerasNetwork does not execute on a GPU. However, importKerasNetwork imports a pretrained neural network for deep learning as a DAGNetwork or SeriesNetwork object, which you can use on a GPU.

  • You can make predictions with the imported network on either a CPU or GPU by using classify. Specify the hardware requirements using the name-value argument ExecutionEnvironment. For networks with multiple outputs, use the predict function.

  • You can make predictions with the imported network on either a CPU or GPU by using predict. Specify the hardware requirements using the name-value argument ExecutionEnvironment. If the network has multiple outputs, specify the name-value argument ReturnCategorical as true.

  • You can train the imported network on either a CPU or GPU by using the trainnet and trainNetwork functions. To specify training options, including options for the execution environment, use the trainingOptions function. Specify the hardware requirements using the name-value argument ExecutionEnvironment. For more information on how to accelerate training, see Scale Up Deep Learning in Parallel, on GPUs, and in the Cloud.

Using a GPU requires a Parallel Computing Toolbox™ license and a supported GPU device. For information about supported devices, see GPU Computing Requirements (Parallel Computing Toolbox).

Tips

  • If the network contains a layer that Deep Learning Toolbox Converter for TensorFlow Models does not support (see Supported Keras Layers), then importKerasNetwork returns an error message. In this case, you can still use importKerasLayers to import the network architecture and weights.

  • You can import a Keras network with multiple inputs and multiple outputs (MIMO). Use importKerasNetwork if the network includes input size information for the inputs and loss information for the outputs. Otherwise, use importKerasLayers. The importKerasLayers function inserts placeholder layers for the inputs and outputs. After importing, you can find and replace the placeholder layers by using findPlaceholderLayers and replaceLayer, respectively. The workflow for importing MIMO Keras networks is the same as the workflow for importing MIMO ONNX™ networks. For an example, see Import and Assemble ONNX Network with Multiple Outputs. To learn about a deep learning network with multiple inputs and multiple outputs, see Multiple-Input and Multiple-Output Networks.

  • To use a pretrained network for prediction or transfer learning on new images, you must preprocess your images in the same way as the images that you use to train the imported model. The most common preprocessing steps are resizing images, subtracting image average values, and converting the images from BGR format to RGB format.

    • To resize images, use imresize. For example, imresize(image,[227 227 3]).

    • To convert images from RGB to BGR format, use flip. For example, flip(image,3).

    For more information about preprocessing images for training and prediction, see Preprocess Images for Deep Learning.

  • MATLAB uses one-based indexing, whereas Python® uses zero-based indexing. In other words, the first element in an array has an index of 1 and 0 in MATLAB and Python, respectively. For more information about MATLAB indexing, see Array Indexing. In MATLAB, to use an array of indices (ind) created in Python, convert the array to ind+1.

  • For more tips, see Tips on Importing Models from TensorFlow, PyTorch, and ONNX.

Alternative Functionality

  • Use importKerasNetwork or importKerasLayers to import a TensorFlow-Keras network in HDF5 or JSON format. If the TensorFlow network is in the saved model format, use importTensorFlowNetwork or importTensorFlowLayers.

  • If you import a custom TensorFlow-Keras layer or if the software cannot convert a TensorFlow-Keras layer into an equivalent built-in MATLAB layer, you can use importTensorFlowNetwork or importTensorFlowLayers, which try to generate a custom layer. For example, importTensorFlowNetwork and importTensorFlowLayers generate a custom layer when you import a TensorFlow-Keras Lambda layer.

References

[1] Keras: The Python Deep Learning library. https://keras.io.

Version History

Introduced in R2017b

collapse all

R2023b: importKerasNetwork will be removed

Starting in R2023b, the importKerasNetwork function warns. Use importNetworkFromTensorFlow instead. The importNetworkFromTensorFlow function has these advantages over importKerasNetwork:

  • Imports a TensorFlow-Keras model into a dlnetwork object in a single step

  • Provides a simplified workflow for importing models with unknown input and output information

  • Has improved name-value arguments that you can use to more easily specify import options

  • Supports the newer TensorFlow SavedModel format instead of the discouraged Keras H5 format

See Also

| | | | | | | |

Topics