drawlib.canvas

drawlib.canvas manages the Cartesian drawing surface (origin (0, 0) at bottom-left; X right, Y up), resolution (dpi), coordinate grids, and output export lifecycle. Import lifecycle functions via from drawlib.canvas import canvas, clear, get_dimage, save, setup, show.

from drawlib.canvas import save, setup
from drawlib.icons import phosphor
from drawlib.lines import line
from drawlib.shapes import circle, rectangle
from drawlib.styles import Colors, Styles
from drawlib.text import text

setup(width=120, height=58, dpi=150)

# Left panel: Cartesian coordinate space
rectangle((35, 29), width=58, height=48, style=Styles.Neutral.patch(shape_r=2.0))
text(
    (35, 48.0),
    "Cartesian Space (0..width, 0..height)",
    style=Styles.DarkBold.patch(text_size=10.8),
)

# Subtle internal coordinate grid
for gx in (24, 36, 48):
    line((gx, 13), (gx, 41), style=Styles.MutedDashed.patch(line_width=0.8))
for gy in (22, 31):
    line((14, gy), (56, gy), style=Styles.MutedDashed.patch(line_width=0.8))

# X and Y axes from bottom-left origin (14, 13)
line((14, 13), (57, 13), arrow_head="->", style=Styles.DarkBold)
line((14, 13), (14, 42), arrow_head="->", style=Styles.DarkBold)
circle((14, 13), radius=1.3, style=Styles.PrimaryFlat)
text((20.5, 9.0), "(0, 0)", style=Styles.DarkBold.patch(text_size=10.0))
text((59.5, 13.0), "X", style=Styles.DarkBold.patch(text_size=10.5))
text((14.0, 44.2), "Y", style=Styles.DarkBold.patch(text_size=10.5))

# Center-anchored shape inside coordinate space
rectangle(
    (36, 27),
    width=24,
    height=11,
    style=Styles.PrimaryNeutral.patch(shape_r=1.5),
    text="(cx, cy)",
    text_style=Styles.DarkBold.patch(text_size=10.5),
)

# Right panel: 3-stage Canvas lifecycle
rectangle((92, 46.5), width=44, height=11, style=Styles.SecondaryNeutral.patch(shape_r=2.0))
phosphor.sliders((78.5, 46.5), width=4.0, style=Styles.DarkBold)
text((95.0, 46.5), "1. setup(w, h, dpi)", style=Styles.DarkBold.patch(text_size=10.5))

line((92, 41.0), (92, 35.0), arrow_head="->", style=Styles.DarkBold)

rectangle((92, 29.0), width=44, height=11, style=Styles.PrimaryFlat.patch(shape_r=2.0))
phosphor.paint_brush((78.5, 29.0), width=4.0, style=Styles.WhiteBold)
text(
    (95.0, 29.0),
    "2. Draw Artists",
    style=Styles.WhiteBold.patch(text_size=11.0, text_color=Colors.White),
)

line((92, 23.5), (92, 17.5), arrow_head="->", style=Styles.DarkBold)

rectangle((92, 11.5), width=44, height=11, style=Styles.Neutral.patch(shape_r=2.0))
phosphor.floppy_disk((78.5, 11.5), width=4.0, style=Styles.DarkBold)
text((95.0, 11.5), "3. save() / clear()", style=Styles.DarkBold.patch(text_size=10.5))

save()

constcanvas#

Singleton Canvas engine instance backing all module-level drawing and lifecycle functions. In addition to mirroring setup(), clear(), save(), show(), get_dimage(), and all 54 shape/line/text/image drawing methods, canvas exposes scoped coordinate transformations via canvas.transform(...) and typography metric helpers.

from drawlib.canvas import canvas

# Scoped coordinate scaling and translation context manager:
with canvas.transform(origin=(0.0, 0.0), scale=0.9, translate=(10.0, 5.0)):
    ...

Public Methods & Constants on Canvas#

defclear()#

Reset the active canvas state, removing all registered drawing artists and restoring default geometry, background, DPI, and grid parameters. Always call clear() between consecutive drawings in multi-image Python scripts.

def clear() -> None

defget_dimage()#

Render all artists currently registered on the canvas in memory and return an immutable Dimage object without writing to disk. Does not automatically clear the canvas.

def get_dimage() -> Dimage

defsave(file=None, format=None)#

Render the current canvas illustration and write it to an image file on disk. Inside Markdown ```drawlib blocks, drawlib build captures the canvas automatically and safely treats explicit save() calls as a no-op so code snippets remain copy-paste compatible with standalone .py scripts.

def save(
    file: str | None = None,
    format: ImageFormat | None = None,
) -> None

defsetup(width=None, height=None, dpi=None, ...)#

Configure canvas logical coordinate bounds (0..width horizontally, 0..height vertically from bottom-left (0, 0)), rasterization dpi, background color/opacity, and optional coordinate inspection grid. Must be called before registering drawing artists (calling setup() after drawing raises RuntimeError; call clear() first to reconfigure).

def setup(
    width: PosInt | None = None,
    height: PosInt | None = None,
    dpi: PosInt | None = None,
    color: ColorType | None = None,
    alpha: Alpha | None = None,
    background_color: ColorType | None = None,
    background_alpha: Alpha | None = None,
    grid: bool | None = None,
    grid_only: bool | None = None,
    grid_style: Style | None = None,
    grid_centerstyle: Style | None = None,
    grid_xpitch: PosInt | None = None,
    grid_ypitch: PosInt | None = None,
) -> None

defshow()#

Open an interactive local desktop Matplotlib preview window displaying the current canvas illustration. For headless CLI/CI environments, use save() or drawlib show <file> -o preview.png instead.

def show() -> None