simaaiboxdecode
===============

The ``simaaiboxdecode`` GStreamer plugin decodes data using SiMa.ai’s proprietary decoding technology. It takes encoded data as input and outputs decoded data. This plugin is designed for efficient and high-performance decoding within a GStreamer pipeline.

Properties
----------

The plugin supports the following properties:

================ ======= ======= ===================================================
Property         Type    Default Description
================ ======= ======= ===================================================
silent           boolean FALSE   If TRUE, suppresses verbose output
num-buffers      uint    5       Number of buffers allocated
json-config-file string  “”      Path to the JSON configuration file for the decoder
================ ======= ======= ===================================================

Usage
-----

The plugin can be integrated into a GStreamer pipeline as follows:

.. code:: bash

   gst-launch-1.0 filesrc location=input.bin ! simaaiboxdecode json-config-file=/path/to/config.json ! fakesink

Replace ``/path/to/config.json`` with the actual path to your JSON configuration file. ``input.bin`` should be replaced with the path to your input file containing the encoded data. The ``fakesink`` element can be replaced with another element suitable for processing the decoded data.

Configuration
-------------

The configuration is divided into three blocks:

1. | **GenerixBoxDecode library parameters**
   | For the full list of parameters, refer to the library README.

2. | **Caps block**
   | For a detailed description of the Caps block, refer to the Caps Negotiation Library README.

3. | **Plugin parameters**
   | These are common across all aggregator template base plugins:

   - ``node_name`` – the name of the current node (used as the output buffer name).
   - ``memory`` – defines output memory options:

     - ``cpu`` – CPU where this plugin will run (affects **only** memory allocation).
     - ``next_cpu`` – CPU where the next plugin will run (affects **only** memory allocation).

   - ``system`` – defines plugin system settings:

     - ``out_buf_queue`` – size of the BufferPool.
     - ``dump_data`` – dumps output buffers to ``/tmp/{name-of-the-object}-{frame_id}.out``.

   - ``buffers`` – defines input/output buffers:

     - ``input`` – an array of objects specifying the input buffer name and size.
     - ``output`` – defines the output buffer size.

Actual examples of all 3 blocks can be found in `example config.json <configuration-file-example>`__.

Configuration file example
--------------------------

.. code:: json

   {
     "version": 0.1,
     "node_name": "simaai_boxdecode",
     "memory": {
       "cpu": 0,
       "next_cpu": 1
     },
     "system": {
       "out_buf_queue": 1,
       "debug": 0,
       "dump_data": 0
     },
     "buffers": {
       "input": [
         {
           "name": "simaai_process_mla",
           "size": 16000
         }
       ],
       "output": {
         "size": 580
       }
     },
     "decode_type" : "detr",
     "topk" : 24,
     "original_width": 1280,
     "original_height": 720,
     "model_width" : 640,
     "model_height" : 480,
     "num_classes" : 92,
     "detection_threshold" : 0.9,
     "nms_iou_threshold" : 0,
     "num_in_tensor": 2,
     "input_width": [
       100,
       100
     ],
     "input_height": [
       1,
       1
     ],
     "input_depth": [
       92,
       4
     ],
     "slice_width": [
       50,
       100
     ],
     "slice_height": [
       1,
       1
     ],
     "slice_depth": [
       92,
       4
     ],
     "dq_scale": [
       6.950103398907683,
       512.0
     ],
     "dq_zp": [
       37,
       -127357
     ],
     "data_type": [
       "INT8",
       "INT32"
     ],
     "caps": {
       "sink_pads": [
         {
           "media_type": "application/vnd.simaai.tensor",
           "params": [
             {
               "name": "format",
               "type": "string",
               "values": "MLA",
               "json_field": null
             },
             {
               "name": "data_type",
               "type": "string",
               "values": "(INT8, INT16, INT32), (INT8, INT16, INT32)",
               "json_field": "data_type"
             },
             {
               "name": "width",
               "type": "int",
               "values": "(1 - 4096), (1 - 4096)",
               "json_field": "input_width"
             },
             {
               "name": "height",
               "type": "int",
               "values": "(1 - 4096), (1 - 4096)",
               "json_field": "input_height"
             },
             {
               "name": "depth",
               "type": "int",
               "values": "(1 - 4096), (1 - 4096)",
               "json_field": "input_depth"
             },
             {
               "name": "slice_width",
               "type": "int",
               "values": "(1 - 4096), (1 - 4096)",
               "json_field": "slice_width"
             },
             {
               "name": "slice_height",
               "type": "int",
               "values": "(1 - 4096), (1 - 4096)",
               "json_field": "slice_height"
             },
             {
               "name": "slice_depth",
               "type": "int",
               "values": "(1 - 4096), (1 - 4096)",
               "json_field": "slice_depth"
             }
           ]
         }
       ],
       "src_pads": [
         {
           "media_type": "application/vnd.simaai.tensor",
           "params": [
             {
               "name": "format",
               "type": "string",
               "values": "BBOX",
               "json_field": null
             }
           ]
         }
       ]
     }
   }

Installation
------------

To install the ``simaaiboxdecode`` plugin, copy the plugin library file from ``/usr/local/simaai/plugin_zoo/gst-simaai-plugins-base/gst/`` into your project’s ``plugins/`` directory.

Integration into a GStreamer Pipeline
-------------------------------------

The ``simaaiboxdecode`` plugin acts as a transformation element within a GStreamer pipeline. It receives encoded data as input, processes it using the SiMa.ai decoder specified in the JSON configuration file, and outputs the decoded data. The plugin handles buffer management internally, according to the ``num-buffers`` property. The ``silent`` property controls the level of logging output. Make sure that the input caps match the expected input format of the decoder as specified in your JSON configuration file. Similarly, ensure appropriate caps are set after the ``simaaiboxdecode`` element to handle the output format.