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". It supports the basic grammar given by Perrig and Song, as well as a restricted subset of Tsoding's extended grammar from his C implementation.

Example

Try it out on The Example Deployment

Install

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 that can then be drawn to a canvas and from there turned into an image data object or saved etc.

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:

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

Public API

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.

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

const seeds = ["[email protected]", "[email protected]", "[email protected]"];
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 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.