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. The 3D mesh and OpenFOAM code moved to icmesh, which is archived. Its released versions stay installable from PyPI.

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.

Licence

Copyright 2026 Irish Centre for High End Computing. MIT licence, see LICENSE.

Metadata

Release files for icplot 0.9.0

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.0
File Size Uploaded Provenance Actions
icplot-0.9.0.tar.gz 127.8 kB Without provenance Details for icplot-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for icplot 0.9.0
File Interpreter ABI Platform Actions
icplot-0.9.0-py3-none-any.whl Python 3 none any Details for icplot-0.9.0-py3-none-any.whl

Total release size: 313.5 kB

Release files / icplot-0.9.0.tar.gz

Download URL icplot-0.9.0.tar.gz
Size 127.8 kB
Tags Source
SHA-256 checksum
How to use checksums
18402dbc09c99b15879dc6ab2be6f0161b8ac5d94321411f7aed8b6fa6df1c3e
BLAKE2b-256 checksum
How to use checksums
59cc010d9471c852c0cb60338350a98f293e1228c3d6fcaeb6d6b8dfbcc3fa08
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.0-py3-none-any.whl

Download URL icplot-0.9.0-py3-none-any.whl
Size 185.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
96640628e5dfcd44b6c6a78ffe2dd96fd5dd94e3de0ee8403765c081f8d623d2
BLAKE2b-256 checksum
How to use checksums
d398c0ab9f90947a632a76550e17b7f1a8b4ed9ea1608075d75c2ca4718975ff
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.0

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.0 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