跳转至

渲染器 API

Renderer 类负责将布局后的节点树转换为 SVG（或 PNG）输出。

基本用法

from latticesvg import GridContainer, TextNode, Renderer

grid = GridContainer(style={"width": 400, "padding": 20, "background": "white"})
grid.add(TextNode("Hello!", style={"font-size": 24}))

renderer = Renderer()

# 输出 SVG 文件
renderer.render(grid, "output.svg")

# 输出 PNG 文件（需要 cairosvg）
renderer.render_png(grid, "output.png", scale=2)

# 获取 drawsvg.Drawing 对象
drawing = renderer.render_to_drawing(grid)

# 获取 SVG 字符串
svg_string = renderer.render_to_string(grid)

构造函数

Renderer()

无参数。内部创建 drawsvg.Drawing 实例。

方法

render(node, output_path, *, embed_fonts=False)

渲染节点及其后代为 SVG 文件。

参数 类型 默认值 说明
node Node 必填 根节点
output_path str 必填 SVG 文件的输出路径
embed_fonts bool False 是否嵌入子集化 WOFF2 字体

返回值： drawsvg.Drawing — 可用于进一步操作

render_to_drawing(node, *, embed_fonts=False)

渲染节点为 drawsvg.Drawing 对象，不写入任何文件。

自动布局

此方法会自动执行 node.layout()，无需手动调用（调了也无妨，会重新执行）。

参数 类型 默认值 说明
node Node 必填 根节点
embed_fonts bool False 是否嵌入子集化 WOFF2 字体

返回值： drawsvg.Drawing

render_to_string(node, *, embed_fonts=False)

渲染节点为 SVG 字符串（无文件 I/O）。

参数 类型 默认值 说明
node Node 必填 根节点
embed_fonts bool False 是否嵌入子集化 WOFF2 字体

返回值： str — SVG XML 字符串

render_png(node, output_path, scale=1.0, *, embed_fonts=False)

先渲染为 SVG，再通过 cairosvg 转换为 PNG。

参数 类型 默认值 说明
node Node 必填 根节点
output_path str 必填 PNG 文件的输出路径
scale float 1.0 缩放因子（2.0 输出 2 倍分辨率）
embed_fonts bool False 是否嵌入字体以确保字形准确

依赖要求

PNG 输出需要安装 cairosvg： 

pip install latticesvg[png]
# 或
pip install cairosvg

字体嵌入

当 embed_fonts=True 时，Renderer 会：

  1. 遍历节点树，收集所有使用的字体和字符
  2. 从字体文件中提取所需字形（子集化）
  3. 将子集化后的字体打包为 WOFF2 格式
  4. 在 SVG 中插入 @font-face 规则

这使得生成的 SVG 完全自包含，不依赖查看端安装的字体。

依赖

字体嵌入需要安装 fonttools 包： 

pip install fonttools[woff]

属性

属性 类型 说明
drawing drawsvg.Drawing \| None 最近一次渲染生成的 Drawing 对象

自动生成的 API 文档

Renderer 

Renderer()

Render a laid-out node tree to SVG using drawsvg.

Usage::

renderer = Renderer()
renderer.render(root_node, "output.svg")
renderer.render_png(root_node, "output.png", scale=2)
Source code in src/latticesvg/render/renderer.py 
33
34
def __init__(self) -> None:
    self.drawing: Optional[dw.Drawing] = None

render 

render(node: 'Node', output_path: str, *, embed_fonts: bool = False) -> dw.Drawing

Render node and its descendants to an SVG file.

PARAMETER DESCRIPTION
embed_fonts

If True, subset and embed all used fonts as WOFF2 @font-face rules inside the SVG, making it fully self-contained. Requires the fonttools package.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
Drawing

