文本转图像

使用 scripts/rendertextimage.py 生成图像并返回本地文件路径。该脚本在需要时也可以包含 data: 图像 URL。

优先使用该脚本而非手动编写图像负载。该脚本已处理以下内容：

• - 固定的图像宽度和高度
• 输出格式：svg、png、jpg、jpeg
• 默认在 tmp/ 下输出临时文件
• 响应中的绝对和相对文件路径
• 响应中的文件路径、文件名和文件大小
• 全文颜色
• 通过友好的高亮字段或原始片段实现部分文本颜色
• 显式字体大小
• 省略 font_size 时自动适配字体大小
• 识别换行符的自动换行
• 透明或纯色背景
• Windows 和 macOS 字体回退

输入格式

通过 --spec-json 或 --spec-file 传入 JSON 规范。

支持的字段：

json
{
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,
minfontsize: 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 + highlighttexts。
• 当调用方知道字符位置时，使用 highlightranges。
• 仅当调用方已经精确拆分好片段时，才使用 segments。
• 需要硬换行时保留 \n。
• 省略 fontsize 可使脚本自动将整个文本适配到图像内。
• 如果提供了 fontsize，脚本会保持该大小，同时根据需要自动换行。
• svg 是默认格式。
• 对于文本密集的图像，优先使用 png 而非 jpg。
• 如果 format 是 jpg 或 jpeg，透明背景会转换为白色。

优先级：

1. 1. segments
2. text + highlightranges / highlighttexts
3. 仅 text

友好的高亮格式：

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

范围格式：

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

推荐工作流程

1. 1. 根据用户请求构建 JSON 规范。
2. 运行脚本。
3. 当下一步是文件上传时，向调用方返回 filepath。
4. 仅当调用方明确需要数据 URI 时，才使用 imageurl。

示例：

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/rendertextimage.py --spec-file spec.json --no-data-url

输出约定

脚本输出 JSON：

json
{
file_path: E:\\clawhub\\text-to-image\\tmp\\rendered-0000.png,
relativefilepath: 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 }
]
}

说明

• - svg 轻量、清晰，是文本渲染的理想选择。
• png 是文本图像的最佳通用位图选择。
• jpg 为兼容性而支持，但通常不是文本的最佳默认格式。
• 自动适配使用宽度感知的自动换行和字体大小搜索；对于中英文混合文本，结果近似但可靠。
• 脚本默认将文件写入技能自身的 tmp/ 文件夹。
• 传入 --output path.ext 可控制文件写入位置。
• 当调用方只需要准备上传的文件元数据时，传入 --no-data-url。
• 在 macOS 上，脚本会先尝试 PingFang 和 STHeiti 等系统字体，然后回退。
• 在 Windows 上，脚本会尝试 Microsoft YaHei、SimHei 和 Arial 等字体。
• 可复用的示例规范位于 testcases/ 中，包括用于固定大小自动换行的 13-wrap-example.json。