Skip to content

Renderer API

The Renderer class converts a laid-out node tree to SVG (or PNG) output.

Basic Usage

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()

# Output SVG file
renderer.render(grid, "output.svg")

# Output PNG file (requires cairosvg)
renderer.render_png(grid, "output.png", scale=2)

# Get drawsvg.Drawing object
drawing = renderer.render_to_drawing(grid)

# Get SVG string
svg_string = renderer.render_to_string(grid)

Constructor

Renderer()

No parameters. Creates an internal drawsvg.Drawing instance.

Methods

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

Renders a node and its descendants to an SVG file.

Parameter Type Default Description
node Node required Root node
output_path str required Output path for SVG file
embed_fonts bool False Whether to embed subsetted WOFF2 fonts

Returns: drawsvg.Drawing — available for further use

render_to_drawing(node, *, embed_fonts=False)

Renders a node to a drawsvg.Drawing object without writing any file.

Automatic Layout

This method automatically runs node.layout(), so callers don't need to call it manually (calling it beforehand is harmless).

Parameter Type Default Description
node Node required Root node
embed_fonts bool False Whether to embed subsetted WOFF2 fonts

Returns: drawsvg.Drawing

render_to_string(node, *, embed_fonts=False)

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

Parameter Type Default Description
node Node required Root node
embed_fonts bool False Whether to embed subsetted WOFF2 fonts

Returns: str — SVG XML string

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

Renders to SVG first, then converts to PNG via cairosvg.

Parameter Type Default Description
node Node required Root node
output_path str required Output path for PNG file
scale float 1.0 Scale factor (2.0 outputs 2x resolution)
embed_fonts bool False Whether to embed fonts for accurate glyphs

Dependency Required

PNG output requires cairosvg: 

pip install latticesvg[png]
# or
pip install cairosvg

Font Embedding

When embed_fonts=True, the Renderer will:

  1. Traverse the node tree to collect all used fonts and characters
  2. Extract required glyphs from font files (subsetting)
  3. Package subsetted fonts as WOFF2 format
  4. Insert @font-face rules into the SVG

This makes the generated SVG fully self-contained, independent of fonts installed on the viewing device.

Dependency

Font embedding requires the fonttools package: 

pip install fonttools[woff]

Properties

Property Type Description
drawing drawsvg.Drawing \| None The Drawing object from the most recent render

Auto-generated API Docs

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),
    )