PR: Port-Based Node-Graph

[KelSolaar]

Summary

This PR implements support for a port-based node-graph via 3 new classes:

• colour.utilities.Port
• colour.utilities.PortNode
• colour.utilities.PortGraph
• colour.utilities.For
• colour.utilities.ParallelForThread
• colour.utilities.ParallelForMultiProcess

The idea behind it is to be able to construct processing graph, initially with code but possibly using a UI in the future.

The API is as follows:

class NodeAdd(PortNode):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.description = "Perform the addition of the two input port values."

        self.add_input_port("a")
        self.add_input_port("b")
        self.add_output_port("output")

    def process(self):
        a = self.get_input("a")
        b = self.get_input("b")

        if a is None or b is None:
            return

        self._output_ports["output"].value = a + b

        self.dirty = False

class NodeMultiply(PortNode):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.description = (
            "Perform the multiplication of the two input port values."
        )

        self.add_input_port("a")
        self.add_input_port("b")
        self.add_output_port("output")

    def process(self):
        a = self.get_input("a")
        b = self.get_input("b")

        if a is None or b is None:
            return

        self._output_ports["output"].value = a * b

        self.dirty = False

node_add = NodeAdd()
node_add.set_input("a", 1)
node_add.set_input("b", 1)
node_multiply = NodeMultiply()
node_multiply.set_input("b", 2)

graph = PortGraph()

graph.add_node(node_add)
graph.add_node(node_multiply)

graph.connect(node_add, "output", node_multiply, "a")

graph.process()

print(node_multiply.get_output("output"))
graph.to_graphviz().draw("Graph.png", prog="dot")

This is obviously a simple and naive example but the immediate use case is for colour-hdri:

Preflight

Code Style and Quality

• [ ] Unit tests have been implemented and passed.
• [ ] Pyright static checking has been run and passed.
• [ ] Pre-commit hooks have been run and passed.
• [ ] New transformations have been added to the Automatic Colour Conversion Graph.
• [ ] New transformations have been exported to the relevant namespaces, e.g. colour, colour.models.

Documentation

• [ ] New features are documented along with examples if relevant.
• [ ] The documentation is Sphinx and numpydoc compliant.

[KelSolaar]

I will look at creating some subclasses that have an execution route instead of relying on the ports, that would allow for adding some control flow nodes, e.g., for loop and conditional branching.

[KelSolaar]

I have implemented support for looping, this can be done sequentially, via thread or multiprocessing using the colour.utilities.For, colour.utilities.ParallelForThread and colour.utilities.ParallelForMultiProcess nodes respectively.

[coveralls]

coverage: 99.833% (-0.1%) from 99.973% when pulling fc8c62459b49a367ce485c194df17bab594943ca on feature/graph into 233ee7283cbc676b262cdcfd13f376af6278375d on develop.

[tjdcs]

I'll have more time for a review on Sunday time in central US. Looks promising!