Add basic <symbol> support in SVG by Theo1335 · Pull Request #1819 · py-pdf/fpdf2

Theo1335 · 2026-04-15T11:11:58Z

Add basic support in SVG parsing

This PR adds support for SVG <symbol> elements.

Reuse existing group parsing logic for symbols.
Add a unit test covering symbol parsing and cross-reference registration.

Checklist:

A unit test is covering the code added / modified by this PR
In case of a new feature, docstrings have been added, with also some documentation in the docs/ folder (N/A)
A mention of the change is present in CHANGELOG.md
This PR is ready to be merged

By submitting this pull request, I confirm that my contribution is made under the terms of the GNU LGPL 3.0 license.

andersonhc · 2026-04-16T04:09:58Z

Thank you for this PR @Theo1335 , it's looking very promising!

I found one problem testing this SVG

The symbols are rendered but the scale is wrong.

Can you please check how to fix this?

Theo1335 · 2026-04-21T16:38:14Z

Thank you for your feedback @andersonhc !

I think I've finally solved the scaling issue with <symbol> elements: the viewBox is now extracted and stored when <symbol> is parsed, and when a <use> directive references a symbol with a width and height, the appropriate scaling is applied based on the `viewBox's dimensions.

Please let me know what you think.

andersonhc · 2026-04-27T11:55:07Z

+        viewbox = symbol.attrib.get("viewBox")
+        if viewbox:
+            parts = viewbox.replace(",", " ").split()
+            if len(parts) >= 4:
+                setattr(group, "_vw", float(parts[2]))
+                setattr(group, "_vh", float(parts[3]))


Right now the test is failing:

@force_nodocument def build_symbol(self, symbol: "Element") -> GraphicsContext: """Parse <symbol> as reusable content, not rendered directly.""" group = self.build_group(symbol) viewbox = symbol.attrib.get("viewBox") if viewbox: parts = viewbox.replace(",", " ").split() if len(parts) >= 4: > setattr(group, "_vw", float(parts[2])) E AttributeError: 'GraphicsContext' object has no attribute '_vw'

I don't think adding the viewbox attribute to the GraphicsContext is the best approach.
I recommend looking into using the GaphicsContext's transform to apply the viewbox.

Apply translate(-vx, -vy) @ scale(1 / vw, 1 / vh) to the symbol group should make it normalized to unit coordinates. In build_xref(), apply scale(width, height) @ translate(x, y).

Hi @andersonhc , I've implemented your suggestion using transforms. The viewBox is now applied in build_symbol with scale(1/vw, 1/vh) @ translate(-vx, -vy), and build_xref applies scale(width, height) when specified. I also ignore percentage values for width/height. I tested it and it should be working now. Let me know what you think !

andersonhc

Please see suggested changes.

I would also add you to add a new item on test/svg/parameters.py on the test_svg_sources set:

pytest.param(svgfile("symbol.svg"), id="symbol reused in different placements"),

then create the file test/svg/svg_sources/symbol.svg with the content below:

<svg viewBox="0 0 80 20" xmlns="http://www.w3.org/2000/svg">
  <!-- Our symbol in its own coordinate system -->
  <symbol id="myDot" width="10" height="10" viewBox="0 0 2 2">
    <circle cx="1" cy="1" r="1" />
  </symbol>

  <!-- A grid to materialize our symbol positioning -->
  <path
    d="M0,10 h80 M10,0 v20 M25,0 v20 M40,0 v20 M55,0 v20 M70,0 v20"
    fill="none"
    stroke="pink" />

  <!-- All instances of our symbol -->
  <use href="#myDot" x="5" y="5" opacity="1.0" />
  <use href="#myDot" x="20" y="5" opacity="0.8" />
  <use href="#myDot" x="35" y="5" opacity="0.6" />
  <use href="#myDot" x="50" y="5" opacity="0.4" />
  <use href="#myDot" x="65" y="5" opacity="0.2" />
</svg>

After that you will need to execute test_svg_conversion() once adding generate=True to assert_pdf_equal so it can generate the new PDF reference file.

