Gst-nvmsgconv
================

The Gst-nvmsgconv plugin is responsible for converting metadata into message payloads based on schema.
DeepStream 5.0 supports two variations of the schema, full and minimal. The Gst-nvmsgconv plugin can be configured to use either one of the schemas.
By default, the plugin uses the full DeepStream schema to generate the payload in JSON format. The full schema supports elaborate semantics for object detection, analytics modules, events, location, and sensor. Each payload has information about a single object.
You can use the minimal variation of the schema to communicate minimal information with the back end. This provides a small footprint for the payload to be transmitted from DeepStream to a message broker. Each payload can have information for multiple objects in the frame.


Gst-nvmsgconv plugin interface with a low level ``nvmsgconv`` library which provides APIs for payload generation using below metadata types:
1. ``NVDS_EVENT_MSG_META`` (NvDsEventMsgMeta) type metadata attached to the buffer as user metadata of frame meta. For the batched buffer, metadata of all objects of a frame must be under the corresponding frame meta. This is the default option.
OR
2. By parsing the ``NVDS_FRAME_META`` (NvDsFrameMeta) type and ``NVDS_OBJECT_META`` (NvDsObjectMeta) type in Gst buffer and available fields in these metadata types are used to create message payload based on schema type. To use this option,  set gst property ``msg2p-newapi`` = true.
This API also supports attaching a custom user message blob(a json formatted string) for each payload if the msg blob is added as user metadata of NvDsFrameMeta.
Additionally, with this API there's also an other gst property you can use to set the frame interval at which each payload is generated.
``frame-interval`` = <interval>. If this is not set, the default frame interval at which frames are generates is every 30 frames

The generated payload (NvDsPayload) in both the above cases are attached back to the input buffer as ``NVDS_PAYLOAD_META`` type user metadata.

Additionally, Gst-nvmsgconv plugin provides optional properties:
- ``debug-payload-dir`` : Absolute path of the directory to dump payloads for debugging
- ``multiple-payloads`` : Generate multiple message payloads

.. image:: /content/DS_plugin_gst-nvmsgconv.png
         :align: center
         :alt: Gst-nvmsgconv


Inputs and Outputs
-------------------

* Inputs

  *	Gst Buffer with NvDsEventMsgMeta or NvDsFrameMeta/NvDsObjectMeta

* Control parameters

  *	config
  *	msg2p-lib
  *	payload-type
  *	comp-id
  *	debug-payload-dir (optional)
  *	multiple-payloads (optional)
  *	msg2p-newapi (optional)
  *	frame-interval (optional)

* Output

  * Same Gst Buffer with additional NvDsPayload metadata. This metadata contains information about the payload generated by the plugin.

Features
---------

The following table summarizes the features of the plugin.

.. csv-table:: Gst-nvmsgconv plugin features 
  :file: ../text/tables/Gst-nvmsgconv tables/DS_Plugin_gst-nvmsgconv_features.csv
  :widths: 30, 30, 30
  :header-rows: 1

Gst Properties
----------------

The following table describes the Gst-nvmsgconv plugin’s Gst properties.

.. csv-table:: Gst-nvmsgconv plugin gst properties 
  :file: ../text/tables/Gst-nvmsgconv tables/DS_Plugin_gst-nvmsgconv_gst-properties.csv
  :widths: 20, 20, 20, 20, 20
  :header-rows: 1

Schema Customization
---------------------

This plugin can be used to implement a custom schema in two ways:

* By modifying the payload generator library: To perform a simple customization of DeepStream schema fields, modify the low-level payload generation library file ``sources/libs/nvmsgconv/nvmsgconv.cpp``.
* By implementing the ``nvds_msg2p`` interface: If a library that implements the custom schema needs to be integrated with the DeepStream SDK, wrap the library in the ``nvds_msg2p`` interface and set the plugin’s msg2p-lib property to the library’s name. Set the payload-type property to ``PAYLOAD_CUSTOM``.

See ``sources/libs/nvmsgconv/nvmsgconv.cpp`` for an example implementation of the ``nvds_msg2p`` interface.

Payload with Custom Objects
-----------------------------

You can add a group of custom objects to the ``NvDsEventMsgMeta`` structure in the ``extMsg`` field and specify their size in the ``extMsgSize`` field. The meta copy (``copy_func``) and free (``release_func``) functions must handle the custom fields accordingly.
The payload generator library handles some standard types of objects (Vehicle, Person, Face, etc.) and generates the payload according to the schema selected. To handle custom object types, you must modify the payload generator library ``nvmsgconv.cpp``.
See ``deepstream-test4`` for details about adding custom objects as ``NVDS_EVENT_MSG_META`` user metadata with buffers for generating a custom payload to send to back end.