Converters
==========
Converters are Python libraries that run on x86 and are used to convert
Keras or ONNX models to ElcoreNN format.

.. blockdiag::

   blockdiag {
     orientation = portrait;
     default_shape = roundedbox;
     default_group_color = "#FFFFFF";
     A [label = "Keras model"];
     B [label = "ONNX model"];
     C [label = "keras-elcorenn"];
     D [label = "onnx-elcorenn"];
     E [label = "ElcoreNN model"];

     A -> C -> E;
     B -> D -> E;

     group {
       label = "Converters";
       C, D;
     }
   }

Supported operators
-------------------
Converters from Keras/ONNX to ElcoreNN supports the following neural network operators:

Operators below are combination of `Keras layers`_ and `ONNX Operators`_.

- ✓: defined in the source framework, converter supports operator.
- ×: defined in the source framework, converter doesn't support operator.
- empty: not defined in the source framework.

==================================================== ============== =============
Operator                                             keras-elcorenn onnx-elcorenn
==================================================== ============== =============
2D Average pooling                                   ✓              ×
2D Convolution (dilation=1, groups=1)                ✓              ✓
2D Depth-wise convolution (dilation=1, multiplier=1) ✓              ✓
2D Global average pooling                            ✓              ✓
2D Max pooling                                       ✓              ✓
2D Transposed convolution (dilation=1)               ✓              ×
2D Upsampling (interpolation="nearest")              ✓
Add (including broadcasting, only for two tensors)   ✓              ✓
BatchNormalization                                   ✓              ✓
Cast                                                                ✓
Concat                                               ✓              ✓
ConstantOfShape                                                     ✓
Gemm (Dense)                                         ✓              ✓
Equal                                                               ✓
Exp                                                                 ✓
Expand                                                              ✓
Flatten                                              ✓              ✓
Gather                                                              ✓
ReduceL2 (L2 normalization)                          ✓              ×
Log                                                                 ✓
Mul (including broadcasting)                         ✓              ✓
Pad (zero padding)                                   ✓              ×
Pow                                                                 ✓
Range                                                               ✓
ReLU                                                 ✓              ✓
ReLU6                                                ✓
Reshape                                              ✓              ✓
Resize                                                              ✓
Shape                                                               ✓
Sigmoid                                              ✓              ✓
Slice                                                               ✓
Softmax                                              ✓              ✓
Sub                                                  ×              ✓
Tanh                                                 ✓              ✓
Transpose                                            ✓              ✓
Unsqueeze                                                           ✓
Where                                                               ✓
==================================================== ============== =============

.. _ONNX Operators: https://github.com/onnx/onnx/blob/main/docs/Operators.md
.. _Keras layers: https://keras.io/api/layers/

ElcoreNN model format
---------------------
ElcoreNN model format is two files.
The first is a JSON file that describes the layers of the model.
The second is a binary file that contains the weights of the model.

keras-elcorenn and onnx-elcorenn convert Keras and ONNX model to ElcoreNN model format.

keras-elcorenn
--------------
keras-elcorenn is a Python library that converts a model from Keras to ElcoreNN.

Requirements:

* python version >=3.7

#. Download keras-elcorenn archive::

     wget --no-check-certificate https://box.elvees.com/index.php/s/SJRtBoB2HjFtAb9/download/keras-elcorenn-1.0.0.tar.gz

#. Activate virtual environment::

     python3 -m venv env
     source ./env/bin/activate

#. Installation from archive::

     pip install keras-elcorenn-1.0.0.tar.gz

#. Convert model::

     python -m keras2elcorenn.convert --keras-model=<path-to-keras-model>

   To see more options run::

     python -m keras2elcorenn.convert --help

onnx-elcorenn
-------------
onnx-elcorenn is a Python library that converts a model from ONNX to ElcoreNN.

Requirements:

* python3.6

#. Download onnx-elcorenn archive and extract::

     wget --no-check-certificate https://box.elvees.com/index.php/s/MeYA8tEsTt5ew68/download/onnxparser-v1.2.1.tar.gz
     tar xfv onnxparser-v1.2.1.tar.gz

#. Install requirements (it is recommended to use a virtual environment)::

     cd onnxparser-v1.2.1
     python3.6 -m venv env
     source ./env/bin/activate
     pip install --upgrade pip
     pip install -r requirements.txt

#. Put your onnx model to ``onnx_models`` folder.

#. Run converter::

     python onnx_converter.py -n <model-name.onnx> -at

   Converter will write result to ``json_models/<model-name>.onnx`` folder.

   To see more options run::

     python onnx_converter.py --help

   or see README.md file.