From 83af22143fcdb5fa706bc4cef5f7387e9d464031 Mon Sep 17 00:00:00 2001 From: Pracheer Gupta Date: Sun, 13 Aug 2017 22:13:26 -0700 Subject: [PATCH 01/12] Fixing CoreML converter's README: typos/grammar/etc. --- tools/coreml/README.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/tools/coreml/README.md b/tools/coreml/README.md index 32cde339d3a9..4d0400631d75 100644 --- a/tools/coreml/README.md +++ b/tools/coreml/README.md @@ -21,23 +21,23 @@ Let's say you want to use your MXNet model in an iPhone App. For the purpose of python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,227,227"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="squeezenetv11.mlmodel" ``` - The above command will save the converted model into squeezenet-v11.mlmodel in CoreML format. Internally MXNet first loads the model and then we walk through the entire symbolic graph converting each operator into its CoreML equivalent. Some of the parameters are used by MXNet in order to load and generate the symbolic graph in memory while others are used by CoreML either to pre-process the input before the going through the neural network or to process the output in a particular way. + The above command will save the converted model in CoreML format to file squeezenet-v11.mlmodel. Internally, the model is first loaded by MXNet recreating the entire symbolic graph in memory. The converter walks through this symbolic graph converting each operator into its CoreML equivalent. Some of the supplied arguments to the converter are used by MXNet to generate the graph while others are used by CoreML either to pre-process the input (before passing it to the neural network) or to process the output of the neural network in a particular way. In the command above: - * _model-prefix_: refers to the MXNet model prefix (may include the directory path). - * _epoch_: refers to the suffix of the MXNet model file. - * _input-shape_: refers to the input shape information in a JSON string format where the key is the name of the input variable (="data") and the value is the shape of that variable. If the model takes multiple inputs, input-shape for all of them need to be provided. + * _model-prefix_: refers to the prefix of the file containing the MXNet model that needs to be converted (may include the directory path). E.g. for squeezenet model above the model files are squeezenet_v1.1-symbol.json and squeezenet_v1.1-0000.params and, therefore, model-prefix is "squeezenet_v1.1" (or "/squeezenet_v1.1") + * _epoch_: refers to the suffix of the MXNet model filename. For squeezenet model above, it'll be 0. + * _input-shape_: refers to the input shape information in a JSON string format where the key is the name of the input variable (i.e. "data") and the value is the shape of that variable. If the model takes multiple inputs, input-shape for all of them need to be provided. * _mode_: refers to the coreml model mode. Can either be 'classifier', 'regressor' or None. In this case, we use 'classifier' since we want the resulting CoreML model to classify images into various categories. - * _pre-processing-arguments_: In the Apple world images have to be of type Image. By providing image_input_names as "data", we are saying that the input variable "data" is of type Image. + * _pre-processing-arguments_: In the Apple world, images have to be of type "Image". By providing image_input_names as "data", the converter will assume that the input variable "data" is of type "Image". * _class-labels_: refers to the name of the file which contains the classification labels (a.k.a. synset file). -output-file: the file where the CoreML model will be dumped. + * _output-file_: the file where resulting CoreML model will be stored. 3. The generated ".mlmodel" file can directly be integrated into your app. For more instructions on how to do this, please see [Apple CoreML's tutorial](https://developer.apple.com/documentation/coreml/integrating_a_core_ml_model_into_your_app). ### Providing class labels -You could provide a file containing class labels (as above) so that CoreML will return the predicted category the image belongs to. The file should have a label per line and labels can have any special characters. The line number of the label in the file should correspond with the index of softmax output. E.g. +You could provide a file containing class labels (as above) so that CoreML will return the category a given image belongs to. The file should have a label per line and labels can have any special characters. The line number of the label in the file should correspond with the index of softmax output. E.g. ```bash python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,227,227"}' --mode=classifier --class-labels classLabels.txt --output-file="squeezenetv11.mlmodel" @@ -49,16 +49,16 @@ You may have to provide the label names of the MXNet model's outputs. For exampl ```bash python mxnet_coreml_converter.py --model-prefix='vgg16' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="vgg16.mlmodel" --label-names="prob_label" ``` - -### Adding a pre-processing to CoreML model. -You could ask CoreML to pre-process the images before passing them through the model. + +### Adding a pre-processing layer to CoreML model. +You could ask CoreML to pre-process the images before passing them through the model. The following command provides image re-centering parameters for red, blue and green channel. ```bash python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,224,224"}' --pre-processing-arguments='{"red_bias":127,"blue_bias":117,"green_bias":103}' --output-file="squeezenet_v11.mlmodel" ``` -If you are building an app for a model that takes image as an input, you will have to provide image_input_names as pre-processing arguments. This tells CoreML that a particular input variable is of type Image. E.g.: - +If you are building an app for a model that takes "Image" as an input, you will have to provide image_input_names as pre-processing arguments. This tells CoreML that a particular input variable is of type Image. E.g.: + ```bash python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,224,224"}' --pre-processing-arguments='{"red_bias":127,"blue_bias":117,"green_bias":103,"image_input_names":"data"}' --output-file="squeezenet_v11.mlmodel" ``` @@ -88,8 +88,8 @@ This is a (growing) list of standard MXNet models that can be successfully conve 12. Transpose ## Known issues -Currently there are no known issues. +There are no known issues currently. -## This tool has been tested on environment with: +## This tool has been tested with: * MacOS - High Sierra 10.13 Beta. * Xcode 9 beta 5. From 01a1630cdf0e7e042f6b1d3dd993873a8ef3f8a7 Mon Sep 17 00:00:00 2001 From: Pracheer Gupta Date: Sun, 13 Aug 2017 22:30:58 -0700 Subject: [PATCH 02/12] CoreML converter README update: Talk about layers first and then about models. --- tools/coreml/README.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/tools/coreml/README.md b/tools/coreml/README.md index 4d0400631d75..d73ae3f5190b 100644 --- a/tools/coreml/README.md +++ b/tools/coreml/README.md @@ -64,16 +64,9 @@ python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --in ``` ## Currently supported -### Models -This is a (growing) list of standard MXNet models that can be successfully converted using the converter. This means that any other model that uses similar operators as these models can also be successfully converted. - -1. Inception: [Inception-BN](http://data.mxnet.io/models/imagenet/inception-bn/), [Inception-V3](http://data.mxnet.io/models/imagenet/inception-v3.tar.gz) -2. [NiN](http://data.dmlc.ml/models/imagenet/nin/) -2. [Resnet](http://data.mxnet.io/models/imagenet/resnet/) -3. [Squeezenet](http://data.mxnet.io/models/imagenet/squeezenet/) -4. [Vgg](http://data.mxnet.io/models/imagenet/vgg/) - ### Layers +List of layers that can be converted: + 1. Activation 2. Batchnorm 3. Concat @@ -87,6 +80,15 @@ This is a (growing) list of standard MXNet models that can be successfully conve 11. Softmax 12. Transpose +### Models +Any MXNet model that uses the above operators can be converted easily. For instance, the following standard models can be converted: + +1. Inception: [Inception-BN](http://data.mxnet.io/models/imagenet/inception-bn/), [Inception-V3](http://data.mxnet.io/models/imagenet/inception-v3.tar.gz) +2. [NiN](http://data.dmlc.ml/models/imagenet/nin/) +2. [Resnet](http://data.mxnet.io/models/imagenet/resnet/) +3. [Squeezenet](http://data.mxnet.io/models/imagenet/squeezenet/) +4. [Vgg](http://data.mxnet.io/models/imagenet/vgg/) + ## Known issues There are no known issues currently. From bbbfe2cab0d015597e7c8541dae08b99e90bdd35 Mon Sep 17 00:00:00 2001 From: Pracheer Gupta Date: Mon, 14 Aug 2017 13:37:26 -0700 Subject: [PATCH 03/12] Providing examples on converting various standard models; calling out issues with InceptionV3. --- tools/coreml/README.md | 43 +++++++++++++++++++++++++++++------------- 1 file changed, 30 insertions(+), 13 deletions(-) diff --git a/tools/coreml/README.md b/tools/coreml/README.md index d73ae3f5190b..e29eebe84bc1 100644 --- a/tools/coreml/README.md +++ b/tools/coreml/README.md @@ -43,13 +43,6 @@ You could provide a file containing class labels (as above) so that CoreML will python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,227,227"}' --mode=classifier --class-labels classLabels.txt --output-file="squeezenetv11.mlmodel" ``` -### Providing label names -You may have to provide the label names of the MXNet model's outputs. For example, if you try to convert [vgg16](http://data.mxnet.io/models/imagenet/vgg/), you may have to provide label-name as "prob_label". By default "softmax_label" is assumed. - -```bash -python mxnet_coreml_converter.py --model-prefix='vgg16' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="vgg16.mlmodel" --label-names="prob_label" -``` - ### Adding a pre-processing layer to CoreML model. You could ask CoreML to pre-process the images before passing them through the model. The following command provides image re-centering parameters for red, blue and green channel. @@ -65,7 +58,7 @@ python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --in ## Currently supported ### Layers -List of layers that can be converted: +List of MXNet layers that can be converted into their CoreML equivalent: 1. Activation 2. Batchnorm @@ -83,14 +76,38 @@ List of layers that can be converted: ### Models Any MXNet model that uses the above operators can be converted easily. For instance, the following standard models can be converted: -1. Inception: [Inception-BN](http://data.mxnet.io/models/imagenet/inception-bn/), [Inception-V3](http://data.mxnet.io/models/imagenet/inception-v3.tar.gz) +1. [Inception-BN](http://data.mxnet.io/models/imagenet/inception-bn/) + +```bash +python mxnet_coreml_converter.py --model-prefix='Inception-BN' --epoch=126 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="InceptionBN.mlmodel" +``` + 2. [NiN](http://data.dmlc.ml/models/imagenet/nin/) -2. [Resnet](http://data.mxnet.io/models/imagenet/resnet/) -3. [Squeezenet](http://data.mxnet.io/models/imagenet/squeezenet/) -4. [Vgg](http://data.mxnet.io/models/imagenet/vgg/) + +```bash +python mxnet_coreml_converter.py --model-prefix='nin' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="nin.mlmodel" +``` + +3. [Resnet](http://data.mxnet.io/models/imagenet/resnet/) + +```bash +python mxnet_coreml_converter.py --model-prefix='resnet-50' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="resnet50.mlmodel" +``` + +4. [Squeezenet](http://data.mxnet.io/models/imagenet/squeezenet/) + +```bash +python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,227,227"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="squeezenetv11.mlmodel" +``` + +5. [Vgg](http://data.mxnet.io/models/imagenet/vgg/) + +```bash +python mxnet_coreml_converter.py --model-prefix='vgg16' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="vgg16.mlmodel" +``` ## Known issues -There are no known issues currently. +* [Inception-V3](http://data.mxnet.io/models/imagenet/inception-v3.tar.gz) model can be converted into CoreML format but is unable to run on Xcode. ## This tool has been tested with: * MacOS - High Sierra 10.13 Beta. From 36e027e85cb5828aabe897e97c5d7b57e5a02101 Mon Sep 17 00:00:00 2001 From: Pracheer Gupta Date: Sun, 13 Aug 2017 22:13:26 -0700 Subject: [PATCH 04/12] Fixing CoreML converter's README: typos/grammar/etc. --- tools/coreml/README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/tools/coreml/README.md b/tools/coreml/README.md index e29eebe84bc1..3c2e6dc2e886 100644 --- a/tools/coreml/README.md +++ b/tools/coreml/README.md @@ -107,7 +107,11 @@ python mxnet_coreml_converter.py --model-prefix='vgg16' --epoch=0 --input-shape= ``` ## Known issues +<<<<<<< HEAD * [Inception-V3](http://data.mxnet.io/models/imagenet/inception-v3.tar.gz) model can be converted into CoreML format but is unable to run on Xcode. +======= +There are no known issues currently. +>>>>>>> Fixing CoreML converter's README: typos/grammar/etc. ## This tool has been tested with: * MacOS - High Sierra 10.13 Beta. From 11599241f5c2f2311232975f83272040fca81690 Mon Sep 17 00:00:00 2001 From: Pracheer Gupta Date: Sun, 13 Aug 2017 22:30:58 -0700 Subject: [PATCH 05/12] CoreML converter README update: Talk about layers first and then about models. --- tools/coreml/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tools/coreml/README.md b/tools/coreml/README.md index 3c2e6dc2e886..fa5919219467 100644 --- a/tools/coreml/README.md +++ b/tools/coreml/README.md @@ -76,6 +76,7 @@ List of MXNet layers that can be converted into their CoreML equivalent: ### Models Any MXNet model that uses the above operators can be converted easily. For instance, the following standard models can be converted: +<<<<<<< HEAD 1. [Inception-BN](http://data.mxnet.io/models/imagenet/inception-bn/) ```bash @@ -105,6 +106,13 @@ python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --in ```bash python mxnet_coreml_converter.py --model-prefix='vgg16' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="vgg16.mlmodel" ``` +======= +1. Inception: [Inception-BN](http://data.mxnet.io/models/imagenet/inception-bn/), [Inception-V3](http://data.mxnet.io/models/imagenet/inception-v3.tar.gz) +2. [NiN](http://data.dmlc.ml/models/imagenet/nin/) +2. [Resnet](http://data.mxnet.io/models/imagenet/resnet/) +3. [Squeezenet](http://data.mxnet.io/models/imagenet/squeezenet/) +4. [Vgg](http://data.mxnet.io/models/imagenet/vgg/) +>>>>>>> CoreML converter README update: Talk about layers first and then about models. ## Known issues <<<<<<< HEAD From a573e2f3d9af6f18184ab8c9e95ee4f12e6a1a9d Mon Sep 17 00:00:00 2001 From: Pracheer Gupta Date: Mon, 14 Aug 2017 13:37:26 -0700 Subject: [PATCH 06/12] Providing examples on converting various standard models; calling out issues with InceptionV3. --- tools/coreml/README.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/tools/coreml/README.md b/tools/coreml/README.md index fa5919219467..e29eebe84bc1 100644 --- a/tools/coreml/README.md +++ b/tools/coreml/README.md @@ -76,7 +76,6 @@ List of MXNet layers that can be converted into their CoreML equivalent: ### Models Any MXNet model that uses the above operators can be converted easily. For instance, the following standard models can be converted: -<<<<<<< HEAD 1. [Inception-BN](http://data.mxnet.io/models/imagenet/inception-bn/) ```bash @@ -106,20 +105,9 @@ python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --in ```bash python mxnet_coreml_converter.py --model-prefix='vgg16' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="vgg16.mlmodel" ``` -======= -1. Inception: [Inception-BN](http://data.mxnet.io/models/imagenet/inception-bn/), [Inception-V3](http://data.mxnet.io/models/imagenet/inception-v3.tar.gz) -2. [NiN](http://data.dmlc.ml/models/imagenet/nin/) -2. [Resnet](http://data.mxnet.io/models/imagenet/resnet/) -3. [Squeezenet](http://data.mxnet.io/models/imagenet/squeezenet/) -4. [Vgg](http://data.mxnet.io/models/imagenet/vgg/) ->>>>>>> CoreML converter README update: Talk about layers first and then about models. ## Known issues -<<<<<<< HEAD * [Inception-V3](http://data.mxnet.io/models/imagenet/inception-v3.tar.gz) model can be converted into CoreML format but is unable to run on Xcode. -======= -There are no known issues currently. ->>>>>>> Fixing CoreML converter's README: typos/grammar/etc. ## This tool has been tested with: * MacOS - High Sierra 10.13 Beta. From ff21ab4ce76f9936b3b0579ce552ec81afc140fb Mon Sep 17 00:00:00 2001 From: Pracheer Gupta Date: Thu, 24 Aug 2017 13:40:35 -0700 Subject: [PATCH 07/12] Pip installer for converter: mxnet-coreml-converter. Runs only on MacOS and python 2.7. Once inside the directory pip_package, user needs to run: python setup.py bdist_wheel twine upload dist/* Once uploaded it'll look like this: https://testpypi.python.org/pypi/mxnet-coreml-converter Also updated the README for converter to reflect this. Note that we are going with a package per tool for the time being. Please leave feedback if you think it is better to adopt the policy of all the tools in one single package. Unit tests continue to pass. --- tools/coreml/README.md | 33 +++++++++--------- tools/coreml/{ => converter}/utils.py | 0 tools/coreml/mxnet_coreml_converter.py | 3 +- tools/coreml/pip_package/.gitignore | 10 ++++++ tools/coreml/pip_package/MANIFEST.in | 5 +++ tools/coreml/pip_package/README.rst | 25 ++++++++++++++ tools/coreml/pip_package/setup.py | 48 ++++++++++++++++++++++++++ tools/coreml/test/test_mxnet_image.py | 2 +- 8 files changed, 108 insertions(+), 18 deletions(-) rename tools/coreml/{ => converter}/utils.py (100%) create mode 100644 tools/coreml/pip_package/.gitignore create mode 100644 tools/coreml/pip_package/MANIFEST.in create mode 100644 tools/coreml/pip_package/README.rst create mode 100644 tools/coreml/pip_package/setup.py diff --git a/tools/coreml/README.md b/tools/coreml/README.md index e29eebe84bc1..4a2457e13683 100644 --- a/tools/coreml/README.md +++ b/tools/coreml/README.md @@ -4,21 +4,22 @@ This tool helps convert MXNet models into [Apple CoreML](https://developer.apple ## Installation In order to use this tool you need to have these installed: -* MacOS - High Sierra 10.13 -* Xcode 9 -* coremltools 0.5.0 or greater (pip install coremltools) -* mxnet 0.10.0 or greater. [Installation instructions](http://mxnet.io/get_started/install.html). -* yaml (pip install pyyaml) +* MacOS - High Sierra 10.12 or higher. * python 2.7 +* mxnet-coreml-converter: + +```bash +pip install mxnet-coreml-converter +``` ## How to use -Let's say you want to use your MXNet model in an iPhone App. For the purpose of this example, let's say you want to use squeezenet-v1.1. +Let's say you want to use your MXNet model in an iPhone App. For the purpose of this example, let's assume it is a squeezenet-v1.1 model. -1. Download the model into the directory where this converter resides. Squeezenet can be downloaded from [here](http://data.mxnet.io/models/imagenet/squeezenet/). +1. Download the model into the directory where this converter resides. Squeezenet can be downloaded from [here](http://data.mxnet.io/models/imagenet/squeezenet/). The synset.txt file which contains all the class-labels and can be downloaded from [here](http://data.mxnet.io/models/imagenet/synset.txt). 2. Run this command: ```bash -python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,227,227"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="squeezenetv11.mlmodel" +mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,227,227"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels synset.txt --output-file="squeezenetv11.mlmodel" ``` The above command will save the converted model in CoreML format to file squeezenet-v11.mlmodel. Internally, the model is first loaded by MXNet recreating the entire symbolic graph in memory. The converter walks through this symbolic graph converting each operator into its CoreML equivalent. Some of the supplied arguments to the converter are used by MXNet to generate the graph while others are used by CoreML either to pre-process the input (before passing it to the neural network) or to process the output of the neural network in a particular way. @@ -40,20 +41,20 @@ python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --in You could provide a file containing class labels (as above) so that CoreML will return the category a given image belongs to. The file should have a label per line and labels can have any special characters. The line number of the label in the file should correspond with the index of softmax output. E.g. ```bash -python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,227,227"}' --mode=classifier --class-labels classLabels.txt --output-file="squeezenetv11.mlmodel" +mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,227,227"}' --mode=classifier --class-labels synset.txt --output-file="squeezenetv11.mlmodel" ``` ### Adding a pre-processing layer to CoreML model. You could ask CoreML to pre-process the images before passing them through the model. The following command provides image re-centering parameters for red, blue and green channel. ```bash -python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,224,224"}' --pre-processing-arguments='{"red_bias":127,"blue_bias":117,"green_bias":103}' --output-file="squeezenet_v11.mlmodel" +mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,224,224"}' --pre-processing-arguments='{"red_bias":127,"blue_bias":117,"green_bias":103}' --output-file="squeezenet_v11.mlmodel" ``` If you are building an app for a model that takes "Image" as an input, you will have to provide image_input_names as pre-processing arguments. This tells CoreML that a particular input variable is of type Image. E.g.: ```bash -python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,224,224"}' --pre-processing-arguments='{"red_bias":127,"blue_bias":117,"green_bias":103,"image_input_names":"data"}' --output-file="squeezenet_v11.mlmodel" +mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,224,224"}' --pre-processing-arguments='{"red_bias":127,"blue_bias":117,"green_bias":103,"image_input_names":"data"}' --output-file="squeezenet_v11.mlmodel" ``` ## Currently supported @@ -79,31 +80,31 @@ Any MXNet model that uses the above operators can be converted easily. For insta 1. [Inception-BN](http://data.mxnet.io/models/imagenet/inception-bn/) ```bash -python mxnet_coreml_converter.py --model-prefix='Inception-BN' --epoch=126 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="InceptionBN.mlmodel" +mxnet_coreml_converter.py --model-prefix='Inception-BN' --epoch=126 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels synset.txt --output-file="InceptionBN.mlmodel" ``` 2. [NiN](http://data.dmlc.ml/models/imagenet/nin/) ```bash -python mxnet_coreml_converter.py --model-prefix='nin' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="nin.mlmodel" +mxnet_coreml_converter.py --model-prefix='nin' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels synset.txt --output-file="nin.mlmodel" ``` 3. [Resnet](http://data.mxnet.io/models/imagenet/resnet/) ```bash -python mxnet_coreml_converter.py --model-prefix='resnet-50' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="resnet50.mlmodel" +mxnet_coreml_converter.py --model-prefix='resnet-50' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels synset.txt --output-file="resnet50.mlmodel" ``` 4. [Squeezenet](http://data.mxnet.io/models/imagenet/squeezenet/) ```bash -python mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,227,227"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="squeezenetv11.mlmodel" +mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' --epoch=0 --input-shape='{"data":"3,227,227"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels synset.txt --output-file="squeezenetv11.mlmodel" ``` 5. [Vgg](http://data.mxnet.io/models/imagenet/vgg/) ```bash -python mxnet_coreml_converter.py --model-prefix='vgg16' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels classLabels.txt --output-file="vgg16.mlmodel" +mxnet_coreml_converter.py --model-prefix='vgg16' --epoch=0 --input-shape='{"data":"3,224,224"}' --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' --class-labels synset.txt --output-file="vgg16.mlmodel" ``` ## Known issues diff --git a/tools/coreml/utils.py b/tools/coreml/converter/utils.py similarity index 100% rename from tools/coreml/utils.py rename to tools/coreml/converter/utils.py diff --git a/tools/coreml/mxnet_coreml_converter.py b/tools/coreml/mxnet_coreml_converter.py index 502377eca864..ffa5008b3db4 100644 --- a/tools/coreml/mxnet_coreml_converter.py +++ b/tools/coreml/mxnet_coreml_converter.py @@ -1,3 +1,4 @@ +#!/usr/bin/env python # Licensed to the Apache Software Foundation (ASF) under one # or more contributor license agreements. See the NOTICE file # distributed with this work for additional information @@ -18,7 +19,7 @@ from __future__ import print_function import argparse from converter._mxnet_converter import convert -from utils import load_model +from converter.utils import load_model import yaml from ast import literal_eval diff --git a/tools/coreml/pip_package/.gitignore b/tools/coreml/pip_package/.gitignore new file mode 100644 index 000000000000..7c67bf467970 --- /dev/null +++ b/tools/coreml/pip_package/.gitignore @@ -0,0 +1,10 @@ +# Compiled python modules. +*.pyc + +# Setuptools distribution folder. +/dist/ + +# Python egg metadata, regenerated from source files by setuptools. +/*.egg-info +/*.egg + diff --git a/tools/coreml/pip_package/MANIFEST.in b/tools/coreml/pip_package/MANIFEST.in new file mode 100644 index 000000000000..6ecd97d57dc7 --- /dev/null +++ b/tools/coreml/pip_package/MANIFEST.in @@ -0,0 +1,5 @@ +# Include the license file +include LICENSE.txt + +# Documentation for pypi webpage +include README.rst diff --git a/tools/coreml/pip_package/README.rst b/tools/coreml/pip_package/README.rst new file mode 100644 index 000000000000..3c6ea3dfacee --- /dev/null +++ b/tools/coreml/pip_package/README.rst @@ -0,0 +1,25 @@ +MXNET -> CoreML Converter +========================= + +This tool helps convert MXNet models into `Apple CoreML `_ format which can then be run on Apple devices. Find more information `here `_. + +Prerequisites +------------- +This package can only be installed on MacOS X since it relies on Apple's CoreML SDK. This tool can be run on MacOS 10.12 or higher though for running inferences on the converted model MacOS 10.13 or higher is needed (or for phones, iOS 11 or above). + +Installation +------------ +To install:: + + pip install mxnet-coreml-converter + + +Sample Usage +------------ + +In order to convert, say a `Squeezenet model `_, with labels from `synset.txt `_, execute this :: + + mxnet_coreml_converter.py --model-prefix='squeezenet_v1.1' \ + --epoch=0 --input-shape='{"data":"3,227,227"}' \ + --mode=classifier --pre-processing-arguments='{"image_input_names":"data"}' \ + --class-labels synset.txt --output-file="squeezenetv11.mlmodel" diff --git a/tools/coreml/pip_package/setup.py b/tools/coreml/pip_package/setup.py new file mode 100644 index 000000000000..71e93ee9e176 --- /dev/null +++ b/tools/coreml/pip_package/setup.py @@ -0,0 +1,48 @@ +from setuptools import setup +from setuptools import find_packages + +# We are overriding the default behavior of bdist_wheel which is generating +# pure python wheels while we need platform specific wheel since this tool +# can only work on MacOS. +try: + from wheel.bdist_wheel import bdist_wheel as _bdist_wheel + class bdist_wheel(_bdist_wheel): + def finalize_options(self): + _bdist_wheel.finalize_options(self) + self.root_is_pure = False +except ImportError: + bdist_wheel = None + + +def readme(): + with open('README.rst') as f: + return f.read() + +setup(name='mxnet-coreml-converter', + version='0.1.0a0', + description='Tool to convert MXNet models into Apple CoreML model format.', + long_description=readme(), + classifiers=[ + 'Development Status :: 3 - Alpha', + 'Intended Audience :: Developers', + 'License :: OSI Approved :: Apache Software License', + 'Operating System :: MacOS :: MacOS X', + 'Programming Language :: Python :: 2.7', + 'Topic :: Software Development :: Libraries :: Python Modules' + ], + keywords='Apache MXNet Apple CoreML Converter Deep Learning', + url='https://github.com/apache/incubator-mxnet/tree/master/tools/coreml', + author='pracheer', + author_email='pracheer_gupta@hotmail.com', + license='Apache 2.0', + package_dir = {'': '..'}, + packages=['converter'], + install_requires=[ + 'mxnet', + 'coremltools', + 'pyyaml', + ], + scripts=['../mxnet_coreml_converter.py'], + python_requires='~=2.7', + zip_safe=False, + cmdclass={'bdist_wheel': bdist_wheel},) diff --git a/tools/coreml/test/test_mxnet_image.py b/tools/coreml/test/test_mxnet_image.py index ac30ac7f5ad9..2bbf7b1e264b 100644 --- a/tools/coreml/test/test_mxnet_image.py +++ b/tools/coreml/test/test_mxnet_image.py @@ -24,7 +24,7 @@ sys.path.append(current_working_directory + "/..") sys.path.append(current_working_directory + "/../converter/") import _mxnet_converter as mxnet_converter -from utils import load_model +from converter.utils import load_model VAL_DATA = 'data/val-5k-256.rec' From bbcd0844ca6ed3efdb371612e206cfb52c589d7d Mon Sep 17 00:00:00 2001 From: Pracheer Gupta Date: Thu, 24 Aug 2017 14:40:08 -0700 Subject: [PATCH 08/12] More informative pypi package documentation. --- tools/coreml/pip_package/README.rst | 25 ++++++++++++++++++++++--- tools/coreml/pip_package/setup.py | 6 +++++- 2 files changed, 27 insertions(+), 4 deletions(-) diff --git a/tools/coreml/pip_package/README.rst b/tools/coreml/pip_package/README.rst index 3c6ea3dfacee..6b7fde246894 100644 --- a/tools/coreml/pip_package/README.rst +++ b/tools/coreml/pip_package/README.rst @@ -1,18 +1,31 @@ MXNET -> CoreML Converter ========================= -This tool helps convert MXNet models into `Apple CoreML `_ format which can then be run on Apple devices. Find more information `here `_. +`Apache MXNet `_ (incubating) is a deep learning framework designed for both efficiency and flexibility. It allows you to mix `symbolic and imperative programming `_ to maximize efficiency and productivity. At its core, MXNet contains a dynamic dependency scheduler that automatically parallelizes both symbolic and imperative operations on the fly. A graph optimization layer on top of that makes symbolic execution fast and memory efficient. MXNet is portable and lightweight, scaling effectively to multiple GPUs and multiple machines. + +`Core ML `_ is an Apple framework which allows developers to simply and easily integrate machine learning (ML) models into apps running on Apple devices (including iOS, watchOS, macOS, and tvOS). Core ML introduces a public file format (.mlmodel) for a broad set of ML methods including deep neural networks (both convolutional and recurrent), tree ensembles with boosting, and generalized linear models. Models in this format can be directly integrated into apps through Xcode. + +This tool helps convert `MXNet models `_ into `Apple CoreML `_ format which can then be run on Apple devices. You can find more information about this tool on our `github `_ page. Prerequisites ------------- -This package can only be installed on MacOS X since it relies on Apple's CoreML SDK. This tool can be run on MacOS 10.12 or higher though for running inferences on the converted model MacOS 10.13 or higher is needed (or for phones, iOS 11 or above). +This package can only be installed on MacOS X since it relies on Apple's CoreML SDK. It can be run on MacOS 10.12 or higher though for running inferences on the converted model MacOS 10.13 or higher is needed (or for phones, iOS 11 or above). Installation ------------ -To install:: +The method for installing this tool follows the `standard python package installation steps `_. Once you have set up a python environment, run:: pip install mxnet-coreml-converter +The package `documentation `_ contains more details on how to use coremltools. + +Dependencies +------------ +This tool has the following dependencies: + +* mxnet (0.10.0+) +* coremltools (0.5.1+) +* pyyaml (3.12+) Sample Usage ------------ @@ -23,3 +36,9 @@ In order to convert, say a `Squeezenet model `_ +* `MXNet framework `_ +* `Apple CoreML `_ diff --git a/tools/coreml/pip_package/setup.py b/tools/coreml/pip_package/setup.py index 71e93ee9e176..156a36752123 100644 --- a/tools/coreml/pip_package/setup.py +++ b/tools/coreml/pip_package/setup.py @@ -15,11 +15,15 @@ def finalize_options(self): def readme(): + """ + Reads README.rst file and allows us to provide + a better experience for pypi webpage. + """ with open('README.rst') as f: return f.read() setup(name='mxnet-coreml-converter', - version='0.1.0a0', + version='0.1.0a10', description='Tool to convert MXNet models into Apple CoreML model format.', long_description=readme(), classifiers=[ From ed842c4d8e810c66b45f9188e179b3df921b63e1 Mon Sep 17 00:00:00 2001 From: Pracheer Gupta Date: Fri, 25 Aug 2017 13:46:34 -0700 Subject: [PATCH 09/12] Updating MacOS in release notes to 10.11 after testing on it. --- tools/coreml/README.md | 8 ++------ tools/coreml/pip_package/README.rst | 2 +- tools/coreml/pip_package/setup.py | 2 +- 3 files changed, 4 insertions(+), 8 deletions(-) diff --git a/tools/coreml/README.md b/tools/coreml/README.md index 4a2457e13683..8fcc2f15dd8e 100644 --- a/tools/coreml/README.md +++ b/tools/coreml/README.md @@ -3,8 +3,8 @@ This tool helps convert MXNet models into [Apple CoreML](https://developer.apple.com/documentation/coreml) format which can then be run on Apple devices. ## Installation -In order to use this tool you need to have these installed: -* MacOS - High Sierra 10.12 or higher. +In order to use this tool you need to have these: +* MacOS - 10.11 (El Capitan) or higher (for running inferences on the converted model MacOS 10.13 or higher (for phones: iOS 11 or above) is needed) * python 2.7 * mxnet-coreml-converter: @@ -109,7 +109,3 @@ mxnet_coreml_converter.py --model-prefix='vgg16' --epoch=0 --input-shape='{"data ## Known issues * [Inception-V3](http://data.mxnet.io/models/imagenet/inception-v3.tar.gz) model can be converted into CoreML format but is unable to run on Xcode. - -## This tool has been tested with: -* MacOS - High Sierra 10.13 Beta. -* Xcode 9 beta 5. diff --git a/tools/coreml/pip_package/README.rst b/tools/coreml/pip_package/README.rst index 6b7fde246894..6dc5d38e3da3 100644 --- a/tools/coreml/pip_package/README.rst +++ b/tools/coreml/pip_package/README.rst @@ -9,7 +9,7 @@ This tool helps convert `MXNet models Date: Fri, 25 Aug 2017 16:03:58 -0700 Subject: [PATCH 10/12] Changing the name to mxnet-to-coreml and version to 0.1.0. --- tools/coreml/pip_package/setup.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tools/coreml/pip_package/setup.py b/tools/coreml/pip_package/setup.py index b6aaaf08db3a..74b9041fa679 100644 --- a/tools/coreml/pip_package/setup.py +++ b/tools/coreml/pip_package/setup.py @@ -22,12 +22,12 @@ def readme(): with open('README.rst') as f: return f.read() -setup(name='mxnet-coreml-converter', - version='0.1.0a13', +setup(name='mxnet-to-coreml', + version='0.1.0', description='Tool to convert MXNet models into Apple CoreML model format.', long_description=readme(), classifiers=[ - 'Development Status :: 3 - Alpha', + 'Development Status :: 4 - Beta', 'Intended Audience :: Developers', 'License :: OSI Approved :: Apache Software License', 'Operating System :: MacOS :: MacOS X', From fb8f3836948f791421ddb616bc441e58cba625b8 Mon Sep 17 00:00:00 2001 From: Pracheer Gupta Date: Mon, 28 Aug 2017 10:32:53 -0700 Subject: [PATCH 11/12] Added license to setup.py --- tools/coreml/pip_package/setup.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/tools/coreml/pip_package/setup.py b/tools/coreml/pip_package/setup.py index 74b9041fa679..18c601d38166 100644 --- a/tools/coreml/pip_package/setup.py +++ b/tools/coreml/pip_package/setup.py @@ -1,3 +1,20 @@ +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + from setuptools import setup from setuptools import find_packages From 53c01e8e69ae8e7c4b00d138db155bb92d7d8bd6 Mon Sep 17 00:00:00 2001 From: Pracheer Gupta Date: Mon, 28 Aug 2017 11:22:31 -0700 Subject: [PATCH 12/12] Updating readme files with the correct pip package name. --- tools/coreml/README.md | 4 ++-- tools/coreml/pip_package/README.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/tools/coreml/README.md b/tools/coreml/README.md index 8fcc2f15dd8e..45f19b608bdb 100644 --- a/tools/coreml/README.md +++ b/tools/coreml/README.md @@ -6,10 +6,10 @@ This tool helps convert MXNet models into [Apple CoreML](https://developer.apple In order to use this tool you need to have these: * MacOS - 10.11 (El Capitan) or higher (for running inferences on the converted model MacOS 10.13 or higher (for phones: iOS 11 or above) is needed) * python 2.7 -* mxnet-coreml-converter: +* mxnet-to-coreml tool: ```bash -pip install mxnet-coreml-converter +pip install mxnet-to-coreml ``` ## How to use diff --git a/tools/coreml/pip_package/README.rst b/tools/coreml/pip_package/README.rst index 6dc5d38e3da3..875d89fcd208 100644 --- a/tools/coreml/pip_package/README.rst +++ b/tools/coreml/pip_package/README.rst @@ -15,7 +15,7 @@ Installation ------------ The method for installing this tool follows the `standard python package installation steps `_. Once you have set up a python environment, run:: - pip install mxnet-coreml-converter + pip install mxnet-to-coreml The package `documentation `_ contains more details on how to use coremltools.