icplot
icplot makes diagrams and images for technical documents at
ICHEC. It converts between image formats, renders
text-based diagrams to images and applies a shared theme.
It also draws the branded diagrams in our READMEs and handbooks.
Install
pip install icplot
The core install is small. Add the extras for the backends you need:
| Extra | Installs | For |
|---|---|---|
cairo |
CairoSVG | SVG to PNG or PDF |
preview |
Playwright | PNG previews of diagrams, drawn by Chromium |
For example, pip install "icplot[cairo]". The cairo extra needs the cairo
library, and PDF to PNG needs ImageMagick's magick. On a Mac:
brew install imagemagick cairo
Convert an image
icplot convert --source my_image.svg --target my_image.png
icplot converts SVG to PNG or PDF, and PDF to PNG.
Render a diagram
icplot render uml_diagram.puml
This renders the PlantUML file to PNG and SVG. icplot also renders LaTeX and
TikZ, and Mermaid.
Render a folder of diagrams
Give icplot render a directory to render every diagram in it:
icplot render .
It reads render.yaml from the current directory, or the file you give with
--config. For example:
tex:
templates:
- styles
- templates
build_engine: dvisvgm
plantuml:
config_path: styles/puml-theme-platform.puml
excludes:
- styles
- templates
tex.templates adds directories to the TeX search path, so a diagram can load
the TikZ libraries in them. build_engine: dvisvgm renders TikZ straight to
SVG. plantuml.config_path applies a PlantUML theme to every diagram.
excludes lists directories not to render.
For reusable TikZ libraries, see templates/tikz.
Draw a branded diagram
icplot.diagram draws SVG diagrams in the ICHEC brand, such as the feature
maps and deployment flows in our READMEs and handbook. A diagram is a short
Python script that builds a Diagram and saves it. The SVG embeds its font, so
it looks the same in a browser, a GitLab README and a PDF.
from pathlib import Path
from icplot.diagram import BLUE, Diagram
d = Diagram(600, 300, "Example", "What the diagram shows, for screen readers")
d.card(24, 24, 220, 90)
d.icon("users", 40, 40)
d.text(72, 56, "Your users", 16, 700)
d.arrow([(244, 69), (340, 69)], BLUE)
d.logo(576, 240)
d.save(Path("example.svg"))
Keep a diagram's script beside its SVG, and commit both. Icons come from
Lucide and Simple Icons. Add
one with uv run scripts/vendor_icons.py lucide:<name> or
simple-icons:<name>.
Theme a diagram
The theme follows Material 3. ref tokens hold the raw colours, sizes and
fonts. sys tokens name what each is for, such as sys.color.outline, and
point at ref tokens.
To make the theme files, run:
icplot theme generate --output_dir styles/
This writes a TikZ library, tikzlibraryplatform.code.tex, and a PlantUML
theme, puml-theme-platform.puml. Don't edit them by hand. To change the
theme, copy theme.json from the package source, change it and pass it with
--theme.
To change one colour in one diagram, set it in that diagram. In TikZ, use
\platformthemeset{accent=FF5500}. In PlantUML, add a skinparam after
@startuml.
Don't theme colours that carry meaning in a notation, such as ArchiMate's layer colours.
Develop
uv run tox runs the checks CI runs. The tests call LaTeX, mmdc,
plantuml, magick and dot, and need the cairo library.
infra/Containerfile installs them, and CI runs the tests in that image. A
test fails, rather than skips, when its tool is missing.
- Keep tests in
test/, whichiccore.test_utilsexpects. - Use
cairocffifor Cairo.pycaironeeds a C compiler in the image. - Never import
icmesh, which depends on this package. - After changing
infra/Containerfile, run the manualimage-publishjob. The image must belinux/amd64, because the runners are.
Licence
Copyright 2026 Irish Centre for High End Computing. MIT licence, see
LICENSE.
Metadata
Release files for icplot 0.9.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| icplot-0.9.1.tar.gz | 128.3 kB | Without provenance | Details for icplot-0.9.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| icplot-0.9.1-py3-none-any.whl | Python 3 | none | any | Details for icplot-0.9.1-py3-none-any.whl |
Total release size: 314.2 kB
Release files / icplot-0.9.1.tar.gz
| Download URL | icplot-0.9.1.tar.gz |
|---|---|
| Size | 128.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a8821c529017ff6d4ad3ea3f6d82b93d40fa7223b44d55b5566080b53cf989bc
|
|
BLAKE2b-256 checksum How to use checksums |
95cc719be3865f800a2c0d7c450b640d57b289dce42c78fea18d4c15eb1e8c6b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.9
|
Release files / icplot-0.9.1-py3-none-any.whl
| Download URL | icplot-0.9.1-py3-none-any.whl |
|---|---|
| Size | 185.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
22b775cd30064fc7443835b9233fd85cf0fa8a111260358c93d660677a00d54a
|
|
BLAKE2b-256 checksum How to use checksums |
d79d841bca4429923494be75149e904041639ad38a64648e3c6eaf580fb433da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.9
|
Security for icplot 0.9.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.