Thumbor Text Filter

This plugin provides a way to draw text boxes on images via a Thumbor filter.

Compatible with Thumbor 7.x (Python 3.10+).

Installation

pip install thumbor_text_filter

Configuration

Add thumbor_text_filter to FILTERS in thumbor.conf, for example:

FILTERS = [
    # other filters....
    'thumbor_text_filter',
]

Usage

Add text() to the filters section of a thumbor url. The method signature is:

text(word, x, y, color, font-size, font-family, box-color, box-width, box-height)

• word, x, y, color, font-size are required.

• word may be plain text, or url-safe base64 prefixed with base64:. Use the base64 form when the text contains characters that would break the url, such as commas (which separate filter arguments). Padding (=) may be omitted.

• font-family is optional (defaults to DejaVuSans.ttf). It accepts, in order of resolution:

  1. a font file name or path (e.g. LiberationSerif-Bold, DejaVuSans.ttf, /usr/share/fonts/.../MyFont.ttf);
  2. a family name (e.g. Arial, Times New Roman) resolved to the closest installed font via fontconfig (fc-match), when available;
  3. otherwise Pillow's bundled default font is used.

  Note: family-name resolution needs fontconfig installed on the host (standard on most Linux distros). Use fc-list : file to see what is available. Values with spaces must be url-encoded (e.g. Times%20New%20Roman).

• box-color, box-width, box-height are optional. When all three are provided, a solid-colour box of box-width x box-height is drawn at (x, y) and the text is centered inside it. If any of them is missing, the text is drawn as plain text anchored at its top-left (x, y) corner.

For color and box-color, see the available color names here: https://pillow.readthedocs.io/en/stable/reference/ImageColor.html#color-names

Examples:

# plain text
http://thumbor/unsafe/filters:text(hello,10,10,red,25)/your-image-url
http://thumbor/unsafe/filters:text(hello,10,10,red,25,Arial)/your-image-url

# white text centered on a solid blue 200x60 box at (10,10)
http://thumbor/unsafe/filters:text(hello,10,10,white,25,Tahoma,blue,200,60)/your-image-url

# base64-encoded text (here "hola, mundo") to allow commas and other chars
http://thumbor/unsafe/filters:text(base64:aG9sYSwgbXVuZG8,10,10,red,25)/your-image-url

Development

This project is managed with uv.

uv sync          # create the environment and install dependencies
uv run pytest    # run the test suite

---

Copyright

MIT