Convert ONNX models into Apple CoreML format.

This tool converts ONNX models to Apple CoreML format. To convert CoreML models to ONNX, use ONNXMLTools.

There's a comprehensive Tutorial showing how to convert PyTorch style transfer models through ONNX to CoreML models and run them in an iOS app.

Installation

Install From PyPI

pip install -U onnx-coreml

Install From Source

To get the latest version of the converter, install from source by cloning the repository along with its submodules and running the install.sh script. That is,

git clone --recursive https://github.com/onnx/onnx-coreml.git
cd onnx-coreml
./install.sh

Install From Source (for contributors)

To get the latest version of the converter, install from source by cloning the repository along with its submodules and running the install-develop.sh script. That is,

git clone --recursive https://github.com/onnx/onnx-coreml.git
cd onnx-coreml
./install-develop.sh

Dependencies

click
numpy
coremltools (2.0+)
onnx (1.3.0+)

How to use

To convert models use single function "convert" from onnx_coreml:

from onnx_coreml import convert

def convert(model,
            mode=None,
            image_input_names=[],
            preprocessing_args={},
            image_output_names=[],
            deprocessing_args={},
            class_labels=None,
            predicted_feature_name='classLabel',
            add_custom_layers = False,
            custom_conversion_functions = {})

The function returns a coreml model instance that can be saved to a .mlmodel file, e.g.:

mlmodel = convert(onnx_model)
mlmodel.save('coreml_model.mlmodel')

CoreML model spec can be obtained from the model instance, which can be used to update model properties such as output names, input names etc. For e.g.:

import coremltools
from coremltools.models import MLModel

spec = mlmodel.get_spec()
new_mlmodel = MLModel(spec)
coremltools.utils.rename_feature(spec, 'old_output_name', 'new_output_name')
coremltools.utils.save_spec(spec, 'model_new_output_name.mlmodel')

For more details see coremltools documentation.

Parameters

model: ONNX model | str
An ONNX model with parameters loaded in onnx package or path to file
with models.

mode: str ('classifier', 'regressor' or None)
Mode of the converted coreml model:
'classifier', a NeuralNetworkClassifier spec will be constructed.
'regressor', a NeuralNetworkRegressor spec will be constructed.

image_input_names: list of strings
Name of the inputs to be defined as image type. Otherwise, by default all inputs are MultiArray type.

preprocessing_args: dict
Specify preprocessing parameters, that are be applied to all the image inputs specified through the "image_input_names" parameter. 'is_bgr', 'red_bias', 'green_bias', 'blue_bias', 'gray_bias',
'image_scale' keys with the same meaning as

https://apple.github.io/coremltools/generated/coremltools.models.neural_network.html#coremltools.models.neural_network.NeuralNetworkBuilder.set_pre_processing_parameters

image_output_names: list of strings
Name of the outputs to be defined as image type. Otherwise, by default all outputs are MultiArray type.

deprocessing_args: dict
Same as 'preprocessing_args' but for the outputs.

class_labels: A string or list of strings.
As a string it represents the name of the file which contains
the classification labels (one per line).
As a list of strings it represents a list of categories that map
the index of the output of a neural network to labels in a classifier.

predicted_feature_name: str
Name of the output feature for the class labels exposed in the Core ML
model (applies to classifiers only). Defaults to 'classLabel'

add_custom_layers: bool
If True, then 'custom' layers will be added to the model in place of unsupported onnx ops or for the ops that have unsupported attributes.
Parameters for these custom layers should be filled manually by editing the mlmodel
or the 'custom_conversion_functions' argument can be used to do the same during the process of conversion

onnx_coreml_input_shape_map: dict (str: List[int])
(Optional) A dictionary with keys corresponding to the model input names. Values are a list of integers that specify how the shape of the input is mapped to CoreML. Convention used for CoreML shapes is:
0: Sequence, 1: Batch, 2: channel, 3: height, 4: width.
For example, an input of rank 2 could be mapped as [3,4] (i.e. H,W) or [1,2] (i.e. B,C) etc.

Returns

model: A coreml model.

CLI

Also you can use command-line script for simplicity:

convert-onnx-to-coreml [OPTIONS] ONNX_MODEL

The command-line script currently doesn't support all options mentioned above. For more advanced use cases, you have to call the python function directly.

Running Unit Tests

In order to run unit tests, you need pytest.

pip install pytest
pip install pytest-cov

To run all unit tests, navigate to the tests/ folder and run

pytest

To run a specific unit test, for instance the custom layer test, run

pytest -s custom_layers_test.py::CustomLayerTest::test_unsupported_ops_provide_functions

Currently supported

Models

Models from https://github.com/onnx/models that have been tested to work with this converter:

BVLC Alexnet
BVLC Caffenet
BVLC Googlenet
BVLC reference_rcnn_ilsvrc13
Densenet
Emotion-FERPlus
Inception V1
Inception V2
MNIST
Resnet50
Shufflenet
SqueezeNet
VGG
ZFNet

Operators

List of ONNX operators that can be converted into their CoreML equivalent:

Abs
Add
ArgMax
ArgMin
AveragePool
BatchNormalization
Clip
Concat
Conv
ConvTranspose
DepthToSpace
Div
Elu
Exp
Flatten
Gemm
GlobalAveragePool
GlobalMaxPool
HardSigmoid
InstanceNormalization
LeakyRelu
Log
LogSoftmax
LRN
MatMul
Max
MaxPool
Mean
MeanVarianceNormalization
Min
Mul
Neg
Pad
PRelu
Reciprocal
ReduceL1
ReduceL2
ReduceLogSum
ReduceMax
ReduceMean
ReduceMin
ReduceProd
ReduceSum
ReduceSumSquare
Relu
Reshape
Selu
Sigmoid
Slice
Softmax
Softplus
Softsign
SpaceToDepth
Split
Sqrt
Sub
Sum
Tanh
ThresholdedRelu
Transpose
Upsample

Some of the operators are partially compatible because CoreML does not support gemm for arbitrary tensors, has limited support for non 4-rank tensors etc.
For unsupported ops or unsupported attributes within supported ops, CoreML custom layers can be used.
See the testing script tests/custom_layers_test.py on how to produce CoreML models with custom layers.

License

Use of this source code is governed by the MIT License that can be found in the LICENSE.txt file.

genp/onnx-coreml