andersonhc · 2026-05-13T12:37:33Z

    "turn": math.tau,
 }




Suggested change

class SymbolInfo(NamedTuple):

"""Reusable SVG <symbol> sizing metadata."""

viewbox: tuple[float, float, float, float]

width: Optional[float]

height: Optional[float]

@force_nodocument

def resolve_optional_length(length_str: Optional[str]) -> Optional[float]:

"""Resolve an optional absolute SVG length, ignoring unsupported percentages."""

if not length_str or "%" in length_str:

return None

return resolve_length(length_str)

@force_nodocument

def parse_viewbox(viewbox: str) -> tuple[float, float, float, float]:

"""Parse an SVG viewBox into min-x, min-y, width, and height values."""

parts = [float(num) for num in NUMBER_SPLIT.split(viewbox.strip()) if num]

if len(parts) != 4:

raise ValueError(f"invalid viewBox {viewbox}")

vx, vy, vw, vh = parts

if (vw < 0) or (vh < 0):

raise ValueError(f"invalid negative width/height in viewBox {viewbox}")

return vx, vy, vw, vh

andersonhc · 2026-05-13T12:39:12Z

    ) -> None:
        self.image_cache = image_cache  # Needed to render images
        self.resource_access_policy = resource_access_policy
        self.cross_references: dict[str, Any] = {}


Suggested change

self.cross_references: dict[str, Any] = {}

self.symbol_info: dict[str, SymbolInfo] = {}

andersonhc · 2026-05-13T12:41:11Z

+    @force_nodocument
+    def build_symbol(self, symbol: "Element") -> GraphicsContext:
+        """Parse <symbol> as reusable content, not rendered directly."""
+        group = self.build_group(symbol)
+        viewbox = symbol.attrib.get("viewBox")
+        if viewbox:
+            parts = viewbox.replace(",", " ").split()
+            if len(parts) >= 4:
+                vx, vy, vw, vh = (float(p) for p in parts[:4])
+                group.transform = Transform.scaling(
+                    x=1 / vw, y=1 / vh
+                ) @ Transform.translation(x=-vx, y=-vy)
+        return group
+


Suggested change

@force_nodocument

def build_symbol(self, symbol: "Element") -> GraphicsContext:

"""Parse <symbol> as reusable content, not rendered directly."""

group = self.build_group(symbol)

viewbox = symbol.attrib.get("viewBox")

if viewbox:

parts = viewbox.replace(",", " ").split()

if len(parts) >= 4:

vx, vy, vw, vh = (float(p) for p in parts[:4])

group.transform = Transform.scaling(

x=1 / vw, y=1 / vh

) @ Transform.translation(x=-vx, y=-vy)

return group

@force_nodocument

def build_symbol(self, symbol: "Element") -> GraphicsContext:

"""Parse <symbol> as reusable content, not rendered directly."""

group = self.build_group(symbol)

viewbox = symbol.attrib.get("viewBox")

if viewbox:

vx, vy, vw, vh = parse_viewbox(viewbox)

if vw == 0 or vh == 0:

group = GraphicsContext()

else:

group.transform = Transform.translation(

x=-vx, y=-vy

) @ Transform.scaling(x=1 / vw, y=1 / vh)

symbol_id = symbol.attrib.get("id")

if symbol_id:

symbol_key = (

"#" + symbol_id if not symbol_id.startswith("#") else symbol_id

)

self.symbol_info[symbol_key] = SymbolInfo(

viewbox=(vx, vy, vw, vh),

width=resolve_optional_length(symbol.attrib.get("width")),

height=resolve_optional_length(symbol.attrib.get("height")),

)

return group

andersonhc · 2026-05-13T12:44:43Z

+            target = self.cross_references[ref]
+            pdf_group.add_item(target)


Suggested change

target = self.cross_references[ref]

pdf_group.add_item(target)

pdf_group.add_item(self.cross_references[ref])

I don't think there's the need for the extra step here

andersonhc · 2026-05-13T12:47:24Z

        if "x" in xref.attrib or "y" in xref.attrib:
            # Quoting the SVG spec - 5.6.2. Layout of re-used graphics:
            # > The x and y properties define an additional transformation translate(x,y)
            x, y = float(xref.attrib.get("x", 0)), float(xref.attrib.get("y", 0))
            pdf_group.transform = Transform.translation(x=x, y=y)
