Metadata-Version: 2.4
Name: icplot
Version: 0.7.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/documentation/ichec-plot
Project-URL: Homepage, https://git.ichec.ie/platform-engineering/modules/documentation/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: ichec_platform_core==0.1.4
Requires-Dist: graphviz
Requires-Dist: Jinja2
Provides-Extra: cairo
Requires-Dist: CairoSVG; extra == "cairo"
Provides-Extra: imagemagick
Requires-Dist: wand; extra == "imagemagick"
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Provides-Extra: video
Requires-Dist: moviepy; extra == "video"
Provides-Extra: all
Requires-Dist: CairoSVG; extra == "all"
Requires-Dist: wand; extra == "all"
Requires-Dist: matplotlib; extra == "all"
Requires-Dist: moviepy; extra == "all"
Dynamic: license-file

# icplot

`icplot` makes plots, 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. The 3D mesh
and OpenFOAM code is now in
[icmesh](https://git.ichec.ie/platform-engineering/modules/ichec-mesh).

## 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, 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:

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

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

## Licence

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