depthai-pipeline-graph 0.0.7
Tool to create graphs oh DepthAI pipelines
Requires Python: >=3.6

# DepthAI Pipeline Graph

This version is compatible with DepthAI version 3.3.0 or higher. For compatibility with older depthai versions use branch `main_old`.

A tool that dynamically creates graphs of [DepthAI pipelines](https://docs.luxonis.com/projects/api/en/latest/components/pipeline/). It is an **ideal tool for debugging**, as it provides insight into the pipeline and its inner workings. The original author of this tool is [geaxgx](https://github.com/geaxgx), Luxonis has updated some features and added pipeline state information.

![Detection network demo](media/pipeline_graph.png)

## How it works ?
In the DepthAI context, a pipeline is a collection of nodes and links between them.
When the pipeline is built the pipeline configuration gets serialized to JSON. If the environment variable `DEPTHAI_LEVEL` is set to `debug` before running your code, the content of the JSON config is printed to the console like below:
```
[2022-06-01 16:47:33.721] [debug] Schema dump: {"connections":[{"node1Id":8,"node1Output":"passthroughDepth","node1OutputGroup":"","node2Id":10
,"node2Input":"in","node2InputGroup":""},{"node1Id":8,"node1Output":"out","node1OutputGroup":"","node2Id":9,"node2Input":"in","node2InputGroup":""},{"node1Id":7,"node1Output":"depth","node1OutputGroup":"","node2Id":8,"node2Input":"inputDepth","node2InputGroup":""},{"node1Id":0,"node1Output":"preview","node1OutputGroup":"","node2Id":8,"node2Input":"in","node2InputGroup":""},{"node1Id":0,"node1Output":"preview","node1OutputGroup":"","node2Id":3,"node2Input":"inputImage","node2InputGroup":""}, 
...
```

If the environment variable is set to `trace`, pipeline state information is also printed to the console, providing insights into the status of each node and port in the pipeline.

By analyzing the printed schema dump, it is then possible to retrieve the nodes of the pipeline and their connections. That's exactly what the tool `pipeline_graph` is doing:

* it sets  `DEPTHAI_LEVEL` to `trace`,
* it runs your code,
* it catches the schema dump in the ouput stream of the code (by default the tool then terminates the process running your code),
* it parses the schema dump and creates the corresponding graph using the NodeGraphQt framework,
* it updates the graph with the pipeline state information (if available).

<br>




## Install

```
pip install git+https://github.com/luxonis/depthai_pipeline_graph.git
```
If not already present, the command above will install the python module Qt.py. Qt.py enables you to write software that runs on any of the 4 supported bindings - PySide2, PyQt5, PySide and PyQt4. If none of these binding is installed, you will get an error message when running `pipeline_graph`: 
```
ImportError: No Qt binding were found. 
```
If you don't have a preference for any particular binding, you can just choose to install PySide2:
```
pip install PySide2
```


## Run

Once the installation is done, you have only one command to remember and use: `pipeline_graph`
```
> pipeline_graph -h
usage: pipeline_graph [-h] {run,from_file,load} ...

positional arguments:
  {run,from_file,load}  Action
    run                 Run your depthai program to create the corresponding
                        pipeline graph
    from_file           Create the pipeline graph by parsing a file containing
                        the schema (log file generated with
                        DEPTHAI_LEVEL=debug or Json file generated by
                        pipeline.serializeToJSon())
    load                Load a previously saved pipeline graph

optional arguments:
  -h, --help            show this help message and exit
```

There are 3 actions/modes available: `run`, `from_file` and `load`

### 1) pipeline_graph run


```
> pipeline_graph run -h
usage: pipeline_graph run [-h] [-dnk] [-var] [-p PIPELINE_NAME] [-v] command

positional arguments:
  command               The command with its arguments between ' or " (ex:
                        python script.py -i file)

optional arguments:
  -h, --help            show this help message and exit
  -dnk, --do_not_kill   Don't terminate the command when the schema string has
                        been retrieved
  -var, --use_variable_names
                        Use the variable names from the python code to name
                        the graph nodes
  -p PIPELINE_NAME, --pipeline_name PIPELINE_NAME
                        Name of the pipeline variable in the python code
                        (default=pipeline)
  -v, --verbose         Show on the console the command output

```

As an example, let's say that the usual command to run your program is:
```
python main.py -cam
```
To build the corresponding pipeline graph, you simply use the following command (the quotes are important):
```
pipeline_graph "python main.py -cam"
```
Note that as soon as the `pipeline_graph` program has catched the schema dump, your program is forced to be terminated. It means that your program will possibly not have time to display any windows (if it is something it is normally doing).
If you prefer to let your program continue its normal job, use the "-dnk" or "--do_not_kill" argument:
```
pipeline_graph "python main.py -cam" -dnk
```
Note how the `pipeline_graph` own arguments are placed outside the pair of quotes, whereas your program arguments are inside. 
<br>When using the `-dnk` option, the pipeline graph is displayed only after you quit your program.

**Nodes**

The label inside the node is formatted as \[(G:XXXms,P:XXXms,S:XXXms,T:XXXms)\] (XXX is a zero-padded number):

* G: average time spent getting input messages per loop
* P: average time spent processing per loop (equals total - send - get)
* S: average time spent sending output messages per loop
* T: average total time per loop

The node name is formatted as *name*(*id*)\[*state*\] where:

* *name* is the node type (ex: ColorCamera, NeuralNetwork, XLinkOut, etc.)
* *id* is the unique node identifier
* *state* is the current state of the node:
  * I: inactive
  * G: getting inputs
  * P: processing
  * S: sending outputs

**Ports**

For the input ports, the shape represents the blocking state of the port (square for blocking, round for non-blocking). The color of the input and output ports represents their status:

* Gray: inactive port (no data transferred yet)
* Green: idle port (ready to receive / send data)
* Yellow: busy port (input is waiting for data / output is sending data)
* Red: blocked input port (the input queue is full and an output is trying to send data to it)

The label of input ports is formatted as \[*fps* | *num* / *max*\] *name*, where:

* *fps* is the rolling average frame rate of data received on that port (or "?" if no data has been received yet)
* *num* is the number of messages currently waiting in the input queue (or "?" if no data has been received yet)
* *max* is the maximum size of the input queue
* *name* is the name of the port

The label of output ports is formatted as \[*fps*\] *name*.

![Pipeline graph node](media/pipeline_graph_node.png)

### 2) pipeline_graph from_file
Use this command when the "pipeline_graph run" method fails (for instance, if your application is executed as a subprocess) or you don't have access to the application code (so you cannot run it) but the owner of the code send you a log file containing an execution trace.<br>
Two type of files can be parsed by this command:
* a log file generated by setting the environment variable `DEPTHAI_LEVEL` to `debug`, then running the code and saving the standard output: the tool will parse the log file exactly like it does with the "pipeline_graph run" method, looking for the "Schema dump:" string;
* a Json file generated by a call to [pipeline.serializeToJson()](https://docs.luxonis.com/projects/api/en/latest/references/python/#depthai.Pipeline.serializeToJson).

```
> pipeline_graph from_file -h
usage: pipeline_graph from_file [-h] schema_file

positional arguments:
  schema_file  Path of the file containing the schema

optional arguments:
  -h, --help   show this help message and exit

```

### 3) pipeline_graph load
Use this command to open and edit a previously saved pipeline graph.

```
> pipeline_graph load -h
usage: pipeline_graph load [-h] json_file

positional arguments:
  json_file   Path of the .json file

optional arguments:
  -h, --help  show this help message and exit

```

## Credits
* [NodeGraphQt](https://github.com/jchanvfx/NodeGraphQt) by jchanvfx.