weasyvsdx 0.1.0__tar.gz

weasyvsdx-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+
+# Ruff
+.ruff_cache/
+coverage.xml
+
+# Visual regression bench output
+tools/visual/out/

weasyvsdx-0.1.0/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-24
+
+### Added
+
+- Visio drawings (VSDX, VSDM, VSD and the templates and stencils of Visio) render in WeasyPrint as vector
+  SVG: an `<img>`, `<object>` or `<embed>`, a CSS image, an `<image>` inside an SVG. `vsd2xhtml` of
+  libvisio draws the first page. An untyped response is a drawing by the suffix of its URL, before or after
+  a redirect.
+- The text of a drawing wraps and aligns as in Visio: each text block is HTML in a `<foreignObject>`, from
+  the output of `vsd2raw`, with its padding, vertical alignment, rotation, paragraphs, bullets and fonts,
+  and the character scale of Visio, which widens the glyphs.
+- Arrowheads take their own shape and size, and a line under one ends at its base, as in Visio. A hollow
+  one hides the line under it.
+- A shape on a hidden or non-printing layer is left out, as in Visio.
+- The text a shape of a VSDX hides is left out: the names of the Azure icons no longer show under them.
+- Black behind dark text, which libvisio reads from a palette color, draws white: labels no longer show as
+  black bars.
+- A text with a line break of Visio (U+2028) shows, broken at it, instead of going missing.
+- A bitmap inside an EMF that Office draws flipped no longer shows mirrored.
+- A fill pattern draws as hatch lines, on the fill color where it has one, instead of black.
+- A shape of a VSDX that fills with a gradient of Visio 2013 or later gets it, linear or radial, instead of
+  black: the icons of Azure show in color.
+- A shape of a VSDX that inherits its geometry from a master group draws, from the XML of the master:
+  libvisio drew nothing for it, and parts of the Azure icons went missing.
+- A text block of no width or height is as wide and as high as its text and never wraps, as in Visio.
+- A path that libvisio writes without a leading moveto starts at the end of its first segment, not at the
+  corner of the page.
+- EMF images become SVG through `emf2svg-conv`, and so does the EMF that Office puts inside a WMF image,
+  and the picture an embedded OLE object shows.
+- The tools run in processes of their own, with a timeout and, on Linux, limits on memory and output.
+  The EMF images of a page share one timeout.
+  A drawing that does not convert renders as a broken image.
+- A drawing that libvisio draws as a page of no size renders as a broken image.
+- `install()` warns when `vsd2xhtml` reports another libvisio than 0.1.7, the release weasyvsdx is tested
+  with: 0.1.8 to 0.1.11 fill the shapes of a VSDX with the colors of its theme over their own.
+- A font of Microsoft that the system lacks falls back to its free replacement: Calibri to Carlito, Cambria to
+  Caladea, Segoe UI to Selawik.
+- A comparison page on GitHub Pages shows each drawing of the corpus in LibreOffice, as libvisio writes it,
+  and in weasyvsdx.
+- The bench also compares the Azure diagrams with the SVG that Visio exported for their article.
+  LibreOffice reads them through libvisio and shares its errors.

weasyvsdx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergey Grigoriev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

