Select Function to Import ONNX Pretrained Network

Deep Learning Toolbox™ Converter for ONNX™ Model Format provides three functions to import a pretrained ONNX (Open Neural Network Exchange) network: importONNXNetwork, importONNXLayers, and importONNXFunction.

This flow chart illustrates which import function best suits different scenarios.

Flow chart for selecting ONNX import function

Note

By default, importONNXNetwork and importONNXLayers try to generate a custom layer when the software cannot convert an ONNX operator into an equivalent built-in MATLAB^® layer. For a list of operators for which the software supports conversion, see ONNX Operators Supported for Conversion into Built-In MATLAB Layers.

importONNXNetwork and importONNXLayers save the generated custom layers in the package +PackageName in the current folder.

importONNXNetwork and importONNXLayers do not automatically generate a custom layer for each ONNX operator that is not supported for conversion into a built-in MATLAB layer.

Decisions

This table describes each decision in the workflow for selecting an ONNX import function.

Decision	Description
Are all the ONNX operators supported for conversion into equivalent built-in MATLAB layers or can the software automatically generate custom layers?	If the imported network contains an ONNX operator not supported for conversion into a built-in MATLAB layer (see ONNX Operators Supported for Conversion into Built-In MATLAB Layers) and `importONNXNetwork` does not generate a custom layer, then `importONNXNetwork` returns an error. If the imported network contains an ONNX operator not supported for conversion into a built-in MATLAB layer and `importONNXLayers` does not generate a custom layer, then `importONNXLayers` inserts a placeholder layer in place of the unsupported layer. `importONNXFunction` supports most ONNX operators. For more information, see ONNX Operators That importONNXFunction Supports.
Will you deploy the imported network?	If you use `importONNXNetwork` or `importONNXLayers`, you can generate code for the imported network. To create a `DAGNetwork` object for code generation, see Load Pretrained Networks for Code Generation (MATLAB Coder).
Will you load the imported network with Deep Network Designer?	If you use `importONNXNetwork` or `importONNXLayers`, you can load the imported network with the Deep Network Designer app.
If you retrain the imported network, will you use a custom training loop?	If you use `importONNXFunction`, you can retrain the imported network only with a custom training loop. For an example, see Train Imported ONNX Function Using Custom Training Loop. Use `importONNXNetwork` with `TargetNetwork` specified as `"dlnetwork"` to import the network as a `dlnetwork` object. A `dlnetwork` enables support for custom training loops using automatic differentiation. Use `importONNXLayers` with `TargetNetwork` specified as `"dlnetwork"` to import the network as a `LayerGraph` object compatible with a `dlnetwork` object. Then convert the layer graph to a `dlnetwork` by using `dlnetwork`. For more information about training options, see Train Deep Learning Model in MATLAB.

Actions

This table describes each action in the workflow for selecting an ONNX import function.

Action	Description
Use `importONNXNetwork`	`importONNXNetwork` returns a `DAGNetwork` or `dlnetwork` object that is ready to use for prediction (for more information, see the `TargetNetwork` name-value argument). Predict class labels by using the `classify` function on the `DAGNetwork` object or the `predict` function on the `dlnetwork` object.
Use `importONNXLayers`	`importONNXLayers` returns a `LayerGraph` object compatible with a `DAGNetwork` or `dlnetwork` object (for more information, see the `TargetNetwork` name-value argument). `importONNXLayers` inserts placeholder layers in the place of unsupported layers. Find and replace the placeholder layers. Then, you can assemble the layer graph by using `assembleNetwork`, which returns a `DAGNetwork` object, or convert the layer graph to a `dlnetwork` object by using `dlnetwork`.
Use `importONNXFunction`	`importONNXFunction` returns an `ONNXParameters` object, which contains the network parameters, and a model function (see Imported ONNX Model Function), which contains the network architecture. The `ONNXParameters` object and the model function are ready to use for prediction. For an example, see Predict Using Imported ONNX Function.
Find and replace the placeholder layers	To find the names and indices of the placeholder layers in the imported network, use the `findPlaceholderLayers` function. You then can replace a placeholder layer with a new layer that you define. To replace a layer, use `replaceLayer`.