"""A Python package for autogenerating OpenVX C-code for calculation graphs.

Introduction
============
The main script parse_graph.py parses an OpenVX graph defined in yEd's graphml format,
to generate C-code for running the graph using the libs-vision GraphManager.

See the documentation of the graphml_parser submodule for documentation
on the required format of the yEd graph in order to be a valid graph
for the graph parser (which nodes, edges and metadata to use etc.).

The parse_graph.py script uses the graph_parser module and its
submodules to parse graph definition files generated by yEd,
which are stored in .graphml format.

Workflow when using the graph parser
------------------------------------

  1. Graphs are drawn in the graph editor yEd
     which saves them in XML format in .graphml files
  2. The Python script parse_graph.py is used to parse the .graphml file
     and autogenerate source code in C for setting up a "graph skeleton".
     The graph skeleton is a complete description of the graph
     except that the input and output images are not set
     (points to empty images), hence the name "skeleton".
  3. The graph_manager object can then use the autogenerated code to
     set up I/O images and parameters, and process the graph.

The graph_manager is a C object that is designed to handle
the autogenerated code from the graph parser.
It is designed to be user friendly and hide a lot of tedious
and error-prone details about memory management and handling
of I/O images etc from the user. It expects certain functions
to be generated by the parser.
The graph parser will generate C files named exactly as the yEd .graphml file name,
except the extension .graphml is changed to .c and .h respectively.
One registers a graph for the graph manager by passing a function pointer to a graph registration function.
In order to make the naming easier to remember, the graph parser names the required function
exactly as the C-file name, without the file type extension.
The graph manager expects this function to provide it with a I{create}, and a I{set I/O images} function,
as well as an optional I{set debug images} function.

If the yEd file is named graph_name.graphml, the graph parser will thus generate functions with the following names:

  - graph_name\n
  - graph_name_create\n
  - graph_name_set_io_images\n

and a I{set debug images} function (only generated if any image node is defined as a debug image node):
  - graph_name_set_debug_images

If the rules for how to draw the graphs in yEd and how to annotate the graph
with metadata are followed, the generated C code will automatically
get the correct formatting of these functions, as expected by the graph manager.

Note that the OpenVX standard might mention the concept of a graph manager as well.
The graph manager here is a higher level concept that is NOT part
of the OpenVX standard, and the two concepts should not be confused with each other.


Updating the graph parser with new OpenVX calculation nodes
-----------------------------------------------------------

The first time a new function node is ever being used, the algorithm developer
will need to add some details about the parsing of that function node.
The update process is streamlined to be as minimal and easy to understand
as possible.

  1. Add a .py file in the node_parse_info submodule. The file should be
     named after the node and contain information about how to parse the node.
  2. Add parameter and naming data to the file function_node_library.py
     in the node_parse_info submodule. The needed information can be
     extracted directly from the OpenVX API specification.

Further overview documentation
------------------------------

  1. L{The I{parse_graph} module<parse_graph>}: Information about the top level parse graph script that uses the graphml parser framework.
  2. L{The I{graphml_parser} package<graphml_parser>}: Information on the metadata the parser expects from the yEd graph definitions.
  3. L{The I{node_parse_info} package<node_parse_info>}: Contains further details on how to add new types of nodes to the parser framework.
"""

#This file also serves as a hook for package-initialization-time actions

