ErisPulse-Takumi

ErisPulse-Takumi 是 ccd2s 维护的 第三方图片渲染模块，基于 takumi-py，让 Bot 能够将 HTML、节点树、Jinja 模板、SVG、动画渲染为图片。模块 内置中英文字体（Noto Sans SC / Roboto / Source Code Pro），无需额外配置。

epsdk install Takumi

适用场景：

• 将数据/统计渲染为卡片图片
• 将 Markdown / 长文本渲染为排版稳定的图片，规避平台样式差异
• 生成 SVG / 动画，实现动态视觉效果
• 中英混排图文（内置字体开箱即用）

安装与启用

epsdk install Takumi

安装后模块自动加载，在配置中确认启用：

[Takumi]
enabled = true

快速上手

模块自动加载后，通过模块管理器获取，或使用 sdk 快捷方式：

from ErisPulse import sdk

takumi = sdk.module.get("Takumi")
# 等价写法：takumi = sdk.Takumi

渲染 HTML

png = takumi.render_html(
    """
    <div class="card">
      <h1>你好，ErisPulse</h1>
      <p>由 Takumi 渲染</p>
    </div>
    """,
    stylesheets=["""
    .card {
      width: 800px;
      padding: 48px;
      color: white;
      background: #111827;
      font-family: "Noto Sans SC";
    }
    """],
    width=800,
    height=None,   # 按内容自动撑高
    lang="zh-CN",
)

渲染节点树

png = takumi.render_node(
    {
        "type": "text",
        "text": "中文和 English 都可直接渲染",
        "style": {"fontSize": 48, "color": "#111827"},
    },
    width=800,
    height=None,
    lang="zh-CN",
)

png 是 bytes，可通过 event.reply(png, method="Image") 发送（详见 发送渲染结果）。

渲染 API

sdk.Takumi 代理了底层 takumi_py.Renderer 的全部能力：所有渲染、测量、SVG、动画、模板方法都可直接在 sdk.Takumi 上调用。对这些方法，模块会在调用时自动注入内置字体回退栈（takumi.families），无需手动传 font_families；若显式传入则尊重调用方设置。

方法总览

CompiledNode 暴露 resource_urls() 方法，可预先发现待加载的 HTTP(S) 图片引用，便于提前准备资源。

通用参数

以下参数适用于静态渲染与 SVG 方法（动画方法另有 fps 等，见对应示例）：

完整字段定义见 takumi_py.RenderOptions。

节点树示例

png = takumi.render_node(
    {
        "type": "container",
        "style": {"padding": "32px", "backgroundColor": "#111827"},
        "children": [
            {"type": "text", "text": "标题", "style": {"fontSize": 32, "color": "white"}},
            {"type": "text", "text": "正文", "style": {"fontSize": 18, "color": "#9ca3af"}},
        ],
    },
    width=800,
    height=None,
    lang="zh-CN",
)

Jinja 模板示例

png = takumi.render_template(
    "card.html.jinja",
    {"title": "Takumi", "subtitle": "Jinja to image"},
    stylesheets=["""
    .card {
      width: 800px;
      padding: 48px;
      color: white;
      background: #111827;
    }
    """],
    width=800,
    height=None,
    lang="zh-CN",
)

可通过 filters={...} 注入自定义 Jinja 过滤器，或 environment=... 传入完整 jinja2.Environment。模板目录与环境配置详见 takumi-py 模板文档。

SVG 输出示例

svg = takumi.render_svg_html(
    '<div class="card">Hello</div>',
    stylesheets=[".card { width: 800px; color: black; }"],
    width=800,
    height=None,
)

动画示例

from takumi_py import AnimationScene

webp = takumi.render_animation(
    [
        AnimationScene(
            {"type": "container", "style": {"width": "100%", "height": "100%", "backgroundColor": "black"}},
            duration_ms=100,
        ),
        AnimationScene(
            {"type": "container", "style": {"width": "100%", "height": "100%", "backgroundColor": "white"}},
            duration_ms=100,
        ),
    ],
    width=64,
    height=64,
    fps=20,
    format="webp",
)

每帧由 AnimationScene(node, duration_ms=...) 构成，duration_ms 必须为正数。

视口与输出格式

输出格式

format="raw" 返回行主序 RGBA 字节流，用于自定义像素级处理。

关于 width 与 height

width 与 height 的角色不对称：

• width 是视口宽度，文本与布局按它换行、回流。应固定为具体数值（如 800），否则画布会按内容自然宽度拉伸、文字不换行，尺寸不可控。
• height 是画布高度，随内容增长。height 默认值为 630；传入 height=None 时，Takumi 会根据内容自动撑高画布（auto viewport）。

字体

内置字体

模块属性：

自动注入

sdk.Takumi 上的全部渲染、测量、SVG、动画、模板方法会自动注入 takumi.families 作为字体回退栈。若直接调用 takumi.renderer（原生实例）或通过 create_renderer() 创建的独立实例，则需手动传 font_families=takumi.families。

自定义字体

from takumi_py import FontResource

families = takumi.renderer.register_font(
    FontResource(
        font_bytes,
        name="MyFont",
        weight=400,
        style="normal",
        generic_family="sans-serif",
    )
)

register_font 返回注册的 family 名称列表，可在后续渲染时作为 font_families 传入。

渲染器实例

原生 Renderer

takumi.renderer 是原始的 takumi_py.Renderer 实例。直接调用时需手动传 font_families：

png = takumi.renderer.render_html(
    "<div>你好</div>",
    font_families=takumi.families,
    lang="zh-CN",
)

独立 Renderer

需要隔离字体 / 图片 / 资源缓存时（长生命周期进程、多租户场景），可创建独立的 Renderer，内置字体会自动注册：

renderer = takumi.create_renderer(cache_max_bytes=64 * 1024 * 1024)

png = renderer.render_html(
    "<div>独立 Renderer</div>",
    font_families=takumi.families,
    width=800,
    height=None,
    lang="zh-CN",
)

create_renderer() 接受 takumi_py.Renderer 的构造参数：

独立实例不经过模块代理，因此若要保留统一的内置字体回退栈，需显式传入 font_families=takumi.families。若显式传入 font_families，模块会尊重调用方设置，不再注入默认回退栈；RenderOptions(font_families=...) 同样有效。

发送渲染结果

渲染得到的图片为 bytes，可通过事件回复直接发送：

from ErisPulse import sdk

takumi = sdk.Takumi
png = takumi.render_html("<div>hello</div>", lang="zh-CN")

# 方式一：以 Image 方法回复
await event.reply(png, method="Image")

# 方式二：通过 OneBot12 消息段回复
from ErisPulse.Core.Event import MessageBuilder
await event.reply_ob12(
    MessageBuilder().image(png).build()
)

不同平台对图片的封装由适配器统一处理。详见 MessageBuilder 详解 与 发送方法规范。

配置

[Takumi]
enabled = true

相关链接

• PyPI：https://pypi.org/project/ErisPulse-Takumi/
• 仓库：https://github.com/ccd2s/ErisPulse-Takumi（作者 @ccd2s）
• 底层引擎：https://github.com/BalconyJH/takumi-py
• takumi-py 文档：https://github.com/BalconyJH/takumi-py/blob/main/docs/index.md