Metadata-Version: 2.4
Name: icplot
Version: 0.9.1
Summary: Utilities for generating plots and graphics for technical reports.
Author: Irish Centre for High End Computing
License: MIT
Project-URL: Repository, https://git.ichec.ie/platform-engineering/modules/ichec-plot
Project-URL: Homepage, https://git.ichec.ie/platform-engineering/modules/ichec-plot
Keywords: Publishing,Technical Reports,Graphics
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: iccore==0.2.6
Requires-Dist: pydantic
Requires-Dist: PyYAML
Requires-Dist: graphviz
Requires-Dist: Jinja2
Requires-Dist: fonttools[woff]
Provides-Extra: cairo
Requires-Dist: CairoSVG; extra == "cairo"
Provides-Extra: preview
Requires-Dist: playwright; extra == "preview"
Provides-Extra: all
Requires-Dist: CairoSVG; extra == "all"
Dynamic: license-file

# icplot

`icplot` makes diagrams and images for technical documents at
[ICHEC](https://www.ichec.ie). 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

```shell
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:

```shell
brew install imagemagick cairo
```

## Convert an image

```shell
icplot convert --source my_image.svg --target my_image.png
```

`icplot` converts SVG to PNG or PDF, and PDF to PNG.

## Render a diagram

```shell
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:

```shell
icplot render .
```

It reads `render.yaml` from the current directory, or the file you give with
`--config`. For example:

```yaml
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](templates/tikz/README.md).

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

```python
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](https://lucide.dev) and [Simple Icons](https://simpleicons.org). 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:

```shell
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`.
