Text To Image

文本转图像（Text to Image）

使用 scripts/render_text_image.py 脚本生成图像，并返回本地文件路径。该脚本在需要时还可同时输出 data: 协议格式的内联图像 URL。

优先使用该脚本，而非手动构造图像 payload。 脚本已内置支持以下功能：

• 固定图像宽高尺寸
• 输出格式：svg、png、jpg、jpeg
• 默认将临时文件输出至 tmp/ 目录
• 响应中同时提供绝对路径与相对路径
• 响应中包含文件路径、文件名及文件大小
• 全局文本颜色控制
• 通过友好的高亮字段（highlight_texts）或原始分段（segments）实现局部文本着色
• 显式指定字体大小（font_size）
• 当未指定 font_size 时自动适配字体大小以填满图像区域
• 支持换行符（\n）感知的自动换行
• 支持透明背景或纯色背景
• Windows 与 macOS 平台下的字体回退机制（fallback）

输入结构（Input Shape）

通过 --spec-json 或 --spec-file 参数传入 JSON 格式的配置说明（spec）。

支持的字段如下：

{
  "text": "Hello\nWorld",
  "highlight_ranges": [
    { "start": 0, "end": 5, "color": "#111111" },
    { "start": 6, "end": 11, "color": "#ff4d4f" }
  ],
  "highlight_texts": [
    { "match": "World", "color": "#1677ff", "occurrence": "all", "case_sensitive": true }
  ],
  "segments": [
    { "text": "Hello ", "color": "#111111" },
    { "text": "World", "color": "#ff4d4f" }
  ],
  "width": 1200,
  "height": 630,
  "format": "png",
  "font_size": 72,
  "min_font_size": 12,
  "default_color": "#111111",
  "background": "#ffffff",
  "padding": 48,
  "line_height": 1.2,
  "align": "center",
  "valign": "middle",
  "font_family": "Microsoft YaHei, PingFang SC, Arial, sans-serif"
}

规则说明：

• 必须提供 text 或 segments 二者之一；若两者同时存在，则以 segments 为准。
• 对于简单的“将某单词标红”类请求，推荐使用 text + highlight_texts 组合。
• 若调用方已知目标文本的字符起止位置（如编辑器光标位置），请使用 highlight_ranges。
• 仅当调用方已预先完成精确分段时，才使用 segments。
• 如需强制换行，请保留 \n 字符。
• 若省略 font_size，脚本将自动调整字体大小，使全部文本完整适配图像区域。
• 若显式指定了 font_size，脚本将严格采用该字号，并按需进行自动换行。
• 默认输出格式为 svg。
• 对于以文字为主的图像，推荐优先选用 png 而非 jpg。
• 若 format 设为 jpg 或 jpeg，透明背景将被自动转换为白色背景。

优先级顺序（由高到低）：

1. segments
2. text + highlight_ranges 或 highlight_texts
3. 仅 text

友好高亮格式示例（highlight_texts）：

{
  "text": "ClawHub makes text visible",
  "highlight_texts": [
    { "match": "ClawHub", "color": "#1677ff" },
    { "match": "visible", "color": "#fa541c" }
  ]
}

字符范围高亮格式示例（highlight_ranges）：

{
  "text": "Hello World",
  "highlight_ranges": [
    { "start": 6, "end": 11, "color": "#ff4d4f" }
  ]
}

推荐工作流（Recommended Workflow）

1. 根据用户请求构建 JSON spec；
2. 执行脚本；
3. 若后续步骤为文件上传，请仅返回响应中的 file_path 字段；
4. 仅当调用方明确要求 data URI 时，才使用 image_url 字段。

示例（PowerShell）：

@'
{
  "segments": [
    { "text": "Claw", "color": "#111111" },
    { "text": "Hub", "color": "#1677ff" }
  ],
  "width": 1024,
  "height": 512,
  "format": "png",
  "background": "#ffffff",
  "padding": 40
}
'@ | Set-Content spec.json

python scripts/render_text_image.py --spec-file spec.json --no-data-url

输出契约（Output Contract）

脚本标准输出为 JSON 格式，结构如下：

{
  "file_path": "E:\\clawhub\\text-to-image\\tmp\\rendered-0000.png",
  "relative_file_path": "tmp/rendered-0000.png",
  "file_name": "rendered-0000.png",
  "file_size": 21550,
  "mime_type": "image/png",
  "format": "png",
  "width": 1024,
  "height": 512,
  "font_size": 96.0,
  "line_count": 1,
  "resolved_segments": [
    { "text": "Claw", "color": "#111111" },
    { "text": "Hub", "color": "#1677ff" }
  ]
}

补充说明（Notes）

• svg 格式体积小、缩放无损，是文本渲染的理想选择；
• png 是面向文本图像的通用位图首选格式；
• jpg 仅用于兼容性支持，通常不建议作为文本图像的默认格式；
• 自动适配（auto-fit）采用宽度感知的换行策略与二分字体搜索算法，在中英文混排场景下具备良好鲁棒性；
• 脚本默认将生成的文件写入技能自身的 tmp/ 目录；
• 使用 --output path.ext 可自定义输出路径与文件名；
• 使用 --no-data-url 可禁用 data: URL 输出，适用于仅需上传元数据的场景；
• macOS 平台下，脚本优先尝试系统字体（如 PingFang、STHeiti），再回退至通用字体；
• Windows 平台下，脚本优先尝试 Microsoft YaHei、SimHei、Arial 等字体；
• 可复用的测试样例存放在 testcases/ 目录中，例如 13-wrap-example.json 演示了固定尺寸下的自动换行行为。