"""A Python package for autogenerating OpenVX C-code for calculation graphs.

Introduction
============
The main script parse_graph.py parses an OpenVX graph defined in yEd's graphml format,
to generate C-code for running the graph using the libs-vision GraphManager.

See the documentation of the graphml_parser submodule for documentation
on the required format of the yEd graph in order to be a valid graph
for the graph parser (which nodes, edges and metadata to use etc.).

The parse_graph.py script uses the graph_parser module and its
submodules to parse graph definition files generated by yEd,
which are stored in .graphml format.

Workflow when using the graph parser
------------------------------------

  1. Graphs are drawn in the graph editor yEd
     which saves them in XML format in .graphml files
  2. The Python script parse_graph.py is used to parse the .graphml file
     and autogenerate source code in C for setting up a "graph skeleton".
     The graph skeleton is a complete description of the graph
     except that the input and output images are not set
     (points to empty images), hence the name "skeleton".
  3. The graph_manager object can then use the autogenerated code to
     set up I/O images and parameters, and process the graph.

The graph_manager is a C object that is designed to handle
the autogenerated code from the graph parser.
It is designed to be user friendly and hide a lot of tedious
and error-prone details about memory management and handling
of I/O images etc from the user. It expects certain functions
to be generated by the parser.
The graph parser will generate C files named exactly as the yEd .graphml file name,
except the extension .graphml is changed to .c and .h respectively.
One registers a graph for the graph manager by passing a function pointer to a graph registration function.
In order to make the naming easier to remember, the graph parser names the required function
exactly as the C-file name, without the file type extension.
The graph manager expects this function to provide it with a I{create}, and a I{set I/O images} function,
as well as an optional I{set debug images} function.

If the yEd file is named graph_name.graphml, the graph parser will thus generate functions with the following names:

  - graph_name\n
  - graph_name_create\n
  - graph_name_set_io_images\n

and a I{set debug images} function (only generated if any image node is defined as a debug image node):
  - graph_name_set_debug_images

If the rules for how to draw the graphs in yEd and how to annotate the graph
with metadata are followed, the generated C code will automatically
get the correct formatting of these functions, as expected by the graph manager.

Note that the OpenVX standard might mention the concept of a graph manager as well.
The graph manager here is a higher level concept that is NOT part
of the OpenVX standard, and the two concepts should not be confused with each other.


Updating the graph parser with new OpenVX calculation nodes
-----------------------------------------------------------

The first time a new function node is ever being used, the algorithm developer
will need to add some details about the parsing of that function node.
The update process is streamlined to be as minimal and easy to understand
as possible.

  1. Add a .py file in the node_parse_info submodule. The file should be
     named after the node and contain information about how to parse the node.
  2. Add parameter and naming data to the file function_node_library.py
     in the node_parse_info submodule. The needed information can be
     extracted directly from the OpenVX API specification.

Further overview documentation
------------------------------

  1. L{The I{parse_graph} module<parse_graph>}: Information about the top level parse graph script that uses the graphml parser framework.
  2. L{The I{graphml_parser} package<graphml_parser>}: Information on the metadata the parser expects from the yEd graph definitions.
  3. L{The I{node_parse_info} package<node_parse_info>}: Contains further details on how to add new types of nodes to the parser framework.
"""

#This file also serves as a hook for package-initialization-time actions

A Python package for autogenerating OpenVX C-code for calculation graphs.  Introduction ============ The main script parse_graph.py parses an OpenVX graph defined in yEd's graphml format, to generate C-code for running the graph using the libs-vision GraphManager.  See the documentation of the graphml_parser submodule for documentation on the required format of the yEd graph in order to be a valid graph for the graph parser (which nodes, edges and metadata to use etc.).  The parse_graph.py script uses the graph_parser module and its submodules to parse graph definition files generated by yEd, which are stored in .graphml format.  Workflow when using the graph parser ------------------------------------    1. Graphs are drawn in the graph editor yEd      which saves them in XML format in .graphml files   2. The Python script parse_graph.py is used to parse the .graphml file      and autogenerate source code in C for setting up a "graph skeleton".      The graph skeleton is a complete description of the graph      except that the input and output images are not set      (points to empty images), hence the name "skeleton".   3. The graph_manager object can then use the autogenerated code to      set up I/O images and parameters, and process the graph.  The graph_manager is a C object that is designed to handle the autogenerated code from the graph parser. It is designed to be user friendly and hide a lot of tedious and error-prone details about memory management and handling of I/O images etc from the user. It expects certain functions to be generated by the parser. The graph parser will generate C files named exactly as the yEd .graphml file name, except the extension .graphml is changed to .c and .h respectively. One registers a graph for the graph manager by passing a function pointer to a graph registration function. In order to make the naming easier to remember, the graph parser names the required function exactly as the C-file name, without the file type extension. The graph manager expects this function to provide it with a I{create}, and a I{set I/O images} function, as well as an optional I{set debug images} function.  If the yEd file is named graph_name.graphml, the graph parser will thus generate functions with the following names:    - graph_name\n   - graph_name_create\n   - graph_name_set_io_images\n  and a I{set debug images} function (only generated if any image node is defined as a debug image node):   - graph_name_set_debug_images  If the rules for how to draw the graphs in yEd and how to annotate the graph with metadata are followed, the generated C code will automatically get the correct formatting of these functions, as expected by the graph manager.  Note that the OpenVX standard might mention the concept of a graph manager as well. The graph manager here is a higher level concept that is NOT part of the OpenVX standard, and the two concepts should not be confused with each other.   Updating the graph parser with new OpenVX calculation nodes -----------------------------------------------------------  The first time a new function node is ever being used, the algorithm developer will need to add some details about the parsing of that function node. The update process is streamlined to be as minimal and easy to understand as possible.    1. Add a .py file in the node_parse_info submodule. The file should be      named after the node and contain information about how to parse the node.   2. Add parameter and naming data to the file function_node_library.py      in the node_parse_info submodule. The needed information can be      extracted directly from the OpenVX API specification.  Further overview documentation ------------------------------    1. L{The I{parse_graph} module<parse_graph>}: Information about the top level parse graph script that uses the graphml parser framework.   2. L{The I{graphml_parser} package<graphml_parser>}: Information on the metadata the parser expects from the yEd graph definitions.   3. L{The I{node_parse_info} package<node_parse_info>}: Contains further details on how to add new types of nodes to the parser framework. #This file also serves as a hook for package-initialization-time actions