-        # Note that we currently do not support "width" & "height" in <use>
+        # Note that we currently do not support "width" & "height" with % in <use>
+
+        if "width" in xref.attrib or "height" in xref.attrib:
+            w_str = xref.attrib.get("width", "")
+            h_str = xref.attrib.get("height", "")
+            if "%" not in w_str and "%" not in h_str:
+                w = float(w_str) if w_str else 1
+                h = float(h_str) if h_str else 1
+                if pdf_group.transform is None:
+                    pdf_group.transform = Transform.scaling(x=w, y=h)
+                else:
+                    pdf_group.transform = (
+                        Transform.scaling(x=w, y=h) @ pdf_group.transform
+                    )


Suggested change

)

placement_transform = None

if "x" in xref.attrib or "y" in xref.attrib:

# Quoting the SVG spec - 5.6.2. Layout of re-used graphics:

# > The x and y properties define an additional transformation translate(x,y)

x, y = float(xref.attrib.get("x", 0)), float(xref.attrib.get("y", 0))

placement_transform = Transform.translation(x=x, y=y)

# Note that we currently do not support "width" & "height" with % in <use>

symbol_info = self.symbol_info.get(ref)

if symbol_info:

_, _, vw, vh = symbol_info.viewbox

width = (

resolve_optional_length(xref.attrib.get("width"))

or symbol_info.width

or vw

)

height = (

resolve_optional_length(xref.attrib.get("height"))

or symbol_info.height

or vh

)

symbol_transform = Transform.scaling(x=width, y=height)

if placement_transform is None:

placement_transform = symbol_transform

else:

placement_transform = symbol_transform @ placement_transform

if placement_transform:

if pdf_group.transform:

pdf_group.transform = placement_transform @ pdf_group.transform

else:

pdf_group.transform = placement_transform

andersonhc · 2026-05-13T12:49:00Z

+    def test_svg_symbol(self):
+        svg_data = (
+            '<svg xmlns="http://www.w3.org/2000/svg" '
+            'xmlns:xlink="http://www.w3.org/1999/xlink">'
+            "<defs>"
+            '<symbol id="rond" width="10" height="10" viewBox="0 0 2 2"><circle cx="1" cy="1" r="1" fill="red"/></symbol>'
+            "</defs>"
+            '<use href="#rond" x="10" y="10" width="40" height="40"/>'
+            "</svg>"
+        )
+        svg = fpdf.svg.SVGObject(svg_data)
+        assert svg is not None
+        assert "#rond" in svg.cross_references
+


Suggested change

def test_svg_symbol(self):

svg_data = (

'<svg xmlns="http://www.w3.org/2000/svg" '

'xmlns:xlink="http://www.w3.org/1999/xlink">'

"<defs>"

'<symbol id="rond" width="10" height="10" viewBox="0 0 2 2"><circle cx="1" cy="1" r="1" fill="red"/></symbol>'

"</defs>"

'<use href="#rond" x="10" y="10" width="40" height="40"/>'

"</svg>"

)

svg = fpdf.svg.SVGObject(svg_data)

assert svg is not None

assert "#rond" in svg.cross_references

def test_svg_symbol(self):

svg_data = (

'<svg xmlns="http://www.w3.org/2000/svg" '

'xmlns:xlink="http://www.w3.org/1999/xlink">'

"<defs>"

'<symbol id="rond" width="10" height="10" viewBox="0 0 2 2"><circle cx="1" cy="1" r="1" fill="red"/></symbol>'

"</defs>"

'<use href="#rond" x="10" y="10" width="40" height="40"/>'

"</svg>"

)

svg = fpdf.svg.SVGObject(svg_data)

assert svg is not None

assert "#rond" in svg.cross_references

def test_svg_symbol_uses_symbol_dimensions(self):

