SVG Elements Parsing

Warnings

• breaking The project was renamed from `svg.elements` to `svgelements`. Older code using `from svg.elements import ...` will no longer work and needs to be updated to `from svgelements import ...`.
  Fix: Update import statements: `from svg.elements import X` -> `from svgelements import X`.
• gotcha Calculating the length of `CubicBezier` and `Arc` path segments via `Path.length()` or similar methods can be computationally intensive and slow, as it relies on geometric approximation by default. Performance can be significantly improved by installing `scipy`.
  Fix: Install `scipy` (`pip install scipy`) for exact hypergeometric calculations where applicable, which greatly speeds up `Arc.length()`.
• deprecated The `write_xml` and `string_xml` methods were introduced around version 1.9.0, standardizing how SVG objects are serialized. While not strictly a 'breaking' change for existing code that didn't use this functionality, the internal structure for writing XML was significantly re-factored. Relying on pre-1.9.0 implicit XML generation methods may lead to unexpected behavior or missing features.
  Fix: Adopt `SVG.write_xml(filename)` or `SVG.string_xml()` for consistent and supported SVG output generation. Review the `1.9.0` release notes for detailed changes.
• gotcha Loading embedded images within SVG files using `SVGImage` objects implicitly requires the `Pillow` (PIL fork) library. If `Pillow` is not installed, image loading within parsed SVGs will fail silently or raise errors related to missing image handling.
  Fix: Ensure `Pillow` is installed if your SVG files contain embedded images: `pip install Pillow`.
• gotcha The `SVG.parse()` method accepts `width`, `height`, and `ppi` parameters. These values are crucial for correctly interpreting relative SVG units (like percentages) and converting between different unit systems, as the SVG specification itself does not directly define a 'physical' view size or pixels per inch.
  Fix: When parsing SVGs, especially those with relative units or for specific display contexts, provide accurate `width`, `height`, and `ppi` (defaults to 96) values to `SVG.parse()` to ensure correct scaling and geometry interpretation.

Install

• pip install svgelements Install latest version

Imports

• SVG
  wrong:

  from svg.elements import SVG

  correct:

  from svgelements import SVG

  The project was renamed from 'svg.elements' to 'svgelements' around version 0.7.6/1.0.0. Older import paths will fail.
• *

  from svgelements import *

  Commonly used for quick access to all core elements like SVG, Path, Matrix, Rect, etc.

Quickstart

This quickstart demonstrates how to parse an existing SVG string and iterate through its elements. It also shows how to programmatically create an SVG document with basic shapes (Rect, Group) and save it to a file or retrieve its XML as a string. The `SVG.parse()` method can take a file path, file-like object, or string stream. The `write_xml()` and `string_xml()` methods are available for generating SVG output.

from svgelements import SVG, Rect, Group
import io

# Example 1: Parse an SVG string
svg_string = '''<svg width="100" height="100">
  <rect x="10" y="10" width="80" height="80" fill="red" />
</svg>'''
svg_doc = SVG.parse(io.StringIO(svg_string))
print(f"Parsed SVG root element: {svg_doc.xml_tag}")
for element in svg_doc.elements():
    if isinstance(element, Rect):
        print(f"  Found Rect: x={element.x}, y={element.y}, width={element.width}, height={element.height}, fill={element.fill}")

# Example 2: Create an SVG programmatically and write to a file
new_svg = SVG()
new_svg.append(Rect(x=0, y=0, width="2in", height="2in", fill="blue", stroke="black"))
new_svg.append(Group(id="my_group").add(Rect(x=10, y=10, width=30, height=30, fill="green")))

# Save to a temporary file
output_filename = "output.svg"
new_svg.write_xml(output_filename)
print(f"Generated SVG saved to {output_filename}")

# You can also get the XML as a string
svg_output_string = new_svg.string_xml()
print("\nGenerated SVG string:\n" + svg_output_string)

# Clean up the created file
import os
if os.path.exists(output_filename):
    os.remove(output_filename)
    print(f"Cleaned up {output_filename}")