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 converter" [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 converter";
     }
     "Keras model" -> "keras-elcorenn" -> "ElcoreNN model";
     "ONNX model" -> "ONNX converter" -> "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-converter 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 converter
--------------
ONNX converter is a Python library that converts a model from ONNX to ElcoreNN.

Requirements:

* python version >= 3.8, <= 3.12.

Instructions to convert ONNX model to ElcoreNN:

#. Download ONNX converter from `Elvees Box`_.

#. Install wheel file::

     python3 -m venv .venv
     source .venv/bin/activate
     pip install --upgrade pip
     pip install onnx_converter-*-py3-none-any.whl

#. Prepare JSON configuration file according to ONNX converter instructions (to see all configuration options see README.md from `Elvees Box`_)::

     {
          "model_path": "/path/to/model.onnx",
          "result_path": "/path/to/the/folder/where/to/save/elcorenn/model"
     }

#. Run::

     onnx_converter --config_file conf.json


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
AveragePooling1D
AveragePooling2D
BatchNormalization
Concatenate/Merge
Conv1D                                               dilation_rate=1, groups=1
Conv2D                                               dilation_rate=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
MaxPooling2D
Multiply
Permute
ReLU
Reshape
Softmax
UpSampling2D                                         interpolation="nearest"
ZeroPadding2D
==================================================== ===================================

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

==================================================== ============================
ONNX Operators                                       Restrictions
==================================================== ============================
Abs
Add (including broadcasting)                         only for 2 tensors
ArgMax
AveragePool                                          1D, 2D, dilation=1
BatchNormalization
Cast
Clip
Concat
Conv                                                 conv_dimensions=[1,2,3],
                                                     dilations=1,
                                                     Conv3d float32 only
ConvTranspose                                        conv_dimensions=[1, 2]
ConstantOfShape
CumSum
Div (including broadcasting)
Einsum                                               only for 2 tensors
Erf
Equal
Exp
Expand
Flatten
Floor
Gather
GatherElements
Gemm                                                 used as full-connected layer
GlobalAveragePool                                    2D
GlobalMaxPool
Identity
InstanceNormalization
LayerNorm
Less
LSTM
MatMul (including broadcasting)                      Support 2D..5D tensors
MaxPool                                              1D, 2D, dilations=1
Mod
Mul (including broadcasting)                         only for 2 tensors
Neg
NonMaxSuppression
NonZero                                              (Allowed only precomputed inputs)
Not
Pad
Pow
PRelu
Range
ReduceL2
ReduceMax
ReduceMean                                           last dimension only
ReduceSum
ReLU
ReLU6
Reshape
Resize
ScatterND
Shape
Sigmoid
Slice
Softmax
Split
Squeeze
Sqrt
Sub (including broadcasting)                         only for 2 tensors
Tanh
Tile
Transpose
Unsqueeze
Where
==================================================== ============================

.. _ONNX Operators: https://github.com/onnx/onnx/blob/main/docs/Operators.md
.. _Keras layers: https://keras.io/api/layers/
.. _Elvees Box: https://box.elvees.com/index.php/s/elcorenn_converters?path=%2FONNX%20converter
