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

.. graphviz::
   :caption: ElcoreNN converters
   :align: center

   digraph ConvertersDigraph {
     node [ shape = box, style = filled, width=2.0, height=0.4]
     {"Keras model" [shape=cylinder]
      "ONNX model" [shape=cylinder]
      "keras-elcorenn" [shape=box]
      "onnx-elcorenn" [shape=box]
      "ElcoreNN model" [shape=cylinder]
     }
     subgraph "Models" {
       cluster=true;
       label="Models";
       "Keras model";
       "ONNX model";
     }
     subgraph "Converters" {
       cluster=true;
       label="Converters";
       "keras-elcorenn";
       "onnx-elcorenn";
     }
     "Keras model" -> "keras-elcorenn" -> "ElcoreNN model";
     "ONNX model" -> "onnx-elcorenn" -> "ElcoreNN model";
   }

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:

* python version >= 3.6

#. Download onnx-elcorenn archive and extract [see :doc:`release-notes` to choose version]::

     wget --no-check-certificate -O onnxparser-[version].tar.gz \
     https://box.elvees.com/index.php/s/elcorenn-converters/download?files=onnxparser-[version].tar.gz
     tar xfv onnxparser-[version].tar.gz

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

     cd onnxparser-[version]
     python3 -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
Conv3D                                               reference version (fp32 only)
Conv1DTranspose                                      reference version (fp32 only)
Conv2DTranspose                                      dilation_rate=1,
                                                     filters value is divisible by 32
Dense
DepthwiseConv2D                                      dilation_rate=1, depth_multiplier=1
Flatten
GlobalAveragePooling2D
InputLayer
L2Normalization
LSTM                                                 reference version (fp32 only)
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
AveragePool                                          2D, dilations=1
BatchNormalization
Cast
Clip
Concat
Conv                                                 conv_dimensions=[1,2,3],
                                                     dilations=1,
                                                     group=[1 or in_channels],
                                                     Conv3d float32 only
ConvTranspose                                        conv_dimensions=[1, 2]
ConstantOfShape
Div
Erf
Equal
Exp
Expand
Flatten
Gather
Gemm                                                 used as full-connected layer
GlobalAveragePool                                    2D
Identity
InstanceNormalization
LSTM                                                 reference version (fp32 only)
MatMul (including broadcasting)                      Support 2D..5D tensors
MaxPool                                              2D, dilations=1
Mul (including broadcasting)                         only for 2 tensors
Pad
Pow
Range
ReduceMean                                           last dimension only
ReLU
ReLU6
Reshape
Resize
Shape
Sigmoid
Slice
Softmax
Squeeze
Sqrt
Sub (including broadcasting)                         only for 2 tensors
Tanh
Transpose
Unsqueeze
Where
==================================================== ============================

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