PR: Port-Based Node-Graph

[KelSolaar]

Summary

This PR implements support for a port-based node-graph via 6 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.835% (-0.1%) from 99.973%
when pulling 91b88de on feature/graph
into e217731 on develop.

[tjdcs]

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

[KelSolaar]

I'm going to merge this one! The feature is at a point where it works really well. What might happen in the future though is that we will extract this in its own repository but for now here is good as colour is the lowest common denominator in our projects.