Rasterize — Multi-Engine Raster Image Generation

Generate professional raster images by routing each request to the best rendering engine. You write Python code; the engine does the pixel work.

Quick Start

1. Read the user's request
2. Pick an engine using the routing table below
3. Read the engine's reference doc from ./references/
4. Write a self-contained Python script that outputs to the target path
5. Run the script using pdm run python <script.py> (to use the plugin's venv), verify the output, deliver the image

Environment: This plugin uses a pdm-managed virtual environment. Always run generation scripts with pdm run python from the plugin root. If pdm is not set up yet, run python scripts/setup.py first.

Engine Routing Table

Routing decision hints

• If the request mentions "chart", "plot", "graph", "histogram", "scatter", "heatmap", or data columns → Matplotlib/Seaborn (or Plotly for fancier output)
• If the request is about a logo, icon, badge, geometric design, or anything that needs crisp anti-aliased curves → Cairo
• If the request says "banner", "social media post", "thumbnail" with text overlays on photos → Pillow
• If the request describes a full-page layout, poster with complex typography, card design, or UI mockup → Playwright
• If the request is about generative/procedural/algorithmic art → Cairo (or Pillow if it's pixel-manipulation art like fractals)
• When in doubt between Pillow and Cairo → prefer Cairo (better quality)
• When in doubt between Matplotlib and Plotly → prefer Matplotlib (simpler, faster)

Multi-engine compositions

Some requests need two engines. Common combos:

• Matplotlib → Pillow: Generate a chart, then composite it onto a branded background with logos and text overlays
• Cairo → Pillow: Draw clean vector shapes, then apply raster effects (blur, noise, texture)
• Playwright → Pillow: Render an HTML layout, then crop/resize/optimize

When combining engines, save intermediate outputs as temporary PNGs and load them in the second engine.

Shared References

These files contain cross-engine patterns — read them before the engine docs:

• ./shared/setup.md — Installation, pdm setup, running scripts
• ./shared/fonts.md — Font directory resolution, per-engine loading, font selection guide
• ./shared/canvas.md — Dimensions, size presets, retina scaling, output saving (PNG/JPEG/WebP)
• ./shared/themes.md — Dark/light themes, color tokens, categorical/sequential/diverging palettes

Workspace

All generated files go into the generated/ directory at the plugin root:

generated/
  <slug>_render.py      # generation script
  <slug>.png            # output image

• Scripts: Save as generated/<slug>_render.py where <slug> is a short kebab-case name derived from the request (e.g., social-card_render.py)
• Output images: Save as generated/<slug>.png (or .jpg/.webp)
• Intermediates: Save temporary files in generated/ too — prefix with _tmp_
• The generated/ directory is gitignored. Do NOT place scripts in scripts/ or output in output/ — those are not for generated artifacts.
• After delivering the final image, clean up intermediate _tmp_* files.
• Keep the generation script after completion — the user may want to iterate ("make the text bigger", "change the color") and the script enables re-rendering without rewriting from scratch.
• If the user explicitly asks to clean up, delete both the script and output.

Script Structure

Every generation script should follow this pattern:

#!/usr/bin/env python3
"""Rasterize: [brief description of what this generates]"""

import os

# === CONFIGURATION ===
WIDTH, HEIGHT = 1200, 630       # Logical dimensions
SCALE = 2                       # Retina multiplier

# Paths — all generated files go in generated/
PLUGIN_ROOT = os.path.dirname(os.path.abspath(__file__))
GENERATED_DIR = os.path.join(PLUGIN_ROOT, "generated")
os.makedirs(GENERATED_DIR, exist_ok=True)
OUTPUT_PATH = os.path.join(GENERATED_DIR, "<slug>.png")
FONT_DIR = os.path.join(PLUGIN_ROOT, "assets", "fonts")

# Engine-specific imports here

# === HELPERS ===
# Reusable drawing functions here

# === COMPOSITION ===
def render():
    # Main rendering logic
    # ...
    pass

# === EXECUTE ===
if __name__ == "__main__":
    render()
    print(f"Saved to {OUTPUT_PATH}")

Design Principles

When generating images, aim for professional quality:

• Whitespace: Leave generous margins (at least 5-8% of canvas size). Content should breathe.
• Color: Use cohesive palettes. When the user doesn't specify colors, choose a palette with 1 primary, 1 accent, 1-2 neutrals. Avoid pure black (#000); use near-black (#1a1a2e or #0f172a) instead. Avoid pure white (#fff) on large areas; use off-white (#fafafa, #f8fafc).
• Typography: Maximum 2 font families per image. Establish clear hierarchy (title → subtitle → body → caption) through size and weight.
• Alignment: Use a grid. Align elements to consistent baselines and gutters. Misalignment is the #1 tell of AI-generated graphics.
• Contrast: Ensure text passes WCAG AA (4.5:1 ratio). Use a contrast checker function if needed.

Error Handling

• If a required engine is not installed, follow ./shared/setup.md.
• If a font file is missing, fall back to a safe default from the bundled collection (see ./shared/fonts.md). Never use system fonts without checking availability.
• If rendering fails, check the error, fix the script, and retry. Common issues: missing font path, wrong image mode, Cairo surface not flushed before save.

Engine Reference Docs

Before writing a generation script, ALWAYS read the relevant engine reference doc from ./references/. These contain engine-specific patterns, gotchas, and helper snippets that prevent common mistakes.

• ./references/pillow.md — Pillow patterns and helpers
• ./references/cairo.md — PyCairo patterns and helpers
• ./references/matplotlib.md — Matplotlib + Seaborn patterns
• ./references/plotly.md — Plotly static export patterns
• ./references/playwright.md — HTML-to-PNG via Playwright