Canvas

The main user-facing class for composing images.

This class implements a fluent builder pattern to define a builders template, which can then be used to render multiple elements. Each styling method returns the instance of the class, allowing for method chaining.

Example

canvas = Canvas()
image = (
    canvas.font_family("Arial")
    .font_size(24)
    .color("blue")
    .add_shadow(offset=(2, 2), blur_radius=3, color="black")
    .render("Hello, ", Text("World!").color("red"))
)
image.save("output.png")

`size(width=None, height=None)`

Sets the explicit size of the element's box using the border-box model.

The width and height are defined independently and control the total dimensions of the element, including its padding and border.

Each dimension supports several modes:

'auto': The size is context-dependent. It typically behaves like 'fit-content', but will yield to parent layout constraints, such as stretching to fill the space in a Row or Column with align stretch. This is the default behavior.
'fit-content': The size is explicitly set to wrap the element's content. This will override parent constraints like stretch.
'fit-background-image': The size is explicitly set to match the dimensions of the element's background image.
Absolute (pixels): An int or float value (e.g., 200) sets a fixed size.
Percentage: A str ending with % (e.g., "50%") sets the size relative to the parent container's content area.

Note: To make an element flexible and fill available space, use .flex_grow(1) instead of setting a size mode.

Parameters:

Name	Type	Description	Default
`width`	`Union[float, int, str]`	The horizontal size value. Defaults to "auto".	`None`
`height`	`Union[float, int, str]`	The vertical size value. Defaults to "auto".	`None`

Returns:

Name	Type	Description
`Self`	`Self`	The instance for method chaining.

`width(value)`

Sets the explicit width of the element's box.

This is a convenience method that is equivalent to calling size(width=value).

Parameters:

Name	Type	Description	Default
`value`	`SizeInput`	The horizontal size value. See `size()` for supported formats.	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance for method chaining.

`height(value)`

Sets the explicit height of the element's box.

This is a convenience method that is equivalent to calling size(height=value).

Parameters:

Name	Type	Description	Default
`value`	`SizeInput`	The vertical size value. See `size()` for supported formats.	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance for method chaining.

`fit_background_image()`

Adjusts the element's size to match its background image dimensions.

This is a convenience method that sets the element's width and height to fit the natural size of the background image. It is a shortcut for calling size(width='fit-background-image', height='fit-background-image').

This is particularly useful for ensuring an element, like a Row or Column, perfectly contains its background image without distortion or cropping, allowing other content to be layered on top.

The behavior can be overridden by a subsequent call to .size().

Example

# A Row that automatically sizes itself to the 'background.png'
# before rendering text on top of it.
Row()
    .background_image("path/to/background.png")
    .fit_background_image()
    .render(Text("Text over the full image").position("center", "center"))

Returns:

Name	Type	Description
`Self`	`Self`	The instance for method chaining.

`min_width(value)`

Sets the minimum width constraint for the element.

Ensures the element never shrinks below this width, regardless of content or flex shrinking behavior.

Parameters:

Name	Type	Description	Default
`value`	`Union[float, int, str]`	Minimum width value. Can be: - Absolute (pixels): int or float (e.g., 100) - Percentage: str ending with '%' (e.g., "50%")	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance for method chaining.

Example

# Ensure text never collapses below 100px
Text(username).flex_grow(1).min_width(100)

`max_width(value)`

Sets the maximum width constraint for the element.

Ensures the element never grows beyond this width, regardless of content or flex growing behavior.

Parameters:

Name	Type	Description	Default
`value`	`Union[float, int, str]`	Maximum width value. Can be: - Absolute (pixels): int or float (e.g., 300) - Percentage: str ending with '%' (e.g., "80%")	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance for method chaining.

Example

# Prevent long names from breaking layout
Text(product_name).size(width="fit-content").max_width(200)

`min_height(value)`

Sets the minimum height constraint for the element.

Ensures the element never shrinks below this height, regardless of content or flex shrinking behavior.

Parameters:

Name	Type	Description	Default
`value`	`Union[float, int, str]`	Minimum height value. Can be: - Absolute (pixels): int or float (e.g., 50) - Percentage: str ending with '%' (e.g., "30%")	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance for method chaining.

Example

# Ensure card has minimum height even with little content
Column(children).min_height(200)

`max_height(value)`

Sets the maximum height constraint for the element.

