**Contents**

-  `Object tracking <#object-tracking>`__
-  `Usage <#usage>`__
-  `Recommendations <#recommendations>`__
-  `Known Issues <#known-issues>`__

Object Tracking
~~~~~~~~~~~~~~~

Object tracking is supported by DLStreamer through ``gvatrack`` element.
It is typically inserted into a video pipeline after ``gvadetect``
element.

There are several tracking types supported, for example,
short-term-imageless, zero-term, zero-term-imageless. By default,
zero-term tracking is enabled which requires object detection to be run
on every frame.

More details object tracking, tracking types, performance
considerations, examples can be found
`here <https://dlstreamer.github.io/dev_guide/object_tracking.html>`__.

Usage
~~~~~

Note: By default, tracking is disabled.

To enable object tracking in a video pipeline that has a UDFLoader
element, two elements ``gvapython`` and ``gvatrack`` need to be inserted
after the ``udfloader`` element in the pipeline. When tracking is
enabled, the metadata will include the object ids starting from
sequentially from ``1`` for each detection.

1. ``gvapython`` element adds detected ROIs to video frame. This is
   required by the tracking element to assign object ids.
2. ``gvatrack`` adds tracking info.

To disable tracking, the above elements (if present) following the
``udfloader`` element need to be removed from the pipeline. When
tracking is disabled, the metadata will include the object id as
``None`` for each detection.

Here is an example for enabling tracking for person detection pipeline
that uses Geti UDF.
``"pipeline": "multifilesrc loop=TRUE stop-index=0 location=/home/pipeline-server/resources/classroom.avi name=source ! h264parse ! decodebin ! queue max-size-buffers=10 ! videoconvert ! video/x-raw,format=BGR ! udfloader name=udfloader ! gvapython class=AddDetectionRoi function=process module=/home/pipeline-server/gvapython/detection/add_roi.py name=add_roi ! gvatrack tracking-type=short-term-imageless ! appsink name=destination"``

Specific metadata format is expected out of the UDF for it work with the
gvapython that adds ROIs. For more details on the ``gvapython`` script,
refer to :doc:`gva_python_script </IEdgeInsights/EdgeVideoAnalyticsMicroservice/user_scripts/gvapython/detection/README>`


Recommendations
~~~~~~~~~~~~~~~

-  Tracking accuracy is reliant on model’s accuracy in detecting
   objects. For skipped detections, other tracking types like
   short-term-imageless may be explored which doesn’t expect detection
   on every frame.

-  When running multiple pipelines with tracking enabled, the object ids
   would still sequentially start from 1 for each pipeline. It can be
   coupled with either pipeline tag or unique published topic
   identifying results associated with a specific pipeline.

Known Issues
~~~~~~~~~~~~

Currently, visualizer doesn’t show the object ids along with the
overlayed detection/labels.