Skip to main content

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/, which iccore.test_utils expects.
  • Use cairocffi for Cairo. pycairo needs a C compiler in the image.
  • Never import icmesh, which depends on this package.
  • After changing infra/Containerfile, run the manual image-publish job. The image must be linux/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)

Source distribution for icplot 0.9.1
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)

Table of built distributions (wheels) for icplot 0.9.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.9.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page