# Heron
Heron is an open source software conceived as an experiment (and general data) pipeline implementation tool. It allows users to realise their conceptual experimental designs such that the final result, i.e. the implementation running the experiment, visually and structurally bears a significant resemblance to its mental schema, i.e. the idea of the experiment in the experimenter’s imagination.
Heron combines a Node based experiment designer with a Python API allowing users to quicly construct and add their own Nodes. It fully obfuscates the Node communication from the user and offers seamless communication between separate machines running different operating systems.
A more thorough description of both why Heron exists in the first place and some info on how to use it can be found in [this document](https://medium.com/@gdimitri/heron-a-hybrid-approach-to-data-pipelines-in-python-aa7719fe8f2e).
The manual is [here](https://heron-42ad.readthedocs.io/en/latest/index.html).
# Videos and Tutorials
A summer 2022 talk at the Sainsbury Wellcome Centre introducing Heron:
https://www.youtube.com/watch?v=o6Pz-1uaJjY
A quick overview of using Heron through an example of putting together a pipeline involving Single Board Computers, Deep Convolutional Networks and a game of Snake.
https://www.youtube.com/watch?v=dRXeFBYG50Q
## Introduction
Heron is a Python only graphical editor designed to initiate, connect and orchestrate multiple processes, passing data between each other, potentially running on multiple computers. Each process is graphically represented as a node with inputs and outputs. Connecting an output of one process to the input of another will result in the data generated by the output process to be passed to the input one, subsequently triggering the input processes functionality.
Heron has originally been conceptualised as a framework to allow modular and fast experimental setup. It is designed to connect multiple pieces of hardware with analysis and data collection code in a versatile / experiment specific matter. Its main goal is to abstract away the need to pass data through the different parts of a pipeline with specific data collection and on the fly analysis requirements, an effort which more often than not, results in single use, spaghetti code.
Heron is not another visual programming language. It is just a graphical abstraction of the way individual pieces of code, each running in its own process, communicate with each other in an experimental pipeline. The code that does the actual work is Python code and the user is expected to construct their own pieces of code (that can be trivially wrapped into the code necessary to have them represented as Heron nodes).
Here is an example of the Heron editor running a simple pipeline
More information on the parts of the Heron editor and its use see the Use paragraph.
## Installation
One way is pip:
```
python -m pip install heron-42ad
```
Yet, Heron does not require any type of installation. One can just download the repo, put it somewhere and then run the editor.py script found in the Heron/Heron/gui folder.
Important note. The whole of the Heron repo must be found in all the computers that run nodes in a pipeline. The editor will only run in one of the computers but the whole repo needs to be present in all computers (since this defines Heron's communication protocol). Any code that runs in a machine separate to the computer running the editor must be part of the Heron directory structure wrapped appropriately in the code that creates the Heron nodes.
The Heron repository comes installed with a small number of Nodes that are generic enough to be useful to most users. This set will over time increase. Yet, for more specialised Nodes Heron allows users to create in Heron's folder structure symbolic links to any directory on their hard disks that has a set of Heron Nodes. For a user to do this they will either have to create their own Nodes or download from an online repository hub (e.g. GitHub) a set of Nodes. To begin with look into https://github.com/Heron-Repositories. Once the code for one or more Nodes is on a user's hard disk then one should access the Operations button on the toolbar, press Add a new Operations Folder (as Symbolic Link from Existing Repo) button and navigate to the folder that carries the Sources, Transforms and/or Sinks folders inside of which the new Nodes exist. That will create a symbolic link of the correct directory strucre inside Heron's folder structure and Heron will from that point on be able to use the new Nodes. If one wants to remove the Nodes all they have to do is delete the symbolic link from Heron's Operations/XXX directory (where XXX = Sources or Transforms or Sinks). That will not affect the actual repository of the new Nodes.
## Requirements.
The library requirements of Heron are:
python >=3.11
pyzmq >= 22.x
numpy
pandas
dearpygui >= 1.2
paramiko
tornado
psutil
pyinput
pyserial
h5py
Unfortunately the in-Node visualisation capabilities and a good few Nodes (Visualiser, Cameras, OpenCV filters) repy on opencv = 4.x (3.x should work but not tested). Sorry about that! In the future there will be an effort to remove basic dependency on opencv but for now, it is what it is.
At the time of writting (Feb. 2022) conda will not install opencv for python > 3.8, so if you are using python 3.11 or newer you have to install opencv through pip.
If you use conda then dearpygui has to also be installed by pip (no conda packages yet).
So once you have a conda environment up and running (and you have added the conda-forge channel to your config as mentioned here https://ostechnix.com/enable-conda-forge-channel-for-conda-package-manager/) and you are in the environment in your command prompt you need to do the following:
```
conda install numpy
conda install pandas
conda install tornado
conda install pyzmq
conda install paramiko
conda install psutil
pip install dearpygui
pip install opencv-python
```
To test that everything works start Heron. That is done by running
```python folder_of_Heron/Heron/gui/editor.py```
Other libraries, which are used in specific Nodes only, can be installed as needs be. One can check the import statements of the Worker scripts of the specific Operations to see what libraries they import.
For optional libraries that are called by often used Nodes do
```
conda install scipy
conda install h5py
conda install pynput
conda install pyserial
```
## Use
The left hand side table in the editor is a list of all available nodes. The user clicks on the ones they need and then proceeds to connect the outputs to the inputs and sets up the parameters values. Once this is done, the user starts the Graph that has been generated. The result is the initialisation of a series of processes (double the number of nodes plus one) which then pass data between them as the connectivity of their nodes prescribes.
There are three types of nodes:
The Source nodes which are meant to bring data from the outside world into the pipeline. Examples of these are cameras, microphones, data acquisition devices and in general any type of hardware that will generate data. For example, in the pipeline shown above, there is a single Source node live capturing camera frames. Source nodes have only outputs.
Then there are the Transform nodes which grab data from one of their inputs, transform it and then pass it to their output. Heron supports both one output to one input and one output to many inputs connectivity. It also supports Nodes with multiple inputs and multiple outputs. In the above example, each captured frame is passed through a canny filter.
Finally there are Sink nodes which only have inputs and which are meant as final saving points for the data. In the above example this is the Save FFMPEG video which takes the canny transformed frame and adds it to a video file (through running ffmpeg).
In the future there will be Kernel nodes with no inputs or outputs (self sufficient processes that do stuff without requiring input or generating output).
## Heron protocol
The below picture gives the overview of the communication protocol Heron uses.
Raw data
{
"_id": null,
"home_page": "https://github.com/Heron-Repositories/Heron",
"name": "Heron-42ad",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "Node-based, experiment",
"author": "George Dimitriadis",
"author_email": "George Dimitriadis <gdimitri@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/fa/22/4019637db4747cfc29fd6654cdc97b24dff684a59800ba07fde7c92d9ecc/heron_42ad-0.8.1.tar.gz",
"platform": null,
"description": "# Heron\r\n\r\nHeron is an open source software conceived as an experiment (and general data) pipeline implementation tool. It allows users to realise their conceptual experimental designs such that the final result, i.e. the implementation running the experiment, visually and structurally bears a significant resemblance to its mental schema, i.e. the idea of the experiment in the experimenter\u2019s imagination.\r\n\r\nHeron combines a Node based experiment designer with a Python API allowing users to quicly construct and add their own Nodes. It fully obfuscates the Node communication from the user and offers seamless communication between separate machines running different operating systems.\r\n\r\nA more thorough description of both why Heron exists in the first place and some info on how to use it can be found in [this document](https://medium.com/@gdimitri/heron-a-hybrid-approach-to-data-pipelines-in-python-aa7719fe8f2e).\r\n\r\nThe manual is [here](https://heron-42ad.readthedocs.io/en/latest/index.html).\r\n\r\n# Videos and Tutorials\r\n\r\nA summer 2022 talk at the Sainsbury Wellcome Centre introducing Heron: \r\nhttps://www.youtube.com/watch?v=o6Pz-1uaJjY\r\n\r\nA quick overview of using Heron through an example of putting together a pipeline involving Single Board Computers, Deep Convolutional Networks and a game of Snake.\r\nhttps://www.youtube.com/watch?v=dRXeFBYG50Q\r\n\r\n## Introduction\r\n\r\nHeron is a Python only graphical editor designed to initiate, connect and orchestrate multiple processes, passing data between each other, potentially running on multiple computers. Each process is graphically represented as a node with inputs and outputs. Connecting an output of one process to the input of another will result in the data generated by the output process to be passed to the input one, subsequently triggering the input processes functionality.\r\n\r\nHeron has originally been conceptualised as a framework to allow modular and fast experimental setup. It is designed to connect multiple pieces of hardware with analysis and data collection code in a versatile / experiment specific matter. Its main goal is to abstract away the need to pass data through the different parts of a pipeline with specific data collection and on the fly analysis requirements, an effort which more often than not, results in single use, spaghetti code.\r\n\r\nHeron is not another visual programming language. It is just a graphical abstraction of the way individual pieces of code, each running in its own process, communicate with each other in an experimental pipeline. The code that does the actual work is Python code and the user is expected to construct their own pieces of code (that can be trivially wrapped into the code necessary to have them represented as Heron nodes).\r\n\r\nHere is an example of the Heron editor running a simple pipeline\r\n\r\n\r\n\r\n\r\n\r\nMore information on the parts of the Heron editor and its use see the Use paragraph.\r\n\r\n\r\n## Installation\r\n\r\nOne way is pip:\r\n\r\n```\r\npython -m pip install heron-42ad\r\n```\r\n\r\nYet, Heron does not require any type of installation. One can just download the repo, put it somewhere and then run the editor.py script found in the Heron/Heron/gui folder.\r\n\r\nImportant note. The whole of the Heron repo must be found in all the computers that run nodes in a pipeline. The editor will only run in one of the computers but the whole repo needs to be present in all computers (since this defines Heron's communication protocol). Any code that runs in a machine separate to the computer running the editor must be part of the Heron directory structure wrapped appropriately in the code that creates the Heron nodes.\r\n\r\nThe Heron repository comes installed with a small number of Nodes that are generic enough to be useful to most users. This set will over time increase. Yet, for more specialised Nodes Heron allows users to create in Heron's folder structure symbolic links to any directory on their hard disks that has a set of Heron Nodes. For a user to do this they will either have to create their own Nodes or download from an online repository hub (e.g. GitHub) a set of Nodes. To begin with look into https://github.com/Heron-Repositories. Once the code for one or more Nodes is on a user's hard disk then one should access the Operations button on the toolbar, press Add a new Operations Folder (as Symbolic Link from Existing Repo) button and navigate to the folder that carries the Sources, Transforms and/or Sinks folders inside of which the new Nodes exist. That will create a symbolic link of the correct directory strucre inside Heron's folder structure and Heron will from that point on be able to use the new Nodes. If one wants to remove the Nodes all they have to do is delete the symbolic link from Heron's Operations/XXX directory (where XXX = Sources or Transforms or Sinks). That will not affect the actual repository of the new Nodes.\r\n\r\n## Requirements. \r\n\r\nThe library requirements of Heron are:\r\n\r\npython >=3.11\r\n\r\npyzmq >= 22.x\r\n\r\nnumpy\r\n\r\npandas\r\n\r\ndearpygui >= 1.2\r\n\r\nparamiko\r\n\r\ntornado\r\n\r\npsutil\r\n\r\npyinput\r\n\r\npyserial\r\n\r\nh5py\r\n\r\nUnfortunately the in-Node visualisation capabilities and a good few Nodes (Visualiser, Cameras, OpenCV filters) repy on opencv = 4.x (3.x should work but not tested). Sorry about that! In the future there will be an effort to remove basic dependency on opencv but for now, it is what it is.\r\nAt the time of writting (Feb. 2022) conda will not install opencv for python > 3.8, so if you are using python 3.11 or newer you have to install opencv through pip.\r\n\r\nIf you use conda then dearpygui has to also be installed by pip (no conda packages yet). \r\n\r\nSo once you have a conda environment up and running (and you have added the conda-forge channel to your config as mentioned here https://ostechnix.com/enable-conda-forge-channel-for-conda-package-manager/) and you are in the environment in your command prompt you need to do the following:\r\n```\r\nconda install numpy\r\nconda install pandas\r\nconda install tornado\r\nconda install pyzmq\r\nconda install paramiko\r\nconda install psutil\r\n\r\npip install dearpygui\r\npip install opencv-python\r\n```\r\n\r\nTo test that everything works start Heron. That is done by running\r\n```python folder_of_Heron/Heron/gui/editor.py```\r\n\r\nOther libraries, which are used in specific Nodes only, can be installed as needs be. One can check the import statements of the Worker scripts of the specific Operations to see what libraries they import.\r\n\r\nFor optional libraries that are called by often used Nodes do\r\n```\r\nconda install scipy\r\nconda install h5py\r\nconda install pynput\r\nconda install pyserial\r\n```\r\n\r\n## Use\r\n\r\nThe left hand side table in the editor is a list of all available nodes. The user clicks on the ones they need and then proceeds to connect the outputs to the inputs and sets up the parameters values. Once this is done, the user starts the Graph that has been generated. The result is the initialisation of a series of processes (double the number of nodes plus one) which then pass data between them as the connectivity of their nodes prescribes.\r\n\r\nThere are three types of nodes:\r\n\r\nThe Source nodes which are meant to bring data from the outside world into the pipeline. Examples of these are cameras, microphones, data acquisition devices and in general any type of hardware that will generate data. For example, in the pipeline shown above, there is a single Source node live capturing camera frames. Source nodes have only outputs.\r\n\r\nThen there are the Transform nodes which grab data from one of their inputs, transform it and then pass it to their output. Heron supports both one output to one input and one output to many inputs connectivity. It also supports Nodes with multiple inputs and multiple outputs. In the above example, each captured frame is passed through a canny filter.\r\n\r\nFinally there are Sink nodes which only have inputs and which are meant as final saving points for the data. In the above example this is the Save FFMPEG video which takes the canny transformed frame and adds it to a video file (through running ffmpeg).\r\n\r\nIn the future there will be Kernel nodes with no inputs or outputs (self sufficient processes that do stuff without requiring input or generating output).\r\n\r\n\r\n## Heron protocol\r\n\r\nThe below picture gives the overview of the communication protocol Heron uses.\r\n\r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Heron Node baed experiment designer",
"version": "0.8.1",
"project_urls": {
"Documentation": "https://heron-42ad.readthedocs.io/en/latest/index.html",
"Homepage": "https://github.com/Heron-Repositories/Heron/tree/main",
"Issues": "https://github.com/Heron-Repositories/Heron/issues"
},
"split_keywords": [
"node-based",
" experiment"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2ae848d3faaebcaa35a1b585eefd78931cefa36330478e64dd09da6bb0210acd",
"md5": "80170a4f6bb2376ee0c18e97499e28e0",
"sha256": "35d8774c679fcb739a8fbce9fe78cdafa1ff62bbe37306ea19b77d5113207b59"
},
"downloads": -1,
"filename": "Heron_42ad-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "80170a4f6bb2376ee0c18e97499e28e0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 10015017,
"upload_time": "2024-07-04T09:12:41",
"upload_time_iso_8601": "2024-07-04T09:12:41.289276Z",
"url": "https://files.pythonhosted.org/packages/2a/e8/48d3faaebcaa35a1b585eefd78931cefa36330478e64dd09da6bb0210acd/Heron_42ad-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fa224019637db4747cfc29fd6654cdc97b24dff684a59800ba07fde7c92d9ecc",
"md5": "9a258938bafe0991aeaa6cc8f28d4f47",
"sha256": "39070c747685b98c10c7416367094c076841ad0cd8bb418ae428aedae540fd65"
},
"downloads": -1,
"filename": "heron_42ad-0.8.1.tar.gz",
"has_sig": false,
"md5_digest": "9a258938bafe0991aeaa6cc8f28d4f47",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 9955403,
"upload_time": "2024-07-04T09:12:55",
"upload_time_iso_8601": "2024-07-04T09:12:55.909519Z",
"url": "https://files.pythonhosted.org/packages/fa/22/4019637db4747cfc29fd6654cdc97b24dff684a59800ba07fde7c92d9ecc/heron_42ad-0.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-04 09:12:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Heron-Repositories",
"github_project": "Heron",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "heron-42ad"
}
JSON