Ensures the element never grows beyond this height, regardless of content or flex growing behavior.

Parameters:

Name	Type	Description	Default
`value`	`Union[float, int, str]`	Maximum height value. Can be: - Absolute (pixels): int or float (e.g., 400) - Percentage: str ending with '%' (e.g., "90%")	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance for method chaining.

Example

# Limit description height with overflow
Text(description).max_height(150)

`aspect_ratio(ratio)`

Sets the aspect ratio constraint for the element.

Maintains a specific width-to-height proportion. When one dimension is specified (e.g., width), the other is calculated automatically to maintain the ratio.

The aspect ratio is expressed as width/height. Common examples: - Square: 1.0 or 1 - Landscape 16:9: 16/9 ≈ 1.778 - Portrait 9:16: 9/16 ≈ 0.5625 - Golden ratio: 1.618

Parameters:

Name	Type	Description	Default
`ratio`	`Union[float, int, str]`	Width-to-height ratio. Can be: - Float or int: Direct ratio value (e.g., 1.5, 16/9) - String with division: "16/9", "4/3", "1/1"	required

Returns:

Name	Type	Description
`Self`	`Self`	The instance for method chaining.

Example

# 16:9 video placeholder - specify width, height auto-calculated
Element().size(width=400).aspect_ratio(16/9)  # height = 225

# Square Instagram post
Element().size(width=300).aspect_ratio(1)  # height = 300

# Vertical story format
Element().size(height=600).aspect_ratio(9/16)  # width = 337.5

`font_family(family)`

Sets the font family or a path to a font file.

Parameters:

Name	Type	Description	Default
`family`	`Union[str, Path]`	The name of the font family or a `Path` object to a font file.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`font_fallbacks(*fonts)`

Specifies a list of fallback fonts.

These fonts are used for characters not supported by the primary font.

Parameters:

Name	Type	Description	Default
`*fonts`	`Union[str, Path]`	A sequence of font names or `Path` objects to font files.	`()`

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`font_size(size)`

Sets the font size in points.

Parameters:

Name	Type	Description	Default
`size`	`float`	The new font size.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`font_weight(weight)`

Sets the font weight.

Parameters:

Name	Type	Description	Default
`weight`	`Union[FontWeight, int, str]`	The font weight, e.g., `FontWeight.BOLD`, `700` or `"bold"`.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`font_style(style)`

Sets the font style.

Parameters:

Name	Type	Description	Default
`style`	`Union[FontStyle, str]`	The font style, e.g., `FontStyle.ITALIC`.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`color(color)`

Sets the text color or gradient.

Parameters:

Name	Type	Description	Default
`color`	`Union[str, PaintSource]`	A color string (e.g., "red", "#FF0000") or a `PaintSource` object.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`text_shadows(*shadows)`

Sets the shadow effects for the text.

Parameters:

Name	Type	Description	Default
`*shadows`	`Shadow`	A sequence of one or more `Shadow` objects.	`()`

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`text_stroke(width, color, mode='center')`

Adds a stroke to the text.

Parameters:

Name	Type	Description	Default
`width`	`float`	The width of the stroke in pixels.	required
`color`	`Union[str, PaintSource]`	The color of the stroke.	required
`mode`	`Union[str, StrokeMode]`	The stroke rendering mode: "center", "outline", or "inline".	`'center'`

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`underline(thickness=2.0, color=None)`

Adds an underline text decoration.

Parameters:

Name	Type	Description	Default
`thickness`	`float`	The thickness of the underline.	`2.0`
`color`	`Optional[Union[str, PaintSource]]`	The color of the underline. If `None`, the main text color is used.	`None`

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`strikethrough(thickness=2.0, color=None)`

Adds a strikethrough text decoration.

Parameters:

Name	Type	Description	Default
`thickness`	`float`	The thickness of the strikethrough line.	`2.0`
`color`	`Optional[Union[str, PaintSource]]`	The color of the line. If `None`, the main text color is used.	`None`

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`letter_spacing(value)`

Sets the extra space between characters (CSS letter-spacing).

Parameters:

Name	Type	Description	Default
`value`	`Union[float, int, str, LetterSpacing]`	Absolute pixels (float/int), a percentage string (e.g. `"10%"`), `"normal"`, or a `LetterSpacing` instance.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`line_height(value)`

Sets the line height.

Controls the vertical space each line of text occupies.

Parameters:

