importCaffeNetwork

Import pretrained convolutional neural network models from Caffe

Syntax

net = importCaffeNetwork(protofile,datafile)

net = importCaffeNetwork(___,Name,Value)

Description

net = importCaffeNetwork(protofile,datafile) imports a pretrained network from Caffe [1]. The function returns the pretrained network with the architecture specified by the .prototxt file protofile and with network weights specified by the .caffemodel file datafile.

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

You can download pretrained networks from Caffe Model Zoo [2].

net = importCaffeNetwork(___,Name,Value) returns a network with additional options specified by one or more Name,Value pair arguments using any of the previous syntaxes.

Examples

Download Deep Learning Toolbox Importer for Caffe Models Support Package

Download and install Deep Learning Toolbox Importer for Caffe Models support package.

To download the required support package, type importCaffeNetwork at the command line.

importCaffeNetwork

If Deep Learning Toolbox Importer for Caffe 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.

Import Caffe Network

Specify files to import.

protofile = 'digitsnet.prototxt';
datafile = 'digits_iter_10000.caffemodel';

Import network.

net = importCaffeNetwork(protofile,datafile)

net = 
  SeriesNetwork with properties:

         Layers: [7×1 nnet.cnn.layer.Layer]
     InputNames: {'testdata'}
    OutputNames: {'ClassificationOutput'}

Input Arguments

protofile — File name

character vector | string scalar

File name of the .prototxt file containing the network architecture, specified as a character vector or a string scalar. protofile 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 the .prototxt file does not specify the size of the input data, you must specify the size using the 'InputSize' name-value pair argument.

Example: 'digitsnet.prototxt'

datafile — File name

character vector | string scalar

File name of the .caffemodel file containing the network weights, specified as a character vector or a string scalar. datafile 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. To import network layers without weights, use importCaffeLayers.

Example: 'digits_iter_10000.caffemodel'

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: importCaffeNetwork(protofile,datafile,'AverageImage',I) imports a pretrained network using the average image I for zero-center normalization.

InputSize — Size of input data

row vector

Size of input data, specified as a row vector. Specify a vector of two or three integer values [h,w], or [h,w,c] corresponding to the height, width, and the number of channels of the input data. If the .prototxt file does not specify the size of the input data, then you must specify the input size.

Example: [28 28 1]

AverageImage — Average image

matrix

Average image for zero-center normalization, specified as a matrix. If you specify an image, then you must specify an image of the same size as the input data. If you do not specify an image, the software uses the data specified in the .prototxt file, if present. Otherwise, the function sets the Normalization property of the image input layer of the network to 'none'.

Classes — Classes of the output layer

'auto' (default) | categorical vector | string array | cell array of character vectors

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

net — Imported pretrained Caffe network

SeriesNetwork object | DAGNetwork object

Imported pretrained Caffe network, returned as a SeriesNetwork object or DAGNetwork object. Caffe networks that take color images as input expect the images to be in BGR format. During import, importCaffeNetwork modifies the network so that the imported MATLAB network takes RGB images as input.

More About

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 Deep Learning 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).

importCaffeNetwork 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

importCaffeNetwork does not execute on a GPU. However, importCaffeNetwork 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 trainNetwork. 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 Parallel Computing Toolbox™ and a supported GPU device. For information on supported devices, see GPU Support by Release (Parallel Computing Toolbox).

Tips

• importCaffeNetwork can import networks with the following Caffe layer types, with some limitations:

  Caffe Layer	Deep Learning Toolbox Layer
  BatchNormLayer	batchNormalizationLayer
  ConcatLayer	depthConcatenationLayer
  ConvolutionLayer	convolution2dLayer
  DeconvolutionLayer	transposedConv2dLayer
  DropoutLayer	dropoutLayer
  EltwiseLayer (only sum)	additionLayer
  EuclideanLossLayer	RegressionOutputLayer
  InnerProductLayer	fullyConnectedLayer
  InputLayer	imageInputLayer
  LRNLayer (Local Response Normalization)	crossChannelNormalizationLayer
  PoolingLayer	maxPooling2dLayer or averagePooling2dLayer
  ReLULayer	reluLayer or leakyReluLayer
  ScaleLayer	batchNormalizationLayer
  SigmoidLayer	nnet.caffe.layer.SigmoidLayer
  SoftmaxLayer	softmaxLayer
  TanHLayer	tanhLayer

  If the network contains any other type of layer, then the software returns an error.

  The function imports only the layers that protofile specifies with the include-phase TEST. The function ignores any layers that protofile specifies with the include-phase TRAIN.

• 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 on MATLAB indexing, see Array Indexing. In MATLAB, to use an array of indices (ind) created in Python, convert the array to ind+1.

References

[1] Caffe. https://caffe.berkeleyvision.org/.

[2] Caffe Model Zoo. https://caffe.berkeleyvision.org/model_zoo.html.

Extended Capabilities

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

For code generation, you can load the network by using the syntax net = importCaffeNetwork.

Version History

Introduced in R2017a

R2018b: 'ClassNames' option will be removed

Not recommended starting in R2018b

'ClassNames' will be removed. Use 'Classes' instead. To update your code, replace all instances of 'ClassNames' with 'Classes'. There are some differences between the corresponding properties in classification output layers that require additional updates to your code.

The ClassNames property of a classification output layer is a cell array of character vectors. The Classes property is a categorical array. To use the value of Classes with functions that require cell array input, convert the classes using the cellstr function.