Core Concepts
A canvas is a list of layers
A Canvas has a size and an ordered list of layers. Each layer method adds one
layer and returns the canvas, so calls chain:
from quickthumb import Canvas
canvas = (
Canvas(1280, 720)
.background(color="#0F172A")
.text(content="Hello", size=64, color="#FFFFFF", align="center")
.outline(width=8, color="#22D3EE")
)
canvas.render("hello.png")
Layers are drawn in the order you add them. The first one is at the back and the last one is on top, so you describe an image the way you would paint it: background first, details last.
Layer types
| Method | Adds | Reference |
|---|---|---|
.background() |
A full-canvas color, gradient, or image | Background |
.text() |
Text, plain or as styled TextParts |
Text |
.image() |
A placed image, optionally cut out of its background | Image |
.shape() |
A rectangle, ellipse, pill, triangle, star, or polygon | Shape |
.svg() |
An SVG file such as an icon or logo (needs the svg extra) |
SVG |
.video() |
A video clip, for animated exports | Video |
.chart(), .qr_code() |
A bar or line chart, or a QR code | Data visualizations |
.counter() |
A number that counts from one value to another | Canvas |
.group() |
A row or column that positions its children for you | Group |
.outline() |
A border around the edge of the canvas | Outline |
.custom(fn) |
Your own function that draws on the Pillow image | Canvas |
Position and alignment
position is an (x, y) pair. Each value is pixels or a percentage of the
canvas, and you can mix them:
canvas.shape(shape="rectangle", position=(64, 64), width=200, height=80, color="#CC0000")
canvas.text(content="Hello", size=72, color="#FFFFFF", position=("8%", 360))
align says which point of the layer sits at that position. By default it is
the top-left corner. align=("center", "middle") puts the layer's center
there instead, and align=("right", "bottom") with position=(1280, 720)
pins a layer to the bottom-right corner of a 1280×720 canvas whatever its
size.
align accepts several spellings of the same thing:
align=("center", "middle") # (horizontal, vertical)
align="center" # same as ("center", "middle")
align="bottom-right"
align=Align.BOTTOM_RIGHT
Horizontal values are left, center, and right; vertical values are
top, middle, and bottom. A text layer with align but no position is
placed on the canvas by its alignment, so align="center" centers it.
Effects
Effects change how one layer is drawn. Pass them as a list:
from quickthumb import Shadow, Stroke
canvas.text(
content="CLICK NOW",
size=96,
color="#FFFFFF",
effects=[
Stroke(width=4, color="#000000"),
Shadow(offset_x=4, offset_y=4, color="#000000", blur_radius=8),
],
)
Not every effect makes sense on every layer:
| Layer | Effects |
|---|---|
| Background | Filter, Grain |
| Text | Stroke, Shadow, Glow, Background (a box behind the text) |
| Shape | Stroke, Shadow, Glow, InnerShadow, BackdropBlur |
| Image, SVG, video | Stroke, Shadow, Glow, Filter, Grain, Duotone, InnerShadow, BackdropBlur |
Passing an effect a layer doesn't support raises ValidationError. The
Effects reference lists every parameter.
Rich text
A plain string is enough when all the text looks the same. To style parts of
it differently, pass a list of TextParts:
from quickthumb import TextPart
canvas.text(
content=[
TextPart(text="5 ", color="#FBBF24"),
TextPart(text="WAYS TO WIN", color="#FFFFFF"),
],
size=80,
weight=900,
position=("8%", "55%"),
align=("left", "middle"),
)
Settings on the layer (size, weight here) apply to every part unless the
part sets its own. A part can override color, size, font, weight,
bold, italic, letter_spacing, line_height, and effects.
Gradients, blend modes, and fit
Backgrounds take a gradient as well as a color or an image:
from quickthumb import LinearGradient, RadialGradient
canvas.background(gradient=LinearGradient(angle=135, stops=[("#FF5733", 0.0), ("#3333FF", 1.0)]))
canvas.background(gradient=RadialGradient(center=(0.5, 0.5), stops=[("#FF5733", 0.0), ("#3333FF", 1.0)]))
Colors in stops can include alpha ("#00000080"), which is how you darken
part of a photo behind text.
blend_mode on a background or image layer sets how it combines with what is
underneath: normal, multiply, screen, overlay, darken, or lighten.
fit sets how an image fills its box: cover fills it and crops the excess
(the default for backgrounds), contain fits the whole image inside, and
fill stretches it.
Auto layout
Text that is placed by hand breaks when the copy gets longer. A group
measures its children and stacks them in a row or column; you place the group
once and it places the children:
canvas.group(
children=[
{"type": "shape", "shape": "pill", "width": 120, "height": 36, "color": "#E94560"},
{"type": "text", "content": "AUTO LAYOUT", "size": 96, "color": "#FFFFFF", "weight": 900},
{"type": "text", "content": "Longer copy pushes the rest down", "size": 40, "color": "#A2A8D3"},
],
direction="column",
gap=24,
position=("8%", "50%"),
align=("left", "middle"),
)
Children don't set a position, and groups can contain groups. See
Group.
JSON specs
Everything above can be written as JSON instead of Python, and a canvas converts both ways:
The only exception is .custom(fn), because a Python function can't be stored
as JSON.
JSON specs can also define colors and sizes once in a theme block and refer
to them as $theme.<path>:
{
"kind": "canvas",
"width": 1280,
"height": 720,
"theme": { "colors": { "primary": "#B8FF00" }, "sizes": { "title": 96 } },
"layers": [
{ "type": "text", "content": "Hello", "size": "$theme.sizes.title", "color": "$theme.colors.primary" }
]
}
See JSON Schema & AI Workflow.
Path motion
Canvas.path() supports SVG path data, fills (including gradients), and dashed
strokes. A path's fixed width/height viewport clips its local drawing and
defines its normalized anchor, including during rotation and scaling:
from quickthumb import AnimationSpec, Canvas, KeyframeSpec, ScaleTrack, TimingSpec
canvas = Canvas(320, 240).path(
"M2 20C2 2 38 2 38 20C38 38 2 38 2 20Z", (100, 80), 40, 40,
"#38B6A080", anchor=(0.5, 0.5),
animation=AnimationSpec.timeline(
ScaleTrack(keyframes=[KeyframeSpec(time=0, value=1), KeyframeSpec(time=1, value=4)]),
timing=TimingSpec(duration=1), easing="linear",
),
)
frame = canvas.render_frame(0.75)
Use track timelines to animate a path. Support varies by output format; presets, stagger, Group children and transform parenting are not supported for paths. See the Path API for animation and export details.
Errors and checks
Arguments are validated when you add a layer, before anything is drawn:
from quickthumb import ValidationError
try:
canvas.text(content="Hello", size=64, color="#FFF")
except ValidationError as error:
print(error) # /color: invalid hex color: #FFF
Problems that only show up while drawing, such as a failed download, raise
RenderingError, and a local file that doesn't exist raises
MissingAssetError. Every error carries structured details; see
Structured Errors.
A canvas can be valid and still look wrong. canvas.diagnose() looks for
text that is too small or runs off the canvas, low contrast, layers hidden by
other layers, and similar problems, without rendering a file. See
Diagnostics & CLI.