Name	Type	Description	Default
`value`	`Union[float, Literal['auto'], LineHeight]`	Accepts three forms: float: unitless multiplier applied to the current `font_size`. A value of `1.5` on a 20 px font yields 30 px per line. Common values: `1.0` (tight), `1.2` (headings), `1.4`-`1.6` (comfortable reading). `"auto"`: restores the default behaviour: each line height is derived from the font's own metrics (`ascent + descent + leading`), similar to CSS `line-height: normal`. `LineHeight`: a pre-built instance.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

Example

Text("Hello").font_size(20).line_height(1.5)
# Each line takes 30 px of vertical space.

Text("Hello").line_height("auto")
# Restores font-metrics-based line height.

`text_align(alignment)`

Sets the text alignment for multi-line text.

Parameters:

Name	Type	Description	Default
`alignment`	`Union[TextAlign, str]`	The alignment, e.g., `Alignment.CENTER` or `"center"`.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`text_wrap(wrap)`

Sets how text should wrap within its container.

Parameters:

Name	Type	Description	Default
`wrap`	`Union[TextWrap, str]`	The wrapping behavior, e.g., `TextWrap.NORMAL` or `"normal"` (allow wrapping), or `TextWrap.NOWRAP` or `"nowrap"` (prevent wrapping).	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`direction(value)`

Sets the text direction (horizontal flow).

BiDi algorithm runs automatically regardless of this setting. This property is inherited by child elements.

Parameters:

Name	Type	Description	Default
`value`	`Union[TextDirection, Literal['ltr', 'rtl']]`	The text direction, either "ltr" (left-to-right) or "rtl" (right-to-left). Can be a TextDirection enum or a string.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

Example

Text("مرحبا").direction("rtl")
Column(
    Text("Text 1"),  # inherits RTL
    Text("Text 2")   # inherits RTL
).direction("rtl")

`text_box_edge(both=None, *, top=None, bottom=None)`

text_box_edge(both: TextBoxEdgeInput) -> Self

text_box_edge(*, top: TextBoxEdgeInput = ..., bottom: TextBoxEdgeInput = ...) -> Self

Controls how the top and bottom edges of a text node's box are calculated.

By default, PicTex uses font metrics (ascent/descent) to size text boxes. This produces stable, predictable layouts because the box size depends only on the font, ignoring the specific characters in the string.

This method lets you override that behavior per-edge. It is inherited, so setting it on a Canvas or layout container applies to all Text nodes inside.

Note: This property is inspired by the CSS text-box-trim and text-box-edge properties, but does not implement them exactly.

Edge values:

"font" (default): The edge is placed at the font's ascent (top) or descent (bottom). The box always has the same height for a given font and size, regardless of content. Safe for dynamic / user-supplied text.
"glyphs": The edge is placed at the actual ink bounds of the rendered glyphs. The box tightly wraps the visible characters, removing the empty space reserved by the font for ascenders/descenders that are not present. Caution: the box size becomes content-dependent, so different strings produce different heights, which can shift your layout unexpectedly.

Parameters:

Name	Type	Description	Default
`both`	`Optional[TextBoxEdgeInput]`	Applies the same edge mode to both top and bottom.	`None`
`top`	`Optional[TextBoxEdgeInput]`	Edge mode for the top of the box (keyword-only). Defaults to `"font"` when omitted.	`None`
`bottom`	`Optional[TextBoxEdgeInput]`	Edge mode for the bottom of the box (keyword-only). Defaults to `"font"` when omitted.	`None`

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

Raises:

Type	Description
`TypeError`	If neither `both` nor at least one of `top`/`bottom` are provided, or if `both` is mixed with `top`/`bottom`.

Example

Trim both edges to the glyph ink bounds:

Text("Hello").text_box_edge(TextBoxEdgeValue.GLYPHS)
Text("Hello").text_box_edge("glyphs")

Trim only the top edge, keep font metrics at the bottom:

Text("Hello").text_box_edge(top="glyphs")
Text("Hello").text_box_edge(top="glyphs", bottom="font")  # equivalent

Inherit the setting for all Text nodes in a canvas:

Canvas().text_box_edge("glyphs").render("Hello, World!")

`box_shadows(*shadows)`

Sets the shadow effects for the element box. This style is not inherited.

This method applies one or more shadows to the box, replacing any previously set box shadows.

Parameters:

