Text Processor

Overview

The Text Processor (text) renders one or more lines of text onto an existing RGBA image. It supports:

Google-Fonts or local .ttf/.otf
Pixel-based sizing (size), including relative sizing as a fraction of image height
Wrapping (max_width) with pixel-accurate measurement
Horizontal (align) and vertical (valign) block alignment
Per-line justification (justify)
Line spacing (line_height), stroke outline (stroke_width + stroke_fill), padding (padding)
Optional semi-opaque background box (background)
Input sanitization and clamping to prevent unreasonable values

Example Usage

- processor:
    processor: "text"
    inputs:
      source: "mem/photo.png"
    params:
      text: |
        Hello, World!
        This is multi-line text.
      font: "gf:Roboto:normal" # gf:<Family>:<light|normal|bold>
      size: 0.03 # as fraction of image height (3%)
      color: "#FFFFFF"
      anchor: "rel(0.5,0.1)"
      align: "center"
      valign: "top"
      justify: "center"
      max_width: 600
      min_height: 100
      max_height: 300
      line_height: 1.2
      stroke_width: 2
      stroke_fill: "rgba(0,0,0,0.7)"
      padding: 8
      background: "rgba(0,0,0,0.5)"
    outputs:
      target: "mem/photo_with_text.png"
    assigns:
      text_left: "txt_x"
      text_top: "txt_y"
      text_width: "txt_w"
      text_height: "txt_h"

Inputs

Key	Required	Description
source	Yes	Path to the RGBA PNG to draw text on.

Params

Key	Type	Required	Default	Description
text	`string`	Yes	—	UTF-8 text to render; may include `\n` for line breaks.
font	`string`	Yes	—	Local path or `gf:<Family>:<light	normal	bold>` Google-Font spec (sanitized).
size	`float`	Yes	—	Font height in pixels or fraction of image height (0.0–1.0).
color	`string`	No	`#000000`	Text fill color (`#RRGGBB`, `rgba()`, or named).
anchor	`string`	No	`"rel(0.0,0.0)"`	`(x,y)` in pixels or `rel(x,y)` relative to canvas [0.0–1.0].
align	`enum`	No	`left`	Horizontal block alignment: `left`, `center`, `right`.
valign	`enum`	No	`top`	Vertical block alignment: `top`, `center`, `bottom`.
justify	`enum`	No	`left`	Per-line text justification: `left`, `center`, `right`.
max_width	`int`	No	(none)	Wrap text to fit within this pixel width (clamped ≤ 2×image width).
min_height	`int`	No	`0`	Ensure text box ≥ this tall (clamped ≤ 2×image height).
max_height	`int`	No	(none)	Clip any text beyond this height (no vertical overflow, clamped ≤ 2×image height).
line_height	`float`	No	`1.0`	Multiplier of `size` for line-to-line spacing.
stroke_width	`int`	No	`0`	Outline (stroke) width in pixels (0 = no outline).
stroke_fill	`string`	No	`#000000`	Color for the text outline; supports RGBA transparency.
padding	`int`	No	`0`	Pixels of padding inside the background box.
background	`string`	No	(none)	Box fill color (`rgba()` or hex); if omitted, no box is drawn.

Outputs

Key	Required	Description
target	Yes	Path where the output PNG is written.

Assigns

Variable	Description
`text_left`	X-coordinate of the left edge of the text box.
`text_top`	Y-coordinate of the top edge of the text box.
`text_width`	Width of the rendered text box (including padding).
`text_height`	Height of the rendered text box (including padding).