AI Full Figure

AI Full Figure

Generate a pictorial substrate via AI (Codex CLI or OpenAI Images API) and overlay labels, arrows, and scale bars programmatically. The output is an SVG that embeds the raster substrate and lets the [[scientific-figure]] composer place it as a panel.

When to use this skill

Reach for ai-full-figure when the figure's picture is the point:

• A brain rendering for a methods overview slide
• A microscope or apparatus illustration for a poster
• An anatomical scene as the background of a graphical abstract
• Any "what does this setup look like" pictorial

Reach for a different skill when the figure is information-dense:

Hard ceiling on AI generation

gpt-image-2 and equivalent models cannot reliably render:

• Data plots with axis numerals (axes hallucinate, tick labels are nonsense)
• Equations (LaTeX or Greek-letter math)
• Multi-arrow flowcharts (arrow direction inconsistent, arrows cross wrong)
• Long labels in specific positions ("> 5 labeled elements" is a useful threshold)
• Anything that needs to be read precisely — labels >1–2 words drift

The right pattern when those are needed: substrate-only generation, programmatic overlay.

1. Prompt the model for the pictorial scene with no text, no labels, no arrows.
2. Compose labels, arrows, scale bars, and panel letters as a separate SVG layer.
3. Ship the combined SVG.

If the user is asking for a figure that violates the hard ceiling, route to [[svg-figure]] or [[scientific-figure]] and explain why. AI generation for embedded text remains unreliable as of 2026.

The theme bible (shared with transparent-icons)

A theme.json keeps an AI-generated substrate visually consistent with the rest of the figure's palette and stroke language. The schema is the same one used by [[transparent-icons]]:

plugins/figures/skills/transparent-icons/references/theme.schema.json

Attach the theme to every generation call. The same fields apply: palette, stroke, style_tokens, negative_tokens, composition, reference_images, model_preferences. For substrates, the most load-bearing keys are:

• palette.primary / accent / neutral — color tokens injected into the prompt.
• negative_tokens — must include text, labels, watermark, arrows, caption. The substrate must not contain any text the overlay will replace.
• composition.aspect — substrates are typically 16:9 ("1920x1080") or 4:3; set this explicitly.
• style_tokens — e.g. "photorealistic illustration", "watercolor", "isometric 3D", "schematic line art".
• reference_images (optional, up to 16) — for consistency across a set of substrates.

Usage

Generate a substrate

uv run --with openai --with python-dotenv --with pillow \
    python scripts/generate_figure.py \
    "a stylized lateral view of a human brain in soft watercolor on a clean white background" \
    -o out/brain_substrate.png \
    --size 1920x1080 --backend codex

generate_figure.py builds the prompt from the theme bible (when --theme path/to/theme.json is provided) and dispatches to the Codex CLI or the OpenAI Images API. Output is an opaque PNG at the requested size. No transparency post-process is applied — substrates are designed to be the bottom layer, not floated.

Compose labels on top

uv run --with svgwrite --with pillow \
    python scripts/overlay_labels.py \
    out/brain_substrate.png \
    --label "lateral sulcus@600,420" \
    --label "central sulcus@800,300" \
    --scale-bar "1 cm@200,950" \
    -o out/brain_labeled.svg

The output SVG embeds the PNG via <image> and adds <text> / <line> / arrow markers on top. The SVG's viewBox matches the PNG's pixel dimensions so coordinates are pixel-addressed; width/height use a mm value so [[scientific-figure]] can compose it without rescaling math.

Label positions can be pre-computed in code (when overlay is data-driven) or eyeballed via Pillow's image viewer. The overlay_labels.py script accepts --label "text@x,y" shorthand or a JSON --labels-file for batch overlay.

Example pipeline

# 1. Generate substrate
uv run --with openai --with python-dotenv --with pillow \
    python scripts/generate_figure.py \
    "a stylized cell membrane with embedded receptor proteins" \
    -o out/cell_substrate.png \
    --size 1920x1080 --backend codex \
    --theme references/cell-theme.json

# 2. Overlay labels
uv run --with pillow \
    python scripts/overlay_labels.py \
    out/cell_substrate.png \
    --labels-file labels.json \
    -o out/cell_labeled.svg

# 3. (Optional) compose into a multi-panel figure with scientific-figure

See examples/poster_substrate.py for an end-to-end runnable demo with a small (cheap) substrate, an overlay, and a final composed figure.

Quality assurance

Invoke [[figure-qa]] after generation. The agent runs the raster branch on the substrate (alpha channel, DPI, dominant colors) and the SVG branch on the labeled output (label legibility, palette compliance, no text bleed). VLM judgment then rates aesthetic and journal-fit.

Additional resources

• references/prompt-patterns.md — substrate-focused prompt patterns and failure modes
• references/overlay-recipes.md — programmatic label/arrow/scale-bar overlay patterns
• Shared theme schema: ../transparent-icons/references/theme.schema.json
• scripts/generate_figure.py — substrate generator (Codex preferred, API fallback)
• scripts/overlay_labels.py — svgwrite-based overlay
• examples/poster_substrate.py — end-to-end demo