Name	Type	Description	Default
`*shadows`	`Shadow`	A sequence of one or more `Shadow` objects to be applied to the box.	`()`

Returns:

Type	Description
`Self`	The `Self` instance for method chaining.

`padding(*args)`

padding(all: Union[float, int]) -> Self

padding(vertical: Union[float, int], horizontal: Union[float, int]) -> Self

padding(top: Union[float, int], right: Union[float, int], bottom: Union[float, int], left: Union[float, int]) -> Self

Sets padding around the element, similar to CSS.

This method accepts one, two, or four values to specify the padding for the top, right, bottom, and left sides.

Parameters:

Name	Type	Description	Default
`*args`	`Union[float, int]`	One value: all four sides. Two values: vertical, horizontal. Four values: top, right, bottom, left.	`()`

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

Raises:

Type	Description
`TypeError`	If the number of arguments is not 1, 2, or 4.

`margin(*args)`

margin(all: Union[float, int]) -> Self

margin(vertical: Union[float, int], horizontal: Union[float, int]) -> Self

margin(top: Union[float, int], right: Union[float, int], bottom: Union[float, int], left: Union[float, int]) -> Self

Sets margin around the element, similar to CSS.

This method accepts one, two, or four values to specify the margin for the top, right, bottom, and left sides.

Parameters:

Name	Type	Description	Default
`*args`	`Union[float, int]`	One value: all four sides. Two values: vertical, horizontal. Four values: top, right, bottom, left.	`()`

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

Raises:

Type	Description
`TypeError`	If the number of arguments is not 1, 2, or 4.

`padding_top(value)`

Sets the top padding, preserving the other three sides.

`padding_right(value)`

Sets the right padding, preserving the other three sides.

`padding_bottom(value)`

Sets the bottom padding, preserving the other three sides.

`padding_left(value)`

Sets the left padding, preserving the other three sides.

`padding_horizontal(value)`

Sets left and right padding equally, preserving top and bottom.

`padding_vertical(value)`

Sets top and bottom padding equally, preserving left and right.

`margin_top(value)`

Sets the top margin, preserving the other three sides.

`margin_right(value)`

Sets the right margin, preserving the other three sides.

`margin_bottom(value)`

Sets the bottom margin, preserving the other three sides.

`margin_left(value)`

Sets the left margin, preserving the other three sides.

`margin_horizontal(value)`

Sets left and right margin equally, preserving top and bottom.

`margin_vertical(value)`

Sets top and bottom margin equally, preserving left and right.

`background_color(color)`

Sets the background color or gradient.

Parameters:

Name	Type	Description	Default
`color`	`Union[str, PaintSource]`	A color string or a `PaintSource` object.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`background_image(path, size_mode=BackgroundImageSizeMode.COVER)`

Sets a background image for the element.

Parameters:

Name	Type	Description	Default
`path`	`str`	The path to the image file.	required
`size_mode`	`Union[BackgroundImageSizeMode, str]`	The fitting strategy. Can be 'cover', 'contain', or 'tile'. - 'cover': The image is resized to completely cover the element's box, maintaining its aspect ratio. The image may be cropped. - 'contain': The image is resized to fit entirely within the box, maintaining its aspect ratio. This may leave empty space. - 'tile': The image is tiled at its original size without resizing.	`COVER`

Returns:

Name	Type	Description
`Self`	`Self`	The instance for method chaining.

`border(width, color, style=BorderStyle.SOLID)`

Sets the border for the element.

Parameters:

Name	Type	Description	Default
`width`	`float`	The width of the border in pixels.	required
`color`	`Union[str, PaintSource]`	The color of the border (e.g., "red", "#FF0000") or a PaintSource object.	required
`style`	`Union[str, BorderStyle]`	The style of the borderline. Can be 'solid', 'dashed', or 'dotted'.	`SOLID`

Returns:

Type	Description
`Self`	The `Self` instance for method chaining.

`border_radius(*args)`

border_radius(all: Union[float, str]) -> Self

border_radius(top_bottom: Union[float, str], left_right: Union[float, str]) -> Self

border_radius(top_left: Union[float, str], top_right: Union[float, str], bottom_right: Union[float, str], bottom_left: Union[float, str]) -> Self

Sets the corner radius for the background, similar to CSS border-radius. Accepts absolute values (pixels) or percentages as strings (e.g., "50%").

Parameters:

