perrig-song-randomart/README.md

A browser implementation of the randomart generator proposed by Perrig and Song's 1999 paper 'Hash Visualization: a New Technique to improve Real-World Security'.

# Perrig-Song-Randomart

This package provides a (browser side) js module to generate randomart images
based on Perrig and Song's 1999 paper ["Hash Visualization: a New Technique to
improve Real-World Security"](https://people.eecs.berkeley.edu/~dawnsong/papers/randomart.pdf).
It supports the basic grammar given by Perrig and Song, as well as a restricted
subset of [Tsoding's](https://github.com/tsoding) 
[extended grammar](https://github.com/tsoding/randomart/blob/main/grammar.bnf) 
from his [C implementation](https://github.com/tsoding/randomart). 

## Example
Try it out on [The Example Deployment](https://james-oswald.github.io/Perrig-Song-Randomart/)

## Install

```sh
npm install perrig-song-randomart
```

This package is published as an ES module and is intended for browser runtimes
with `OffscreenCanvas`, `ImageBitmap`, and WebGL2 support.

## Use

The core function of the library is a single function `randomart`, which
given an image size, string seed, and optional rendering parameters will generate an [ImageBitmap](https://developer.mozilla.org/en-US/docs/Web/API/ImageBitmap) that can then be drawn to a canvas and from there turned into an image data object or saved etc.

```js
import { randomart } from "perrig-song-randomart";

const canvas = document.getElementById('canvas');
const ctx = canvas.getContext('2d');

const image = randomart({
  width: canvas.width,
  height: canvas.height,
  seed: "my seed",
  grammar: "tsoding",
  depth: 15,
  scale: 2
});

ctx.drawImage(image, 0, 0, canvas.width, canvas.height);
image.close();
```

The older positional call style is still supported:

```js
const image = randomart(canvas.width, canvas.height, "my seed", "tsoding", 15, 2);
```

### Public API

```ts
import {
  createRandomartExpression,
  createRandomartFragmentShader,
  grammarNames,
  randomart,
  randomarts,
  type GrammarName,
  type RandomartOptions,
  type RandomartsOptions,
  type RandomartShaderOptions
} from "perrig-song-randomart";
```

- `randomart(options)` renders an `ImageBitmap`.
- `randomarts(options)` renders one `ImageBitmap` for each seed string.
- `createRandomartExpression(options)` returns the generated GLSL expression.
- `createRandomartFragmentShader(options)` returns the full fragment shader source.
- `grammarNames` lists the supported grammar names.

### Batch generation

Use `randomarts` when a UI needs to render many seeded images from a list of
strings. It returns a promise for `ImageBitmap[]` in the same order as the input
`seeds`.

```js
import { randomarts } from "perrig-song-randomart";

const seeds = ["alice@example.com", "bob@example.com", "carol@example.com"];
const images = await randomarts({
  width: 256,
  height: 256,
  seeds,
  grammar: "tsoding",
  depth: 12,
  scale: 2,
  concurrency: 4
});

images.forEach((image, index) => {
  const canvas = document.querySelectorAll("canvas")[index];
  const ctx = canvas.getContext("2d");
  ctx.drawImage(image, 0, 0, canvas.width, canvas.height);
  image.close();
});
```

### Optional Parameters
* `grammar`: The grammar to use for generating the randomart, either `"perrig"`, `"tsoding"`, or `"oswald"`. Defaults to `"tsoding"`.
  * `"perrig"` uses the simple example grammar from the original paper. In general, it produces the "least interesting" images.
  * `"tsoding"` uses a limited subset of [tsoding's extended grammar](https://github.com/tsoding/randomart/blob/main/grammar.bnf)
     it generates fairly interesting images with occasional noise.
  * `"oswald"` extends the tsoding grammar with some additional trig functions, it generates the most complex images, but is often noisy.
* `depth`: The "complexity" of the randomart, default to 15. Governs the size of the random expression tree generated, bigger expressions mean more complex and overlapping motifs in the resulting image.
WARNING: as this governs the depth of a tree, is an exponential parameter, higher values will cause potentially very long
generation times, and have a know issue corrupting WebGL on Firefox, requiring a browser restart. 20 is the recommended maximum to avoid lag. 
* `scale`: How "zoomed out" the randomart is, defaults to 2.0. Some features are not visible at the base zoom, but in general interesting features
tend to clump up in the middle. Zooming out too far usually results in boring repeated patterns.
* `concurrency`: Only used by `randomarts`. Controls how many scheduled render
tasks are active at once. Defaults to the number of seeds.