concept-to-image

从概念到图像

使用 HTML/CSS/SVG 将概念转化为精美视觉作品，并将其作为可迭代优化的中间格式，之后导出为 PNG 或 SVG。

参考文件

文件	用途
references/design-guide.md	设计模式、反模式、调色板、字体选择和布局示例
scripts/render_to_image.py	基于 Playwright 的导出脚本——输入 HTML，输出 PNG 或 SVG
assets/template.html	基础 HTML 模板，已预先配置 .canvas 容器和 CSS 自定义属性

为什么使用 HTML 作为中间格式

HTML 是连接创意与图像的可迭代优化层。与直接渲染画布不同，用户可以查看 HTML 成品、提出修改要求（“把标题放大”“换一组颜色”“添加第三列”），并在满意后再导出。这样能让工作流可迭代且易于控制。

工作流

Concept → HTML artifact (view + refine) → PNG or SVG export

1. 理解 用户的概念——确定最适合的视觉形式（图表、信息图、卡片、图表等）
2. 设计 一个自包含的 HTML 文件，使用内联 CSS 和内联 SVG——不依赖任何外部资源
3. 展示 HTML 成品，让用户预览并提出优化要求
4. 迭代 根据用户反馈调整 HTML（颜色、布局、内容、尺寸）
5. 导出 用户满意后，使用 scripts/render_to_image.py 导出为 PNG 和/或 SVG

步骤 1：理解概念

确定最合适的视觉形式：

用户意图	视觉形式	实现方式
解释流程	流程图或管线图	SVG 路径 + 方框
比较项目	并排布局或矩阵	CSS Grid
展示层级	树形图或分层图	嵌套容器 + SVG 连接线
呈现数据	图表或信息图	SVG 图形 + 数据标签
社交媒体/营销图形	卡片或海报	注重字体排版的 HTML/CSS
图标、徽标、徽章	简洁符号	纯 SVG
教育类概念	带注释的图表	SVG + 定位标签

步骤 2：设计 HTML

阅读 references/design-guide.md，了解详细的设计模式和反模式。

核心规则：

• 单文件、自包含：所有 CSS 都放在 <style> 中，所有图形都使用内联 <svg>。不使用外部资源。
• 固定视口：在根容器上设置明确的 width 和 height，与预期导出尺寸一致。这一点至关重要——Playwright 会按此精确尺寸截取元素。
• 避免 AI 套路：避免所有内容居中、紫色渐变、统一的圆角，以及默认使用 Inter/系统字体。替代方案请参阅设计指南。
• 优先使用 SVG 绘制形状：图标、连接线、形状及任何需要清晰缩放的元素都使用内联 SVG。布局和字体排版使用 CSS。
• 有意识地使用颜色：最多使用 3–4 种色调，加上中性色。将颜色定义为 CSS 自定义属性。每种颜色都应承载含义。
• 从模板开始：使用 assets/template.html 作为基础结构。

尺寸指南

用途	建议尺寸
社交媒体图形	1200×630
信息图（纵向）	800×1200
演示文稿幻灯片	1920×1080
方形帖子	1080×1080
图标/徽章	256×256 或 512×512
宽幅图表	1600×900

将 .canvas 容器设置为选定尺寸。导出脚本会截取此元素。

第 3 步：展示并迭代

向用户展示 HTML 文件。用户会看到渲染后的成果。常见的修改请求：

• 颜色／主题更改 → 更新 CSS 自定义属性
• 布局调整 → 修改 grid/flexbox
• 内容更改 → 编辑文本／SVG 元素
• 尺寸更改 → 更新 .canvas 尺寸

每次迭代只需快速编辑 HTML，无需完整重新渲染。这是相较于直接生成图像的关键优势。

第 4 步：导出为图像

用户满意后，运行导出脚本：

python3 scripts/render_to_image.py <input.html> <output.png|.svg> [--width 1200] [--height 630] [--scale 2] [--selector ".canvas"]

参数

参数	默认值	说明
input	（必填）	HTML 文件路径
output	（必填）	输出路径。扩展名决定格式（.png 或 .svg）
--width	自动	视口宽度（覆盖 HTML 中定义的尺寸）
--height	自动	视口高度（覆盖 HTML 中定义的尺寸）
--scale	2	PNG 的设备缩放因子（2 = Retina 画质）
--selector	.canvas	要捕获元素的 CSS 选择器
--full-page	false	捕获整个页面，而非特定元素

