Overlays

Drawing over the picture on the canvas, without being part of it.

An overlay is never exported. Its pen draws in the picture's own pixels: (0, 0) is the picture's top left corner, wherever the view has it and however far it is zoomed.

overlays: [{
  key: 'thirds', name: 'Rule of thirds',
  draw(pen, view) {
    pen.strokeStyle = 'rgba(255, 255, 255, 0.5)';
    pen.lineWidth = 1 / view.scale;                 // one screen pixel, at any zoom
    for (const part of [1 / 3, 2 / 3]) {
      pen.strokeRect(view.width * part, 0, 0, view.height);
      pen.strokeRect(0, view.height * part, view.width, 0);
    }
  },
}],

@plugin.overlay('Rule of thirds')
def thirds(pen, view, app):
    pen.strokeStyle = 'rgba(255, 255, 255, 0.5)'
    pen.lineWidth = 1 / view.scale                  # one screen pixel, at any zoom
    for part in (1 / 3, 2 / 3):
        pen.strokeRect(view.width * part, 0, 0, view.height)
        pen.strokeRect(0, view.height * part, view.width, 0)

view has the canvas's state (scale, x, y, w, h) plus width and height (the picture's size) and pixel (whether it is pixel art). The function is also handed the API as a third argument.

Overlays are drawn again whenever the view or the picture changes. Call api.view.redraw() (Python: app.view.redraw()) when something of your own changes.