################################################################################
# SPDX-FileCopyrightText: Copyright (c) 2020-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
################################################################################

Prerequisites:
- DeepStreamSDK 7.1
- Python 3.10
- Gst-python
- NumPy package
- OpenCV package

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

To run:
  $ python3 deepstream-opticalflow.py <uri1> [uri2] ... [uriN] <output_folder>
e.g.
  $ python3 deepstream-opticalflow.py file:///opt/nvidia/deepstream/deepstream-<version>/samples/streams/sample_720p.mp4 output


This document shall describe about the sample deepstream-nvof-app application.

Optical Flow (nvof gstreamer plugin):
NVIDIA GPUs, starting with the Nvidia GPU Turing generation and Jetson Xavier generation,
contain a hardware accelerator for computing optical flow. Optical flow vectors are
useful in various use cases such as object detection and tracking, video frame rate
up-conversion, depth estimation, stitching, and so on.
The gst-nvof plugin collects a pair of NV12 images and passes it to the low-level
optical flow library. The low-level library returns a map of flow vectors between
the two frames as its output. The map of flow vectors is encapsulated in an
NvOpticalFlowMeta structure and is added as a user meta for each frame in the batch
using nvds_add_user_meta_to_frame() function.

Optical Flow Visualization (nvofvisual gstreamer plugin):
The Gst-nvofvisual plugin is useful for visualizing motion vector data.
The visualization method is simmilar to the OpenCV reference source code in:
https://github.com/opencv/opencv/blob/master/samples/gpu/optical_flow.cpp
The plugin solves the optical flow problem by computing the magnitude and direction of
optical flow from a two-channel array of flow vectors.
It then visualizes the angle (direction) of flow by hue and the distance (magnitude) of
flow by value of Hue Saturation Value (HSV) color representation.
The strength of HSV is always set to a maximum of 255 for optimal visibility.

This sample creates instance of "nvof" & "nvofvisual" gstreamer elements.

1) nvof element generates the MV (motion vector) data and attaches as
   user-meta data.

2) nvofvisual element is used for visualizing the MV data using pre-defined
   color wheel matrix.

3) It then obtains the flow vectors and demonstrates visualization of these 
   flow vectors using OpenCV. The obtained image is different from the visualization 
   plugin output in color, in order to demonstrate the difference.