svg_data = (

'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 20">'

'<symbol id="myDot" width="10" height="10" viewBox="0 0 2 2">'

'<circle cx="1" cy="1" r="1" />'

"</symbol>"

'<use href="#myDot" x="5" y="5" />'

"</svg>"

)

svg = fpdf.svg.SVGObject(svg_data)

symbol_use = svg.base_group.path_items[0]

assert tuple(symbol_use.transform) == pytest.approx((10, 0, 0, 10, 5, 5))

assert tuple(symbol_use.path_items[0].transform) == pytest.approx(

(0.5, 0, 0, 0.5, 0, 0)

)

def test_svg_symbol_use_dimensions_override_symbol_dimensions(self):

svg_data = (

'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 20">'

'<symbol id="myDot" width="10" height="10" viewBox="0 0 2 2">'

'<circle cx="1" cy="1" r="1" />'

"</symbol>"

'<use href="#myDot" x="5" y="5" width="40" height="20" />'

"</svg>"

)

svg = fpdf.svg.SVGObject(svg_data)

symbol_use = svg.base_group.path_items[0]

assert tuple(symbol_use.transform) == pytest.approx((40, 0, 0, 20, 5, 5))

def test_svg_symbol_viewbox_origin_is_translated_before_scaling(self):

svg_data = (

'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 20">'

'<symbol id="myDot" width="10" height="10" viewBox="10 10 2 2">'

'<circle cx="11" cy="11" r="1" />'

"</symbol>"

'<use href="#myDot" x="5" y="5" />'

"</svg>"

)

svg = fpdf.svg.SVGObject(svg_data)

symbol_use = svg.base_group.path_items[0]

assert tuple(symbol_use.transform) == pytest.approx((10, 0, 0, 10, 5, 5))

assert tuple(symbol_use.path_items[0].transform) == pytest.approx(

(0.5, 0, 0, 0.5, -5, -5)

)

def test_use_width_height_do_not_scale_non_symbol_references(self):

svg_data = (

'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 20">'

'<defs><path id="path" d="M 0 0 L 1 2 Z"/></defs>'

'<use href="#path" x="5" y="5" width="40" height="20" />'

"</svg>"

)

svg = fpdf.svg.SVGObject(svg_data)

path_use = svg.base_group.path_items[0]

assert tuple(path_use.transform) == pytest.approx((1, 0, 0, 1, 5, 5))

Theo1335 · 2026-05-13T13:22:06Z

Thanks for the detailed feedback! I will implement your suggestions and get back to you once it's done, or if I don't understand some details.

Theo1335 added 7 commits March 19, 2026 22:34

Automatically format test SVG <symbol>

f1402d6

Merge branch 'master' into svg-feature

716b040

erge branch 'master' into svg-feature

12c4120

Merge branch 'master' into svg-feature

a74e2eb

add basic <symbol> and tests

08c997f

Merge branch 'master' into svg-feature

1d70e3e

Update changelog for SVG <symbol> support

4b5ede7

Theo1335 added 3 commits April 16, 2026 17:23

Merge branch 'master' into svg-feature

2da065f

scale adjustment for symbols

97b9aa4

Merge branch 'master' into svg-feature

0440c4e

andersonhc added 2 commits April 26, 2026 23:22

Merge branch 'master' into svg-feature

84aac5a

Merge branch 'master' into svg-feature

47d508a

andersonhc requested changes Apr 27, 2026

View reviewed changes

Theo1335 and others added 2 commits May 4, 2026 12:57

Fix <symbol> scaling using transforms instead of setattr

23402a1

Merge branch 'master' into svg-feature

8e6411b

Theo1335 requested a review from andersonhc May 13, 2026 00:07

Merge branch 'master' into svg-feature

660b10e

andersonhc requested changes May 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add basic <symbol> support in SVG #1819

Add basic <symbol> support in SVG #1819
Theo1335 wants to merge 15 commits into
py-pdf:masterfrom
Theo1335:svg-feature

Theo1335 commented Apr 15, 2026 •

edited

Loading

Uh oh!

andersonhc commented Apr 16, 2026

Uh oh!

Theo1335 commented Apr 21, 2026 •

edited

Loading

Uh oh!

