inhumument-lib

The p5.js rendering layer for humument — Phillips-style erasure-poetry drawing over W. H. Mallock's A Human Document (1892), the book Tom Phillips treated to make A Humument.

humument is renderer-agnostic: it loads a page's words, OCR boxes, whitespace geometry, and a navigation graph, and returns every drawing primitive as a plain {x, y} point array. inhumument-lib re-exports all of it and adds back the p5 sugar — an H.draw.* namespace and a H.page.image slot — so p5 sketches (like those in the InHumument editor) can draw balloons, rivers, and word-stamps in one call.

If you're rendering with Canvas2D / SVG / WebGL, use humument directly. If you're drawing with p5.js, use this.

Install

npm install inhumument-lib p5

p5 is a peer dependency. The full 367-page dataset (words + page scans) is published on npm and fetched from a CDN by default, so there is nothing to host.

No build step? CDN

Load the IIFE bundle — it exposes an InhumumentLib global (it bundles humument in, so it's self-contained):

<script src="https://cdn.jsdelivr.net/npm/p5@1/lib/p5.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.global.js"></script>
<script>
  const { Humument } = InhumumentLib;
  // ... same API as the ESM import
</script>

This is the way to use it on editor.p5js.org or OpenProcessing.

Usage

Humument.load is async, and p5 1.x does not await async preload/setup. Kick off the load in setup() and gate draw() until it resolves:

import { Humument } from 'inhumument-lib'; // CDN: const { Humument } = InhumumentLib;

let H = null;

function setup() {
  createCanvas(100, 100); // resized once the page loads
  noLoop();
  Humument.load({ page: 33 }).then((h) => {
    H = h;
    resizeCanvas(H.page.width, H.page.height);
    // The lib never loads the image itself — assign it, then draw:
    H.page.image = loadImage(H.page.imageUrl, () => redraw());
  });
}

function draw() {
  if (!H || !H.page.image) return;
  image(H.page.image, 0, 0);

  const phrases = H.selectChunks({ nSeeds: 4, minLineDist: 3, seed: 42 });
  fill(255); stroke(20);
  for (const ph of phrases) H.draw.balloon(ph, { wobble: 0.15 });
}

Humument.load({ page: 33 }) needs no other options — data and images resolve from the npm CDN. Pass dataBase/imageBase to self-host.

On p5 2.x setup may be async, so you can simply await Humument.load(...) inside it.

The p5 layer

Everything below is added on top of humument's API. The helpers run in p5 global mode (pass nothing) or instance mode (pass the p5 instance as the last argument).

• H.draw.blob(source, opts?, p?) — the true A Humument balloon: word groups (Word[][]) or a hand-built BlobSpec rendered as ONE text-hugging silhouette, phrases fused by tapered necks that flare where they attach. Set fill + stroke first — one shape means one ink rim. Interior pockets stay filled like Phillips's cuts (pass holes: true to punch them). opts is BlobOptions (pad, blend, wobble, seed, …) plus spec (BlobSpecOptions for the auto-necks).
• H.draw.banner(words, opts?, p?) — angular pennant/banner strip (ends: 'square' | 'point' | 'swallowtail', skew, notch, …) — p15's paper-ribbon dialogue shapes. opts is BannerOptions.
• H.draw.balloon(words, opts?, p?) — simple wobbly ellipse enclosing the words (the pre-0.2 look). A cheap analytic loop — still the right choice for animated / per-frame drawing where blob's field march would be too slow. opts is BalloonOptions (pad, wobble, samples, seed, …).
• H.draw.river(segment, opts?, p?) — wavy ribbon along a river segment from H.river.between(a, b). opts is ChannelOptions.
• H.draw.word(word, p?) — re-stamp one word's original pixels crisply (needs H.page.image).
• H.draw.image(p?) — blit the full page scan (needs H.page.image).
• H.page.image — a writable p5.Image | null slot; the lib never fills it, the host does after loadImage(H.page.imageUrl).

The same functions are also exported standalone: drawBlob(H, source, opts?, p?), drawBanner(H, words, opts?, p?), drawBalloon(H, words, opts?, p?), drawRiver(H, seg, opts?, p?), drawWord(pageImage, word, p?), drawImage(pageImage, p?).

Everything else

All of humument's API is re-exported unchanged — H.words / H.lines, H.selectChunks(), H.river.between() / H.river.flow(), the pure H.geom.balloon() / H.geom.channel() point-array primitives, H.bboxOf(), H.noise() / H.random(), and the Word / Gutter / BalloonOptions types. See the humument docs.

License

MIT