deepstream_python_apps/apps/deepstream-segmentation

################################################################################
# Copyright (c) 2019-2020, NVIDIA CORPORATION. All rights reserved.
#
# Permission is hereby granted, free of charge, to any person obtaining a
# copy of this software and associated documentation files (the "Software"),
# to deal in the Software without restriction, including without limitation
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
# and/or sell copies of the Software, and to permit persons to whom the
# Software is furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
# DEALINGS IN THE SOFTWARE.
################################################################################

Prerequisites:
- DeepStreamSDK 5.1
- Python 3.6
- Gst-python
- NumPy package
- OpenCV package

To install required packages:
$ sudo apt update
$ sudo apt install python3-numpy python3-opencv -y

To run:
  $ python3 deepstream_segmentation.py <config_file> <jpeg/mjpeg stream> <FOLDER NAME TO SAVE FRAMES>

This document shall describe the sample deepstream-segmentation application.

It is meant for simple demonstration of how to use the various DeepStream SDK
elements in the pipeline and extract meaningful insights from a video stream such
as segmentation masks and respective color mapping for segmentation visualizaiton.

This sample creates instance of "nvinfer" element. Instance of
the "nvinfer" uses TensorRT API to execute inferencing on a model. Using a
correct configuration for a nvinfer element instance is therefore very
important as considerable behaviors of the instance are parameterized
through these configs.

For reference, here are the config files used for this sample :
1. The 4-class segmentation model configured through dstest_segmentation_config_semantic.txt 
2. The 2-class segmentation model configured through dstest_segmentation_config_industrial.txt

In this sample, we first create one instance of "nvinfer", referred as the pgie.
for semantic segmentation, it needs semantic model which can get 4 classes map,
including backgroud, car, person, bicycle. Then "nvsegvidsual" plugin chooses 4 different 
colors for them and to display. Similarlty for industrial segmentation, it needs industrial 
model which can only get defective area map. Later nvinfer element attach some MetaData 
to the buffer. By attaching the probe function at the end of the pipeline, one can 
extract meaningful information from this inference. Please refer 
the "tiler_src_pad_buffer_probe" function in the sample code. For details on the 
Metadata format, refer to the file "gstnvdsmeta.h". In this probe we demonstrate
extracting the masks and color mapping for segmentation visualization using opencv 
and numpy.