weasyvsdx-0.1.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.5
+Name: weasyvsdx
+Version: 0.1.0
+Summary: Visio drawings (VSDX, VSD) for WeasyPrint, drawn as vector SVG through libvisio.
+Project-URL: Homepage, https://github.com/grigoriev/weasyvsdx
+Project-URL: Repository, https://github.com/grigoriev/weasyvsdx
+Project-URL: Issues, https://github.com/grigoriev/weasyvsdx/issues
+Author-email: Sergey Grigoriev <grigoriev@fastmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
+Classifier: Topic :: Printing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: olefile>=0.47
+Requires-Dist: weasyprint<71,>=70
+Requires-Dist: weasysvg>=0.3.1
+Provides-Extra: dev
+Requires-Dist: mypy==2.4.0; extra == 'dev'
+Requires-Dist: pypdfium2==5.14.0; extra == 'dev'
+Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
+Requires-Dist: pytest==9.1.1; extra == 'dev'
+Requires-Dist: ruff==0.17.2; extra == 'dev'
+Provides-Extra: visual
+Requires-Dist: numpy==2.5.4; (python_version >= '3.12') and extra == 'visual'
+Description-Content-Type: text/markdown
+
+# weasyvsdx
+
+[![CI](https://github.com/grigoriev/weasyvsdx/actions/workflows/ci.yml/badge.svg)](https://github.com/grigoriev/weasyvsdx/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/grigoriev/weasyvsdx/badge)](https://scorecard.dev/viewer/?uri=github.com/grigoriev/weasyvsdx)
+[![Release](https://img.shields.io/github/v/release/grigoriev/weasyvsdx)](https://github.com/grigoriev/weasyvsdx/releases)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/grigoriev/weasyvsdx/blob/main/LICENSE)
+
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=grigoriev_weasyvsdx&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=grigoriev_weasyvsdx)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=grigoriev_weasyvsdx&metric=coverage)](https://sonarcloud.io/summary/new_code?id=grigoriev_weasyvsdx)
+
+A plugin for [WeasyPrint](https://weasyprint.org) 70.x that draws Microsoft Visio drawings (VSDX, VSD) as
+vector SVG, through [libvisio](https://github.com/LibreOffice/libvisio).
+
+## Why?
+
+WeasyPrint cannot read Visio drawings. Services that turn HTML into PDF convert them with LibreOffice
+first, to a PNG. LibreOffice adds some 730 MB to an image and hundreds of findings to its scans, and the
+drawing ends up as pixels.
+
+weasyvsdx hands each drawing to the tools of libvisio, the library LibreOffice itself imports Visio with,
+and draws the result as SVG inside WeasyPrint. The drawing stays vector and its text stays selectable. The
+tools take some 41 MB on Debian.
+
+## Installation
+
+weasyvsdx runs on CPython 3.11 to 3.14.
+
+Install the tools of libvisio, and emf2svg for the EMF images that many drawings hold. On Debian 13 and
+Ubuntu 24.04, which have the libvisio weasyvsdx needs (see "libvisio version"):
+
+```sh
+apt-get install libvisio-tools emf2svg
+```
+
+Then install weasyvsdx from PyPI:
+
+```sh
+pip install weasyvsdx
+```
+
+weasyvsdx depends on WeasyPrint and on [weasysvg](https://github.com/grigoriev/weasysvg), which draws the
+text of the drawings. WeasyPrint needs Pango, see its
+[installation guide](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html).
+
+### libvisio version
+
+Use libvisio 0.1.7. The tests and the bench run with it, and `install()` warns on any other release.
+libvisio 0.1.8 to 0.1.11, the latest, fill the shapes of a VSDX with the colors of its theme over their own
+colors: on the Azure diagrams of the bench, icons turn into olive disks and subnets into olive boxes.
+
+| Distribution | libvisio |
+|---|---|
+| Debian 13 (trixie) | 0.1.7 |
+| Ubuntu 24.04 | 0.1.7 |
+| Debian testing, unstable | 0.1.11 |
+| Ubuntu 26.04 | 0.1.10 |
+| Alpine 3.22, 3.23 | 0.1.8 |
+| Wolfi | none |
+
+To keep it, pin the release of the base image, for example `python:3.14-slim-trixie`, and check it at
+build time:
+
+```sh
+test "$(vsd2xhtml --version)" = "vsd2xhtml 0.1.7"
+```
+
+libvisio 0.1.9 and later also read the text background of a VSD, which 0.1.7 reads as black. weasyvsdx
+draws black behind dark text as white, the most common background, so the labels show. A colored
+background draws white as well.
+
+### Verify
+
+The build of each release has signed provenance on GitHub, and the GitHub release carries its bundle.
+PyPI and the GitHub release hold the same files, so verify a file from either with
+`gh attestation verify <file> --repo grigoriev/weasyvsdx`. On PyPI each file also has a publish
+attestation (PEP 740): it ties the upload to `release.yml` of this repository.
+
+## Usage
+
+Call `install()` once, before the first rendering:
+
+```python
+import weasyprint
+import weasyvsdx
+
+weasyvsdx.install()
+weasyprint.HTML(string='<img src="plan.vsdx">', base_url=".").write_pdf("plan.pdf")
+```
+
+An image renders as a Visio drawing when its media type says so, `application/vnd.ms-visio.drawing` for
+VSDX or `application/vnd.visio` for VSD, or when a file or URL without a type ends in `.vsdx`, `.vsd` or
+another Visio suffix. A data URL counts by its type alone. This works for `<img>`, `<object>`, `<embed>`,
+CSS images and `<image>` inside an SVG.
+
+`install()` patches WeasyPrint in place, for the whole process, and returns the path of `vsd2xhtml`. It
+raises `ConverterNotFoundError` when `vsd2xhtml` is not on the PATH. A later call changes the settings.
+
+| Argument | Default | Effect |
+|---|---|---|
+| `converter` | `"vsd2xhtml"` | the `vsd2xhtml` to run, a name on the PATH or a path |
+| `text` | `True` | lay the text out anew from `vsd2raw`, next to `vsd2xhtml`; installs weasysvg with its defaults unless its `foreign_object` is installed |
+| `emf` | `True` | turn EMF images into SVG through `emf2svg-conv`, where it is on the PATH |
+| `timeout` | `30.0` | seconds one run of a tool may take |
+| `max_input_mb` | `64` | the largest drawing, in MB |
+| `max_output_mb` | `256` | the most a tool may write, in MB (Linux) |
+| `max_memory_mb` | `2048` | the address space of each tool, in MB (Linux) |
+
+A drawing that does not convert, or that passes a limit, renders as a broken image: WeasyPrint logs the
+error and leaves it out, and the rest of the document renders.
+
+## Fonts
+
+Visio drawings ask for fonts of Microsoft, Segoe UI and Calibri most. weasyvsdx names a free replacement
+after each, so an installed original still wins:
+
+| Font | Replacement | Debian package |
+|---|---|---|
+| Calibri | Carlito, same metrics | `fonts-crosextra-carlito` |
+| Cambria | Caladea, same metrics | `fonts-crosextra-caladea` |
+| Segoe UI, Light, Semilight, Semibold | Selawik, close, not equal | none: the [release of microsoft/Selawik](https://github.com/microsoft/Selawik/releases) |
+
+Without them, text falls back to the sans-serif font of the system, which breaks lines elsewhere than Visio.
+Where the license allows it, install the original fonts instead.
+
+## How it works
+
+1. `vsd2xhtml` of libvisio writes each page of the drawing as SVG. weasyvsdx takes the first page, as
+   LibreOffice does.
+2. The generic SVG generator behind `vsd2xhtml` drops part of what libvisio reads. `vsd2raw` prints the
+   same calls with all their properties, and weasyvsdx takes the rest from there:
+   - **Text**: each text block becomes a `<foreignObject>` of its size, with its padding, vertical
+     alignment and rotation, and its paragraphs and spans as HTML: alignment, line spacing, indents, bullets,
+     font, size, scale, weight, style, color, underline, highlight, super- and subscript. WeasyPrint lays it out,
+     so labels wrap inside their shapes as in Visio. The generator wrote each text as one line at the left
+     edge of its block.
+   - **Arrowheads**: each marker gets the shape and size of its line end. The generator drew one stock
+     arrow for all of them, sized by the width of the line.
+   - **Hidden shapes**: a shape on a hidden or non-printing layer goes. The generator drew it.
+   - **Hidden text**: the text a shape of a VSDX hides (HideText, or a text cleared on the shape) goes. The
+     generator wrote the name of each Azure icon under it.
+   - **Hatches**: a fill pattern of Visio draws as the lines of its hatch. The generator filled it black.
+   - **Gradients**: a shape of a VSDX that fills with a gradient of Visio 2013 or later gets it, linear or
+     radial, from the XML of the page, its masters and styles. libvisio reads none, and filled it black.
+   - **Shapes of master groups**: a shape of a VSDX that inherits its geometry from a master group is drawn
+     from the XML of the master, with its fill, line, dashes and gradient. libvisio drew nothing for it, and
+     parts of the Azure icons went missing.
+   - **Line ends**: a line under an arrowhead ends at its base, as in Visio, not at its tip.
+3. EMF images become SVG through `emf2svg-conv`, and so does the EMF that Office puts inside a WMF image,
+   and the picture an embedded OLE object shows.
+   WeasyPrint reads neither, and left them out.
+4. A path that starts without a moveto loses its first segment, whose start libvisio does not give. Drawn as
+   it was, it ran from the corner of the page.
+
+The tools parse untrusted input in C, and a broken file can crash them. Each runs in a process of its own,
+in a temporary directory, with a time limit and, on Linux, limits on its memory and its output.
+`vsd2xhtml` and `vsd2raw` run at the same time. The SVG then goes through WeasyPrint like any other SVG,
+and every URL inside it through the URL fetcher of the caller.
+
+## How it compares to LibreOffice and Visio
+
+The bench in [`tools/visual`](https://github.com/grigoriev/weasyvsdx/tree/main/tools/visual) renders 291
+drawings and compares each with its PNG export by LibreOffice 25.2:
+
+- the 41 test drawings of libvisio, Apache POI and LibreOffice in [`corpus/visio`](https://github.com/grigoriev/weasyvsdx/tree/main/corpus/visio);
+- the 250 Visio diagrams of the Azure Architecture Center, which the bench downloads into a cache: their
+  icons may not be copied into this repository, see [`corpus/SOURCES.md`](https://github.com/grigoriev/weasyvsdx/blob/main/corpus/SOURCES.md).
+
+The [comparison page](https://grigoriev.github.io/weasyvsdx/corpus/comparison.html) shows each drawing of the
+corpus in LibreOffice, as libvisio writes it, and in weasyvsdx, side by side, with a swipe between any two;
+[`corpus/COMPARISON.md`](https://github.com/grigoriev/weasyvsdx/blob/main/corpus/COMPARISON.md) holds the same in the repository. The Azure
+diagrams are not on it: their icons may not be redistributed.
+
+All but two convert: libvisio crashes on `recursion-cycle.vsdx` and refuses `tab-short-prefix.vsdx`, two
+of its tests that are broken on purpose. LibreOffice fails on the same two. Geometry, fills, gradients,
+dashes, arrowheads and images match. The text differs most, and LibreOffice is no exact reference for it:
+it lays text out with fonts of its own choice, and breaks words in narrow blocks where Visio does not. On
+some drawings LibreOffice is wrong where weasyvsdx is right, for example it fills the whole of
+`netapp-files-moodle-zonal` blue.
+
+LibreOffice reads the drawings through libvisio, as weasyvsdx does, and shares its errors. So the bench
+also compares 206 Azure diagrams with the SVG that Visio exported for their article. The median mismatch
+is 25.0% against Visio, 49.5% against LibreOffice: weasyvsdx draws the gradients and the master
+shapes of the Azure icons, which LibreOffice fills black or leaves out. Much of the rest is the icons of Azure, see "Known gaps".
+
+The median Azure diagram converts in 0.08 s, and 9 in 10 in less than 0.5 s. Drawings that embed bitmaps
+of tens of MB take seconds, 17 of the 250 more than one: libvisio writes the bitmaps out as base64. One,
+`adaptive-apps`, takes 46 s, more than the default timeout of 30 s: it converts only with a larger `timeout`.
+
+## Known gaps
+
+- A shape whose ID another shape that libvisio draws shares keeps what libvisio drew: no gradient, and no
+  geometry from its master. So do the shapes of a VSD, gradients of the rarer kinds (FillGradientDir 8 to
+  13) and colors of the theme of a drawing.
+- Only the first page renders. LibreOffice and the converters before it did the same.
+- Visio drawings ask for Calibri and Segoe UI most, fonts of Microsoft. A font the system lacks falls back
+  to its free replacement, else to sans-serif: Calibri to Carlito and Cambria to Caladea, which share their
+  metrics, so text breaks where Visio breaks it; Segoe UI to Selawik, the open fallback of Microsoft, close
+  to it but not equal. Install them, see "Fonts".
+- Character scaling (the "Scale" of a Visio font) applies where all text of a block shares one scale; a block
+  of mixed scales draws unscaled. Fields show the value libvisio formats.
+- A WMF image without an EMF inside is left out, and so is an embedded OLE object whose picture is no EMF.
+  Office writes the EMF into each WMF it saves, and into the picture of each OLE object.
+- Text that a VSD hides stays: only a VSDX holds HideText where weasyvsdx reads it.
+- A shape on a hidden or non-printing layer goes, but its text would stay: libvisio marks the path of
+  such a shape as hidden, not its text.
+- An EMF draws its GDI records only. Part of an icon that Office drew in EMF+ alone, the newer records an EMF
+  can carry in its comments, stays out: `emf2svg-conv` does not read EMF+, LibreOffice does.
+
+## Development
+
+Tests and the bench run in Docker, since WeasyPrint needs Pango and weasyvsdx the tools of libvisio. See
+[CONTRIBUTING.md](https://github.com/grigoriev/weasyvsdx/blob/main/CONTRIBUTING.md).
+
+```sh
+make lint     # ruff and mypy, on the host
+make test     # pytest with coverage, in Docker
+make visual   # the visual bench, report in tools/visual/out/report.html
+make comparison # corpus/COMPARISON.md and corpus/comparison.html, the panels in corpus/render
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/grigoriev/weasyvsdx/blob/main/CONTRIBUTING.md). Report vulnerabilities privately, see [SECURITY.md](https://github.com/grigoriev/weasyvsdx/blob/main/SECURITY.md).
+
+## Disclaimer
+
+This software is provided "as is", without warranty of any kind, as the LICENSE states. Use
+it at your own risk. Sergey Grigoriev is not liable for damage from its use, as far as the law
+allows. It is published free of charge, outside of any commercial offering, with no
+obligation to support it. Security reports are welcome, see [SECURITY.md](https://github.com/grigoriev/weasyvsdx/blob/main/SECURITY.md).
+
+## License
+
+MIT, see [LICENSE](https://github.com/grigoriev/weasyvsdx/blob/main/LICENSE). The test corpus keeps the licenses of its sources, see
+[corpus/SOURCES.md](https://github.com/grigoriev/weasyvsdx/blob/main/corpus/SOURCES.md).

weasyvsdx-0.1.0/README.md

@@ -0,0 +1,238 @@
+# weasyvsdx
+
+[![CI](https://github.com/grigoriev/weasyvsdx/actions/workflows/ci.yml/badge.svg)](https://github.com/grigoriev/weasyvsdx/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/grigoriev/weasyvsdx/badge)](https://scorecard.dev/viewer/?uri=github.com/grigoriev/weasyvsdx)
+[![Release](https://img.shields.io/github/v/release/grigoriev/weasyvsdx)](https://github.com/grigoriev/weasyvsdx/releases)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/grigoriev/weasyvsdx/blob/main/LICENSE)
+
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=grigoriev_weasyvsdx&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=grigoriev_weasyvsdx)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=grigoriev_weasyvsdx&metric=coverage)](https://sonarcloud.io/summary/new_code?id=grigoriev_weasyvsdx)
+
+A plugin for [WeasyPrint](https://weasyprint.org) 70.x that draws Microsoft Visio drawings (VSDX, VSD) as
+vector SVG, through [libvisio](https://github.com/LibreOffice/libvisio).
+
+## Why?
+
+WeasyPrint cannot read Visio drawings. Services that turn HTML into PDF convert them with LibreOffice
+first, to a PNG. LibreOffice adds some 730 MB to an image and hundreds of findings to its scans, and the
+drawing ends up as pixels.
+
+weasyvsdx hands each drawing to the tools of libvisio, the library LibreOffice itself imports Visio with,
+and draws the result as SVG inside WeasyPrint. The drawing stays vector and its text stays selectable. The
+tools take some 41 MB on Debian.
+
+## Installation
+
+weasyvsdx runs on CPython 3.11 to 3.14.
+
+Install the tools of libvisio, and emf2svg for the EMF images that many drawings hold. On Debian 13 and
+Ubuntu 24.04, which have the libvisio weasyvsdx needs (see "libvisio version"):
+
+```sh
+apt-get install libvisio-tools emf2svg
+```
+
+Then install weasyvsdx from PyPI:
+
+```sh
+pip install weasyvsdx
+```
+
+weasyvsdx depends on WeasyPrint and on [weasysvg](https://github.com/grigoriev/weasysvg), which draws the
+text of the drawings. WeasyPrint needs Pango, see its
+[installation guide](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html).
+
+### libvisio version
+
+Use libvisio 0.1.7. The tests and the bench run with it, and `install()` warns on any other release.
+libvisio 0.1.8 to 0.1.11, the latest, fill the shapes of a VSDX with the colors of its theme over their own
+colors: on the Azure diagrams of the bench, icons turn into olive disks and subnets into olive boxes.
+
+| Distribution | libvisio |
+|---|---|
+| Debian 13 (trixie) | 0.1.7 |
+| Ubuntu 24.04 | 0.1.7 |
+| Debian testing, unstable | 0.1.11 |
+| Ubuntu 26.04 | 0.1.10 |
+| Alpine 3.22, 3.23 | 0.1.8 |
+| Wolfi | none |
+
+To keep it, pin the release of the base image, for example `python:3.14-slim-trixie`, and check it at
+build time:
+
+```sh
+test "$(vsd2xhtml --version)" = "vsd2xhtml 0.1.7"
+```
+
+libvisio 0.1.9 and later also read the text background of a VSD, which 0.1.7 reads as black. weasyvsdx
+draws black behind dark text as white, the most common background, so the labels show. A colored
+background draws white as well.
+
+### Verify
+
+The build of each release has signed provenance on GitHub, and the GitHub release carries its bundle.
+PyPI and the GitHub release hold the same files, so verify a file from either with
+`gh attestation verify <file> --repo grigoriev/weasyvsdx`. On PyPI each file also has a publish
+attestation (PEP 740): it ties the upload to `release.yml` of this repository.
+
+## Usage
+
+Call `install()` once, before the first rendering:
+
+```python
+import weasyprint
+import weasyvsdx
+
+weasyvsdx.install()
+weasyprint.HTML(string='<img src="plan.vsdx">', base_url=".").write_pdf("plan.pdf")
+```
+
+An image renders as a Visio drawing when its media type says so, `application/vnd.ms-visio.drawing` for
+VSDX or `application/vnd.visio` for VSD, or when a file or URL without a type ends in `.vsdx`, `.vsd` or
+another Visio suffix. A data URL counts by its type alone. This works for `<img>`, `<object>`, `<embed>`,
+CSS images and `<image>` inside an SVG.
+
+`install()` patches WeasyPrint in place, for the whole process, and returns the path of `vsd2xhtml`. It
+raises `ConverterNotFoundError` when `vsd2xhtml` is not on the PATH. A later call changes the settings.
+
+| Argument | Default | Effect |
+|---|---|---|
+| `converter` | `"vsd2xhtml"` | the `vsd2xhtml` to run, a name on the PATH or a path |
+| `text` | `True` | lay the text out anew from `vsd2raw`, next to `vsd2xhtml`; installs weasysvg with its defaults unless its `foreign_object` is installed |
+| `emf` | `True` | turn EMF images into SVG through `emf2svg-conv`, where it is on the PATH |
+| `timeout` | `30.0` | seconds one run of a tool may take |
+| `max_input_mb` | `64` | the largest drawing, in MB |
+| `max_output_mb` | `256` | the most a tool may write, in MB (Linux) |
+| `max_memory_mb` | `2048` | the address space of each tool, in MB (Linux) |
+
+A drawing that does not convert, or that passes a limit, renders as a broken image: WeasyPrint logs the
+error and leaves it out, and the rest of the document renders.
+
+## Fonts
+
+Visio drawings ask for fonts of Microsoft, Segoe UI and Calibri most. weasyvsdx names a free replacement
+after each, so an installed original still wins:
+
+| Font | Replacement | Debian package |
+|---|---|---|
+| Calibri | Carlito, same metrics | `fonts-crosextra-carlito` |
+| Cambria | Caladea, same metrics | `fonts-crosextra-caladea` |
+| Segoe UI, Light, Semilight, Semibold | Selawik, close, not equal | none: the [release of microsoft/Selawik](https://github.com/microsoft/Selawik/releases) |
+
+Without them, text falls back to the sans-serif font of the system, which breaks lines elsewhere than Visio.
+Where the license allows it, install the original fonts instead.
+
+## How it works
+
+1. `vsd2xhtml` of libvisio writes each page of the drawing as SVG. weasyvsdx takes the first page, as
+   LibreOffice does.
+2. The generic SVG generator behind `vsd2xhtml` drops part of what libvisio reads. `vsd2raw` prints the
+   same calls with all their properties, and weasyvsdx takes the rest from there:
+   - **Text**: each text block becomes a `<foreignObject>` of its size, with its padding, vertical
+     alignment and rotation, and its paragraphs and spans as HTML: alignment, line spacing, indents, bullets,
+     font, size, scale, weight, style, color, underline, highlight, super- and subscript. WeasyPrint lays it out,
+     so labels wrap inside their shapes as in Visio. The generator wrote each text as one line at the left
+     edge of its block.
+   - **Arrowheads**: each marker gets the shape and size of its line end. The generator drew one stock
+     arrow for all of them, sized by the width of the line.
+   - **Hidden shapes**: a shape on a hidden or non-printing layer goes. The generator drew it.
+   - **Hidden text**: the text a shape of a VSDX hides (HideText, or a text cleared on the shape) goes. The
+     generator wrote the name of each Azure icon under it.
+   - **Hatches**: a fill pattern of Visio draws as the lines of its hatch. The generator filled it black.
+   - **Gradients**: a shape of a VSDX that fills with a gradient of Visio 2013 or later gets it, linear or
+     radial, from the XML of the page, its masters and styles. libvisio reads none, and filled it black.
+   - **Shapes of master groups**: a shape of a VSDX that inherits its geometry from a master group is drawn
+     from the XML of the master, with its fill, line, dashes and gradient. libvisio drew nothing for it, and
+     parts of the Azure icons went missing.
+   - **Line ends**: a line under an arrowhead ends at its base, as in Visio, not at its tip.
+3. EMF images become SVG through `emf2svg-conv`, and so does the EMF that Office puts inside a WMF image,
+   and the picture an embedded OLE object shows.
+   WeasyPrint reads neither, and left them out.
+4. A path that starts without a moveto loses its first segment, whose start libvisio does not give. Drawn as
+   it was, it ran from the corner of the page.
+
+The tools parse untrusted input in C, and a broken file can crash them. Each runs in a process of its own,
+in a temporary directory, with a time limit and, on Linux, limits on its memory and its output.
+`vsd2xhtml` and `vsd2raw` run at the same time. The SVG then goes through WeasyPrint like any other SVG,
+and every URL inside it through the URL fetcher of the caller.
+
+## How it compares to LibreOffice and Visio
+
+The bench in [`tools/visual`](https://github.com/grigoriev/weasyvsdx/tree/main/tools/visual) renders 291
+drawings and compares each with its PNG export by LibreOffice 25.2:
+
+- the 41 test drawings of libvisio, Apache POI and LibreOffice in [`corpus/visio`](https://github.com/grigoriev/weasyvsdx/tree/main/corpus/visio);
+- the 250 Visio diagrams of the Azure Architecture Center, which the bench downloads into a cache: their
+  icons may not be copied into this repository, see [`corpus/SOURCES.md`](https://github.com/grigoriev/weasyvsdx/blob/main/corpus/SOURCES.md).
+
+The [comparison page](https://grigoriev.github.io/weasyvsdx/corpus/comparison.html) shows each drawing of the
+corpus in LibreOffice, as libvisio writes it, and in weasyvsdx, side by side, with a swipe between any two;
+[`corpus/COMPARISON.md`](https://github.com/grigoriev/weasyvsdx/blob/main/corpus/COMPARISON.md) holds the same in the repository. The Azure
+diagrams are not on it: their icons may not be redistributed.
+
+All but two convert: libvisio crashes on `recursion-cycle.vsdx` and refuses `tab-short-prefix.vsdx`, two
+of its tests that are broken on purpose. LibreOffice fails on the same two. Geometry, fills, gradients,
+dashes, arrowheads and images match. The text differs most, and LibreOffice is no exact reference for it:
+it lays text out with fonts of its own choice, and breaks words in narrow blocks where Visio does not. On
+some drawings LibreOffice is wrong where weasyvsdx is right, for example it fills the whole of
+`netapp-files-moodle-zonal` blue.
+
+LibreOffice reads the drawings through libvisio, as weasyvsdx does, and shares its errors. So the bench
+also compares 206 Azure diagrams with the SVG that Visio exported for their article. The median mismatch
+is 25.0% against Visio, 49.5% against LibreOffice: weasyvsdx draws the gradients and the master
+shapes of the Azure icons, which LibreOffice fills black or leaves out. Much of the rest is the icons of Azure, see "Known gaps".
+
+The median Azure diagram converts in 0.08 s, and 9 in 10 in less than 0.5 s. Drawings that embed bitmaps
+of tens of MB take seconds, 17 of the 250 more than one: libvisio writes the bitmaps out as base64. One,
+`adaptive-apps`, takes 46 s, more than the default timeout of 30 s: it converts only with a larger `timeout`.
+
+## Known gaps
+
+- A shape whose ID another shape that libvisio draws shares keeps what libvisio drew: no gradient, and no
+  geometry from its master. So do the shapes of a VSD, gradients of the rarer kinds (FillGradientDir 8 to
+  13) and colors of the theme of a drawing.
+- Only the first page renders. LibreOffice and the converters before it did the same.
+- Visio drawings ask for Calibri and Segoe UI most, fonts of Microsoft. A font the system lacks falls back
+  to its free replacement, else to sans-serif: Calibri to Carlito and Cambria to Caladea, which share their
+  metrics, so text breaks where Visio breaks it; Segoe UI to Selawik, the open fallback of Microsoft, close
+  to it but not equal. Install them, see "Fonts".
+- Character scaling (the "Scale" of a Visio font) applies where all text of a block shares one scale; a block
+  of mixed scales draws unscaled. Fields show the value libvisio formats.
+- A WMF image without an EMF inside is left out, and so is an embedded OLE object whose picture is no EMF.
+  Office writes the EMF into each WMF it saves, and into the picture of each OLE object.
+- Text that a VSD hides stays: only a VSDX holds HideText where weasyvsdx reads it.
+- A shape on a hidden or non-printing layer goes, but its text would stay: libvisio marks the path of
+  such a shape as hidden, not its text.
+- An EMF draws its GDI records only. Part of an icon that Office drew in EMF+ alone, the newer records an EMF
+  can carry in its comments, stays out: `emf2svg-conv` does not read EMF+, LibreOffice does.
+
+## Development
+
+Tests and the bench run in Docker, since WeasyPrint needs Pango and weasyvsdx the tools of libvisio. See
+[CONTRIBUTING.md](https://github.com/grigoriev/weasyvsdx/blob/main/CONTRIBUTING.md).
+
+```sh
+make lint     # ruff and mypy, on the host
+make test     # pytest with coverage, in Docker
+make visual   # the visual bench, report in tools/visual/out/report.html
+make comparison # corpus/COMPARISON.md and corpus/comparison.html, the panels in corpus/render
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/grigoriev/weasyvsdx/blob/main/CONTRIBUTING.md). Report vulnerabilities privately, see [SECURITY.md](https://github.com/grigoriev/weasyvsdx/blob/main/SECURITY.md).
+
+## Disclaimer
+
+This software is provided "as is", without warranty of any kind, as the LICENSE states. Use
+it at your own risk. Sergey Grigoriev is not liable for damage from its use, as far as the law
+allows. It is published free of charge, outside of any commercial offering, with no
+obligation to support it. Security reports are welcome, see [SECURITY.md](https://github.com/grigoriev/weasyvsdx/blob/main/SECURITY.md).
+
+## License
+
+MIT, see [LICENSE](https://github.com/grigoriev/weasyvsdx/blob/main/LICENSE). The test corpus keeps the licenses of its sources, see
+[corpus/SOURCES.md](https://github.com/grigoriev/weasyvsdx/blob/main/corpus/SOURCES.md).