Skip to main content

icplot

icplot makes plots, 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 is now in icmesh.

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, and drawing scenes
imagemagick wand PDF to PNG
plot matplotlib plots and charts
video moviepy videos
all all of these everything

For example, pip install "icplot[cairo]". The cairo and imagemagick extras also need the system libraries. 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. It renders its own JSON formats for plots, trees, Gantt charts and scenes.

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

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.8.2
File Size Uploaded Provenance Actions
icplot-0.8.2.tar.gz 141.6 kB Without provenance Details for icplot-0.8.2.tar.gz

Built distribution (wheel)

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

Total release size: 342.7 kB

Release files / icplot-0.8.2.tar.gz

Download URL icplot-0.8.2.tar.gz
Size 141.6 kB
Tags Source
SHA-256 checksum
How to use checksums
37e9af01ec00ada44b6335c555031b80237ec04cbd7c5a6fb391f11cb02de91b
BLAKE2b-256 checksum
How to use checksums
3c746e06787657978498957a0a77afedaaa6720da1b235222bba46b233dbddf5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Release files / icplot-0.8.2-py3-none-any.whl

Download URL icplot-0.8.2-py3-none-any.whl
Size 201.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a138ed2b031d1df5d5038c4b4398bc47b93e7d232346c445de08828f37e2e437
BLAKE2b-256 checksum
How to use checksums
f0d236a045382c8830d6c23e3c5285309d4c6156623a38a7eee35b8bfb6c7a70
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Security for icplot 0.8.2

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