README.md.in

# Generative Art

[![GitHub Actions status](https://github.com/Notgnoshi/generative/workflows/Tests/badge.svg)](https://github.com/Notgnoshi/generative/actions)
[![GitHub Actions status](https://github.com/Notgnoshi/generative/workflows/Pylint/badge.svg)](https://github.com/Notgnoshi/generative/actions)
[![GitHub Actions status](https://github.com/Notgnoshi/generative/workflows/Black/badge.svg)](https://github.com/Notgnoshi/generative/actions)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A polyglot collection of composable generative art tools, with a focus on 2D computational geometry.

# Table of contents

* [How to build](#how-to-build)
* [Philosophy](#philosophy)
* [Examples](#examples)
  * [Asemic writing](#asemic-writing)
  * [Random L-Systems](#random-l-systems)
* [The tools](#the-tools)
  * [Lindenmayer systems](#lindenmayer-systems)
    * [parse-production-rules.py](#parse-production-rulespy)
    * [random-production-rules.py](#random-production-rulespy)
    * [interpret-lstring.py](#interpret-lstringpy)
    * [random-lsystem.sh](#random-lsystemsh)
  * [Generation](#generation)
    * [point-cloud](#point-cloud)
    * [grid](#grid)
  * [Algorithms](#algorithms)
    * [bitwise](#bitwise)
    * [dla](#dla)
    * [streamline](#streamline)
    * [traverse](#traverse)
    * [urquhart](#urquhart)
  * [Transformations](#transformations)
    * [project.py](#projectpy)
    * [geom2graph](#geom2graph)
    * [smooth](#smooth)
    * [snap](#snap)
    * [transform](#transform)
  * [Utilities](#utilities)
    * [wkt2svg](#wkt2svg)
    * [render.py](#renderpy)
    * [bundle](#bundle)
    * [pack](#pack)

# How to build
This project contains a mix of Rust, C++, and Python. It's primarily Rust.

Install dependencies with
```sh
# Python dependencies
python3 -m venv --prompt generative .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
# C++ dependencies
sudo apt install build-essential cmake ninja-build
git submodule update --init --recursive
```

The Rust build has been configured to also perform the C++ CMake build, so all you need is
```sh
cargo build
```

If you don't want to build the C++ parts, you can do
```sh
cargo build --no-default-features
```
but note that this will disable building the [`geom2graph`](#geom2graph) tool.

You can run the Python tests with
```sh
source .venv/bin/activate
pytest
```
and the Rust tests with
```sh
cargo test
```
If the C++ tests have been enabled with `--all-features`, or `--features=cxx-tests`, they are copied
to `target/debug/cxx-tests`.

Throughout this entire document, it is assumed that each of the tool binaries has been added to your
PATH with
```sh
export PATH=$PWD/target/debug/:$PATH
```

# Philosophy

There is a [`generative`](./generative/) Rust/C++/Python library, but the user is expected to use
the [CLI tools](./tools/) instead. I'm enamored with the Unix philosophy, so each tool does its best
to produce/consume a standard textual interface.
* Each tool read/writes to/from `stdin`/`stdout`
* Logging is done to `stderr`
* Geometries are in [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)
  format, one geometry per line
* Graphs are in [TGF](https://en.wikipedia.org/wiki/Trivial_Graph_Format) format

# Examples
## Asemic writing
The following snippet generates random asemic writing glyphs
```sh
@ASEMIC_SETUP_SNIPPET@
```

To generate random glyphs, we'll:
1. Take a geometry graph
2. Perform random traverals of the graph
3. (optionally) Smooth each traversal into a curve
```sh
@ASEMIC_RANDOM_ROUNDED_SNIPPET@
```
![](@ASEMIC_RANDOM_ROUNDED@)
The `--untraversed` points could be replaced with diacritical marks.

We could also use the triangulation of a random point cloud
```sh
@ASEMIC_RANDOM_TRIANGULATED_SNIPPET@
```
![](@ASEMIC_RANDOM_TRIANGULATED@)

Neither of these approaches give a coherent sense of self-similarity that's necessary for linguistic
glyphs. If, instead of using a random point cloud, we use a regular grid, that dramatically changes
the sense of self-similarity.
```sh
@ASEMIC_GRID_ROUNDED_SNIPPET@
```
![](@ASEMIC_GRID_ROUNDED@)

We can also reduce the number of smoothing iterations to get beveled corners
```sh
@ASEMIC_GRID_BEVELED_SNIPPET@
```
![](@ASEMIC_GRID_BEVELED@)

We could also regular triangle grid, to get loopier results, with no vertical lines
```sh
@ASEMIC_GRID_TRIANGULATED_SNIPPET@
```
![](@ASEMIC_GRID_TRIANGULATED@)

Using a slanted grid makes _almost_ compelling cursive, if only the jarring horizontal lines were
removed.
```sh
@ASEMIC_GRID_JAGGED_SNIPPET@
```
![](@ASEMIC_GRID_JAGGED@)

## Random L-Systems
[examples/random-lsystems/saved.json](examples/random-lsystems/saved.json) contains parameters for
randomly (pre)generated Lindenmayer systems.
```sh
@RANDOM_LSYSTEMS_SNIPPET@
```
@RANDOM_LSYSTEM_IMAGES@

# The tools

## Lindenmayer Systems
### parse-production-rules.py
The `parse-production-rules.py` tool takes a set of production rules, and a starting axiom, and
interprets the rules on the axiom for some specified number of iterations
```sh
$ @PARSE_LSYSTEM_SNIPPET@
@PARSE_LSYSTEM_OUTPUT@
```

This tool supports context-free, stochastic, and context-sensitive grammars, with rules of the form
```
[left_context<] lhs [>right_context] [:probability] -> rhs
#ignore: tok1,tok2,tok3
```
The `[]` square brackets denote optional parts of the production rule.

### random-production-rules.py
The `random-production-rules.py` tool generates a random set of production rules in JSON form that
`parse-production-rules.py --config` knows how to read.
```sh
$ @RANDOM_LSYSTEM_RULES_SNIPPET@
@RANDOM_LSYSTEM_RULES_OUTPUT@
```

### interpret-lstring.py
These L-strings can then be interpreted with a 3D turtle. Each symbol controls the turtle's motion
through space.
```sh
$ @SIERPINKSI_TREE_SNIPPET@
@SIERPINKSI_TREE_OUTPUT@
```
Notice that the geometries are in 3D WKT. They can be rendered in an interactive 3D OpenGL viewer
([render.py](#renderpy)) or projected to 2D ([project.py](#projectpy) before being converted to SVG
with [wkt2svg](#wkt2svg).

```sh
@SIERPINSKI_TREE_SVG@
```
![](./examples/lsystems/sierpinski-tree.svg)

### random-lsystem.sh
`random-production-rules.py` generates a great many duds (See
[#83](https://github.com/Notgnoshi/generative/issues/83)), so `random-lsystem.sh` is an easy way of
generating and visualizing random L-Systems quickly.
```
$ ./tools/random-lsystem.sh
2024-03-03 08:57:05,580 - tools/random-production-rules.py - INFO - Using random seed 1063093925
{"seed": 1063093925, "rules": ["G -> [>[v[[|v-|<F>GG[v", "G -> v]<|", "F -> <^v"], "axiom": "G"}
2024-03-03 08:57:05,926 - tools/render.py - INFO - Loaded 64 segments and 0 points.
```

<!-- GitHub doesn't support inline .webm :( -->
<!-- ffmpeg -i examples/lsystems/random-lsystem.webm -pix_fmt rgb8 examples/lsystems/random-lsystem.gif -->
![random-lsystem.gif](./examples/lsystems/random-lsystem.gif)

## Generation
The generation-type tools generate input data for other tools to consume.

### point-cloud
`point-cloud` is a tool that generates random points in the unit circle or square.
```sh
$ @POINT_CLOUD_SNIPPET@
@POINT_CLOUD_OUTPUT@
```

### grid
The `grid` tool generates different kinds of grids:
* `triangle`
* `quad`
* `ragged`
* `hexagon`
and supports outputting the resulting grid in TGF graph format, WKT POINTs, or WKT LINESTRINGs.

```sh
$ @GRID_GRAPH_SNIPPET@
@GRID_GRAPH_OUTPUT@
```
```sh
$ @GRID_HEX_SNIPPET@
```
![](./examples/grid/hex.svg)

## Algorithms
### bitwise
The bitwise tool was inspired by <https://www.reddit.com/r/generative/comments/10hk4jg/big_renfest_crest_energy_bitwise_operations_svg>.
It takes an arbitrary expression on `(x, y)`, and visualizes the pattern resulting from connecting
adjacent non-zero cells with a line. The particulars of the pattern are highly influenced by
* Using modular arithmetic (and prime numbers) in the expression
* The order in width adjacent cells are searched (only the first hit is connected via a line)

A better number-theorist than me could probably extract some meaning from the resulting patterns.

```sh
$ @BITWISE_EXPR1@
```
![](./examples/bitwise/expr1.svg)

```sh
$ @BITWISE_EXPR2@
```
![](./examples/bitwise/expr2.svg)

Changing the search order doesn't change which cells are non-zero, just which cells are connected
via a line.
```sh
$ @BITWISE_EXPR3@
```
![](./examples/bitwise/expr3.svg)

### dla
The `dla` tool uses [Diffusion Limited
Aggregation](https://en.wikipedia.org/wiki/Diffusion-limited_aggregation) to generate fractal
growths like snowflakes, lightning, and river networks (in mountainous terrain anyways)

```sh
$ @DLA_ORGANIC_SNIPPET@
```
![](examples/dla/organic.svg)

There are a huge number of tunable parameters to play with, and it's quite hard to get an intuitive
sense for the impact of each.

### streamline
The `streamline` tool can be used to trace geometry streamlines in a vector field.
You can define your own vector field as a function of `(x, y)`, or a random Perlin noise field will
be used.

```sh
$ @STREAMLINE_SNIPPET1@
```
![](examples/streamline/field1.svg)

```sh
$ @STREAMLINE_SNIPPET2@
```
![](examples/streamline/field2.svg)

### traverse
The `traverse` tool performs random walks on the given graph.
```sh
$ @TRAVERSE_SNIPPET@
```
![](examples/traverse/hex-walk.svg)

### triangulate
The `triangulate` tool finds the Delaunay triangulation of the given geometries. It can triangulate
individual geometries, or relax all geometries into a point cloud, and triangulate the point cloud.

```sh
$ @TRIANGULATE_SNIPPET@
```
![](examples/urquhart/triangulation.svg)

### urquhart
The [Urquhart Graph](https://en.wikipedia.org/wiki/Urquhart_graph) is a computationally easy(ish)
approximation to the [Relative Neighborhood
Graph](https://en.wikipedia.org/wiki/Relative_neighborhood_graph). It's formed from the Delaunay
triangulation.

```sh
@URQUHART_SNIPPET@
```
![](examples/urquhart/urquhart.svg)

## Transformations
### project.py
The `project.py` tool can be used to project 3D geometries to 2D. It supports several projection
types, I recommend PCA or isometric.

```sh
$ @PROJECT_SNIPPET@
```
![](examples/project/isometric.svg)

### transform
The `transform` tool can be used to apply affine transformations to the given geometries; rotation,
scale, offset, and skew (applied in that order). Note that `wkt2svg` can also scale geometries,
because it's very common for the generative algorithms to work on a sub-pixel scale.

```sh
$ @TRANSFORM_SNIPPET@
```
![](examples/transform/square.svg)

### geom2graph
The `geom2graph` tool converts back and forth between WKT geometries, and their TGF connection-graph
representation. It can be useful to de-duplicate vertices and overlapping segments, find all-pairs
intersections, and convert to a graph representation of a set of geometries useful for other kinds
of algorithms (See [Asemic Writing](#asemic-writing) above).

```sh
@GEOM2GRAPH_SNIPPET@
```
this give a TGF graph
```
@GEOM2GRAPH_OUTPUT@
```
that we can observe has the intersection points added
```sh
@GEOM2GRAPH_SNIPPET2@
```
![](examples/geom2graph/offset-squares.svg)

> **NOTE:** Converting the graph back into a set of geometries is sub-optimal; it returns a set of
> polygons, and returns anything else as a set of "dangles" each of which is a single line segment,
> even if the original geometry was all one big long connected linestring.

### smooth
The `smooth` tool smooths geometries.
```sh
@SMOOTH_SNIPPET1@
```
![](examples/smooth/beveled.svg)

```sh
@SMOOTH_SNIPPET2@
```
![](examples/smooth/rounded.svg)

### snap
The `snap` tool snaps geometry vertices together with some tolerance; either to a regular grid, or
to the closest vertex of a nearby geometry.

To demonstrate, start with a couple of squares offset from each other by `0.1`
```sh
@SNAP_CREATE_GRID@
```
![](examples/snap/grid.svg)

You can snap the vertices of the geometries to the closest nearby points
```sh
@SNAP_CLOSEST@
```
![](examples/snap/snap-closest.svg)

Or you can snap the vertices of the geometries to a regular grid centered at `(0, 0)` with spacing
given by the `--tolerance` flag.
```sh
@SNAP_GRID@
```
![](examples/snap/snap-grid.svg)

The `snap` tool can snap both geometries and geometry graphs. It is cheaper to snap graphs, because
the first stage of snapping geometries is to build the graph representation.

> **Note:** The `snap` tool is sensitive to the ordering of geometries, and to the ordering of the
> vertices in each geometry.

## Utilities
### bundle
The `bundle` tool is a simple tool that bundles multiple geometries together into a single
`GEOMETRYCOLLECTION`. This is useful when combined with the [`pack`](#pack) tool.
```sh
@BUNDLE_SNIPPET@
```
```
@BUNDLE_OUTPUT@
```

### pack
The `pack` tool is a rectangle packing tool. For each input geometry (a `GEOMETRYCOLLECTION` is
considered a single geometry), the tool will determine the axis-aligned bounding box, and attempt to
pack each geometry into a rectangular region of a fixed size.


```sh
@PACK_SNIPPET@
```
![](examples/pack/squares.svg)

> **Note:** The rectangular region should be big enough that each of the geometries fits, but small
> enough that it generates an appealing packing.

> **Note:** The packing algorithm uses integer coordinates, so you may need to scale up your
> geometries to enable more control.

### render.py
The `render.py` tool can be used to interactively render 2D and 3D WKT geometries in an OpenGL
visualizer.

```sh
$ tools/parse-production-rules.py --config examples/maya-tree-2.json |
    tools/interpret-lstring.py --angle 30 |
    tools/render.py --axis
```
![](examples/maya-tree-2.png)

### wkt2svg
The `wkt2svg` tool can be used to render 2D WKT geometries to an SVG image.

> **Note:** `wkt2svg` only accepts 2D geometries. If you have 3D geometries, you'll need to use
> [`project.py`](#projectpy) to project the 3D geometries down to 2D.

Additionally, `wkt2svg` supports styling through its CLI arguments (to override the global default)
or by the use of commands that can be interleaved with the WKT being processed.
* `POINTRADIUS(1.0)` - Can be used to set the radius of WKT `POINT`s
* `STROKE(black)` - Can be used to set the color of geometries
* `STROKEWIDTH(2.0)` - Can be used to set the width lines
* `FILL(red)` - Can be used to fill in `POLYGON`s and `POINT`s (if the `POINTRADIUS` is large enough
  that there's an interior to fill).
* `STROKEDASHARRAY(...)` - Can be used to draw dotted lines; See [the MDN
  docs](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray) for help.

```sh
@WKT2SVG_SNIPPET@
```
![](examples/wkt2svg/styles.svg)