PNG 导出

使用 Playwright 启动无头 Chromium，并按指定的缩放因子截取 .canvas 元素。缩放因子为 2 时会生成 Retina 画质的输出（例如，1200×630 CSS 像素 → 2400×1260 PNG ≈ 3.02 MP）。

Opus 4.7 反馈循环： Retina 比例导出（例如 2400×1260）不超过 Opus 4.7 约 3.75 MP 的视觉上限，因此可以将渲染后的 PNG 输入模型，通过批评迭代循环进行优化。在 Opus 4.6 中，这类输出在输入时会被缩小。

SVG 导出

自动选择以下两种策略之一：

1. SVG 原生内容：如果 .canvas 元素包含单个根 <svg>，则直接提取为干净的 SVG 文件。这会生成真正的矢量 SVG。
2. 基于 HTML 的内容：如果内容主要由 CSS／HTML 构成，则回退到 PNG 导出，并提示真正的 SVG 需要采用 SVG 原生设计。如果需要矢量输出，脚本会发出警告并建议改用 SVG 元素重新设计。

交付输出

向用户提供输出文件。始终同时交付 HTML（以便日后编辑）和图像（最终输出）。

错误处理

错误	原因	解决方法
playwright not found	未安装 Playwright 包	运行 npx playwright install chromium 或 pip install playwright && playwright install chromium
浏览器启动失败	无头 Chromium 无法启动	确认支持 --headless 模式；检查可用内存（Chromium 需要约 200 MB）
未找到 .canvas 选择器	HTML 中没有匹配 .canvas 的元素	确认使用了 assets/template.html 作为基础；检查根容器是否包含 class="canvas"
渲染超时	复杂 HTML 在截图前需要过长时间渲染	通过脚本中的 --timeout 标志延长超时时间，或简化 HTML（减少 DOM 深度、减少内联 SVG）
SVG 导出回退到 PNG	.canvas 元素包含 HTML／CSS 内容，而非根 SVG	请参阅 SVG 导出部分；如果需要矢量输出，请改用单个根 <svg> 重新设计

限制

• 需要 Playwright + Chromium——导出脚本必须在 Chromium 正常安装的情况下才能运行。
• 仅支持 macOS 和 Linux 导出无头浏览器内容。Windows Subsystem for Linux 可用；原生 Windows 上的 Playwright 可能需要单独配置。
• SVG 导出尽力而为——复杂的 HTML/CSS 布局会回退到 PNG。真正的矢量 SVG 要求 .canvas 子元素是单个根 <svg>。
• 视口最大为 4096×4096——Chromium 会拒绝尺寸超过此限制的屏幕截图。使用 --scale，在此限制内实现更高的有效分辨率。
• 不支持动画——导出的图像是静态快照。CSS 动画和 JavaScript 驱动的过渡效果会冻结在初始状态。

输出示例

成功导出后，脚本会打印输出路径和文件统计信息：

Exported: concept-diagram.png
  Size:       2400 × 1260 px  (2× scale from 1200 × 630 canvas)
  File size:  ~180 KB
  Format:     PNG (RGBA)

文件名模式取决于传入的输出参数。典型文件大小：

• 简单图表（文本 + 图形）：80–200 KB
• 带渐变的密集信息图：300–600 KB
• 完整的 1920×1080 图像，缩放至 2 倍：500 KB–1.5 MB

应避免的设计反模式

这些设计会让输出看起来像普通的“AI 生成”内容：

• 所有元素都居中且间距相同
• 紫色／蓝色渐变背景
• 所有元素都使用统一的圆角半径
• 通用图标库（使用自定义内联 SVG）
• 缺乏字体设计意图的系统字体栈
• 所有元素都加投影
• 信息密度低（留白过多）

字体处理

由于此环境可用字体有限，请使用带有精心选择的回退字体的 Web 安全字体栈：

• 技术／等宽：'Courier New', 'Consolas', monospace
• 简洁无衬线：'Helvetica Neue', 'Arial', sans-serif
• 编辑风格衬线：'Georgia', 'Times New Roman', serif
• 展示字体：需要展示字体排印效果时，使用带有自定义路径的 SVG 文本