.. Copyright (c) 2021-2022, NVIDIA CORPORATION. All rights reserved. NVIDIA CORPORATION and its licensors retain all intellectual property and proprietary rights in and to this software, related documentation and any modifications thereto. Any use, reproduction, disclosure or distribution of this software and related documentation without an express license agreement from NVIDIA CORPORATION is strictly prohibited. ========================================= Getting Started ========================================= Overview ------------------------------ This guide helps you get familiar with the following: 1. Installing and running Graph Composer. 2. Load and run pre-built graphs. 3. Create your own graphs. We will start by first setting up the system and explain the basic layout of the Composer. Then, we will load, understand, and run a simple application. This will provide an understanding of how the Composer works. Finally, we will create a simple application without writing a single line of code. Installation ------------------- System Requirements ~~~~~~~~~~~~~~~~~~~~~~~ The table below lists the system requirements for Graph Composer Global Access (GA) release: .. csv-table:: :widths: 10, 20 Platform,"x86_64, Jetson \ :sup:`1`" OS,"Ubuntu 20.04, Windows 10 \ :sup:`2`" Python,3.8 CUDA,"11.6 (for x86_64), 11.4 (for Jetson)" GPU, "CUDA-capable GPU, iGPU \ :sup:`2,3`" DeepStream SDK,"6.1 (for DeepStream extensions)" Docker,>=19.03.3 \ :sup:`1` \ As :ref:`remote execution ` target only \ :sup:`2` \ (Alpha) With :ref:`remote execution ` only \ :sup:`3` \ (Alpha) Need Vulkan support (`Intel Iris Graphics 540 or later `_) Installing the Composer ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Graph Composer has separate packages for x86_64 and Jetson. These packages contains the following tools: .. csv-table:: :widths: 20, 20, 20 Tool, x86_64, Jetson Registry, 2.0.0, 2.0.0 Composer, 2.0.0, NA Container Builder, 2.0.0, NA Graph Execution Engine, 2.4.2, 2.4.2 1. Download Graph Composer Debian package for x86 from [`here `_] and Graph runtime for ARM from [`here `_] Graph development is currently supported only on x86. Graph Composer package for `arm64` can be used to deploy or execute graph on Jetson: * x86_64: :: graph_composer-2.0.0_amd64.deb * aarch64: :: graph_composer-2.0.0_arm64.deb 2. Install the package: :: sudo dpkg -i graph-composer-2.0.0-.deb This command will install all tools in the ``/opt/nvidia/graph-composer`` directory with links to tools in ``/usr/bin`` directory. You can access the tools without switching to the installation directory. After installation, check if the installation was successful using the following commands in a terminal: ``registry --help`` Output should look similar to the following: .. image:: /content/registry_help.png :align: center :width: 400 :alt: Registry Help Command ``container_builder --help`` Output should look similar to the following: .. image:: /content/container_builder_help.png :align: center :width: 500 :alt: Container Builder Help Command If you still don't see the components, check the :doc:`GraphComposer_FAQ` section. Note that GXF is installed as a part of the Graph Composer installation described above. Installing the Composer on Windows ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Download Graph Composer Windows Installer from [`here `_] On Windows, Graph Composer can be installed with ``graph_composer_installer.exe``. By default, it installs on ``C:\Program Files (x86)\NVIDIA Corporation\Graph Composer\``. You can always choose to select a different directory. It can be launched from the installtion directory by running ``composer.exe`` Installer also creates Desktop shortcut and Start Menu shortcut with the name ``Graph Composer`` Please note it will need administrative permissions to run the Composer. Getting Started with the Composer --------------------------------- To run the Graph Composer, run the command: ``composer`` This will open the following window: .. image:: /content/Composer_with_components.png :align: center :width: 600 :alt: Adding a Component to the Graph In the panel on the left, you should see components listed which are picked up from your ``registry``. If you don't see any components that means registry is not synced. You can sync the registry by using the Registry menu. After syncing the registry, you should see all the components listed. You can read more about registry in :doc:`GraphComposer_Registry` and about the related commands in :doc:`GraphComposer_Registry_CLI` Loading and Running an existing Graph ------------------------------------- Loading an existing Graph ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before we build our own graph, let's first run a sample graph. Download the `reference graph package `_ and install it using the command: ``dpkg -i deepstream-reference-graphs-6.1.deb``. This will install sample graphs and their required file in ``/opt/nvidia/deepstream/reference-graphs``. From your composer window, open ``/opt/nvidia/deepstream/deepstream-6.1/reference_graphs/deepstream-test1/deepstream-test1.yaml`` from ``Files -> Open Graph``. This will open all the components in the Graph Editor Window. You should be able to see all the components and how they are connected to each other. The window will look something like: .. image:: /content/Composer_test1_graph.png :align: center :width: 600 :alt: Sample Graph 1 .. _running_a_graph: Running a Graph ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To run a graph click on the Play button on the left panel. This will open a dialog where you can choose a graph file and the targer config file ``/opt/nvidia/deepstream/deepstream-6.1/reference_graphs/common/target_.yaml``. Optionally, you can also specify the details of a remote machine where you might want to run this graph. Once all the details are filled, click on ``Run``. This will execute the graph and you can see the output in an external terminal. Creating a Graph ------------------------------ Now, let's create a simple graph and run it. For this example we will create a simple `Ping` Graph using components present in the Sample Extension and Standard Extension. In this `Ping` Graph, we simply send a message from one entity to another periodically. It uses the following components: 1. Transmitter: - ``DoubleBufferTransmitter`` - This is a queue which is holds a message being transmitted. - ``PingTx`` - This component creates and publishes a message every time it's executed. - ``PeriodicSchedulingTerm`` - Scheduling Terms determine when to execute an entity in this case Transmitter. PeriodicSchedulingTerm is used to execute entities periodically. - ``CountSchedulingTerm`` - CountSchedulingTerm is used to stop the execution after a certain count. 2. Receiver: - ``DoubleBufferReceiver`` - This is a queue which hold the messages sent by other components. - ``PingRx`` - This component receives a message on DoubleBufferReceiver every time it's executed. - ``MessageAvailableSchedulingTerm`` - This Scheduling Term determines if a new message has arrived. 3. Scheduler: - ``GreedyScheduler`` - Scheduler determines the order in which components are executed. GreedyScheduler is a simple single-threaded scheduler which executes components one after another. - ``ManualClock`` - A clock used by Scheduler to track time. Follow the steps: 1. Add PingTx, PingRx and GreedyScheduler by dragging and dropping them from the components panel the graph window. 2. Add the rest of the components such as CountSchedulingTerm, PeriodicSchedulingTerm and MessageAvailableSchedulingTerm by dragging and dropping into the respective entity. 3. Now, right click on the signal in PingTx and click Create DoubleBufferTransmitter. Follow the same steps for PingRx's signal and GreedyScheduler's clock. We can create a graph by simply dragging and dropping components from the Component Panel and add more components to it. .. image:: /content/Composer_add_components.gif :align: center :width: 600 :alt: Adding a Component to the Graph After adding the components your graph will look like the image below: .. image:: /content/Composer_Ping_Example.png :align: center :width: 600 :alt: Create Ping Graph Now we make connections between components. For instance, you will have to connect a ``DoubleBufferTransmitter`` to a ``DoubleBufferReceiver`` to pass messages between them. ``PingTx/clock`` needs to be linked to ``GreedyScheduler/ManualClock``. These connections are made by creating an edge between the components as shown below: .. image:: /content/Composer_all_connections.gif :align: center :width: 600 :alt: Connecting the Components Finally, we have to set the required parameters for the components: - In ``PingRx/MessageAvailableSchedulingTerm``: set `min_size` to ``1`` - In ``PingTx/CountSchedulingTerm``: set `count` to ``5`` - In ``PingTx/PeriodicSchedulingTerm``: set `recess_period` to ``5`` Now you can save the graph using ``File -> Save Graph (as)``. This will create a ``yaml`` file with all the components and the connections. Finally, we can run this graph following the steps in :ref:`Running a Graph ` section. Once you run the graph you will see the output in the terminal where you can see five messages being sent and received.