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;
     }
   }

ElcoreNN model format
---------------------
ElcoreNN model format is represented by 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 -O keras-elcorenn-1.0.0.tar.gz \
     https://box.elvees.com/index.php/s/elcorenn-converters/download?files=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 -O onnxparser-v1.3.0.tar.gz \
     https://box.elvees.com/index.php/s/elcorenn-converters/download?files=onnxparser-v1.3.0.tar.gz
     tar xfv onnxparser-v1.3.0.tar.gz

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

     cd onnxparser-v1.3.0
     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.


Supported operators
-------------------

For all Keras layers keras-elcorenn supports only NHWC data format.

keras-elcorenn supports the following `Keras layers`_:

==================================================== ===================================
Keras layer                                          Restrictions
==================================================== ===================================
Activation                                           only linear, relu, relu6, softmax,
                                                     leakyrelu, sigmoid
Add
AveragePooling2D
BatchNormalization
Concatenate/Merge
Conv1D                                               dilation_rate=1, groups=1
Conv2D                                               dilation_rate=1, groups=1
Conv2DTranspose                                      dilation_rate=1,
                                                     filters value is divisible by 32
Dense
DepthwiseConv2D                                      dilation_rate=1, depth_multiplier=1
Flatten
GlobalAveragePooling2D
InputLayer
L2Normalization
MaxPooling2D
Multiply
Permute
ReLU
Reshape
Softmax
UpSampling2D                                         interpolation="nearest"
ZeroPadding2D
==================================================== ===================================

onnx-elcorenn supports the following `ONNX Operators`_:

==================================================== ============================
ONNX Operators                                       Restrictions
==================================================== ============================
Add (including broadcasting)                         only for 2 tensors
BatchNormalization
Cast                                                 fixed point isn't supported
Concat
Conv                                                 conv_dimensions=[1,2],
                                                     dilations=1,
                                                     group=[1 or in_channels]
ConstantOfShape
Div
Erf
Equal
Exp
Expand
Flatten
Gather
Gemm                                                 used as full-connected layer
GlobalAveragePool                                    2D
Identity
MaxPool                                              2D, dilations=1
Mul (including broadcasting)                         only for 2 tensors
Pow
Range
ReLU
ReLU6
Reshape
Resize
Shape
Sigmoid
Slice
Softmax
Sqrt
Sub (including broadcasting)                         only for 2 tensors
Transpose
Unsqueeze
Where
==================================================== ============================

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