# **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
```yaml
- processor:
processor: "text"
inputs:
source: "mem/photo.png"
params:
text: |
Hello, World!
This is multi-line text.
font: "gf:Roboto:normal" # gf::
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::\\` 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). |