Skip to content

PNG and PDF Export

pyDEXPI uses SVG as the native export format for P&ID diagrams. PNG and PDF files are produced by converting the generated SVG — the SVG rendering logic is never reimplemented.

Quick start

from pydexpi.loaders import xml_serializer
from pydexpi.exports.svg_export import DrawDiagram

serializer = xml_serializer.DexpiXmlSerializer()
model = serializer.load("data", "reference_pid")

diagram = model.diagram
drawer = DrawDiagram(diagram=diagram)

# SVG — always available, no extra dependencies
drawer.save_svg(diagram.name, "output/my_pid.svg")

# PNG — requires the [png] extra
drawer.save_png(diagram.name, "output/my_pid.png")

# PDF — requires the [pdf] extra
drawer.save_pdf(diagram.name, "output/my_pid.pdf")

All three methods share the same signature:

def save_svg(self, object_name: str, filepath: str, background: bool = True) -> str: ...
def save_png(self, object_name: str, filepath: str, background: bool = True) -> str: ...
def save_pdf(self, object_name: str, filepath: str, background: bool = True) -> str: ...
Parameter Description
object_name Used to auto-generate the filename when filepath is a directory
filepath Target file path or directory (a filename is generated automatically)
background If True (default), add a light-grey background rectangle

Each method returns the absolute path to the saved file.

Installation

PNG and PDF backends are optional dependencies so they don't bloat the base install for users who only need the Python API or SVG export.

# PNG support (uses resvg — pure-Rust, no system C libraries needed)
pip install pydexpi[png]

# PDF support (uses svglib + reportlab — pure-Python)
pip install pydexpi[pdf]

# Both at once
pip install pydexpi[export]

If you call save_png() or save_pdf() without the required extra installed, a clear ImportError is raised with install instructions:

ImportError: PNG export requires the 'resvg' package.
Install it with:  pip install pydexpi[png]

How it works

┌──────────────┐      draw_svg()      ┌──────────┐
│  DEXPI Model │  ─────────────────►  │ SVG text │
└──────────────┘                      └────┬─────┘
                                           │
                          ┌────────────────┼────────────────┐
                          │                │                │
                     save_svg()       svg_to_png()     svg_to_pdf()
                          │           (resvg)         (svglib+reportlab)
                          ▼                ▼                ▼
                       .svg file       .png file        .pdf file
  1. draw_svg() generates the SVG string using the existing renderer.
  2. save_png() / save_pdf() call draw_svg() internally, then pass the string through the appropriate converter.
  3. The conversion layer lives in pydexpi/exports/png_export.py (PNG) and pydexpi/exports/pdf_export.py (PDF).

Why no JPG/JPEG?

JPEG is a lossy format optimised for photographs. Engineering line drawings contain sharp edges, thin lines, and text that degrade badly under JPEG compression. PNG (lossless) and PDF (vector) are both superior choices for P&ID output.

Backend choices

Format Backend Why
PNG resvg Pure-Rust with Python bindings. No system C library needed — installs cleanly on Linux, macOS, and Windows via pip.
PDF svglib + reportlab Pure-Python. No Cairo or system library dependency.

CairoSVG was deliberately avoided because it requires the Cairo C library, which is notoriously difficult to install on Windows.

Platform compatibility

Backend Linux macOS Windows
resvg ✅ wheels available ✅ wheels available ✅ wheels available
svglib + reportlab ✅ pure-Python ✅ pure-Python ✅ pure-Python

Both backends install with a simple pip install on all major platforms.

Degenerate element handling

Some DEXPI files contain ShapeUsage elements with near-zero scale factors (e.g. scaleX=0.0001, scaleY=0.0001). These would produce scale(0.00,0.00) in the SVG (due to %.2f formatting), creating non-invertible transforms that crash renderers like reportlab.

pyDEXPI automatically skips these degenerate elements during SVG generation. If an externally generated SVG containing such transforms is passed to svg_to_pdf(), a clear ValueError is raised instead of an unhandled ZeroDivisionError.

Limitations

  • SVG feature coverage — svglib does not support every SVG feature. Complex SVGs with advanced CSS, filters, or animations may not convert perfectly to PDF. For the SVGs produced by pyDEXPI (simple geometric primitives and text) this is generally not an issue.
  • PNG resolution — resvg renders at the pixel dimensions specified in the SVG width/height attributes. For higher-resolution PNGs, increase the SVG dimensions before export (e.g., using the pretty mode which scales to A3).
  • svglib transitive dependency — svglib declares a dependency on rlpycairo, which may attempt to install pycairo (requiring the Cairo C library). In practice, svglib works without Cairo for the SVG features used by pyDEXPI. If pip install pydexpi[pdf] fails due to Cairo, install with pip install svglib --no-deps && pip install reportlab.