core.rst

Core API

morphocut.core

This chapter describes the core module of MorphoCut.

Pipelines

The Pipeline is the main entry point for a MorphoCut application.

Pipeline

Nodes

A Node applies creates, updates or deletes stream objects.

Call

In simple cases, a call to a regular function can be recorded in a pipeline using :pyCall.

Call

Subclassing :pyNode

If a Node has multiple outputs or needs to change the stream, :pyNode has to be subclassed.

The subclass has no or any number of :py@Output <Output> decorators. :py@ReturnOutputs <ReturnOutputs> is used to turn :pyNode subclasses into a functions returning stream variables.

Overriding transform(...)

If the Node handles one object at a time, it is enough to implement a custom transform(...).

The parameter names have to correspond to attributes of the Node. :pyNode.transform_stream will then use introspection to call transform with the right parameter values.

@ReturnOutputs
@Output("bar")
@Output("baz")
class Foo(Node):
    """This class has two outputs."""
    def __init__(self, ham, spam):
        super().__init__()
        self.ham = ham
        self.spam = spam

    # This is automatically called by Node.transform_stream,
    # reading ham and spam from the stream
    # and introducing the result back into the stream.
    def transform(self, ham, spam):
        # ham and spam are raw values here
        return ham + spam, ham - spam

with Pipeline() as pipeline:
    # ham and spam are stream variables here
    ham = ...
    spam = ...
    bar, baz = Foo(ham, spam)

Overriding :pytransform_stream <Node.transform_stream>

If the Node has to change the stream in some way, :pyNode.transform_stream needs to be overridden.

@ReturnOutputs
@Output("bar")
@Output("baz")
class Foo(Node):
    """This class has two outputs."""
    def __init__(self, ham, spam):
        super().__init__()
        self.ham = ham
        self.spam = spam

    def transform_stream(self, stream):
        with closing_if_closable(stream):
            for obj in stream:
                # Retrieve raw values
                ham, spam = self.prepare_input(obj, ("ham", "spam"))

                # Remove objects from stream based on some condition
                if not ham:
                    continue

                # Append new values to the stream object:
                # bar = ham + spam
                # baz = ham - spam
                yield self.prepare_output(obj, ham + spam, ham - spam)

with Pipeline() as pipeline:
    # ham and spam are stream variables here
    ham = ...
    spam = ...
    bar, baz = Foo(ham, spam)

Node

Output

ReturnOutputs

Variables

Upon instanciation, Nodes return Variables that are used to identify values in stream objects.

Variable

Stream

Stream

StreamObject