https://github.com/chalk-diagrams/chalk
A declarative drawing API in Python
https://github.com/chalk-diagrams/chalk
cairo declarative-language drawing edsl python
Last synced: 3 months ago
JSON representation
A declarative drawing API in Python
- Host: GitHub
- URL: https://github.com/chalk-diagrams/chalk
- Owner: chalk-diagrams
- License: mit
- Created: 2022-01-04T16:03:58.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-08-28T04:48:21.000Z (almost 2 years ago)
- Last Synced: 2025-03-04T22:37:24.516Z (over 1 year ago)
- Topics: cairo, declarative-language, drawing, edsl, python
- Language: Python
- Homepage:
- Size: 59 MB
- Stars: 294
- Watchers: 5
- Forks: 13
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Chalk is a declarative drawing library.
The API draws heavy inspiration from
Haskell's [diagrams](https://diagrams.github.io/),
Scala's [doodle](https://github.com/creativescala/doodle/) and
Jeremy Gibbons's lecture notes on [Functional Programming for Domain−Specific Languages](http://www.cs.ox.ac.uk/publications/publication7583-abstract.html).
The documentation is available at [https://chalk-diagrams.github.io](https://chalk-diagrams.github.io).
⚠️ The library is still very much work in progress and subject to change.
## Installation
The library is available on PyPI as `chalk-diagrams` and can be installed with `pip`:
```bash
pip install git+https://github.com/chalk-diagrams/chalk/
```
On Debian (or Colab) you will need to install Cairo for [PyCairo](https://pycairo.readthedocs.io)
```bash
sudo apt-get install libcairo2-dev
```
If you want to use the LaTeX extension, run:
```bash
pip install chalk-diagrams[latex]
```
For the LaTeX extension you might need to install `pdf2svg` and `texlive`;
on Debian these dependencies can be installed as follows:
```bash
sudo apt-get install pdf2svg texlive texlive-science texlive-latex-recommended texlive-latex-extra
```
**Installation with Conda**
You can install the library with **conda** from `conda-forge` channel.
```powershell
conda install -c conda-forge chalk-diagrams
```
## Overview
Below we provide a brief introduction of the main functionality of the library.
These examples are available in the `examples/intro.py` file.
We start by importing the [`colour`](https://github.com/vaab/colour) module and the `diagrams` functions:
```python
from colour import Color
from chalk import *
```
We also define some colors that will be shortly used:
```python
papaya = Color("#ff9700")
blue = Color("#005FDB")
```
We can easily create basic shapes (the functions `circle`, `square`, `triangle`) and style them with various attributes (the methods`fill_color`, `line_color`, `line_width`).
For example:
```python
d = circle(1).fill_color(papaya)
```
The diagram can be saved to an image using the `render` method:
```python
d.render("examples/output/intro-01.png", height=64)
```
We can glue together two diagrams using the combinators `atop` (or `+`), `beside` (or `|`), `above` (or `/`).
For example:
```python
circle(0.5).fill_color(papaya) | square(1).fill_color(blue)
```
which is equivalent to
```python
circle(0.5).fill_color(papaya).beside(square(1).fill_color(blue), unit_x)
```
This code produces the following image:
We also provide combinators for a list of diagrams:
`hcat` for horizontal composition, `vcat` for vertical composition.
For example:
```python
hcat(circle(0.1 * i) for i in range(1, 6)).fill_color(blue)
```
We can use Python functions to build more intricate diagrams:
```python
def sierpinski(n: int, size: int) -> Diagram:
if n <= 1:
return triangle(size)
else:
smaller = sierpinski(n - 1, size / 2)
return smaller.above((smaller | smaller).center_xy())
d = sierpinski(5, 4).fill_color(papaya)
```
### Gallery of examples
For more examples, please check the `examples` folder;
their output is illustrated below:
squares.py
logo.py
escher_square_limit.py
hilbert.py
koch.py
hex-variation.py
These scripts can be run as follows:
```bash
python examples/squares.py
```
## Authors
- [Dan Oneață](http://doneata.bitbucket.io/)
- [Alexander Rush](http://rush-nlp.com/)
Special thanks to:
- [Sugato Ray](https://github.com/sugatoray/), for his significant contributions and suggestions;
- [Ionuț G. Stan](http://igstan.ro/), for providing many useful insights and comments.
