Graphics blocks

Graphics blocks

This page describes the contract for writing new graphics blocks that inherit from GraphicsBlock.

Superclass contract

A graphics block should:

• Inherit from GraphicsBlock
• Call super().start(simstate) at the top of start
• Call super().step(t, inports) at the end of step
• Usually not override done unless it has custom cleanup

After super().start(simstate) returns and graphics are enabled:

• self.fig is valid and ready to use
• self.ax is created by the base class for both 2D and 3D blocks
• key handling is connected (q closes current window, Q closes all and requests stop)
• movie setup is automatic when movie=... is provided

GraphicsBlock.step() handles:

• backend-specific redraw/flush behavior
• movie frame capture when movie output is enabled

So subclasses should do their drawing updates first, then call super().step(...).

Default axes behavior

By default, GraphicsBlock creates one 2D axes.

Axes behavior is controlled by the class variable PLOT3D:

• False (default): create a 2D axes
• True: create a 3D axes (projection='3d')

If a subclass does not define PLOT3D, it inherits the base default (False).

In tiled mode, each graphics block receives a tile slot and GraphicsBlock creates either a 2D or 3D axes in that slot based on PLOT3D.

Example: standard 2D block

class MyPlot(GraphicsBlock):
    nin = 1
    nout = 0
    # Optional; shown here for clarity. Omit to use inherited default.
    PLOT3D = False

    def start(self, simstate):
        super().start(simstate)
        if not self._enabled:
            return

        # fig/ax already prepared by GraphicsBlock
        self.line, = self.ax.plot([], [], "k-")

    def step(self, t, inports):
        if not self._enabled:
            return

        y = inports[0]
        # ... update line data ...
        super().step(t, inports)

Example: 3D block

class MyPlot3D(GraphicsBlock):
    nin = 1
    nout = 0
    PLOT3D = True

    def start(self, simstate):
        super().start(simstate)
        if not self._enabled:
            return

        # fig/ax are prepared by GraphicsBlock
        self.ax.set_xlabel("X")
        self.ax.set_ylabel("Y")
        self.ax.set_zlabel("Z")

    def step(self, t, inports):
        if not self._enabled:
            return

        # ... update 3D artists ...
        super().step(t, inports)

Notes

• Do not call _start_movie() directly in subclasses.
• Assigning self.fig is sufficient; movie setup is automatic.
• In tiled mode, GraphicsBlock creates 2D or 3D tile axes automatically from PLOT3D.
• Keep drawing logic in the subclass and lifecycle logic in the base class.