Name	Type	Description	Default
`*args`	`Union[float, str]`	One value: all four corners. Two values: [top-left, bottom-right], [top-right, bottom-left]. Four values: [top-left], [top-right], [bottom-right], [bottom-left].	`()`

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

`flex_grow(value)`

Sets the flex grow factor for this element (CSS flex-grow).

Controls how much this element should grow relative to siblings when there's extra space in the flex container.

Parameters:

Name	Type	Description	Default
`value`	`float`	The grow factor. 0 means no growth (default), 1+ means grow. Higher values grow proportionally more.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

Example

Row(
    Text("Fixed").size(width=100),
    Text("Grows x1").flex_grow(1),
    Text("Grows x2").flex_grow(2)
)

`flex_shrink(value)`

Sets the flex shrink factor for this element (CSS flex-shrink).

Controls how much this element should shrink relative to siblings when the container is too small.

Parameters:

Name	Type	Description	Default
`value`	`float`	The shrink factor. 0 means no shrinking, 1 means shrink proportionally (default). Higher values shrink more.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

Example

Row(
    Text("Don't shrink").flex_shrink(0),
    Text("Can shrink").flex_shrink(1)
)

`align_self(alignment)`

Override the container's align-items for this specific element (CSS align-self).

Allows an individual flex item to override the alignment set by its container.

Parameters:

Name	Type	Description	Default
`alignment`	`Union[AlignSelf, str]`	Alignment mode. Can be 'auto', 'start', 'center', 'end', or 'stretch'. 'auto' uses the container's align-items value (default).	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

Example

Row(
    Text("A"),
    Text("B").align_self('end'),  # This one aligns differently
    Text("C")
).align_items('start')

`overflow(value)`

Controls how content that exceeds the element's bounds is rendered.

Equivalent to CSS overflow. When set to "hidden", any content (text, child nodes, images) that extends beyond the element's padding box is clipped and hidden. The background and border are not affected by the clip.

This property is not inherited.

Parameters:

Name	Type	Description	Default
`value`	`Union[Overflow, Literal['hidden', 'visible']]`	`"hidden"` to clip overflowing content, or `"visible"` to leave it unclipped (the default). Accepts the `Overflow` enum or its string equivalents.	required

Returns:

Type	Description
`Self`	The `Self` instance for chaining.

Example

# Clip text that overflows a fixed-size box:
Text("Very long text…").size(width=200, height=50).overflow("hidden")

# Clip children that grow beyond a container:
Row(child1, child2).size(width=300).overflow("hidden")

`render(*elements, crop_mode=CropMode.NONE, font_smoothing=FontSmoothing.SUBPIXEL, scale_factor=1.0)`

Renders an image from the given elements using the configured builders.

Parameters:

Name	Type	Description	Default
`elements`	`Union[Element, str]`	The elements to be rendered. The strings received are converted to Text elements.	`()`
`crop_mode`	`CropMode`	The cropping strategy for the final canvas. - `SMART`: Tightly crops to only visible pixels. - `CONTENT_BOX`: Crops to the text + padding area. - `NONE`: No cropping, includes all effect boundaries (default).	`NONE`
`font_smoothing`	`Union[FontSmoothing, str]`	The font smoothing strategy. Accepts either `FontSmoothing.SUBPIXEL` (default) or `FontSmoothing.STANDARD`.	`SUBPIXEL`
`scale_factor`	`float`	Scaling factor for rendering. Values > 1.0 will render the image at a larger size. All dimensions (width, height, fonts, etc.) are scaled proportionally. Default is 1.0.	`1.0`

Returns:

Type	Description
`BitmapImage`	An `Image` object containing the rendered result.

`render_as_svg(*elements, embed_font=True)`

Renders the given elements as a scalable vector graphic (SVG).

This method produces a vector-based image, ideal for web use and applications requiring resolution independence.

Parameters:

Name	Type	Description	Default
`elements`	`Union[Element, str]`	The elements to be rendered. The strings received are converted to Text elements.	`()`
`embed_font`	`bool`	If `True` (default), any custom font files (`.ttf`/`.otf`) provided will be embedded directly into the SVG. This ensures perfect visual fidelity across all devices but increases file size. A warning will be issued if a system font is used with this option enabled. If `False`, the SVG will reference the font by name, relying on the viewing system to have the font installed.	`True`

Returns:

Type	Description
`VectorImage`	A `VectorImage` object containing the SVG data.