The drawing instance for further use.
Source code in src/latticesvg/render/renderer.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
def render(
    self,
    node: "Node",
    output_path: str,
    *,
    embed_fonts: bool = False,
) -> dw.Drawing:
    """Render *node* and its descendants to an SVG file.

    Parameters
    ----------
    embed_fonts:
        If *True*, subset and embed all used fonts as WOFF2
        ``@font-face`` rules inside the SVG, making it fully
        self-contained.  Requires the ``fonttools`` package.

    Returns
    -------
    drawsvg.Drawing
        The drawing instance for further use.
    """
    d = self.render_to_drawing(node, embed_fonts=embed_fonts)
    d.save_svg(output_path)
    return d

render_to_drawing 

render_to_drawing(node: 'Node', *, embed_fonts: bool = False) -> dw.Drawing

Render node to a drawsvg.Drawing without writing any file.

A full layout() pass is performed automatically before rendering, so callers do not need to call node.layout() explicitly. (Calling it beforehand is harmless — it will simply be executed again to guarantee up-to-date geometry.)

PARAMETER DESCRIPTION
embed_fonts

If True, subset and embed all used fonts as WOFF2 @font-face rules.

TYPE: bool DEFAULT: False

Source code in src/latticesvg/render/renderer.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def render_to_drawing(
    self,
    node: "Node",
    *,
    embed_fonts: bool = False,
) -> dw.Drawing:
    """Render *node* to a ``drawsvg.Drawing`` without writing any file.

    A full ``layout()`` pass is performed automatically before
    rendering, so callers do **not** need to call ``node.layout()``
    explicitly.  (Calling it beforehand is harmless — it will simply
    be executed again to guarantee up-to-date geometry.)

    Parameters
    ----------
    embed_fonts:
        If *True*, subset and embed all used fonts as WOFF2
        ``@font-face`` rules.
    """
    # Always (re-)layout to ensure geometry is up-to-date.
    node.layout()
    bb = node.border_box
    self.drawing = dw.Drawing(bb.width, bb.height)
    self._render_node(node, offset_x=-bb.x, offset_y=-bb.y)
    if embed_fonts:
        from ..text.embed import embed_fonts as _embed
        _embed(self.drawing, node)
    return self.drawing

render_to_string 

render_to_string(node: 'Node', *, embed_fonts: bool = False) -> str

Render node to an SVG string (no file I/O).

Source code in src/latticesvg/render/renderer.py 
 94
 95
 96
 97
 98
 99
100
101
def render_to_string(
    self,
    node: "Node",
    *,
    embed_fonts: bool = False,
) -> str:
    """Render *node* to an SVG string (no file I/O)."""
    return self.render_to_drawing(node, embed_fonts=embed_fonts).as_svg()

render_png 

render_png(node: 'Node', output_path: str, scale: float = 1.0, *, embed_fonts: bool = False) -> None

Render to SVG, then convert to PNG via cairosvg.

PARAMETER DESCRIPTION
embed_fonts

If True, embed subsetted fonts into the intermediate SVG before rasterising. This ensures cairosvg uses the exact same glyphs that were measured during layout.

TYPE: bool DEFAULT: False

Source code in src/latticesvg/render/renderer.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
def render_png(
    self,
    node: "Node",
    output_path: str,
    scale: float = 1.0,
    *,
    embed_fonts: bool = False,
) -> None:
    """Render to SVG, then convert to PNG via *cairosvg*.

    Parameters
    ----------
    embed_fonts:
        If *True*, embed subsetted fonts into the intermediate SVG
        before rasterising.  This ensures *cairosvg* uses the exact
        same glyphs that were measured during layout.
    """
    try:
        import cairosvg  # type: ignore
    except ImportError:
        raise ImportError(
            "cairosvg is required for PNG output. "
            "Install it with: pip install cairosvg"
        )

    svg_string = self.render_to_string(node, embed_fonts=embed_fonts)
    bb = node.border_box
    cairosvg.svg2png(
        bytestring=svg_string.encode("utf-8"),
        write_to=output_path,
        output_width=int(bb.width * scale),
        output_height=int(bb.height * scale),
    )