andersonhc Apr 27, 2026 •

edited

Loading

Uh oh!

Theo1335 May 4, 2026

Uh oh!

andersonhc left a comment

Uh oh!

andersonhc May 13, 2026

Uh oh!

andersonhc May 13, 2026

Uh oh!

andersonhc May 13, 2026

Uh oh!

andersonhc May 13, 2026

Uh oh!

andersonhc May 13, 2026

Uh oh!

andersonhc May 13, 2026

Uh oh!

Theo1335 commented May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

+class SymbolInfo(NamedTuple):
+    """Reusable SVG <symbol> sizing metadata."""
+    viewbox: tuple[float, float, float, float]
+    width: Optional[float]
+    height: Optional[float]
+@force_nodocument
+def resolve_optional_length(length_str: Optional[str]) -> Optional[float]:
+    """Resolve an optional absolute SVG length, ignoring unsupported percentages."""
+    if not length_str or "%" in length_str:
+        return None
+    return resolve_length(length_str)
+@force_nodocument
+def parse_viewbox(viewbox: str) -> tuple[float, float, float, float]:
+    """Parse an SVG viewBox into min-x, min-y, width, and height values."""
+    parts = [float(num) for num in NUMBER_SPLIT.split(viewbox.strip()) if num]
+    if len(parts) != 4:
+        raise ValueError(f"invalid viewBox {viewbox}")
+    vx, vy, vw, vh = parts
+    if (vw < 0) or (vh < 0):
+        raise ValueError(f"invalid negative width/height in viewBox {viewbox}")
+    return vx, vy, vw, vh


	self.cross_references: dict[str, Any] = {}
	self.symbol_info: dict[str, SymbolInfo] = {}

		target = self.cross_references[ref]
		pdf_group.add_item(target)

	target = self.cross_references[ref]
	pdf_group.add_item(target)
	pdf_group.add_item(self.cross_references[ref])

-                    )
+        placement_transform = None
+        if "x" in xref.attrib or "y" in xref.attrib:
+            # Quoting the SVG spec - 5.6.2. Layout of re-used graphics:
+            # > The x and y properties define an additional transformation translate(x,y)
+            x, y = float(xref.attrib.get("x", 0)), float(xref.attrib.get("y", 0))
+            placement_transform = Transform.translation(x=x, y=y)
+        # Note that we currently do not support "width" & "height" with % in <use>
+        symbol_info = self.symbol_info.get(ref)
+        if symbol_info:
+            _, _, vw, vh = symbol_info.viewbox
+            width = (
+                resolve_optional_length(xref.attrib.get("width"))
+                or symbol_info.width
+                or vw
+            )
+            height = (
+                resolve_optional_length(xref.attrib.get("height"))
+                or symbol_info.height
+                or vh
+            )
+            symbol_transform = Transform.scaling(x=width, y=height)
+            if placement_transform is None:
+                placement_transform = symbol_transform
+            else:
+                placement_transform = symbol_transform @ placement_transform
+        if placement_transform:
+            if pdf_group.transform:
+                pdf_group.transform = placement_transform @ pdf_group.transform
+            else:
+                pdf_group.transform = placement_transform

Conversation

Theo1335 commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andersonhc commented Apr 16, 2026

Uh oh!

Theo1335 commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andersonhc Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Theo1335 May 4, 2026

Choose a reason for hiding this comment

Uh oh!

andersonhc left a comment

Choose a reason for hiding this comment

Uh oh!

andersonhc May 13, 2026

Choose a reason for hiding this comment

Uh oh!

andersonhc May 13, 2026

Choose a reason for hiding this comment

Uh oh!

andersonhc May 13, 2026

Choose a reason for hiding this comment

Uh oh!

andersonhc May 13, 2026

Choose a reason for hiding this comment

Uh oh!

andersonhc May 13, 2026

Choose a reason for hiding this comment

Uh oh!

andersonhc May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Theo1335 commented May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Theo1335 commented Apr 15, 2026 •

edited

Loading

Theo1335 commented Apr 21, 2026 •

edited

Loading

andersonhc Apr 27, 2026 •

edited

Loading